Implementing an CA-Earl File Exit. A how to instruction set and sample.

Document ID : KB000011547
Last Modified Date : 14/02/2018
Show Technical Document Details
Introduction:

To learn more about the file exit, please refer to the CA-Earl User Guide and the CA-Earl Reference Guide.

Question:

Implementing an CA-Earl File Exit. A how to instruction set and sample.

Answer:

A file exit is accessed from the processing sections of an CA-Earl program and may perform I/O not handled already by CA-Earl.

Below is an example of an CA-Earl program that utilizes a file exit called MYFILEX:

      OPTION PRINTER=60
      AIRPORTS:FILE MYFILEX 4 'US  ' RECORD=57               
          DEF A_NAME      1-18 X 'NAME OF' 'AIRPORT'         
          DEF A_CITY     20-35 X 'CITY'                      
          DEF A_COUNTRY  40-43 X 'COUNTRY' 'ABBREVIATION'    
          DEF A_PASS     50-57 N 'NUMBER OF' 'PASSENGERS'    
                           PIC 'ZZ,ZZZ,ZZ9'            
      GET AIRPORTS                                           
      GOTO EOJ (AIRPORTS = 'E')                              
      REPORT 'BUSIEST AIRPORTS'                  
      TITLE 'IN THE UNITED STATES'                   
      PRINT A_NAME A_CITY A_COUNTRY A_PASS                   
      END

The File Statement

The file statement tells CA-Earl that a file exit is to be used. The format of the file statement is as follows:

Filename:FILE modulename length 'initial value' RECORD=lrecl

FilenameThis is the name that identifies the file being used within this Advantage CA-Earl program. It is also the name of a 1-byte alphanumeric field that is used to indicate that an End of File condition has occurred.
ModulenameThis is the name of the user module as it has been saved in the operating system library for execution.
LengthThis specifies the length of the communication area, in bytes. The default is 80 and the minimum value is four bytes.
'initial value'This is a string literal that contains the initial value of the communications area. If omitted, a blank area is generated.
RECORD=lreclThis is the record length of the record to be passed from the user module to Advantage CA-Earl. The DEF statements in the Advantage CA-Earl program that follow the FILE statement define the fields returned from the file exit.

In the example above, the user module name or file exit that will be called is MYFILEX:

	AIRPORTS:FILE MYFILEX 4 'US  ' RECORD=57

This file statement informs CA-Earl that the user module MYFILEX will set up a 4-byte communications area with the initial value 'US ' and will pass back a 57-byte long record to the CA-Earl program. A file exit module is LOADed at the start of the CA-Earl program's runtime processing.

The GET Statement

The GET statement causes the file exit program to be invoked. In this example, the GET statement retrieves a record from the AIRPORTS file.

The File Exit Routine

Below is an example of a file exit routine written in Assembler language:

MYFILEX  CSECT                                                  
         STM   R14,R12,12(R13)    Save callers registers       
         LR    R12,R15            Address our entry point          
         USING MYFILEX,R12        Set up addressability            
         LA    R15,SAVEAREA       Point to our save area           
         ST    R15,8(,R13)        and store address in callers     
         ST    R13,4(,R15)        Store address of callers save area    
         LR    R13,R15            Address our save area             
***********************************************************************
* Store the parameter that are passed from Advantage CA-Earl          *
*  Register 4   -  pointer to the record area                         *
*  Register 5   -  pointer to the (80 byte) communication area        *
*  Register 6   -  pointer to the (8 byte) file name                  *
*  Register 7   -  pointer to the operating system communication area *
***********************************************************************
         LM    R4,R7,0(R1)
         CLI   OPENFLG,X'FF'      Test to see if file is already open  
         BE    READREC            If yes, then bypass open                                                       
         OPEN  (INPUT1,(INPUT))   Open Input file
         MVI   OPENFLG,X'FF'      Set open flag on          
READREC  GET   INPUT1,FILE1DS     Read a record
         CLC   0(4,R5),COUNTRY    Does it match the country in commarea
         BNE   READREC            If not get another record
         MVC   0(57,R4),FILE1DS   Move data to the record area
         B     RETURN             Return back to CA-Earl
EOF1     MVC   0(4,R5),=F'-1'     Set EOF flag
         CLOSE INPUT1             Close file    
RETURN   L     R13,4(,R13)        Pick up callers save area address         
         LM    R14,R12,12(R13)    Restore callers registers              
         BR    R14                and return                             
         EJECT                                                           
SAVEAREA DC    20F'0'
OPENFLG  DC    X'00'                                                     
***********************************************************************
*   The DSECT below should match the records layout that is defined   *
*   in the Advantage CA-Earl program that is calling the file exit.   *
***********************************************************************
FILE1DS  DS    0CL57
NAME     DS    CL18
         DS    XL1
CITY     DS    CL16
         DS    XL4
COUNTRY  DS    CL4
         DS    XL6
PASS     DS    XL8
         EJECT                                                           
R0       EQU   0
R1       EQU   1
R2       EQU   2
R3       EQU   3
R4       EQU   4     POINTER TO THE RECORD AREA
R5       EQU   5     POINTER TO THE (80 BYTE) COMMUNICATION AREA
R6       EQU   6     POINTER TO THE (8 BYTE) FILE NAME
R7       EQU   7     POINTER TO THE OPERATING SYSTEM COMMUNICATION AREA
R8       EQU   8
R9       EQU   9
R10      EQU   10
R11      EQU   11
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15
INPUT1   DCB   DDNAME=AIRPORTS,DSORG=PS,MACRF=(GM),                    X
               EODAD=EOF1
         LTORG                                                           
         END

This file exit reads the AIRPORTS file, using the parameter passed on the FILE statement as the record selection criteria. In our sample file exit program, the parameter value passed ('US ') is matched against the field COUNTRY in each record.

Registers and Return Code

A file exit can be written in any language that observes the standard operating system subroutine linkage conventions, where:

  • Register 1 contains a pointer to a list of parameter pointers upon entry.
    The parameter list contains 4 pointers:
              Pointer to the record area
              Pointer to the (80 byte) communications area
              Pointer to the (8 byte) file name
              Pointer to the operating system communications area.
  • Register 15 contains the entry point of the routine.
  • Register 14 contains the address to which control is to be returned upon exit.

On return, register 15 is ignored by CA-Earl. The file exit communicates with CA-Earl by setting a return code value in the first 4 bytes of the communication area. Below are the return code values that CA-Earl will recognize:

HexadecimalCOBOL Equivalent Type of Condition
X'FFFFFFFF'Numeric value of -1 or HIGH-VALUESEnd of File
X'FFFFFFFE'Numeric value of -2No record Found
X'00000000'Numeric value of 0 or LOW-VALUESAbort the run

When the 'End of File' (X'FFFFFFFF') condition is returned, CA-Earl sets the Filename field named by the FILE statement (in this example, AIRPORTS) to the value 'E'. In our CA-Earl sample program, the End of File condition for the AIRPORTS file is tested by the following statement:

GOTO EOJ (AIRPORTS = 'E')
Additional Information:

To learn more about the file exit, please refer to the CA-Earl User Guide and the CA-Earl Reference Guide.