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
Operation |
Environment |
Authorization: |
Problem program or supervisor state, PSW key 8 |
Dispatchable unit mode: |
Task |
Cross memory mode: |
PASN = HASN |
AMODE (BPX1MMI): |
31-bit |
AMODE (BPX4MMI): |
64-bit |
ASC mode: |
Primary address space control (ASC) mode |
Interrupt status: |
Enabled for interrupts |
Locks: |
Unlocked |
Control parameters: |
All parameters must be addressable by the caller
and in the primary address space. |
Format
CALL BPX1MMI (FunctionCode,
ParmListPtr,
Return_value,
Return_code,
Reason_code)
|
AMODE 64 callers use BPX4MMI with the same parameters.
ParmListPtr is a doubleword pointer field.
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.)
- 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.
- The worker processes can connect as many blocks to their map area
as will fit.
- 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.
- 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.
- 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.
- There is no explicit call to delete the map area.
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.)