__map_init (BPX1MMI, BPX4MMI) — Create a mapped megabyte area

Function

The __map_init callable service creates a mapped megabyte area in the private area of the calling address space to hold a fixed number of the application's data blocks. This map area is divided into map blocks, each of which is a view onto a data block that is maintained in the kernel data space. The application can set the number of map blocks contained in the map area and the size, in megabytes, of each map block.

Once it has created the map area with the __map_init service, an application can use the __map_service (BPX1MMS, BPX4MMS) callable service to connect and disconnect blocks of storage in the map area.

Requirements

Parameters

FunctionCode

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains a value indicating the type of map function the caller is requesting. The following is the only supported value:

Constant	Description
MMG_INIT	Create mapped megabyte area

This constant is defined in the BPXYMMG macro. See BPXYMMG — Map interface for _map_init and _map_service.

ParmListPtr

Supplied parameter

Type:

Pointer

Length:

Fullword (doubleword)

The name of a fullword (doubleword) field that contains the address of the parameter list. See BPXYMMG — Map interface for _map_init and _map_service for the mapping of the parameter list.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __map_init service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __map_init service stores the return code. The __map_init service stores a return code only if the return value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The __map_init service may return one of the following values in the Return_code parameter:

Return code	Explanation
EEXIST	An attempt was made to create more than one map area for the process (JRMapAlreadyActive).
ENOMEM	A request to initialize a map area failed for one of the following reasons: There was insufficient storage in the caller's address space to obtain the map area needed to contain the map blocks (JRNoUserStorage). All or part of the area defined by the address that was provided by the caller in MMG_AREAADDR was already allocated (JRStorNotAvail).
EPERM	One of the following errors occurred: The caller is not permitted to the BPX.MAP resource in the FACILITY class. Superuser status (UID=0) is not sufficient (JRNotAuthMAP). The BPX.MAP resource in the FACILITY class is not defined, and the user is not a superuser (JROK).
EMVSSAF2ERR	An error occurred in the security product.
EINVAL	One of the following errors occurred: The FunctionCode parameter contains a value that does not represent a supported function (JRMapBadFunction). The number of blocks specified ( _MMG_NUMBLKS) was either negative or zero (JRNegativeValueInvalid). The number of megabytes per block specified (_MMG_MEGSPERBLK) was either negative or zero (JRNegativeValueInvalid). A reserved field contains nonzero data (JRReservedValueInvalid). The request specified a map address (_MMG_AREAADDR) that was not above the line, or that was not on a megabyte boundary (JRBadAddress).
EFAULT	An argument of this service contained an address that was not accessible to the caller (JRMapBadStorage).
EMVSERR	One of the following occurred: There was an unexpected error (JRMapUnexpectedErr). An attempt to process the new map area failed in RSM (JRIarvServ).

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __map_init service stores the reason code. The __map_init service stores a reason code only when the return value is -1. The reason code further qualifies the return code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. The __map_init and __map_service callable services allow applications to manage an unlimited number of data blocks, each of which can hold some number of megabytes of data. They provide a fast way to connect up to persistent memory for applications that need more shared memory than will fit in the address space.
2. It is intended that an application will call the __map_init service once to create the map area. The map area should be large enough for the biggest expected usage.
3. A process may have one, and only one, map active at a given time. There is currently no way to terminate a map area once it has been established without terminating the establishing process.
4. At any point in time, an application can view as many data blocks as were specified at initialization of the map area, and it can have many times this number of data blocks defined and residing in kernel data spaces.
5. The map area may be shared among one or more processes. Sharing may only be between a parent and any children that were created after the parent created the map area with a call to the __map_init service. Children that were created before the call do not have access to the map area, nor can they gain access to it through any service.
6. A map area is not propagated across a spawn or preserved across an exec. Unlike most attributes on fork, the map area that is inherited by a child is empty; none of the map blocks are connected to data blocks, regardless of how many data blocks are currently connected to the parent's map area.
7. A map area persists until the process that created it terminates. Once that process terminates, all map activity against the data blocks is shut down. Currently connected blocks may continue to be used until they are disconnected. New blocks cannot be created, nor can a process connect to an existing data block. Once all data blocks have been disconnected by all processes, the map area is ended. A process that has been detached from a map area by disconnecting from all data blocks may create a new map area.
8. Each process that is sharing a map (parent, child, or grandchild) gets a map area that is located at the same virtual storage address as the map originator and that consists of map blocks that are the same size and number as those of the originator. Each process that is sharing a map manages its own map area in terms of the data blocks that are connected, and each process determines which data block is viewed through which map area block.
9. The initial process forks worker processes, which inherit the map area at the same virtual address. Because the map area is at the same virtual address, storage blocks can be connected to the same block in map areas of different worker processes, and pointers can be used to point to data in this and other blocks. (This assumes that they are always connected at the same location in the map area.)
10. As worker processes perform their tasks, they can request that new blocks of storage be created in the map area. Each block has a token associated with it, which allows other worker processes to connect to the same block. In this respect, the map area acts like shared memory.
11. The worker processes can connect as many blocks to their map area as will fit.
12. When the worker process has no further need for a data block, it can disconnect it from the map area. Following a delete request for a block, the block is actually freed when the last worker process disconnects from it.
13. When a worker process has finished using a data block, the storage can be freed. The data is actually freed when the last worker process disconnects from that block.
14. Using the __map_init and __map_services, an application could create multiple gigabytes of storage, of which only certain blocks are mapped into the worker processes at a given time.
15. There is no explicit call to delete the map area.

Related services

• __map_service (BPX1MMS, BPX4MMS) — Mapped megabyte area services

Characteristics and restrictions

Users of __map_service can create and manage a tremendous amount of data, causing the kernel to consume a large amount of system resources. To prevent abuse of such power, the __map_init service requires that the user be permitted to the BPX.MAP resource in the FACILITY class. (The __map_service callable service does not check for authority to BPX.MAP, because it does not perform any functions without first completing a __map_init request.)