Writing a User Exit Module
Overview of Writing a User Exit Module
Examples of such languages
are IBM assembly language and C. For an example of an exit that
is written in assembly language, see Sample Program.
Note: In all the figures in this
appendix, the field names that are shown in parentheses (for example,
EXITIDB in UEBCB Structure, Part 1 of 2) are the ones that were used in the
sample program.
In your user exit module,
you should include code for all seven of the functions that are described
in Function Descriptions. At the beginning of your user exit
module, examine the function code that was passed to you in the Function
Request Control Block (described in the next section), and branch
to the routine or function that is being requested.
When you write the user
exit module, you must follow IBM conventions for assembler linkage.
You must also set R15 to a return code value that indicates whether
the user exit was successful. Any nonzero return code causes execution
to stop. If you want to write an error message to the SAS log, use
the SAS LOG service routine. For more information, see “LOG”
in SAS Service Routines.
If the user exit terminates
with a nonzero return code value, then you must put the address of
a user-defined message string that ends in a null ('00'x) character
in the Pointer to User Error Message (ERRMSG) field of the User Exit
BAG Control Block. For more information, see User Exit BAG Control Block. This message is printed in the SAS
log.
Return code values that
apply to particular function requests are listed with the descriptions
of those functions in later sections of this appendix.
Be sure to take advantage
of the SAS service routines when you write your user exit functions.
For more information, see SAS Service Routines.
Function Request Control Block
The Function Request
Control Block (FRCB) provides a means of communication between SAS
and your user exit functions. Each time SAS invokes the user exit
module, R1 points to a Function Request Control Block (FRCB) that
contains, at a minimum, the fields shown in the following figure:
Function Request Control Block Fields
The 4-byte Function
Code communicates the current user exit phase to the user exit. It
contains one of the following values:
These functions are
described in Function Descriptions. Each time SAS calls the user exit,
the user exit should branch to the appropriate exit routine, as determined
by the Function code.
User Exit BAG Control Block
In Function Request Control Block Fields, the UEBCB (User Exit BAG Control
Block) serves as a common anchor point for work areas that SAS has
obtained on behalf of the user exit. SAS reserves a user word in
the UEBCB for the user exit to use. You can use this word to store
a pointer to memory that you allocate for use by all your exit routines.
SAS does not modify this word during the lifespan of the user exit.
The lifespan is defined as the time period between the Initialization
function request and the end of the DATA step.
The following two figures
illustrate the structure of the UEBCB and its relationship to other
data areas:
UEBCB Structure, Part 1 of 2
