UPDATE POOL command

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes for UPDATE POOL TYPE(FPBP64)
• Usage notes for UPDATE POOL TYPE(DBAS)
• Output fields
• Return, reason, and completion codes
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the commands and keywords.

Syntax

>>-+-UPDATE-+--POOL--------------------------------------------->
   '-UPD----'         

>--TYPE-+-(DBAS)-+-------------+-SECTION(-+-OSAMxxx---------+-)-+-><
        |        '-MEMBER(xxx)-'          +-VSAMxxx---------+   |   
        |                                 '-OSAMxxx,VSAMxxx-'   |   
        '-(FPBP64)-+-------------------+------------------------'   
                   '-SET(LIMIT(xxxxx))-'                            

Keywords

The following keywords are valid for the UPDATE POOL command:

TYPE()

This required keyword specifies which type of UPDATE POOL command to issue.

DBAS

This option specifies that the command dynamically adds, updates, or deletes OSAM or VSAM subpools. TYPE(DBAS) is mutually exclusive with other options on the TYPE() keyword. The command is rejected with a syntax error if multiple options are specified.

The UPDATE POOL TYPE(DBAS) command is not valid for DCCTL environments.

FPBP64

This option specifies that the command sets or changes values for storage used by the Fast Path 64-bit buffer manager. TYPE(FPBP64) is mutually exclusive with other options on the TYPE() keyword. The command is rejected with a syntax error if multiple options are specified.

SET()

Specifies the attribute values to be changed. This keyword is valid only if TYPE(FPBP64) is specified.

LIMIT

Specifies the maximum amount of 64-bit storage used by the Fast Path 64-bit buffer manager.

xxxxx

You can specify the value in bytes, kilobytes, or megabytes, as follows:

• xxxxx - Value in bytes. The maximum value is 2,147,483,647 bytes.
• xxxxxK - Value in kilobytes. The maximum value is 2,097,151 KB.
• xxxxxM - Value in megabytes. The maximum value is 2,047 MB.

The valid range is between 2GB-1 megabytes and the initial size of the buffer pool at IMS™ startup.

You can also set this value at IMS startup by specifying the parameter FPBP64M on the DFSDFxxx member of the IMS PROCLIB data set.

MEMBER(xxx)

This keyword is valid only if TYPE(DBAS) is specified. It is optional. The xxx on the MEMBER keyword specifies a 1- to 3-alphanumeric character value that represents the suffix to a DFSDFxxx member name. The identified DFSDFxxx member is read in and parsed for OSAM and VSAM subpool definitions. If the keyword is not specified, the DFSDFxxx member specified by the DBA on system initialization is used as the default. The DFSDFxxx member specified on system initialization can be determined from message DFS1929I on the system console or log. The command fails if the MEMBER keyword is specified with an invalid xxx value or if the DFSDFxxx member is not found.

Note: This keyword is optional and by default the command will always refer to the DFSDFxxx member specified on system initialization. Normally the DFSDFxxx member specified on system initialization should be the only one available. The purpose of this keyword is to allow the capability to have the command point to an alternate DFSDFxxx member (different from the system default) for test purposes. In other cases, the MEMBER keyword is expected to be omitted.

SECTION()

This keyword is valid only if TYPE(DBAS) is specified. It is required if TYPE(DBAS) is specified. This keyword specifies the section names in the DFSDFxxx member to read in for subpool definitions. It must be followed with a valid section name. One or both of the following section name types can be specified with this keyword:

OSAMxxx

Specifies the OSAM section in the DFSDFxxx member to read and process. The xxx value is the 1- to 3-alphanumeric character suffix of the OSAM section name. The indicated OSAM section must exist in the DFSDFxxx member and must contain valid OSAM subpool definition statements. Only one OSAM section name can be specified on the command.

VSAMxxx

Specifies the VSAM section in the DFSDFxxx member to read and process. The xxx value is the 1- to 3-alphanumeric character suffix of the VSAM section name. The indicated VSAM section must exist in the DFSDFxxx member and must contain valid VSAM subpool definition statements. Only one VSAM section name can be specified on the command.

If you are reassigning the DBD association (for example, changing a database data set association from one subpool to another subpool), you must stop and restart the database. The reason for the stop and restart is that the subpool assignment is done during data set open time.

Usage notes for UPDATE POOL TYPE(FPBP64)

The value that can be changed by the UPDATE POOL TYPE(FPBP64) SET(LIMIT(xxxxx)) command is not recoverable.

Enter the UPDATE POOL TYPE(FPBP64) SET(LIMIT(xxxxx)) command after an IMS restart, if needed. Because this command updates the value set by FPBP64M in the DFSDFxxx member, you might want to update FPBP64M with a new value before IMS cold restart.

Usage notes for UPDATE POOL TYPE(DBAS)

Determination of success, failure, or partial success of the command

There can be multiple change requests in the OSAMxxx or VSAMxxx sections of the DFSDFxxx member of the IMS PROCLIB data set. The UPDATE POOL TYPE(DBAS) command processes the change requests serially. When the UPDATE POOL TYPE(DBAS) command is completed, the results can be success, failure, or partial success.

The UPDATE POOL TYPE(DBAS) command cannot be canceled or aborted after it is issued.

Command completion if storage is unavailable

There are circumstances where the storage requested by the UPDATE POOL TYPE(DBAS) command cannot be satisfied. Because IMS cannot cancel or abort the command, it attempts to find the next best solution to satisfy the command, which means the command might result in less storage being allocated for the requested subpool change.

When the storage requested by the UPDATE POOL TYPE(DBAS) command cannot be satisfied, both OSAM and VSAM make a sequence of attempts to find a smaller amount of storage.

If a reduced amount of buffer pool storage is allocated as a result of the UPDATE POOL TYPE(DBAS) command, an X'EC' completion code is displayed to indicate the condition.

The minimum number of buffers for a VSAM buffer pool is 3. If a VSAM pool cannot allocate this minimum number of buffers, the databases that are using this pool are left without a buffer assignment. An internal /DBRECOVERY command is issued for all these databases. The UPD POOL command must be issued again to create the buffer pools. A subsequent /STA DB command must be issued to reestablish the buffer pool connection.

Effect of long-running BMPs on the command

For VSAM, a long-running batch message processing (BMP) program that does not take any checkpoint can affect the ability of the command to complete, since the command cannot be canceled or aborted. Either the subpool is eventually freed up by the BMP and the command can complete, or the subpool is not freed up by the BMP and the command waits indefinitely for the subpool to become available for the change. This effect applies to any subpool in the same VSAM local shared resource pool (that is, under the same POOLID statement).

OSAM and VSAM have different mechanisms for freeing up the target subpool. In general, OSAM waits for the target subpool to become unowned, while VSAM waits for DL/I activity for the target subpool to reach commit points. Since there is no timeout for this command, all partition specification tables (PSTs) with subpools affected by this command wait until the command completes.

Spreading database data sets across many subpools tends to lessen the impact of a change to any one of these subpools.

Buffer pool statistics and database data set reassignment

Buffer pool statistics are handled differently for VSAM and for OSAM following an UPDATE POOL TYPE(DBAS) command. For VSAM, the buffer pool statistics are reset and the old statistics are not carried over. It is advisable to issue a QUERY POOL command for the VSAM buffer pool statistics before issuing the command. The OSAM statistics are carried over and are not reset with the command.

When a database data set is reassigned from one buffer pool to a different buffer pool, the database data set must be closed and reopened. For OSAM, the closing and reopening of the database data set must be done explicitly. In other words, it is not performed as part of the command. For VSAM, the database data set must also be closed and reopened. However, if there is a corresponding change to the target buffer pool along with the reassignment of the database data set (for example, an increase in buffers), then the closing and opening of the database data set is done implicitly by the command.

Output fields

Return, reason, and completion codes

The following table includes the return and reason codes and a brief explanation of the codes. The return or reason code returned for the command might also indicate an error from a CSL request.

Errors unique to the processing of this command are returned as completion codes. The following table includes an explanation of the completion codes.