gtpa2m3iApplication Programming

Tape Support

Real-time and general tape functions provide the application program with single file, multivolume tape input and output. In order to fulfill different system requirements, 2 distinct I/O capabilities are provided. The real-time tapes are intended for logging application data, system changes, system performance and other dynamic maintenance information in the real-time environment. The general tape functions provide the tape writing, reading, and searching capabilities required by utility and application programs.

Real-Time Operations

The real-time tapes are write-only tapes that are available to all entries in the system. All hardware-oriented tape functions such as labeling, label checking, and end-of-volume conditions are handled by TPF. The application program is relieved of these responsibilities and can assume that the real-time tapes are always available. Records are written on these tapes in the order in which the toutc and tourc functions are received by TPF. However, because each tape is also available to other entries in the system, the application program should not depend on creating consecutive records.

The toutc function writes a record, contained in main storage, on the specified real-time tape. This record must not be altered until the writing operation is complete. The execution of a wait system service routine ensures the completion of the I/O transfer. Note that no restrictions are placed on the record's location in main storage. The record may be in a permanent main storage area, a working storage block, or the fixed work area in the ECB. To prevent a condition in which the tape output record is modified by another entry before the completion of the I/O transfer, it is recommended that the output record be located in a storage area held exclusively by the ECB. The following arguments must be specified in the order listed below when using the toutc function:

name
A pointer to a 3-character string that names the tape to be written to.

level
A value of enumeration type t_lvl that specifies the FARW containing the address of the record to be written to tape.

bufmode
One of the predefined terms NOBUFF, NULL, or BUFFERED, which determines whether the tape will be written to in immediate (NOBUFF or NULL) or buffered (BUFFERED) mode.

These parameters, which identify the symbolic tape to be used, are passed to TPF. The record starting location and byte count are stored in the specified request level in the FARW, in the following format:

Address of Start of Record Unused Byte Count
4 bytes 2 bytes 2 bytes

The CBRW is unused. Because of this, the application program may use any request level without releasing the main storage block held, if any, on that level.

The tourc function writes a record, contained in a main storage block, on the specified real-time tape. The main storage must be held by the ECB at the specified CBRW. This block is detached from the ECB upon execution of the function and then written to independently. Consequently, the application program cannot determine the status of the write operation; a waitc function call is unnecessary. Moreover, the request level used in the tourc function is available immediately for more use upon return from the function.

Code examples in assembly language:

TOUTC NAME=RTA,LEVEL=D2
TOURC NAME=RTL,LEVEL=D6
 

Code examples in C language:

  toutc("RTA",D2,BUFFERED);
  tourc("RTL",D6);
 

General Tape Operations

There may be active general tapes on the system at any time. These tapes are separated into distinct sets or groups, each one exclusively associated with a particular active entry: no entry can use another entry's general tape set concurrently. In addition to the tape reading, writing, and searching capabilities provided, the application program can refine and adjust the definition of its tape(s). Two types of C library functions are provided for general tape operations: basic and higher-level functions.

The basic general tape functions for assembly language and C language, which include tasnc, tbspc, tdspc, topnc, tprdc, trewc, trsvc, tsync, and twrtc, provide more direct control of general tape operations. In addition, the tdspc_q function is provided for C language only. These functions can provide very efficient general tape access when an entry can be assured of sole use of a general tape or when multiple I/O requests to a specific general tape are made. Each of the basic functions directly corresponds to a single macro service routine and therefore a small functionality, whereas the higher-level functions incorporate more system services. The judicious use of the basic functions can reduce unnecessary use of system resources and can be employed in some cases to produce more efficient code.

The higher-level general tape functions handle the details of general tape access for the application programmer, which can be especially useful in handling attempts to access a general tape that is already in use. The higher-level functions in C language include the tape_open, tape_close, tape_read, tape_write, and tape_cntl functions. It is important to note that these higher-level functions comprise an adequate library for performing general tape operations.

General Tape Functions

Most of the information for tape operations is described in terms of the basic tape functions. See the TPF C/C++ Language Support User's Guide and TPF General Macros for more information on basic and higher-level general tape functions.

Tape Allocation -- Open and Close: The open and close functions (topnc, tape_open, tclsc, and tape_close) are used in determining the availability of a general tape to an application program.

A general tape first becomes available to an application program through the use of an open function. The following arguments must be specified when using the topnc function:

name
A pointer to a 3-character string that names the general tape to be opened.

io
Indicates whether the tape is to be read or written to. INPUT indicates the tape is to be read. OUTPUT indicates that the tape is to be written to.

bufmode
The mode in which a buffered device will be written to. It can be one of the predefined terms NOBUFF, NULL, or BUFFERED NOBUFF or NULL indicates that a buffered device will be written to in write-immediate mode. BUFFERED indicates that a buffered device will be written to in buffered mode.

The tape_open function takes only the first 2 arguments listed above.

When an open function is called, the tape name is added to the tape set for that entry. TPF does the specified labeling operations and presents the desired tape positioned at the first data record. For topnc, TPF assigns the tape to the current ECB -- making it unavailable to any other ECB. For tape_open, TPF places the tape into the reserved state -- making it available for use by any ECB. Either close function, when called, deactivates the specified tape by deleting its tape name from the entry's tape set. TPF performs the trailer labeling when a close function addresses an output tape.

The allocation of physical tape units for general tape use is controlled by the computer operator, who is responsible for mounting the proper tapes and starting the various job phases in their correct sequence. The operator must know where new input or scratch tapes are needed, and when output tapes are complete. A utility program can communicate this information to the operator through the combined use of a setup sheet and the open and close functions.

Data Transfer -- Read, Write, and Synchronize: The general tape input/output functions are tprdc, twrtc, and tsync (all basic functions) and tape_read and tape_write (higher-level functions). In addition to the I/O operation, each read and write function does the appropriate main storage allocation. During the execution of a read function, TPF gets a main storage block to read the record into. Reference to this block is placed in the specified CBRW when the input operation completes. Conversely, after the completion of a write function, the main storage block containing the record is released to the appropriate storage pool. Accordingly, each request of tape I/O via the general tape functions has an associated data level in the ECB; this CBRW contains the block references in standard format. The FARW at the associated data level is not used.

On return from the tprdc function, the status of the read operation is unknown. Consequently, a call to the waitc function must be made to ensure completion of the I/O in C language. The return from the waitc function is used to indicate the success or failure of any input operation. In assembly language the success or failure of any input operation is activated by the condition code. The tape_read function produces the equivalent of a call to waitc. Consequently, all pending I/O will have occurred prior to return to the calling program.

On a write function, the writing operation and main storage containing the data record are detached from the ECB on return from the function. Therefore, the data level used is immediately available for more use upon the return from the twrtc function. The same availability applies to the return from the tape_write function. Note that for both twrtc and tape_write, the status of the I/O operation cannot be determined by the application. Consequently, a waitc function call is irrelevant.

The tsync function can be called in conjunction with twrtc to ensure that all records contained in all buffers (the control unit hardware buffer and/or the host buffer) are physically written to tape. A waitc function call made afterward will ensure the operation completes. It also is desirable to call waitc before calling tsync to clear any outstanding DASD I/O. Note that the tape_cntl function using the predefined FLUSH command will perform a similar synchronization with the higher-level functions.

Tape Allocation -- Assign and Reserve: It is important to note that the use of tasnc and trsvc is unnecessary when only higher-level functions are coded.

For those utility jobs that are single entry jobs (process from start to finish in the same entry), the previously described functions provide an adequate library. However, some jobs with extensive running time are segmented into a sequence of short phases. Each phase is a unique entry in the system and is begun by the computer operator upon completion of the previous phase. In such a case, it is desirable to have 1 set of tapes associated with the entire life of the job. An example of such a job might be nightly file maintenance, in which several capabilities are desirable:

To eliminate the tape handling by the operator between job phases, the application programmer may use 2 special purpose functions, general tape reserve (trsvc) and assign (tasnc). These functions are designed to pass an open set of general tapes from a currently active entry, which is about to exit, to a future entry.

Between these phases the positioning of the tapes remains unchanged. The trsvc function reserves the specified tape, in the set of this entry or current job phase, for use by a future entry or the next phase. When the next phase of the job is initiated, the new entry makes the tapes available by calling the assign (tasnc) function.

Control Operations: Control functions provide the application program with the motion control necessary to search a tape. These functions include: tbspc (backspace), trewc (rewind), and tape_cntl (tape control). The tape_cntl function, depending upon its argument list, can be used to execute the following type of motion control:

Not all applications can use tapes mounted in either blocked or unblocked mode. The following operational differences between blocked and unblocked tapes should be noted:

  1. Forward space or backward space operations on a blocked tape are performed at the physical block level, rather than the logical record level.
  2. If the tbspc function is issued to a blocked tape a system error will occur.

Tape Utilities: Tape utility functions provide information that helps applications manage tapes. The tdspc function returns a pointer to the data structure that contains tape status (tpstat). The tdspc_q function returns a pointer to the data structure that contains the module queue length (tpqstat) of a specified active tape.

Summary of General Tape Functions

Following is a summary of the general tape functions, listed in alphabetical order. Basic and higher-level function types are so noted.

Table 23. General Tape Functions

Function Summary Type
tape_close Close General Tape -- Deactivates a general tape from an entry (C only). Higher-level
tape_cntl Tape Control -- Provides tape control operations not otherwise provided; for example, write tape marks (C only). Higher-level
tape_open Open General Tape -- Makes a general tape available to an entry (C only). Higher-level
tape_read Read General Tape Record -- Gets a main storage block and reads a general tape record (C only). Higher-level
tape_write Write General Tape Record -- Writes a general tape record from a main storage block and releases the block (C only). Higher-level
tasnc Assign General Tape -- Makes a general tape that was reserved by a previous entry available to the current entry. Basic
tbspc Backspace General Tape -- Backspaces a general tape a specified number of physical blocks. Basic
tclsc Close General Tape -- Deactivates a general tape from an entry. Basic
TDCTC The Tape Data Chain Transfer macro writes or reads a single record from or into specified main storage areas. WAITC must be issued to ensure that the CCWs have been completed. For a list of tape commands supported by this macro, see TPF System Macros (Assembly language only). Basic
tdspc Display Tape Status -- Provides the status of a specified tape. Basic
tdspc_q Display Tape Queue Status -- Provides the module queue length of a specified active tape (C only). Basic
TDTAC The Tape Data Transfer macro performs 1 of several data transfer commands. For a list of tape commands supported by this macro, see TPF System Macros (Assembly language only). Basic
topnc Open General Tape -- Makes a general tape available to an entry. Basic
TPCNC The Tape Control macro performs 1 of several control commands. For a list of tape commands supported by this macro, see TPF System Macros (Assembly language only). Basic
tprdc Read General Tape Record -- Gets a main storage block and reads a general tape record. The tape remains open for use by other ECBs upon return. Basic
trewc Rewind General Tape -- Positions a general tape to the beginning of its first data record. Basic
trsvc Reserve General Tape -- Reserves a general tape at the current position for use by a future entry. Basic
tsync The Synchronize Tape function enables an application to ensure that records contained in a buffer are physically written to the tape. Basic
twrtc Write General Tape Record -- Writes a general tape record from a main storage block and releases the block. Basic

Operator Control of Tape Operations

The section discusses a method of structuring general tape programs to allow for independence from the hardware tape configuration. The application programmer provides the computer operator with a run sheet outlining the symbolic tape configuration for each job. This run sheet identifies each tape by general name and attributes (input, output, scratch, blocked, and so on). Using the run sheet, tape units are assigned and the necessary tapes are mounted for the job. The operator then communicates the tape units assigned and their corresponding general tape names to TPF.

Each tape is recorded as being in a ready status by TPF. When the utility job is started, the application program opens each tape with a call to either topnc or tape_open. TPF expects to find a ready tape for each topnc or tape_open call from the application program. If no such tape exists, TPF sends a message to the operator requesting the desired tape. Return from the open function is delayed until the tape is made ready.

Only the operator and TPF are concerned with the tape units in use. Thus, the application program, working with symbolic general tape names, is independent of the system's physical tape configuration. For details about C function use or macros, see the TPF C/C++ Language Support User's Guide, TPF General Macros, and TPF System Macros.