General
Application area: | Memory pools; see "Common memory areas shared by several users (Memory pools)" |
Macro type: | Type S, MF format 1: standard/L/E form; see "S-type macros" |
A memory pool (MP) is a memory area (class 6 memory) that may be used by several users together. The user who creates the memory pool defines its size (position), name and memory attributes.
Memory pools can be created in units of 64K and 1 Mb. Memory pools with units of 64K are always created below the 16-Mb boundary; on a long-term basis, such memory pools will no longer be supported. For this reason and reasons of degraded performance, users are advised against creating memory pools of 64K units. Information about the size of the memory pool and the number of memory pages allocated can be requested by means of the MINF macro.
Macro description
With the ENAMP macro, a user can create a memory pool or declare participation in an existing memory pool. The user is given an ID for the memory pool by the system. This ID can be used to increase the speed of processing in subsequent pool macros (CSTMP, REQMP, RELMP, DISMP); it can vary for different users.
When creating a new memory pool, the caller sets the following fixed pool attributes with ENAMP:
name of the memory pool
scope (authorized users: the caller only, all tasks under the user ID of the caller, all tasks from the user group of the caller, all tasks in the system)
size
start address (uniform or freely selectable for each user)
location (below the 16 Mb boundary or freely selectable for each user)
page management (resident or pageable)
The specified memory space is reserved in the address space of the caller with ENAMP. Pages are requested with REQMP.
The following points apply when using an existing memory pool:
a memory pool can only be identified uniquely with its own name and the scope (SCOPE operand); (in subsequent calls the ID is sufficient).
the caller must not specify any different pool attributes (see above) (it is best to use the default setting).
any caller can request memory space with REQMP (as far as the size of the memory pool permits) and release memory space with RELMP.
any authorized caller (CSTMP-MACRO-ALLOWED=*YES in the user catalog) can define a lock to protect memory pages against access or release the lock (CSTMP).
any caller can terminate participation in the memory pool by means of DISMP.
Notes
the WRCPT macro and the commands HOLD-TASK and RESTART-PROGRAM are rejected if a task is using a memory pool.
operand lists and input/output areas that are supplied dynamically should not be stored in memory pools (otherwise complicated synchronization measures are required).
Macro format and description of operands
ENAMP |
{ MPNAME=name / MPNAMAD={addr / (r)} [,MPNAMLN={length / (r)}] } ,SCOPE=LOCAL / GROUP / USER_GROUP / GLOBAL [,MPIDRET=addr / (r)] ,MODE=ANY / NEW / OLD [, { BSIZE={size / (r)} / PSIZE={size / (r)} }] [,LOC=BELOW] [,PAGE=addr / (r)] [,FIXED=YES] ,RES=NO / YES ,INHERIT=YES / NO [,PARMOD=24 / 31] [,MF=L / (E,..)] |
MPNAME=
Defines the name of the memory pool. Note the connection with the SCOPE operand.
name
Memory pool name. 1 <= name length <= 54 characters.
Name format:
1st character: letter or special character #,@.
2nd through 54th character: any combination from the character set
(A,...,Z,0,...,9,$,#,@).
The first blank (X'40') terminates the name.
MPNAMAD=
Defines the address of the field with “name”. Note the connection with the SCOPE operand.
addr
Symbolic address (name) of the field.
(r)
Register containing the address value of the field.
MPNAMLN=
Defines the length of the name specified under MPNAMAD. If it is not specified: length attribute of the “addr” field or, if MPNAMAD=(r) was specified, 54 bytes.
length
Length in bytes.
(r)
Register containing the length.
SCOPE=
Specifies the scope (authorized participants) for the memory pool.
The operand allows a unique identifier to be assigned to the memory pool, and must be used in conjunction with the operands MPNAME and MPNAMAD. Note the default value!
LOCAL
the use of the memory pool is limited to the calling task.
GROUP
All the tasks with the same user ID as the calling task are participants.
USER_GROUP
All the tasks, whose user IDs belong to the same user group as the user ID of the creating participant, can be participants.
The operand value assumes the existence of user groups and may therefore only be specified when the SRPM function unit of the SECOS software product is available in the system. This is why the GETUGR macro (see the “SECOS” manual [14 (Related publications)]) has to check whether SRPM is available prior to a macro call with SCOPE=USER_GROUP. The program reaction is dependent on the result (return code).
GLOBAL
All the tasks in the system are participants.
MPIDRET=
Defines the ID for the memory pool. The ID is returned to the user by the system after execution of the macro and can be used in subsequent macros (REQMP, RELMP, DISMP, CSTMP) to identify the pool uniquely (the use of the ID increases the speed of processing). All memory pool users are given their own ID by ENAMP. An exception are “inheritable” memory pools, where the “son task” can use the same ID as the “parent task”.
addr
Symbolic address (name) of the field containing the ID.
Field length = 4 bytes.
(r)
Register containing the address value of the field.
MODE=
Specifies whether the caller wants to create a new memory pool or use one that already exists. If the latter is the case, it should be noted that a memory pool can only be identified uniquely via its name and scope (SCOPE operand).
ANY
the caller wants to use the specified memory pool if it exists; if not, a memory pool with the specified attributes is created for the caller.
NEW
The caller wants to generate a new memory pool with the specified attributes.The call is rejected if a memory pool with this name and SCOPE already exists.
OLD
The caller wants to use an existing memory pool. The call is rejected if
the memory pool does not exist,
the specified pool attributes do not correspond to those determined at pool creation
the memory pool was generated with SCOPE=LOCAL.
BSIZE=
Defines the size of the memory pool (in 4K units = memory pages). The memory pool is created as a contiguous memory area as specified by means of the operands PAGE and/or LOC and, depending on the addressing mode, below or above the 16-Mb boundary.
BSIZE cannot be specified if the PSIZE operand was specified at memory pool creation.
size
Number of memory pages (4K units). Specification of size = 0 is illegal and results in the macro call being rejected. The size of the memory pool may be rounded by the operating system for performance reasons (see Notes).
(r)
Register containing the number of memory pages
Default setting:
For reasons of compatibility, a (new) memory pool is created using the default value for the PSIZE operand if neither BSIZE nor PSIZE is specified explicitly.
Current value for existing memory pool.
Notes
The size of the memory pool may be rounded by the operating system for performance reasons as follows:
The memory pool is created with units of 1 Mb and aligned on a 1-Mb boundary. Currently it is rounded to a multiple (n) of 1 Mb units (size of MP = n * 1Mb >= size * 4K).However, the value of the rounding is not a guaranteed part of the interface and may be HSI-dependent.
PSIZE=
Defines the size of the memory pool in 64K units. The memory pool is created as a contiguous memory area below the 16-Mb boundary and aligned on a 64K boundary.PSIZE cannot be specified if the BSIZE operand was specified at memory pool creation.
size
Number of memory segments with 64K each. size=0 is illegal; the macro is rejected in this case.
(r)
Register containing the value for “size”.
Default value (only if operand BSIZE was not specified at memory pool creation):
size = 1 for a memory pool to be created,
current value for an existing memory pool.
Note
The "PSIZE" parameter and memory pools of 64 Kbyte units should be used only, if the memory pool must be accessible in 24-bit addressing mode, too.
Otherwise, the "BSIZE" parameter is recommended to specify the size of a memory pool.
LOC=
Specifies that part of the address space where the memory pool is to be located. Specification of this operand is useful only in conjunction with 31-bit addressing and if the BSIZE operand is specified.
BELOW
The memory pool is created in the caller's address space below the 16-Mb boundary.
Note
A memory pool created with LOC=BELOW but without a fixed start address may, in another participant's own address space, also be placed above the 16-Mb boundary.
PAGE=
Specifies the start address of the memory pool in the caller's address space. The start address should be aligned as follows:
on a 64K boundary, if the memory pool consists of 64K segments (PSIZE operand).
on a 1-Mb boundary, if the memory pool consists of 1-Mb segments (BSIZE operand).
Default setting: The first sufficiently large and contiguous area that begins on a 64K or 1-Mb boundary is selected.
In 31-bit addressing mode, the memory pool is located above the 16 Mb boundary unless LOC=BELOW is specified. If the memory pool was created with FIXED=YES, the fixed start address is binding for all future users.
Default value in this case: the start address is assumed (the memory pool is placed in the address space of the caller in the same way as in the address space of the one that created the memory pool). The start address is submitted to the caller in register R1.
addr
Start address.
(r)
Register containing the address value “addr”.
Note
Wherever possible, the PAGE operand should not be used. Should it be indispensable, the user should previously inquire about the size and location of the class 6 memory by means of the MINF macro.
FIXED=YES
The memory pool has the same virtual start address for all users (from this address onwards, it is placed in the caller's address space).
Notes
if FIXED=YES is not specified (by the first caller), future users may each specify a different start address in their address space.
a caller that wants to use an existing memory pool cannot revoke the FIXED=YES specification.
specification of this operand is useful only for the caller that created the memory pool. If it is not specified at memory pool creation, any subsequent specification of FIXED=YES by a pool participant will be rejected.
RES=
Specifies whether the memory pages of the pool are to be pageable or resident. This attribute is determined by the caller that creates the pool (the maximum number of resident memory pages is set in user catalog).
NO
The memory pages are to be pageable.
YES
The memory pages are to be resident.
Note
In the case of RES=YES, the specification for the PSIZE/ BSIZE operand is not checked against the specification for the RESIDENT-PAGES operand in the START-EXECUTABLE-PROGRAM or LOAD-EXECUTABLE-PROGRAM command. The check is not carried out until memory space is occupied with REQMP.
INHERIT=
Specifies the inheritability of a memory pool when the participating user task (“parent task”) generates a new son task: (“fork()”). This operand is not supported if a local and resident class 6 memory pool was specified or PARMOD=24 was set. See also note on "ENAMP - Enable memory pool".
YES
The memory pool should be inheritable i.e. in the event of a fork(), the son task is implicitly linked to a non-local memory pool of the parent task.
For a local (non-resident) memory pool, the memory space of the parent task is copied to the son task. This means that the memory space for each task is locally available and the task is free to decide on the contents of the memory pool and the functions to be executed.
NO
In the event of a fork(), the son task is not linked to the memory pool of the parent task. The memory area is not assigned to the son task.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
PARMOD=
Controls macro expansion. Either the 24-bit or the 31-bit interface is generated.
If PARMOD is not specified here, macro expansion is performed according to the specification for the GPARMOD macro or according to the default setting for the assembler (= 24-bit interface).
24
The 24-bit interface is generated. Data lists use 24-bit addresses.
(Address space <= 16 Mb).
31
The 31-bit interface is generated. Data lists use 31-bit addresses
(address space <= 2 Gb) and start with the standard header.
Notes on memory pool inheritability
For inheritable, local memory pools, a new memory pool is set up implicitly for the “son task” (after task generation by the parent task: “fork()”). This has the same properties (name, access rights etc.) and contents as the memory pool of the parent task at the point when the son task was generated (implemented via the copy-on-write mechanism). This enables both parent and son tasks to have shared access to the contents of the memory pool, while any changes effected by them apply only locally within their “own” memory pool.
For inheritable, non-local memory pools, inheritance is effected via an implicit ENAMP call to the existing memory pool during the fork(). This means that parent and son tasks operate in the same memory area.
The ID of the memory pool (MPIDRET operand) is inherited from the the parent task by the son task.
However, the allocation for requesting resident memory pages and - for a local memory pool - the resident memory pages priorized with CSTAT PAGE=NO, are not inheritable.
Return information and error flags
The virtual start address of the memory pool is stored in register R1 after the function has been carried out.
R15:
+---------------+ | | | | | |b|b|0|0|0|0|a|a| +---------------+
A structured return code (aa=primary return code, bb=secondary return code) relating to the execution of the ENAMP macro is transferred in register R15.
X'bb' | X'aa' | Meaning |
X'04' | X'00' | Normal execution; a new memory pool has been established (MODE=NEW/ANY). |
X'08' | X'00' | Normal execution; the caller is the new user of the specified memory pool |
X'04' | X'04' | Function was not executed; memory pool does not exist (MODE=OLD). |
X'08' | X'04' | Function was not executed. The macro refers to an existing memory pool:
|
X'14' | X'04' | Function was not executed; insufficient free memory space
|
X'18' | X'04' | Function was not executed; invalid memory address:
|
X'1C' | X'04' | Function was not executed. Operand error:
|
X'20' | X'04' | Function was not executed. Owing to memory saturation, the macro cannot be |
31-bit interface:
In the event of errors in the alignment or initialization of the standard header, the return codes X'0001FFFF' / X'0003FFFF'/ X'0004FFFF' are additionally transferred in register R15; see the table “Standard return codes” (Standard header).
No return codes are transferred in the standard header.