The functions of the FASTPAM access method are implemented in the macros FPAMSRV and FPAMACC. These functions are as follows:
Function | Meaning |
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 |
Enabling the system environment for FASTPAM processing (macro function FCT=*ENAENV)
The ENABLE ENVIRONMENT function (macro FPAMSRV, operand FCT=*ENAENV) enables a user to create a FASTPAM environment or join an existing one. The caller is returned a task-specific environment short ID which can be used to refer to the environment in subsequent OPEN calls.
Since a FASTPAM environment is uniquely identified by its name and scope, and the scope is implicitly derived from the address of the FPAMACC parameter lists, the name as well as the address of the parameter lists must be specified in each ENABLE-ENVIRONMENT call. The other attributes need not be specified when joining an existing environment. If they are specified, however, they must match the corresponding values for the existing environment.
If the user has FASTPAM authorization, the entire class 3 memory area required for disk access is generated in advance, and the area of the FPAMACC parameter list is fixed.In order to do this, the address of the parameter list area, the number of parameter lists, and the maximum transfer length used for later file access are required.
The only values permitted for the transfer length are 4 KB and 32KB. A value of 32KB should be used only if the number of parallel access operations is not too high, since 2KB of resident system memory is used for each I/O path. The logical block size of files subsequently opened with this environment and the I/O length of the following file accesses must not exceed this maximum value.
Users who wish to work with eventing must specify the short ID of the event item at the time of creating the environment.
The parameter list area must be requested in advance and must allow write access. When the FASTPAM environment is being created by the first environment user (i.e. when the ENABLE ENVIRONMENT call is being processed), no I/O is permitted on any page that overlaps the parameter list area.
Enabling the I/O area for FASTPAM processing (macro function FCT=*ENAIPO)
The ENABLE IOAREA POOL function (macro FPAMSRV, operand FCT=*ENAIPO) enables a user to create a FASTPAM I/O area pool or join an existing one. Given the appropriate FASTPAM authorization, the operating system “fixes” the specified memory area and returns to the caller a task-specific I/O area pool short ID which can be used to refer to the pool in subsequent OPEN FASTPAM calls.
Like the FASTPAM environment, an I/O area pool is also identified uniquely by its name and scope. The attributes of the I/O area pool are fixed at the time it is created and cannot be changed, so no deviating attributes may be specified by other users of the same I/O area. The I/O area pool is typically joined by specifying just the name and the address.
The memory area must be requested in advance and must allow write access. When the FASTPAM I/O area pool is being created by the first I/O area user (i.e. when the ENABLE-IOAREA-POOL call is being processed), no I/O is permitted on any page of the I/O area pool.
Opening files for processing with FASTPAM (macro function FCT=*OPEN)
The short IDs obtained from ENABLE ENVIRONMENT and ENABLE IOAREA POOL can be used by any task to open any number of files.
If the environment is associated with an event item, each file can be opened by using the FPAMSRV macro with the operand FCT=*OPEN, EVENTNG=*YES. Every asynchronous ACCESS job is then acknowledged via the event item. Otherwise, each asynchronous job must be explicitly terminated by the user with a WAIT operation. Synchronous jobs are treated identically in both cases.
The access mode (read or write) can be defined with the MODE operand, and the SHARUPD operand can be used to define multiuser mode. The BLKSIZE operand determines the granularity of subsequent file access operations.
The LARGE_FILE operand specifies whether the file that is to be opened may grow to become a “large file” with a file size >= 32 GB.
For each OPEN that is completed without error, the user is returned an OPEN short ID, which must be specified for following ACCESS FILE jobs.
As in the case of UPAM, parameter values specified in a previously issued ADD-FILE-LINK call override the values specified in the *OPEN call. If these values are not permitted for the FASTPAM-OPEN, the *OPEN call is rejected.
Processing a file opened with FPAMSRV (macro FPAMACC)
The FPAMACC macro can be used to write to the file and read from it. The file, its associated environment, and the I/O pool are identified by the OPEN short ID. I/O requests can be submitted both synchronously and asynchronously.
Synchronous operations are:
READ AND WAIT
WRITE AND WAIT
READ AND EQUALIZE
Asynchronous operations are:
READ
WRITE
The WAIT operation is used to wait for the end of asynchronous jobs, i.e. jobs which are not executed synchronously.
In order to enable users to make efficient use of cached files, FASTPAM closes synchronously executed asynchronous jobs completely and does not send any signal to the event item when eventing is used. No WAIT macro (for eventing: no SOLSIG call) may be issued following a synchronously executed job.
The I/O length must be a multiple of BLKSIZE and must not exceed the value specified for MAXIOLN. In addition, specifications for the logical block within the file (BLOCK) and the address of the I/O buffer (IOAREA) are also required.
In order to avoid SVCs, job chaining is also supported. The CHAIN operand may be used to concatenate up to 5000 FPAMACC lists.
Eventing
Like UPAM, FASTPAM supports event-driven processing of I/O requests (see also section "TU eventing: event-driven processing" and the “Executive Macros” manual [2]). If a job is not terminated synchronously, FASTPAM sends a message to the associated event item on completion of an I/O operation. This message can be retrieved by the user with the SOLSIG macro. The message is sent if EVENTNG=YES is specified; no message is sent if EVENTNG=NO. A WAIT macro must be issued in any case.
Closing a file opened with FASTPAM (macro function FCT=*CLOSE)
The CLOSE function (macro FPAMSRV, operand FCT=*CLOSE) is used to close a file that was open. The file is identified by the OPEN short ID in this case as well.
Disabling the system environment for FASTPAM processing (macro function FCT=*DISENV)
The DISABLE ENVIRONMENT function (macro FPAMSRV, operand FCT=*DISENV) is used to disconnect a task from a FASTPAM environment that is specified by means of a short ID. When the last task is disconnected, the environment is disabled, but no user memory is released.
Disabling the IOAREA for FASTPAM processing (macro function FCT=*DISIPO)
The DISABLE IOAREA POOL function (macro FPAMSRV, operand FCT=*DISIPO) is used to disconnect a task from an I/O area pool specified by a short ID. When the last task is disconnected, the I/O area pool is disabled, but no user memory is released.