MAY 1992 VOLUME 4 NUMBER 5

INDEX

• MAD'S COLUMN
• ARTICLES
• ADDITIONAL READING
• TECHNICAL INSIGHTS
• NIBBLES AND BITS
• NOVELL EDUCATION
• FUN & FACTS
• CONTACTING NOVELL
• ACKNOWLEDGEMENTS

MAD'S COLUMN

I hope that the information provided in "NLMs: From 'Hello World' to World-Class Computing" over the last two months has assisted you in writing your own NLMs and distributed applications.

In talking with a wide variety of folks during the past two months, I have discovered that developers and their managers do not always agree about NLM development. In general, I have found that current NLM developers:

• feel that the present SDK has come a long way in a short time and contains highly useful, stable, well-documented and supported API sets.
• believe that the NetWare v3.11 APIs and tools are good -and that those which will be included in the NetWare v3.2 SDK are "very good" to "screaming" (i.e., "excellent").

• are not aware that Novell has developer APIs available or feel that NLMs are very difficult to understand and write.
• feel that Novell is not committed to its developers and programs.

Happy_Programming!

Mad Poarch
Director
Developer Support/Service

ARTICLES:

NLMs: From "Hello World" to World-Class Computing (Part II)

This month, Part II will explore the three remaining software components of a distributed application: the distributed application protocol (DAP), and the client and server portions of the distributed application. As before, this article will include an in-depth discussion of how these layers are implemented in the DAX example, and how you can customize this example program for use in your own distributed application. Regardless of the server or client operating system platforms, the issues and techniques discussed in this article can be applied to developing any distributed application.

Distributed Application Protocol

Some messages exchanged between the client and server are standard for almost any distributed application, while others are unique to a specific application. Requests for allocating and deallocating sessions with a server application will appear in almost any distributed application. The remaining messages are usually unique to a specific application. Regardless of the message type, each message that the distributed application supports is implemented essentially the same way.

In the same way that the CP protocol layer hides the details of a given communication protocol from the DAP, the DAP conceals the details of the distributed application protocol from the application itself. The client application uses several APIs in the DAP layer to communicate with the server application. This modular design allows you to replace the DAP Layer with minimum difficulty, simplifying the creation of new distributed applications.

The DAX Implementation of DAP

1. Client application calls API in DAP layer
2. DAP API fills in the necessary fields in the DAP request buffer, then passes the data to an API in the CP layer.
3. CP API fills in the necessary fields in the CP request buffer, builds a protocol packet conforming to the underlying communication protocol (in this case, IPX) then calls an API in IPX to transmit the request.
4. On the server side, IPX passes the incoming request to a buffer set aside by the CP NLM.
5. A thread in the CP NLM looks at the data in the CP header, performs a few authentication details, then calls an API in the DAP layer to queue the request. Note that only the DAP related data is given to the DAP API, the CP header is stripped off by the CP layer.
6. A thread in the DAP NLM identifies the request type, calls an API to service the request, then calls another API to queue the reply.
7. The sending thread in the DAP NLM unlinks the reply from the send queue, then passes the data to an API in the CP layer.
8. The CP API fills in the necessary fields in the CP reply buffer, builds a protocol packet, then calls an IPX API to transmit the reply.
9. The client CP layer receives the reply, strips the CP header information, and passes the DAP data to the DAP layer.

Part I of this article discussed the advantages of designing a distributed application with four software layers:

• Communication protocol
• Distributed application protocol
• Client application
• Server application

Most of the requests supported by the DAX example were implemented with a single line of code. Because of this, it was possible to embed the server application within the DAP software layer. This design allows you to customize the application to your specific needs quickly and painlessly.

DAX Source Directories

• DAP - Common source and headers
• DAP/DAPE - Engine code & headers
• DAP/DAPA - Client code & headers
• DAP/DAPA/DOS - MakeFile for DOS client
• DAP/DAPA/NLM - MakeFile for NLM client

The first configuration parameter, DAPMAXDATA, defines the maximum packet size of any single packet within the DAP layer (i.e., the maximum size of a message, be it reply or request) that can be exchanged between the two applications.

The next three constants are specific to the server application. INCDATAAREA identifies whether or not the server application's data structure is defined inside the DAP structure. In DAX, since the server application logic is embedded in the DAP layer, INCDATAAREA is set to TRUE. DEFMAXSESSIONS sets the default maximum number of clients the server application can support. Finally, DAPSTATISTICS defines whether the logic for enabling statistical information will be included in the build. When DAPSTATISTICS is set to TRUE, the DAP spawns a thread of execution that continuously updates various statistical data on the main screen of the server application.

The final three constants are used during the build of the client software. DEFRETRYCOUNT specifies the number of times the DAP layer should resend a request to the server application before giving up. DEFRESPONSEDELAY stipulates how many tenths of a second to wait between each resend of the message. DEFSEQUENCENUMBER is the sequence number assigned to the first packet exchanged between the client and server.

Also included in the DAP directory is the header file, DAP.H. This file contains declarations and constants used by both the client and server portions of the DAP layer. The first items of interest in DAP.H are the protocol packet types supported by the DAX example.

Two of these protocol packet types, DAPALLOCATESESSION and DAPDEALLOCATESESSION, are used by nearly any distributed application. When you customize this example for your own application, these two protocol packet types will probably be the only two you reuse. The remaining seven are specific to DAX.

DAP.H also contains the packet layout structures for the DAP layer. The type declarations are shown below:

..typedef struct {

....UINT32    packetType;

....UINT32    sequence;

....UINT32    sessionID;

....UINT32    timesTried;

....UINT32    requestCode;

....UINT8     data[DAPMAXDATA];

  }DAPRequest;

..typedef struct {

....UINT32    packetType;

....UINT32    sequence;

....UINT32    returnCode;

....UINT8     data[DAPMAXDATA];

....UINT32    dummy[2];

  }DAPReply;

"packetType" tells the DAP layer what type of message is being transmitted. Future versions of DAX supporting broadcasting and bidirectional messaging will use this field to identify what type of message has been received.

"sequence" contains the sequence number of a given request. This value is set by the client when a request is made of the server. The server copies the sequence number from the request packet over to the reply packet. The client (application) uses this value to ensure that the reply received was in response to the request generated.

The "sessionID" is assigned by the DAP layer on the server side when the client performs an "allocate session" request. For the "allocate session" request, this value should be zero.

"timesTried" informs the server side when it has been necessary to resend a request and is used for statistical purposes only.

"requestCode" is the protocol packet number (i.e. DAPALLOCATESESSION).

"data" contains the information necessary for a given protocol packet, and is usually unique for each protocol packet type. Of course, each protocol packet has one format for the "data" on the request, and another for the reply.

"returnCode" is the return code of the protocol request and is only valid if the request is processed by the server.

Finally, the DAP.H header file contains the structure layouts for a structure called DAPDATA, used on both the client and server side to track a given session in the DAP layer. These structures are not transmitted across the network; they are used locally to maintain the session. On the client side, the DAPInitialize API returns a pointer to one of these structures whenever a session is established. All subsequent calls to the DAP layer use this pointer as a parameter. This design allows you to use these APIs in a multithreaded environment, such as the NLM implementation of the client application. The client application does not modify this structure; in fact, it knows nothing about the contents of the structure. Only the APIs in the DAP layer of the client software can "see" the elements of this structure.

Figure 1 shows the layout of the client DAPDATA structure. Items of interest in the client DAPDATA structure include "CPid," the handle returned by the CP layer when a session is established with the server. "CPid" is passed on subsequent calls to the CP layer, much like the DAPDATA structure pointer is passed into the DAP layer. In addition, the DAP layer knows nothing about the "CPid" variable, it just passes it to the APIs in the CP layer. (See Part I of this article for a discussion of this structure). Finally, both a DAPRequest and DAPReply structure are declared within the client's DAPDATA structure.

FIGURE 1: Layout of the Client DAPDATA Structure

typedef struct  {

     void    *CPid;         // data for CP layer

UINT32  sessionID;     // ID between client & server DAP Layer

UINT16  retryCount;    // retry count for session

UINT16  responseDelay; // units to wait for a reply

UINT16  timesTried;    // #times sent duplicate msg

UINT16  sendFailed;    // #times actual send failed

char    serverName[48];

UINT32  nextSequence;  // next sequence # to use

DAPRequest  dapRequest;

DAPReply    dapReply;
}DAPDATA;

End of Figure 1

FIGURE 2: Layout of the Server DAPDATA Structure

typedef struct  _dd{
        struct _dd  *prev;    // pointer to previous link
        struct _dd  *next;    // pointer to next one in link
        UINT32      CPid;     // client ID for CP layer
        UINT32      DAPState;
        UINT32      DAPFlags;
        DAPRequest  dapRequest;
        DAPReply    dapReply;
    #if INCDATAAREA
        struct{
        SINT32      lastResult;
        SINT32      mailBox001;
        }applData;
    #else
        void        *applData;
    #endif
}DAPDATA;

End of Figure 2

Server implementation

FIGURE 3: Server implementation of the DAP layer

 __________              __________         _________
| Service  |  Requests  |          |       | From    |
| Request  |<-----------| Enqueue  |<------| CP      |
| Queue    |            | Request  |       | Layer   |
|__________|            |__________|       |_________|
        |
      __V_________ ____________ _______________
     |            |            |               |
 ____V_____   _____V____   _____V____       ____V_____
|          | | De-      | |          |     |          |
| Allocate | | Allocate | | Request  | *** | Request  |
| Session  | | Session  | |    1     |     |    n     |
|__________| |__________| |__________|     |__________|
     |            |            |               |
     V____________V____________V_______________V
        |
 _______V__              __________         _________
|          |  Replies   | Service  |       | To      |
| Enqueue  |----------->| Reply    |------>| CP      |
| Reply    |            | Queue    |       | Layer   |
|__________|            |__________|       |_________|

End of Figure 3

The Client Application

This article includes a final example of the minimum requirements for a client application. The example program, named ADD, is displayed in Figure 4.

FIGURE 4: Example program ADD

#include 
#include 
#include 
#include 
#include "h/appl.h"
#include "dap/dapapi.h"

#include 

static  DAPDATA *dd;

atexitproc()
{
   if( dd ){
      DAPDeAllocateSession(dd);
      DAPDeInitialize(dd);
   }
}

main(int argc, char *argv[])
{
   int     rc;
   long    x,y,z;

   if( argc == 3 ){
      x = atol(argv[1]);
      y = atol(argv[2]);
   }
   else{
      printf("usage: ADD op1 op2\n");
      exit(1);
   }
   atexit(atexitproc);
   if( (dd = DAPInitialize(SERVERNAME, SERVERTYPE)) == NULL ){
      printf("Could not initialize DAP\n");
      exit(1);
   }
   printf("Initialized okay...\n");
   if( (rc = DAPAllocateSession(dd)) != NULL ){
      printf("Allocate Session failed '%s'",
      DAPTranslateReturnCode(rc));
   }
   printf("Attached to server '%s'\n",SERVERNAME);
   if( (rc = DAPAddOperands(dd,x,y,&z)) != NULL ){
      if( DAP_CRITICAL_ERROR(rc) ){
          printf("\n\n\t%s. rc = %d\n",
                 DAPTranslateReturnCode(rc),rc);
          DAPDisplaySessionData(dd);
          exit(1);
      }
      else{
          printf("\n%s\n", DAPTranslateReturnCode(rc));
      }
   }
   printf("%ld + %ld = %ld\n",x,y,z);
   if( (rc = DAPDeAllocateSession(dd)) != NULL ){
      printf("\n\n\t%s. rc = %d\n",
             DAPTranslateReturnCode(rc),rc);
   }
   DAPDeInitialize(dd);
   dd = NULL;
   return 0;
}

End of Figure 4

• DAPInitialize()
• DAPAllocateSession()
• DAPAddOperands()
• DAPDeAllocateSession()
• DAPDeInitialize()

Using the DAX example program as a prototype or point of departure, you should be able to create your own distributed applications. The NetWare 3.x environment offers a full set of APIs for application programmers: an ANSI-compliant runtime library, an execution thread API, synchronization APIs, POSIX APIs, NetWare APIs, and other platform specific APIs. For more information on the Network C for NLMs software developer's kit, contact Novell's Professional Developers' Program at 1-800-RED-WORD (1-800-733-9673), or 1-512-794-1796.

TECHNICAL INSIGHTS:

Using BROLLFWD with Btrieve for DOS (Btrieve for DOS v5.10)

To log a Btrieve file to another physical drive, make an entry in the BLOG.CFG file in the following format:

 [=]

#ifdef __cplusplus   extern "C" {   endif

#ifdef __cplusplus   }   endif

Bin$=""                            'Initialize the string

  INPUT"Decimal number = ";Decimal 'obtain the decimal number

 FOR i = 14 TO 0 STEP -1           'Positive numbers only
   pow2 = 2^i
   IF Decimal >= pow2 THEN
      Decimal = Decimal - pow2
      Bin$ = Bin$ + "1"
   ELSE
      Bin$ = Bin$ + "0"
   END IF
NEXT i
PRINT"Binary String = ";Bin$

End of Figure 5

1.   With Novell's Network C for NLMs SDK, how do you set the break-point when you get a
message on the console saying "Module did not release [X] resources" and "Resource : Small
Memory Allocations" while unloading your NLM?

A.   'b=malloc-4b+[dmalloc-7]'
B.   'b=malloc-3d+[dmalloc-5]'
C.   'b=malloc-4d+[dmalloc-9]'
2.   With the LAN WorkPlace Toolkit for DOS v4.01, what is the link interface driver which,
instead of interpreting received packets, simply copies identification information from the packet
into a receive ECB and passes the ECB to the link support layer (LSL)?

A.   NLID (Novell Link Interface Driver)
B.   MLID (Multiple Link Interface Driver)
3.   OS/2 workstations can boot from NetWare server using what program?

A.   RIPL (Remote Initial Program Load)
B.   OS2RPL (OS/2 Remote Program Load)
C.   OS2INIT (OS/2 Initialize)
4.   NetWare NFS is implemented as a family of different remote procedure calls. How many
different calls are there?

A.   23
B.   18
C.   15
D.   14
5.   In NetWare C Interface for Windows, what function releases the resources allocated by
NWIPXSPX.DLL?

A.   IPXDeinit()
B.   SPXDeinit()
C.   IPXSPXDeinit()
D.   IPXDeinitialize()
6.   What status code does Btrieve return when you attempt to perform an INVALID
OPERATION?

A.   62
B.   48
C.   27
D.   1
7.   What Btrieve operation is valid in the v5.10 DOS and VAP versions, but not the NLM
version?

A.   Reset (28)
B.   Extend (16)
C.   Insert Extended (40)
8.   What is the pre-defined function key in Xtrieve PLUS to display the Help screen?

A.   F1
B.   F2
C.   F7
D.   F10
9.   In Xtrieve PLUS, what is the maximum length of a user password?

A.   8
B.   12
C.   14
10.  What BROLLFWD command line option is used for automatic recovery of all files on a
volume?
     A.   /v
     B.   /r
     C.   /a

FUN & FACTS ANSWERS
1.   C
2.   B
3.   A
4.   B
5.   C
6.   D
7.   B
8.   A
9.   A
10.  C