SetNLMID

Changes the current NLM ID

Local Servers:nonblocking
Remote Servers:N/A
Classification:3.x, 4.x, 5.x, 6.x
Service:Thread

Syntax

  #include <nwthread.h>  
   
  int SetNLMID  (  
     int   newNLMID);

Parameters

newNLMID
(IN) Specifies the ID of NLM to make current (returned by a previous call to SetNLMID or GetNLMID.

Return Values

This function returns the ID of the previously current NLM if successful. Otherwise, it returns EFAILURE and sets errno to:

Value

Hex

Name

Description

22

(0x16)

EBADHNDL

Invalid NLM ID was passed in.

Remarks

SetNLMID changes the NLM context for the calling thread and its entire thread group. If a library NLM calls SetNLMID from a client thread, the NLM level context of the thread's entire thread group in the client NLM is changed. For this reason, library NLMs are discouraged from calling SetNLMID.

The current NLM determines which NLM "owns" resources that are subsequently allocated. (See Connection Number and Task Management Concepts (NDK: Connection, Message, and NCP Extensions) for a discussion of resources.)

The main implication of "ownership" of resources is the automatic cleanup performed by the NetWare API when an NLM terminates. In the case of a library/client relationship:

  • If a library allocates resources while being called by a client, by default (without calling SetNLMID), the resources are owned by the client.
  • If the library calls SetNLMID to make itself the current NLM and then allocates resources, the library owns the resources.

NOTE:A library should save and restore the client’s NLM ID when it changes the current NLM ID.

See Also

GetNLMID