FASTPAM function: ENABLE IOAREA POOL

This function can be used to create an I/O area pool or to connect the caller with an existing pool.
A pool ID (FPAMIPID) is entered in the parameter list; this ID must then be used in subsequent OPEN calls. If the same parameter list is used for such calls, the ID will have already been entered and need not be filled in by the user.

The ENAIPO function only evaluates the operands described below.

Format FCT=*ENAIPO

Operation	Operands
FPAMSRV	[,FCT = *ENAIPO / adr / (r)] [,IPONAME = 'name' / adr / (r)] [,IPOADDR = (elem1,elem2)] [,IPOSIZE = size / adr / (r)] [,RES = *NOT_SPECIFIED / *NO / *YES / adr / (r)] MF = L
	MF = E,PARAM = adr / (r)
	MF = D[,PREFIX = F / pre]
	MF = C / M [,PREFIX = F / pre] [,MACID = PAM / macid]

Operand descriptions

FCT

Defines the FASTPAM function to be executed.

Only a direct specification is allowed for the MF=L form.

= *ENAIPO
Direct specification for the ENABLE IOAREA POOL function.

This function creates an I/O area pool or connects the user with an existing pool.A pool ID (FPAMIPID) is entered in the parameter list; this ID must then be used in subsequent OPEN calls. If the same parameter list is used for such calls, the ID will have already been entered and need not be taken into account.

= addr
Symbolic address of a 1-byte field containing the value for the ENABLE IOAREA POOL function to be executed.

= (r)
Register containing the value for the ENABLE IOAREA POOL function.

IPOADDR

Defines the location of the I/O area pool in a data space or a program space by means of a list of 2 elements (see the “Executive Macros” manual [2]).

= elem1
Specifies the 4K-aligned starting address of the memory area in the data space or program space. If this area is created in resident memory, it must not overlap with the memory area of some other I/O area pool, with the parameter list area of an environment, or a DIV window and must be requested beforehand (REQM, REQMP...).

If the area lies in a memory pool, the memory pool must be one that was created by using the ENAMP macro with the operand FIXED=YES.

Only the symbolic address is allowed for the MF=L form, but no symbolic names may be used within a DSECT, since its address is not known until runtime.

elem1 has the following format:

elem1 =adr1 / (r1)

where:

addr1	is the symbolic starting address of the I/O area pool in the data or program space.
(r1)	is a register containing the starting address of the I/O area pool in the data or program space.

= elem2
Identifies the address space.
elem2 = 0: the I/O area pool lies in the program address space.
elem2 ≠ 0: the I/O area pool lies in a data space with ALET <elem2>
(ALET stands for Access List Entry Token, i.e a pointer to an entry in the access list; see the “Executive Macros” manual [2] for details). Note that only non-resident data spaces are currently supported.

Only a direct specification is allowed for the MF=L form.

elem2 has the following format:

elem2 =adr2 / nmbr / (r2)

where:

nmbr	is the numeric value of the ALET or 0.
addr2	is the symbolic address of a 4-byte field containing the ALET or 0 (binary).
(r2)	is a register containing the ALET or 0.

IPONAME

Designates the name of the I/O area pool.

Only a direct specification is allowed for the MF=L form.

= 'name'
Name of the I/O area pool:
1 <= 'name' <= 54 characters.
Naming conventions:
1st position: a letter or the special characters # and @
2nd - 54th position: any combination from the character set (A,...,Z,0,...,9,$,#,@).
The name is terminated by the first blank (X'40')
The name must be enclosed in single quotes.

= addr
Symbolic address of a 54-byte field containing the name of the I/O area pool.

= (r)
Register that holds the address of a 54-byte field containing the name of the I/O area pool.

IPOSIZE

Indicates the size of the memory area for the I/O area pool in units of 4 Kbytes. This area should have already been created with the appropriate size.

Only a direct specification is allowed for the MF=L form.

= size
Size of the memory area for the I/O area pool in 4-Kbyte units: 1 <= size <= 2¹⁹.

= addr
Symbolic address of a 4-byte field containing the size of the memory area for the I/O area pool in units of 4 Kbytes.

= (r)
Register containing the size of the memory area in units of 4 Kbytes.

MACID

See the description under the format FCT=*ENAENV on "FASTPAM function: ENABLE ENVIRONMENT".

MF

The forms of the MF operand are described in detail in the appendix, "Macro types".

PARAM

See the description under the format FCT=*ENAENV on "FASTPAM function: ENABLE ENVIRONMENT".

PREFIX

See the description under the format FCT=*ENAENV on "FASTPAM function: ENABLE ENVIRONMENT".

RES

Specifies whether the I/O area pool is to be made resident.

Only a direct specification is allowed for the MF=L form.

= *NOT_SPECIFIED
The I/O area pool already exists, and the user wishes to join it, regardless of whether or not it was made resident.

= *YES
The I/O area pool is to be created in resident memory.
In this case, a check is performed to determine whether the user ID has the required FASTPAM authorization and whether the number of resident pages requested in the program call (user catalog: “RESIDENT-PAGES” or “CLASSII”) is sufficient for the I/O area pool. If the result of the check is negative, the user receives the return code “FPAMNORE”, and the I/O area pool is made non-resident.

Space in data spaces is provided only on a non-resident basis.

= *NO
The I/O area pool is not to be created in resident memory.

= addr
Symbolic address of a 1-byte field containing the value for RES.

= (r)
Register containing the value for RES.

Possible return codes of the FASTPAM function FCT=*ENAIPO

Standard header: ccbbaaaa

The following code relating to execution of the FPAMSRV macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):

X'cc'	X'bb'	X'aaaa'	Meaning
	X'00'	X'0000'	Function executed successfully.
	X'01'	X'0002'	Function not executed. Invalid name of I/O area pool.
	X'01'	X'0007'	Function not executed. Invalid memory address of I/O area pool.
	X'01'	X'0008'	Function not executed. Invalid size of I/O area pool.
	X'01'	X'0012'	Function not executed. Invalid specification for RES NOT_SPECIFIED was entered for RES, but the specified environment does not exist.
	X'20'	X'0028'	Function not executed. System error. Run system diagnostics.
	X'40'	X'0032'	The environment or the I/O area pool could not be created in resident memory. The application system can still be used for testing, but without the benefits of FASTPAM performance. Subcode2 specifies the cause of the error.
X'01'	X'40'	X'0032'	The user ID of the task that created the environment or I/O area pool does not have the required FASTPAM authorization. Response: inform the system administrator.
X'02'	X'40'	X'0032'	Not enough room in actual memory.
X'03'	X'40'	X'0032'	The amount of resident main memory allocated at the start of the program is not sufficient.
X'04'	X'40'	X'0032'	Connection to a nonresident environment or a nonresident I/O area pool.
X'05'	X'40'	X'0032'	This FASTPAM version only supports non-resident data spaces.
	X'40'	X'0035'	An I/O operation is being executed on the memory pages that are to be fixed during execution of the *ENAENV/*ENAIPO function. This return code only occurs when creating the environment or I/O area pool. There is no restriction on I/Os when joining an existing environment or I/O area pool.
	X'40'	X'0037'	System resource bottleneck. Response: inform the system administrator.
	X'40'	X'0038'	The named FASTPAM resource can be enabled by TPR tasks only.
	X'40'	X'0039'	The named FASTPAM resource can only be enabled by tasks of an ID with FASTPAM privileges.
	X'40'	X'003D'	The user wishes to join an existing I/O area pool with some other operand value for IPOADDR.
	X'40'	X'003E'	The user wishes to join an existing I/O area pool with some other operand value for IPOSIZE.
	X'40'	X'0049'	The task is already connected to the I/O area pool.
	X'40'	X'004A'	The specified user memory area overlaps a DIV window. This return code only occurs if the environment is made resident.
	X'40'	X'004B'	The specified user memory area overlaps a FASTPAM user memory area that is already in use. This return code is only output if a resident environment or resident I/O area pool is being used.
	X'40'	X'0057'	The request to allocate memory for the I/O area pool is not complete.
	X'40'	X'005B'	The ' ENAMP' call to create the memory pool for the access lists or I/O area pool was not specified with 'FIXED=YES'. This is required even if 'SCOPE=LOCAL'.