Chapter Contents

Previous

Next
SAS Companion for the OS/390 Environment

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 OS/390. 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 will be 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 string 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 will not appear in any output data set.
X'02' the variable is an external variable; it will 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 will be 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


Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.