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. Start of changeProblem state callers must pass parameters in storage with the same key as the initial execution key of the job step or attached program.End of change