gtpc2m08C/C++ Language Support User's Guide

TPF API Functions

This chapter contains an alphabetic listing of most TPF API functions. There are additional sets of functions that provide the interface for TPF Advanced Program-to-Program Communications (TPF/APPC). The descriptions for these functions are provided in the following chapters:

You can find more information about TPF/APPC support in TPF ACF/SNA Data Communications Reference.

There is also an additional set of functions for TCP/IP support. These functions are described in TPF Transmission Control Protocol/Internet Protocol.

The following information is shown for each TPF API function:

Format
The function prototype and a description of any parameters.

Description
The service that the function provides.

Normal Return
What is returned when the requested service has been performed.

Error Return
What is returned when the requested service could not be performed. Specifying incorrect function parameters results in a system error with exit.

Programming Considerations
Remarks that help the programmer to understand the proper use of the function and any side effects that may occur when the function is executed. Also, if the use of a particular function affects the use of another function, that is described.

Example
A code segment, showing a sample function call.

Related Functions
Where to find additional information pertinent to this function.
Note:
Remember to include tpfeq.h in the TARGET(TPF) source program even though it is not shown in any of the function prototypes. The tpfeq.h header must be the first header file included in any TPF C source module.

Several standard C library functions have been rewritten or substantially modified to run in the TPF system environment. For this reason, they are included in this reference section, even though they operate in the standard fashion; formats and return values have not been changed. These modified standard C library functions include:

Table 1. Modified Standard C Library Functions

Function Description
abort Terminate program abnormally
assert Verify condition or print diagnostic message
exit Exit an ECB
perror Write error message to standard error stream
fprintf Format and write data
printf Format and write data
sprintf Format and write data
scanf Scan input for variables

The remaining functions described in this chapter may be thought of as being on two levels; one group of them is better suited to general application use for one or more of the following reasons:

The functions we are talking about include the following:

Table 2. General Application Use C Library Functions

Function Description
file_record File a record
find_record Find a record
global Address or operate on TPF globals
glob Address global field or record
glob_keypoint Keypoint a global field or record
glob_lock Lock and Access a synchronizable global field or record
glob_modify Modify a global field or record
glob_sync Synchronize a global field or record
glob_unlock Unlock a global field or record
glob_update Update a global field or record
levtest Test core level for occupied condition
tape_close Close a general tape
tape_cntl Tape control
tape_open Open a general tape
tape_read Read a record from general tape
tape_write Write a record to general tape

These functions consist of a subset of system services.

The other group of functions, that are not as well suited to general application use, correspond to TPF macros written in assembler. Each of these functions performs one operation. They give the C programmer more control, direct access to the ECB (and registers), and assume that the programmer is coding them in the proper sequence. Some installations may want to restrict the use of these functions.

You may want to extend the existing set of higher-level functions to create a complete set, which includes the remaining system services. This can be done by adding a #define statement to the following functions and supplying alternative names for the preprocessor:

Function Description Suggested Alternative Name
getcc Obtain working storage block getcore
getfc Obtain file pool address gfs
relcc Release working storage block relcore
relfc Release file pool storage rfs
unfrc Unhold a file record unhold
waitc Wait for outstanding I/O completion wait

The TPF control program does not support C language programs. The implementation of C requires ECB virtual memory (EVM) and register connection to an ECB.