Using and registering functions with the IBM Function Registry for z/OS

IBM Function Registry for z/OS provides a simple way to find and enable functions on a z/OS system. A function is anything provided by IBM or a vendor within any z/OS product (such as, for IBM, XCF or CICS). For example, a function registered with the IBM Function Registry for z/OS could be representing a particular service or an operational mode a product offers.

The IBM Function Registry for z/OS provides:
  • Information about registered functions, such as whether a function is available on the system, whether it has been enabled, whether it has been used, and optionally, how often it has been used.
  • Ways to enable and disable registered functions within a product. For example, users might want to disable new registered functions shipped in the service stream.
Note that the IBM Function Registry for z/OS is simply a repository of information about functions. It is not a legal instrument, nor is it related to usage rates, or licensing.

Using the IBM Function Registry for z/OS

  • Display information about functions in the IBM Function Registry for z/OS, including the enablement state of each. There are two ways to do this:
    • Use the FXEPRINT tool to send all IBM Function Registry for z/OS data to an output data set. A JCL sample for using the FXEPRINT tool is included in SYS1.SAMPLIB member FXEPRNTJ and looks as follows:
      //FXEPRINT JOB
…
//FXEPRINT EXEC PGM=FXEPRINT,TIME=1440,REGION=0K
//SYSOUT   DD SYSOUT=A,DCB=(LRECL=80)
//SYSIN    DD DUMMY
/*
    • Issue the DISPLAY FXE command to display the current enablement state of selected functions currently registered with the IBM Function Registry for z/OS using the vendor, product, and function selector information supplied by the function owner. See the DISPLAY FXE command in z/OS MVS System Commands.
  • Enable and disable functions in the IBM Function Registry for z/OS using parmlib members as follows:
    • Define the enablement state you want for functions in an FXEPRMxx parmlib member. Specify the information identifying the function as directed by the function owner. See information on FXEPRMxx in z/OS MVS Initialization and Tuning Reference.
    • Specify the FXE= parameter in parmlib member IEASYSxx to identify the FXEPRMxx members you want the system to use starting at IPL time. See information on FXE= in IEASYSxx in z/OS MVS Initialization and Tuning Reference.
    • Issue the SET FXE command to add FXEPRMxx parmlib members after IPL. See the SET FXE command in z/OS MVS System Commands.
  • Issue the SETFXE command to toggle enablement states for functions in the IBM Function Registry for z/OS. See the SETFXE command in z/OS MVS System Commands.
  • While mainly intended for use by function owners, you can also update some information about functions using the FXECNTRL service, assuming your code runs with the appropriate authority levels. See z/OS MVS Programming: Assembler Services Reference ABE-HSP and z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG.

Registering functions in the IBM Function Registry for z/OS

To register a function in the IBM Function Registry for z/OS, you will put information about your functions in a series of data structures in storage, as shown in Figure 1:
Figure 1. IBM Function Registry for z/OS data structures
funkreg1
All functions are anchored from the XCVT_FRAT field in the XCVT data area (mapping macro IHAXCVT), pointing from there to the following structures in mapping macro FXEFR:
  • FXEFRAT, the anchor table, containing slots, each referencing a single vendor area and defined by the owning vendor. There are two ways to define a slot:
    • Get your slot assigned by IBM by contacting the IBM Support Center. You will be assigned the same slot number for the IBM Function Registry for z/OS, the CICS Vendor Anchor table, and the customer anchor table.
    • Use one of the slots reserved for local use. Because these are not officially registered, use of these slots should be limited to the environment you control and for functions no one else needs.
    Only authorized code can update slot content in the anchor table, since this table is located in key zero storage. Once you set a slot in the anchor table to reference a new vendor area, you cannot free the vendor area or any data structures referenced in that vendor's product and function hierarchy, because no access serialization protocol is provided for the registry data.
  • FXEFRVA, the vendor area or areas containing information about vendors, including references to product areas owned by the vendor. Your code should build your vendor area FXEVRA structure or structures as early as possible, for example in the startup code of an associated subsystem or a vendor/product related started task.
  • FXEFRPA, the product area or areas containing information about one product and all the function entries, mapped by structure FXEFRFE, for the product. It also contains a reference to an optional list of additional instances or versions of the product on this system.

For information about the structure of these data areas and the self-describing attributes, see z/OS MVS Data Areas Volume 1 (ABE - IAR).

Once you have a vendor slot, you can allocate storage and access it to fill in your vendor, product, and function information in the FXEFRAT, FXEVRVA, and FXEFRPA structures mapped by FXEFR using authorized code. Storage in the FXEVRVA vendor area structure and product area structure must be:
  • Key 0 (or other system key), not fetch-protected
  • Common storage (64-bit recommended), pageable or page-fixed (as needed according to owner needs), double-word aligned

In order to support system parameter FXE, which allows to apply FXEPRMxx PARMLIB member statements at system start time, your product code needs to make use of service FXECNTRL REQUEST=APPLYIPLPARM, just before you link in any new product area into the Function Registry data structures. This handshake via service FXECNTRL is required since your product area is not available to the system at startup time and therefore the system cannot apply any statements from FXEPRMxx members that target your product area at that time. The system instead parses and stores such FXEPRMxx statements at start time and will apply them when you call service FXECNTRL REQUEST=APPLYIPLPARM (once, for each new, to-be-registered product area). For more information on service FXECNTRL REQUEST=APPLYIPLPARM, see z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG.

You can optionally define self-describing attributes in the IBM Function Registry for z/OS data structures (vendor, product, and function areas). These attributes allow a reporting tool to interpret and report on a wide variety of vendor, product, or function specific attributes without IBM or vendors having to maintain and publish mapping macros and other interfaces for these fields. A header at the top of the vendor, product, and function areas reference the self-describing attributes using fields containing counts, offset-to-1st attribute, and length-of-each attribute.

Defining multiple product versions or instances in the product area: Some products allow users to run multiple instances or version levels of the same product on the same system. To define and track these separately in the IBM Function Registry for z/OS, use optional fields in the product area to distinguish different instances or levels of a product, such as product ID and product instance ID. Use a pointer to the next instance to reference multiple product versions or instances.

Figure 1 shows an example of a data structure for a product with only one instance.

Figure 2 shows an example of a data structure for a product with two instances:
Figure 2. Defining multiple product versions in the product area
funkreg2
Updating function entries: Once your code has established a function entry in structure FXEFRPA, you can periodically update them with usage figures and enablement state. User's might later retrieve this data and analyze it. You can update function entries in FXEFRPA in one of the following ways:
  • Use the FXECNTRL macro to update function entry fields, such as the "used" flag. Any authorized or unauthorized callers can use FXECNTRL, but unauthorized callers can only update function entries using the macro service. Note also that there might be two sets of function entries in a product area - one set of function entries that only authorized code is allowed to update, and another that both unauthorized and authorized code are allowed to update.
  • Write your own authorized code to modify the function entries in common storage directly.

No serialization is required to read the data in the function structures.