Topics for This Exit Appear as Follows:
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.
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:
- 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.
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-ins 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
one 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 eight-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 eight-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(), 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 a six-word area that IEFUSI can use to communicate
with MVS regarding the region size and region limit
it desires. The region size and region limit information consists
of:
- 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. |
|
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 |
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. |
|
1 |
Check if the requested above-16-megabyte-region
size is available. If the size is not available, an 822 abend occurs. |
3-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.
On every entry to IEFUSI, the last four words 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 four-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' x 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**24)-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**32)-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**31)-1.
Note: If you change
the default, make sure you balance this with other uses of SQA storage.
The number of 4K pages that Extended SQA (ESQA) requires equals (the
number of shared pages plus the number of shared views plus 252) all
divided by 127 and then ignoring any remainder.
- 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.
Note: - 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
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.
- Oher 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 already-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.