nld Manual Abstract Product Version Supported Release Updates (RVUs) Part Number Published

nld Manual Abstract This publication explains how to use the TNS/R native link editor nld (T6017), which links and changes object file attributes. Product Version nld D44 Supported Release Updates (RVUs) This publication supports G06.26 and all subsequent D-series and G-series RVUs until otherwise indicated by its replacement publication. Part Number Published 528272-001 April 2005

Document History Part Number Product Version Published 528272-001 nld D44 April 2005

nld Manual Glossary Index Examples Tables What s New in This Manual vii Manual Information vii New and Changed Information vii About This Manual ix Audience ix Related Reading ix Notation Conventions x 1. Introduction Native Object Files 1-2 nld 1-2 2. nld Utility Running the nld Utility in the Guardian Environment 2-1 Running the nld Utility in the OSS Environment 2-3 Running Windows nld on the PC 2-4 Components of Windows nld 2-4 Directory Structure of Windows nld 2-5 Compilers That Can Launch Windows nld 2-5 How Windows nld Differs from nld 2-5 How the ETK Command-Line and GUI Interfaces Differ 2-6 Command-Line Interface Linking Options 2-7 Changing the Target Environment 2-7 Creating Loadfiles and Linkfiles 2-8 Linking Programs 2-8 C Programs 2-8 C++ Programs 2-9 COBOL Programs 2-11 ptal Programs 2-12 Mixed-Language Programs 2-12 Programs With Embedded NonStop SQL/MP 2-12 Linking User Libraries 2-12 Hewlett-Packard Company 528272-001 i

Contents 2. nld Utility (continued) 2. nld Utility (continued) Linking SRLs 2-14 Specifying SRLs 2-15 Determining Which SRLs Programs Require 2-16 Linking Archive Files 2-20 Linking Floating-Point Programs 2-21 Link-Time Consistency Checking 2-22 Run-Time Consistency Checking 2-24 Linking Mixed-Language Programs 2-25 Searching for Archives and SRLs With Simple File Names 2-26 Dynamic and Static Linking 2-27 Stripping Symbol Information 2-28 nld Compilation Rules 2-28 Case-Sensitivity 2-28 Local and Shared Symbols 2-29 Declaration and Definition 2-30 3. nld Options -allow_duplicate_procs 3-2 -allow_missing_libs 3-3 -allow_multiple_mains 3-3 -ansistreams 3-3 -bdynamic 3-3 -bstatic 3-4 -change 3-4 -e 3-5 -elf_check 3-5 -export 3-5 -fl or -obey 3-6 -import 3-6 -l or -lib 3-7 -L or -libvol 3-8 -libname 3-9 -nostdfiles 3-9 -nostdlib 3-9 -noverbose 3-10 -NS_extent_size 3-10 -NS_max_extents 3-10 -o 3-11 ii

Contents 3. nld Options (continued) 3. nld Options (continued) -r 3-11 -rename 3-12 -s 3-12 -set 3-13 -stdin 3-15 -strip 3-16 -ul 3-16 -verbose 3-16 -x 3-17 -y 3-17 4. nld Diagnostic Messages General Information 4-1 Terms That Appear in nld Diagnostic Messages 4-2 Fatal Errors 4-11 Nonfatal Errors 4-60 Warnings 4-68 Informational Messages 4-76 A. Sample nld and noft Session Example Program A-1 Header Files A-2 Source Module MAINC A-3 Source Module MODULE1C A-3 Source Module MODULE2C A-5 User Library UTILC A-6 Compilation Commands A-6 nld Command Examples A-7 Program Output A-8 noft Command Examples on a Linkfile A-9 FILE A-9 LISTATTRIBUTE A-9 LISTCOMPILERS A-10 LISTPROC A-10 LISTSOURCE A-12 LISTSRLINFO A-13 LISTUNRESOLVED A-14 iii

Contents A. Sample nld and noft Session (continued) A. Sample nld and noft Session (continued) noft Command Examples on a Loadfile A-15 FILE A-15 LISTATTRIBUTE A-16 LISTCOMPILERS A-17 LISTPROC A-17 LISTSOURCE A-18 SET SORT A-19 LISTSRLINFO A-20 LISTUNRESOLVED A-20 LISTOPTIMIZE A-21 XREFPROC A-22 DUMPPROC A-24 LISTSRLFIXUPS A-26 LISTSRLEXPORTS A-27 LISTSRLFIXUPS A-27 B. Converting From Binder to nld Object File Differences B-1 Linking Unit Differences B-2 Comparing Binder With nld B-3 C. Native Object File Structure Code and Data Segments C-1 MDEBUG Section C-2 Glossary Index Examples Example 2-1. Creating a Loadfile (Guardian) 2-2 Example 2-2. Changing the HIGHPIN Attribute (Guardian) 2-2 Example 2-3. Creating a Loadfile (OSS) 2-3 Example 2-4. Creating a User Library (OSS) 2-3 Example 2-5. Creating a Program File (OSS) 2-3 Example 2-6. Creating an Executable C Program (OSS) 2-4 Example 2-7. Running nmcobol and Launching Windows nld 2-5 Example 2-8. Running nld from the Command Prompt 2-6 Example 2-9. Creating a Program for the Guardian Environment (OSS) 2-7 iv

Contents Examples (continued) Examples (continued) Example 2-10. Creating an Executable C Program 2-9 Example 2-11. Linking a Mixed-Language Program With IEEE Floating-Point Format 2-25 Example 2-12. Searching for ZCRTLSRL and ZCRESRL (Guardian) 2-27 Example 2-13. Searching for ZCRTLSRL and ZCRESRL (OSS) 2-27 Example 2-14. Searching for ZCOBSRL and ZCRESRL (OSS) 2-27 Example A-1. Header File GLOBALSH With Edit Line Numbers A-2 Example A-2. Header File MODULE1H With Edit Line Numbers A-2 Example A-3. Header File MODULE2H With Edit Line Numbers A-2 Example A-4. Header File UTILH With Edit Line Number A-3 Example A-5. Source Module MAINC With Edit Line Numbers A-3 Example A-6. Source Module MODULE1C With Edit Line Numbers A-4 Example A-7. Source Module MODULE2C With Edit Line Numbers A-5 Example A-8. User Library UTILC With Edit Line Numbers A-6 Example A-9. Linking an Executable User Library A-7 Example A-10. Linking a Program File A-7 Example A-11. Sample Program Output A-8 Example A-12. FILE Option (Linkfile) A-9 Example A-13. LISTATTRIBUTE Option (Linkfile) A-9 Example A-14. LISTCOMPILERS Option (Linkfile) A-10 Example A-15. LISTPROC Option (Linkfile) A-11 Example A-16. LISTSOURCE Option (Linkfile) A-12 Example A-17. LISTSRLINFO Option (Linkfile) A-13 Example A-18. LISTUNRESOLVED Option (Linkfile) A-14 Example A-19. FILE Option (Loadfile) A-15 Example A-20. LISTATTRIBUTE Option (Loadfile) A-16 Example A-21. LISTCOMPILERS Option (Loadfile) A-17 Example A-22. LISTPROC Option (Loadfile) A-17 Example A-23. LISTSOURCE Option (Loadfile) A-18 Example A-24. Effect of SET SORT on LISTPROC and LISTSOURCE A-19 Example A-25. LISTSRLINFO Option (Loadfile) A-20 Example A-26. LISTUNRESOLVED Option (Loadfile) A-20 Example A-27. LISTOPTIMIZE Option (Loadfile) A-21 Example A-28. Effect of SET SCOPESOURCE on LISTOPTIMIZE Option A-21 Example A-29. Effect of SET SCOPESOURCE on XREFPROC Option A-22 Example A-30. Effect of RESET SCOPESOURCE on XREFPROC Option A-22 Example A-31. XREFPROC Option (Loadfile) A-23 Example A-32. DUMPPROC Option A-24 v

Contents Examples (continued) Examples (continued) Tables Example A-33. Effect of SET FORMAT INNERLIST on DUMPPROC Option A-25 Example A-34. LISTSRLFIXUP Option A-26 Example A-35. LISTSRLEXPORTS Option A-27 Example A-36. LISTSRLFIXUP (LLF) Option A-27 Example B-1. Linking Two Object Files in Binder and nld (Simple Case) B-4 Example B-2. Linking Two Object Files in Binder and nld (Less Simple Case) B-5 Example B-3. Setting the INSPECT Attribute in Binder and nld B-5 Table 2-1. Using the Guardian nld Utility to Link SRLs 2-16 Table 2-2. Using the OSS nld Utility to Link SRLs 2-18 Table 2-3. Floating-Point Consistency Check by nld Utility (floattype Not Specified) 2-22 Table 2-4. Floating-Point Type Consistency Check by nld (floattype Specified) 2-23 Table 2-5. Incompatible Program File and User Library floattypes (TNS) 2-24 Table 2-6. Local and Shared Symbols by Language 2-29 Table 2-7. Declarations and Definitions by Language 2-30 Table 3-1. nld Flag Summary 3-1 Table 3-2. Descriptions of Run-Time Attributes 3-13 Table 3-3. Default Run-Time Attribute Values 3-15 Table 4-1. nld Diagnostic Types 4-1 Table 4-2. Warning and Informational Message Defaults 4-1 Table B-1. Corresponding Binder Tasks and Native Utilities B-1 Table B-2. Comparing Binder With nld B-3 Table C-1. Loadfile Segments and Sections C-1 Table C-2. MDEBUG Section Tables C-2 vi

What s New in This Manual Manual Information nld Manual Abstract This publication explains how to use the TNS/R native link editor nld (T6017), which links and changes object file attributes. Product Version nld D44 Supported Release Updates (RVUs) This publication supports G06.26 and all subsequent D-series and G-series RVUs until otherwise indicated by its replacement publication. Part Number Published 528272-001 April 2005 Document History Part Number Product Version Published 528272-001 nld D44 April 2005 New and Changed Information The information in this manual was previously in the nld and noft Manual. vii

What s New in This Manual New and Changed Information viii

About This Manual This manual explains how to use the TNS/R native object file utility nld, which which links and changes object file attributes. Topics: Audience on page ix Related Reading on page ix Notation Conventions on page x Audience This manual is intended for systems programmers and application programmers who are familiar with: HP NonStop servers HP NonStop operating system Reference manuals and programmer s guides for the languages in which programs are written (C/C++, COBOL, and ptal see Related Reading on page ix) Related Reading C/C++ Programmer s Guide COBOL85 for NonStop Systems Manual DLL Programmer s Guide for TNS/R Systems Guardian Procedure Calls Reference Manual Guardian Procedure Errors and Messages Manual Guardian Programmer s Guide Guardian User s Guide Inspect Manual ld Manual noft Manual Open System Services Programmer s Guide Open System Services User s Guide Open System Services Shell and Utilities Reference Manual ptal Conversion Guide ptal Reference Manual TACL Reference Manual TNS/R Native Application Migration Guide Using the Command-Line Cross Compilers on Windows ix

About This Manual Notation Conventions Notation Conventions Hypertext Links on page x General Syntax Notation on page -x Example Notation on page xii Change Bar Notation on page xii Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example: This requirement is described under Backup DAM Volumes and Physical Disk Drives on page 3-2. General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list may be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: LIGHTS [ ON ] [ OFF ] [ SMOOTH [ num ] ] K [ X D ] address-1 x

About This Manual General Syntax Notation { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list may be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LISTOPENS PROCESS { $appl-mgr-name } { $process-name } ALLOWSU { ON OFF } Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT { OFF ON SAVEABEND } Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address-1 [, new-value ]... [ - ] {0 1 2 3 4 5 6 7 8 9}... An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char..." Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be entered as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must enter as shown. For example: "[" repetition-constant-list "]" Item Spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In the following example, there are no spaces permitted between the period and any other items: $process-name.#su-name xi

About This Manual Example Notation Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] CONTROLLER [, attribute-spec ]... Example Notation In examples with user input, user input is in bold type and it is assumed that the user presses the return key after typing the input. For instance, in the example: ENTER RUN CODE?123 CODE RECEIVED: 123.00 the system displays ENTER RUN CODE on one line and prompts the user with? on the next line, the user types 123 and presses return, and the system displays: CODE RECEIVED: 123.00. Change Bar Notation A change bar (as shown to the right of this paragraph) indicates a substantive difference between this edition of the manual and the preceding edition. Change bars highlight new or revised information. xii

1 Introduction The nld utility (or native link editor) links one or more non-pic object files to produce a single non-pic loadfile or linkfile. (To produce a PIC object file such as a dynamic-link library (DLL) use the ld utility, which is explained in the ld Manual.) The nld utility operates in the TNS/R native mode development environment on TNS/R native object files both PIC (position-independent code) and non-pic (nonposition-independent code) files. PIC and non-pic native object files are generated by the native C, native C++, native COBOL, and ptal compilers. For information on these compilers, see these manuals: C/C++ Programmer s Guide COBOL85 for NonStop Systems Manual ptal Reference Manual For general information about PIC, see the DLL Programmer s Guide for TNS/R Systems. In the TNS/R native development environment, the functions that nld provides are similar but not identical to the functions that the Binder product provides in the TNS development environment. For migration information, see Appendix B, Converting From Binder to nld. Topics: Native Object Files on page 1-2 nld on page 1-2 1-1

Introduction Native Object Files Native Object Files nld nld operates on native object files. Native object files are in executable and linking format (ELF), a standard format used for object files, with HP extensions. For details on the structure of native object files, see Appendix C, Native Object File Structure. Native object files are either linkfiles or loadfiles, but not both. Can Be Linked to Produce a Loadfile Can Be Loaded for Execution Linkfiles Yes No Loadfiles No Yes Native compilers produce only linkfiles. The nld utility can produce either linkfiles or loadfiles. Linkfiles can be used as nld input. Loadfiles can be used as nld input in several ways: For change of attributes or stripping options For use in determining the libraries to be used at run time As symbol bindings. For example: nld newobj.o crtlmain.o zcrtlsrl specifies a linkfile (newobj.o), a library linkfile (crtlmain.o), and a library loadfile (zcrtlsrl). Including the library loadfile in the nld command makes its facilities available at run time. Native object files in the Guardian environment have a file code of 700. Use the nld utility to: Link one or more non-pic TNS/R native object files to produce a single non-pic loadfile or linkfile Modify existing loadfiles The nld utility runs in these environments: Guardian OSS Microsoft Windows NT, Windows 2000, and Windows XP, by means of the HP Enterprise Toolkit NonStop Edition (ETK), which is based on Microsoft Visual Studio.NET 1-2

Introduction nld The nld utility has the same capabilities in each environment, but each environment has a slightly different syntax. You can run nld in these ways: Directly Automatically, from these compilers: Environment Compiler T Number Guardian NMC T9577 NMCPLUS T9225 NMCOBOL T8107 OSS c89 T8164 nmcobol T8107 Windows NT* Windows 2000* Windows XP* All the previous and ptal T9248 * By means of ETK As a batch process by issuing nld commands from a terminal or a command file You cannot run nld interactively. This manual explains only how to run nld directly. For information on running nld from compilers, see these manuals: C/C++ Programmer s Guide COBOL85 for NonStop Systems Manual ptal Reference Manual nld can use archives created by the ar utility, as explained in the noft Manual. For more information: Section 2, nld Utility Section 3, nld Options Section 4, nld Diagnostic Messages 1-3

Introduction nld 1-4

2 nld Utility The nld utility, the native link editor, links one or more non-pic TNS/R native object files to produce a single non-pic loadfile or linkfile. Topics: Running the nld Utility in the Guardian Environment on page 2-1 Running the nld Utility in the OSS Environment on page 2-3 Running Windows nld on the PC on page 2-4 Changing the Target Environment on page 2-7 Creating Loadfiles and Linkfiles on page 2-8 Linking Programs on page 2-8 Linking User Libraries on page 2-12 Linking SRLs on page 2-14 Linking Archive Files on page 2-20 Linking Floating-Point Programs on page 2-21 Searching for Archives and SRLs With Simple File Names on page 2-26 Dynamic and Static Linking on page 2-27 Stripping Symbol Information on page 2-28 nld Compilation Rules on page 2-28 Running the nld Utility in the Guardian Environment To run the nld utility in the Guardian environment, use this syntax: [RUN] NLD [ / IN command-filename [, OUT output-listing ] / ] [ Filename ]... [ option ]... Note. Filename arguments need not be specified before option arguments. Arguments can be mixed. An item that begins with a hyphen (-) is an option. Any other item is a Filename. [RUN] NLD is the TACL command to start the nld process. 2-1

nld Utility Running the nld Utility in the Guardian Environment command-filename is a Guardian file name or a map DEFINE for an nld command file. nld uses command-filename only if no Filename or option arguments are specified on the command line. Otherwise, nld ignores command-filename. output-listing is a Guardian file name to which nld writes its listing. The file can be type 101 (edit file) or type 129 (spooler file). If output-listing is a disk file name and the file does not exist, nld creates a type 101 edit file. If you omit the OUT option, nld writes its output to your current default output file. Filename is a Guardian file name for a native object file. Depending on the options specified, the file can be a linkfile or a loadfile. option is an nld option (a flag and its parameters, if any). You must include a space between a flag and its parameters, except after the -l and -L flags. Case is not significant when specifying nld options, except for the -l and -L flags. For descriptions of nld flags and their parameters, see Section 3, nld Options. If you do not specify parameters on the command line and the standard input file is not an edit file, nld returns syntax information. You can specify input from the command line or use the option -fl or -obey on page 3-6, which enables the contents of a file to be entered in the command input at the point specified. Use the -obey option to supply several options or input file names. Example 2-1 links together the input object files named objecta and objectb to create a loadfile named objectc. Example 2-1. Creating a Loadfile (Guardian) nld objecta objectb -o objectc Example 2-2 changes the HIGHPIN attribute in the loadfile exeobj to OFF. Example 2-2. Changing the HIGHPIN Attribute (Guardian) nld -change highpin off exeobj 2-2

nld Utility Running the nld Utility in the OSS Environment Running the nld Utility in the OSS Environment To run the nld utility in the OSS environment, use this syntax: nld [ option ]... Filename option is an nld option (a flag and its parameters, if any). A flag begins with a hyphen (-). You must include a space between a flag and its parameters, except after the -l and -L flags. Case is not significant when specifying nld options, except for the -l and -L flags. For descriptions of nld flags and their parameters, see Section 3, nld Options. Filename is an OSS filename for a TNS/R native object file. The nld utility supports /E OSS directories. Depending on the flags specified, the object file can be a linkfile or a loadfile. You can specify input from the command line or use the option Section, -fl or -obey, which enables the contents of a file to be entered in the command input at the point specified. Use the -obey option to supply several options or input file names. Example 2-3 combines object files named objecta, objectb, and objectc and creates a loadfile named objectd. Example 2-3. Creating a Loadfile (OSS) nld objecta objectb objectc -o objectd Example 2-4 links the object files named obj1.o and obj2.o together into a user library named lib. Example 2-4. Creating a User Library (OSS) nld obj1.o obj2.o -ul -o lib Example 2-5 links object files named obj3.o and obj4.o together into a program named prog. It also associates prog with a user library with the Guardian name $a.b.c. The backslash prevents the shell from misinterpreting the dollar sign ($). Example 2-5. Creating a Program File (OSS) nld obj3.o obj4.o -o prog -libname \$a.b.c 2-3

nld Utility Running Windows nld on the PC Example 2-6 uses the C object files test1.o and test2.o to build a program named prog. Because the program is a C program, the crtlmain.o library object file is required. The obey option directs nld to link all of the required SRLs in the program. Example 2-6. Creating an Executable C Program (OSS) nld /user/lib/crtlmain.o test1.o test2.o \ -obey /usr/lib/libc.obey -o prog Running Windows nld on the PC Using ETK, you can run Windows nld on: Windows NT 4.0 Windows 2000 Windows XP ETK has both a command-line interface and a graphical user interface (GUI). Topics: Components of Windows nld on page 2-4 Directory Structure of Windows nld on page 2-5 Compilers That Can Launch Windows nld on page 2-5 How Windows nld Differs from nld on page 2-5 How the ETK Command-Line and GUI Interfaces Differ on page 2-6 Command-Line Interface Linking Options on page 2-7 Components of Windows nld The components of Windows nld are: Component nld.dll nld.exe Description A Windows dynamic-link library (DLL) that implements nld functionality A Windows executable file that provides a direct command line interface for nld functionality 2-4

nld Utility Directory Structure of Windows nld Directory Structure of Windows nld The directory structure of Windows nld is: Directory bin cmplr lib Files nld.exe nld.dll SRLs for linking Note. On the PC, you must use -l or -lib on page 3-7 on the command line to specify the location for nld to look for SRLs and archives. There are no standard library locations. Compilers That Can Launch Windows nld Windows nld is a component of these Windows-based cross-compilers, which can launch it automatically after compilation: Compiler Native C/C++ Native COBOL ptal Compiler Driver DLL c89.dll coboldvr.dll ptaldvr.dll When a compiler launches Windows nld, the compiler driver selects the correct runtime libraries. The command in Example 2-7 on page 2-5 runs the native COBOL85 compiler, nmcobol, compiling the source files text3.cob and text4.cob, and then launches Windows nld, producing the executable file pcoss.exe for the OSS environment. Example 2-7. Running nmcobol and Launching Windows nld nmcobol text3.cob text4.cob -Wsystype=oss -o pcoss.exe How Windows nld Differs from nld Windows nld object files are compatible with NonStop operating system object files; therefore, you can build object files on either of these platforms and then link them on the other. Linking object files on Windows nld is usually much faster than linking them on the NonStop operating system. For Windows nld, these flags are meaningless: -NS_extent_size on page 3-10 -NS_max_extents on page 3-10 2-5

nld Utility How the ETK Command-Line and GUI Interfaces Differ How the ETK Command-Line and GUI Interfaces Differ Software Requirements Where Instructions Are Run-Time Libraries Filename Path Format ptal Command-Line Interface You need only install one of the Compilers That Can Launch Windows nld on page 2-5 Using the Command-Line Cross Compilers on Windows on the compiler s CD You must specify them NonStop operating system format (see the Guardian User s Guide or the Open System Services User s Guide) You must compile and link a program in separate steps GUI You must install all of: One of the Compilers That Can Launch Windows nld on page 2-5 Microsoft Visual Studio.NET The ETK package Online help You must specify them Windows format (see the documentation for your Windows operating system)* You can compile and link a program in one step * A Windows format file name path that includes a backslash (\) or a space must be enclosed in quotation marks (as in Example 2-8 on page 2-6). Example 2-8. Running nld from the Command Prompt nld test1.o test2.o "c:\program Files\Compaq ETK-NSE\g06.15\lib\crtlmain.o" -set systype oss -set highpin on -set highrequester on -set inspect on -set runnamed on -verbose -L "c:\program Files\Compaq ETK-NSE\g06.15\lib" -obey "Program Files\Compaq ETK-NSE\g06.15\lib\libc.obey" -o mystest.exe 2-6

nld Utility Command-Line Interface Linking Options Command-Line Interface Linking Options The command-line interface link options for C/C++ and COBOL are: -l=library -L=directory -s -Wansistreams -WBdynamic -WBstatic -Wheap=N[b w p] -Whighpin={on off} -Whighrequesters={on off} -W[no]inspect -Wnld="arguments" -Wnld_obey file -Wnostdlib -Wr -Wrunnamed -W[no]saveabend -Wx Changing the Target Environment The target environment is the environment in which you intend to run the program file. By default, the Guardian version of nld builds files intended to run in the Guardian environment and the OSS version of nld builds files intended to run in the OSS environment. To build a program file intended to run in the Guardian environment using the OSS version of nld, specify: -set systype guardian To build a program file intended to run in the OSS environment using the Guardian versions of nld, specify: -set systype oss Note. In some cases, such as when C/C++ programs include stdio.h, setting the target environment with the -set systype option might result in a program that executes incorrectly in the specified environment. In such cases, you must specify the systype option on the compiler command line to ensure the correct code is created. Example 2-9, in the OSS environment, links the object files names obj6.o and obj7.o into a program named prog that you intend to run as a Guardian process. Example 2-9. Creating a Program for the Guardian Environment (OSS) nld obj6.o obj7.o -o prog -set systype guardian 2-7

nld Utility Creating Loadfiles and Linkfiles Creating Loadfiles and Linkfiles A loadfile cannot be linked to a new object file. It can be used only as input to nld with options that modify an existing loadfile. A linkfile can be used as nld input again. nld creates a loadfile if you do not specify the -r flag. If you do specify the -r flag, nld creates a linkfile. Linking Programs C Programs on page 2-8 C++ Programs on page 2-9 COBOL Programs on page 2-11 ptal Programs on page 2-12 Mixed-Language Programs on page 2-12 Programs With Embedded NonStop SQL/MP on page 2-12 Note. You can only link linkfiles into a program. You cannot link loadfiles, or a combination of loadfiles and linkfiles, into a program. C Programs C programs require access to their run-time environments. To create an executable C program, you must link to the run-time environment initialization code and the shared run-time libraries (SRLs) your program uses. The NMC and c89 compilers automatically link to the required items. If you use nld directly to link a C program, you must specify these items in nld options. To create an executable C program using nld: 1. Link together the object code files that you compiled. 2. Link to the C run-time library initialization object code file: Environment Guardian OSS Run-Time Library Initialization Object Code File $SYSTEM.SYSTEM.CRTLMAIN /usr/lib/crtlmain.o 3. Link to the SRLs that your program uses. To link the standard set of C SRLs, use these options: Environment Guardian OSS Option for Linking the Standard Set of C SRLs -OBEY $SYSTEM.SYSTEM.LIBCOBEY -obey /usr/lib/libc.obey 2-8

nld Utility C++ Programs 4. If your program uses active backup programming functions, such as ns_start_backup(), link to the active backup programming support object code file: Environment Guardian OSS Active Backup Programming Support Object Code File $SYSTEM.SYSTEM.CRTLNS /usr/lib/crtlns.o 5. If you want to overload the new and delete operations, you must link these files to your program: Environment Guardian OSS Active Backup Programming Support Object Code File $SYSTEM.SYSTEM.CPPINIT /usr/lib/cppinit.o For information about active backup programming in C, see the Guardian Programmer s Guide. Example 2-10 takes a C source program named MYSRC, compiles it into an object file named MYOBJ, and creates a loadfile named MYEXEC. It links to the C run-time library initialization object file named CRTLMAIN and the SRLs named ZCRESRL and ZCRTLSRL. In the Guardian environment, ZCRESRL and ZCRTLSRL are located in the active SYSnn subvolume. Example 2-10. Creating an Executable C Program Guardian Environment NLD $SYSTEM.SYSTEM.CRTLMAIN MYOBJ -o MYEXEC -l ZCRESRL -l ZCRTLSRL OSS Environment & nld /usr/lib/crtlmain.o myobj -o myexec -l zcresrl -l zcrtlsrl C++ Programs There are three versions of C++: Version Conforms to ANSI and ISO Standards for C++ 1 No No 2 No Yes 3 (default) Yes Yes Supports PIC (position-independent code) When you compile a C++ program, you can specify its version with the command-line directive VERSION1, VERSION2, or VERSION3. The default is VERSION3. 2-9

nld Utility C++ Programs The version, known as the C++ Dialect, is stored in one of the program's internal structures. To see a program s C++ dialect, use the noft option LISTATTRIBUTE or LA (see the noft Manual). C++ Input Files C++ Version Recorded in the Loadfile* VERSION1 CPP_V1 (1) VERSION2 CPP_V2 (2) VERSION3 CPP_V3 (3) Mixed versions Lowest version * When none of the input files are C++ files, the value CPP_NEUTRAL is recorded in the loadfile. Mixing versions of C++ in a loadfile is not recommended (except for mixing CPP_NEUTRAL with one other version). The result is either a nonfatal error or a warning, depending on the combination: L I N K F I L E CPP_NEUTRAL CPP_V1 CPP_V2 CPP_V3 LINKFILE CPP_NEUTRAL CPP_V1 CPP_V2 CPP_V3 Loadfile is CPP_NEUTRAL Loadfile is CPP_V1 Loadfile is CPP_V2 Loadfile is CPP_V3 Loadfile is CPP_V1 Loadfile is CPP_V1 Warning Loadfile is CPP_V1 Nonfatal error Loadfile is CPP_V2 Warning Loadfile is CPP_V1 Loadfile is CPP_V2 Nonfatal error Loadfile is CPP_V3 Nonfatal error Nonfatal error Loadfile is CPP_V3 For information about nonfatal errors and warnings, see Nonfatal Errors on page 4-60 and Warnings on page 4-68. C++ programs require access to their run-time environments. To create an executable C++ program, you must link to the run-time environment initialization code and the program s SRLs. The NMC and c89 compilers automatically link to the required items. If you use nld directly to link a C++ program, you must specify these items in nld options. For details, see the C/C++ Programmer s Guide. To create an executable C++ program using nld: 1. Link together the object code files that you compiled. 2. Link to the C++ run-time library initialization object code file: Environment Guardian OSS Run-Time Library Initialization Object Code File $SYSTEM.SYSTEM.CRTLMAIN /usr/lib/crtlmain.o 2-10

nld Utility COBOL Programs 3. Link to the SRLs that your program uses. To link the standard set of C SRLs, use these options: Environment Guardian OSS Option for Linking the Standard Set of C SRLs -OBEY $SYSTEM.SYSTEM.LIBCOBEY -obey /usr/lib/libc.obey C++ programs require additional SRLs. See Determining Which SRLs Programs Require on page 2-16. 4. If your program uses active backup programming functions, such as ns_start_backup(), link to the active backup programming support object code file: Environment Guardian OSS Active Backup Programming Support Object Code File $SYSTEM.SYSTEM.CRTLNS /usr/lib/crtlns.o For information about active backup programming in C++, see the Guardian Programmer s Guide. 5. If you want to overload the new and delete operations, you must link these files to your program: Environment Guardian OSS Active Backup Programming Support Object Code File $SYSTEM.SYSTEM.CPPINIT /usr/lib/cppinit.o COBOL Programs In the OSS environment, the nmcobol compiler automatically calls nld to link the compiled program unless the compiler is run with the -c (compile only) directive. In the Guardian environment, the NMCOBOL compiler automatically calls nld to link the compiled program only if the compiler is run with the RUNNABLE directive. When the NMCOBOL compiler automatically calls nld to link the compiled program, it gives nld: The compiled program s object file name (either the object file name that you specified or the default name a.out) as the input file name The name of the COBOL run-time library, ZCOBSRL The name of the common run-time environment library, ZCRESRL Any files located by the SEARCH directive If you use nld directly to link a COBOL program, you must supply the libraries ZCOBSRL and ZCRESRL. 2-11

nld Utility ptal Programs ptal Programs Because ptal does not support embedded NonStop SQL/MP or a language-specific run-time library, there are no special requirements for linking ptal programs. Mixed-Language Programs You can create mixed-language programs containing native C modules, native C++ modules, native COBOL modules, and ptal modules. The MAIN procedure in a mixed-language program can be written in C/C++ or COBOL but not ptal. Mixedlanguage programs that include C/C++ modules require you to link to the same runtime initialization code and SRLs that C or C++ programs do (see C++ Programs on page 2-9). Mixed-language programs that include COBOL modules require you to link to the same run-time libraries that COBOL programs do (see COBOL Programs on page 2-11). Programs With Embedded NonStop SQL/MP Native C and native COBOL programs can contain embedded HP NonStop SQL/MP statements. Use nld to create a single loadfile from multiple C or COBOL object files that contain embedded SQL/MP statements. After creating a loadfile with nld, use the SQL/MP compiler, SQLCOMP, to set up an executable SQL/MP application. Always run nld before SQLCOMP. Do not run SQLCOMP on a linkfile and use the resulting file as nld input. A user library cannot contain embedded SQL/MP. Linking User Libraries A user library, which is optional, is a set of procedures that the operating system can link to a program file at run time. Putting commonly used procedures in a user library provides these benefits: Reduces the storage required for object code on disk and in main memory Shares a set of common procedures among applications The first time you execute a program file after compilation, duplication, or change to the -libname specification, the operating system searches the user library to resolve each unresolved external reference before searching the system code and library. The operating system resolves an external reference by changing the call in the program file to point to the user library or to the system library. You can then run the program file repeatedly (using the same -libname specification) without resolving the reference again. 2-12

nld Utility Linking User Libraries If the operating system cannot find a user library or system library procedure to satisfy a run-time external reference, it displays a message as the process starts. When the process calls an unresolved procedure, the process changes the call to the unresolved procedure into a call to the Debug utility or the Inspect symbolic debugger, and the process enters the debug state. In the TNS environment, either or both the program file and the user library can be processed by the Accelerator. TNS user libraries can contain embedded SQL/MP statements. In the TNS/R environment, both the program file and the user library must be compiled with TNS/R native compilers. TNS/R native user libraries cannot contain embedded SQL/MP statements. Move procedures with embedded SQL/MP statements to user code before migrating a TNS user library to a TNS/R native user library. (For more information on migrating TNS user libraries to TNS/R native user libraries, see the TNS/R Native Application Migration Guide.) A TNS/R native user library can contain its own data, which is allocated for each process, in a separate location from the client program s data. A TNS/R native user library can call functions in SRLs, such as the C run-time library. If a user library calls functions in an SRL, you must specify the SRLs when linking. Do not link the CRTLMAIN object file to a user library. To create a TNS/R native user library: 1. Compile the procedures that you want to put in the library. If the procedures are written in... Compile them... C or C++ With the SRL pragma and without the RUNNABLE pragma COBOL Without the RUNNABLE directive ptal With the SRL pragma 2. Use nld to link the resulting object files into a single executable user library. Note. You can link only linkfiles into a user library. You cannot link loadfiles, or a combination of loadfiles and linkfiles, into a user library. Use the -o option to specify the name of the resulting object file. Use the -ul option to specify that the resulting object file is a user library. For example, in the Guardian environment, this command links the object files file1 and file2 into an executable user library named lib: nld file1 file2 -o lib -ul This command is the OSS equivalent of the preceding command: nld file1.o file2.o -o lib -ul 2-13

nld Utility Linking SRLs A program file can have at most one TNS/R native user library associated with it. This table shows how to associate a TNS/R native user library with a program file. When Link time* Run time How If you use programs or user libraries that contain C++ code, use the noft option LISTATTRIBUTE or LA (see the noft Manual) to verify that the program and the user library have compatible C++ dialects. (For information about C++ dialects, see C++ Programs on page 2-9.) User libraries specified at run time override those specified at link time. Linking SRLs nld utility -libname library option nld utility -set libname library option nld utility -change libname library options Native c89 utility -Wnld= "nld-options" option Native nmcobol utility -Wnld= "nld-options" option TACL command interpreter RUN command LIB option OSS run command -lib option OSS runv command -lib option OSS run gtacl command -lib option * library must be a Guardian file name. For details, see -libname on page 3-9. An SRL contains code present in virtual memory at run time, to be shared by other processes, rather than being copied into object files. An SRL can also contain global data, and each process using the SRL automatically gets its own run-time copy of the data, called instance data. A process can use several SRLs. Note. nld supports TNS/R native SRLs. It does not support the TNS SRL available to TNS and accelerated programs in the OSS environment. See the Binder Manual for details. Some of the code configured in the system library for TNS processes is packaged in SRLs for native processes. For example: C run-time library NonStop TCP/IP sockets library Tools.h++ class library Much of the OSS API HP supplies public SRLs; you cannot create your own. You can create your own user library. See Linking User Libraries on page 2-12 for details. 2-14

nld Utility Specifying SRLs In the Guardian environment, each processor loads public SRLs at startup time from the active SYSnn subvolume. The SYSnn subvolume, located on $SYSTEM, contains a version of the operating system image for a particular node. A node can have more than one SYSnn subvolume, but only one active (running) SYSnn subvolume. D42 and later product versions of nld automatically select the active SYSnn subvolume. Previous versions of nld required you to specify the active SYSnn subvolume. (To determine the SYSnn subvolume active on a particular node, use the Guardian command STATUS 0,0.) When you use nld to build a program file, nld fixes up references to the SRLs that you have specified. You can also use nld to repeat the fix-up process on an existing program to use a new version of an SRL or let the operating system update the references when you execute the program. The SRLs required to create a program file depend on the run-time resources a program uses. Topics: Specifying SRLs on page 2-15 Determining Which SRLs Programs Require on page 2-16 Specifying SRLs You can specify SRLs on the nld command line directly and with the options -l or -lib on page 3-7. Using options to specify SRLs is a good choice for flexibility and ease of use. A file specified in a -l or -lib option must be an SRL or an archive. In the Guardian environment, an SRL often has a file name that starts with Z and ends with SRL, such as ZCOBSRL. In the OSS environment, an SRL often has a filename that starts with lib and ends with the filename suffix.srl, such as libc.srl. nld uses SRLs to resolve undefined symbols after all object files and archive files specified on the command line have been used. nld uses SRLs in the order specified on the command line and in -l or -lib options. You can specify Guardian subvolumes or OSS directories where nld searches for SRLs with the option -L or -libvol on page 3-8. The -bdynamic and -bstatic flags determine if nld performs dynamic or static linking, respectively. See Dynamic and Static Linking on page 2-27 for details. 2-15

nld Utility Determining Which SRLs Programs Require Determining Which SRLs Programs Require The SRLs that a program requires depend on: The run-time libraries that the program uses The environment in which the program runs The nld options that you must specify to link the SRLs that your program requires depend on: The SRLs that the program requires The environment in which you are using the nld utility Environment in Which You Are Using nld See Guardian Table 2-1 on page 2-16 OSS Table 2-2 on page 2-18 Table 2-1 on page 2-16 and Table 2-2 on page 2-18 apply only to the most common SRLs, which are: C run-time library C++ run-time library COBOL run-time library Tools.h++ library NonStop TCP/IP sockets library Your program might require additional SRLs for other run-time libraries and services. Table 2-1. Using the Guardian nld Utility to Link SRLs (page 1 of 2) Library That Program Uses C run-time library Environment in Which Program Runs Guardian OSS nld Options to Specify -OBEY $SYSTEM.SYSTEM.LIBCOBEY or -l ZCRTLSRL -l ZCRESRL -OBEY $SYSTEM.SYSTEM.LIBCOBEY or -l ZCRTLSRL -l ZCRESRL -l ZOSSKSRL -l ZOSSFSRL -l ZSECSRL -l ZI18NSRL -l ZICNVSRL -l ZOSSESRL -l ZINETSRL -l ZOSSHSRL -l ZSTFNSRL 2-16

nld Utility Determining Which SRLs Programs Require Table 2-1. Using the Guardian nld Utility to Link SRLs (page 2 of 2) Library That Program Uses C++ run-time library VERSION2 Standard C++ library, Tools.h++ library (version 7) VERSION3 Standard C++ library COBOL runtime libraries OSS nlist() function NonStop TCP/IP socket library Environment in Which Program Runs Guardian OSS Guardian OSS Either Either OSS Either nld Options to Specify -l ZCPLSRL -l ZRWSLSRL -OBEY $SYSTEM.SYSTEM.LIBCOBEY or -l ZRWSLSRL -l ZCPLSRL -l ZCRTLSRL -l ZCRESRL -OBEY $SYSTEM.SYSTEM.LIBCOBEY -l ZOSSHSRL -l ZSTFNSRL -l ZCPLSRL -l ZRWSLSRL or -l ZRWSLSRL -l ZCPLSRL -l ZCRTLSRL -l ZCRESRL -l ZOSSKSRL -l ZOSSFSRL -l ZSECSRL -l ZI18NSRL -l ZICNVSRL -l ZOSSESRL -l ZINETSRL -l ZOSSHSRL -l ZSTFNSRL -OBEY $SYSTEM.SYSTEM.LIBCOBEY -l ZTLHSRL -l ZRWSLSRL -l ZCPLSRL or -l ZCRTLSRL -l ZCRESRL -l ZCPLSRL -l ZTLHSRL -l ZRWSLSRL -OBEY $SYSTEM.SYSTEM.LIBCOBEY -l ZOSSHSRL -l ZSTFNSRL -l ZCPLSRL -l ZRWSLSRL -l ZTLHSRL or -l ZOSSHSRL -l ZCRTLSRL -l ZCRESRL -l ZOSSKSRL -l ZOSSFSRL -l ZSECSRL -l ZI18NSRL -l ZICNVSRL -l ZOSSESRL -l ZINETSRL -l ZSTFNSRL -l ZCPLSRL -l ZRWSLSRL -l ZTLHSRL -l ZSTLSRL -OBEY $SYSTEM.SYSTEM.LIBCOBEY -l ZCOBSRL -l ZCRESRL -l ZUTILSRL and other SRLs required by the program environment -l ZINETSRL and other SRLs required by the program environment 2-17

nld Utility Determining Which SRLs Programs Require For example, this nld command links a Guardian C++ program that uses the Tools h++ class libraries: NLD $SYSTEM.SYSTEM.CRTLMAIN MYOBJ -o MYEXEC & -l ZCRESRL -l ZCRTLSRL -l ZCPLGSRL -l ZTLHGSRL -l ZRWSLSRL CRTLMAIN is the C run-time library initialization object file that contains code required by all C and C++ programs. Table 2-2 identifies the OSS nld options required to link the SRLs necessary to create a program file. Table 2-2. Using the OSS nld Utility to Link SRLs (page 1 of 2) Library That Program Uses C run-time library C++ run-time library Environment in Which Program Runs Guardian OSS Guardian OSS nld Options to Specify -obey /usr/lib/libc.obey or -l ZCRTLSRL -l ZCRESRL -obey /usr/lib/libc.obey or -l ZCRTLSRL -l ZCRESRL -l ZOSSKSRL -l ZOSSFSRL -l ZSECSRL -l ZI18NSRL -l ZICNVSRL -l ZOSSESRL -l ZINETSRL -l ZOSSHSRL -l ZSTFNSRL -obey /usr/lib/libc.obey -l ZRWSLSRL -l ZCPLGSRL or -l ZRWSLSRL -l ZCRTLSRL -l ZCRESRL -l ZCPLGSRL -obey /usr/lib/libc.obey -l ZRWSLSRL -l ZCPLSRL -l ZOSSHSRL -l ZSTFNSRL or -l ZRWSLSRL -l ZCPLSRL -l ZCRTLSRL -l ZCRESRL -l ZOSSKSRL -l ZOSSFSRL -l ZSECSRL -l ZI18NSRL -l ZICNVSRL -l ZOSSESRL -l ZINETSRL -l ZOSSHSRL -l ZSTFNSRL 2-18

nld Utility Determining Which SRLs Programs Require Table 2-2. Using the OSS nld Utility to Link SRLs (page 2 of 2) Library That Program Uses VERSION2 Standard C++ library, Tools.h++ library (version 7) VERSION3 Standard C++ library COBOL runtime libraries OSS nlist() function NonStop TCP/IP socket library Environment in Which Program Runs Guardian OSS Either Either OSS Either nld Options to Specify -obey /usr/lib/libc.obey -l ZTLHSRL -l ZRWSLSRL -l ZCPLSRL or -l ZTLHSRL -l ZRWSLSRL -l ZCPLSRL -l ZCRTLSRL -l ZCRESRL -obey /usr/lib/libc.obey -l ZTLHSRL -l ZRWSLSRL -l ZCPLSRL or -l ZTLHSRL -l ZRWSLSRL -l ZCPLSRL -l ZOSSHSRL -l ZCRTLSRL -l ZCRESRL -l ZOSSKSRL -l ZOSSFSRL -l ZSECSRL -l ZI18NSRL -l ZICNVSRL -l ZOSSESRL -l ZINETSRL -l ZSTFNSRL -obey /usr/lib/libc.obey -l ZSTLSRL -l ZCOBSRL -l ZCRESRL -l ZUTILSRL and other SRLs required by the program environment -l ZINETSRL and other SRLs required by the program environment The OSS nld utility processes the simple names in the -l options as files within the Guardian file system. For example, this nld command links an OSS C++ program that uses the Tools h++ class libraries: nld myobj.o /usr/lib/crtlmain.o -o myexec -l ZCRESRL -l ZRWSLSRL -l ZCPLGSRL -l ZTLHGSRL crtlmain is the C run-time library initialization object file that contains code required by all C and C++ programs. The value of the COMP_ROOT environment variable is added to the beginning of the /usr/lib. By default, the value of COMP_ROOT in the OSS environment is null. 2-19

nld Utility Linking Archive Files Linking Archive Files The nld utility supports archive files for selecting input object files when building a new object file. An archive file is created by the ar utility and contains a collection of object files. Any type of file can be put into an archive, but nld uses only the relinkable TNS/R native object files in an archive file. To create an archive file, use the ar utility in either the Guardian environment, the OSS environment, or on platforms running Windows. The nld utility supports archive files existing in the Guardian and OSS environments, regardless of where the archives were created. The ar utility is described in the noft Manual. In the OSS environment, archive files often have filenames that start with lib and end with the filename suffix.a, such as libc.a. You can specify archive files on the nld command line directly and with the options -l or -lib on page 3-7. Specifying archive files with options is usually easier than specifying archive files on the command line. nld resolves references using archive files in the order they are specified, either on the command line directly or with -l or -lib options. nld searches an archive file to resolve references. When nld finds object files that satisfy references, it copies them from the archive file to the target object file. Unlike Binder, nld copies the entire object file, not only the individual procedure. For example, given object files obja, objb, and objc and archive files arc1 and arc2 and this nld command line: nld obja objb -lib arc1 objc arc2 -o myexec nld performs these steps: 1. Copies obja and objb. 2. Searches arc1 for unresolved references in obja and objb. For those references satisfied in arc1, nld copies the object file satisfying the reference. 3. Copies objc. 4. Searches arc2 for unresolved references in obja, objb, and objc. nld also searches arc2 for unresolved references in object files copied from arc1. A duplicate reference in an object file or an archive file generates an error. 2-20

nld Utility Linking Floating-Point Programs Unlike libraries, which must be specified only once in a linking operation, you might need to specify archives more than once in the same linking operation. For example, if the object program obj calls functions fun1 and fun3, and if archive ar1 contains functions fun1 and fun2 in separate archives or object files, and archive ar2 contains function fun3, which calls fun2, the command: nld obj.o -l ar1.a -l ar2.a links obj, ar1, and ar2. nld resolves references to fun1 and fun3, but fun2 is unresolved. The command: nld obj.o -l ar1.a -l ar2.a -l ar1.a links obj, ar1, and ar2 completely, and nld resolves all references. Linking Floating-Point Programs When linking object files using the nld utility, you can specify the floating-point type of the output object file using the option -set on page 3-13 with the attribute-name FLOATTYPE. The floating-point type can be any of: TANDEM_FLOAT IEEE_FLOAT NEUTRAL_FLOAT If you do not specify the floating-point type of the output object file, nld derives it from the types of the input files (see Link-Time Consistency Checking on page 2-22). When modifying an existing object file, nld sets the type as specified by the option -change on page 3-4. Topics: Link-Time Consistency Checking on page 2-22 Run-Time Consistency Checking on page 2-24 Linking Mixed-Language Programs on page 2-25 For more information about using IEEE floating-point format: Topic Building programs using IEEE floating-point format Operating mode routines Routines for converting between Tandem and IEEE floating-point formats Descriptions of the IEEE_FLOAT and TANDEM_FLOAT pragmas See Guardian Programmer s Guide Guardian Procedure Calls Reference Manual C/C++ Programmer s Guide 2-21