gtpa2m48 | Application Programming |
This section describes the library interface tool.
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.
- The ordinal numbers for the libraries and the functions specified in the
library interface scripts must correspond exactly to the ordinals for the
libraries and functions loaded online.
- Each function defined in the library interface script must also be defined
in one of the object files included in the library, or the results of calling
the function are undefined.
- Some common rules govern interface tool statements. Each statement
is restricted to a single line. Comments begin with the number sign
(#) and continue for the remainder of the input line. Blank
lines are ignored.
- Refer to TPF General Macros, TPF System Macros, or TPF
Operations for information on how to read syntax diagrams that represent
the statement formats.
- library ordinal number
- the decimal ordinal number of the library
- library name
- the name of the library
- Only 1 @libid statement can be used in each library interface script
- Every library must have a unique ordinal number. Each library
should have the same ordinal on every processor where it is loaded.
This is especially important when using libraries or code imported from
another installation.
- The name is 4 characters long and must be unique.
Notes:
- 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.
- Only 1 @libfun statement should appear for each function being
defined.
- For each @libfun statement you must also define a library function within
the library load module. The name of the function is the same as the
internal name defined by the @libfun statement (if
fn internal name is not specified, then the internal name
is the same as fn external name). If no such
function is defined, a call stub for the function will still be generated, and
the results of calling the function will be indeterminate. During
development, before the library is fully implemented, coding an empty function
that just returns, or one that only takes a snap dump, for each unimplemented
function will ensure that the library works in a predicatable manner.
This script creates a small ISO-C library. There are several points
to notice:
- The name of the library, ASHB, appears in the @libid statement. The
ordinal number of the ASHB library is 13. Notice that the line
immediately following the @libid statement is blank.
- The order that the functions appear in the library depends solely on the
ordinal specified. The order they appear in the list has no bearing on
the order of functions in the library. It is not required that the
ordinals be in increasing order.
- Function 8, good1, was commented out. It does not appear in the
finished library.
- The cursr function is defined to appear at the end of the library
generated. The programmer who created the list ensured that it would
appear as the last function in the library by making its ordinal 1023.
Where cursr appears in the input list has no effect.
- The die function has an internal name as well as an external name.
The internal name (_TPFABRT) is what the members of the library are called by
the library, and the external name (die) is used by callers.
#######################################################################
@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
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.