Chapter Contents

Previous

Next
CMSSTOR

CMSSTOR



Allocate or Free Storage

Portability: SAS/C extension


SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS AND DIAGNOSTICS
CAUTION
PORTABILITY
SEE ALSO


SYNOPSIS

#include <cmsstor.h>

int CMSSTOR_OBT(unsigned int bytes, void **loc, char *subpool,
                char options, int erresp);

int CMSSTOR_REL(unsigned int bytes, void *loc2, char *subpool,
                char options, int erresp);


DESCRIPTION

These functions simulate the CMSSTOR macro. CMSSTOR_OBT requests a fixed amount of free storage. CMSSTOR_REL releases free storage that has been allocated by CMSSTOR_OBT .

Each macro causes the compiler to generate an SVC 204, with register 1 addressing an appropriate parameter list. Most of the arguments correspond directly to the equivalent assembler macro parameters.

bytes
is the number of bytes of free storage to be allocated by CMSSTOR_OBT or released by CMSSTOR_REL .

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

loc2
is a pointer to the storage to be freed.

subpool
is a pointer to a null-terminated string containing the name of the CMS subpool from which storage is to be allocated or freed. If the subpool is specified as a null string, storage is allocated from the subpool "CMS" or released from the subpool in which it was allocated. The subpool must be a PRIVATE or SHARED subpool, not a GLOBAL subpool.

options
is a set of option flags. Option flags are defined as macros in <cmsstor.h> . There are three types of option flags, corresponding to the assembler macro keyword parameters MSG, LOC, and BNDRY.
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 .
LOC options specify the location of the storage requested. There are four LOC flags: LOC_ABOVE specifies storage above the 16-megabyte line, LOC_BELOW specifies storage below the 16-megabyte line, LOC_SAME specifies storage located according to the addressing mode of the calling program, and LOC_ANY specifies any location.
BNDRY options specify the required alignment for the requested storage. There are two BNDRY flags: BNDRY_DWORD requests doubleword alignment, and BNDRY_PAGE requests page alignment.

Also, the macros OBT_DEF and REL_DEF are defined. These macros represent the defaults used by the CMSSTOR assembler macro when the MSG, LOC, and BNDRY parameters are omitted. They are defined as

MSG_YES+LOC_SAME+BNDRY_DWORD

erresp
indicates how a failure is to be handled. Two macros are defined in <cmsstor.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 204 has completed. For CMSSTOR_OBT , the value in register 1 is stored in the void * pointed to by loc .


ERRORS AND DIAGNOSTICS

The possible errors are the same as when the CMSSTOR Assembler macro is used in an assembler 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/ESA CMS Application Development Reference for Assembler.


Chapter Contents

Previous

Next

Top of Page

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