GETMAIN/FREEMAIN

GETMAIN/FREEMAIN

Allocate or Free Virtual Storage

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS AND DIAGNOSTICS
CAUTIONS
PORTABILITY
IMPLEMENTATION
SEE ALSO
EXAMPLE

SYNOPSIS

#include <getmain.h>

int GETMAIN_C(unsigned int length, int subpool, int options,
              void **loc);

int GETMAIN_U(unsigned int length, int subpool, int options);

int GETMAIN_V(unsigned int max, unsigned int min, int subpool,
              int options, void **loc, unsigned int *alloc);

int FREEMAIN( void **loc, unsigned int length, int subpool,
              int options);

DESCRIPTION

These functions simulate the use of the OS/390 GETMAIN and FREEMAIN Assembler macros. GETMAIN_C and GETMAIN_U are used to generate conditional and unconditional requests, respectively, to allocate virtual storage. GETMAIN_V generates a variable request. FREEMAIN generates a request to free virtual storage that has been allocated by one of the GETMAIN_ macros.

Each macro causes the compiler to generate code to load the appropriate values into registers 0, 1, and 15, and then to generate SVC 120 (under OS/390) or SVC 10 (under CMS). The use of each argument is explained here.

length

is the number of bytes of virtual storage to be allocated by the GETMAIN_ macros or released by FREEMAIN .

subpool

specifies the number of the subpool from which the storage is to be allocated.

options

is a set of option flags. All option flags are defined as macros in <getmain.h> .

For GETMAIN_U and GETMAIN_C , options is the logical sum of zero or more of the values defined by the macros BNDRY_PAGE , LOC_BELOW , LOC_ANY , and LOC_RES . These options are equivalent to the BNDRY and LOC keyword parameters to the GETMAIN assembler macro. For GETMAIN_V , options also can include COND, indicating a conditional request, or UNCOND, indicating an unconditional request. For FREEMAIN , options can be either COND or UNCOND.

loc

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

max,min

is the maximum and minimum length of the variable request.

alloc

is a pointer to an unsigned int where the length allocated for a variable request can be stored.

RETURN VALUE

GETMAIN_U returns the address of the allocated storage. GETMAIN_V , GETMAIN_C , and FREEMAIN return the value in register 15 after the SVC completes. In addition, GETMAIN_C and GETMAIN_V store the value in register 1 (the address of the allocated storage) in the void * pointed to by loc . GETMAIN_V also stores the value in register 0 (the amount of virtual storage allocated) in the unsigned int addressed by alloc .

ERRORS AND DIAGNOSTICS

The possible errors are the same as if the GETMAIN or FREEMAIN assembler macros are used in an assembly language program.

CAUTIONS

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.

The compiler generates different code sequences depending on the host operating system. If the program is to be executed on a system other than that under which it is compiled, #define (or #undef ) can be used for the symbol CMS name before including <getmain.h> .

PORTABILITY

None of the macros are portable.

IMPLEMENTATION

If the macro name CMS is defined, then CMS versions of the GETMAIN_U and FREEMAIN macros are defined. These versions generate an inline SVC 10. All option flags are ignored. The GETMAIN_C and GETMAIN_V macros are not defined.

If the macro name CMS is not defined, all four macros are defined. The macros generate an inline SVC 120.

EXAMPLE

/* Allocate a number of pages of 4K-aligned storage. */
void *pgalloc(int pages, int sp)
{
   return GETMAIN_U((pages*4096),sp,BNDRY_PAGE+LOC_ANY);
}

Chapter Contents
Previous
Next
Top of Page