Chapter Contents

Previous

Next
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.


SEE ALSO

See VM/SP CMS for System Programming.


Chapter Contents

Previous

Next

Top of Page

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