IFAUSAGE macro
IFAUSAGE identifies individual products as users of a system and identifies the type and level of usage data for each product. If you do not provide your own product-specific usage data, IFAUSAGE collects data that already exists in the system, generally CPU time. (See CPU time for detailed information about CPU time.) The usage reporting program analyzes the usage data and produces a report that contains identification and usage data for each product over specific intervals of time. Together, IFAUSAGE and the usage reporting program enable you to track product usage on a system or a sysplex basis, assuming that the system or systems are running SMF.
You identify a product to SMF by issuing the IFAUSAGE macro with the REQUEST=REGISTER parameter. You must register a product before issuing any of the other REQUEST parameters.
When you specify REQUEST=REGISTER, the system returns a token that you can use on subsequent request options. Specifying this token eliminates the need to specify the product registration information (PRODOWNER, PRODNAME, PRODVERS, PRODQUAL, and PRODID parameters). If you do not code the optional parameters PRODVERS, PRODQUAL, and PRODID on REQUEST=REGISTER and any subsequent requests, a blank field will appear in the corresponding report field. For the report program only, specifying PRODOWNER=NONE, PRODNAME=NONE, or PRODVERS=NONE, has the same effect as not coding the parameter at all.
When registering a product, you also can identify the scope of data you want to accumulate for the eventual report. For example, you can attribute all CPU time for an address space or for a task to a specified product.
If you choose to accumulate data for a task, you can further choose to record the product's use of resources on the REQUEST=FUNCTIONDATA parameter. In this case, IFAUSAGE starts collecting data only when you specify REQUEST=FUNCTIONBEGIN, and it ends when you specify REQUEST=FUNCTIONEND. Resources identified on the FUNCTIONDATA parameter are recorded in the SMF type 89 record. The report program, IFAURP, does not currently process the FUNCTIONDATA fields in the type 89 record or include the data in its report.
You cannot specify any of the other request options for a particular product once you have specified REQUEST=DEREGISTER for the product. When you specify REQUEST=DEREGISTER for a product, the system no longer collects usage data for this registration instance of the product. If other registrations for the product are still active, data recorded under those registrations continues to be collected. The system stops collecting data for the product only when there are no active registrations for the product.
Programs in both supervisor and problem state can issue the IFAUSAGE macro. However, programs running in problem state can only issue LINKAGE=SVC with the REQUEST=REGISTER or REQUEST=STATUS parameters. For problem state programs, IFAUSAGE allows only two REQUEST=REGISTER invocations for each domain specified on the DOMAIN parameter. Problem state callers must pass parameters in storage with the same key as the initial execution key of the job step or attached program.
Environment
The requirements for the caller are:
Minimum authorization: | Problem state and any PSW key. For LINKAGE=BRANCH, supervisor
state. Problem state callers must pass parameters in storage with the same key as the initial execution key of the job step or attached program. |
Dispatchable unit mode: | Task. |
Cross memory mode: | PASN=HASN=SASN. |
AMODE: | 31- or 64-bit. If in AMODE 31, do not
use the following parameters:
If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro. Do not use the following
parameters in AMODE 64:
Callers in AMODE 64 may pass in parameter list and parameter list data that resides in 31-bit or 64-bit storage. |
ASC mode: | Primary. |
Interrupt status: | Enabled for I/O and external interrupts. |
Locks: | No locks may be held. |
Control parameters: | None. |
Programming requirements
None.
Restrictions
IFAUSAGE supports multiple versions. Some keywords are unique to certain versions. For details, see the description of the PLISTVER parameter.
Input register information
- Register
- Contents
- 13
- The address of a standard 72-byte save area
Before issuing the IFAUSAGE macro, the caller does not have to place any information into any access register (AR) unless using it in register notation for a particular parameter or using it as a base register.
Output register information
- Register
- Contents
- 0
- Unchanged
- 1
- Used by the system
- 2 - 13
- Unchanged
- 14
- Used by the system (LINKAGE=BRANCH) or unchanged (LINKAGE=SVC)
- 15
- Return code
- Register
- Contents
- 0 - 15
- Unchanged
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
The IFAUSAGE macro is written as follows:
Parameters that apply to all request types
- name
- An optional symbol, starting in column 1, that is the name on the IFAUSAGE macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
- REQUEST=REGISTER
- REQUEST=DEREGISTER
- REQUEST=FUNCTIONBEGIN
- REQUEST=FUNCTIONDATA
- REQUEST=FUNCTIONEND
- REQUEST=STATUS
- A required parameter that specifies the service to be invoked.
- REQUEST=REGISTER
- Specifies a request to identify a product for usage data collection and provide the domain and scope options to be used. See Parameters for REQUEST=REGISTER for parameters that are specific to this request type.
- REQUEST=DEREGISTER
- Specifies a request to end data collection for the product in the current domain and scope. See Parameters for REQUEST=DEREGISTER for parameters that are specific to this request type.
- REQUEST=FUNCTIONBEGIN
- Specifies a request to start collecting function-level data for the product in the current domain and scope. See Parameters for REQUEST=FUNCTIONBEGIN for parameters that are specific to this request type.
- REQUEST=FUNCTIONDATA
- Specifies a request to provide product-specific usage data for the product in the current domain and scope. You must have issued a FUNCTIONBEGIN request before you can issue a FUNCTIONDATA request. See Parameters for REQUEST=FUNCTIONDATA for parameters that are specific to this request type.
- REQUEST=FUNCTIONEND
- Specifies a request to stop collecting function-level data for the product in the current domain and scope. See Parameters for REQUEST=FUNCTIONEND for parameters that are specific to this request type.
- REQUEST=STATUS
- Specifies a request to generate code which will check the status (available and active) of the usage data collection service and the installation recording request for the system-wide usage data record (type 89). The status is returned via a return code. The return code value will be in the variable specified by the RETCODE parameter, or in register 15 if the RETCODE parameter is not specified. For a list of the values that can be returned, see Return codes.
- ,LINKAGE=SVC
- ,LINKAGE=BRANCH
- An optional parameter that specifies the type of linkage to be generated for the data collection service.
- ,LINKAGE=SVC
- Requests that an SVC-type invocation of the service be generated.
- ,LINKAGE=BRANCH
- Requests that direct CALL be used to invoke the service. Callers using LINKAGE=BRANCH must be in supervisor state.
Default:,LINKAGE=SVC
- ,VALIDATE=YES
- ,VALIDATE=NO
- When LINKAGE=BRANCH is specified, an optional parameter that specifies whether certain
validation (such as of the input token) is to be done.
- ,VALIDATE=YES
- Requests that all validation be done.
- ,VALIDATE=NO
- Requests that limited validation be done.
Default:,VALIDATE=YES
- ,FBFE=NO
- ,FBFE=YES
- An optional parameter that specifies whether the caller intends to use FUNCTIONBEGIN and
FUNCTIONEND processing to account for time. This keyword has no effect on internal processing.
- ,FBFE=NO
- Specifies that FUNCTIONBEGIN and FUNCTIONEND will not be done.
- ,FBFE=YES
- Specifies that FUNCTIONBEGIN and FUNCTIONEND will be done.
Default:,FBFE=NO
- ,RETCODE=retcode
- An optional output parameter into which the return code is to be copied from GPR 15. If you
specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR
15.To code: Specify the RS-type address of a fullword field, or register (2) - (12) or (15), (GPR15), (REG15), or (R15).
- ,PLISTVER=IMPLIED_VERSION
- ,PLISTVER=MAX
- ,PLISTVER=1
- ,PLISTVER=2
- An optional input parameter that specifies the version of the macro. PLISTVER determines which
parameter list the system generates. PLISTVER is an optional input parameter on all forms of the
macro, including the list form. When using PLISTVER, specify it on all macro forms used for a
request and with the same value on all of the macro forms. The values are:
- IMPLIED_VERSION
- Specifies the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
- MAX
- Specifies that the parameter list is to be the largest size currently possible. This size might
grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
- 1
- Supports all parameters except those specifically referenced in higher versions.
- 2
- Supports the following parameters and those from version 1:
- BEGTIME64
- CURRENTDATA64
- DATA64
- ENDDATA64
- ENDTIME64
- PRTOKEN64
To code: Specify one of the following:- IMPLIED_VERSION
- MAX
- A decimal value of 1 or 2
- ,MF=S
- ,MF=(L,listaddr)
- ,MF=(L,listaddr,attr)
- ,MF=(L,listaddr,0D)
- ,MF=(E,listaddr)
- ,MF=(E,listaddr,COMPLETE)
- ,MF=(E,listaddr,NOCHECK)
- ,MF=(M,listaddr)
- ,MF=(M,listaddr,COMPLETE)
- ,MF=(M,listaddr,NOCHECK)
- An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms of IFAUSAGE in the following order:- Use IFAUSAGE ...,MF=(M,listaddr,COMPLETE), specifying appropriate parameters, including all required ones.
- Use IFAUSAGE ...,MF=(M,listaddr,NOCHECK), specifying the parameters that you want to change.
- Use IFAUSAGE ...,MF=(E,listaddr,NOCHECK),to execute the macro.
- listaddr
- The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register (1) - (12).
- attr
- An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
- COMPLETE
- Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
- NOCHECK
- Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
Parameters for REQUEST=REGISTER
When you specify REQUEST=REGISTER, the following parameters apply:
- ,PRODOWNER=prodowner
- A required input parameter that contains the product's owner or vendor name for this request.
IBM® products use the character string "IBM CORP."To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRODNAME=prodname
- A required input parameter that contains the name of the product for this request.To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRODVERS=NONE
- ,PRODVERS=prodvers
- An optional input parameter that contains the version of the product for the request. Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODQUAL=NONE
- ,PRODQUAL=prodqual
- An optional input parameter that contains the qualifier of the product for the request. You
might wish to use this parameter when there are multiple iterations of the same product running on
one system and you want to record usage data for each iteration, rather than grouping all product
usage together. If a product is running multiple times on a specific system, you can record usage
based on individual system use of the product. A subsystem product could use the subsystem name as
the qualifier under which each copy of the product runs.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODID=NONE
- ,PRODID=prodid
- An optional input parameter that contains the ID of the product (for instance, the product ID
(PID) number) for the request. Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,DOMAIN=ADDRSP
- ,DOMAIN=TASK
- An optional parameter that specifies the level of data to be collected for the product.
- ,DOMAIN=ADDRSP
- Requests data collection at the address space level.
- ,DOMAIN=TASK
- Requests data collection for the current task.
Default:,DOMAIN=ADDRSP
- ,SCOPE=ALL
- ,SCOPE=FUNCTION
- An optional parameter that specifies the level of data collection within the task that is being requested.
- ,SCOPE=ALL
- Requests that all the CPU time in the task be associated with the requesting product.
- ,SCOPE=FUNCTION
- Requests that only the CPU time that is accumulated during the invocation of the FUNCTIONBEGIN and FUNCTIONEND requests be associated with this product. Additional invocations of the IFAUSAGE macro for FUNCTIONBEGIN and FUNCTIONEND requests is expected.
Default:,SCOPE=ALL
- ,PRTOKEN=prtoken
- ,PRTOKEN64=prtoken64
- An optional output parameter into which the service will place a usage product token that can be
used in subsequent service invocations. Using the token provides a shortened path length on those
requests (eliminating the need to specify PRODNAME, PRODVERS, PRODOWNER, PRODQUAL, and PRODID each
time), but is not required.
- ,PRTOKEN=prtoken
- A parameter variable to hold the usage product token when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,PRTOKEN64=prtoken64
- A parameter variable to hold the usage product token when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,UNAUTHSERV=BASE
- ,UNAUTHSERV=LEVEL1
- An optional parameter that specifies the level of authorized services to which the unauthorized
caller requires access.
Authorized callers can use all services without SAF authorization, and may use the LINKAGE=BRANCH interface.
- ,UNAUTHSERV=BASE
- Specifies that an unauthorized caller does not need access to any IFAUSAGE services other than REGISTER and STATUS. Unauthorized callers that do not have SAF authorization are limited to two IFAUSAGE REGISTER requests per address space.
- ,UNAUTHSERV=LEVEL1
- Specifies that an unauthorized caller requires access to IFAUSAGE services that are available to
authorized callers. These services include DEREGISTER, FUNCTIONBEGIN, FUNCTIONDATA, and FUNCTIONEND.
The unauthorized caller may also issue more than two IFAUSAGE REGISTER requests per address
space.
The SAF facility is used to validate that the installation has authorized the user ID associated with this job or task to use LEVEL1 features. The user ID must have READ access to the IFAUSAGE.prodowner.prodname.prodqual.prodid profile in the XFACILIT class. The prodowner, prodname, prodqual, and prodid are translated to upper case, and any special characters are translated to an underscore (
_
). Any fields that are blank are not represented in the profile name.
Default:,UNAUTHSERV=BASE
Parameters for REQUEST=DEREGISTER
When you specify REQUEST=DEREGISTER, the following parameters apply:
- ,PRODOWNER=prodowner
- ,PRTOKEN=prtoken
- ,PRTOKEN64=prtoken64
- A mutually exclusive set of required input parameters.
- ,PRODOWNER=prodowner
- A parameter that contains the product's owner or vendor name for this request. You cannot
specify PRODOWNER if you specify PRTOKEN or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRTOKEN=prtoken
- A parameter that contains the name of the product token that was returned on the associated
REGISTER request when invoking IFAUSAGE in
AMODE 31. The parameter value must reside in 31-bit storage. You cannot specify PRTOKEN if you
specify PRODOWNER or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRTOKEN64=prtoken64
- A parameter that contains the name of the product token that was returned on the
associated REGISTER request when invoking
IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage. You cannot
specify PRTOKEN64 if you specify PRODOWNER or PRTOKEN. To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRODNAME=prodname
- When PRODOWNER=prodowner is specified, a required input parameter that
contains the name of the product for this request. You must specify PRODNAME if you specify
PRODOWNER. You cannot specify PRODNAME if you specify PRTOKEN or PRTOKEN64.
To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRODVERS=NONE
- ,PRODVERS=prodvers
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the version of the product for the request. You can only specify PRODVERS if you specify
PRODOWNER. You cannot specify PRODVERS if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODQUAL=NONE
- ,PRODQUAL=prodqual
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the qualifier of the product for the request. You can only specify PRODQUAL if you specify
PRODOWNER. You cannot specify PRODQUAL if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODID=NONE
- ,PRODID=prodid
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the ID of the product (for instance, the product ID (PID) number) for the request. You can
only specify PRODID if you specify PRODOWNER. You cannot specify PRODID if you specify PRTOKEN or PRTOKEN64. Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,ENDTIME=endtime
- ,ENDTIME64=endtime64
- An optional output parameter into which IFAUSAGE returns the amount of TCB time, from the time
you issued the REGISTER request, or the time the task has run up to the time you issue the
DEREGISTER request.
- ,ENDTIME=endtime
- Use this parameter when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,ENDTIME64=endtime64
- Use this parameter when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,ENDDATA=enddata
- ,ENDDATA64=enddata64
- An optional output parameter into which IFAUSAGE returns data accumulated by all FUNCTIONDATA
requests for the product recorded under this domain since the REGISTER request.
- ,ENDDATA=enddata
- Use this parameter when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,ENDDATA64=enddata64
- Use this parameter when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
Parameters for REQUEST=FUNCTIONBEGIN
When you specify REQUEST=FUNCTIONBEGIN, the following parameters apply:
- ,PRODOWNER=prodowner
- ,PRTOKEN=prtoken
- ,PRTOKEN64=prtoken64
- A mutually exclusive set of required input parameters.
- ,PRODOWNER=prodowner
- A parameter that contains the product's owner or vendor name for this request. You cannot
specify PRODOWNER if you specify PRTOKEN or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRTOKEN=prtoken
- A parameter that contains the name of the product token that was returned on the associated
REGISTER request when invoking IFAUSAGE in
AMODE 31. The parameter value must reside in 31-bit storage. You cannot specify PRTOKEN if you
specify PRODOWNER or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRTOKEN64=prtoken64
- A parameter that contains the name of the product token that was returned on the
associated REGISTER request when invoking
IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage. You cannot
specify PRTOKEN64 if you specify PRODOWNER or PRTOKEN. To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRODNAME=prodname
- When PRODOWNER=prodowner is specified, a required input parameter that
contains the name of the product for this request. You must specify PRODNAME if you specify
PRODOWNER. You cannot specify PRODNAME if you specify PRTOKEN or PRTOKEN64.
To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRODVERS=NONE
- ,PRODVERS=prodvers
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the version of the product for the request. You can only specify PRODVERS if you specify
PRODOWNER. You cannot specify PRODVERS if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODQUAL=NONE
- ,PRODQUAL=prodqual
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the qualifier of the product for the request. You can only specify PRODQUAL if you specify
PRODOWNER. You cannot specify PRODQUAL if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODID=NONE
- ,PRODID=prodid
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the ID of the product (for instance, the product ID (PID) number) for the request. You can
only specify PRODID if you specify PRODOWNER. You cannot specify PRODID if you specify PRTOKEN or PRTOKEN64. Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,BEGTIME=begtime
- ,BEGTIME64=begtime64
- An optional output parameter into which IFAUSAGE returns the beginning CPU time for the product.
- ,BEGTIME=begtime
- Use this parameter when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,BEGTIME64=begtime64
- Use this parameter when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
Parameters for REQUEST=FUNCTIONDATA
When you specify REQUEST=FUNCTIONDATA, the following parameters apply:
- ,PRODOWNER=prodowner
- ,PRTOKEN=prtoken
- ,PRTOKEN64=prtoken64
- A mutually exclusive set of required input parameters.
- ,PRODOWNER=prodowner
- A parameter that contains the product's owner or vendor name for this request. You cannot
specify PRODOWNER if you specify PRTOKEN or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRTOKEN=prtoken
- A parameter that contains the name of the product token that was returned on the associated
REGISTER request when invoking IFAUSAGE in
AMODE 31. The parameter value must reside in 31-bit storage. You cannot specify PRTOKEN if you
specify PRODOWNER or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRTOKEN64=prtoken64
- A parameter that contains the name of the product token that was returned on the
associated REGISTER request when invoking
IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage. You cannot
specify PRTOKEN64 if you specify PRODOWNER or PRTOKEN. To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRODNAME=prodname
- When PRODOWNER=prodowner is specified, a required input parameter that
contains the name of the product for this request. You must specify PRODNAME if you specify
PRODOWNER. You cannot specify PRODNAME if you specify PRTOKEN or PRTOKEN64.
To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRODVERS=NONE
- ,PRODVERS=prodvers
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the version of the product for the request. You can only specify PRODVERS if you specify
PRODOWNER. You cannot specify PRODVERS if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODQUAL=NONE
- ,PRODQUAL=prodqual
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the qualifier of the product for the request. You can only specify PRODQUAL if you specify
PRODOWNER. You cannot specify PRODQUAL if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODID=NONE
- ,PRODID=prodid
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the ID of the product (for instance, the product ID (PID) number) for the request. You can
only specify PRODID if you specify PRODOWNER. You cannot specify PRODID if you specify PRTOKEN or PRTOKEN64. Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,DATA=data
- ,DATA64=data64
- A required input parameter that contains the resource data you want to accumulate. Fixed data
should right-justified and padded with zeros.
- ,DATA=data
- Use this parameter when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,DATA64=data64
- Use this parameter when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,FORMAT=CPUTIME
- ,FORMAT=BINARY
- ,FORMAT=FLOAT
- An optional input parameter that specifies the data type of the value in the DATA or DATA64 parameter.
- ,FORMAT=CPUTIME
- The value in the DATA parameter is a CPU time in STCK format.
- ,FORMAT=BINARY
- The value in the DATA parameter is in 64-bit binary format.
- ,FORMAT=FLOAT
- The value in the DATA parameter is in long floating-point hexadecimal format.
- ,CURRENTDATA=currentdata
- ,CURRENTDATA64=currentdata64
- An optional output parameter into which IFAUSAGE returns the data accumulated by this and
previous FUNCTIONDATA requests.
- ,CURRENTDATA=currentdata
- Use this parameter when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,CURRENTDATA64=currentdata64
- Use this parameter when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
Parameters for REQUEST=FUNCTIONEND
When you specify REQUEST=FUNCTIONEND, the following parameters apply:
- ,PRODOWNER=prodowner
- ,PRTOKEN=prtoken
- ,PRTOKEN64=prtoken64
- A mutually exclusive set of required input parameters.
- ,PRODOWNER=prodowner
- A parameter that contains the product's owner or vendor name for this request. You cannot
specify PRODOWNER if you specify PRTOKEN or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRTOKEN=prtoken
- A parameter that contains the name of the product token that was returned on the associated
REGISTER request when invoking IFAUSAGE in
AMODE 31. The parameter value must reside in 31-bit storage. You cannot specify PRTOKEN if you
specify PRODOWNER or PRTOKEN64.To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRTOKEN64=prtoken64
- A parameter that contains the name of the product token that was returned on the
associated REGISTER request when invoking
IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage. You cannot
specify PRTOKEN64 if you specify PRODOWNER or PRTOKEN. To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
- ,PRODNAME=prodname
- When PRODOWNER=prodowner is specified, a required input parameter that
contains the name of the product for this request. You must specify PRODNAME if you specify
PRODOWNER. You cannot specify PRODNAME if you specify PRTOKEN or PRTOKEN64.
To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.
- ,PRODVERS=NONE
- ,PRODVERS=prodvers
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the version of the product for the request. You can only specify PRODVERS if you specify
PRODOWNER. You cannot specify PRODVERS if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODQUAL=NONE
- ,PRODQUAL=prodqual
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the qualifier of the product for the request. You can only specify PRODQUAL if you specify
PRODOWNER. You cannot specify PRODQUAL if you specify PRTOKEN or
PRTOKEN64.Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,PRODID=NONE
- ,PRODID=prodid
- When PRODOWNER=prodowner is specified, an optional input parameter that
contains the ID of the product (for instance, the product ID (PID) number) for the request. You can
only specify PRODID if you specify PRODOWNER. You cannot specify PRODID if you specify PRTOKEN or PRTOKEN64. Default:
NONE
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,ENDTIME=endtime
- ,ENDTIME64=endtime64
- An optional output parameter into which IFAUSAGE returns the current accumulation of CPU time
for the product since the FUNCTIONBEGIN request was issued.
- ,ENDTIME=endtime
- Use this parameter when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,ENDTIME64=endtime64
- Use this parameter when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field. - ,ENDDATA=enddata
- ,ENDDATA64=enddata64
- An optional output parameter into which IFAUSAGE returns the current accumulation of resource
data for the product since the FUNCTIONBEGIN request was issued.
- ,ENDDATA=enddata
- Use this parameter when invoking IFAUSAGE in AMODE 31. The parameter value must reside in 31-bit storage.
- ,ENDDATA64=enddata64
- Use this parameter when invoking IFAUSAGE in AMODE 64. The parameter value may reside in 31-bit or 64-bit storage.
To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.
ABEND codes
IFAUSAGE may issue system completion (ABEND) code 655. For details, see z/OS® MVS™ System Codes.
Return codes
When the IFAUSAGE macro returns control to your program, GPR 15 (and retcode, when you code the RETCODE parameter) contains a return code.
The following table identifies the return codes.
Return code decimal (hex) |
Meaning and action |
---|---|
00 (00) | Meaning: The IFAUSAGE request completed successfully. Action: None. |
04 (04) | Meaning: The error is due to one of the following conditions:
|
08 (08) | Meaning: The error is due to one of the following conditions:
Note: This return code also results if the specification of the PRODOWNER, PRODNAME, PROVERS,
PRODQUAL, or PRODID parameter on a DEREGISTER, FUNCTIONBEGIN, FUNCTIONDATA, or FUNCTIONEND request
does not match the parameter coded on the associated REGISTER request.
|
12 (0C) | Meaning: The PRTOKEN parameter specifies a token that the system cannot identify; the
token is not defined. Action: Check your specification of the PRTOKEN parameter and ensure that it is the same token returned by the REGISTER request. Also verify that the REGISTER request completed with a return code of 0. |
16 (10) | Meaning: IFAUSAGE cannot complete processing because the SMF usage data collection
function is not available on this system. Action: Do not issue the IFAUSAGE macro on this system. |
20 (14) | Meaning: The error is due to one of the following conditions:
|
24 (18) | Meaning: A REGISTER request was specified with the UNAUTHSERV=LEVEL1 keyword to enable
all services for an unauthorized caller, but the SAF resource check failed. Action: Ensure that the SAF resource profile exists and that the user ID associated with this program is permitted to that resource. |
28 (1C) | Meaning: An unauthorized program specified REQUEST=REGISTER,UNAUTHSERV=LEVEL1,DOMAIN=ADDRSP while running in an address space with multiple SAF environments established. |