BUFFER Statements

 
idms19
 
The BUFFER statements create, alter, drop, display, or punch the definition of a database buffer in the dictionary. You must define at least one database buffer for a DMCL.
2
2
Authorization
  • To create, alter, or drop a database buffer, you must have the following privileges:
    • DBADMIN on the dictionary in which the database buffer definition resides
    • ALTER on the DMCL with which the database buffer is associated
  • To display or punch the database buffer, you must have DISPLAY privilege on the DMCL with which the database buffer is associated or DBADMIN on the dictionary in which the buffer definition resides
BUFFER Statement Syntax
CREATE/ALTER BUFFER
►►─┬── CREATE ─┬─ BUFFER ─┬──────────────┬─ database-buffer-name ─────────────►    └── ALTER ──┘          └─ dmcl-name. ─┘    ►─┬────────────────────────────────────────┬─────────────────────────────────►    └─ PAGE SIZE character-count characters ─┘    ►─┬──────────────────────────────────────────────────────────────────────┬───►    └─ NATIVE VSAM ─┬─ LSR KEYLEN lsr-key-length ──┬─ STRNO string-number ─┘                    └─ NSR BUFNI nsr-buffer-count ─┘    ►─┬───────────────────────────────────────────────────────────────────────┬──►    └─ LOCAL MODE BUFFER PAGES local-mode-page-count ─┬───────────────────┬─┘                                                      ├─ OPSYS storage ◄──┤                                                      └─ IDMS storage ────┘    ►──┬────────────────────────────────────────────────────────────┬────────────►◄     └┬─ CENTRAL VERSION ─┬─ MODE BUFFER ─┬─────────────────────┬─┘      └─ CV ──────────────┘               └─ cv-buffer-options ─┘
DROP BUFFER
►►─── DROP BUFFER ─┬──────────────┬─ database-buffer-name ────────────────────►◄                    └─ dmcl-name. ─┘
DISPLAY/PUNCH BUFFER
►►─┬─ DISplay ─┬─ BUFFER ─┬──────────────┬─ database-buffer-name ─────────────►    └─ PUNch ───┘          └─ dmcl-name. ─┘      ┌───────────────────────────────────────┐  ►─▼─┬───────────────────────────────────┬─┴──────────────────────────────────►      │               ┌────────────────┐  │      ├─ WITh ──────┬─▼─┬─ DETails ──┬─┴──┘      └─ WITHOut ───┘   ├─ HIStory ──┤                        ├─ ALL ◄─────┤                        └─ NONe ─────┘    ►─┬──────────────────────────┬───────────────────────────────────────────────►    └─ VERb ─┬─ DISplay ───┬───┘             ├─ PUNch ─────┤             ├─ CREate ◄───┤             ├─ ALTer ─────┤             └─ DROp ──────┘    ►─┬───────────────────────┬──────────────────────────────────────────────────►◄    └─ AS ─┬─ COMments ◄──┬─┘           └─ SYNtax ─────┘
Expansion of
 
cv-buffer-options
►►─┬────────────────────────────────────┬─────────────────────────────────────►    └─ INITIAL PAGES initial-page-count ─┘    ►─┬────────────────────────────────────┬─────────────────────────────────────►    └─ MAXIMUM PAGES maximum-page-count ─┘    ►─┬──────────────────────┬───────────────────────────────────────────────────►◄    └┬─ OPSYS storage ◄──┬─┘     └─ IDMS storage ────┘
 
BUFFER Statement Parameters
  • dmcl-name
    Identifies the DMCL with which the database buffer is associated.
    Dmcl-name
    must name an existing DMCL defined to the dictionary. If you don't specify a DMCL name, you must establish a current DMCL as described in 7.3.3, “Entity Currency".
  • database-buffer-name
    Specifies the name of the buffer being created.
    Database-buffer-name
    must be a 1- through 18-character name that follows the conventions described in 7.3, “Naming Conventions".
    Database-buffer-name
    must be unique among the database and journal buffer names within the DMCL. From 1 to 32,767 database buffers can be defined to a single DMCL.
  • PAGE SIZE
    character-count
    Specifies the number of characters in each page of the buffer. This clause is required on a CREATE statement. The buffer page size determines the size of the largest database page or VSAM control interval that can be written to the buffer.
    The value of
    character-count
    depends on the type of buffer being defined:
File
Buffer Type
Valid Page Sizes (in bytes)
VSAM database file
 
48 - 32764; multiple of 4 1 2
Native VSAM file3
LSR
512, 1024, 2048, or multiple of 4096 up to 28672
 
NSR
512 - 8192; multiple of 512
8193 - 30720; multiple of 2048
For VSAM database files, character-count must be at least 8 bytes larger than the size of the database page.
For native VSAM files, the PAGE SIZE clause must be greater than or equal to the largest control interval of a file that maps to the buffer.
  • NATIVE VSAM
    Specifies a buffer for use with native VSAM data sets.
  • LSR KEYLEN
    lsr-key-length
    Specifies an LSR (local shared resource) buffer. Only one is allowed per DMCL.
    Lsr-key-length
    specifies the maximum key length for all native VSAM files using the buffer, where
    lsr-key-length-n
    is an integer in the range 1 through 255.
  • NSR BUFNI
    index-buffer-count
    Specifies an NSR (nonshared resource) buffer. Any number of these are allowed.
    Index-buffer-count
    specifies the number of index buffers VSAM uses to transfer the contents of index entries between main memory and auxiliary storage. It is an integer in the range
    string-number
    through 32767.
  • STRNO
    string-number
    Specifies the maximum number of concurrent requests permitted against all areas associated with files that are assigned to the buffer, where
    string-number
    is an integer in the range 1 through 255.
  • LOCAL MODE BUFFER PAGES
    local-mode-page-count
    Specifies the number of pages to be included in the buffer when the database is used in local mode. Valid values for
    local-mode-page-count
    appear as follows:
Buffer Type
Valid Values
Non-native VSAM buffers
3 to 16,777,2141; default 3
Native VSAM buffers
2 to 256; must be greater than the value assigned to STRNO in the NATIVE VSAM clause above
The practical upper limit depends on the amount of available storage.
Native VSAM
For native VSAM data sets, the buffer page count specifies the number of pages in the buffer used to transfer
data
between memory and auxiliary storage. For LSR buffers, the page count specifies the number of pages used to transfer both
data and index entries
.
  • OPSYS storage
    Places the buffer in a contiguous block of storage acquired from the operating system. The storage is acquired above the 16-megabyte line in operating systems that support extended addressing. If sufficient storage is not available, storage is acquired as IDMS storage. OPSYS STORAGE is the default.
  • IDMS storage
    Acquires a discrete piece of storage for each buffer page. If the operating system supports extended addressing, the storage will be acquired above the 16-megabyte line.
    Native VSAM:
    Do not specify this clause.
  • CENTRAL VERSION MODE BUFFER
    Specifies page counts for the buffer when the database is used under the central version.
  • cv-buffer-options
    Specifies options for the buffer used under the central version.
  • INITIAL PAGES
    initial-page-count
    Specifies the initial number of pages to be allocated for the buffer.
    Initial-page-count
    is an integer. Valid values appear as follows:
Buffer Type
Valid Values
Non-native VSAM buffers
3 to 16,777,2141; default 3
Native VSAM buffers
2 to 256; must be greater than the value assigned to STRNO in the NATIVE VSAM clause above
The practical upper limit depends on the amount of available storage.
Native VSAM:
For native VSAM data sets, the buffer page count specifies the number of pages in the buffer used to transfer data between memory and auxiliary storage. For LSR buffers, the page count specifies the number of pages used to transfer both data and index entries.
  • MAXIMUM PAGES
    maximum-page-count
    Specifies the largest number of pages that can be allocated for the buffer.
    Maximum-page-count
    is an integer in the range 3 to 16,777,214. It must be greater than or equal to the number specified in the INITIAL PAGES parameter. The default is the initial number of pages included in the buffer.
    Native VSAM:
    Do not specify this clause.
  • OPSYS storage
    Places the buffer in contiguous storage acquired from the operating system. OPSYS STORAGE is the default.
    The storage is acquired above the 16-megabyte line in operating systems which support extended addressing. If sufficient storage is not available, storage is acquired as IDMS storage.
  • IDMS storage
    Requests a discrete piece of storage for each buffer page from the DC/UCF storage pool. If the DC/UCF system contains a storage pool above the 16-megabyte line, then storage for the buffer is acquired above the 16-megabyte line.
    Native VSAM:
    Do not specify this clause.
  • DETails
    Displays or punches details about the database buffer.
  • HIStory
    Displays or punches:
    • The user who defined the database buffer
    • The user who last updated the database buffer
    • The date the database buffer was created
    • The date the database buffer was last updated
  • ALL
    Displays or punches all information on the database buffer. ALL is the default action for a DISPLAY or PUNCH verb.
  • NONe
    Displays or punches the name of the database buffer.
BUFFER Statement Usage
Buffer Storage Not Acquired Until Needed
CA IDMS/DB does not acquire storage for a buffer until it opens a file associated with the buffer.
Buffer Page Count Under the Central Version
When you start up a DC/UCF system, the number of pages in a given buffer is the number specified in the INITIAL PAGES parameter in the buffer definition. If the initial number of pages is lower than the number specified in the MAXIMUM PAGES parameter, you can use the DCMT VARY BUFFER command to increase the number of pages in the buffer up to the specified maximum.
How CA IDMS/DB Acquires Storage for a Buffer
The OPSYS and IDMS parameters tell CA IDMS/DB how to acquire storage for the buffer. In response to the OPSYS parameter, CA IDMS/DB issues a request to the operating system for a contiguous block of storage for the buffer pages. In response to the IDMS parameter, CA IDMS/DB issues requests to the DC/UCF system for storage equal to the size of a buffer page until all the required pages are acquired. For both OPSYS and IDMS, CA IDMS/DB acquires the storage above the 16-megabyte line, if possible.
Dropping a Buffer with Associated Files
Before you delete the definition of a buffer, use the ALTER DMCL statement to change the buffer specification for files associated with the buffer.
Reducing the number of physical I/Os
Reduce the number of physical I/Os by increasing the size of Database Buffers and/or implementing CA IDMS features such as Buffers above the BAR.
BUFFER Statement Examples
Defining the Default Buffer
The CREATE BUFFER statement below defines a buffer for DMCL IDMSDMCL. The buffer can be used in both local mode and under the central version.
create buffer idmsdmcl.index_buffer    page size 4276    local mode buffer pages 15    central version mode buffer       initial pages 100       maximum pages 500;
Modifying the Page Count for Use Under the Central Version
The following ALTER BUFFER statement modifies both the initial page count and the maximum page count of the INDEX_BUFFER buffer:
alter buffer idmsdmcl.index_buffer    central version mode buffer       initial pages 150       maximum pages 300;
Dropping a Database Buffer
The following DROP BUFFER statement deletes the definition of the INDEX_BUFFER buffer from the dictionary:
drop buffer idmsdmcl.index_buffer;