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.
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:
a pointer to a fullword
in which the allocated area address is stored.
the amount of memory
required.
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. |
frees an area of memory
that was previously allocated by a call to the ALLOC routine. The
FREE routine takes the following parameters:
a pointer to the area
to be freed.
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. |
prints a message to
the SAS log. The LOG routine takes the following parameter:
a pointer to a character
expression that ends with a null (x'00').
defines or gets access
to a SAS DATA step variable. The VARRTN routine takes the following
parameters:
a pointer to the name
of the variable.
the length of the variable
name.
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. |
the size of the variable,
if the variable type is character.
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.
|
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.