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.
- 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.
- If you are using the IBM Function Registry for z/OS to find functions, get information about functions, or enable and disable functions, see Using the IBM Function Registry for z/OS.
- If you want to register your function with the IBM Function Registry for z/OS, see Registering functions in the IBM Function Registry for z/OS.
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.
- 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:
- 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
- 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.
- 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).
- 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.
- 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.