gtpa2m4aApplication Programming

ISO-C Load Module Build Tool (CBLD)

This section describes the ISO-C load module build tool.

Purpose

The C load module build tool (CBLD) creates the job control language (JCL) needed to make files from compiled or assembled object files. Input to the C load module build tool consists of build script input records, collectively called a script, and comments.

The C load module build tool is called by SIP to generate the JCL needed to prelink and link-edit run-time (nondynamic) libraries, DLMs, or dynamic link libraries (DLLs). It can be used as a front-end utility to assist application programmers.

Requirements and Restrictions

Format for a Load Module Build Tool Statement







Notes:

  1. Each repetition takes place on a new line.

module_name
Name of the load module being created.

xx yy zz
Two-digit, alphanumeric version codes.

When DLM, LIBRARY, or DLL has a version code, the version appears on the DLM, library, or DLL startup code (CSTRTDxx, CSTRTLxx, or CSTDLLxx, respectively). If DLM, LIBRARY, or DLL does not have a version code supplied, version 40 is used as the default. Similarly, if the version code supplied is not valid, version code 40 is used.

Sample Load Module Build Scripts

The following shows an example of a build script for a dynamic load module (DLM). The load module in this example is a non-DLL application because there are no @IMPORTDS statements.

#######################################################################
#                                                                     #
#  SCRIPT NAME..... CDM0BS                                            #
#                                                                     #

  ·
  ·
  ·
# # ####################################################################### DLM CDM0LB # Include startup code for DLM #Object File Function Source Language #----------- -------- --------------- CDMAINLB # ZDMAP command C # mainline routine CDMPRSLB # zdmap_parse C CDMHLP40 # zdmap_help C CDMDSPF1 # zdmap_display C CDMER140 # zdmap_parse_error_handler; error C # messages in 1000 range CDMER240 # zdmap_retrieve_error_handler; C # error messages in 2000 range CDMER340 # zdmap_process_error_handler; C # error messages in 3000 range

The load module that results from this sample script is CDM0LB, where LB is the version code.

Note:
With link map support, if the object file name plus the version code is greater than 8 characters, an error message will be written to the message file and the INCLUDE card will not be written to the generated JCL deck.

The following shows an example of a build script for a DLL.

#######################################################################
#                                                                     #
#  SCRIPT NAME..... QZZ2BS                                            #
#                                                                     #

  ·
  ·
  ·
# # ####################################################################### DLL QZZ2RX # Include startup code for DLL @IMPORTDS CPP140 # Include a definition side-deck @IMPORTDS DLL3RK # Include a definition side-deck #Object File Function Source Language #----------- -------- --------------- QZZ2A41 # QZZ2A function C++ QZZ2B41 # QZZ2B function C
Note:
With the DLL keyword, CSTDLL startup code is used. The @IMPORTDS statements indicate the definition side-decks that this DLL imports from. @IMPORTDS statements must follow the DLL statement and precede the list of object files to be included.

The following shows an example of a build script for a DLM that is a DLL application.

#######################################################################
#                                                                     #
#  SCRIPT NAME..... QZZ1BS                                            #
#                                                                     #

  ·
  ·
  ·
# # ####################################################################### DLM QZZ1RX # Include startup code for DLM (DLL application) @IMPORTDS QCCC41 # Include a definition side-deck @IMPORTDS QDDDRX # Include a definition side-deck #Object File Function Source Language #----------- -------- -------------- QZZ1A41 # QZZ1A function C QZZ1B41 # QZZ1B function C++
Note:
DLL applications use the DLM keyword in the build script. CSTRTD startup code is used. The @IMPORTDS statements indicate the definition side-decks that this DLL application (DLM) imports from. @IMPORTDS statements must follow the DLM statement and precede the list of object files to be included.

Running the Build Tool

The C load module build tool (CBLD) requires 3 data sets, as described in Table 28.

Table 28. C Load Module Build Tool Data Sets

C Definition Purpose
stdin Input file containing a C load module build script.

The user specifies the name of a file, called the Load Module Build Script.

stdout Output file containing JCL to link the object files.

The user specifies the name of a file used to write the JCL to link the load modules. This file can be modified before it is run on MVS.

stderr Output file for C Load Module Build Tool messages.

The user specifies the name of a file used to write messages, including error messages. Read this file before the JCL is sent to MVS for execution.

The JCL needed to run the build tool is quite simple.

 //CLMBUILD EXEC PGM=CBLDxx,REGION=4M
 //STEPLIB  DD  DSN=ACP.LINK.INTGvv.NBS,DISP=SHR
 //         DD  DSN=LE.V1R3M0.SCEERUN,DISP=SHR
 //SYSUDUMP DD  DUMMY
 //SYSABEND DD  DUMMY
 //SYSPRINT DD  DSN=ACP.LK.RELxx(myprgvv),DISP=(NEW,PASS),UNIT=SYSDA,
 //         DCB=(BLKSIZE=400,RECFM=FB,LRECL=80)
 //SYSIN    DD  DSN=ACP.SRCE.OL.INTGvv(myprgvv),DISP=SHR
 /*

where

Return codes indicate if the generator successfully built the JCL object file.

Code
Meaning

 2 
Successful completion with only informational messages.

 4 
One or more warning messages were generated, but no error or fatal messages.

 8 
One or more error messages were generated, but no fatal message.

 16 
The tool ended with a fatal message.

When the build tool completes successfully, a JCL deck has been generated that will link the object library or DLM specified. The linkage editor, EDCPL, takes the object files specified (in this case using SYSIN) and produces a linked load module in the ACP.LK.RELvv data set.

For link map support, the generated JCL deck has extra data. For each included object file (excluding the startup code), the following three cards are added before each INCLUDE card:

  1. An ESD card for a symbol named @@LMnnnn, where nnnn is a 4-digit value beginning with 0001.
  2. A TXT card, which contains 8 bytes of character data. The first 6 bytes are for the name of the object file and the last 2 bytes contain the version code.
    Note:
    If the object file name is less than 6 characters, the name is blank-padded on the right. The version code is always in bytes 7 and 8.
  3. An END card.

With the addition of these three cards, the prelinker and linkage editor create an 8-byte CSECT before each object file. The symbol named in the ESD card is found by the offline loader so that the address of each 8-byte CSECT can be placed in the link map.

After the INCLUDE card for the last object file, the following cards are added by CBLD to build a final CSECT:

  1. An ESD card for a symbol named @@LMnnnn, where nnnn is a 4-digit value that is one digit higher than the previous value used.
  2. A TXT card, which contains the following 16 bytes of eye-catcher character data: 'END_OF_LAST_OBJ '
  3. An END card.

This CSECT is used to mark the end of the last object file so that its size can be determined.

The sample JCL that is generated for CDM0LB used a DLM specification on input. This can be seen by the inclusion of the CSTRTD object file (the DLM startup code) at the beginning of the list of object files to include.

The ESD, TXT, and END cards generated by CBLD contain some unprintable characters that cannot be seen in the following examples.

//$CDM0BS1 JOB ...
//PRELINK EXEC EDCPL,COND.LKED=(0,NE),
// LPARM='AMODE=31,RMODE=ANY,LIST,XREF'
//PLKED.SYSLIB DD DSN=ACP.CLIB.RELxx,DISP=OLD
//             DD DSN=ACP.STUB.RELxx,DISP=OLD
//PLKED.OBJLIB DD DSN=ACP.OBJ.RELxx,DISP=SHR
//PLKED.SYSIN DD *
 INCLUDE OBJLIB(CSTRTD40)
 ESD            @@LM0001
 TXT            CDMAINLB
 END                            1569623400 010195215
 INCLUDE OBJLIB(CDMAINLB)
 ESD            @@LM0002
 TXT            CDMPRSLB
 END                            1569623400 010195215
 INCLUDE OBJLIB(CDMPRSLB)
 ESD            @@LM0003
 TXT            CDMHLP40
 END                            1569623400 010195215
 INCLUDE OBJLIB(CDMHLP40)
 ESD            @@LM0004
 TXT            CDMDSPF1
 END                            1569623400 010195215
 INCLUDE OBJLIB(CDMDSPF1)
 ESD            @@LM0005
 TXT            CDMER140
 END                            1569623400 010195215
 INCLUDE OBJLIB(CDMER140)
 ESD            @@LM0006
 TXT            CDMER240
 END                            1569623400 010195215
 INCLUDE OBJLIB(CDMER240)
 ESD            @@LM0007
 TXT            CDMER340
 END                            1569623400 010195215
 INCLUDE OBJLIB(CDMER340)
 ESD            @@LM0008
 TXT            END_OF_LAST_OBJ
 END                            1569623400 010195215
/*
//LKED.SYSLMOD DD DSN=ACP.LK.RELxx(CDM0LB),DISP=OLD
//

As mentioned previously, object file names that are less than 6 characters are right-padded with blanks. Using QZZ0 as an example, the build script for C load module QZZ0 is as follows:

DLM QZZ0LD  # Include startup code for DLM
 
#Object File  Function                           Source Language
#-----------  --------                           ---------------
 
QZZ0LD        # QZZ0 function                    C
QZADDLC       # QZADD function                   C

After running the C load module build tool, the output is as follows:

//PLKED.SYSIN DD *
 INCLUDE OBJLIB(CSTRTD40)
 ESD            @@LM0001
 TXT            QZZ0  LD
 END                            1569623400 010195215
 INCLUDE OBJLIB(QZZ0LD)
 ESD            @@LM0002
 TXT            QZZ1A LC
 END                            1569623400 010195215
 INCLUDE OBJLIB(QZZ1ALC)
 ESD            @@LM0003
 TXT            END_OF_LAST_OBJ
 END                            1569623400 010195215
/*
Note:
The COND parameter on the EXEC card means "execute the link-edit step only if the prelink step returns zero." For online TPF ISO-C programs, all external references should be resolved by the prelinker and, therefore, a nonzero return code from the prelink step indicates an error in the build process. For regular MVS C programs (including offline TPF C programs), an RC=4 from the prelink step is normal because references to library functions are only resolved during the link-edit step.

CBLD Support for Dynamic Link Libraries (DLLs)

Both the previous DLL and DLL application build script examples show the use of the @IMPORTDS keyword. CBLD takes the load module name that follows this keyword and adds a definition side-deck INCLUDE statement to the list of INCLUDE statements in the JCL output deck. For a DLL only, the JCL will also contain the ACP.IMPORTS.RELvv definition side-deck SYSDEFSD data set for exported functions and variables. The following examples show the different JCL output decks generated by CBLD for a DLL and a DLL application:

See the programming guide for the IBM C/C++ compiler used by your installation for more information about DLLs and definition side-decks. See TPF System Generation for more information about the ACP.IMPORTS.RELvv definition side-deck data set.