__moservices() - Memory object services
Standards
| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
| AMODE 64 Language Environment® | both | z/OS® V1.10 |
Format
#include <stdlib.h>
int __moservices(int reqtype, size_t mopllen,
struct __mopl_s * mopl, void ** moorigin);General description
The __moservices() function allows the caller to perform the following memory object services:
- Create a memory object that will be associated with the current Language Environment enclave;
- Free a memory object that was created using a previous __moservices() call;
- Specify a shared memory dump priority to be used when allocating shared memory.
- Argument
- Description
- reqtype
-
The request type. Valid values are
- __MO_GETSTOR
- Use IARV64 REQUEST(GETSTOR) to create a memory object that is associated with the current Language Environment enclave.
- __MO_DETACH
- Use IARV64 REQUEST(DETACH) to free a memory object that was created using __moservices().
- __MO_SHMDUMPPRIORITY
- Set a shared memory dump priority, to be associated with shared memory segments on subsequent shmget() calls.
- mopllen
- The length of the passed mopl structure. If a mopl is not passed, this length should be set to zero.
- mopl
-
Points to a structure describing additional characteristics for the request.
For __MO_GETSTOR and __MO_SHMDUMPPRIORITY requests, this structure is required.
For __MO_DETACH requests, this structure is optional.
- moorigin
-
On __MO_GETSTOR calls, moorigin contains the origin address of the memory object upon return.
On __MO_DETACH calls, moorigin contains the origin address of the memory object to be detached.
The __mopl_s structure is defined in stdlib.h and has the following format:
struct __mopl_s {
unsigned long __moplrequestsize;
int __mopldumppriority;
unsigned int __moplgetstorflags;
long __moplreserved;
int __mopl_iarv64_rc;
int __mopl_iarv64_rsn;
};The entire __mopl_s structure must be set to binary zeroes prior to use. The fields are used as follows:
| __mopldumppriority | For __MO_GETSTOR, the desired memory object dump priority (1-99). For __MO_SHMDUMPPRIORITY, the desired shared memory dump priority (1-99). |
|---|---|
| __moplsize | For __MO_GETSTOR, the size of the memory object to be created. The size is in 1MB units when 4K or 1MB page frames are requested. The size is in 2GB units when 2GB page frames are requested. |
| __moplstorflags | For __MO_GETSTOR, flags identifying additional
characteristics for the memory object to be created. The following
flags are defined:
Note: If none of the above flags are set, then the memory
object will be backed by 4K page frames. Also, the above flags are
mutually exclusive.
|
| __mopliarv64rc | The return code from the call to IARV64 |
| __mopliarv64rsn | The reason code from the call to IARV64 |
Constants are available which identify the dump priorities of memory objects obtained by Language Environment:
| __MO_DUMP_PRIORITY_STACK | Dump priority of memory objects to be used as Language Environment stacks. Value is 5. |
| __MO_DUMP_PRIORITY_HEAP | Dump priority of memory objects to be used as Language Environment heaps. Value is 15. |
For the dump priority of memory objects obtained by other programs (such as Java™), refer to the corresponding documentation for those programs.
All memory objects obtained by __moservices() are unguarded and count towards the address space memlimit. For more information on memory objects and the IARV64 service, See z/OS MVS Programming: Assembler Services Guide and the z/OS MVS Programming: Assembler Services Reference ABE-HSP, z/OS MVS Programming: Assembler Services Reference IAR-XCT.
Returned value
If successful, __moservices() returns 0.
If unsuccessful, __moservices() returns -1 and sets errno to one of the following values:
- Error Code
- Description
- EINVAL
- An argument to this function contained an incorrect value. Use __errno2() to obtain more detailed information on the error.
- EMVSERR
-
A z/OS environmental or internal error occurred. Use __errno2() to obtain more detailed information on the error.
If the underlying IARV64 call is unsuccessful, and the mopl argument has been specified, then __mopl_iarv64_rc and __mopl_iarv64_rsn will contain the return and reason codes returned by IARV64.
Example
/* CELEBM25
This example illustrates the __moservices() function.
This example sets a shared memory dump priority, then
gets and detaches a memory object.
*/
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
int main(void) {
__mopl_t mymopl;
int mos_rv;
void * mymoptr;
memset(&mymopl, 0, sizeof(__mopl_t));
/* Set a shared memory dump priority for subsequent shmget() */
mymopl.__mopldumppriority = 8;
mos_rv = __moservices(__MO_SHMDUMPPRIORITY, sizeof(mymopl),
&mymopl , &mymoptr);
if (mos_rv != 0) {
perror("moservices(SHMDUMPPRIORITY) call failed");
}
/* Obtain a 100MB memory object whose dump priority falls */
/* between the dump priorities of the Language Environment */
/* stacks and heaps. */
mymopl.__mopldumppriority = __MO_DUMP_PRIORITY_STACK + 5;
mymopl.__moplrequestsize = 100;
mos_rv = __moservices(__MO_GETSTOR, sizeof(mymopl),
&mymopl , &mymoptr);
if (mos_rv == 0) {
printf("moservices(GETSTOR) successful, MO addr: %p\n",
mymoptr);
/* Free the 100MB memory object. */
mos_rv = __moservices(__MO_DETACH, 0, NULL, &mymoptr);
if (mos_rv != 0) {
perror("moservices(DETACH) call failed");
}
}
else {
perror("moservices(GETSTOR) call failed");
}
return 0;
}