Direct BSAM Interface Functions

The Record-Oriented BSAM Interface

The record-oriented BSAM interface is similar to QSAM in many ways, but the use of BSAM permits some useful non-QSAM functionality.

QSAM features supported by the BSAM record interface include the following:

Access to data is a record at a time rather than a block at a time. Determination of input record length is handled automatically.
Overlapping of I/O with CPU processing is handled automatically. The number of channel programs to issue and buffers to use is under program control.
Fairly easy support is provided for processing concatenated sequential files with unlike attributes.

Differences between QSAM and the BSAM record interface include the following:

The record interface allows the use of osfind , osstow , and ostclose to perform member-by-member PDS processing.
Open modes of INOUT and OUTIN not supported by QSAM can be used.
The osseek and ostell routines allow a file to be repositioned, which QSAM does not support.
The processing of spanned records using the BSAM record interface is segment-oriented rather than record-oriented. Spanned record applications are harder to write with BSAM than they are with QSAM but still much easier than doing deblocking "by hand".

The BSAM record interface also includes an osdcb routine, which can be used to define a DCB more conveniently than osbdcb by using a string of keyword parameters similar to the operands of the assembler DCB macro. Although this interface is more convenient than osbdcb , additional processing is required to parse the keyword string. This processing can be avoided by using osbdcb and explicit code to modify the DCB after it is allocated.

Controlling Buffering Using the Record Interface

The two DCB parameters that control buffering and overlapping of I/O operations are BUFNO and NCP. If these are not specified by the user when a file is opened, default values are assumed. Following are the four different styles of buffering supported:

BUFNO =1 and NCP= 1: In this mode, no overlapping of I/O occurs. This mode is most useful for applications that use osseek heavily.
BUFNO =2 and NCP= 1: In this mode, only one I/O operation is active, but a new operation usually starts immediately on completion of the previous request. This enables I/O and program processing to overlap and supports modest use of osseek and ostell .
BUFNO=n and NCP=n- 1: This mode provides for the maximum overlapping of I/O operations and is recommended for maximum efficiency. However, osseek and ostell are difficult or impossible to use.
BUFNO=n and NCP=n: This mode is used with open mode "updat". osseek and ostell can be used only if n is 1 .

Using osseek and ostell

osseek and ostell are similar to the standard SAS/C Library's fseek and ftell functions. Unlike osnote and ospoint , they use position indicators (of type ospos_t ) that identify a particular record, rather than a particular block, of the file. As part of its processing, ostell calls osnote to issue the NOTE macro, and, similarly, osseek calls ospoint to issue the POINT macro.

Unfortunately, a BSAM restriction requires that no I/O operations be active when a NOTE or POINT is issued. This means that when ostell or osseek is called, all reads or writes have to be checked, and the advantages of overlapping I/O are lost. There is another, more subtle problem as well.

Suppose the program has just called osget to obtain a record and now wants to call ostell to find the position of the record. osget may have started to read one or more additional blocks. After these read operations have been checked, a call to osnote returns the address of the last block read, which is not the same as the address of the block containing the record most recently passed to the program, the one whose address was requested. This problem means that ostell cannot usually be used meaningfully if the NCP value is greater than 1 .

To allow the use of ostell with BUFNO= 2 , which allows I/O to overlap with processing, the record interface supports a special mode of operation called "autonote" mode. In this mode, after every block is read or written, the library calls osnote and saves the block address for later use when the program calls ostell . Note that this requires that a NOTE be issued for every block, whether or not the block address is required. For this reason, autonote mode should be used only for applications in which the record address is used frequently or in which the efficiency gains from double buffering outweigh the loss from overuse of NOTE.

Autonote mode is set via an argument to osopen and cannot be changed once a DCB is opened.

Handling Spanned Records

The BSAM record interface mode is locate on input and move on output. That is, the input routine stores a pointer to the input data (within the BSAM buffer), and the output routine copies data to the BSAM buffer. Spanned records on input are difficult to deal with in locate mode because of the need to allocate a buffer to hold an entire record, when the length of the record is unknown, until all segments have been read. To bypass this problem, the SAS/C record interface is segment-oriented rather than record-oriented for spanned records. If segment consolidation is required, it can be performed by the application program, which frequently has information unavailable to the library about expected record lengths.

When the osget routine is called, it stores the address and length of the input record for nonspanned records. For spanned records, it stores the segment address and length. If the segment is the last (or only) segment of a record, the length is stored normally; for other segments, the negative of the length is stored. An application that needs to process an entire record at a time can call osget to read a segment at a time, stopping when a positive length is returned, indicating the end of the record.

Processing of spanned records is similar on output. When osput is called, one argument is the length of the record to write. If the length is negative, this indicates that the data are a record segment and that additional segments are to be expected. The final segment is indicated via a positive length. When record segments are passed to osput , the segments do not need to be physical segments because osput reblocks and resegments as necessary to match the output file attributes. This enables records to be copied easily from one record format to another without having to code elaborate logic to despan and respan records.

Processing Concatenations with Unlike Attributes

One reason for using a low-level I/O interface as opposed to a high-level interface such as standard C I/O is the ability to process concatenated files with different attributes, such as a tape file concatenated to a disk file or several files with different record lengths. Processing like this is easy with the direct BSAM interface. It is also supported via the record interface, but a little more work is necessary to enable the interface to rebuild its buffer pool and restart I/O when processing switches from one file to the next.

A brief summary of how to process unlike concatenations follows; for a more detailed description, see IBM publication MVS/DFP Using Data Sets (SC26-4749).

A program that supports concatenation of unlike data sets in assembler sets the DCBOFPPC bit of the DCBOFLGS field of the DCB. When the end of one of the concatenated data sets is reached, BSAM closes and reopens the DCB and frees and reallocates buffers for the file. Each time the DCB is closed and reopened, the DCB open exit is called by BSAM to inform the program that the file attributes may have changed and to give the program an opportunity to extract the new attributes from the DCB.

When the C record interface is used, the same DCB bit is used to request unlike concatenation support from BSAM. You must provide a C open exit, and the open exit must call the osflush routine to inform the record interface that the buffer pool has been freed and reallocated. Also, you must specify NCP= 1 to allow the library to successfully restart I/O interrupted by the end of a concatenated file.

Chapter Contents
Previous
Next
Top of Page