__map_service (BPX1MMS, BPX4MMS) — Mapped megabyte area services

Function

The __map_service callable service performs the following operations on one or more data blocks in a memory map area created by the __map_init service:

Creates a new data block
Connects to an existing data block
Disconnects from a data block
Frees the backing storage for a data block
Changes the read or write permission for a data block

Before an application can use this service, it must invoke the __map_init callable service to create a mapped megabyte area to hold its data blocks. See __map_init (BPX1MMI, BPX4MMI) — Create a mapped megabyte area.

Requirements

Operation	Environment
Authorization:	Problem program or supervisor state, PSW key 8
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1MMS):	31-bit
AMODE (BPX4MMS):	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 BPX1MMS (FunctionCode,
              ParmListPtr,
              ArrayCount,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MMS 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_SERVICE	Perform one or more operations on map blocks: Activate a new data block (MAP_NEWBLOCK) Connect to a data block (MAP_CONN) Disconnect from a data block (MAP_DISCONN) Free the backing storage for a data block (MAP_FREE) Change the read or write permissions for a data block (MAP_CNTL)

These constants are 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 for the specified function. See BPXYMMG — Map interface for _map_init and _map_service for the mapping of the parameter lists.

ArrayCount

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the number of entries in the array that is contained in the parameter list provided by ParmListPtr. The value specified in the ArrayCount parameter must be greater than or equal to 1 and less than or equal to 1000.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which __map_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_service callable service stores the return code. The __map_service callable 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_service callable service may return one of the following values in the Return_code parameter:

Return code	Explanation
EEXIST	A request was made to perform a service on a block, but either a map area is not currently active for the process, or the map area is in the process of being shut down (JRMapNotActive).
ENOMEM	A request to create a new block or connect to an existing block was made with a zero block address, specifying that the __map service is to locate the address of a free map block, but there are no unused blocks in the map area to satisfy the request (JRMapOutOfBlocks).
EINVAL	One of the following errors occurred: The FunctionCode parameter contains a value that is not a supported function, or the service call parameter list field MMG_SERVICETYPE contains an unsupported value (JRMapBadFunction). A request was made to connect to a block, free the backing storage for a block, or change the access state (control operation) for a block, but the token provided does not match that of any allocated block in the backing storage (JRMapTokenNotFound). A MAP_NEWBLOCK or MAP_CONN request specified a map area block that is already in use (JRMapBlockInUse). A request was made to connect to a block in the backing storage that is currently marked to be freed. The connection is not permitted (JRMapBlockFreePending). A request was made to disconnect from a map block, but the block is not currently in use in the map area for this process (JRMapBlockNotInUse). A reserved field contains nonzero data (JRReservedValueInvalid). A block address was provided, but either it is not in the map area or it is not on a map block boundary (JRBadBlkAddr). The array count was negative, zero, or greater than the maximum number of array elements permitted (1000) (JRMapArrayCountErr).
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). A request to create a new block, connect to an existing block, disconnect from an existing block, or change the read or write permissions for a block failed in RSM (JRIarvServ).

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the __map_service callable service stores the reason code. The __map_service callable 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_service callable service is designed to perform storage connects and disconnects very quickly. No data movement occurs.
Input to the __map_service callable service is an array of requests. Each request is processed in order until all requests have been successfully processed, or until an error occurs. When an error occurs, some requests may have been processed and some may not. An output flag on the array elements, _mmg_ReqFail, indicates the requests that have and have not been processed. The flag is off for array elements that have been processed successfully. The flag is on for the request that failed and all requests that had not yet been processed at the time of the failure.
The __map_service callable service allows an application to create a new data block and specify which map area block is to be used to view this data block. The map area block that is to contain the new data block must be free, that is, not currently connected to another data block. The kernel assigns a unique token to the new data block and returns this token to the application. The token is later used to identify the data block to subsequent calls to __map_service. The application may modify the new data block contained within its map block in any way it chooses.
Storage blocks are initially connected in write mode. When a block is in write mode, all worker processes that have the block connected have the block in write mode. If the block access is changed to read-only, all worker processes that have the block connected have the block in read-only mode.
Any areas within the map area that do not have a block connected are in the hidden state. Any reference to storage in the hidden state triggers a SIGSEVG signal.
If the initial process or a worker process forks, the child process inherits a map area that is initialized to the hidden state.
When an application has finished using a data block, it may do one of several things:
- If it no longer needs the data block, it can disconnect it from the map block and request that the kernel free the data block. Once the data block has been freed and its use count has gone to zero, the data no longer exists in the kernel data space and is no longer available for processing.
- If the data is still valuable, but is not currently needed, the application can request that the map area block be disconnected from the data block (without freeing it). This leaves the data block in a kernel data space for later use, while freeing the map area block for use in processing other data blocks. The map area block is hidden as part of the disconnect, and an 0C4 abend occurs if the application attempts to reference any storage in the map area block.
  Later, when a disconnected data block needs to be processed, the application can call __map_service with a connect request, specifying the token for the data block and the address of the map block it is to be attached to for processing. The __map_service callable service attaches the specified data block to the appropriate map block for use by the application. The block is read-only or read/write based on its state as of the last control operation.
- A data block may be freed without having first been connected by a call to __map_service with a free request, specifying the token of the data block.
- An application can control the access state (read or read/write) of a connected data block by calling __map_service with a control request and specifying the desired target state. Because special mechanisms are used for the sharing of a data block between several processes, a state change is against the data block and affects all users of the data block (not just the current user's data block). State changes persist across disconnects. If a data block is made read-only and all users disconnect from the data block, the next user to connect to the data block obtains the block read-only.

See the description of the __map_init callable service, Usage notes, for more information about using these two related services.

Related services

__map_init (BPX1MMI, BPX4MMI) — Create a mapped megabyte 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.).

Examples

For an example using this callable service, see BPX1MMS (__map_service) example.