Processing files with FASTPAM

File format

FASTPAM will only process PAM files with BLKCTRL=NO/DATA and BLKSIZE=(STD,2n), where n=1,2,3...8. Files which do not have this format must first be converted.

FASTPAM authorization

In order to receive resident memory via FASTPAM calls, the user must be authorized for this purpose, which means that there must be an entry for the user in the user catalog (field DMS-TUNING-RESOURCES=*EXCLUSIVE in the SHOW-USER-ATTRIBUTES command or field DMS-TUNING-RESOURCES=*EXCLUSIVE-USE in the MODIFY-USER-ATTRIBUTES command). Users who do not have such authorization may also use the FASTPAM access method, but no resident areas are maintained. FASTPAM behaves like UPAM in such cases, i.e. only a small, non-resident part of the I/O path is created by the system, and the area of the parameter lists and the I/O area pool are not fixed. In other words, the path must be recreated, and user areas must be validated and fixed for each I/O. Performance gains typically achieved with FASTPAM are lost as a result.

If no memory can be made resident, FASTPAM behaves as if the required FASTPAM authorization were missing, thus offering a performance level equivalent to or better than that of UPAM.

Making memory areas resident

One of the primary purposes of FASTPAM is to enable rapid file access. This is done by making the required system environment available in resident memory before the first file is accessed.

In order to do this, the memory areas containing the user parameter lists and the I/O areas (both of which must be supplied by the user) are made memory resident by the “FASTPAM page fixing” mechanism.

This is essentially the same procedure that is performed by PPAM for the I/O area for every I/O operation when other access methods are used. The only difference with the other access methods is that the I/O area is released on completion of each I/O operation.

With FASTPAM, the user can define how long the parameter lists and the I/O area are (with ENABLE/DISABLE ENVIRONMENT and ENABLE/DISABLE IOAREA POOL) and can use them during that period. Validation is only required once at the beginning, since fixed areas cannot be released.

The ENABLE ENVIRONMENT function is also used to request the system memory that is required for I/O operations (once for each I/O operation that can be concurrently executed). A major part of this memory, i.e. the area used by IOCTRL, is always resident. This is also true for the other access methods, but the area is reallocated for each I/O and is not permanently reserved.

The rest of the system memory consists of a FASTPAM work area, which primarily contains the parameter list to call PPAM. In contrast to UPAM, if TU eventing is used, this area must also be in resident memory (since the I/O is then terminated in SIH).

The fixing of memory areas as described above is performed only if the user ID has the required FASTPAM authorization (entry in the user catalog, field DMS-TUNING-RESOURCES=*EXCLUSIVE).

If such an entry exists and if the appropriate memory areas are fixed, the resulting environment or I/O area pool is said to be “resident”.

A “resident environment” thus refers to:

• • prevalidated parameter lists in resident memory

  • system memory that is reserved in advance, and

if eventing is used:

• • a resident FASTPAM work area

Similarly, a “resident IO area pool” implies:

• • prevalidated I/O areas in resident memory

Prerequisites for resident FASTPAM areas

• The user has specified the appropriate parameters
  (macro FPAMSRV, FCT=*ENAENV/*ENAIPO, operand RES=YES)

• The user has the required FASTPAM authorization

• No data spaces are being used

• An adequate amount of main memory is available

• A sufficient number of resident pages were allocated on calling the program (command START-PROGRAM/LOAD-PROGRAM, operand RESIDENT-PAGES); when resident pages are allocated in the program call, the maximum value defined in the user catalog and the system-global limit for resident memory pages must not be exceeded.

FASTPAM macros and their functions

Two macros are available to the user for processing files: FPAMSRV and FPAMACC. These macros can be used to execute various functions and operations (see the section "FASTPAM functions", and the macro and operand descriptions in the chapter "FPAMSRV - FASTPAM management function").

The FPAMSRV macro has the following functions:

ENABLE ENVIRONMENT	Enable system environment for FASTPAM processing
ENABLE IOAREA POOL	Enable I/O area for FASTPAM processing
OPEN FILE	Open file for processing with FASTPAM
ACCESS FILE	Process a file (opened with FPAMSRV)
CLOSE FILE	Close a file (opened with FASTPAM), optionally specifying the last-page pointer
DISABLE ENVIRONMENT	Disable system environment for FASTPAM processing
DISABLE IOAREA POOL	Disable I/O area for FASTPAM processing

The following function is implemented in the FPAMACC macro:

ACCESS FILE: Process a file (opened with FPAMSRV)

Multiuser mode on one computer

A PAM file can be created and/or processed with the UPAM access method (see "UPAM - User Primary Access Method"), FASTPAM or DIV (see "DIV - Data In Virtual").

The first user (User A) can select any combination of values for OPEN and SHARUPD (in the FCB macro) when opening his PAM file. The table 2 shows which OPEN and SHARUPD combinations a second user (User B) may use to open the same (already opened) file. If a file has been opened by more than one user, the OPEN/SHARUPD combination specified by each subsequent user (User B) is compared with all the existing opens (User A). each of these comparisons must yield a positive result before the file can be opened by the next user. Illegal combinations result in an OPEN error.

The following points apply to the FASTPAM access method:

• A file can be concurrently processed with FASTPAM by multiple tasks (multiple SHARUPD=*YES and MODE=*OUTIN/*INOUT opens).

  Note

When a file is accessed in shared-update mode, appropriate synchronization routines must be supplied by the user if no such routines are built into the software product being used. In contrast to UPAM, FASTPAM does not provide any locking mechanism for this purpose.

• FASTPAM and UPAM openers

  A file can be opened in parallel by multiple tasks with FASTPAM as well as UPAM. Processing of the file is controlled by the operands MODE and SHARUPD (see below) of the OPEN function. Although FASTPAM does not support SHARUPD=WEAK, it otherwise behaves exactly like UPAM: both for FASTPAM openers exclusively and also when UPAM and FASTPAM openers are mixed. 

  When a file is concurrently accessed with UPAM and FASTPAM, the UPAM user must also synchronize operations with the FASTPAM user, since UPAM page locks are only effective when used by both sides, and since FASTPAM has no page-locking mechanism.

• FASTPAM and DIV openers

  FASTPAM interacts with DIV exactly like UPAM. Parallel processing is permitted only if the file is opened with INPUT by all users.

Compatibility matrix: FASTPAM with UPAM/FASTPAM/DIV

FASTPAM does not support SHARUPD=*WEAK

			USER B	USER B	USER B	USER B	USER B	USER B	USER B	USER B	USER B
	SHARUPD=		*YES	*YES	*YES	*NO	*NO	*NO	*WEAK	*WEAK	*WEAK
		OPEN mode	I N P U T	I N O U T	O U T I N	I N P U T	I N O U T	O U T I N	I N P U T	I N O U T	O U T I N
U S E R A	*YES	INPUT INOUT OUTIN	X O O	O O O		X			X X X
	*NO	INPUT INOUT OUTIN	X			X			X X X
	*WEAK	INPUT INOUT OUTIN	X	X		X	X		X X X	X

Table 2: FASTPAM: Permissible SHARUPD/OPEN combinations 

X: OPEN permitted

O: OPEN permitted only

• • if the same block-oriented access method is used by all (either UPAM/FASTPAM or DIV)

  • and the same value is used by all for the LOCKENV operand
    (either LOCKENV=*HOST or LOCKENV=*XCS)

  • and all are running on the same host or, with LOCKENV=*XCS, in an XCS network

Comments

• Read operations with SHARUPD=*WEAK may have opened a file simultaneously with any write operation (SHARUPD=*WEAK is only possible with UPAM and DIV).

  Exception:
  Parallel opening with a UPAM/FASTPAM write operation is not allowed for read operations with DIV-SHARUPD=*WEAK and which specified LOCVIEW=*MAP with OPEN.

  Read operations with DIV-SHARUPD=*WEAK and which specified LOCVIEW=*NONE with OPEN possess the same compatibility as read operations with UPAM/FASTPAM-SHARUPD=*WEAK.

• Openers with DIV-SHARUPD=*YES are not compatible to openers with UPAM/FASTPAM-SHARUPD=*YES.

• Read operations are always compatible to each other (regardless of access method, SHARUPD specification, LOCKENV specification and host).

• Illegal combinations lead to an OPEN error. 

• SHARUPD=*YES:
  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).

Multiuser mode with multiple systems

A multisystem environment is a configuration in which several systems are interlinked by means of shareable private disks (see the chapter “Volumes” in the “Introductory Guide to DMS” [1]) or shared pubsets. The table 2 shows the permissible combinations for access from two different systems.

The following points are relevant for the FASTPAM access method: A multisystem environment is a configuration in which several systems are interlinked by means of shared pubsets.

• Files on shared pubsets (shared PVS) are supported by FASTPAM: FASTPAM openers can access a shared PVS from different systems and read from it concurrently and can also read in parallel with UPAM and DIV openers.

• Remote file access (RFA) is not supported.

Data consistency

• Data consistency in multiuser mode

  The FASTPAM access method does not provide a synchronization mechanism for shared access to a file (shared-update mode). Appropriate synchronization routines must therefore be supplied by the user if no such routines are included in the software product being used.
  If FASTPAM, UPAM and DIV applications are all operating in shared-update mode, a common synchronization mechanism must be used for all accesses

• Data consistency following a system crash

  If an error occurs during an ACCESS FILE job, it is not possible to specify whether and how much data has been transferred. The writing of a block cannot be treated as an atomic operation. The contents of the file may be inconsistent in such cases. 

Summary of functional differences between UPAM and FASTPAM

• FASTPAM can only be used to process PAM files with the following file attributes:

  • BLOCK-CONTROL-INFO=NO

  • BUF-LEN = an even number

• FASTPAM supports I/Os in data spaces.

• The following functions are not supported by FASTPAM:

  • DUMMY files

  • tape processing

  • RFA

• FASTPAM supports synchronous and asynchronous read and write operations. The following operations are offered by UPAM, but are not supported by FASTPAM:

  • CHK

  • LOCK / UNLOCK

  • LRD / LRDWT / WRTWU

  • SETL

  • SYNC

• The functionality of the UPAM operation SETLPP is included in the framework of FASTPAM-CLOSE processing.

• The function SHARUPD=*WEAK is not supported (see also "Compatibility matrix: FASTPAM with UPAM/FASTPAM/DIV").

• An implicit WAIT is not possible.

• Within an OPEN/CLOSE bracket asynchronous I/Os can either be terminated only by WAIT, or their termination can be reported only via the eventing mechanism.

• It is not possible to specify a relative page number.