gtpa2m4dApplication Programming

Installing Additional IBM TARGET(TPF) C Library Functions

Periodically, application programmers can want to collect frequently used C code into a common library routine available to all application programs. The following section describes the procedure for doing this.

  1. Choose a TPF program segment to contain the library function source code. Prepare the C source code.
  2. Add a CLIBFUN macro call to segment C000 for the new function.

    The format of the CLIBFUN macro is:

        CLIBFUN cfun,tpfname,TYPE=,VERSION=,FEATURE=
    

    where:

    cfun
    is the name of the C library function

    tpfname
    is the TPF program segment that will contain the C library function

    TYPE
    is the TPF segment type for the SPPBLD macro. Valid types are:

     RT 
    TPF system assembler code

     UR 
    user assembler code

     CRT 
    TPF system C code

     CUR 
    user C code

     OCO 
    object code only.

    VERSION
    is the version code on the TPF segment name. The default is 40.

    FEATURE
    is the name of a TPF feature, such as TPFAR. Functions that belong to optional features need to code this parameter. (This parameter is optional for functions of required features.) The feature name is defined in SYGLB and set by SYSET.
    Note:
    If the feature is not active, the CLIBFUN macro call for that set of functions is considered a dummy call.

    cfun and tpfname are positional, required parameters. TYPE and VERSION are keyword parameters, and VERSION is optional.

    The purpose of segment C000 is to provide a single point of update whenever new library functions are created. C000 contains a CLIBFUN macro call for every library function in the system. When C000 is assembled, 4 sets of objects are automatically produced in the form of comment cards in the object decks:

    1. A set of #pragma map and #pragma linkage statements for the C compiler. Remove these #pragma map and #pragma linkage statements and put them in the tpflink.h header file. This header file contains all of the information the compiler needs to provide linkage.
    2. A set of allocation statements for the system allocator. Remove these statements and add them to your allocator input deck.
    3. A set of SPPBLD statements for the TPF program list. The SPPBLD macro is used to build dependency tables that determine which programs will or will not be included in the system. Extract these SPPBLD cards and add them to SPPGML.
    4. A set of LOADER CALL cards for the system loaders. These cards can be extracted and added to the appropriate load deck.
    Note:
    To avoid having to recompile all existing C application programs, add CLIBFUN calls for new library functions to the END of the list in C000. The order in which the CLIBFUN calls appear directly affects the calling linkage produced by the compiler. If the sequence of the CLIBFUN calls is disturbed, you must recompile all application programs that refer to library functions that have moved to ensure that the compiler resolves the linkage to each library function correctly.

    You can also code the following special form,

        CLIBFUN DUMMY,tpfname
    

    which will reserve an entry in the quick enter directory for future use. No comment cards will be generated for this item, but it will serve as a placeholder so that the sequence of CLIBFUN calls is not disturbed when the item is later converted to a normal CLIBFUN call. If any program attempts to call a library function using an index number that corresponds to a dummy slot, segment C246 will be activated and cause the ECB to exit with system error.

  3. Assemble C000 and use a text editor to extract the cards needed from the object deck, as described in Step 2.

    You can want to extract only the allocator statements, SPPBLD, and LOADER CALL cards that are actually required for the new library function. However, be sure to replace the entire set of #pragma statements in tpflink.h with those generated by assembling C000 as the new set of #pragma map and #pragma linkage statements are interrelated.

  4. Prepare to run SIP.

    Check if an update to the APSIZxx parameter of the CORREQ macro is required to accommodate the additional code. This can be determined by examining the sum of accumulated code size that appears in the object decks (and in the listings) when C000 is assembled.

  5. Run SIP Stages I and II. The resulting TPF system will contain the new library function.
  6. Be sure to compile any application programs that call the new function against the updated version of tpflink.h. This will ensure that the library function linkage is resolved correctly by the compiler.