DMSFREE

DMSFREE

Allocate or Free DMSFREE Storage

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
PORTABILITY
SEE ALSO

SYNOPSIS

#include <dmsfree.h>

int DMSFREE(unsigned int dwords, void **loc, char options,
            int erresp);

int DMSFREE_V(unsigned int dwords, unsigned int min,
              void **loc, unsigned int *got; char options,
              int erresp);

int DMSFRET(unsigned int dwords, void *loc2, char msg,
            int erresp);

DESCRIPTION

These functions simulate the CMS DMSFREE and DMSFRET Assembler macros. DMSFREE requests a fixed amount of free storage. DMSFREE_V requests a variable amount of free storage. DMSFRET releases free storage that has been allocated by DMSFREE or DMSFREE_V .

Each macro causes the compiler to generate an SVC 203, followed by the halfword of flags specified by the macro arguments. Most of the arguments correspond directly to the equivalent assembler macro parameters.

dwords

is the number of doublewords of free storage to be allocated by DMSFREE or DMSFREE_V or released by DMSFRET .

min

is the minimum number of doublewords of free storage to be allocated in a variable request.

loc

is a pointer to a void * where the address of the first byte of allocated free storage can be stored.

loc2

is a pointer to the storage to be freed.

got

is a pointer to an unsigned int where the number of doublewords actually allocated by a variable request can be stored.

options

is a set of option flags. Option flags are defined as macros in <dmsfree.h> . There are three types of option flags, corresponding to the assembler macro keyword parameters TYPE, AREA, and MSG.

TYPE options	specify the type of storage requested. There are two TYPE flags: `TYPE_NUC` specifies NUCLEUS free storage, and `TYPE_USER` specifies USER free storage.
AREA options	specify the area of storage from which the request will be filled. There are three AREA flags: `AREA_LOW` specifies that the request be filled from free storage below the user areas, `AREA_HIGH` specifies that the request be filled from free storage above the user area, and `AREA_ANY` specifies that any area can be used.
MSG options	indicate whether or not a message is to be issued if a failure occurs. There are two MSG flags: `MSG_YES` and `MSG_NO` .

Also, the macro FREE_DEF is defined. This macro represents the defaults used by the DMSFREE assembler macro when the TYPE, AREA, and MSG parameters are omitted. FREE_DEF is defined as follows:

AREA_ANY+MSG_YES

Use the FREE_DEF macro as the options argument, or create it by using OR to select one choice from each of the AREA, MSG, and (optionally) TYPE flags. It is not possible to allow the AREA or MSG flag to default.

msg: is one of the two MSG flags.
erresp: indicates how a failure is to be handled. Two macros are defined in <dmsfree.h> . Use the macro ERR_RET to indicate that a nonzero value is to be returned in the event of a failure. Use the macro ERR_ABN to indicate that the system should abend in the event of a failure.

RETURN VALUE

Each macro returns the value in register 15 after the SVC 203 has completed. For DMSFREE and DMSFREE_V , the value in register 1 is stored in the void * pointed to by loc . For DMSFREE_V , the value in register 0 is stored in the unsigned int pointed to by got .

The possible errors are the same as when the DMSFREE or DMSFRET assembler macros are used in an assembly language program.

CAUTION

The macros do not perform any error checking on their arguments. Incorrect arguments such as invalid combinations of option flags are either ignored entirely or remain undetected until execution time, at which point they cause unpredictable and probably undesirable results.

PORTABILITY

None of the macros are portable.

Chapter Contents
Previous
Next
Top of Page