File-AID/MVS I/O exit

File-AID/MVS and File-AID/Data Solutions can share the same I/O exit, which means an I/O exit created for File-AID/MVS can be used with File-AID/Data Solutions and vice-versa.

The File-AID I/O exit enables you to write a callable routine to perform functions not supported by File-AID such as: encryption, decryption, compression, and decompression. In addition, an I/O exit routine can be written to handle all the I/O for specified files -- including Open and Close.

The two types of I/O exits are type 1 and type 2. A type 1 exit allows record access after File-AID reads from a data set and before File-AID writes to a data set. A type 2 exit allows nonstandard data set access; it performs all I/O processing against the data set. The exit supplies File-AID with a logical record upon request.

BMC provides three sample exits. The sample exit names are XVJTYP1A and XVJTYP2A (for Assembler) and XVJCOB1 (for COBOL). The communications macro for Assembler only is called XVJFAIOU. XVJTYP1A and XVJCOB1 are sample compression and decompression exits. XVJTYP2A is a sample exit for handling all I/O requests.

I/O exit processing can be initiated by entering a module name in the I/O EXIT field on the Browse, Edit, Copy, Search/Update, Print, or Reformat screens or by coding the IOEXIT parameter for File-AID/Batch. File-AID calls the I/O exit at least five times during a File-AID function. I/O Exit Sequence lists the calls in the sequence in which they occur. I/O Exit Function Calls describes the tasks performed by File-AID and the I/O exit for each call.

I/O Exits From Prior File-AID Releases

With the current Release of File-AID, existing exits should be compiled using a vendor supported release of the compiler (or a compiler covered by BMC’s support policy).

What’s Different About Current Release I/O Exits

For current Release I/O exits, use the revised communications area illustrated by sample library (hlq.SXVJSAMP) macro XVJFAIOU. For COBOL, see the linkage section of XVJCOB1. The sample Assembler program XVJCOB1 now uses macro XVJFAIOU to describe the changed area. Previous versions of the sample used macro FASYUSX.

We recommend reviewing the changes in XVJFAIOU. During the verify call, a value should be placed in field USXMREC to indicate the maximum record size that can be returned from your exit. During subsequent calls, any returned records must be moved to the address found in field USXREC@R. The length of returned records must be placed in the field, USXRECLR.

Sample library (hlq.SXVJSAMP) member XVJLKIOA (XVJLKIOC for COBOL) illustrates the special load module requirements for macro XVJFAIOU. Use of the revised area requires that the load module contain two CSECTs. The module must begin with CSECT FSPFIXID and is followed by your routine whose CSECT name must be FAIOXUSR. The load module can have any name except DXPCPXT.

I/O Exit Sequence

1. Verify call: Occurs when the user presses Enter on a primary function panel, but after File-AID identifies and allocates the user-entered data set.
2. Open call: Occurs at data set open.

3. Record Access call: Occurs multiple times as each record is required for read or write. The following five record access calls may occur:

   Add	Insert a record
   Delete	Delete a record
   Update	Update a record
   Read	Read a record
   Write	Write a record.

4. Close call: Occurs at the end of a record access cycle.
5. Term call: Occurs at the end of a function just before a redisplay of the primary function panel.

I/O Exit Function Calls

1. Verify Call.File-AID does the following:

   • Sets the data set name, member name, volume serial, password, and DD name fields in the I/O exit communications area.
   • Calls the I/O exit.

   The I/O exit does the following:

   • Verifies whether or not it should process this data set.
   • Sets the processing type flag indicating that it will process the data set as a type (2) exit, or as a type (1) exit, or that it will ignore (I) this data set (that is, File-AID does not call the exit again for this function).
   • Sets R15 = 0 for a successful call and R15 = nonzero to abort.

   When R15 is nonzero, a message should be set in the communications area. If R15 is nonzero, the File-AID function is terminated, and the user exit is not called again.

   • Indicates the maximum record size that can be returned from the exit to File-AID.

2. Open Call - Type 1 and Type 2 Exits.

   File-AID does the following:

   • Sets the processing mode as random or sequential.
   • Updates the member name in the common area. With PDS processing, an open, record access, and close cycle may occur for each member.
   • Sets key length and relative key position.
   • Sets open type access mode to input, output, or update.
   • Sets the record format, data set organization, and organization type.

   The I/O exit does the following:

   The I/O exit sets R15 = 0 for a successful call and R15 = nonzero to abort. When R15 is nonzero and File-AID aborts the open, the I/O exit still receives close and terminate calls.

   The type 1 I/O exit is called for open processing. After File-AID opens the file, the exit verifies again that it can handle this data set. The exit may set the ignore (I) flag. When the ignore flag is set, File-AID continues to process the data set without calling the I/O exit. If the I/O exit wants to abort the function, then R15 should be nonzero and a message should be set in the communications area.

   The type 1 I/O exit may set the following:

   • Key position relative to zero
   • Key length if applicable
   • Member name if applicable.

   The type 2 I/O exit opens the file and sets the following:

   • Record type to varying or fixed
   • Key length if applicable
   • Member name if applicable
   • Key position relative to zero
   • Data set organization and type.

3. Record Access Call
   Type 1 exits have all I/O performed by File-AID. Type 2 exits must perform all I/O, as required by type of access call.

   Read Record Access Calls:

   File-AID sets the following for a type 1 exit:

   • Address of the record read by File-AID (USXREC@)
   • Record length in the communications area (USXRECL).

   The type 2 I/O exit must perform the I/O to read the record. Type 1 and type 2 I/O exits do the following:

   • Move the record to the address provided by File-AID (USXREC@R).
   • Set the record length in the communications area (USXRECLR).
   • Set R15 = 0 to continue processing.
   • Set R15 = 4 for no record found (type 2 only). Random processing return code. File-AID continues normal processing.
   • Set R15 = 8 for end of data (type 2 only). File-AID terminates record access and continues normal processing.
   • Set R15 = 12 for File-AID to abort function processing. The I/O exit is still called for close and termination. A message should be set in the communications area.

   Write Record Access Calls (Add, Delete, Update, and Write):

   File-AID sets the following for a type 1 exit:

   • Record to be written in the common area (USXREC@)
   • Length of the record in the common area (USXRECL).

   The type 2 I/O exit must perform the requested I/O to write the record to the file.

   The type 1 I/O exit is only called for the write and must:

   • Move the record to be written to the address provided by File-AID (USXREC@R).
   • Set the length of the record to be written (USXRECLR).

   Type 1 and 2 I/O exits set the following:

   1. 
      
      • R15 = 0 to continue processing.
      • R15 = nonzero for File-AID to abort record access processing. The I/O exit still is called for close and termination. A message should be set in the communications area.
4. Close Call - Type 2 Exit Only.
   The exit should close the data set being processed. No message processing is done, and File-AID proceeds to the termination call.

5. Term Call
   Exits should free (FREEMAIN) any temporary storage acquired.

   If R15 is nonzero, File-AID uses the message (if any) in the communications area for the next panel display. The primary function panel is then redisplayed.