gtpa2m4a | Application Programming |
This section describes the ISO-C load module build tool.
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.
|
|
Notes:
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.
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.
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
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++
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
SYSIN records can also be defined in the input stream rather than in a data set.
//CBMBLD EXEC PGM=CBLDxx,PARM='NOJCL',REGION=4M
This parameter suppresses the generation of the JCL decks for prelinking and linking, and only generates the list of INCLUDE files. There is no JCL parameter. If NOJCL is not specific, the JCL decks are generated by default.
Return codes indicate if the generator successfully built the JCL object file.
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:
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:
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 /*
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:
//$QZZ2BS0 JOB ... //PRELINK EXEC EDCPL,COND.LKED=(0,NE), // LPARM='AMODE=31,RMODE=ANY,LIST,XREF,MAP', // PPARM='DLLNAME(QZZ2)' //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.SYSDEFSD DD DISP=SHR,DSN=ACP.IMPORTS.RELxx(QZZ2RX) //* //PLKED.DSD DD DISP=SHR,DSN=ACP.IMPORTS.RELxx //PLKED.SYSIN DD * INCLUDE OBJLIB(CSTDLL40) INCLUDE DSD(DLL240) INCLUDE DSD(DLL3RK) ESD @@LM0001 TXT QZZ2A 41 END 1569623400 010195215 INCLUDE OBJLIB(QZZ2A41) ESD @@LM0002 TXT QZZ2B 41 END 1569623400 010195215 INCLUDE OBJLIB(QZZ2B41) ESD @@LM0003 TXT END_OF_LAST_OBJ END 1569623400 010195215 /* //LKED.SYSLMOD DD DISP=OLD,DSN=ACP.LK.RELxx(QZZ2RX) //
//$QZZ1BS5 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.DSD DD DISP=SHR,DSN=ACP.IMPORTS.RELxx //PLKED.SYSIN DD * INCLUDE OBJLIB(CSTRTD40) INCLUDE DSD(QCCC41) INCLUDE DSD(QDDDRX) ESD @@LM0001 TXT QZZ1A 41 END 1569623400 010195215 INCLUDE OBJLIB(QZZ1A41) ESD @@LM0002 TXT QZZ1B 41 END 1569623400 010195215 INCLUDE OBJLIB(QZZ1B41) ESD @@LM0003 TXT END_OF_LAST_OBJ END 1569623400 010195215 /* //LKED.SYSLMOD DD DISP=OLD,DSN=ACP.LK.RELxx(QZZ1RX) //
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.