DLL Programmer’s Guide for TNS/R Systems Abstract This guide describes how application programmers can use the DLL facilities provided on TNS/R systems and recommends good practices in using them. Product Version T9050 at G06.20 Supported Release Version Updates (RVUs) This publication supports G06.20 and subsequent G-series RVUs until otherwise indicated by its replacement publication.
Document History Part Number Product Version 522203-002 522203-001 T9050 at G06.20 T9050 at G06.
DLL Programmer’s Guide for TNS/R Systems Glossary Index What’s New in This Manual vii Manual Information vii New and Changed Information Figures Tables vii About This Manual ix Purpose of This Manual ix Who Should Read This Manual ix How This Manual Is Organized ix Related Reading ix Your Comments Invited x Notation Conventions xi 1.
2. Essential DLL Facility Controls Contents 2.
3. Dynamic Use of DLLs Contents 3.
5. Advanced DLL Facility Controls (continued) Contents 5.
Tables Contents Figure 4-2. Figure 4-3. Figure 4-4. Figure 4-5. Figure 4-6. Development of the Globalized SearchList for the Program and Libraries based on Figure 1-5 on page 1-12. 4-3 The Loadfiles of Figure 1-5, Now Showing the Use and Availability of the Global Symbol xray. 4-7 Development of the Globalized SearchList for the Program and Libraries in Figure 4-3. 4-9 Localized and Globalized Symbol Resolution 4-10 Intercepting a Call to Library D 4-14 Tables Table 4-1.
Contents DLL Programmer’s Guide for TNS/R Systems—522203-002 vi
What’s New in This Manual Manual Information DLL Programmer’s Guide for TNS/R Systems Abstract This guide describes how application programmers can use the DLL facilities provided on TNS/R systems and recommends good practices in using them. Product Version T9050 at G06.20 Supported Release Version Updates (RVUs) This publication supports G06.20 and subsequent G-series RVUs until otherwise indicated by its replacement publication.
What’s New in This Manual New and Changed Information DLL Programmer’s Guide for TNS/R Systems—522203-002 viii
About This Manual Purpose of This Manual The DLL Programmer’s Guide For TNS/R Systems is intended as an introduction to the process of creating and using Dynamic-Link Libraries (DLLs) on TNS/R S-series systems. Who Should Read This Manual Applications and Systems Programmers who want to create or use DLLs. How This Manual Is Organized This manual consists of the following sections: Section 1, DLLs on a TNS/R System.
Your Comments Invited About This Manual • • • The TACL Reference Manual. This contains infomation on loadfiles in processes and processes using loadfiles. The Guardian Procedure Calls Reference Manual. This contains new information including changes to PROCESS_GETINFOLIST The Guardian Procedure Errors and Messages Manual. This contains new process creation error messages You will also be using a programming language, so choose from the following: • • • COBOL85 For Non-Stop Systems.
Notation Conventions About This Manual Notation Conventions 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 This list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS.
General Syntax Notation About This Manual { } 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 can 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.
Notation for Messages About This Manual 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 / ] LINE [ , attribute-spec ]… !i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data to the called procedure); the !o notation follows an output parameter (one that returns data to the calling program).
Notation for Messages About This Manual The user must press the Return key after typing the input. Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or returned exactly as shown. For example: Backup Up. lowercase italic letters. Lowercase italic letters indicate variable items whose values are displayed or returned. For example: p-register process-name [ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed.
Notation for Management Programming Interfaces About This Manual Notation for Management Programming Interfaces This list summarizes the notation conventions used in the boxed descriptions of programmatic commands, event messages, and error lists in this manual. UPPERCASE LETTERS. Uppercase letters indicate names from definition files. Type these names exactly as shown. For example: ZCOM-TKN-SUBJ-SERV lowercase letters.
Change Bar Notation About This Manual DLL Programmer’s Guide for TNS/R Systems—522203-002 xvi
1 DLLs on a TNS/R System This section explains the TNS/R DLL (dynamic-link library) facility– what DLLs are, how they work, how they can be used, and the basic workings of the tools that create them. This facility comprises the linker (ld), the loader (rld), and the portions of the H-P NonStop™ Kernel (NSK) operating system used in loading libraries.
Libraries and Symbols DLLs on a TNS/R System exported by another loadfile. Thus, in Figure 1-1, Library K exports Joe and, after H is loaded, H imports Joe. In the rest of this document, the term library means a DLL, a TNS/R shared runtime library (SRL), or a public hybrid SRL. The terms DLL, SRL, and hybrid SRL refer to specific types of library, which are discussed later. Figure 1-1.
DLLs on a TNS/R System Position-Independent Code (PIC) and Conventional Code in TNS/R Position-Independent Code (PIC) and Conventional Code in TNS/R Code that can be relocated in virtual memory at load time without alteration is called position-independent code (PIC). If you use DLLs in your application, your program and these DLLs are PIC.
DLLs on a TNS/R System Why Dynamically Linked Libraries? Figure 1-2. An Application Made Up Of a Program And The DLLs It Needs Program DLL A DLL D DLL B DLL C DLL E DLL F DLL G VST012.vsd Why Dynamically Linked Libraries? For statically-linked programs, you must copy all shared libraries into your own programs; thus, complete copies of these libraries appear in all the programs that use them, and each copy consumes main memory and disk space.
DLLs on a TNS/R System • • • • Building and Loading Programs and Libraries The same program can run simultaneously in different processes with different DLLs supplying the supporting data and functions. A new version of a DLL can be introduced without having to alter a program or DLL that references it, even though the location of the referenced sites has changed. This gives you great freedom to change a DLL.
DLLs on a TNS/R System Compilers Figure 1-3. Simplified Code Generation and Load Processes Source Compiler Linkfile Linkfile Linkfile Linker Loadfile Loadfile Loadfile { A program and libraries Loader Executable load image VST013.vsd Compilers The TNS/R compilers translate source input into a linkfile.
DLLs on a TNS/R System Loader to the loader. This process, called linking or executing a link, must be applied to linkfiles after they have been compiled and before they can be loaded for execution. You invoke the linker by a single command, ld, and control it by items you enter in its command stream, which comprises the options, file names, and parameters that modify the ld command.
DLLs on a TNS/R System Finding the Needed libraries The system automatically arranges loadfiles in virtual memory so there is no address overlap and interference. Finding the Needed libraries A loadfile must be loaded with all the libraries that it directly references, that is, the libraries in its libList. However, loading only the directly referenced libraries might not be enough, because some of these libraries might directly reference still other libraries.
DLLs on a TNS/R System • • • The TNS/R Library Facility The program indirectly references D, E, F, and G, so these libraries do not appear in the program’s libList. The program’s loadList comprises all the libraries shown in the figure. A indirectly references G, and A’s loadList comprises D, E, and G. Neither a loadfile nor its programmer needs to know about its indirect needs. There is no limit to the number or depth of directly and indirectly referenced libraries in a loadList.
DLLs on a TNS/R System Linkfiles and Archives In addition to accessing public libraries (hybrid SRLs), PIC programs and DLLs will automatically access the system and millicode libraries, without your specifying this linkage requirement. The system and millicode libraries are non-PIC libraries that the system loads before loading any application code, and the loader and operating system automatically link your application to these libraries as appropriate.
DLLs on a TNS/R System Other Loader Operations multiple loadfiles define and use the same symbol and you want to ensure that they all use the same one. If you declare all these loadfiles to be globalized, then the loader will resolve all these imports to the same exported symbol. However, object files using globalized or semi-globalized import are likely to take somewhat longer to load, because the linker is unable to preset bindings for files not seen at link time.
DLLs on a TNS/R System User Library The starting virtual addresses of the program text (code) and data segments are system constants, set by the linker and enforced by the operating system. The linker also sets "preferred" virtual addresses for the text and data of DLLs, either by default or from command-string input. (DLL data immediately follows the text.
DLLs on a TNS/R System • User Library In OSS, the shell command run has a -lib option that accepts a fully qualified Guardian file name in OSS notation: -lib /G/vol/subvol/name Alternatively, use -lib=unset to disregard any libname attribute in the program file. For PIC programs (unlike TNS and non-PIC native programs), a /lib .../ or -lib=... specification at run time does not change the libname attribute of the program file.
DLLs on a TNS/R System DLL Programmer’s Guide for TNS/R Systems—522203-002 1- 14 User Library
2 Essential DLL Facility Controls You control the TNS/R DLL facility by using the linker and the loader options, many of which normally run using automatic defaults. This section explains the linker’s most commonly used controls, but Advanced DLL Facility Controls on page 5-1 tells you how to get more precise control over the process and its results.
Essential DLL Facility Controls Option Types Parameter – a non-file-name argument of an option The command stream comprises all the tokens that modify an ld command; these are processed in the order they appear in the command stream. These tokens can come from the command line or from command files that are referenced in the command line. In this document, to insert an item means to make it a token in the linker’s command stream either directly or as an option argument.
Essential DLL Facility Controls Choosing the Output File where linkfile1,and linkfile2 are names of linkfiles to be combined in the link. Choosing the Output File The output file is where the linker stores the loadfile that results from a link. To specify an output file name, insert the –o filename option, where filename is the desired name of a file.
Essential DLL Facility Controls • • File-Name Qualification The -dllname nameofdll option, when used by itself, also assigns nameofdll to the file. You can use both the -dllname and -o options with the same name in each. The following example of the first option gives the resulting DLL the name mainout and also stores it in a file named mainout. ld linkfile1 linkfile2 -dll -o mainout -soname is a synonym for -dllname.
Essential DLL Facility Controls At a Glance: Controlling Linker Output When Producing a Loadfile Choosing a DLL Name On the execution target, you must store a DLL in a file having the same name as that DLL, or else the loader will be unable to find it. This is because when a loadfile being linked requires that DLL, the linker uses that DLL’s internal name to enter in this loadfile’s libList.
Essential DLL Facility Controls Linkfile Inputs output loadfile references directly or indirectly. The following subsections describe each of these inputs in detail. Linkfile Inputs The linker’s main purpose is to combine linkfiles to produce a loadfile. You must insert directly in the command stream the name of the linkfiles that are the primary inputs to the link.
Essential DLL Facility Controls Library Inputs In this case, -include_whole remains in effect for the rest of the command stream that follows it. Availability of Linkfiles from Archives Regardless of how the linker finds an archive, that archive is opened and remains open, with its linkfiles available for inclusion in your link, only while the linker processes the token naming that archive.
Essential DLL Facility Controls Specifying Where the Linker Can Find Its Inputs tell the linker which libraries can resolve those symbols, by inserting their file names in the command stream. Using these names, the linker opens the corresponding files and reads their internal names to build the libList in the resulting loadfile. There it lists the libraries in the order that you inserted them; these libraries are called your loadfile’s libListed libraries.
Essential DLL Facility Controls • • Files the Linker Opens Normally If a partially or fully qualified file name is used in a -lib option, the linker does not search; it applies the host-system defualts to a partially-qualified file name , and attempts to open the file. The linker can look for the file among the public libraries. Files the Linker Opens Normally The linker accesses files inserted directly in the command stream by making a single attempt to open it, as described above.
Essential DLL Facility Controls Libraries the Linker Searches For and Opens Where The Linker Searches for Libraries and Archives The following example adds a library, whose unqualified name is libfile1, to the link. ld linkfile1 linkfile2 archfile1 -lib libfile1 -dll -o mainout If libfile1 were a qualified name, the linker would open it normally, just as it did for the two linkfiles and the archive.
Essential DLL Facility Controls Specifying a User Library for a Program The following example causes the linker to look for a library listed in a -lib option first in a private subvolume, pvtsvol, before looking for it in the public libraries. ld linkfile1 linkfile2 -lib dllfile1 & -first_L pvtsvol -dll -o mainout You may find it convenient to use a common search path that can work on different linker platforms.
Essential DLL Facility Controls Your Loadfile’s Exported Symbols one item. When applied to the declaration of a class, it affects all the symbol definitions within that class, including auxiliary compiler-generated definitions such as type identification variables. This facility has several important advantages: • • • • The identifiers can be marked in the source, avoiding the need to place details into the linker's command stream.
Essential DLL Facility Controls Re-exported libraries Controlling Which Symbols Your Loadfile Exports on page 5-5 discusses how to override the automatic exporting of symbols your compiler designates as exportable. Re-exported libraries A DLL can also make available symbols exported by any library in its libList; that is, the given DLL can re-export the other library.
Essential DLL Facility Controls Some Examples Using Re-Exportation or groups. To split a DLL in two, you give one of the new DLLs the name of the original and have it re-export the other. Figure 2-1. DLL A Imports DLL D’s Symbols. Alpha Alpha Beta Beta Gamma Gamma DLL D DLL A VST021.vsd Figure 2-1 above illustrates DLL D exporting symbols Alpha, Beta, and Gamma, while its client, DLL A, imports those symbols.
Essential DLL Facility Controls Some Examples Using Re-Exportation Figure 2-2. Splitting a DLL Into Two Parts Alpha Alpha Beta Beta Gamma Gamma DLL D (new) DLL Y (new) DLL A VST022.vsd Replacing an Existing Symbol Definition In a working DLL you can make a new version of an existing symbol having new function without recompiling that DLL, so that all client loadfiles that use this symbol will invoke the new function without being altered.
Essential DLL Facility Controls Things to Consider about the Loader Because the search order for the linker and loader comes to D before Y (See Finding Symbol Definitions on page 4-1), D’s Gamma masks Y’s. So without any change to the users, all of those that formerly used old D’s Gamma will now get new D’s Gamma. Things to Consider about the Loader Many of the loader’s operations are automatic and driven by adequate defaults. This subsection discusses a few of which you must be aware.
Essential DLL Facility Controls Unresolved Symbols at Load Time The loader quietly ignores invalid path names, so you can mix OSS paths and Guardian subvolumes to create a loader search path that will work on either. As mentioned above, the loader offers the ability to specify paths at load time, but for security reasons, you may wish to ensure that the loader accepts no load-time directives and uses only the paths in 1 through 4 above.
Essential DLL Facility Controls Default Setting and Checking of File Attributes production DLL is to link the program and DLLs to allow load-time search-path specifications, as described in Controlling the Loader’s Search Path at Load Time on page 5-11. Default Setting and Checking of File Attributes The linker sets certain attributes of the loadfile being linked and performs certain consistency checks. This subsection discusses those that you must know about.
Essential DLL Facility Controls C++ Dialect differs from floating-point type set for the program, the linker issues a warning message. When linking a DLL, the linker does not check for floating-point type consistency among loadfiles from which it imports symbol definitions. C++ Dialect Each compiler identifies its language in the generated linkfiles. Three different versions of the C++ language exist on HP NonStop systems; these dialects are called version1, version2 and version3.
Essential DLL Facility Controls Execution-Target System Type (78,6 and 77,8, respectively; see the Guardian Procedure Errors and Messages Manual). Neutralizing the C++ Dialect of a Loadfile The linker can overwrite the cppdialect attribute of an existing PIC loadfile; the command is ld -change cppdialect cppneutral filename This action must be taken with care. Like the corresponding -set option at link time, it causes the presence of any C++ code in this loadfile to be suppressed.
Essential DLL Facility Controls Linker Default Operation 2. The archives that contain linkfiles that resolve symbols your loadfile needs. 3. The libraries that resolve symbols your loadfile needs. Also, you may run a link in a situation where you know certain needed libraries are missing, and you may not want the linker to issue the consequent diagnostics. In that case, insert the -allow_missing_libs option.
Essential DLL Facility Controls DLL Programmer’s Guide for TNS/R Systems—522203-002 2- 22 Linker and Loader Errors
3 Dynamic Use of DLLs An important attribute of the DLL facility is that a running PIC program or DLL can load and open a previously not-loaded DLL and gain access to the symbols it offers. DLLs invoked this way are called dynamically loaded DLLs. One advantage of dynamically loading a DLL is that its name need not be known when the program is constructed; instead, you can add this new DLL to an existing application without even restarting the application.
Dynamic Use of DLLs Opening a DLL from a Running Loadfile (dlopen) dlclose() invalidates a dlopen handle and unloads any dynamically loaded libraries not required by some other handle. dlerror() provides a textual error message that describes any error arising from an immediately preceding call to dlopen(), dlsym(), or dlclose(). dlresultcode()provides an enumerated result code for the last call to dlopen(), dlsym(), or dlclose().
Dynamic Use of DLLs dlopen’s Mode Parameter Values a Localized Loadfile on page 4-5; whereas, the loader binds symbols imported by an added globalized DLL to those offered by the entire new operating load set. To resolve globalized symbols, the added load set’s search list is appended to the end of the old operating load set’s globalized search list, which is described in The SearchList for a Globalized Loadfile on page 4-8.
Dynamic Use of DLLs Returned Value of dlopen 3 - also show files loaded 4 - also show symbol resolution 5 - same as 3, plus file search details 6 - same as 4, plus file search details 7 - same as 4, plus symbol search details 8 - all the above dlopen() treats the mode parameter as the union of the above values and detects an error if any other value is used.
Dynamic Use of DLLs Accessing Symbols (dlsym) When dlopen returns 0, call dlerror() for a textual description of the error, or dlresultcode() for an encoded error code and error-detail. Accessing Symbols (dlsym) Using the handle returned to the calling process by dlopen, that process can access a named symbol if it is exported by the targeted DLL or any library in its loadList.
Dynamic Use of DLLs Closing a Running Loadfile’s Handle to a DLL (dlclose) When dlsym returns 0, call dlerror() for a textual description of the error, or dlresultcode() for an encoded error code and error-detail. In the rare event that dlsym found the symbol and its value was 0, dlerror() and dlresultcode() return 0. Closing a Running Loadfile’s Handle to a DLL (dlclose) To invalidate a handle obtained by a dlopen call, a running process issues the following call.
Dynamic Use of DLLs Error Reporting For Dynamic Library Calls (dlerror and dlresultcode) Error Reporting For Dynamic Library Calls (dlerror and dlresultcode) Error Text : dlerror To obtain information in textual form about any error that occurred in a dynamic library call (dlopen, dlsym, or dlclose), a process can immediately invoke the following function. char *dlerror(void) dlerror has no parameters.
Dynamic Use of DLLs Thread Considerations process creation errors. These error and error-detail codes are described in the Guardian Procedure Errors and Messages Manual and in the PROCESS_LAUNCH_ description in the Guardian Procedure Calls Reference Manual. Certain errors are unique to the dynamic loading functions. These are reported with error code 100; the error-detail is one of the following: 1 - An invalid handle argument was passed to dlsym() or dlclose().
Dynamic Use of DLLs Using Dynamically Loaded DLLs to Extend an Application In either event, the program can load the required DLL if it is not already present. Or it could unload an existing DLL (of that name or for that transaction type) and load another, thus dynamically updating part of the application code. Of course, loading the DLL is only the first step; the application must also find and access the necessary symbols.
Dynamic Use of DLLs Using Dynamically Loaded DLLs to Extend an Application DLL Programmer’s Guide for TNS/R Systems—522203-002 3- 10
4 Finding Symbol Definitions This section describes how the linker and loader resolve symbol references, including cases when multiple definitions are available for the same symbol name. Figure 4-1 below shows the evolution of code from source to linkfile to loadfile to executable PIC load image. At the linkfile and loadfile stages, these code objects can be brought together so they can exchange services and data.
Finding Symbol Definitions The loadList The linker or loader creates the loadList for a loadfile using the following algorithm: 1. [Initialize] To an empty loadList add the name of the designated file, and set a pointer referring to this entry, making it the currently referenced loadfile. 2. If the designated file is the program and it has a user library, add the library name to the loadList. 3.
Finding Symbol Definitions Global Scope, Import and Export Figure 4-2. Development of the Globalized SearchList for the Program and Libraries based on Figure 1-5 on page 1-12. Algorithm step: 1st LoopRun 2nd LoopRun 3rd LoopRun 4th LoopRun 5th (last) LoopRun 4 5 Program Program UL A B UL A B C C Program UL Program UL A B C A B C D Program UL A Program UL A B C D B C D Program Program UL A B C D UL A B C D Program UL Program UL A B C A B C D D VST043.
Finding Symbol Definitions Global Scope, Import and Export loadfiles (programs and libraries). Furthermore, the application of these concepts differs from one source language to another. In C, items declared within a function are local to that function and are undefined (invisible) elsewhere. Items declared outside any function have global scope and are visible in any function that doesn't hide that declaration with a local one of the same name.
Finding Symbol Definitions Import Controls and SearchLists in your loadfile to be exported, and then you can choose which symbols not to export. See Controlling Which Symbols Your Loadfile Exports on page 5-5. Import Controls and SearchLists Just as you have control over the symbol definitions your loadfile offers for export, you can control the sources from which your loadfile can import symbol definitions.
Finding Symbol Definitions The SearchList for a Localized Loadfile 1. [Initialize] To an empty searchList add the name of the localized loadfile being linked and set a reference pointer pointing to this entry, making it the currently referenced loadfile. 2. If the referenced loadfile is a program that has a user library, add the user library’s name to the searchList. 3.
Finding Symbol Definitions The SearchList for a Localized Loadfile Figure 4-3. The Loadfiles of Figure 1-5, Now Showing the Use and Availability of the Global Symbol xray. Exports xray DLL A DLL D Lib D Lib E Lib G Imports xray Code and Data Program libList Lib A Lib B Lib C Lib G DLL B DLL E Lib F Lib G Exports xray User Library (DLL) Lib H DLL C Lib F Lib F Lib H VST042.vsd The final searchList is shown at the bottom of Figure 4-4.
Finding Symbol Definitions The SearchList for a Globalized Loadfile The SearchList for a Globalized Loadfile For a loadfile with globalized import, the linker's searchList is just its loadList; the loader's searchList is the loadList of the program. (For dynamic loads, that is the operating load set, also called the cumulative loadList of the program.
Finding Symbol Definitions The SearchList for a Globalized Loadfile Figure 4-4. Development of the Globalized SearchList for the Program and Libraries in Figure 4-3. Algorithm step: 1st LoopRun 4 5 Program UL Program UL A B C A B C H 2nd LoopRun 3rd LoopRun Program UL Program UL A B C A B C H H D E Program UL A Program UL A B C H B C H D E D E F Program UL A B C H 9th (last) LoopRun D E F G VST044.
Finding Symbol Definitions The SearchList for a Globalized Loadfile below, the programmer of globalized DLL B links it to another globalized library, called F, that exports the symbol definition of john that B should use. Thus, there appears to be no ambiguity, and the resolution of john should be simple. But, because B is globalized, the loader sees it differently. Figure 4-5. Localized and Globalized Symbol Resolution Exports john Lib F DLL B Lib F DLL B as it was linked.
Finding Symbol Definitions The SearchList for a Semi-Globalized Loadfile Perhaps more surprising, if a DLL references its own global symbol definition, one might think that this definition would always be used to satisfy this DLL. However, as we saw earlier in Ambiguity Example 1 on page 4-8, the loader can preempt the linker’s setting and decide to import that symbol. So, if a DLL is globalized, any of its references might be satisfied by a symbol of the same name in some other loadfile.
Finding Symbol Definitions C++ Considerations: Globalized (Gblzd) Symbols of the loadfile itself. That range comprises the loadfile’s LibList, the loadfiles that those loadfiles re-export , and so on. Table 4-1.
Finding Symbol Definitions System Library and Millicode program, the loader looks first in hybrid public SRLs (because the loader cannot rebind references in SRLs). At most one public SRL in the process should define a gblzd symbol; the loader issues a warning if more than one such definition is encountered. System Library and Millicode The TNS/R system and millicode libraries are implicitly attached to the end of every searchList and cannot be mentioned in the command stream.
Finding Symbol Definitions Example: Intercepting an Exported Symbol Figure 4-6. Intercepting a Call to Library D Alpha Alpha Beta Beta Gamma Gamma Gamma DLL A Joe Joe Gamma Library D DLL X DLL Y VST046.vsd The symbol Gamma, provided by the existing Library D, is intercepted for selected calling loadfiles (including DLL A). These selected loadfiles must be relinked to put DLL X in their libLists and remove Library D. Hence, their Gamma references are bound to the definition in DLL X.
5 Advanced DLL Facility Controls This section tells how you can manually override and extend previously described linker and loader defaults and options to meet special needs. These advanced options fall loosely into four categories that compose the major headings in this section: • • • • Linker Input Controls Linker Output Controls Link-Time Operation Load-Time Operation Linker Input Controls Specifying Which Inputs Go into a Link on page 2-5 describes the essential controls over linker inputs.
Advanced DLL Facility Controls Augmenting Library Names Automatically in Searches Also, recall that if the linker is searching for both archives and DLLs, -allow_missing_libs can cause the linker to overlook missing archives as well; see Allowing Missing Libraries on page 2-11. However, if -b static is in effect, then the linker can only be looking for archives, and even if -allow_missing_libs has been inserted, the linker will terminate in error if it doesn’t find the specified archive file.
Advanced DLL Facility Controls Handling Duplicate Symbols among Linkfiles in a Link Data Definitions The linker accepts multiple data-item definitions of the same symbol in input linkfiles when both of the following are true: • • An item is defined in more than one file, and the compiler has marked every instance of this symbol to allow multiple definition (so this will become a gblzd symbol; see , C++ Considerations: Globalized (Gblzd) Symbols, on page 4-12 .
Advanced DLL Facility Controls Making the Linker Look for Unresolved Symbols Making the Linker Look for Unresolved Symbols As part of a link, you can ask the linker to check that the symbol definitions imported by the output loadfile are available through the libraries in its libList. You do this by inserting -unres_symbols parameter, where parameter can have the values error, warn, or ignore.
Advanced DLL Facility Controls Controlling Which Symbols Your Loadfile Exports supplied main program. Therefore, the -e command is rarely needed. (See also , CRTLMAIN and CCPPMAIN Files, on page 6-17) In a program, the procedure having the main attribute is the default entry point for starting the program, and it usually a mistake for you to force a program to start at some other point.
Advanced DLL Facility Controls How to Set Run-Time Attributes of Your Loadfile the following list, which summarizes the values that can be set. The linker places these attribute values in the loadfile being linked, in order to make them available to the system at load time. The purpose and meaning of these attributes may not be described in this document. cppdialect sets the C++ dialect of the output loadfile. The only accepted value is cppneutral.
Advanced DLL Facility Controls Controlling the Load Image of DLLs saveabend possible values are on and off. The default is off. space_guarantee has a numeric value with a default of zero (0). systype sets the system type of the loadfile being linked. Possible values are OSS and Guardian. See Execution-Target System Type on page 2-20. Controlling the Load Image of DLLs Segmenting Loadfiles The linker produces the output loadfile in two segments, text and data.
Advanced DLL Facility Controls Using the Linker to Change an Existing Loadfile Using the Linker to Change an Existing Loadfile The options described in this subsection act on existing loadfiles, rather than a file being linked. In the following options, loadfileName is the name of the target loadfile. Changing the Attributes of an Existing Loadfile To alter any attribute of an existing loadfile, invoke the linker and insert the -change attribute value loadfileName option.
Advanced DLL Facility Controls Running the Linker Through the Compiler These compiler drivers will also run the linker when building a DLL, if you use the SHARED rather than the CALL_SHARED option. For example: nmc /in mylibc/ mylib;suppress,shared,symbols This example compiles a program that uses that DLL: nmc /in myprog2c/ myprog2;suppress,runnable, & call_shared,symbols,search "mylib" The search pragma causes the "mylib" to be included in the linker command stream.
Advanced DLL Facility Controls Naming Intermediate Linker Output Files Naming Intermediate Linker Output Files The linker always creates the output in an intermediate file in a link operation, and the linker gives this intermediate file an internal name. When the operation is complete, the intermediate file contents are renamed to the file name you specified as the output file. See Choosing the Output File on page 2-3.
Advanced DLL Facility Controls Load-Time Operation If -verbose or -warn is in effect, then when a linking operation finishes, the linker puts out a completion message that covers the entire process and indicates how many of each type of message (error, warn, or information) were generated during the linking process.
Advanced DLL Facility Controls Controlling the Loader’s Search Path at Load Time The list of paths is the set of subvolumes specified by the define's attributes in the order SUBVOL0, RELSUBVOL0, SUBVOL1, ..., RELSUBVOL20. Each attribute can specify a single subvolume or a parenthesized, comma-separated list of subvolumes. Any attributes unspecified are ignored. For example the following TACL statements specify search list $A.B:$B.C:$C.D:$D.E: SET CLASS SEARCH, SUBVOL0 $A.B, RELSUBVOL0 $B.C, & SUBVOL1 ($C.
Advanced DLL Facility Controls Changing Run-Time Options for C and C++ Programs It is possible to displace a public SRL by providing a DLL of the same name on the path list ahead of it; the DLL will be loaded and the SRL will not. However, if any other public SRL in this process utilizes the displaced one, the load fails when the loader discovers that one of the libraries named on the libList of that other SRL is a DLL. This is an error; a hybrid public SRL's libList must designate other public SRLs.
Advanced DLL Facility Controls Changing Run-Time Options for C and C++ Programs DLL Programmer’s Guide for TNS/R Systems—522203-002 5- 14
6 Sample Sessions and Usage Notes This section contains two parts: • A set of sample sessions to introduce you to some of the tools and capabilities for building dynamic linked libraries. Sample Session One. Create a non-PIC program that uses a statically-linked library. This is the default situation if you choose not to use PIC and do not need to create or use DLLs. Sample Session Two. Create the same thing, as a PIC program running with a DLL, using the latest tools. Sample Session Three.
Sample Sessions and Usage Notes Sample Session One Sample Session One This sample session shows the use of a main program mainstrc and second program, a library called mystrngc. Both will be compiled using nmc, then loaded using nld. mystrngc will be loaded as an SRL. This will show you the default situation. Display the Source Code Here is the code for the main program, mainstrc #include nolist #include nolist #include
Sample Sessions and Usage Notes Sample Session One char *pBegin; char *pEnd; char c; strcpy(r, s); pBegin = r; pEnd = r + strlen(r); while (--pEnd > pBegin ) { c = *pBegin; *pBegin++ = *pEnd; *pEnd = c; } return (0); } /* StrRev */ Compile the Program and Library The first step is to compile the programs using nmc, the native mode RISC compiler, on NSK to create the two object files, mainstro and mystro. $SYSTEM.SYSTEM.
Sample Sessions and Usage Notes Sample Session One Build the Program The next step is to link the files using nld, the native mode linker, to create an executable file called revstr. $SYSTEM.SYSTEM.NLD mainstro mystro -o revstr -obey $SYSTEM.SYSTEM.libcobey -L $OSS.NSKAPAT1 -set HIGHPIN ON -set HIGHREQUESTOR ON $SYSTEM.SYSTEM.CRTLMAIN NLD - NATIVE MODE LINKER - T6017D45 - 30APR03 (C)1993 Tandem (C)2003 Hewlett-Packard Development Company, L.P. NLD's command line was: \dllqa.$system.system.
Sample Sessions and Usage Notes Sample Session Two Sample Session Two In this session we use the same source code, but compile it as position-independent code (PIC) and create a DLL. Display the Program Code There are no changes to the source code used in Session One. Compile the Program and Library We use the same compiler, nmc, but select a new option, call_shared, which creates position independent code (PIC).
Sample Sessions and Usage Notes Sample Session Two 0 warnings were issued during compilation. 0 errors were detected during compilation. Object file: mystro Compiler statistics phase CPU seconds elapsed time file name NMC \DLLQA.$SYSTEM.SYSTEM.NMC CFE 0.3 00:00:01 \DLLQA.$SYSTEM.SYSTEM.CFE UGEN 0.1 00:00:00 \DLLQA.$SYSTEM.SYSTEM.UGEN AS1 0.0 00:00:00 \DLLQA.$SYSTEM.SYSTEM.AS1 total 0.4 00:00:02 All processes executed in CPU 03 (NSR-G) Swap volume: \DLLQA.
Sample Sessions and Usage Notes Sample Session Two The library specified as 'zcresrl' in a -l or -lib option was resolved to the library named '\DLLQA.$SYSTEM.SYS00.zcresrl'. Comment: lots of other informational messages edited out . . . LD INFORMATIONAL MESSAGE **** [40065]: Creating a DLL without -t option specified. LD will use 0x60000000 as the default value. LD reported 0 errors. LD reported 0 warnings. LD reported 16 informational messages.
Sample Sessions and Usage Notes Sample Session Three Sample Session Three This session demonstrates dynamic loading. We create and compile a program and a DLL, but don’t load the DLL with the program. We invoke the loader from inside the process with a dlopen() call. If you set breakpoints in Visual Inspect just before and after executing such calls, and use the new TACL command LOADEDFILES, you can see the process in action.
Sample Sessions and Usage Notes Sample Session Three result = dlclose(dlopenHandle); dlopenHandle = 0; /* demonstrate the error routines */ dlopenHandle = dlopen("NotThere",RTLD_NOW); if (dlopenHandle == 0) { res.resCode = dlresultcode( ); printf("dlopen of a non-existent dll returns result %i\n" ,res.resCode); printf("\terror( %i,%i)\n" ,res.err[0], res.err[1]); printf( "%s\n", dlerror( ) ); return (1); } return 0; } /* of proc main */ The source code for helloc is as follows: #include
Sample Sessions and Usage Notes Sample Session Three The compile for helloc is as follows: NMC /IN helloc/helloo;suppress, OPTIMIZE 0,SYMBOLS,ERRORS 5,EXTENSIONS,call_shared TNS/R Native Mode Risc C - T9577D46 - 30APR2003 (Mar 23 2003 19:42:26) (C)2000 Compaq (C)2003 Hewlett Packard Development Company, L.P. 0 remarks were issued during compilation. 0 warnings were issued during compilation. 0 errors were detected during compilation.
Sample Sessions and Usage Notes Sample Session Three Next, the main executable file is built. Note that the main program does not use -l to refer to hellodll at link time. ld maino -o mainexe -obey $SYSTEM.SYSTEM.libcobey -L $OSS.NSKAPAT4 $SYSTEM.SYSTEM.CCPPMAIN -l ZRLDSRL LD (T0429G09 - 30APR2003) (C)2003 Hewlett Packard Development Company, L.P. T0429's command line: maino -o mainexe -obey $SYSTEM.SYSTEM.libcobey -L $OSS.NSKAPAT4 $SYSTEM.SYSTEM.
Sample Sessions and Usage Notes Sample Session Three You can use the process name with LOADEDFILES, but can also refer to it by cpu, number which we do in this TACL example. status *,user,pri Process 3,301 Pri PFR %WT Userid 168 000 180,1 Program file $OSS.NSKAPAT4.MAINEXE Hometerm $ZTN10.#PTBSQW8 Comment: This is before the first dlopen(). $OSS NSKAPAT 8> loadedfiles 3,301 PROCESS NAME = UNNAMED PROCESS TYPE FILENAME PPROG \DLLQA.$OSS.NSKAPAT4.MAINEXE SRL \DLLQA.$SYSTEM.SYS00.ZCRESRL SRL \DLLQA.
Sample Sessions and Usage Notes SRL SRL SRL SRL Total No. \DLLQA.$SYSTEM.SYS00.ZCRTLSRL \DLLQA.$SYSTEM.SYS00.ZOSSKSRL \DLLQA.$SYSTEM.SYS00.ZOSSFSRL \DLLQA.$SYSTEM.SYS00.
Sample Sessions and Usage Notes Usage Notes Usage Notes No Support for DLL Tools on UNIX Systems This is a reminder. Developers, such as private SRL providers who build their SRLs on UNIX (for example, SUN) workstations should already be aware that the DLL-enabled compilers and linkers run only under Guardian, OSS and Windows (under ETK) environments. These developers will have to migrate at least some part of their development environment to NSK, PC or OSS.
Sample Sessions and Usage Notes Notes on Debugging Public Libraries PIC programs and DLLs can access hybrid SRLs in HP public libraries. Furthermore, any HP products released as public SRLs will be automatically converted to hybrid SRLs, as part of installing these public libraries at the customer site; and no change to these SRLs is needed. The NonStop Server DLL structure does not allow private hybrid SRLs.
Sample Sessions and Usage Notes Notes on C++ Garth is Not an Application-Level Debugger Garth and Inspect are fundamentally different. Inspect runs on the same system as the application and is used to debug it. Garth is mainly used for debugging dumps. Notes on C++ The following are notes on changes to C++ language support. A primary source of further information is the C/C++ Programmer’s Guide for NonStop Servers (G06.20 version).
Sample Sessions and Usage Notes Guardian Fundamentals For a given version, you can link only to the SRLs listed in the column for that version. If you attempt to link to SRLs that are listed in another column, unexpected results can occur. SQL/MX Restriction For C++ Public SRLs that support SQL/MX have cppdialect = version2. Therefore, SQL/MX clients cannot yet use C++ version3. CRTLMAIN and CCPPMAIN Files The CRTLMAIN file, located in $SYSTEM.
Sample Sessions and Usage Notes Guardian Fundamentals This is no regression for DLLs on TNS/R because there has never been dynamic loading before. The position is consistent with others taken in the past, most notably the incompatibility of C and C++ heap operations with passive checkpoint. There is no way to cause the passive backup to capture heap allocations and deallocations, whether explicit via malloc() or new, or implicit in any number of functions.
A Linker Options List The following table lists all the options available to control the linker from the linker command stream. The meaning and interpretation of the columns is as follows: Option: The name of the option to be inserted in the linker’s command stream. Argument: The item that must be given as part of the option. Also, toggle options, which have no arguments, are indicated here. A pathname is the resolved path name to access the designated directory or subvol.
Linker Options List Option Argument -export symbolname Default Reference 5-4 -export_all 2-10, 5-4 -export_not symbolname 5-5 -first_L pathname 2-9 -obey -FL -include_whole toggle -no_include_whole 2-5 -L (upper case) -libvol -l (lower case) -lib -lib 2-8 simplefilename or filename -libname filename -set libname -libvol pathname 2-9 -limit_runtime_paths 2-14 -m -map -map 5-8 -nostdfiles 5-10 -nostdlib 2-9 -noverbose -no_verbose -no_include_whole toggle -no_incl
Linker Options List Option Argument -ul Default Reference see text 5-4 -unres_symbols 5-3 -verbose -verbose in Guardian.
Linker Options List DLL Programmer’s Guide for TNS/R Systems—522203-002 A- 4
Glossary code file: A file comprising instructions that can be executed or emulated by a computer. Native code files can be either linkable (linkfiles) or loadable (loadfiles). Object files and binaries are other names for code files. client (of a loadable library): A loadfile that uses functions or data from a library. default: The choice made when the user does not direct otherwise. direct reference (of a loadfile): A library listed in a loadfile’s libList.
Glossary indirect reference (of a loadfile): A library in a loadfile’s searchList that is not named in its libList. instance: A particular case of a class of items, objects, or events. For example, a process is defined as one instance of the execution of a program; multiple processes might be executing the same program simultaneously. Also, instance data refers to global data of a program or library; each process has a its own instance of these data.
Glossary loadList: A list of all the libraries that must be loaded for a given loadfile to execute. A loadfile's loadList includes all the libraries in the given loadfile's libList plus all the libraries in those loadfiles' libLists, and so forth; it does not include the implicit (system and millicode) libraries. The loadList order is the sequence in which these loadfiles are to be loaded when they are not already loaded by a previous operation.
Glossary appended to every searchList. A loadfile's searchList is unaffected by the import control of any other loadfile. semi-globalized: An import control characteristic of a loadfile that allows the loadfile first to obtain symbols from its own definitions and then to obtain others as for a globalized loadfile. Thus, a semi-globalized loadfile cannot have its symbol references to itself preempted. See also searchList. symbol: The symbolic name of a function or data item.
Index A added load set 3-2 ambiguity example 4-8, 4-9 warning 4-11 ambiguous symbols 4-5 archive 1-10, 2-6 repeated insertion 2-6 argument, of a command-stream option 2-1 attributes, see loadfile attributes augmenting file names 2-4, 2-9, 5-2 augmenting library names 5-2 auxiliary linkfile 1-10 auxiliary system 1-7, 2-1 B bind symbols 1-1 C C and C++ I/O Files 5-13 C library, dlfcn.
Index E E entry point 5-4 error, dlclose returned values 3-6 error, dlopen mode parameter 3-4 returned values 3-4 unresolved symbols 3-3 error, dlsym returned values 3-5 error, dynamic library call analysis data 3-7 error, linker avoiding errors 2-20 consequence of an error 2-21 during -change processin 5-8 error codes 5-10 library type 5-2 library unavailable 5-4 main in a DLL 5-5 missing archive with allow_missing_libs in effect 5-2 missing searched-for file 2-11 mixed floating-point types 2-18 multiple
Index I I implicit libraries 4-13 import Glossary-1 import control 1-10, Glossary-1 default 1-10 import symbol 1-2 include
Index M loadfile attributes changing 5-8 setting 5-6 loading sequence for libraries, see loadList loadList 1-8, Glossary-3 localized Glossary-3 loadfile, see loadfile M MAIN attribute 5-4 main entry point 5-4 in a DLL 5-5 mainstack_max 5-7 mangled symbol names 5-5 memory arrangement of DLLs 1-8 message-control options 5-11 millicode 4-13, Glossary-2 millicode library 1-10, Glossary-3 missing DLLs 5-2 missing libraries 2-11 multiple main procedures in a loadfile.
Index P -o 2-3 -obey 2-2 -reexport 2-13 -rld_first_L 2-16 -rld_L 2-16 -set 5-6 -shared, see Option -dll -show_multiple_defs 5-11 -soname, see Option, -dllname -stdin 2-2 -t 5-7 -temp_o 5-10 -u 2-7 -ul 5-5 -unres_symbol 5-4 -verbose 5-10, 5-11 -warn 5-10 -y 5-11 option definition 2-1 list of, see Appendix A see linker OSS 2-10 output file, naming 2-3 overriding MAIN 5-4 Q P S parameter of a linker option 2-2 pfsize 5-6 PIC 1-3, Glossary-3 position-indipendent code, see PIC preempt 4-8, Glossary-3 proce
Index T segmenting loadfiles 5-7 segments in a loadfile 5-7 semi-globalized Glossary-4 semi-globalized loadfile, see loadfile semi-globalized searchList 4-11 sequence 4-5 severity code 5-10, 5-11 severity codes 5-10 space_guarantee 5-7 splitting a DLL 2-13 SRL 1-9 hybrid 1-9 standard C/C++ I/O files, see C/C++ I/O files symbol 1-1, 1-7, 4-13, Glossary-4 accessing in dynamic-loaded DLLs 3-5 bind 1-1 definition 1-1, Glossary-4 duplicated in linkfiles 5-2 resolve 1-1 value 1-1, Glossary-4 symbolic reference
