Implementing an CA-Earl File Exit. A how to instruction set and sample.
Article ID: 11547
Updated On:
Products
Issue/Introduction
To learn more about the file exit, please refer to the CA-Earl User Guide and the CA-Earl Reference Guide.
Implementing an CA-Earl File Exit. A how to instruction set and sample.
Environment
Component:
Resolution
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
| Filename | This 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. |
| Modulename | This is the name of the user module as it has been saved in the operating system library for execution. |
| Length | This 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=lrecl | This 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:
| Hexadecimal | COBOL Equivalent | Type of Condition |
| X'FFFFFFFF' | Numeric value of -1 or HIGH-VALUES | End of File |
| X'FFFFFFFE' | Numeric value of -2 | No record Found |
| X'00000000' | Numeric value of 0 or LOW-VALUES | Abort 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.
Feedback
