Novell Directory Services Q & A
Articles and Tips: article
Developer Support Engineer
Developer Support
01 May 1997
Novell Directory Services Q & A
Q. I have started to write an NLM based on the NDS Cross-Platform APIs available in Novell's NetWare SDK Release 9 and later. I have found that I can't call the runtime Clib functions such as Fopen, etc. successfully. What am I doing wrong?
A. The way connections are handled in the runtime and cross-platform libraries is not compatible. When using the Cross-Platform libraries, you call NWCCOpenConnByAddr, Name, Pref or Ref, you get a connection handle returned to you. With all of the Cross-Platform APIs, you hand them a connection handle. This is the handle they use to send the NCP request on. (This connection handle is not to be confused with runtime Clib's connection ID and connection number.)
In contrast, the Clib runtime APIs such as Fopen don't ask for a connection. Clib has a "state" that stores the pertinent connection ID and connection number via runtime APIs such as SetCurrentConnection. This way Clib knows where to direct a request from a call such as Fopen.
NWCCOpenConByxxx doesn't set Clib's "state." You can't pass the connection handle to the runtime Clib function SetCurrentConnection. They are totally incompatible.
Since the runtime Clib functions require you to call an API such as SetCurrentConnection to populate the "state" information, this "state" information can't be used with the cross-platform APIs. It doesn't recognize it. The cross-platform libraries have the connection handle, which takes care of this.
A new function, NWCCSetCurrentConnection, receives a cross-platform connection handle and sets the connection ID and connection number for Clib.
A couple of common examples follow:
If your NLM application is based on the cross-platform APIs, and you want to call a runtime Clib function, you need to call the new API NWCCSetCurrentConnection, since this function goes out to REQUESTR.NLM and obtains the connection ID and connection number to set the Clib "state" correctly. Since the Clib runtime functions depend on this "state" information, the Clib runtime functions will now work. You will need to call NWCCSetCurrentConnection every time you call a runtime Clib function where you need to change the connection number that the runtime API needs to use.
On the converse, if your NLM is Clib runtime API based and you want to call an cross-platform API, you need to pass in your connection number to the cross-platform API (in place of the connection handle) and make sure that your connection ID is set correctly. The cross-platform API is smart enough to make the conversion from Clib "state" model to the cross-platform connection handle model.
|
Note: The new NWCCSetCurrentConnectionAPI exists in CLXNLM32.NLM,a part of Modular Clib, and available in LIBUPC.EXE.You must load this independently of CLIB and DSAPI. |
Some miscellaneous definitions:
Connection Handle. The handle that a cross-platform API relies on to know what server to direct the request to.
Connection ID. The ID that identifies which server you want your request to go to. Used with the runtime Clib APIs.
Connection Number. The slot on the server, used along with Connection ID to identify the server, to direct the request to the server. Used with the runtime Clib functions.
REQUESTR.NLM. The NLM component of Modular Clib that is responsible for taking the provided request, building a packet and sending it to the server. Typically these requests will be NCPs.
Cross-Platform APIs. A set of NetWare APIs designed to work on multiple platforms such as NLM, WIN32, WIN16 and Unix. On the NLM platform, these APIs are only available in Modular Clib.
Clib Runtime APIs. The original set of NetWare APIs designed to work in the NLM programming environment. These functions comprised the original CLIB.NLM.
Q. My NLM development project is based on the Cross-Platform Library APIs. I am trying to copy a file to a remote server and realize that I must use the NLM Runtime API write. When I do this, even after callingNWCCSetCurrentConnection before the write function, I get an error. What is the problem?
A. File handles are a special case when using the NLM Runtime write function in an NLM that is designed around the Cross-Platform libraries. First of all you need to make sure that call write with the same connection that you called "open" with. If you use the runtime library open API with the runtime library write API, you should be fine just as long as you use the same connection with each. If you have called NWCCSetCurrentConnection, then your Clib "state" will be set up correctly and this will work correctly. If you use NWOpenFile, from the Cross-Platform library, then you will need to convert the file handle returned to one useable by the Runtime library. There are two functions that will do this for you.
NWConvertFileHandle. This Cross-Platform function will convert a Cross-Platform file handle (NWFILE_HANDLE) to a 4-byte or 6-byte NetWare handle suitable for passing in to the Runtime library=s write function. Note that when the converted file handle is obtained, a licensed connection handle is created that should be closed by NWCCCloseConn when no longer in use.
NWConvertHandle. This Cross-Platform function will convert a NetWare file handle to a local file handle. This does the inverse of NWConvertFilehandle, allowing you to convert a file handle suitable for using with the NLM Runtime library functions to that suitable for the Cross-Platform functions.
Q. What is the advantage of using the Cross-Platform API (NWCALLS) libraries over the Runtime API libraries in the NLM programming environment?
A. First a clarification is in order. The Clib runtime APIs are basically the ANSI C functions that are available in libraries that ship with the various compilers. The NetWare specific library call comprise the NLM NIT or NetWare Interface libraries. These libraries are going to be obsoleted by the Cross-Platform libraries.
The following are reasons to consider using the Cross-Platform libraries over the NLM NIT libraries:
One code base for all platforms (currenlty client and server and soon Unix) that Novell needs to maintain.
There is much more functionality in the Cross-Platform libraries compared to the NLM NIT libraries.
New functionality will only be added to the Cross-Platform libraries. This will include new functions and enhancements as well as bug fixes.
The NLM NIT library will only have critical bugs fixed. No enhancements or new functions will be added.
Support will slowly be ended for the NLM NIT libraries as they are obsoleted.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.