Using the INFILE/FILE User Exit Facility

SAS Service Routines

SAS provides four service routines that you can use when writing INFILE/FILE user exits. These service routines allocate memory, free memory, access DATA step variables, or write a message to the SAS log. Whenever possible, use the SAS service routines instead of the routines that are supplied with z/OS. For example, use the ALLOC SAS service routine instead of GETMAIN. When you use the ALLOC routine, SAS frees memory when you are finished with it. By contrast, if you use the GETMAIN routine, cleaning up memory is your responsibility, so you also have to use the FREEMAIN routine.

The following list describes the four SAS service routines. You invoke one of these routines by loading its address from the appropriate field in the UEBCB and then branching to it. All of these routines are used in the Sample Program.

ALLOC routine

allocates an area of memory from within the SAS memory pool. This memory is automatically freed when the Close function is processed. The ALLOC routine takes the following parameters:

ALCEXIT

a pointer to the UEBCB.

ALCPTR

a pointer to a fullword in which the allocated area address is stored.

ALCLEN

the amount of memory required.

ALCFLG

a flag byte that controls whether the memory is allocated above or below the 16M line. It has the following values:

1	allocates the memory below the 16M line.
0	allocates the memory above the 16M line.

FREE routine

frees an area of memory that was previously allocated by a call to the ALLOC routine. The FREE routine takes the following parameters:

FREEXIT

a pointer to the UEBCB.

FREPTR

a pointer to the area to be freed.

FREFLG

a flag byte that indicates whether the memory that is to be freed is above or below the 16M line. It has the following values:

1	the memory is below the 16M line.
0	the memory is above the 16M line.

LOG routine

prints a message to the SAS log. The LOG routine takes the following parameter:

LOGSTR: a pointer to a character expression that ends with a null (x'00').

VARRTN routine

defines or gets access to a SAS DATA step variable. The VARRTN routine takes the following parameters:

VARNAME

a pointer to the name of the variable.

VARNAMEL

the length of the variable name.

VARTYPE

the type of variable that is being defined. It takes the following values:

1	the variable is numeric (double precision).
2	the variable is character.

VARSIZE

the size of the variable, if the variable type is character.

VARFLAG

a flag byte that controls whether the variable is considered internal or external. It takes the following values:

X'01'	the variable is an internal variable; it does not appear in any output data set.
X'02'	the variable is an external variable; it does appear in the output data set.

VARADDR

a pointer to a fullword into which SAS places the address at which the current value of the variable is stored. For numeric variables, the value is stored as a double precision value. For character variables, the stored value consists of three components:

MAXLEN	is 2 bytes and represents the maximum length of the character variable.
CURLEN	is 2 bytes and represents the current length of the character variable.
ADDR	is 4 bytes and is a pointer to the character variable string data.

Here are the return codes for the VARRTN routine:

0	the routine was successful (the variable was created or accessed).
1	the variable already exists as a different type.
2	the variable already exists as a character variable, but with a shorter length.
3	the variable already exists.

SAS provides two versions of the four service routines that are described in this section. The versions of the routines can be used from a SAS/C environment. Here are the service routines:

Assembler language programs that conform to the SAS/C standard, such as the example in Sample Program
ALLOC1, FREE1, LOG1, and VARRTN1

These routines contain extra logic to reestablish the SAS/C environment when the exit does not conform to this standard. If R12 is modified by the user exit, or by the run-time library for the language that the user exit is written in, then you must use this set of functions.

Top of Page