Macro type: type S (E form/L form/D form/C form); see "Macro types"
The CREPOOL macro creates a task-specific, host-specific, or user ID-specific ISAM pool or links a job to an existing ISAM pool. The ISAM pool is unambiguously identified by the following characteristics:
its pool name: operand NAME
its catalog ID: operand CATID
its scope: operand SCOPE
its size: operand SIZE
type of buffering: operand WROUT
performance characteristic of the ISAM pool: operand RESDNT
The CREPOOL macro may be used only for XS programming (31-bit interface).
Note
Cross-task ISAM pools are created automatically in a data space on a file-specific basis when the file is opened.
SCOPE=USERID and SCOPE=USERGROUP, which were available up to BS2000/OSD V6.0A, are still accepted for reasons of compatibility, but are mapped internally to SCOPE=HOST (cross-task ISAM pool).
For further information on ISAM pools in data spaces please refer to the “Introductory Guide to DMS” [1].
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
CATID = catid
Specifies the catalog ID of the pubset to which the ISAM pool is to be assigned. The ISAM pool is created 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.
Default value: | the default catalog ID of the calling job. |
MACID
Evaluated only in conjunction with MF=C; defines the second through fourth characters of each field name and equate generated in the data area when the macro is expanded.
Default setting: | MACID = ISC |
= macid
Three-character string defining the second through fourth characters of each field name and equate generated.
MF
The forms of the MF operand are described in detail in the appendix (see "Macro types").
MODE
Specifies, for cross-task ISAM pools, whether the user wants to create a new ISAM pool or whether a link to any existing ISAM pool with the same name and the same catalog ID may be established.
By default, DMS always links the job to an existing ISAM pool with the specified name.
= ANY
If a cross-task ISAM pool with the same name and the same catalog ID has already been created by another task, the job is linked to this pool, even if the value specified for SIZE does not match the actual pool size.
If no such ISAM pool exists, a new pool with the size specified in SIZE is created.
The parameter CREATION-MODE=ANY can be used to set up an exclusive connection to an ISAM pool that was created by some other task. This means that if a task issues a CREPOOL with CREATION-MODE=ANY more than once in succession for one ISAM pool, the second call (and all others) will be rejected with an error message even if the ISAM pool already exists as a result of the first call. This in turn implies that an exclusive ISAM pool can be created within a task only if the pool does not exist for that task.
= NEW
A new cross-task ISAM pool is to be created. If, in this case, a host-specific ISAM pool with the same name and the same catalog ID already exists, the command is rejected with an error message.
NAME = poolname
Assigns a name to the ISAM pool. This, together with the catalog ID and the scope, uniquely identifies the pool.
“poolname” may be 1-8 characters long and may contain all letters and digits and the special characters $, # and @; the first character of “poolname” must be a letter or the special character # or @.
PARAM
Specifies the address of the operand list; evaluated only in conjunction with MF=E (see "Macro types").
= addr
Symbolic address (name) of the operand list.
= (r)
Number of the register containing the address of the operand list. The register must be loaded with this address value before the macro is called.
PREFIX
Evaluated only in conjunction with MF=C or MF=D; defines the first character of each field name and equate generated in the data area when the macro is expanded.
Default setting: | PREFIX = D |
= pre
Single-character prefix with which the field names and equates generated by the assembler are to begin.
RESDNT
Specifies whether the pages of an ISAM pool are to be maintained in resident working memory (as defined in the function $CSTAT):
= NO
Specifies that the pages of the ISAM pool to be created are not to be maintained in resident memory.
= YES
Specifies that the pages of an ISAM pool are to be maintained in resident memory. A PFA (Performant File Access) privilege is required in order to execute this function.
The call is rejected for existing ISAM pools if there is a conflict between the RESDNT attribute of the pool and the requested RESDNT attribute.
SCOPE
Specifies the scope of the ISAM pool.
All the operand values except TASK are only still supported for reasons of compatibility (see the "Note").
= TASK
The ISAM pool can be used only by the calling job: it is task-local.
= USERID
= USERGROUP
SCOPE=USERID and SCOPE=USERGROUP, which were available up to BS2000/OSD V6.0A, are still accepted for reasons of compatibility, but are mapped internally to SCOPE=HOST (cross-task ISAM pool).
= HOST
The ISAM pool is cross-task and may be used by all jobs.
In the case of SCOPE=HOST, the MODE operand is evaluated. At the same time, SCOPE=HOST affects the WROUT operand: the default value WROUT=YES applies to all files in the ISAM pool and cannot be changed by the user.
SIZE
defines the size of the new ISAM pool to be created.
= STD
The ISAM pool is to be created with the default size specified in the ISAM parameter service.
If the CREATION-MODE=ANY parameter has been specified, the following applies: if the pool is newly created, the SIZE specification is analyzed as described above. If the ISAM pool already exists, the size of the existing ISAM pool is taken over. The specifications for RESDNT and WROUT, however, have to match the attributes of the existing ISAM pools.
= number
defines the size of the ISAM pool to be created in PAM pages:
32 <= num <= 32767 for cross-task ISAM pools
32 <= num <= 8192 for task-local ISAM pools
It is possible that the maximum size set by the system manager for the user address space is the upper limit. An ISAM pool that is used to buffer files which were created with both BLKCTRL=DATA2K and =DATA4K is dynamically allocated a second extent and thus consists of a 2K extent as well as a 4K extent of the size defined by “num”.
It should be noted that with the minimum size of 32 PAM pages only files of a block size of up to (STD,6) can be processed. For processing files with logical blocks of the size (STD,16), an ISAM pool with 96 PAM pages is required.
WROUT
specifies for the pool whether the changed blocks of a file are to be written to disk immediately:
Default setting:
WROUT=NO for a task-local ISAM pool (SCOPE=TASK)
WROUT=YES for a cross-task ISAM pool (SCOPE=USERID/USERGROUP/HOST)
= YES
Changed blocks are written to disk immediately, irrespective of the value of the WROUT operand in the FILE or FCB call for the associated file.
= NO
specifies that changed blocks do not need to be written to disk immediately. In spite of specifying WROUT=NO at CREPOOL, a changed block is written to disk immediately ifWROUT=YES (by means of FILE or FCB or ADD-FILE-LINK) has been specified for the associated file or if
SCOPE≠TASK is specified for the pool.
= UNCOND-NO
Specifies that updated blocks need not be written back to disk immediately; the restrictions of WROUT=NO do not apply in the following cases:For a cross-task pool (SCOPE=USERID/USERGROUP/HOST), too, updated blocks are not written back to disk immediately;
OPEN is only carried out for files that are to be opened with SHARUPD=YES in case WRITE-IMMEDIATE=NO or WROUT=NO has been explicitly specified in the associated ADD-FILE-LINK command or FILE macro.
Return codes
The field names and the EQU statements for return codes generated with the C and D forms of the macro start with the string DISC. The first character of this string can be changed by PREFIX, characters 2-4 by MACID.
The return codes are placed in the standard header of the operand list.
Main return code | Meaning |
DISCOK X'0000' | The macro was executed successfully. |
DISCNPAR X'0001' | Access to the operand list is not possible. |
DISCNCAT X'0003' | The catalog ID “catid” is unknown in the system. |
DISCNACC X'0004' | There is no link to the pubset “catid”. |
DISCINVN X'0005' | The pool name is invalid. |
DISCSPAC X'0007' | There is not enough free address space to create a pool (SIZE specification is too large). |
DISCPLEX X'0008' | The specified ISAM pool already exists; |
DISCSYSE X'000B' | A system error occurred during macro processing. |
DISCSIZE X'000C' | The SIZE specification is invalid. |
DISCINVW X'000E' | The WROUT specification is invalid. |
DISCINVS X'000F' | The SCOPE specification is invalid. |
DISCINVM X'0010' | The MODE specification is invalid. |
DISCPRIV X'0011' | Missing privilege with a RESDNT=YES specification |
DISCPRES X'0012' | The RESDNT specification in the parameter list and the one for the existing pool are in conflict. |
DISCPERR X'0013' | Parameter error. |
DISCSPEX X'0014' | Contingent for ISAM pools exceeded. |
DISCRLNK X'FFFF' | Macro could not be executed (linkage error): |