Sequential buffering control statements

Use sequential buffering control statements to specify I/O operations that require sequential buffering (SB), capture internal calls to the SB buffer handler, take a snapshot of SB control blocks, and perform an SB buffer handler self-check.

This section describes the control statements you can use to modify sequential buffering definitions.

Syntax of SB control statements

SB control statements are contained in 80-character records. Positions 72-80 are ignored.

Each SB control statement must begin on a new record. The first record must contain at least the statement name. IMS considers the first non-blank character the start of the statement. The first word on the statement must be the statement name, such as SBPARM and SBIC, followed by one or more blanks.

Depending upon the type of SB control statement, one or more keyword parameters follow the statement name. Keywords must be followed immediately by an equal (=) sign and a value. If you specify multiple keywords, separate them with commas. If you specify multiple values, enclose them in parentheses. Individual keyword parameters must be contained on a single record.

A blank or a /* signals the end of a statement. You can continue SB control statements on multiple records. Use a comma at the end of a line to indicate continuation.

An asterisk (*) in the first position on a record indicates a comment. Elsewhere on a record, comments begin with /*.

Two examples of proper syntax follow:

SBPARM ACTIV=COND,DB=SKILLDB,BUFSETS=6   /*Comment

SBPARM ACTIV=COND,   /*This is a comment
       DB=SKILLDB,   /*This is a comment
       BUFSETS=6     /*This is a comment

SB parameters (SBPARM) control statement

The SBPARM control statement is used to:

Specify which I/O operations require sequential buffering (I/O operations can be specified by database, PCB, ddname, and PSB)
Override SB default parameters

All SBPARM parameters are optional.

The format of the SBPARM control statement is:

Default values are underlined. The default value, however, might have been overridden by other specifications. If you provide the same SB option or parameter in more than one place, the following priority list applies (item 1 has the highest priority):

SB control statement specifications (the nth control statement overrides the mth control statement, where n>m)
PSB specifications
Defaults changed by the SB Initialization exit routine

If you specify multiple SBPARM control statements applying to the same I/O operation, the nth control statement overrides the mth one (where n>m). This lets you specify defaults on the first statement which can be overridden by subsequent statements.

The SBPARM control statement has two types of keyword parameters:

Option parameters, such as ACTIV= and BUFSETS=, which set and override an SB option or parameter, respectively
Qualification parameters, such as DB, PCB, DD, and PSB, which specify the I/O operations to which the SBPARM statement applies

Sequential Buffering option parameters

Option parameters set or override an SB option or parameter. If an option parameter is not specified, the previously established value of the parameter is in effect. The previously established value might have been set by an IMS default, the SB Initialization exit routine, PSBGEN, or preceding SBPARM statements.

ACTIV=

Specifies if and when SB should be activated.

NO: Specifies that SB is not activated. NO is the default; however, the default might have been changed by what is specified in the SB Initialization exit routine, PSBGEN, or a preceding SBPARM control statement.
COND: Specifies that IMS monitors the I/O reference patterns of PCBs and eventually activates SB if analysis shows the I/O reference pattern is sequential, and the rate of I/O activity is high enough.

Recommendation: Specify COND for batch and BMP programs that sometimes or always process a database sequentially. Do not use SB for short-running MPP, Fast Path, or IBM® CICS® Transaction Server for z/OS® programs because of the overhead associated with initializing SB for each program execution.

If ACTIV= is not specified on an SBPARM control statement, IMS uses the previously established value of the ACTIV parameter. Therefore, omitting ACTIV lets you override the BUFSETS parameter without inadvertently changing SB PSBGEN specifications.

BUFSETS=

Specifies how many buffer sets are to be allocated for a given SB buffer pool. You can specify a value from 1 through 25. The default is 4. (The default can be changed by the SB Initialization exit routine.)

Each SB buffer pool consists of n buffer sets. Each buffer set has 10 buffers. Each buffer is large enough to hold one OSAM data set block.

You must specify a value greater than 1 if SB is to use overlapped I/O.

A well-organized database might only require a BUFSETS value of 2 for efficient sequential buffering. Less well-organized databases might require a BUFSETS value of 6 or more. One indicator of database organization can be found in the optional //DFSSTAT reports. If, for a sequential program, these reports show a low percentage of random I/O operations, this can indicate a well-organized database. Conversely, a high percentage of random I/O can indicate a poorly organized database. In either case, the //DFSSTAT reports can help you adjust the BUFSETS value to improve buffering performance.

Sequential Buffering qualification parameters

Qualification parameters specify the I/O operations to which the SBPARM statement applies. You can associate SBPARM statements with a database, PCB, ddname, or PSB.

You can specify any combination of qualification parameters. If you specify more than one qualification parameter, the SBPARM statement applies only to I/O operations that satisfy all qualification parameters. If you do not specify any qualification parameters, the SBPARM statement applies to all I/O operations.

DB=

Specifies the DBD name (as specified in the PCB macro of PSBGEN) of those PCBs to which the SBPARM statement applies.

If multiple PCBs have the same DBD name, and you want different specifications for different PCBs, use the PCB= keyword. If the PCB refers to multiple database data sets and you want different specifications for these data sets, use the DD= keyword.

If no DB= keyword is provided, the SBPARM statement applies to all I/O operations that satisfy the other qualification keywords.

PCB=

Specifies the label coded on the database PCB during PSBGEN. Use this keyword to distinguish between multiple PCBs with the same DBD name.

If no PCB= keyword is provided, the SBPARM statement applies to all I/O operations that satisfy the other qualification keywords.

DD=

Specifies the ddname of the database data set to which the SBPARM statement applies. Use this keyword to distinguish between multiple data sets to which the PCB refers.

If no DD= keyword is provided, the SBPARM statement applies to all I/O operations that satisfy the other qualification keywords.

PSB=

Specifies the name of the PSB to which the SBPARM statement applies.

If no PSB=keyword is provided, the SBPARM statement applies to all I/O operations that satisfy the other qualification keywords.

Use of the PSB= keyword is recommended for message regions. Normally, SB should not be activated for all programs running in the message region; rather, SB should be restricted to a small number (if any) of these programs. If SB is to be used for more than one program, you need to provide one SBPARM statement for each program and code the PSBname of the program on the PSB= keyword.

PSB= is also useful if you decide to centralize all SB control statements in one common SB control statement file. In this case, PSB= identifies for each SBPARM statement, the PSB or program to which it applies.

SBPARM examples	Comments
`SBPARM ACTIV=COND`	SBPARM requests conditional activation of SB for all I/O operations. No default values for SB parameters are overridden.
`SBPARM ACTIV=COND,DB=SKILLDB`	SBPARM requests conditional activation of SB for I/O operations associated with all PCBs coded with DBDNAME=SKILLDB during PSBGEN. No default values for SB parameters are overridden.
`SBPARM ACTIV=COND,DB=SKILLDB,PCB=LABEL1`	SBPARM requests conditional activation of SB for all PCBs that satisfy both of the following conditions: DBDNAME=SKILLDB coded during PSBGEN The PCB label coded as LABEL1 during PSBGEN
`SBPARM ACTIV=COND,DB=SKILLDB,BUFSETS=6`	SBPARM requests conditional activation of SB for all PCBs coded with DBDNAME=SKILLDB during PSBGEN. The BUFSETS parameter is set to 6 (instead of 4, which is the default). This increase in BUFSETS value can improve buffering efficiency if the database is poorly organized.
`SBPARM BUFSETS=6`	SBPARM requests that the default values of BUFSETS be overridden. Increasing the value of BUFSETS to 6 (rather than using the default, which is 4) can improve buffering efficiency if the database is poorly organized. In this example, ACTIV has not been coded. As a result, the SBPARM statement does not change the previously established set of I/O operations being buffered by SB.
`SBPARM ACTIV=NO`	SBPARM requests that SB not be used. The request applies to all I/O operations.

SB Image Capture (SBIC) control statement

The SBIC control statement captures all internal calls to the SB buffer handler. The captured information is put in the X'5E' log record.

The X'5E' log records can be used as input to the SB test program (DFSSBHD0).

Related reading: For detailed information about the SB test program (DFSSBHD0), see IMS Version 15.2 Database Utilities.

The format of the SBIC control statement is as follows:

SB Compare Option (SBCO) control statement

The SBCO control statement asks the SB buffer handler to perform a self check to determine if SB is putting incorrect block images in the OSAM buffers, and if so, to provide problem determination information.

Problem determination information is provided in the form of a snap. In the IMS online environment, this snap is written to the IMS log. In the IMS batch environment, you can request that the snap is written to any of the following:

The data set specified in the DFSDDLT0 //PRINTDD DD statement
A user-specified data set
The IMS log

See Snap Destination (SNAPDEST) control statement for a description of how to request these snap destinations. In the batch environment, the default snap destination is the data set specified in the //DFSSNAP DD statement.

Related reading: For detailed information about the SBCO control statement, see IMS Version 15.2 Diagnosis.

The format of the SBCO control statement is as follows:

SB Snap (SBSNAP) control statement

The SBSNAP control statement snaps SB control blocks after each internal call of the OSAM buffer handler to the SB buffer handler. As an option, you can request that, for each internal SB call, the following additional information be snapped:

The OSAM database block returned by the SB buffer handler to the OSAM buffer handler
The SB buffers for the current data set group

In IMS online environment, this snap is written to the IMS log. In the IMS batch environment, you can request that the snap is written to any of the following:

The data set specified in the DFSDDLT0 //PRINTDD DD statement
A user-specified data set
The IMS log

All SBSNAP parameters are optional.

The format of the SBSNAP control statement is as follows:

If you specify multiple SBSNAP control statements, the n-th control statement overrides the mth control statement (where n>m).

Related reading: For additional information about the SBSNAP control statement, see IMS Version 15.2 Diagnosis.

BHBUF=: Specifies whether (YES) or not (NO) the OSAM buffer handler buffer is to be included in the snap produced at the end of each internal call to the SB buffer handler. The default is NO.
SBBUFCB=: Specifies whether (YES) or not (NO) the buffer control blocks of the SB buffer handler are to be included in the snap produced at the end of each internal call to the SB buffer handler. The default is NO.
SBBUF=: Specifies whether (YES) or not (NO) the buffers of the SB buffer handler are to be included in the snap produced at the end of each internal call to the SB buffer handler. The default is NO.
START=: Specifies that the snap is to start on the nth call to the SB buffer handler (instead of the first call). The default is 1.
The START= and the STOP= parameters are useful if you want to limit snapping to a specific period during which an application is running. The SBSNAP option often creates a large amount of output.
STOP=: Specifies that the snap is to be stopped on the mth call to the SB buffer handler (instead of the last call).
The default is that the snap is stopped after the last call.

SB Evaluation Snap (SBESNAP) control statement

The SBESNAP control statement snaps SB control blocks at the end of each periodic evaluation of the buffering process. The information in this snap can help you understand why IMS did or did not use SB.

In the IMS online environment, the snap is written to the IMS log. In the IMS batch environment, you can request that the snap is written to any of the following:

The data set specified in the DFSDDLT0 //PRINTDD DD statement
A user-specified data set
The IMS log

All SBESNAP parameters are optional.

The format of the SBESNAP control statement is:

If you specify multiple SBESNAP control statements, the nth control statement overrides the mth control statement (where n>m).

Related reading: For additional information about the SBESNAP control statement, see IMS Version 15.2 Diagnosis.

EVAL=

NEG requests a snap only when a periodical evaluation results in a decision not to use SB.

POS requests a snap only when a periodical evaluation results in a decision to use SB.

ALL requests a snap whenever a periodical evaluation of a data set group is made.

The default is NEG.

Snap Destination (SNAPDEST) control statement

The SNAPDEST control statement is applicable in batch environments only. SNAPDEST specifies the destination of the snap created by the SBSNAP, SBESNAP, or SBCO options. In the IMS online environment, SNAPDEST is ignored, and snap information is written to the IMS log.

The default destination for snap information in the batch environment is the data set specified in the //DFSSNAP DD statement.

If you specify an invalid destination in the SNAPDEST control statement, IMS tries to write the snap to the IMS log.

The format of the SNAPDEST control statement is as follows:

The destination specified in the SNAPDEST control statement can be any one of the following:

DFSSNAP

Specifies that snap information is to be put in the data set associated with the //DFSSNAP DD statement.

PRINTDD

Specifies that snap information is to be put in the data set associated with the //PRINTDD DD statement of the DL/I test program DFSDDLT0. This data set also contains information created by DFSDDLT0.

ddname

Specifies that snap information is to be put in the data set with the specified ddname. The DD statement for this data set must conform to z/OS requirements for snap.

When the snap destination is ddname, DCB attributes are provided by IMS. You should not code them on the DD statement.

For this type of destination, each snap opens and closes the data set. If there are many snaps, this can result in significant overhead.

LOG

Specifies that snap information is to be put in the IMS log.

When snaps are written to the log, the log record codes are as follows:

X'67ED'- snap created by the SBESNAP option
X'67EE'- snap created by the SBSNAP option
X'67EF'- snap created by the SBCO option

You can select and print these log records using the File Select and Formatting Print utility (DFSERA10) and the Log Type X'67' Record Format and Print Module (DFSERA30).

Related reading: Both of these programs are described in IMS Version 15.2 System Utilities.