16.21 The FUNCTIONS Statement

The FUNCTIONS statement places functions in a specified physical order and assigns functions to segments or overlays. For more information on overlays, see Chapter 15, “Creating Overlaid DOS Programs.”

Syntax

FUNCTIONS[[:{segmentname|overlaynumber}]]
functionname

Remarks

The FUNCTIONS keyword marks the beginning of a section of functions. FUNCTIONS statements can appear more than once in the .DEF file.

FUNCTIONS can be followed by a colon (:) and a destination specifier, which
is either segmentname or overlaynumber.

The segmentname specifies a defined segment in which a function is to be placed. The segmentname does not have to be previously defined in a SEGMENTS statement. LINK assumes the segment definition, using the class CODE; a later SEGMENTS statement can redefine the segment.

The overlaynumber specifies the overlay in which a function is to be placed. Valid overlay numbers are from 0 through 65,535. The number 0 represents the root.

The functionname is the identifier for a “packaged function.” A packaged function is visible to the linker in the form of a COMDAT record. To compile a C function as a packaged function, use the /Gy option on the CL command line (or in PWB, choose Enable Function Level Linking in the Additional Global Options dialog box, which is available from the C or C++ Compiler Options dialog boxes.) Only packaged functions can be specified in a FUNCTIONS statement. You can specify one or more function names, separated by one or more spaces, tabs, or newline characters. If the function is in a C++ module, functionname must be specified as a decorated name. For specific information on decorated names, see Appendix B.

Ordering Functions

You can use FUNCTIONS to specify a list of ordered functions. LINK places ordered functions into a segment in the physical order that you specify before unordered functions in the same segment. You can let LINK choose the segment, or you can specify the segment. If LINK makes the decision, it places ordered functions in segments called COMDAT_SEGn, where n is one of a sequence of numbers beginning with 0. As LINK places ordered functions in these segments, it creates a new segment when the current one reaches 64K-36. You can specify the destination segment in one of two ways:

Specify the segment using “explicit allocation.” In explicit allocation, a function is assigned to a segment at compile time, either in the source code or when compiling. In C source code, you can use the __based keyword (or its predecessor, the alloc_text pragma) to specify the segment where an individual function is to reside. When compiling with the CL compiler, you can use the /NT option to specify the segment where all functions in an object file are to reside. A function not explicitly allocated to a segment is sometimes referred to as an anonymous function.

Specify the segment after the FUNCTIONS keyword. The segment must already have been defined, either in a SEGMENTS statement or at compile time. An explicitly allocated function cannot be placed in a different segment from the one to which it was allocated.

LINK accumulates multiple specifications and treats them as one list of ordered functions. If segments or overlays are specified, LINK accumulates the functions with other functions that have the same destination.

The following statement places three functions in a specified order within the segment called MySeg:

FUNCTIONS:MySeg

Func1

Func2

Func3

Creating Overlays

You can use FUNCTIONS to place a packaged function in an overlay. By default, a function is assigned to the root.

If a function is explicitly allocated (see the previous section), it can be placed in an overlay only if its segment and any other functions in that segment are not also assigned to an overlay. In this case, the FUNCTIONS statement implicitly assigns the entire segment to the specified overlay. An explicitly allocated function cannot be placed in a different overlay from the segment to which it is allocated.

For examples of how to use the FUNCTIONS statement to create overlays, see “The FUNCTIONS and SEGMENTS Statements” in Chapter 15.