IOSFBA — IOS fixed block architecture service

Description

IOSFBA is used to manage (allocate and unallocate) and perform I/O (read and write) to allocated fixed block architecture (FBA) devices. IOSFBA has the following functions:

ALLOCATE: Allocates one or more FBA devices to be used with the READ or WRITE IOSFBA service.
QUERY: Provides information about the requested devices. The caller provides a list of device numbers for which the service returns device attributes.
READ: Initiates read operations for one or more devices as described in the supplied device I/O list.
WRITE: Initiates write operations for one or more devices as described in the supplied device I/O list.
ERASE: Initiates erase operations for a contiguous area for one or more devices as described in the supplied device I/O list.
CLEANUP: Cleans up resources associated with an I/O token.
UNALLOCATE: Unallocates one or more FBA devices that were previously allocated with this service.

Note: Mapping macros for the IOS fixed block architecture services are contained in IOSDFBA.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state, PSW Key 0.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts.
Locks:	No locks may be held.
Control parameters:

Programming requirements

None.

Restrictions

The invoker must have SAF authorization to facility 'IOSFBA'. Specifically, the invoker must have UPDATE authority to facility class 'IOSFBA'.

Input register information

Before issuing the IOSFBA macro, the caller must ensure that general register 13 contains the address of a 72 byte save area (for AMODE(31) callers) or 216 byte save area (for AMODE(64) callers). The save area must be in primary storage in the first 2GB of storage. The caller does not have to place any information into any other general purpose register (GPR) unless using it in register notation for a particular parameter or using it as a base register.

Output register information

The contents of registers 14 through 1 are altered during processing.

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason code
1: Unpredictable (Used as a work register by the system)
2-13: Unchanged
14: Unpredictable (Used as a work register by the system)
15: Return code

Performance implications

None.

Syntax

The IOSFBA macro is written as follows:


main diagram

>>-+------+--␢--IOSFBA--␢--------------------------------------->
   '-name-'                 

>--+-ALLOCATE--| parameters-1 |--------------------------------------------------------+-->
   +-QUERY--+-,--DEVLISTPTR--=--devlistptr-----+--+-,--DEVDESCPTR--=--devdescptr-----+-+   
   |        '-,--DEVLISTPTR64--=--devlistptr64-'  '-,--DEVDESCPTR64--=--devdescptr64-' |   
   +-READ--| parameters-2 |------------------------------------------------------------+   
   +-WRITE--| parameters-3 |-----------------------------------------------------------+   
   +-ERASE--+-,--DEVDESCPTR--=--devdescptr-----+---------------------------------------+   
   |        '-,--DEVDESCPTR64--=--devdescptr64-'                                       |   
   +-CLEANUP--,--IOTOKEN--=--iotoken---------------------------------------------------+   
   '-UNALLOCATE--+-,--DEVDESCPTR--=--devdescptr-----+----------------------------------'   
                 '-,--DEVDESCPTR64--=--devdescptr64-'                                      

>--+------------------------+--+------------------------+------->
   '-,--RETCODE--=--retcode-'  '-,--RSNCODE--=--rsncode-'   

   .-,--PLISTVER--=--IMPLIED_VERSION-.   
>--+---------------------------------+-------------------------->
   +-,--PLISTVER--=--MAX-------------+   
   '-,--PLISTVER--=--1---------------'   

   .-,--MF--=--S--------------------------------------.   
>--+--------------------------------------------------+--------><
   |                               .-,--0D---.        |   
   +-,--MF--=--(--L--,--list addr--+---------+--)-----+   
   |                               '-,--attr-'        |   
   |                               .-,--COMPLETE-.    |   
   '-,--MF--=--(--E--,--list addr--+-------------+--)-'   
                                   '-,--NOCHECK--'


parameters-1

   .-,--ACCESS--=--SINGLE-.   
>>-+----------------------+------------------------------------->
   +-,--ACCESS--=--READ---+   
   +-,--ACCESS--=--WRITE--+   
   '-,--ACCESS--=--ANY----'   

>--+-,--DEVLISTPTR--=--devlistptr-----+------------------------->
   '-,--DEVLISTPTR64--=--devlistptr64-'   

>--+-,--DEVDESCPTR--=--devdescptr-----+------------------------->
   '-,--DEVDESCPTR64--=--devdescptr64-'   

   .-,--DEVCOUNT--=--1--------------------------------------------.   
>--+--------------------------------------------------------------+-><
   |                           .-,--MINDEVCOUNT--=--0-----------. |   
   '-,--DEVCOUNT--=--devcount--+--------------------------------+-'   
                               '-,--MINDEVCOUNT--=--mindevcount-'


parameters-2

>>-+-,--DEVIOLISTPTR--=--deviolistptr-----+--------------------->
   '-,--DEVIOLISTPTR64--=--deviolistptr64-'   

   .-,--ECB--=--NONE-.                    
>--+-----------------+--+-------------+------------------------->
   '-,--ECB--=--ecb--'  '-,--RESERVED-'   

>--+----------------------------------------------------+------><
   |                             .-,--REUSECP--=--NO--. |   
   '-+-,--IOTOKEN--=--NONE----+--+--------------------+-'   
     '-,--IOTOKEN--=--iotoken-'  '-,--REUSECP--=--YES-'


parameters-3

>>-+-,--DEVIOLISTPTR--=--deviolistptr-----+--------------------->
   '-,--DEVIOLISTPTR64--=--deviolistptr64-'   

   .-,--ECB--=--NONE-.                    
>--+-----------------+--+-------------+------------------------->
   '-,--ECB--=--ecb--'  '-,--RESERVED-'   

>--+----------------------------------------------------+------><
   |                             .-,--REUSECP--=--NO--. |   
   '-+-,--IOTOKEN--=--NONE----+--+--------------------+-'   
     '-,--IOTOKEN--=--iotoken-'  '-,--REUSECP--=--YES-'

Parameters

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the IOSFBA macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

,ACCESS=SINGLE

,ACCESS=READ

,ACCESS=WRITE

,ACCESS=ANY

When ALLOCATE is specified, ACCESS is an optional parameter that indicates the type of allocation that should be performed. The default is ACCESS=SINGLE.

,ACCESS=SINGLE: The FBA device is allocated for use by a single z/OS system. Note that one or more distributed systems can access this device in addition to the single z/OS system. Access from distributed systems is controlled through the use of LUN masking or using the persistent reserve from the distributed side.
,ACCESS=READ: The FBA device is allocated for READ only on the system where this request is received. This device can also be allocated on another z/OS system by requesting ACCESS=WRITE. Note that one or more distributed systems can access this device in addition to the pair of z/OS systems that performed the z/OS allocations. Access from distributed systems is controlled through the use of LUN masking or using the persistent reserve from the distributed side.
,ACCESS=WRITE: The FBA device is allocated for WRITE only on the system where this request is received. This device can also be allocated on another z/OS system by requesting ACCESS=READ. Note that one or more distributed systems can access this device in addition to the pair of z/OS systems that performed the z/OS allocations. Access from distributed systems is controlled through the use of LUN masking or using the persistent reserve from the distributed side.
,ACCESS=ANY: The FBA device is allocated once on each z/OS system. Note that one or more distributed systems can access this device in addition to the z/OS systems that performed the z/OS allocations. Access from distributed systems is controlled through the use of LUN masking or using the persistent reserve from the distributed side.

ALLOCATE

A required input parameter that allocates the devices as specified in the device list (FBADL DSECT in the IOSDFBA macro). This request, if successful, allocates the requested number of devices within a sysplex for the caller's use.

To code: Specify a value.

,CLEANUP

A required input parameter that cleans up resources for the input IOTOKEN. During IOSFBA READ or IOSFBA WRITE invocations, one or more IOTOKEN areas may have been used to allow for efficiency. IOSFBA CLEANUP must be invoked once for each IOTOKEN that was used during processing.

To code: Specify a value.

,DEVCOUNT=devcount

,DEVCOUNT=1

When ALLOCATE is specified, DEVCOUNT is an optional input parameter that contains the number of devices that should be allocated from the devices specified in the device list (FBADL) addressed by the DEVLISTPTR or DEVLISTPTR64 parameter. DEVCOUNT indicates the maximum number of devices to allocate. DEVCOUNT should be less than or equal to the number of devices specified in the device list. The default is 1.

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

,DEVDESCPTR=devdescptr

When ALLOCATE is specified, DEVDESCPTR is a required output parameter of the output device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro).

The device descriptor area contains the addresses of a device descriptor entry for each device successfully allocated. The device descriptor entry contains specific device information discovered by the ALLOCATE service. The device descriptor entry is mapped by the FBADDE (defined in the IOSDFBA macro). The device descriptor entry is required input for the IOSFBA READ and IOSFBA WRITE services.

When using the IOSFBA READ or IOSFBA WRITE services, the device descriptor entry is required input for each device that is read from or written to. Refer to the DEVIOLISTPTR or DEVIOLISTPTR64 parameter for the IOSFBA READ and/or IOSFBA WRITE service for more information.

The device descriptor address is an input parameter for the IOSFBA UNALLOCATE service. The UNALLOCATE service unallocates the devices contained in the device descriptor area.

The caller is responsible for freeing or releasing this storage after the devices have been UNALLOCATED. The subpool and length of the storage are contained in the device descriptor area. The device descriptor area must be freed using either STORAGE RELEASE or FREEMAIN macro invocation.

Note: The DEVDESCPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVDESCPTR=devdescptr

When QUERY is specified, DEVDESCPTR is a required output parameter of the output device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro).

The device descriptor area contains the addresses of a device descriptor entry for each device successfully queried. The device descriptor entry contains specific device information discovered by the QUERY service. The device descriptor entry is mapped by the FBADDE (defined in the IOSDFBA macro).

The caller is responsible for freeing or releasing this storage after the devices have been queried. The subpool and length of the storage are contained in the device descriptor area. The device descriptor area must be freed using either STORAGE RELEASE or FREEMAIN macro invocation.

Note: The DEVDESCPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVDESCPTR=devdescptr

When ERASE is specified, DEVDESCPTR is a required input parameter of the input device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro). The device descriptor area is obtained by the IOSFBA ALLOCATE service.

The device descriptor area contains the addresses of the device descriptor entry for each device to be unallocated. The device descriptor entry contains specific device information discovered by the ALLOCATE service. The device descriptor entry is mapped by the FBADDE (defined in the IOSDFBA macro).

The status of the erase request for each device is obtained by checking the FBADDL_EraseFailed and FBADDL_NoEraseAttempted indicators in the FBADDL for each device. If FBADDL_EraseFailed is indicated, the FBADDE_COD and FBADDE_RCOD fields contain information about the I/O failure.

Note: The DEVDESCPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVDESCPTR=devdescptr

When UNALLOCATE is specified, DEVDESCPTR is a required input parameter of the input device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro). The device descriptor area is obtained by the IOSFBA ALLOCATE service.

The UNALLOCATE service unallocates the devices contained in the device descriptor area, specifically each of the device descriptor entries.

The status of the unallocation request for each device is obtained by checking the return code and reason code contained in the device descriptor entry (FBADDE). The return code and reason code contain the dynamic allocation (SVC 99) return and reason code or an IOSFBA service return and reason code.

Note: The DEVDESCPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVDESCPTR64=devdescptr64

When ALLOCATE is specified, DEVDESCPTR64 is a required output parameter of the output device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro).

The device descriptor area contains the addresses of a device descriptor entry for each device successfully allocated. The device descriptor entry contains specific device information discovered during by the ALLOCATE service. The device descriptor entry is mapped by the FBADDE (defined in the IOSDFBA macro). The device descriptor entry is required input for the IOSFBA READ and IOSFBA WRITE services.

When using the IOSFBA READ or IOSFBA WRITE services, the device descriptor entry is required input for each device that is read from or written to. Refer to the DEVIOLIST parameter for the IOSFBA READ and/or IOSFBA WRITE service for more information.

The device descriptor address is an input parameter for the IOSFBA UNALLOCATE service. The UNALLOCATE service unallocates the devices contained in the device descriptor area.

The caller is responsible for freeing or releasing this storage after the devices have been UNALLOCATED. The storage area must be freed using the IARST64 service.

Note: The DEVDESCPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,DEVDESCPTR64=devdescptr64

When QUERY is specified, DEVDESCPTR64 is a required output parameter of the output device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro).

Note: The DEVDESCPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,DEVDESCPTR64=devdescptr64

When ERASE is specified, DEVDESCPTR64 is a required input parameter of the input device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro). The device descriptor area is obtained by the IOSFBA ALLOCATE service.

The UNALLOCATE service unallocates the devices contained in the device descriptor area, specifically each of the device descriptor entries.

Note: The DEVDESCPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,DEVDESCPTR64=devdescptr64

When UNALLOCATE is specified, DEVDESCPTR64 is a required input parameter of the input device descriptor area mapped by the FBADDL (defined in the IOSDFBA macro). The device descriptor area is obtained by the IOSFBA ALLOCATE service.

The UNALLOCATE service unallocates the devices contained in the device descriptor area - specifically each of the device descriptor entry.

The caller is responsible for freeing or releasing this storage after the devices have been UNALLOCATED. The device descriptor area must be freed using the IARST64 service.

Note: The DEVDESCPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,DEVIOLISTPTR=deviolistptr

When READ is specified, DEVIOLISTPTR is a required input parameter of the input device I/O list mapped by the FBADIOL (defined in the IOSDFBA macro). The device I/O list specifies the number of devices that will participate in the IOSFBA READ service. Additionally, the device I/O list contains a pointer to the device I/O entry for each device (mapped by the FBADIOE, defined in the IOSDFBA macro).

The device I/O entry includes the address of the device descriptor entry (that was returned as part of the device descriptor area by the IOSFBA ALLOCATE service), a count of extent entries, the addresses of each extent entry (mapped by the FBAEE, defined in the IOSDFBA macro), and if required by the caller, the address of a status block or area (mapped by the FBAST, defined in the IOSDFBA macro). For a complete description, see the IOSDFBA macro.

The extent entry defines the parameters of the READ I/O operation for a given device. It defines the starting block number on the device, the number of blocks to transfer, and the storage address or addresses to place the information read from the FBA device.

The status block provides the caller with status information for the I/O to each device. A status block should be obtained and initialized to zeroes by the caller for each device that will participate in the IOSFBA READ service.

For AMODE(31) callers, the storage area must be addressable in AMODE(31).

Note: The DEVIOLISTPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVIOLISTPTR=deviolistptr

When WRITE is specified, DEVIOLISTPTR is a required input parameter of the input device I/O list mapped by the FBADIOL (defined in the IOSDFBA macro). The device I/O list specifies the number of devices that will participate in the IOSFBA READ service. Additionally, the device I/O list contains a device I/O entry for each device (mapped by the FBADIOE, defined in the IOSDFBA macro).

The extent entry defines the parameters of the WRITE I/O operation for a given device. It defines the starting block number on the device, the number of blocks to transfer, and the storage address or addresses to place the information read from the FBA device.

For AMODE(31) callers, the storage area must be addressable in AMODE(31).

Note: The DEVIOLISTPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVIOLISTPTR64=deviolistptr64

When READ is specified, DEVIOLISTPTR64 is a required input parameter of the input device I/O list mapped by the FBADIOL (defined in the IOSDFBA macro). The device I/O list specifies the number of devices that will participate in the IOSFBA READ service. Additionally, the device I/O list contains a device I/O entry for each device (mapped by the FBADIOE, defined in the IOSDFBA macro).

Note: The DEVIOLISTPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,DEVIOLISTPTR64=deviolistptr64

When WRITE is specified, DEVIOLISTPTR64 is a required input parameter of the input device I/O list mapped by the FBADIOL (defined in the IOSDFBA macro). The device I/O list specifies the number of devices that will participate in the IOSFBA READ service. Additionally, the device I/O list contains a device I/O entry for each device (mapped by the FBADIOE, defined in the IOSDFBA macro).

Note: The DEVIOLISTPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,DEVLISTPTR=devlistptr

When ALLOCATE is specified, DEVLISTPTR is a required input parameter of the input device list mapped by the FBADL (defined in the IOSDFBA macro). The FBADL specifies the number of devices, the device numbers, and others to allocate. (Refer to the FBADL for specific information.)

For AMODE(31) callers, the storage area must be addressable in AMODE(31).

Note: The DEVLISPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVLISTPTR=devlistptr

When QUERY is specified, DEVLISTPTR is a required input parameter of the input device list mapped by the FBADL (defined in the IOSDFBA macro). The FBADL specifies the number of devices, the device numbers, and others to allocate. (Refer to the FBADL for specific information.)

For AMODE(31) callers, the storage area must be addressable in AMODE(31).

Note: The DEVLISPTR parameter is allowed only when not in AMODE 64 as indicated by the SYSSTATE macro.

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

,DEVLISTPTR64=devlistptr64

When ALLOCATE is specified, DEVLISTPTR64 is a required input parameter of the input device list mapped by the FBADL (defined in the IOSDFBA macro). The FBADL specifies the number of devices, the device numbers, and others to allocate. (Refer to the FBADL for specific information.)

Note: The DEVLISTPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,DEVLISTPTR64=devlistptr64

When QUERY is specified, DEVLISTPTR64 is a required input parameter of the input device list mapped by the FBADL (defined in the IOSDFBA macro). The FBADL specifies the number of devices, the device numbers, and others to allocate. (Refer to the FBADL for specific information.)

Note: The DEVLISTPTR64 parameter is allowed only when in AMODE 64 as indicated by the SYSSTATE macro.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,ECB=ecb

,ECB=NONE

When READ is specified, ECB is an optional input parameter that contains the address that points to an optional ECB that is posted when all read operations are complete. If an ECB is not specified, control returns to the invoker when all read operations have completed. The default is NONE.

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

,ECB=ecb

,ECB=NONE

When WRITE is specified, ECB is an optional input parameter that contains the address that points to an optional ECB that is posted when all write operations are complete. If an ECB is not specified, control returns to the invoker when all write operations have completed. The default is NONE.

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

,ERASE

A required input parameter that erases a contiguous area of the device or devices as specified in the device list mapped by the FBADL DSECT (defined in the IOSDFBA macro). Erase writes null characters (X'00').

To code: Specify a value.

,IOTOKEN=iotoken

,IOTOKEN=NONE

When READ is specified, IOTOKEN is an optional input parameter that contains the address that points to an optional 32-byte area used by the IOSFBA service to store addresses and lengths of storage areas that can be reused in order to avoid system overhead of obtaining these resources on each call.

The invokers of IOSFBA can use as many unique 32-byte IOTOKEN areas as desired. When IOTOKEN is used,

The area specified by the IOTOKEN should be initially cleared by the calling program before the first usage of the IOTOKEN area.
Each IOTOKEN is used to represent storage areas for the life of an I/O request. The caller should not reuse an IOTOKEN until the I/Os initiated for it have completed. For synchronous callers, the IOTOKEN can be immediately reused. For asynchronous callers (when an ECB is provided), the caller must not reuse an IOTOKEN until the ECB has been posted.
IOSFBA CLEANUP must be invoked for each IOTOKEN that was used to ensure that task related storage is released.

The default is NONE.

To code: Specify the RS-type address of a pointer field.

,IOTOKEN=iotoken

,IOTOKEN=NONE

When WRITE is specified, IOTOKEN is an optional input parameter that contains the address that points to an optional 32-byte area that is used by the IOSFBA service to store addresses and lengths of storage areas that can be reused in order to avoid system overhead of obtaining these resources on each call.

The invokers of IOSFBA can use as many unique 32-byte IOTOKEN areas as desired. When IOTOKEN is used,

The area specified by the IOTOKEN should be initially cleared by the calling program before the first usage of the IOTOKEN area.
Each IOTOKEN is used to represent storage areas for the life of an I/O request. The caller should not reuse an IOTOKEN until the I/Os initiated for it have completed. For synchronous callers, the IOTOKEN can be immediately reused. For asynchronous callers (when an ECB is provided), the caller must not reuse an IOTOKEN until the ECB has been posted.
IOSFBA CLEANUP must be invoked for each IOTOKEN that was used to ensure that task related storage is released.

The default is NONE.

To code: Specify the RS-type address of a pointer field.

,IOTOKEN=iotoken

When CLEANUP is specified, IOTOKEN is a required input parameter that contains the address that points to a 32-byte area that is used by the IOSFBA service to store addresses and lengths of storage areas that can be reused in order to avoid system overhead of obtaining these resources on each call.

To code: Specify the RS-type address of a pointer field.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,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.

,list addr: The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this is an RS-type address or an address in register (1)-(12).
,attr: An optional 1 to 60 character input string used 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.

,MINDEVCOUNT=mindevcount

,MINDEVCOUNT=0

When ALLOCATE is specified, MINDEVCOUNT is an optional input parameter that indicates the minimum number of devices that must be allocated to fulfill this allocate request. The devices are specified in the device list (FBADL) addressed by the DEVLISTPTR or DEVLISTPTR64 parameter. This number should be less than or equal to the number specified in DEVCOUNT.

If the caller requests DEVCOUNT=x and MINDEVCOUNT=y, the IOSFBA service attempts to allocate the requested number of devices (as specified by the DEVCOUNT=x parameter). If 'x' devices are not available to be allocated, IOSFBA ALLOCATE service attempts to allocate as many devices that are available. The ALLOCATE request is considered successful if at least 'y' devices are allocated (as specified by the MINDEVCOUNT=y parameter). The ALLOCATE request is considered unsuccessful if 'y' devices (as specified by the MINDEVCOUNT=y parameter) are not allocated and a return code is set indicating the ALLOCATE request failed since the minimum number of devices could not be allocated.

The count or number of devices that have been allocated is contained in the device descriptor area (mapped by the FBADDL).

If this keyword is omitted or specified as 0, the MINDEVCOUNT is assumed to be the value specified on the DEVCOUNT keyword. The default is 0.

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

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

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, 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, if you want the parameter list 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, 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, if you use the currently available parameters.

To code: Specify one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1

,QUERY

A required input parameter, queries information about a list of devices. Information is returned for each device in the list of devices identified in the DEVLIST keyword.

To code: Specify a value.

,READ

A required input parameter, reads information from one or more FBA devices as specified by the device I/O list (DEVIOLIST parameter).

To code: Specify a value.

,RESERVED

When READ is specified, RESERVED is an optional input parameter indicating that the device or devices for this READ operation may be serialized by persistent reserve from a distributed client. When this keyword is specified, z/OS I/O operations are permitted to the devices while the persistent reserve is held. This keyword should only be used when the invoking program is coordinating I/O activity between z/OS and the distributed client that owns the persistent reserve. The default is NONE.

To code: Specify a value.

,RESERVED

When WRITE is specified, RESERVED is an optional input parameter that indicates that the device or devices for this WRITE operation may be serialized by persistent reserve from a distributed client. When this keyword is specified, z/OS I/O operations are permitted to the devices while the persistent reserve is held. This keyword should only be used when the invoking program is coordinating I/O activity between z/OS and the distributed client that owns the persistent reserve. The default is NONE.

To code: Specify a value.

,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 is 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).

,REUSECP=NO

,REUSECP=YES

When IOTOKEN=iotoken and READ are specified, REUSECP is an optional parameter indicating that the channel program for this operation is exactly the same as the previous channel program. On the first READ request, this keyword is ignored. On subsequent requests, this keyword indicates whether the exact same storage buffers and blocks on the disks are involved in the I/O operations. The exact same channel program is used to perform the I/O. Using this REUSECP=YES may provide some performance advantage since analyzing the extents and storage buffers is not required. The default is REUSECP=NO.

,REUSECP=NO

Indicates that the channel program may vary from invocation to invocation and should be rebuilt on each IOSFBA request.

,REUSECP=YES

Indicates that the channel program does not vary from invocation to invocation and that IOSFBA is instructed to start the previously built channel program without modification if one has been previously built. If no prior channel program was executed for the input IOTOKEN, a new one is built and saved for the next invocation. When REUSECP=YES is specified,

You must use storage that is fixed for life of the IOTOKEN. Channel programs are not rebuilt to obtain the latest real storage address.
You must make the address space non-swappable for the life of the IOTOKEN.

If either of these conditions cannot be met, you must not use REUSECP=YES.

,REUSECP=NO

,REUSECP=YES

When IOTOKEN=iotoken and WRITE are specified, REUSECP is an optional parameter that indicates that the channel program for this operation is exactly the same as the previous channel program. On the first WRITE request, this keyword is ignored. On subsequent requests, this keyword indicates whether the exact same storage buffers and blocks on the disks are involved in the I/O operations. The exact same channel program is used to perform the I/O. Using this REUSECP=YES may provide some performance advantage since analyzing the extents and storage buffers is not required. The default is REUSECP=NO.

,REUSECP=NO

Indicates that the channel program may vary from invocation to invocation and should be rebuilt on each IOSFBA request.

,REUSECP=YES

You must use storage that is fixed for life of the IOTOKEN. Channel programs are not rebuilt to obtain the latest real storage address.
You must make the address space non-swappable for the life of the IOTOKEN.

If either of these conditions cannot be met, you must not use REUSECP=YES.

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value is left in GPR 0.

To code: Specify the RS-type address of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,UNALLOCATE

A required input parameter that unallocates the devices as specified in the device list mapped by the FBADL DSECT (defined in the IOSDFBA macro).

To code: Specify a value.

,WRITE

A required input parameter that writes information to one or more FBA devices as specified by the device I/O list (DEVIOLIST parameter).

To code: Specify a value.

ABEND codes

None.

Return and reason codes

When the IOSFBA macro returns control to your program:

GPR 15 (and retcode, when you code RETCODE) contains a return code.
When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code RSNCODE) contains a reason code.

The following table identifies the hexadecimal return and reason codes:

Table 1. Return and Reason Codes for the IOSFBA Macro
Return Code	Meaning and Action
X'00'	Successful operation. Reason Code Meaning/Action X'00' The operation was successful. X'01' (ALLOCATE) The requested number of devices (DEVCOUNT) were not available. However, FBADDL_COUNT contains the number of devices actually allocated for this request, which is greater than or equal to the minimum number of devices required (MINDEVCOUNT).
X'04'	Warning error. Reason Code Meaning/Action X'01' (QUERY) Information for one or more devices could not be obtained. X'02' (UNALLOCATE) One or more devices in the DEVLIST could not be unallocated.
X'08'	Error in the caller's parameters. Reason Code Meaning/Action X'01' IOSFBA abended during parameter validation. X'02' (ALLOCATE) MINDEVCOUNT is greater than DEVCOUNT. X'03' (ALLOCATE, QUERY) The device list is not properly built. X'04' (READ, WRITE) The number of blocks identified in the READ or WRITE request does not properly equate with the amount of I/O buffers provided. X'05' (READ, WRITE) The requested extents to be READ or WRITTEN are not within the acceptable range of extents available on the device. X'06' An invalid function was specified for the IOSFBA invocation. X'07' (UNALLOCATE, ERASE) The device descriptor list is not properly built. X'08' (UNALLOCATE, READ, WRITE, ERASE) The device descriptor entry is not properly built. X'09' (UNALLOCATE, READ, WRITE, ERASE) The UCB specified in the device descriptor entry is not allocated. X'0B' (READ, WRITE) The buffers specified are not properly sized with the physical block size of the device. Buffer sizes must be multiples of the physical block size of the device. X'0C' (READ, WRITE) The device I/O list is not properly built. X'0D' (READ, WRITE) The device I/O entry is not properly built. X'0E' (READ, WRITE) The extent entry is not properly built. X'0F' (READ, WRITE) REUSECP=YES was specified, but the address space is swappable. The address space must be non-swappable when REUSEP=YES is specified.
X'0C'	Environmental error. Reason Code Meaning/Action X'01' (ALLOCATE) Not enough devices were available to satisfy the requested allocation. Devices must be online, usable, and not already allocated in order to be allocated by this service. X'02' (ALLOCATE) Not enough devices provided I/O responses that enabled IOSFBA to validate that they were usable, so IOSFBA was not able to satisfy the requested allocation. Devices must be online, usable, not already allocated, and must properly respond to I/O commands that query device information in order to be allocated by this service. X'03' (ALLOCATE, READ, WRITE) IOSFBA detected a serialization problem with one of the devices being allocated. A SYMREC record was written. Consider varying the device offline and investigate prior device usage before attempting to use the identified device again. X'04' IOSFBA service is not available. X'05' IOSFBA detected that the caller is not in task mode. IOSFBA must be invoked in task mode. X'06' IOSFBA detected that the caller is not enabled for I/O interrupts.
X'10'	The READ or WRITE operation was not successful. Check the status blocks for information on the failed I/Os. Note that this return code is only valid for synchronous READ and WRITE operations. Asynchronous READ and WRITE operations are notified by a post code of X'10'.
X'14'	The invoker is not authorized to use this programming service. Reason Code Meaning/Action X'01' The invoker must be in PSW key 0-7 and in supervisor state.