IEFUSI — Step Initiation Exit

Topics for This Exit Appear as Follows:

Comparing IEFUSI with IEALIMIT when Limiting Region Size
Defining the Exit in SMFPRMxx
Controlling the Exit Routine Through the Dynamic Exits Facility
Exit Routine Environment
Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
- Registers at Entry
- Parameter Descriptions
Return Specifications
- Registers at Exit
Examples
- Example of Using IEFUSI to Limit Region Size
- Examples of Storage Allocations Based on Values Set by IEFUSI

IEFUSI receives control before each job step is started (prior to allocation). A return code from this exit indicates whether the job step is to be started or the job should be cancelled.

You can use IEFUSI to:

Validate job step accounting information.
Write to a user data set.
For long-running jobs, create and write a user step-initiation SMF record in case of system failure.
Set the region size and region limit for all programs that run under this job step. For more information about controlling region size and region limit, see z/OS MVS Initialization and Tuning Guide.
Note: For programs with the NOHONORIEFUSIREGION Program Property Table (PPT) attribute specified, region and MEMLIMIT values and limits set by the IEFUSI exit are not honored. See the z/OS MVS Initialization and Tuning Reference and the z/OS MVS Initialization and Tuning Guide for more information about this PPT attribute and how it affects the IEFUSI-altered region and MEMLIIT settings.
Set limits on the use of data spaces and hiperspaces created by application programs with storage key 8 - F.
Limit the number of pages that can be shared at one time through the use of the IARVSERV macro.
Set the default size of data spaces and hiperspaces.
Limit the use of the 16 exabyte address space above two gigabytes.
Reduce the values of LDAELIM, LDAEVVRG, LDALIMIT, and LDAVVRG. Initially, these fields contain the maximum amount of storage available to the user. Specifically:
```
LDAELIM = LDAEVVRG = 32Mb
```
and
```
LDALIMIT = LDAVVRG = LDASIZA − 64K
```
Note: For programs with the NOHONORIEFUSIREGION Program Property Table (PPT) attribute specified, these region values are not changed by the IEFUSI exit. See the z/OS MVS Initialization and Tuning Reference and the z/OS MVS Initialization and Tuning Guide for more information about this PPT setting and how it affects the IEFUSI-altered region and MEMLIMIT values and limits.

Start of change Use of the IEFUSI exit may only reduce the amount of storage requested, not increase it. End of change

If an installation uses major and minor account numbers with several fields, IEFUSI is easier to use than IEFUJV for account number processing because the accounting fields are placed in a formatted list. See Table 2 for the format of the accounting information.

Limiting Region Size: There are several factors to consider in using IEFUSI to limit region size:

Consider using the SMFLIMxx parmlib member, which provides the ability to set the REGION and reserve storage for system key storage obtains without writing an IEALIMIT or IEFUSI exit.
If IEFUSI is not available, or IEFUSI is not used to set up the region size, the system will use IEALIMIT.
To use IEFUSI for region size control, you must tell the system to bypass the IEALIMIT exit by setting a flag in the IEFUSI parameter list.
When writing the installation exit, the region size should be made less than the region limit. This is to protect against programs that issue variable requests for storage with very large upper bounds and then do not immediately free part of that space, or free such a small amount that a subsequent request for storage (possibly issued by a system service) causes the job to fail. See z/OS MVS Initialization and Tuning Guide for a discussion on the relationship between region size and region limit and how the system uses these values.
For programs with the NOHONORIEFUSIREGION Program Property Table (PPT) attribute specified, IEFUSI-altered region and MEMLIMIT values and limits are not honored. The NOHONORIEFUSIREGION PPT attribute can be specified in the SCHEDxx member of SYS1.PARMLIB, or as an IBM® supplied PPT default. This PPT attribute is used to bypass IEFUSI region controls for programs that require more region space to successfully execute. See the z/OS MVS Initialization and Tuning Reference and the z/OS MVS Initialization and Tuning Guide for more information on this PPT setting and how it affects the IEFUSI-altered region and MEMLIMIT values and limits.

Although you can use the IEFUSI exit to modify the region size of an address space, IBM strongly recommends that you do not alter the region size of address spaces in the OMVS subsystem category.

Note: A default IEFUSI module is included in SYS1.LPALIB. This default module does not do any processing, but just returns to the caller. It will be picked up first by the system at IPL time, unless you code your exit specifically in the PROGxx parmlib member using the EXIT ADD statement.

Comparing IEFUSI with IEALIMIT when Limiting Region Size

Historically, users could limit program storage below 16 megabytes in virtual storage by using IEALIMIT. IEALIMIT can still be used to limit program storage in the nonextended region; however, IEFUSI is the preferred exit routine, and has the following advantages over IEALIMIT:

IEFUSI is a separate load module in the link pack area. You must supply a routine named IEFUSI and linkedit it into LPALIB or an LPALSTxx member of SYS1.PARMLIB. IEALIMIT must reside in the nucleus, so you must linkedit the nucleus every time you replace IEALIMIT with a new version. You must linkedit your routine again into the nucleus each time you IPL a different version of the nucleus, as all versions of the nucleus initially contain the IBM-supplied IEALIMIT routine.
IEFUSI users can obtain information required to set a region size and region limit. IEALIMIT scans system control blocks to gather that information; thus IEFUSI is easier to write and less susceptible to system changes.
IEALIMIT requires that the local lock be held and therefore cannot issue SVCs. IEFUSI has neither of these restrictions.
IEFUSI can control the region size and region limit of both the area above and the area below 16 megabytes in virtual storage. IEALIMIT can set values for only the area below 16 megabytes, leaving values for the extended private area above 16 megabytes to be determined by the system.
Previously, if the region requested by a job was greater than 16 megabytes, MVS™ allowed a minimum of 32 megabytes in the extended region; IEFUSI can override this 32-megabyte minimum value.

Defining the Exit in SMFPRMxx

In the SMF parmlib member (SMFPRMxx), specify IEFUSI on the EXITS option of either the SYS or SUBSYS parameters, depending on the scope of work (system-wide or subsystem-wide) the exit is to affect.

If you use the SUBSYS option, the system invokes the IEFUSI routine only for work running under the subsystems you specify on SUBSYS. If you use the SYS option, the system invokes the IEFUSI routine for work running under any SMF-defined subsystem, such as JES2, JES3, STC, ASCH, OMVS, or TSO.

For more information about coding the EXITS option, see the description of SMFPRMxx in z/OS MVS Initialization and Tuning Reference.

Controlling the Exit Routine Through the Dynamic Exits Facility

IBM has defined the IEFUSI installation exit to the dynamic exits facility. You can refer to the exit by the name SYS.IEFUSI or SYSyyy.IEFUSI. See the description of the SMFPRMxx parmlib member in z/OS MVS Initialization and Tuning Reference for an explanation of the naming conventions for SMF exit routines. You can use the EXIT statement of the PROGxx parmlib member, the SETPROG EXIT operator command, or the CSVDYNEX macro to control this exit and its routines.

To define IEFUSI to the dynamic exits facility, you must specify the exit in both PROGxx and SMFPRMxx. The system does not call the exit if it is defined in PROGxx only. If you do not plan to use the dynamic exits facility for IEFUSI, you need only define this exit in SMFPRMxx.

The exit should reside in LPA, the LNKLST concatenation, or the nucleus. Do not use the DSNAME keyword when defining the exit in PROGxx, as the system will not be able to load the exit when restarting SMF.

If you do not associate any exit routines with exit IEFUSI in PROGxx, the system defaults to using the exit routine name that matches the exit name (IEFUSI).

If you associate exit routines with IEFUSI in PROGxx, the system does not use the default exit routine. If you need the default exit routine, add it explicitly to PROGxx.

You can use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX REQUEST=ADD macro or the ABENDNUM parameter of the SETPROG EXIT operator command to limit the number of times the exit routine abnormally ends before it becomes inactive. An abend is counted when both of the following conditions exist:

The exit routine does not provide recovery, or the exit routine does provide recovery but percolates the error
The system allows a retry; that is, the recovery routine is entered with bit SDWACLUP off.

By default, the system does not disable the exit routine.

Exit Routine Environment

IEFUSI receives control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0.
In AMODE 31.

Exit Recovery

IBM strongly recommends that you set up an ESTAEX recovery routine to handle errors that might occur during the execution of IEFUSI.

An ESTAE-type recovery routine is set up by the module that calls IEFUSI; the recovery routine, if it gets control, will allow the job to continue processing if the exit routine abnormally ends.

Whether or not the exit routine continues to be invoked depends on the abend processing of the dynamic exits facility.

Exit Routine Processing

IEFUSI exit routines receive control before the initiator checks to determine whether the job step will actually execute. That is, IEFUSI receives control before the system performs testing for COND and IF/THEN/ELSE/ENDIF, including ABENDs. This means that IEFUSI will always be called, regardless of whether the step will execute.

Using IEFUSI to Limit Data Space and Hiperspace Use: Your IEFUSI exit routine can communicate the values you want to use to limit data space and hiperspace use for programs with storage key 8 - F. Code your routine to place these values in word 7 of the SMF parameter list before returning control. (See the parameter descriptions in Entry Specifications for a description of word 7.)

Your IEFUSI exit routine can include region processing for the private area, both less than and greater than 16 megabytes. The exit checks the region requested on the JOB or EXEC JCL statement, and determines whether it is acceptable. You can then communicate the values you want to use to limit access to private area storage. Your IEFUSI routine places these values in the appropriate fullwords in the SMF parameter list before returning control to the initiator.

For more information on data spaces and hiperspaces, see z/OS MVS Programming: Extended Addressability Guide.

Programming Considerations

When coding an IEFUSI exit routine, observe the following conventions:

When issuing a WTOR macro, specify LONG=YES on the WAIT macro. Do not use a WTO with a routing code of 11 to send a message to the JESYSMSG data set for started tasks or TSO users.
Do not use subpool 240 or 250 when obtaining storage for this exit. Using these subpools may result in errors when the exit receives control for address spaces that are created with the KEEPRGN attribute.
To provide a consistent environment for accessing and allocating data sets across calls to SMF exits for the duration of a job or task, IEFUSI receives control with the initiator's JSCB active.
IEFUSI must be reenterable and refreshable because PLPA pages are stolen. That is, they can be paged in but not paged out, and subsequent page-in operations will overlay any code changes.
IEFUSI can perform dynamic allocations and write to installation-defined data sets. In foreground jobs, data sets are allocated dynamically. However, for background jobs, you can either allocate data sets dynamically or you can pre-define (pre-allocate) a data set with a DD statement in the initiator-cataloged procedure.
IEFUSI cannot access ISAM data sets.

Additional Considerations for z/OS UNIX Applications: When running z/OS UNIX applications you need to consider that fork and spawn are issued to create new address spaces. The default processing on fork and spawn is for the z/OS UNIX kernel to propagate the region size from the parent to the child. Because the region size in the parent process has already passed through IEFUSI and has an approved region size, IBM recommends that you bypass normal IEFUSI processing when the subsystem (Word 8) is OMVS.

At the time of IEFUSI processing, the kernel has not yet propagated the parent's region size to the child, so IEFUSI has nothing to work with. If IEFUSI modifies the region size of the child process, the kernel will honor that region size and not propagate the region size from parent to child. This can result in failure of a fork if the region size is insufficient in the child to capture the parent's storage.

Entry Specifications

The system passes a list of parameter addresses to IEFUSI.

Registers at entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Address of the parameter list
2 - 12: Not applicable
13: Register save area
14: Return address
15: Entry point address of IEFUSI

Parameter descriptions: Register 1 points to the following list of addresses:

Word 1

The address of the common exit parameter area. (See Table 1.)

Word 2

The address of an 8-byte area containing the job step name (in EBCDIC) from the EXEC statement. This area is aligned left and padded with blanks if necessary.

For a forked/spawned address space, this will be STEP1 when the address space is first started and will be *OMVSEX, after an exec().

Note: It is possible that some address spaces will be associated with IEESYSAS. For that case, JMRJOB will contain IEESYSAS.

Word 3

The address of an 8-byte area containing the program name (in EBCDIC) from the EXEC statement. This area is aligned left and padded with blanks if necessary. If you refer back, the area contains pgm=*.DD. For a forked/spawned address space,this will be BPXPRFC; after an exec() call, it will be BPXPRECP.

Word 4

The address of an area containing the accounting information from the EXEC statement. (See Accounting Information.)

Word 5

The address of an 8-word area that IEFUSI can use to communicate with MVS. This area primarily consists of region size and region limit information. The information consists of the following sub-words: End of change

Sub-word 1

Flag word to specify that IEFUSI, rather than IEALIMIT, is to provide the information on how to control access to private area storage.

The flag word is initialized to zero. Your routine sets the flag bits to mean the following:

Bit	Value	Meaning
0	0	IEALIMIT is supplying information on how to control access to private area storage.
0	1	IEFUSI is supplying information on how to control access to private area storage.
1	0	Check if the requested below-16-megabyte-region size is available. If the size is not available an 822 abend occurs.
1	1	Do not check if the requested below-16-megabyte-region size is available. If the size is not available, a less-predictable abend than 822 might occur.
2	0	Do not check if the requested above-16-megabyte-region size is available. If the size is not available, a less-predictable abend than 822 might occur.
2	1	Check if the requested above-16-megabyte-region size is available. If the size is not available, an 822 abend occurs.
3	0	REGIONX keyword was not used. Note that this bit cannot be altered.
3	1	REGIONX keyword was used with sub-word 7 holding the REGIONX first parameter (non-extended region size requested) and sub-word 8 holding the REGIONX second parameter (extended region size requested).
4	0	The SMFLIMxx parmlib settings, if applicable, can override the exit's output.
4	1	The SMFLIMxx parmlib settings must not override the exit's settings. This applies to all SMFLIMxx settings, not just region size and region limit information.
5 - 31		Reserved.

Note: The settings for bits 1 and 2 have opposite meanings. You must turn on bit 2 when the amount of contiguous free space requested is critical for the step to be executed.

Sub-word 2

Region size request on the JOB or EXEC JCL statement. For a forked address space, this shows as 54M.

Sub-word 3

Region limit below 16 megabytes.

Sub-word 4

Region size below 16 megabytes.

Sub-word 5

Region limit above 16 megabytes.

Sub-word 6

Region size above 16 megabytes.

Sub-word 7

The REGIONX first parameter (non-extended region size requested).

Sub-word 8

REGIONX second parameter (extended region size requested).

On every entry to IEFUSI, sub-words 3 through 6 in the region size information list are set to X'FFFFFFFF'.

There is no lower bound on the region limit and region size that IEFUSI can request. If the JCL specifies REGION=0 with no MEMLIMIT coded, and the IEFUSI exit changes the REGION size but does not set the MEMLIMIT, the MEMLIMIT value is set to the REGION size above 16MB.

Word 6

The address of a word containing a flag indicating a V=R job.

Word 7

The address of a 4-word area containing IBM-supplied default values for data spaces, hiperspaces, and data sharing (through the IARVSERV macro). These defaults apply only for programs running in problem state with user keys. The number of sharing pages, address spaces, data spaces and hiperspaces can be limited only for jobs running in user keys and in problem state. Jobs running in system key (0 - 7) or in supervisor state may use unlimited sharing pages, data spaces and hiperspaces. The words are defined as follows:

Sub-word

Contents

1

Default data space and hiperspace size. It is specified in blocks of 4K bytes and must be in the range of 1 - X'00080000'. The IBM-supplied default is 956K (X'000000EF' × 4K).

2

Maximum combined size for all user key data spaces and hiperspaces that are created by application programs owned within an address space (in megabytes). The IBM-supplied default and the maximum that can be specified is (2²⁴ − 1) megabytes.

3

Maximum number of user-key data spaces and hiperspaces created by application programs that can exist at any given time for an address space. The IBM-supplied default and the maximum number that can be specified is (2³² − 1).

4

Maximum number of source and target shared pages that can be used at one time by problem state callers using the IARVSERV SHARE services. The IBM-supplied default is 32 (which allows at most 16 pages to be shared with 16 other pages; the number of pages include source plus target). The maximum you can specify is (2³¹ − 1).

Note:

If you change the default, make sure you balance this with other uses of real storage. You can calculate the number of real 4K frames that are required, as follows:

(number of share groups + number of shared views + 252) ÷ 127

Ignore any remainder after dividing by 127. End of change

Word 8

The address of a 4-character area that contains the name of the subsystem for the job being processed. Examples:

ASCH, JES2, or JES3 — indicates the name of the subsystem that selected the job.
OMVS — indicates a forked or spawned address space
STC — indicates a started task
TSO — indicates a time sharing option task
The jobname — used if it is four or fewer characters and none of the others apply

Word 9

The address of an area consisting of three 64-bit fields used to specify MVS MEMLIMIT value. The MEMLIMIT information consists of:

Sub-parm 1

A 64-bit flag word. The first 8 bits indicate whether the source of the MEMLIMIT is from JCL, or the SMF-supplied system default. The remaining 56 bits are not used.

Your routine can set the flag bits to the following possible values:

Hex value of first 8 bits	Meaning
01 ('00000001'b)	MEMLIMIT is from SMF
02 ('00000010'b)	MEMLIMIT is from JCL
03 ('00000011'b)	MEMLIMIT was set to NOLIMIT because JCL specified REGION=0
FF ('11111111'b)	MEMLIMIT is from SMF (indicative of internal processing errors)

Note: When you initialize a child address space in the UNIX System Services environment, the source MEMLIMIT value can be set using definitions other than those provided through the IEFUSI exit. For additional information, see

Sub-parm 2

The 64-bit MEMLIMIT originally requested by the source that is specified in the flagword. This value is specified in megabytes.

Sub-parm 3

The 64-bit MEMLIMIT requested by the IEFUSI exit. The initial value is X'FFFFFFFFFFFFFFFF' to indicate that no value was set by the exit. This value is specified in megabytes.

Notes:

A MEMLIMIT of NOLIMIT is equivalent to X'00000FFFFFFFF000'.
Critical address spaces are exempt from the IEFUSI imposed limit on above the bar virtual memory, so as not to affect system availability.

For a complete description of MEMLIMIT, and the ways to define it, see z/OS MVS Programming: Extended Addressability Guide.

Note: The high-order bit is set in the address of the last parameter to indicate the end of the parameter list.

Figure 1. IEFUSI Input Parameter Structure

Note: These fields are only valid when bit 3 in the "Flag word" is set.

Return Specifications

A return code from IEFUSI indicates whether job processing should continue or be cancelled.

If you associate multiple exit routines with IEFUSI, you can specify how the return information is to be handled using the ATTRIB KEEPRC function of the SETPROG EXIT command, the EXIT statement of PROGxx, or CSVDYNEX services. If multiple exit routines match the ATTRIB KEEPRC criteria, the system returns information from the exit routine that finished first.

If you do not specify the ATTRIB KEEPRC function, the system returns the information from the exit routine whose return value was the greatest. If multiple exit routines return with the same highest value, the return information from the exit routine that finished first will be returned.

If you associate multiple exit routines with exit IEFUSI, and any of those exit routines return with a value of 4, job processing will be cancelled.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register

Contents

0 - 14

Restored to contents at entry

15

One of the following return codes:

Return Code: Explanation
4: Job processing should be cancelled.
Other than 4: Job processing should continue.

Examples

The examples that follow illustrate actual allocations based on region size and limit values set by IEFUSI.

Example of using IEFUSI to Limit Region Size: Suppose you want to limit all jobs in a given step-accounting category to a user region of 4 megabytes below and 4 megabytes above 16 megabytes. You also want to set a GETMAIN limit of 6 megabytes below 16 megabytes and 48 megabytes above 16 megabytes.

The system applies the following limits when allocating space for the program whose values you set in IEFUSI:

(Assume that the user's private area below 16 megabytes is 8
megabytes, and that the extended private area, above 16
megabytes, is approximately 1975 megabytes.)

Limit Value below 16Mb = 6Mb: (Less than 8Mb)
Limit Value above 16Mb = 48Mb: (The value from IEFUSI is greater than 32Mb, but less than the extended private area)
Region Size below 16Mb = 4Mb: (Less than limit value)
Region Size above 16Mb = 4Mb: (Less than extended limit value)

Examples of Storage Allocations Based on Values Set by IEFUSI: Assume that application program A has the following characteristics:

 Limit value                 150K
 REGION size value           100K
 Space currently allocated    80K

Program A issues the following variable length GETMAIN requests, in the order indicated (note that the GETMAIN requests are cumulative ):

Request 5K—10K: 10K is allocated, making the currently allocated space 90K.
Because the amount still unallocated (20K, relative to the region size of 100K), was greater than the maximum amount requested, the maximum amount was allocated.
Request 5K—100K: 10K is allocated, making the currently allocated space 100K.
Because the amount still unallocated (10K, relative to the region size) was between the minimum and maximum requested, the unallocated space was allocated.
Request 40K—100K: 40K is allocated, making currently allocated space 140K.
Although the amount still unallocated (0K, relative to the region size) was less than the minimum amount requested (40K), the minimum amount requested would not increase the currently allocated space beyond the limit value, so the minimum amount was allocated.
Request 15K—50K: the GETMAIN fails.
The amount still unallocated (0K, relative to the region size) was less than the minimum amount requested (15K), AND the minimum requested would increase the currently-allocated space to 155K, which exceeds the GETMAIN limit value of 150K.

The region size value is usually set up to be less than the limit value. This will protect against programs that issue variable length GETMAINs with very large maximums and then do not immediately free part of that space, or free such a small amount that a subsequent GETMAIN (possibly issued by a system service) causes the job to fail.

As an example, suppose that the region size value equals the limit value, and a program issues a variable length GETMAIN with a maximum of (2 gigabytes − 1). If the GETMAIN is satisfied, all the space in the region up to the limit value will be allocated, and any subsequent GETMAIN that cannot be satisfied from free space in an existing subpool will cause the job to fail.

If, however, the region size value is less than the limit value, only space up to the region size value is allocated for the GETMAIN. Thus, an amount of space equal to the limit value minus the region size value remains for subsequent GETMAINs.

Note: For V=R jobs, the REGION parameter is more significant as a limiting value than are the limits set by IEFUSI. You can use the two factors together to control the region size for applications that must run V=R:

Set the region size value where you want it, via IEFUSI.
If a REGION parameter specification for a V=R job exceeds the region size value you have set, the job will not be initiated.

Coded Example of the Exit Routine

A sample IEFUSI exit routine is provided in SYS1.SAMPLIB in member IEEUSI. It sets the flag in the VSM parameter list indicating that it is controlling region sizes and limits instead of IEALIMIT. It is designed to perform the same processing as IEALIMIT in the control of region size and limit above and below the 16Mb line.