Create ISAM pool or attach task to ISAM pool
Component: | BS2000 |
Functional area: | File processing |
Domain: | FILE |
Privileges: | STD-PROCESSING |
Function
The CREATE-ISAM-POOL command enables the user to create an ISAM pool or to link his or her job (task) with any existing ISAM pool that was created with system-wide scope.
Every ISAM pool is uniquely identified by the following attributes, which are specified at the time that the ISAM pool is created:
The name of the ISAM pool (POOL-NAME operand)
The catalog ID of the pubset (CAT-ID operand)
Its scope of applicability (SCOPE operand)
The type of buffering (WRITE-IMMEDIATE operand)
Its size (SIZE operand).
Its performance attribute (RESIDENT operand)
If the task is to be linked with an existing ISAM pool, there should be no conflict between the specifications in the CREATE-ISAM-POOL command and the attributes of the existing ISAM pool. The existing attributes of a previously created ISAM pool can be displayed by using the SHOW-ISAM-POOL-ATTRIBUTES command.
Note for ISAM pools
As of BS2000/OSD V6.0B cross-task ISAM pools are automatically created on a file specific basis when a file is opened in a data space. The CREATE-ISAM-POOL command with SCOPE=*USER-ID/*USER-GROUP is only supported for reasons of compatibility and has the same effect as SCOPE=*HOST-SYSTEM (for details on ISAM pools in data spaces see the “Introductory Guide to DMS” [13]).
NK-ISAM files in NK2 and NK4 format
NK-ISAM files in both NK2 format as well as NK4 format can be processed via the ISAM pool. When the first NK-ISAM file to be processed is opened, the ISAM pool is formatted in accordance with that file. If an NK-ISAM file in another format is then opened via the same ISAM pool, the ISAM pool is extended dynamically by an extent equal to its previous size and is formatted according to the new file to be processed. In other words, after the extension, the ISAM pool will consist of one extent for processing NK2-ISAM files and one for processing NK4-ISAM files, thus doubling the actually required memory space to twice the SIZE specification.
To prevent the resulting degradation in performance, it is therefore advisable to only process files of the same format via an ISAM pool.
A detailed description of ISAM pools can be found in the “Introductory Guide to DMS” [13].
Format
CREATE-ISAM-POOL | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
POOL-NAME = <name 1..8>
Assigns a name to the ISAM pool which is to be created or which already exists, and to which the task is to be linked. Together with its catalog ID and scope, this allows the pool to be uniquely identified.
CAT-ID = *DEFAULT-PUBSET / <alphanum-name 1..4>
Specifies the catalog ID of the pubset to which the ISAM pool is to be assigned.
The ISAM pool will be set up on the host computer to which this pubset belongs.
The catalog ID can – as in the file name – be regarded as part of the name, i.e. different catalog IDs identify different ISAM pools.
CAT-ID = *DEFAULT-PUBSET
The ISAM pool is assigned to the catalog that was set with the system parameter ISPLDEFC (ISAM-POOL-DEFAULT-CATID):
X'00': | default catalog ID from the user entry (see the SHOW-USER-ATTRIBUTES command, output field DEFAULT-PUBSET) |
X'01': | catalog ID of the home pubset |
CAT-ID = <alphanum-name 1..4>
The catalog ID of the pubset to which the ISAM pool is to be assigned.
SCOPE = *TASK(...) / *USER-ID(...) / *USER-GROUP(...) / *HOST-SYSTEM(...)
Specifies the scope of the ISAM pool and governs the possible users:
task-local, i.e. only for the creating task
cross-task, for all the tasks of the system
The scope identifies the ISAM pool uniquely, i.e. ISAM pools that have the same name and same catalog ID but different scopes are not the same.
SCOPE = *TASK(...)
The ISAM pool can only be used by the calling job: it is task-local.
WRITE-IMMEDIATE = *NO / *YES
Specifies whether the blocks which are buffered in the ISAM pool are to be written out immediately after any change, or only when the buffer is required for another block.
WRITE-IMMEDIATE = *NO
For files which are to be processed in this pool, any WRITE-IMMEDIATE specification in an ADD-FILE-LINK command, or as specified in the FCB in the program, will apply. If these contain no specification, then *NO will be applicable.
WRITE-IMMEDIATE = *YES
For all the files to be processed in this pool, the WRITE-IMMEDIATE function will apply: any amended blocks will immediately be written back to the disk.
It should be noted that this will greatly increase the input/output rate, and performance will be reduced.
SCOPE = *HOST-SYSTEM(...)
The ISAM pool is cross-task and can be used by any job (task).
WRITE-IMMEDIATE = *YES / *NO
Specifies whether the blocks which are buffered in the ISAM pool are to be written out immediately after any change, or only when the buffer is required for another block.
WRITE-IMMEDIATE = *YES
Activates the WRITE-IMMEDIATE function for all files processed in this pool. In other words, updated blocks are written back to disk immediately.
WRITE-IMMEDIATE = *NO
Modified blocks are not written back to disk until the buffer is required for another block. WRITE-IMMEDIATE=*NO must be defined in the ADD-FILE-LINK command for any file to be processed via this ISAM pool; otherwise, the file cannot be opened.
CREATION-MODE = *ANY / *NEW
Specifies whether the user wishes to establish a new ISAM pool, or whether a link to an ISAM pool with the same name and catalog ID, which may already exist, may be established.
CREATION-MODE = *ANY
If there is already a cross-task ISAM pool with the same name and catalog ID, the job is linked to this pool. The specified SIZE of the pool is not taken into account.
If no such ISAM pool currently exists, a new pool is set up with the size defined in SIZE.
CREATION-MODE = *NEW
A new ISAM pool is to be created. However, if a cross-task ISAM pool with the same name and catalog ID already exists, the command will be rejected with an error message.
SCOPE = *USER-ID(...) / *USER-GROUP(...)
The ISAM pool can be used by all jobs (tasks) which belong to the same user group as the task which created it. For a description of the lower-level operands WRITE-IMMEDIATE and CREATION-MODE see SCOPE=*USER-ID.
SIZE = *STD / <integer 32..32767 2Kbyte >
Defines the size of the new ISAM pool to be created.
SIZE = *STD
A task-local ISAM pool is set up with the default size defined in the ISAM parameter LCLPS in the parameter service. An ISAM pool which is cross-task is set up with the size defined in the ISAM parameter GLBPS.
SIZE = <integer 32..524288>
Defines the size of the ISAM pool to be created in units of 2 Kbytes (PAM pages).The following are possible size specifications:
32 <= SIZE <= 32767 | for ISAM pools which are cross-task |
32 <= SIZE <= 8192 | for task-local ISAM pools |
The specified SIZE is rounded internally if required. The rounded value for SIZE is shown in the output of the SHOW-ISAM-POOL-ATTRIBUTES command.
The minimum size of 32 PAM pages means that files with logical blocks of no more than STD(6) can be processed. An ISAM pool of 96 PAM pages is required for files with logical blocks of size STD(16).
NK-ISAM files in both NK2 format as well as NK4 format can be processed via the ISAM pool. When the first NK-ISAM file to be processed is opened, the ISAM pool is formatted in accordance with that file. If an NK-ISAM file in another format is then opened via the same ISAM pool, the ISAM pool is extended dynamically by an extent equal to its previous size and is formatted according to the new file to be processed. To prevent a degradation in performance, only files of one format should be processed via an ISAM pool.
RESIDENT = *NO / *YES
Performance attribute of the ISAM pool.
Specifies whether the ISAM pool is to be created as a memory-resident pool if the appropriate resources are currently available.
If the task is to be linked to an existing ISAM pool, this specification must match the performance attribute defined for that pool.
RESIDENT = *NO
The memory pages of the ISAM pool are pageable.
RESIDENT = *YES
This specification is only possible for users who have the DMS tuning privilege CONCURRENT-USE or EXCLUSIVE-USE for the pubset (see the output fieldDMS-TUNING-RESOURCES in the output of the SHOW-USER-ATTRIBUTES command). Depending on the currently available resources, the memory pages of the ISAM pool are kept resident in memory as far as possible.
Return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
|---|---|---|---|
0 | CMD0001 | Command executed without errors | |
32 | DMS0A17 | Internal system error | |
64 | DMS0A0E | Syntax error in ISAM pool command | |
64 | DMS0A11 | Specified catalog ID does not exist | |
64 | DMS0A13 | Specified pool name is syntactically invalid | |
64 | DMS0A15 | Specified ISAM pool already exists | |
64 | DMS0A18 | Size of ISAM pool invalid | |
64 | DMS0A1E | Not authorized for resident pool | |
64 | DMS0A1F | RESIDENT parameters incompatible | |
64 | DMS0A20 | Parameters not permitted for remote BS2000 version | |
64 | DMS0A21 | ISAM pool limit reached | |
64 | DMS0A22 | User group does not exist | |
130 | DMS0A12 | Specified catalog ID not available | |
130 | DMS0A14 | Shortage of memory space for CREATE-ISAM-POOL |
Example
Connecting a task to several ISAM pools
/show-isam-pool-attr pool=*all —————————————————————————————— (1)
% % CATID POOLNAME SCOPE WROUT SIZE EXTENTS RESIDENT %===================================================================== % 1OSB SDFPOOLN TASK NO 128 --/-- NO %
/cre-isam-pool pool-name=poolab01,scope=*host ————————————————————— (2)/cre-isam-pool pool-name=poolab01,scope=*task ————————————————————— (3)/show-isam-pool-attr pool=*all —————————————————————— (4)
% % CATID POOLNAME SCOPE WROUT SIZE EXTENTS RESIDENT %===================================================================== % 1OSB SDFPOOLN TASK NO 128 --/-- NO % N POOLAB01 HOST YES 96 --/-- NO % N POOLAB01 TASK NO 96 --/-- NO %
/show-isam-pool-attr pool=poolab01(scope=host),inf=*user-and-attr —— (5)
% % CATID POOLNAME SCOPE WROUT SIZE EXTENTS RESIDENT %===================================================================== % N POOLAB01 HOST YES 96 --/-- NO % %------------------- CONNECTED TASKS --------------------------------- % TSN = 1EUW % TSN = 1EUE %--------------------------------------------------------------------% %
/show-isam-pool-attr pool=poolab01(scope=*task),inf=*user-and-attr ——— (6)
% % CATID POOLNAME SCOPE WROUT SIZE EXTENTS RESIDENT %===================================================================== % N POOLAB01 TASK NO 96 --/-- NO % %------------------- CONNECTED TASKS --------------------------------- % TSN = 1EUE %--------------------------------------------------------------------%
(1) | Returns information on all ISAM pools to which the task is connected. There is one existing task-local ISAM pool: SDFPOOLN. |
(2) | Connects the task to the cross-task ISAM pool POOLAB01. |
(3) | Connects the task to the task-local ISAM pool POOLAB01. The task-local ISAM pool has the same name as the host-specific ISAM pool; however, the name is considered unique, since the scope differs. |
(4) | Returns information on all ISAM pools to which the task is connected. The output shows that there are three existing ISAM pools: one named SDFPOOLN and two with the name POOLAB01, of which one is cross-task, and one is task-local. It is evident that no file has been processed with these ISAM pools, since the EXTENTS output column does not contain any formatting information. |
(5) | Shows the attributes and the connected task for the cross-task ISAM pool POOLAB01. Two tasks are connected to this pool: the ISAM pool which was created earlier by the task with TSN 1EUW, and the user’s own TSN 1EUE, which is shown as the second task (see also Point 6). |
(6) | Shows the attributes and the connected task for the task-local ISAM pool POOLAB01. As expected, only the users’ own task (TSN 1EUE) can be connected to the pool in this case. This ISAM pool was created using the CREATE-ISAM-POOL command (see Point 3). |