FASTPAM function: OPEN

This function can be used to open a PAM file with the short IDs returned by ENABLE ENVIRONMENT and ENABLE IOAREA POOL.
A short ID (FPAMOPID) is returned in the parameter list. This ID must be copied to the FPAMACC parameter lists for all following accesses to the file.

The OPEN function only evaluates the operands described below.

Format FCT=*OPEN

Operation	Operands
FPAMSRV	[,FCT = *OPEN / adr / (r)] [,ENVID = nmbr / adr / (r)] [,IPOID = nmbr / adr / (r)] [,LINK = 'name' / adr / (r)] [,FILE = 'pathname' / adr / (r)] [,SHARUPD = *NO / *YES / adr / (r)] [,MODE = *INPUT / *INOUT / *OUTIN / adr / (r)] [,EVENTNG = *NO / *YES / adr(r)] [,BLKSIZE = size / adr / (r)] [,ENV = *HOST / *XCS / adr / (r)] [,LARGE_FILE = *FORBIDDEN / *ALLOWED / 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

BLKSIZE

Defines the block size for following I/O operations in 4K units. The value specified for BLKSIZE must not exceed the maximum value that was defined for the MAXIOLN parameter in the ENABLE ENVIRONMENT function.

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

= size
Specifies the block size in 4K units: 1 <= size <= 8

= addr
Symbolic address of a 1-byte field containing the block size in 4K units (binary).

= (r)
Register containing the block size in 4K units.

ENV

Affects the compatibility of parallel openers dependent on their execution location (cf. “Compatibility matrix: FASTPAM with UPAM/FASTPAM/DIV” in chapter Processing files with FASTPAM).

= *HOST
The maximum permissible parallelism is limited to openers running on the same host.

= *XCS
The openers can run in different hosts in an XCS network without restricting the compatibility (e.g. write operations with SHARUPD=*YES can run in parallel).

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

= (r)
Register containing the value for ENV.

ENVID

Designates the short ID of the environment with which the file is to be opened. If the same parameter list is used as for ENABLE ENVIRONMENT, the short ID will have already been entered in the parameter list (FPAMENEV) and need not be taken into account.

The ENVID specification is not allowed for the MF=L form.

= nmbr
Direct entry of the short ID as a decimal numeric value.

=addr
Address of a 4-byte field containing the short ID.

=(r)
Register containing the short ID.

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. This value will only be accepted if EVENTNG=*YES was specified when creating the environment.

= *NO
Indicates that the user does not wish to work with eventing.

= 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.

= *OPEN
Direct specification of the OPEN function.
This function can be used to open a PAM file with the short IDs returned by ENABLE ENVIRONMENT and ENABLE IOAREA POOL.
A short ID (FPAMOPID) is returned in the parameter list. This ID must be entered in the FPAMACC parameter lists for all following accesses to the file.

= addr
Symbolic address of a 1-byte field with the value for the OPEN function.

= (r)
Register containing the value for the OPEN function.

FILE

Specifies the path name of the file. The FILE specification is not evaluated if a value has been specified for the LINK operand.

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

= 'pathname'
<c-string 1..54: filename 1..54>.
The name must be enclosed in single quotes.

= addr
Address of a 54-byte field containing the path name.

= (r)
Register containing the field with the address of the path name.

IPOID

Designates the short ID of the I/O area pool with which the file is to be opened. If the same parameter list is used as for ENABLE IOAREA POOL, the short ID will have already been entered in the parameter list (and is hence not required).

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

= nmbr
Short ID of the I/O area pool as a decimal numeric value.

= addr
Address of a 4-byte field containing the short ID.

= (r)
Register containing the short ID.

LARGE_FILE

Specifies whether the file that is to be opened can grow to become a “large file” with a file size >= 32 GB.

Default value:

LARGE_FILE = *FORBIDDEN

In the case of MF=L, only direct specification is permitted.

= *FORBIDDEN
The file may not become a “large file”.

= ALLOWED
The file may become a “large file”.

= addr
The address of an 8-byte field that contains the value for LARGE_FILE.

= (r)
Register containing the address of an 8-byte field with the value for LARGE_FILE.

LINK

Specifies the file link name.

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

= 'name'
File link name with: <c-string 1..8> (enclosed in single quotes)

If the file link name is to be accessed via the command interface it must correspond to the data type <structured_name 1..8> (see the “Commands” manual [3]).

= addr
Address of an 8-byte field containing the file link name.

= (r)
Register containing the address of the field with the file link name.

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 on "Macro types".

MODE

Defines the OPEN mode (see the sections “Multiuser mode on one computer” in chapter Processing files with FASTPAM ).

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

= *INPUT
The file can only be read.
Parallel INPUT opens are possible, even with the UPAM and DIV access methods, regardless of the SHARUPD mode.
The file must exist, i.e. must have been opened once with OUTIN.

= *INOUT
The file can also be written to.
The SHARUPD mode and ENV operand determine whether parallel opens are possible.
The file must exist, i.e. must have been opened once with OUTIN.

= *OUTIN
The file can also be written to.
It is, however, recreated, i.e. will be empty after the OPEN.
The SHARUPD mode and DIV operand determine whether parallel opens are possible.In multi-user mode (SHARUPD=*YES), any user who wishes to open the file with MODE=*OUTIN must always be the first user to do so; otherwise, access will be denied.

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

= (r)
Register containing the value for the OPEN mode.

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".

SHARUPD

Controls multi-user mode (see also the section on “FASTPAM functions, multi-user mode...” in the “Introductory Guide to DMS” [1]).

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

= *NO
The file can be concurrently read by more than one user (MODE=*INPUT) or can be written to by exactly one user (MODE=*INOUT | *OUTIN).

= *YES
The file can be concurrently read and written by multiple users.

Notes

FASTPAM does not provide any “block-locking” mechanism (LOCK/UNLOCK functions). An appropriate locking mechanism must therefore be supplied by the user. Concurrent access by UPAM applications must be synchronized differently.

The file size is checked whenever the allocator is called.
If this check indicates a file size >= 32 GB and the attribute LARGE_FILE=*FORBIDDEN is set in the associated FCB or the attribute EXCEED-32GB=*FORBIDDEN is set in the TFT then processing is canceled. In this case, FASTPAM returns the code X'00400145' in its local parameter list FPAMACC(I).

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

= (r)
Register containing the value for SHARUPD.

Possible return codes of the FASTPAM function FCT=*OPEN

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'0009'	Function not executed. Invalid specification for SHARE UPDATE max. 4K or 32K
	X'01'	X'000B'	Function not executed. Invalid eventing.
	X'01'	X'000C'	Function not executed. Invalid specification for MODE
	X'01'	X'000E'	Function not executed. Invalid specification for logical block length (BLKSIZE). Note The BLKSIZE is specified in 2-Kbyte units in the ADD-FILE-LINK command; the value specified there is therefore equivalent to half the block size specified in the FASTPAM OPEN.
	X'01'	X'000F'	Function not executed. Invalid short ID for environment.
	X'01'	X'0010'	Function not executed. Invalid short ID for I/O area pool.
	X'01'	X'0014'	Function not executed. Invalid ENV specification.
	X'01'	X'0015'	Function not executed. Invalid LARGE_FILE specification.
	X'20'	X'0028'	Function not executed. System error. Run system diagnostics.
	X'40'	X'0033'	General DMS error during OPEN/CLOSE. The DMS return code is passed in the field FPAMDMSC. Response: evaluate DMS return code.
	X'40'	X'0037'	System resource bottleneck. Response: inform the system administrator.
	X'40'	X'0042'	The value specified for BLKSIZE in the FASTPAM OPEN does not match the value in the catalog entry.
	X'40'	X'004D'	The named file is not a PAM file.
	X'40'	X'0050'	RFA is not supported by FASTPAM.
	X'40'	X'0051'	SPD is not supported by FASTPAM.
	X'40'	X'0052'	PPD is not supported by FASTPAM.
	X'40'	X'0053'	Tape files are not supported by FASTPAM.
	X'40'	X'0054'	*DUMMY is not supported by FASTPAM.
	X'40'	X'0055'	The specified secondary allocation is too small for a logical block.
	X'40'	X'0056'	An unprivileged user has specified the short ID of an environment or I/O area pool that was created by a privileged user.
	X'40'	X'0058'	FASTPAM only supports files with the attribute 'BLKCTRL = NO'.
	X'40'	X'005A'	'WRCHK=YES' was specified in a call to FILE.