Using the INFILE/FILE User Exit Facility

Function Descriptions

The following sections provide the information that you need in order to write the functions that are part of the user exit module.

Initialization Function

SAS calls the Initialization function before it calls any of the other functions. In the Initialization function, you specify the amount of virtual memory that your routine needs above and below the 16-megabyte address line. You store the length of the work area that you need above the line in the fullword that is pointed to by the INITMALN field of the Initialization FRCB. You store the length of the work area that you need below the line in the fullword that is pointed to by the INITMBLN field of the Initialization FRCB. All pointers in the Initialization FRCB point to valid data areas.

In the amount of storage that you request, you should include space for a Local Register Save Area (LRSA) of 72 bytes, plus any other work areas that your Parse Options function and Open function needs.

SAS allocates the memory that you request when it returns from this function, and it stores pointers to the allocated memory in the UEBCB. The pointer to the memory that was allocated above the line is stored in the MEMABV field of the UEBCB. The pointer to the memory that was allocated below the line is stored in the MEMBEL field.

The following figure illustrates the Initialization FRCB structure and its relationship with other control blocks:

Initialization FRCB

[Initialization FRCB]

Parse Options Function

In the Parse Options function, you validate both the name of the user exit and any INFILE or FILE statement options that SAS does not recognize. SAS calls this function once to process the user exit module name. SAS then calls the function for each statement option that it does not recognize so that the function can process each option and value string.

You can use two types of statement options in your user exit:

options that take a value, such as name=value. For example:
```
myopt=ABC
```
Note that quotation marks are considered part of the value; if you want them to be stripped off, you must provide the code to do so.
options that do not take a value.

The first time the Parse Options function is invoked, it should do the following:

verify that the virtual storage that was requested during the Initialization function has been allocated
initialize both the allocated virtual storage and the two data areas in the UEBCB (User Word and Pointer to User Error Message).

The following figure illustrates the Parse Options FRCB structure and its relationship to other control blocks:

Parse Options FRCB

[Parse Options FRCB]

When the Parse Options function receives control, PARSOPTL is set to the length of the option name, and the address of the option name is stored in PARSOPTN. For options that take a value, PARSVALL is set to the length of the value, and the address of the option value is stored in PARSVAL. For options that do not take a value, both PARSVALL and PARSVAL are set to 0.

If an invalid option name or option value is detected, R15 should be set to a return code value of 8.

Open Function

SAS invokes the Open function after INFILE or FILE statement processing opens the associated data set. The following figure illustrates the Open FRCB and its relationship to other control blocks:

Open FRCB

[Open FRCB]

The OPENMODE field can be one of the following values:

1	The data set is opened for input mode.
2	The data set is opened for output mode.
4	The data set is opened for append mode.
8	The data set is opened for update mode (read and write).

When this function receives control, the Pointer to User Maximum Data Size field (OPENZLEN) points to a fullword that contains the Data Set Record Size. In this function, set the pointer so that it points to a fullword that you initialize. The fullword should contain the size of the largest record that you expect to process with the Read function. If it contains a lesser value, then truncated records might be passed to the Read function.

The Data Set Record Format field (OPENRECF) can be any combination of the following values:

'C0'x	indicates Undefined format.
'80'x	indicates Fixed format.
'40'x	indicates Variable format.
'10'x	indicates Blocked format.
'08'x	indicates Spanned format.
'04'x	indicates ASA Control Characters format.

The Open function should activate any subprocesses or exits and should solicit from them any virtual storage requirements.

In this function, if you turn on the EX_NEXT flag in the UEBCB, SAS calls the Read function for the first record before it reads any records from the file itself.

If you use any SAS service routines (such as the ALLOC and FREE routines) in this function, then you must set the EX_ALC flag in the UEBCB.

Read Function

SAS invokes the Read function during execution of the INPUT statement to obtain the next input record. The following figure illustrates the Read FRCB structure and its relationship to other control blocks:

Read FRCB

[Read FRCB]

When the Read function receives control, the READRECA field (or Pointer to User Record Area Address) points to the address of the current record from the file. The READRECL field points to a fullword that contains the length of the record that is in the Record Area.

In this function you can change the Record Address so that it points to a record that was defined by your user exit. If you make this change, then SAS passes your record to the INPUT statement, rather than passing the record that was read from the file. However, in this case you must also update the fullword that the Pointer to Record Size points to: it must equal the actual size of the record that the Record Address points to.

As long as the EX_NEXT flag is on, SAS invokes the Read function to obtain the next record. SAS reads no records from the file itself until you turn off the EX_NEXT flag.

If you set the EX_DEL flag, then SAS ignores the current record, and processing continues to the next record.

Concatenation Function

SAS invokes the Concatenation function whenever a data set in a concatenation of data sets has reached an end-of-file condition and the next data set has been opened. The following figure illustrates the Concatenation FRCB structure and its relationship to other control blocks:

Concatenation FRCB

[Concatenation FRCB]

In this function you can modify the maximum data size for the next data set by changing the Pointer to User Maximum Data Size so that it points to a fullword that you initialize.

Write Function

SAS invokes the Write function during the execution of the PUT statement whenever a new record must be written to the file. The following figure illustrates the Write FRCB and its relationship to other control blocks:

Write FRCB

[Write FRCB]

When the Write function receives control, the WRITRECA field (or Pointer to User Record Area Address) points to a Record Address. The Record buffer is allocated by SAS and contains the record that was created by the PUT statement.

In this function you can change the Record Address so that it points to a record that is defined by your user exit. If you make this change, then SAS writes your record to the file, instead of writing the record that was created by the PUT statement. However, in this case you must also update the fullword that the Pointer to Record Size points to: it must equal the actual size of the record that the Pointer to Record Area points to.

In the Write function, you can also change the setting of flags in the UEBCB. As long as the EX_NEXT bit in the UEBCB is on, SAS calls the Write function to write the next output record. The DATA step is not prompted for any new records to output until the EX_NEXT flag has been set. At any time, if the EX_DEL bit in the UEBCB is on, SAS ignores the current record, and processing continues to the next record.

Close Function

SAS invokes the Close function after it closes the associated data set. In this function, you should close any files that you opened, free any resources that you obtained, and terminate all subprocesses or exits that your user exit initiated.

The following figure illustrates the Close FRCB structure and its relationship to other control blocks:

Close FRCB

[Close FRCB]

Top of Page