SAS Companion for the OS/390 Environment

Writing a User Exit Module

You can write a user exit module in any language that meets the following criteria:

the language runs in 31-bit addressing mode
the language supports standard OS linkage.

Examples of such languages are IBM assembly language and C. See Sample Program for an example of an exit that is written in assembly language.

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 those that were used in the Sample Program. [cautionend]

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, and you must 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. (See "LOG" in SAS Service Routines.)

If the user exit terminates with a nonzero return code value, you must put the address of a user-defined message string that ends in a null (00x) character in the Pointer to User Error Message (ERRMSG) field of the User Exit BAG Control Block. (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. See SAS Service Routines for details.

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 Function Request Control Block Fields.

Function Request Control Block Fields

[IMAGE]

The 4-byte Function Code communicates the current user exit phase to the user exit. It contains one of the following values:

0 indicates the Initialization function.

4 indicates the Parse Options function.

8 indicates the Open function.

12 indicates the Read function.

16 indicates the Concatenation function.

20 indicates the Write function.

24 indicates the Close function.

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 Close function request.

UEBCB Structure, Part 1 of 2 and UEBCB Structure, Part 2 of 2 illustrate the structure of the UEBCB and its relationship to other data areas:

UEBCB Structure, Part 1 of 2

[IMAGE]

UEBCB Structure, Part 2 of 2

[IMAGE]

The Flag Byte 1 field can have one of several values. The following list gives the values and their meanings:

'80'x EX_NEXT: prompt the exit for the next record.
'40'x EX_DEL: ignore the current record.
'20'x EX_EOF: end-of-file has been reached.
'10'x EX_EOFC: this exit supports read/write calls after end-of-file has been reached.
'08'x EX_ALC: this exit uses the ALLOC/FREE routines.
'04'x EX_STOR: this exit supports stored programs and views.

Chapter Contents
Previous
Next
Top of Page

0	indicates the Initialization function.
4	indicates the Parse Options function.
8	indicates the Open function.
12	indicates the Read function.
16	indicates the Concatenation function.
20	indicates the Write function.
24	indicates the Close function.