Remote server support provides an NLM with the ability to access other servers on the network through the functions in the NetWare API. A local server can be defined as the server on which the NLM is loaded. Any other server on the internetwork to which an NLM can attach and log in to is considered a remote server.
Servers are identified by a server ID number.
Do not confuse the server ID with the connection number. The server ID identifies a particular server, whereas the connection number indicates a particular connection on a particular server.
NLM and thread group context play an important role in remote server support. Server IDs are placed at the NLM level of context. At this level, all connections are accessible by any threads running within the NLM. If any thread does a logout, all connections for all threads are cleared.
The current server, which is the server to which all calls are being directed, is maintained at the thread group level. Any thread within a thread group can directly affect the current server of all threads within that group.
To see if an NLM provides remote support, see the "Remote Servers" notation on its function description.
A remote server is accessed by calling LoginToFileServer with a server name attached to the object name (server/object). If the specified server is found, it is assigned the next available server ID and this number is added to a remote session table maintained by the NetWare API. This remote server then has the same server ID for the life of the NLM even if all connections to it are logged out. However, if the NLM terminates and is loaded again, the same server might not have the same server ID.
Server IDs are assigned in the order in which logins are performed to remote servers. If an NLM logs in to server A and then to server B, server A has server ID 1 and server B has server ID 2 for the life of the NLM. If the NLM terminates and is loaded again but first logs in to server B, then server B is assigned server ID 1. The local server (the one that is actually running the NLM) is always assigned server ID 0, even if no login is performed to the local server.
Functions that use a pathname (such as chdir in Multiple and Inter-File Services) and close and open in Single and Intra-File Services) now accept a server name as part of the path (server/volume:path). If no server name is given, the path is assumed to be on the current server.
The current server can be changed by calling SetCurrentFileServerID or chdir (Multiple and Inter-File Services). chdir allows a server name as part of the path. If the specified server is found in the remote session list, the current server ID is set to the specified server.
An NLM can break connections to remote servers by calling any of the following functions:
NWDSLogout--Logs an object out of the network leaving all server attachments and other session connections intact.
Logout--Breaks all connections to all remote servers. This function does not allow an NLM to selectively maintain groups of connections. (Requires bindery context.)
LogoutFromFileServer--Breaks all connections between a server and all logged objects from the NLM. This function allows an NLM to specifically target those connections that it no longer needs. (Requires bindery context.)
LogoutObject--Allows an NLM that logged in multiple times to selectively break a connection between a particular logged-in object and a server. (Requires bindery context.)
Not all functions in the NetWare API work on remote servers.
The function descriptions include paragraphs that indicate whether the function supports only remote server or local server operations, or both.
The paragraphs are labelled Local Server and Remote Server. N/A in this paragraph indicates that the function does not support operation on the indicated type of server.
Additionally, for the type of server operations that the function supports, each function is further identified as nonblocking or blocking.
Nonblocking functions do not cause the caller to lose its thread of execution (do not relinquish control).
Functions that can block might cause the caller to relinquish control.
For example, a function that is blocking on a remote server would read "Remote Server: blocking."
Finally, some functions can be either blocking or nonblocking depending on the circumstances of the call. These functions are identified as "either blocking or nonblocking." When this is the case, a note is included in the Remarks section to explain the circumstances under which the function blocks.