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.

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. You must also include 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.

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:

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

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.

The OPENMODE field can be one of the following values:

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:

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, then 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.

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.

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.

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.

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.