6.4 Using MPKXDC

MPKXDC.EXE creates an XDC file referenced by the loader in a NetWare 5.x or 6.x server. As an NLM loads, the XDC file specifies four designations for an NLM and its exported API functions:

(For more information on funneling and exported API functions, see NetWare MPK and Funneling.)

To use MPKXDC, do the following:

  1. If some but not all exported API functions in an NLM are MP safe (can be run on any processor), create an APILIST.API file that lists either the API functions that are MP safe or those that are not MP safe.

    This file contains a list of API functions, one per line without leading or trailing white spaces or trailing commas. Lines beginning with # are ignored as comments. Blank lines or lines with leading white spaces are also ignored.

  2. Prior to compiling, run MPKXDC.EXE using the following syntax:

      MPKXDC [option] [APILIST.API] FILENAME.XDC

    The table following these steps explains available choices for [option].

    FILENAME is your name for the file to which MPKXDC.EXE outputs XDC data for reference by your NLM at load time.

  3. For the WATCOM WLINK linker, include the following line in the linker directive file used in generating an NLM:

      OPTION XDCDATA=<FILENAME.XDC>

The following options can be specified with the MPKXDC tool.

Option

Explanation

-n

Generates XDC data declaring an entire NLM to be MT safe. Threads created for an NLM thus marked do not start in the CNB and can run on any available processor automatically. All routines and exported API functions are also considered MT safe. All new NLMs should be written for this option. This option is not backward compatible with any NetWare version prior to 5.0.

Usage: MPKXDC -n FILENAME.XDC

-f

Generates XDC data declaring only a specified set of API functions in an NLM to be MT unsafe. Thus with this option, only API functions listed are funneled, and all other exported API functions are considered MT safe. This option is not backward compatible with any NetWare version prior to 5.0.

Usage: MPKXDC -f APILIST.API FILENAME.XDC

-u

Generates XDC data declaring the NLM to be MT unsafe in general, although it has the effect of declaring that the NLM will deal with multithreading/multiprocessing issues itself. This option is solely for performance needs and is discouraged because it carries many risks. Although using this option and declaring some of the exported functions to be MT unsafe are not mutually exclusive, such a combination can have serious implications for the following reason:

Even though a given NLM has -u XDC data, a thread executing in that NLM can be outside the CNB. The thread might have entered the NLM through an exported MT safe API function or might have exited the CNB within that NLM. While outside the CNB, if such a thread were to call an MT unsafe function, results would be unpredictable--for performance reasons, the kernel attempts to short circuit the funneling wrapper while resolving the imports of an NLM that has -u XDC data.

In most cases, the -u flag is used to simply indicate that the NLM is legacy and does not contain any MT safe code. With very careful scrutiny, some NLMs may be found to benefit from having some of their exports marked MT safe, if performance considerations demand and sufficient examination reveals that the above listed caveats have been carefully considered.

This option is not compatible with -n or -p.

Usage: MPKXDC -u FILENAME.XDC

-p

Generates XDC data declaring the NLM as being pre-emptible. This means that any thread executing in the code section of the NLM can be pre-empted (assuming the thread has not programmatically entered a critical section). This has to be used carefully--a nonblocking API function in the NLM may become blocking because a thread executing it can be pre-empted.

-h

Displays a help screen for the mpkxdc tool.