FASTPAM function: ENABLE ENVIRONMENT

This function can be used to create a FASTPAM environment or to connect the user with an existing environment.
A FASTPAM environment ID (FPAMENID) is entered in the parameter list; this ID must 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 ENAENV function only evaluates the operands described below.

Format FCT=*ENAENV

Operation	Operands
FPAMSRV	[,FCT = *ENAENV / adr / (r)] [,ENVNAME = 'name' / adr / (r)] [,ACCLSTS = adr / (r)] [,ACCNUMB = number / adr / (r)] [,MAXIOLN = *NOT_SPECIFIED / *MINI / *MAXI / adr / (r)] [,EVENTNG = *NOT_SPECIFIED / *NO / *YESadr(r)] [,EIID = nmbr / 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

ACCLSTS

ACCLSTS specifies the 4-Kbyte-aligned starting address of the contiguous area containing all the FPAMACC parameter lists. If this area created as a memory-resident area, it must not overlap with the parameter list area of other environments, with I/O area pools, or DIV windows.

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

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.

= addr
Symbolic address (name) of the area.

= (r)
Register containing the starting address of the area.

ACCNUMB

ACCNUMB specifies the number of parameter lists contained in the area defined by ACCLSTS. This area must therefore be requested with a minimum size of ACCNUMB * (length of the FPAMACC parameter list).

If the application is not run with FASTPAM authorization, the number of parameter lists is restricted to 500; otherwise, 5000.

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

= number
Specifies the number of parameter lists to be held in the area defined by ACCLISTS (1 <= number <= 5000).

= addr
Symbolic address of a 4-byte field containing the number of parameter lists as a numeric value (binary).

= (r)
Register containing the number of parameter lists as a numeric value.

EIID

Specifies the short ID for the event item via which the end of a job is indicated during file access. This ID is returned to the user via the EIIDRET operand of the ENAEI macro (see also the “Executive Macros” manual [2]).
If the FPAMACC parameter lists are located in a memory pool, it is important to ensure that the scope of the pool is not larger than that of the event item (return code FPAMEISS).

The EIID operand is not interpreted if EVENTNG=*NO is specified.

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

= nmbr
Decimal numeric value of the short ID for the event item.

= addr
Symbolic address (name) of the 4-byte field containing the short ID for the event item.

= (r)
Register containing the short ID for the event item.

ENVNAME

Designates the name of the environment.

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

= 'name'
Name of the environment.
Name length: 1 <= 'name' <= 54 characters.
Naming conventions:
1st position: a letter or the special character #, @ (or $ for TPR tasks).
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 environment.

= (r)
Register containing the address of a 54-byte field with the name of the environment.

EVENTNG

Determines whether the end of a job is reported to the user via the eventing mechanism when files are accessed asynchronously (see also the section on “FASTPAM functions, eventing” in the “Introductory Guide to DMS” [1]).

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

= *YES
Indicates that the user wishes to work with eventing, so the short ID of the event item (operand EIID) must be specified. Subsequent OPEN calls can be made with EVENTNG=*YES as well as with EVENTNG=*NO.

= *NO
Means that files can no longer be opened with the parameter EVENTNG=*YES using this environment.

The EIID operand is not interpreted for EVENTNG=*NO.

= *NOT_SPECIFIED
Means that the environment already exists and that the user wishes to join that environment regardless of the setting for the corresponding attribute.

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

= (r)
Register containing the value for EVENTNG.

FCT

Defines the FASTPAM function to be executed.

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

= *ENAENV
Direct specification for the ENABLE ENVIRONMENT function.

This function creates a FASTPAM environment or connects the user to an existing environment.
A FASTPAM environment ID (FPAMENID) 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 ENVIRONMENT function.

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

MACID

Defines the second to the fourth character (inclusive) of the field names and equates that are generated when macros are resolved.

= PAM
Default value: MACID=PAM

= macid
“macid” is three-character string that defines the second to the fourth characters (inclusive) of the generated field names and equates.

MAXIOLN

Defines the maximum I/O length that is possible with this environment. This length must not be exceeded when accessing files, but smaller I/O lengths may be used.
When working with resident FASTPAM environments, additional system memory (class 3) is reserved for the preformatted I/O paths. The following allocation is made for each I/O path:

• 1 Kbyte with MAXIOLN = *MINI

• 2 Kbytes with MAXIOLN = *MAXI

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

= *MINI
An I/O path for 4-Kbyte transfers is created for each FPAMACC parameter list.

= *MAXI
An I/O path for 32-Kbyte transfers is created for each FPAMACC parameter list.

= *NOT_SPECIFIED
Means that the environment already exists and that the user wishes to join that environment regardless of the setting for the corresponding attribute.

= addr
Symbolic address of a 1-byte field containing the maximum I/O length for this environment.

= (r)
Register containing the value for MAXIOLN.

MF

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

PARAM

Indicates the address of the operand list. This operand is only evaluated in conjunction with MF=E (see also "Macro types").

PREFIX

Defines the first character of field names and equates that are generated when macros are expanded.

= F
Default value: PREFIX=F

= pre
“pre” is a one-character prefix with which the generated field names and equates are to begin.

RES

Specifies whether the environment is to be made resident.

= *YES
The environment 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 FPAMACC parameter list area. The size of the FPAMACC parameter list area is determined by the ACCUNUMB operand.
If the result of the check is negative, the user receives the return code “FPAMNORE”, and the FASTPAM environment is made non-resident.

= *NO
A non-resident environment is created.

= *NOT_SPECIFIED
The environment already exists, and the user wishes to join it, regardless of whether or not it was made resident.

= 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 = * ENAENV

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'0001'	Function not executed. Invalid environment name.
	X'01'	X'0005'	Function not executed. Invalid address of operand list.
	X'01'	X'0006'	Function not executed. Invalid number of operand lists.
	X'01'	X'000A'	Function not executed. Maximum permissible length of I/O area exceeded (max. 4KB or 32KB).
	X'01'	X'000B'	Function not executed. Invalid eventing.
	X'01'	X'000D'	Function not executed. Invalid event-item short-ID.
	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 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'003B'	The user wishes to join an existing environment with some other operand value for ACCLSTS.
	X'40'	X'003C'	The user wishes to join an existing environment with some other operand value for ACCNUMB.
	X'40'	X'003F'	The user wishes to join an existing environment with some other operand value for MAXIOLN.
	X'40'	X'0040'	The user wishes to join an existing environment with some other operand value for EVENTNG.
	X'40'	X'0041'	The user wishes to join an existing environment with some other event item.
	X'40'	X'0046'	The user wishes to join an existing environment, but is not connected to the associated event item short ID.
	X'40'	X'0047'	The scope of the event item is smaller than that of the FPAMACC parameter list memory area.
	X'40'	X'0048'	The task is already connected to the environment.
	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'004C'	The request to allocate memory for FPAMACC parameter lists 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' .