Querying and allocating FBA devices

Querying FBA devices

The QUERY function lets the caller gather physical and self-describing information on the specified devices and an indication if the FBA device is allocated. The caller must provide a list of devices to query.

The information returned includes the starting block and number of blocks available for each device, the physical record size (size of each block), and the I/O Node Element Descriptor (I/O NED).

Using IOSFBA QUERY to gather information on z/OS FBA devices

First, a program must know what devices are defined for its use. Typically, this would be done using either parameters or an initialization file. The program could also perform a UCBSCAN with DEVCLASS=UREC looking for devices with UCBTBYT4=X’60’. Using an initialization file or parameters is the preferred method because many software products may be using z/OS FBA devices on a single system.

Once devices to be used are known, the program would build a list of devices (mapped by the FBADL DSECT in the IOSDFBA macro) and invoke the IOSFBA QUERY function.

If successful, IOSFBA QUERY returns a device descriptor list (mapped by the FBADDL DSECT in the IOSDFBA macro) and one or more FBADDE structures describing the devices.

The storage containing the FBADDL structure must be freed by the caller when the information is no longer required. The length field in the FBADDL header is the total length of storage, including storage for the FBADDE structures.

For input and output to the IOSFBA QUERY service, see Figure 1 .

Figure 1. Visual representation of IOSFBA query

Allocating FBA devices

An FBA device must be online and allocated prior to it being used to read, write, or erase data from the device.

As with the QUERY function, ALLOCATE requires a list of devices that are to be allocated. The function dynamically allocates (SVC99) the device and provide the same information that the QUERY function provides.

The information returned after the IOSFBA ALLOCATE service is issued contains the same information returned from the IOSFBA QUERY service (the starting block and number of blocks available for each device, the physical record size (size of each block), and the I/O Node Element Descriptor (I/O NED)), plus additional information specific to the IOSFBA ALLOCATE service. This information is used as input for the READ, WRITE and UNALLOCATE functions.

For input and output to the IOSFBA ALLOCATE service, see Figure 2.

Figure 2. Visual representation of IOSFBA allocation

How the device is to be used dictates how it should be allocated. The ALLOCATE function provides the following access types for allocating a z/OS FBA device:

Specifying ACCESS=SINGLE limits the usage of the device to a single z/OS system within the SYSPLEX.
Specifying ACCESS=READ or ACCESS=WRITE allows the usage of the device to two z/OS systems within the SYSPLEX (one as READ and the other as WRITE).
Specifying ACCESS=ANY provides the caller control of how the device is serialized on the z/OS systems within the SYSPLEX.

For all access types, distributed systems can still share the device; that is, the distributed system can read from or write to the device.

Note that with ACCESS=SINGLE, ACCESS=READ, or ACCESS=WRITE, a small amount of metadata is written to the device. Ensure that important data that may reside on the disk is not erased by the IOSFBA service. If data exists on the z/OS FBA disk, using ACCESS=ANY ensures that the IOSFBA does not alter that pre-existing data.

When selecting the method of allocation by the calling programs, the pool of devices used for ACCESS=ANY should not be mixed with the pool of devices used for ACCESS=SINGLE, ACCESS=READ, or ACCESS=WRITE allocations. This avoids duplicate allocations from different systems within a sysplex because ACCESS=ANY does not use metadata to control device allocations

Using the IOSFBA ALLOCATE function to allocate z/OS FBA devices

A program must know what devices are defined for its use. Typically, this is done using either parameters or an initialization file. The program can also perform a UCBSCAN with DEVCLASS=UREC looking for devices with UCBTBYT4=X’60’. Using an initialization file or parameters is the preferred method because many software products may be using z/OS FBA devices on a single system.

Once devices to be used are known, the program builds a list of devices (mapped by the FBADL DSECT in the IOSDFBA macro) and invokes the IOSFBA ALLOCATE function.

If successful, IOSFBA ALLOCATE returns a device descriptor list (mapped by the FBADDL DSECT in the IOSDFBA macro) and one or more FBADDE structures describing the devices that were allocated. The FBADDL is required input for the IOSFBA UNALLOCATE service.

The storage containing the FBADDL structure must eventually be freed by the caller when the information is no longer required. This should be done by the calling program after calling the IOSFBA UNALLOCATE service. The length field in the FBADDL header is the total length of storage, including storage for the FBADDE structures.

Identifying FBA devices with distributed SCSI logical unit numbers (LUNs) and other z/OS systems

Part of the information returned by both IOSFBA QUERY and IOSFBA ALLOCATE is an I/O Node Element Descriptor (NED). The I/O NED is 32 bytes long. It uniquely identifies the FBA device and contains:

The device manufacturer
The plant where the device was built
The model number
The sequence number
The logical subsystem
The unit address

For distributed environments, this information can be obtained by issuing a standard SCSI inquiry command. Remember that the information returned in a z/OS environment is in EBCDIC format, while distributed environments return the information in ASCII format.

Reconciling the information from both sources helps the peer programs ensure that the correct device is being used.

Reconciling information from both sources to help the peer programs ensure that the correct device is being used

Input to QUERY and ALLOCATE

The QUERY and ALLOCATE functions require the caller to pass the address of an FBA device list, which is mapped by the FBADL (found in the IOSDFBA mapping macro). The FBADL consists of two structures; the first can be referred as the header (FBADL) and the second can be referred to as the device entry (FBADL_DEVICE_ENTRY). The FBADL header indicates the length of each entry, the total length (header and entries), and the number of device entries. For each device to be queried or allocated, a device entry must exist.

Figure 3. FBADL with three device entries

Output from QUERY and ALLOCATE

The output from either the IOSFBA QUERY or IOSFBA ALLOCATE request is an address of a storage area obtained by the IOSFBA service that maps the FBA device descriptor list (FBADDL) and the FBA device descriptor entry (FBADDE). The FBADDL and FBADDE provide detailed information about each FBA device that was either queried or allocated. This information is required input for READ, WRITE, and UNALLOCATE options. The caller or invoker is responsible for releasing the storage through either a STORAGE RELEASE invocation for callers in AMODE 31 or an IARST64 invocation for callers in AMODE 64.

Figure 4. Mapping of output area from IOSFBA QUERY and IOSFBA ALLOCATE

The FBADDE structures is pointed to by the FBADIOE structures created to read or write to the z/OS FBA devices.