Start PFA caching for open file
Component: | BS2000 |
Functional area: | File processing |
Domain: | FILE |
Privileges: | STD-PROCESSING |
Function
The START-FILE-CACHING command starts caching for a file that is already open for processing. The file has to be on a pubset for which a cache configuration is defined in the MRSCAT and the cache has to be active, i.e. PFA caching for the pubset has to be activated.
Caching can be activated later for files for which no appropriate cache medium was available or was requested when the OPEN was issued (the first OPEN in the case of shared update processing). The performance requirements for input/output operations are defined through the IO-ATTRIBUTES operand which is validated and output in the same way as when OPEN is issued (see ADD-FILE-LINK command).
The command is rejected in the following situations:
The caller is not authorized to access the file.
The file is not open on the local host.
No PFA cache area is available.
The file is already being cached.
The file is on a private disk or on a tape.
An XCS lock exists for the file.
The specified cache settings are not possible or not allowed.
Format
START-FILE-CACHING | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
Operands
FILE-NAME = <filename 1..54>
Name of the file to be cached. The file has to be open and on a pubset that is locally accessible.
IO-ATTRIBUTES = *PARAMETERS(...)
Specifies the performance requirements demanded by the user for input/output operations. Whether the requirements are fulfilled and to what extent depends on the cache medium active for the pubset (see the output for the SHOW-PUBSET-CACHE-ATTRIBUTES or SHOW-PUBSET-PARAMETERS command). Read and write access is performed through a fast cache. The number of disk accesses and the access times are reduced.
IO-ATTRIBUTES = *PARAMETERS(...)
The specifications made for the PERFORMANCE and USAGE operands determine the performance attributes.
PERFORMANCE = *HIGH / *VERY-HIGH / *USER-MAXIMUM
Specifies the file’s performance attribute. This operand defines the priority requested for the input/output operations named in the USAGE operand. The highest performance operand allowed for files that are located on a PFA pubset with CACHED-FILES=*BY-USER (see the MODIFY-PUBSET-CACHE-ATTRIBUTES command) is defined in the user entry (see output for the SHOW-USER-ATTRIBUTES command, output field DMS-TUNING-RESOURCES).
PERFORMANCE = *HIGH
The file is to be processed through a cache (high performance priority).
This value can only be specified for a file on a PFA pubset with CACHED-FILES=*BY-USER if the user has the DMS tuning privilege CONCURRENT-USE or EXCLUSIVE-USE for the pubset (see the output for the SHOW-USER-ATTRIBUTES command, output field DMS-TUNING-RESOURCES).
PERFORMANCE = *VERY-HIGH
The file is to be processed through a cache. The referenced data in the file is to be kept permanently in the cache (highest performance priority; only available in GS). The cache data is only evicted from the cache when the file is closed. Only users who have the DMS tuning privilege EXCLUSIVE-USE for the pubset can specify (see the output for the SHOW-USER-ATTRIBUTES command, output field DMS-TUNING-RESOURCES).
Note
All cache segments used for this file are locked until the file is closed. If several files with this attribute are open simultaneously, the cache space available for files that are cached normally may become restricted to an extent that they cannot be accessed with reasonable speed.
PERFORMANCE = *USER-MAXIMUM
The file is assigned the highest performance attribute contained in the user catalog for the user. If the user does not have the DMS tuning privilege, the command is rejected.
USAGE = *READ-WRITE / *WRITE / *READ
Specifies for which input/output operations high performance requirements (processing via cache) are wanted. The default setting is *READ-WRITE, i.e. the requirements apply to read and write operations.
If the file does not have a particular performance attribute (PERFORMANCE= *STD) and if the cache area for the pubset is not defined in such a way that all existing files are served (see the operand CACHED-FILES=*ALL for the MODIFY-PUBSET-CACHING-ATTRIBUTES command), then the USAGE operand has no effect on processing.
USAGE = *READ-WRITE
The performance requirements apply both to read and to write operations.
USAGE = *WRITE
The performance requirements apply to write operations only.
USAGE = *READ
The performance requirements apply to read operations only.
Note
In the case of USAGE=*READ-WRITE or *WRITE, write caching is only performed if the prerequisites for the DISK-WRITE file attribute are met (see CREATE-FILE or MODIFY-FILE-ATTRIBUTES). In the case of DISK-WRITE= *IMMEDIATE, the cache medium used for write caching has to be failsafe (see the output for the command SHOW-MASTER-CATALOG-ENTRY INFORMATION=*USER, output field CACHE-MEDIUM).
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed | |
1 | 0 | CMD0001 | The desired state was already reached |
1 | CMD0202 | Syntax error | |
32 | DMS1D0E | MSCF connection error | |
32 | DMS1D10 | Internal error | |
64 | DMS1D03 | User does not have access authorization for the file | |
64 | DMS1D05 | File not open (on local host) | |
64 | DMS1D06 | No cache available | |
64 | DMS1D07 | No user privilege for increased performance | |
64 | DMS1D08 | Caching no allowed for this file | |
64 | DMS1D09 | File is processed with XCS environment | |
64 | DMS1D0A | File not allowed (or not available) | |
64 | DMS1D0B | Data backup must not be left until close | |
64 | DMS1D0D | Storage bottleneck | |
64 | DMS1D0F | Error in catalog management call | |
64 | DMS1D11 | ’DAB’ subsystem not found |