gtpa2m3c | Application Programming |
Database support is critical to the performance of any system. Performance of a system is largely dependent on the number of file storage requests and the time required to transfer them. TPF is designed to optimize the queuing and transfer time, but the number of requests is largely determined by application design. Therefore, good performance in any online system is the result of TPF support facilities, plus good application design and use of those facilities. For this reason, it is important that application programmers understand the concepts and basic structure supported by TPF.
High performance is an assumed objective of TPF data support. This implies 2 secondary objectives:
The main database of a TPF system comprises 2 categories of disk data file: the fixed file and the random pool. (General data sets and general files are excluded from this discussion. See General Data Set and General File Support.) Programs that run on the TPF system are another category of disk file, although they are not considered data.
The fixed file is analogous to a conventional multivolume data set organized for direct access. The storage area in the fixed file is allocated at system generation to specific functional application record types. An application cannot create a new record type, nor can it add to the allocation for a record type, during execution. It can use only what was allocated during system generation. The characteristics of the fixed file determine the type of records that should be placed in the fixed file.
For example, the fixed file often is used to contain records that are pointers to data in the random pool file area (see Random Pool File Area).
A given record type may be allocated on the fixed file as small (381 bytes), large (1055 bytes), or 4 K (4095 bytes). For assembly language, the record types are assigned symbolic names (which begin, by convention, with a #) and are equated in the system equate macro (SYSEQC) to an absolute value. For C language, the record types are assigned symbolic names and equated to absolute values in c$syseq.h using #define preprocessor statements.
For more information about fixed file storage, see TPF System Generation.
In a record type, each record has a record ordinal number (also called relative record number or RRN). However, to retrieve a record, the TPF system must know the ordinal number of the record across the entire DASD base. The file address compute programs (FACE and FACS) and the FAC8C macro calculate this number from the record type and record ordinal number.
FACE, FACS, and the FAC8C macro each consist of a system utility program and associated index table residing permanently in main storage. An application programmer must know the record type of the record to be retrieved. The application must develop the algorithm that calculates the desired ordinal number in that record type.
Figure 41 shows an example of a simple fixed file structure with 4 record types, the FACE/FACS table, and SYSEQC items that define it. Usually the numeric record type is set up using an equate or a #define. Nevertheless, any changes to the FACE index table may require programs that use FACE to be recompiled.
The FACE and FACS programs and the FAC8C macro are similar:
The numeric record types may be changed from time to time in the FACE table; they may also vary from MDBF subsystem to subsystem. This means programs that use FACE must be recompiled when the FACE table is changed or when they are transported between systems. The symbolic record types used by FACS avoid this drawback.
Figure 41. Example of Fixed File Organization and FACE/FACS Table
Application linkage from assembly language to FACE or FACS is by the ENTRC macro, by the face_facs function from ISO-C, and from TARGET(TPF) by the #pragma linkage and, optionally, the #pragma map preprocessor statements. For the FACS program or the FAC8C macro, the symbolic record type must be an 8-byte field, left-justified and padded with blanks, at the address specified.
Register requirements on input for FACE or FACS, which in C language normally are set up by means of the TPF_regs structure, are as follows:
Return conditions from FACE/FACS are as follows:
when R7 = 1 and
when R7 = 2 and
= 1 - Input record type invalid
= 2 - Input ordinal number out of range
= 3 - No records defined for the record type on the requested SSU/Processor/I-stream.
Return conditions from the FAC8C macro are found through the IFAC8 DSECT in the IFACRET field. See TPF General Macros for more information about the FAC8C macro.
Following is a FACS linkage coding example for assembly language:
L R0, EBW020 Load ordinal number LA R6,=CL8'#VD1VD' Symbolic record type LA R7,CE1FA2 Location = FARW, level 2 ENTRC FACS LTR R0,R0 Test for exception BZ EXCEPT Logic for exception return
The following TARGET(TPF) example makes a call to FACS to compute a file address prior to calling findc. Note that the assembler program FACS has been renamed for use in C as getfileadd.
#pragma linkage(getfileadd,TPF,N) /* define appropriate linkage #include <tpfapi.h> #include <tpfio.h> #define VD1RI "#VD1VD " struct TPF_regs regs; /* set up for register interface
·
·
·
regs.r6 = (long) VD1RI; /* pointer to symbolic record ty regs.r7 = (long) &(ecbptr()->ce1fa2); /* level where file addres regs.r0 = 10; /* ordinal number * &FACS.(®s); /* calculate fixed file address */ if (!regs.r0) /* FACS error? if (regs.r7 == 1) /* invalid record identification exit(0x12345); else { /* invalid ordinal number */ serrc_op(SERRC_EXIT,0x1234,"INVALID ORDINAL NUMBER",NULL); } findc(D2); /* find the record *
The face_facs ISO-C function provides for file address generation. The function is not available in TARGET(TPF). It initializes a file address reference word (FARW) with the data necessary to access a fixed file record.
The following generates a SON address for "#PROG1" record number 235 and stores it in the FARW for data level D6.
#include <tpfio.h>
·
·
·
unsigned long prog1_ordinal; int rc = face_facs(235, "#PROG1", 0, D6, &prog1_ordinal); switch (rc) { case 0: /* Success: the FARW at data level D6 contains the */ /* file address for "#PROG1" record ordinal number */ /* 235, and prog1_ordinal contains the maximum record */ /* ordinal for #PROG1 fixed file records. */
·
·
·
break; Default: /* Error Conditions include the record type is not */ /* defined, is empty, contains fewer records than the */ /* number requested, and so forth. */
·
·
·
break; }
For information on the face_facs function, see the TPF C/C++ Language Support User's Guide.