REQMP - Request pages in memory pool

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"

The user can explicitly request (contiguous) space in a memory pool, where:

• the caller must be a pool participant (ENAMP).

• any pool participant can release the allocated memory area.

• any pool participant can access the allocated memory area.

Macro description

A contiguous memory area in a memory pool is requested with the REQMP macro. The allocation is carried out in memory pages (4Kb). The bytes of the requested page(s) are overwritten with X'00' (unless the page(s) have been requested before).

Notes

• A memory pool is addressed via a pool name or its ID (see ENAMP).

• REQMP is rejected if the memory pool is write-protected (CSTMP macro).

• Resident memory pool: REQMP is rejected if the number of pages requested exceeds the value of the RESIDENT-PAGES operand in the START- or LOAD-EXECUTABLE-PROGRAM command.

• An inquiry as to the size of the memory pool and the status of memory pages (allocated or not) can be made by means of MINF.

Macro format and description of operands

REQMP

{ {MPNAME=name / MPNAMAD={addr / (r)}[,MPNAMLN={length / (r)}]}

[,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL}] /

MPID={addr / (r)}}

[,ADDR=addr / (r)]

[,BSIZE=number / (r)]

,ALIGN=4KB / HW_PAGE

[,PARMOD=24 / 31]

[,MF=L / (E,..)]

MPNAME=
Defines the name of the memory pool (Note the connection with the SCOPE operand).

name
Name of the memory pool.

MPNAMAD=
Specifies the address of the field containing “name” (note the connection with the SCOPE operand).

addr
Symbolic address (name) of the field.

(r)
Register containing the address value “addr”.

MPNAMLN=
Defines the length of the name specified under MPNAMAD. If omitted: length attribute of the “addr” field, or 54 bytes if MPNAMAD=(r) was specified.

length
Length in bytes.

(r)
Register containing “length”.

SCOPE=
Defines the scope (authorized users) of the memory pool. This specification is used to identify the memory pool uniquely and must always be entered in conjunction with the MPNAME or MPNAMAD operand.

LOCAL

The memory pool is only used by the user who created it.

GROUP
Memory pool users can be all tasks with the ID of the user that created the memory pool.

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 SRPMOPT 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
Users can be all the tasks running in the system.

MPID=
Specifies the address of a field (length = 4 bytes) with the ID for the memory pool (see ENAMP). The ID provides unique identification of the memory pool; this operand speeds up processing.

addr
Symbolic address (name) of the field containing the ID.

(r)
Register containing the address value of the field.

ADDR=

Specifies the start address of the memory area to be allocated. The address must be aligned on a 4-Kb boundary. The entire area must be in the specified memory pool.Default value: the first unused, contiguous area in the memory pool or in user memory below the 16-Mb boundary. The area may be aligned on a specific boundary (64-Kb or 1-Mb boundary) if the number of pages requested exceeds a defined threshold.

addr
Start address.

(r)
Register containing the start address.

BSIZE=
Specifies the size of the requested memory area in memory pages (4Kb).Default value: BSIZE=1; this value is also assumed if BSIZE=0 was specified.

number
Number of memory pages.

(r)
Register containing “number”.

ALIGN=
Specifies the alignment of the requested area.

4KB
The requested area is aligned on 4-Kb boundary.

HW_PAGE
The requested memory area begins on a page boundary determined by the hardware. In this case, the operands BSIZE (in 4 Kbyte units) and ADDR (as the start address) must be used in such a way that a multiple of hardware page sizes is achieved.

Note

The hardware page size can be obtained by the NSIINF INFO=PAGESIZE macro. It is 4Kb on all currently supported servers, i.e. there is no difference between ALIGN=4KB and ALIGN=HW_PAGE.  

MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see section “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.

Return information and error flags

After successful execution of the function, register R1 contains the start address of the allocated memory area.

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 REQMP macro is transferred in register R15.
aa = X'00': normal execution,
aa = X'04': function was not carried out.

X'bb'	X'aa'	Meaning
X'00'	X'00'	Normal execution. Memory was allocated
X'18'	X'00'	Normal execution. At least one memory page was already allocated within the requested area. The remaining memory pages were allocated
X'04'	X'04'	Function was not executed. The caller is not a memory pool user (no ENAMP macro)
X'14'	X'04'	Function was not executed. Insufficient memory space: Memory pool does not have this amount of free contiguous memory space available Resident memory space: the request exceeds the value of the RESIDENT- PAGES operand in the START- or LOAD-EXECUTABLE-PROGRAM command BSIZE or ADDR is not a multiple of the hardware page size and ALIGN=HW_PAGE is specified.
X'18'	X'04'	Function was not executed. Invalid memory area: Start address or an address of the specified memory is not within the memory pool The start address is not aligned on a 4K boundary
X'24'	X'04'	Function was not executed. Authorization error: The memory pool is write-protected The caller is not authorized to request memory pages from a privileged or a class 5 memory pool
X'1C'	X'04'	The function was not executed. Operand error: Invalid operand list address Error in operand list structure Invalid address for MPNAMAD or MPID in the operand list Memory pool designation: name contains invalid characters invalid length specification (MPNAMLN) MPNAMLN was specified but MPNAMAD was not MPNAME, MPNAMAD and MPID were not specified SCOPE was specified but MPNAME/MPNAMAD was not designation not unequivocal: more than one of the operands MPNAME/MPNAMAD/MPID was specified Invalid SCOPE operand Invalid BSIZE operand Invalid register (R1) specified SCOPE=USER_GROUP was specified although SRPMOPT is not available in the system PARMOD=24 was specified in conjunction with 31-bit addressing mode (AMODE31) Requests for pages not in a memory pool are no longer supported

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 table “Standard return codes” (Standard header).

• No return codes are transferred in the standard header.