gtpa2m48Application Programming

Library Interface Tool

This section describes the library interface tool.

Purpose

The library interface tool produces a library transfer vector (LIBVEC) and the library call linkage stubs. Figure 67 shows the relationships found in the tool. To do this, the tool reads a file defining the library ordinal numbers and the functions contained in the libraries. These files are called library interface scripts. The library interface scripts define the libraries using @libid and @libfun statements.

Note

You do not need the library interface tool for dynamic link libraries (DLLs).

Figure 67. Output of the Library Interface Tool


Library ordinals are extremely important because they identify the library in the online system (using the array of library addresses). There are 1024 library ordinals available and 1024 functions can appear in each library. So, you can refer to more than 1 million functions throughout all the possible libraries. Of the the library ordinals, IBM reserves ordinals in the 0-199 range for its own use and the remainder (200-1023) for users.

The first non-comment line in a build script defines the library ordinal and library name. The remaining non-comment lines specify the ordinal numbers and names for the functions in the library.

Requirements and Restrictions

Format for the @libid Statement




library ordinal number
the decimal ordinal number of the library

library name
the name of the library

Additional Information

Format for the @libfun Statement




Notes:

  1. Each repetition takes place on a new line.

fn ordinal number
the decimal ordinal number of the function. The function ordinal is the number of the function in the library. The position in the file of the @libfun statement specifying a function has no effect on the ordinal of the function.

fn external name
The external name is the name of the function to be used by callers (users of the library). The internal_name is the name of the function in the library.

fn internal name
The internal name is optional and defaults to the external_name if it is not used.

Additional Information

Example of a Library Interface Tool Script

This script creates a small ISO-C library. There are several points to notice:

#######################################################################
 
@libid(0013,ASHB)                      # Ashby's Gems
 
@libfun(0000,mysort)                   # Called by payroll program
@libfun(0001,die,_TPFABRT)             # stop it, please
@libfun(0003,qsort1)                   # quicker
@libfun(0005,qsort2)                   # maybe
@libfun(0007,token)                    # get next word
 
@libfun(0002,hello)
@libfun(0004,mydate)                   # provides sensible date data
@libfun(0006,myssm)
#####libfun(0008,good1)                # Use another version
 
@libfun(1023,cursr)                    # last function in library
 

Running the Tool

The tool runs as an offline job. It uses several data sets as specified in the data sets table on page Table 26.

Table 26. File Specifications for the Library Interface Tool

DD Name DCB Characteristics Purpose
SYSIN LRECL=80,
RECFM=F or
RECFM=FB
Input file of library interface statements - the interface script
SYSPRINT   Output file for tool messages
SYSXV LRECL=80,
RECFM=F or
RECFM=FB
Output object file for the library transfer vector (LIBVEC)
SYSCLS LRECL=80,
RECFM=F or
RECFM=FB
Output object partitioned data set (PDS) containing the library call linkage stubs.

There are 2 run-time parameters: MSGS and SOURCE. They regulate the information provided to SYSPRINT.

MSGS
lists only library interface tool messages. This is the default.

SOURCE
lists the input statements interspersed with any messages from the library tool.

The JCL necessary to run the interface script is straight forward. The program name, LIBIvv, is requested to run from the ACP.LINK.RELvv library. According to our previous example the interface statements are found in a file called ASHBXVvv in the ACP.CSRCE.RELvv dataset. SYSPRINT is to the standard output file, SYSOUT. The library vector (LIBVEC) is put in the LIB1XVvv member of ACP.CSRCE.RELvv, overriding any existing version as LIBI proceeds. The stub library is put in the ACP.CLIB.RELvv file. Any error messages displayed are documented in the Offline section of TPF Messages, Volume 1 and TPF Messages, Volume 2.

 //LIBINTFC EXEC PGM=LIBIvv,REGION=4M
 //STEPLIB  DD DSN=ACP.LINK.RELvv.BSS,DISP=SHR
 //         DD DSN=LE.V1R3M0.SEDCLINK,DISP=SHR
 //         DD DSN=SYS1.PLI.SIBMLINK,DISP=SHR
 //SYSXV    DD DSN=ACP.OBJ.RELvv.BSS(ASHBXVvv),DISP=OLD
 //SYSCLS   DD DSN=ACP.CLIB.RELvv.BSS,DISP=OLD
 //SYSIN    DD  DSN=ACP.CSRCE.RT.RELvv(ASHBXVvv),DISP=SHR
 //SYSPRINT DD SYSOUT=A
 /*
 SOURCE
 MSGS
 /*

Return codes indicate if the tool successfully built the library vector and stub library.

Code
Meaning

 0 
indicates successful completion and informational messages

 4 
indicates unsuccessful completion and one or more warning messages as the highest severity

 8 
indicates unsuccessful completion and 1 or more error messages as the highest severity

 16 
indicates unsuccessful completion.