Use the IXZXIXPI macro to provide an interface for resource monitoring
products such as Resource Measurement Facility (RMF) to obtain required
data. Use this macro to extract information from the JES XCF message
queues concerning address space delays encountered due to JES3 processing
delays.
Refer to Collecting JES3 Performance Information Data (IXZXIXPI Macro) for a description
of using IXZXIXPI to access JES XCF message queues.
Environment
The requirements for the caller
are:
Table 1. EnvironmentVariable |
Value |
---|
JES environments: |
JES3 User |
Minimum authorization: |
Supervisor state with PSW key 0 or 1 |
Dispatchable unit mode: |
Task |
Cross memory mode: |
PASN=HASN=SASN |
AMODE: |
31 |
ASC mode: |
Primary |
Interrupt status: |
Enabled for I/O and external interrupts |
Locks: |
No locks held |
Control parameters: |
None |
Programming Requirements
JES2 programs must
include the $MODULE macro so it is invoked before IXZXIXPI is invoked.
JES3 programs must include the ENVIRON= keyword on the IATYMOD
macro so it is invoked before IXZXIXPI is invoked.
Restrictions
Do not issue IXZXIXPI until
JES3 initialization processing has established an attachment to the
JES XCF group; that is, after IXZXIT03 processing has completed.
Input Register Information
Before issuing
the IXZXIXPI macro, the caller does not have to place any information
into any register unless using it in register notation for a particular
parameter, or using it as a base register.
Output Register Information
When IXZXIXPI
returns control, the general purpose registers (GPRs) contain:
- Register
- Content
- 0
- Reason code
- 1
- Used as a work register by the system
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
When IXZXIXPI returns control, the access registers
(ARs) contain:
- Register
- Content
- 0,1
- Used as a work register by the system
- 2-13
- Unchanged
- 14,15
- Used as a work register by the system
Some callers depend on register contents remaining
the same before and after issuing a service. If the system changes
the contents of registers on which the caller depends, the caller
must save them before issuing the service, and restore them after
the system returns control.
Performance Implications
None
Syntax
>>-+-------+--IXZXIXPI----GROUPTOKEN=grouptoken----------------->
'-label-'
>----,PIDS=pids------,PIDSSIZE=pidssize------------------------->
>--+------------------+--+------------------+------------------->
'-,RTNCODE=rtncode-' '-,RSNCODE=rsncode-'
.-,MF=S-------------------------------.
>--+-------------------------------------+---------------------><
| .-,0D-----. |
'-,MF=-+-(L-,mfctrl-+---------+-)---+-'
| '-,mfattr-' |
| .-,COMPLETE-. |
'-(E-,mfctrl-+-----------+-)-'
Parameters
- label
- Specifies an optional symbol, starting in column 1, to be used
as the name on the IXZXIXPI macro invocation.
Default: no
name
- GROUPTOKEN=grouptoken
- Specifies the name (RS-type) or address (in GPR2-GPR12) of a required
fullword input field that contains the group token returned by the
IXZXIXAT macro.
Default: none
- PIDS=pids
- Specifies the name (RS-type) of a required fullword input/output
field or register (GPR2-GPR12) into which JES XCF puts the address
of the JES3 performance output data. This storage is in the caller's
address space (key 0).
Default: none
- PIDSSIZE=pidssize
- Specifies the name (RS-type) of a required fullword input/output
field or register (GPR2-GPR12) that contains the size of the JES3
performance output data area to which the PIDS= parameter points.
If the size of the area requested is too small, JES XCF returns the
correct size requirement to the caller in the field specified by this
parameter.
Default: none
- RTNCODE=rtncode
- Specifies the name (RS-type) of an optional fullword output field
or register (GPR2-GPR12) into which the return code is copied from
GPR 15.
Default: none
- RSNCODE=rsncode
- Specifies the name (RS-type) of an optional fullword output field
or register (GPR2-GPR12) into which the reason code is copied from
GPR 0.
Default: none
- MF=S | L | E
- Specifies the form of the macro as standard (S), list (L), or
execute (E). This keyword is optional.
- MF=S
- Specifies the standard form of the macro; that is, to build the
in-line parameter list and invoke the desired service. Processing
also includes checking for all required keywords and supplying defaults,
if any, for omitted optional parameters.
- MF=(L,mfctrl{,mfattr | 0D})
- Specifies the list form of the macro; that is, defining an area
to be used for the parameter list. If you code MF=L, do not code anything
else except a label, the macro name, and the following values:
- mfctrl
- Specifies the name of a storage area to contain the parameters.
- mfattr | 0D
- Specifies an optional 1- to 60-character input string, which can
contain any value that is valid on an assembler DS pseudo-op. You
can use this parameter to force boundary alignment of the parameter
list. If you do not code mfattr, the system provides a value
of 0D, which forces the parameter list to a doubleword boundary.
Default: 0D
- MF=(E,mfctrl,COMPLETE)
- Specifies the execute form of the macro; that is, builds the parameter
list specified by mfctrl. Processing also includes checking
for all required keywords and supplying defaults, if any, for omitted
optional parameters.
- mfctrl
- Specifies the name (RS-type) or address (in GPR1-GPR12) of a storage
area for the parameter list.
- COMPLETE
- Specifies the desired degree of macro parameter syntax checking.
Syntax checking includes checking for all required keywords and supplying
default values, if any, for all omitted optional parameters.
Default: COMPLETE
Default: S
ABEND Codes
When control returns to your
program, if you receive a return code of X'C', it indicates
that processing failed because the IXZXIXPI service ended abnormally,
and you will also receive an associated ABEND code. Refer to z/OS MVS System Codes
for a description of possible ABEND codes.
Return and Reason Codes
When the IXZXIXPI
macro returns control to your program, GPR 15 (and rtncode if you coded RTNCODE) contains the return code and GPR 0
(and rsncode if you coded RSNCODE) contains
the reason code.
Return Code
(hex) |
Reason Code (hex) |
Meaning and Action |
---|
0 |
0 |
Meaning: Processing was successful. JES
XCF accessed and returned the JES3 performance data. Action: None
|
4 |
0 |
Meaning: Processing failed because the
size of the storage requested (PIDSSIZE=) was too small. Action: Change the PIDSSIZE= specification to the value IXZXIXPI returned
in the field pointed to by PIDS= and rerun the program that issues
the IXZXIXPI macro.
|
8 |
4 |
Meaning: Processing failed because the
IXZXIXPI service exceeded its retry count. The IXZXIXPI service routine
is unable to gather data due to the lack of serialization. Action: This return code is temporary. Rerun the program that
issues the IXZXIXPI macro or assume there is no data to be returned
at this point in the processing cycle.
|
C |
0 |
Meaning: Processing failed because the
IXZXIXPI service abended. Action: Refer to z/OS MVS System Codes
for a description of the abend code and its associated reason codes.
|