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:

BEGTIME64
CURRENTDATA64
DATA64
ENDDATA64
ENDTIME64
PRTOKEN64

If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro. Do not use the following parameters in AMODE 64:

BEGTIME
CURRENTDATA
DATA
ENDDATA
ENDTIME
PRTOKEN

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

Before issuing the IFAUSAGE macro with LINKAGE=BRANCH, the caller must ensure that the following general purpose registers (GPRs) contain the specified 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

When control returns to the caller, the GPRs contain:

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

When control returns to the caller, the ARs contain:

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:

Main diagram

Parameters-1

Parameters-2

Parameters-3

Parameters-4

Parameters-5

Parameters-6

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

To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.

,PRODVERS=NONE

,PRODVERS=prodvers

Default: NONE

To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.

,PRODQUAL=NONE

,PRODQUAL=prodqual

Default: NONE

To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.

,PRODID=NONE

,PRODID=prodid

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

To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.

,PRODVERS=NONE

,PRODVERS=prodvers

Default: NONE

To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.

,PRODQUAL=NONE

,PRODQUAL=prodqual

Default: NONE

To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.

,PRODID=NONE

,PRODID=prodid

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

To code: Specify the RS-type address or address in register (2) - (12) of a 16-character field.

,PRODVERS=NONE

,PRODVERS=prodvers

Default: NONE

To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.

,PRODQUAL=NONE

,PRODQUAL=prodqual

Default: NONE

To code: Specify the RS-type address or address in register (2) - (12) of an 8-character field.

,PRODID=NONE

,PRODID=prodid

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.

Table 1. Return codes and reason codes for the IFAUSAGE macro
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: REGISTER — Another product has already registered for the domain specified on the DOMAIN parameter. IFAUSAGE records the data for both products. Action: No action is necessary. However, you may receive duplicate data for each product. FUNCTIONDATA — The data format specified on the FORMAT parameter of the FUNCTIONDATA request does not match the format specified by a previous caller. All subsequent invocations of REQUEST=FUNCTIONDATA must specify the same data format as the first caller. Action: Check usage records or read SMF type 89 records to identify the specified data format. Ensure that you specify the same format on the FORMAT parameter on any subsequent invocations of REQUEST=FUNCTIONDATA. STATUS — You specified REQUEST=STATUS, but the installation is not collecting SMF record type 89. Action: Ensure that the installation intends to collect type 89 records. If it does not, do not issue IFAUSAGE. If the installation does intend to collect type 89 records, check with your installation programmer that the record type is specified in the SMFPRMxx parmlib member.
08 (08)	Meaning: The error is due to one of the following conditions: REGISTER — The unauthorized request would have caused the unauthorized request limit to be exceeded; IFAUSAGE cannot process more than two unauthorized (problem state) program invocations of REQUEST=REGISTER for a domain. Action: Do not specify REQUEST=REGISTER more than two times for any specific domain. DEREGISTER — The caller issued a DEREGISTER request for a product for which a prior REGISTER request has not been issued. Action: Issue IFAUSAGE with the REQUEST=REGISTER parameter to identify the product to the system for usage data collection. FUNCTIONBEGIN — The caller issued a FUNCTIONBEGIN request for a product for which a prior REGISTER request has not been issued. Action: Issue IFAUSAGE with the REQUEST=REGISTER parameter to identify the product to the system for usage data collection. FUNCTIONDATA — The caller issued a FUNCTIONDATA request for a product for which a prior FUNCTIONBEGIN request has not been issued. Action: Issue IFAUSAGE with the REQUEST=FUNCTIONBEGIN parameter to identify the function to the system for usage data collection. FUNCTIONEND — The caller issued a FUNCTIONEND request for a product for which a prior FUNCTIONBEGIN request has not been issued. Action: Issue IFAUSAGE with the REQUEST=FUNCTIONBEGIN parameter to identify the function to the system for usage data collection. 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: REGISTER, DEREGISTER, FUNCTIONBEGIN, FUNCTIONDATA, or FUNCTIONEND — The current task environment does not support usage data collection. This only applies to invocations from system tasks (those tasks at or above the initiator task in an address space) or tasks in system address spaces where the TCB does not have a valid SMF Timing Control table as indicated by TCBTCT=0. This table is necessary to store Usage Data information. Action: Do not issue the IFAUSAGE macro from this task. An internal parameter error was detected. Record the return code and contact IBM Support.
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.