Novell Documentation: NLM & NetWare Libraries for C

1.5 NetWare Global Data

Because NLM applications can vary widely in their design and purpose, the NetWare API maintains a variety of global data items for NLM applications. These data items are divided into the following categories described in the sections below:

Thread Global Data
Thread Group Global (CLib) Data
NLM Global Data

These global data items can be set and queried by various functions in the NetWare API. Each category of global data items represents a different level of scope or context.

1.5.1 Thread Global Data

Each thread has its own set of data items. The data items are global only within that thread. That is, they have separate values for each thread. The data items of one thread cannot be referenced by another thread.

A thread is the lowest level within an NLM, and its context can consist of the following data items:

Data Item	Description
asctime, asctime_r char String Pointer	Only allocated if asctime is called. The asctime function returns a char *.
Critical Section Count	Contains the number of outstanding EnterCritSec calls against a thread.
ctime, ctime_r, gmtime, gmtime_r, and localtime, localtime_r functions, tm structure	The ctime, ctime_r, gmtime, gmtime_r, and localtime, localetime_r functions return a pointer to a tm structure. Each thread has its own tm structure. The tm structure is allocated only if one of these three functions is called.
errno	Some functions set the errno return code to the last error code that was detected.
Last Value from the rand Function	Each thread has its own seed value (to start or continue a sequence of random numbers).
NetWareErrno	A NetWare specific error code. Some functions set both NetWareErrno and errno
stack	This points to the block of memory that BeginThread allocated for the thread’s stack.
strtok Pointer	The strtok function maintains a pointer into the string being parsed.
t_errno	Used with Transport Level Interface (TLI) functions. chapter).
Thread Custom Data Area Pointer and Size	The threadCustomDataPtr points to space that the NetWare API allocates to be associated with an individual thread. The threadCustomDataPtrSize variable specifies the size (in bytes) of this data.
Suspend Count	This count contains the number of outstanding SuspendThread calls against a thread.

1.5.2 Thread Group Global Data

One instance of the following data items exists for each thread group. This collection of data effectively makes up what is caled CLib context. Any change that one thread makes to the value of a thread group global data item affects all the threads in the group. All threads within a thread group share the same thread group context, and require this context data to for proper execution. This fact makes it important not to tear down the data structures assoicated with a thread group until all threads in the group have cleaned up the resources individually allocated to them and until thread group resoureces are cleaned up. This issue becomes centrally important at the time an NLM unloads, especially on the ULOAD command. For information and instructions on cleaning up threads and thread groups successfully for an UNLOAD termination, see Terminating an NLM in the Advanced NLM Tasks chapter of NDK: NLM Development Concepts, Tools, and Functions.

Data Item	Description
Current Connection	The current connection number is described in Connection Number and Task Management Concepts (NDK: Connection, Message, and NCP Extensions).
Current Screen	The current screen is the target of screen I/O functions (see Screen Handling).
Current Task	The current task number is described in Connection Number and Task Management Concepts (Connection, Message, and NCP Extensions).
CWD	Current working directory (see File System Concepts in Multiple and Inter-File Services).
Current User	The "current user" is the user context used in NDS™ functions.
signal Settings	Most signal handler functions are set by the signal function. (See signal and raise.)
stdin, stdout, stderr	These data items are the second-level standard I/O handles (see Stream I/O Concepts (Single and Intra-File Services)).
Thread Group Custom Data Area Pointer and Size	The threadGroupCustomDataPtr points to space that the NetWare API allocates to be associated with a thread group. The threadGroupCustomDataPtrSize variable specifies the size (in bytes) of this data.
umask Flags	These flags are set by the umask function (see File System Concepts in Multiple and Inter-File Services).

1.5.3 NLM Global Data

These data items have only one value for the entire NLM. The data items are global to all the thread groups and threads in the NLM. Any changes made to the values of NLM global data items affect all the thread groups and threads in the NLM.

Data Item	Description
active "Advertisers"	Each NLM may have a set of active "advertisers" (started by AdvertiseService (NLM)).
argv Array	This is the argv array passed to main.
atexit, AtUnload	Registers functions that are to be called when the NLM exits normally or is unloaded.
Libraries’ Work Areas Pointers	Pointers to the data areas of any NLM libraries that the NLM has called (see Library Concepts (NDK: Program Management) for more information on library work areas).
locale Settings	Used by the locale functions.
Open Directories	The set of directories (opened by opendir) that the NLM has opened.
Open IPX/SPX Sockets	The set of IPX/SPX™ sockets that the NLM has opened.
Open Files	The set of files the NLM has opened. First-level open files include those opened with open, sopen, creat; second-level files include those opened with fopen, fdopen, freopen.
Open Network Semaphores	The set of network semaphores (opened by OpenSemaphore) the NLM has opened.
Open Screens	The set of screens the NLM has opened.
Original Command Line	A copy of the original command line that was entered when the NLM was started is saved (used by getcmd).
Resource Tag	A tag used whenever the NLM allocates memory.
signal Settings	The SIGTERM constant that triggers a call to the signal handler in NLM termination.
Thread Name	Pattern used for naming new threads (used by BeginThread and BeginThreadGroup).

1.5.4 Hierarchy of Global Data

The different scope levels of the global data items in the NetWare API form a three-tier hierarchy. The thread global data items comprise the bottom level of the hierarchy. At the middle level are the thread group global data items. The top level of the hierarchy includes NLM global data items.

For example, consider the organization of a hypothetical NLM that services requests from multiple clients, as shown in the following figure.

Figure 1-4 Hierarchy of Global Data Items

Bottom Level-Thread Global Data Items: Each of the four threads has its own set of global data items. The global data items in one thread cannot be referenced by any of the other threads.

Middle Level-Thread Group Global Data Items: The global data items for the Control Thread Group are common to two threads: the Console Handler Thread and the Communications Manager Thread. The global items for the worker Thread Group #1 can be referenced only by worker Thread #1. The global items for the worker Thread Group #2 can be referenced only by Worker Thread #2.

Top Level-NLM Global Data Items: The global data items for the Server NLM are common to all the thread groups and threads.

1.5.5 NetWare 4.x-6.x Global Data

The NetWare API for NetWare 4.x, 5.x, and 6.x has added custom data areas to the thread and thread group contexts. These custom data areas can be referenced with the following variables:

Variable	Description
threadCustomDataPtr	A void pointer that points to a data area always associated with the current thread. You can use this area to associate data with a thread.
threadCustomDataSize	The size (in bytes) of the data area pointed to by threadCustomDataPtr. This variable is a LONG.
threadGroupCustomDataPtr	A void pointer that points to a data area always associated with the current thread group. You can use this area to associate data with a thread group.
threadGroupCustomDataSize	The size (in bytes) of the data area pointed to by threadGroupCustomDataPtr. This variable is a LONG.

When a thread is running it can use the custom data associated with its thread and thread group. You can use these data areas to store in memory information associated with a thread or a thread group.

threadCustomDataPtr and threadGroupCustomDataPtr point to areas in memory that the NetWare API has set aside. Before using the data areas these pointers point to, you should check threadCustomDataSize and threadGroupCustomDataSize to see if the available space is sufficient. (These data areas may shrink with future versions of the OS.)

NOTE:You should not change these pointers to point to data that you have allocated. However, you can use the data areas to hold the addresses to data that you have allocated.