gtpa2m3cApplication Programming

Accessing Data in Assembly Language and C Language

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:

  1. The online files are a common data resource for all users and applications. Applications may be designed to provide independent function, but all share the same data resource. The application may structure data to its unique requirements, but the structuring must be in the context of the basic common data structure. This common database is allocated and structured at system generation. There is no facility comparable to MVS jobs or JCL which allow file allocation per job. The program or entry must use the preallocated system data resource. (See General Data Set and General File Support for a discussion of MVS-type data sets in TPF.)
  2. File addressing is symbolic so that the application programming is independent of the physical configuration. Essentially, all disk files are organized for direct access and are allocated across the entire physical storage to improve performance. The application always deals with a symbolic reference number that system programs and tables translate ultimately to a physical address. The user configuration can expand, take on new devices or eliminate old, without requiring application programming changes.

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.

Fixed File

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.

FACE, FACS, and FAC8C

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.

Note:
Entry requirements and return conditions for the FAC8C macro are different from FACE and FACS and are found through the IFAC8 DSECT in the IFACRET field. See TPF General Macros for more information about the FAC8C macro.

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:

Register
Use

 Register 0 (R0) 
The ordinal number in a record type.

 Register 6 (R6) 
The address of symbolic record type (for FACS) and record type (for FACE).

 Register 7 (R7) 
The location of an 8-byte field where the system file reference is to be placed. Normally, this location will be the FARW because the address must be there before the find or file function can be called.

Return conditions from FACE/FACS are as follows:

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

Making a Call to FACS Using TARGET(TPF)

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.(&regs); /* 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 *

face_facs Function

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.