JANUARY 1994 VOLUME 6 NUMBER1

INDEX

• ARTICLES
• TECHNICAL INSIGHTS
• NIBBLES AND BITS
• MAD'S COLUMN
• DEVELOPER EDUCATION
• CURRENT PATCHES FOR NOVELL DEVELOPMENT TOOLS
• CONTACTING NOVELL
• ACKNOWLEDGMENTS
• NOVELL OFFICES

ARTICLES:

IPX/SPX for NetBIOS Developers

This article discusses the advantages of using IPX/SPX and provides an introduction to Novell's IPX and SPX protocols for developers who have a working familiarity with NetBIOS.

Why Use IPX/SPX?

You lose no connectivity by switching protocols either, since the emulated NetBIOS layer cannot communicate with hardware NetBIOS systems. In fact, moving to IPX/SPX gives you a net gain in connectivity; NetWare has a 70% share of the network operating system market.

Also, since the NetBIOS emulator adds an additional layer of complexity to packets being sent out, it is more difficult to troubleshoot problems. Emulating NetBIOS involves an extra driver and an extra set of potential incompatibilities. Generally speaking, since IPX and SPX are not dramatically different from NetBIOS, it makes your job easier to work with the protocols that NetWare is designed to support.

Datagram Services

NetBIOS also supports the broadcast datagram, a datagram that is broadcast to the entire internetwork. IPX supports broadcasts, but only to one subnet at a time. Usually, this restriction poses no problem, since mechanisms such as the NetWare Service Advertising Protocol (SAP) overcome this limitation.

The data portion of a NetBIOS datagram is limited in length to 512 bytes, whereas IPX packets allow 546 bytes of data on all networks and can sometimes be substantially larger than that depending on the maximum packet size supported by network routers. Some networks can handle packet sizes of 4096 bytes or more.

Session Services

The primary difference between the two is the supported packet size. NetBIOS sessions support 64K packet sizes (128K with Chain Sends). SPX has the same 546-byte packet size limitation as IPX and, in fact, SPX allows slightly less data in a packet than IPX, since the SPX header requires an additional 12 bytes. SPX therefore supports 534 bytes of data on all networks with the potential for much larger packets if supported by the routers, although attaining a 64K packet size is unlikely.

Probably the most noticeable difference between IPX/SPX and NetBIOS is how each addresses packets. IPX/SPX addresses packets using network, node, and socket numbers. NetBIOS uses unique names to address packets. Each workstation can be uniquely addressed using the network and node numbers.

A workstation can then have as many open sockets as desired for receiving peer-to-peer data packets. Many methods exist for determining a workstation's network, node, and destination socket number, but for simplicity the example code in this article uses SAP to obtain this information.

The Waiting Game

Since most NetBIOS developers use the "no-wait" variants, this difference should not pose a problem, but if you need to use a "wait," you can code it very simply by issuing the command and then looping on the in use field.

Asynchronous Events

The Network Control Block & the Event Control Block

FIGURE 1: The IPX/SPX Event Control Block

void far *linkAddress              Set by IPX
void (far *ESRAddress)()           Equivalent to NetBIOS POST routine
BYTE inUseFlag                     Set when the ECB is in use, zero when   it is available
BYTE completionCode                Equivalent to NetBIOS Command Completion
WORD socketNumber                  Socket number associated with ECB
BYTE IPXWorkspace[4]               Set by IPX
BYTE driverWorkspace[12]           Set by IPX
BYTE immediateAddress[6]           Node address of next "hop"
WORD fragmentCount                 Number of buffer fragments in packet
ECBFragment fragmentDescriptor[2]  Address and size of fragment(s)
END of FIGURE 1

IPX Send Example

FIGURE 2: IPX Send

/* Send "Hello!" to the station at network 0x11111111, node
   0x222222222222, socket 0x3333 using IPX */
void IPXSayHello()
{
   char buffer[] = "Hello!";
   ECB ecb;
   IPXHeader header;
   int transTime;
   header.packetType = 4;
   memset(header.destination.network, 0x11, 4);
   memset(header.destination.node,    0x22, 6);
   memset(header.destination.socket,  0x33, 2);
   ecb.ESRAddress     = NULL;
   ecb.socketNumber   = 0x4444;
   IPXGetLocalTarget(header.destination,
ecb.immediateAddress, &transTime);
   ecb.fragmentCount = 2;
   ecb.fragmentDescriptor[0].address = &header;
   ecb.fragmentDescriptor[0].size    = sizeof(IPXHeader);
   ecb.fragmentDescriptor[1].address = buffer;
   ecb.fragmentDescriptor[1].address = strlen(buffer) + 1;
   IPXSendPacket(&ecb);
}
END of FIGURE 2

FIGURE 3: IPX Header

WORD       checkSum            Included to conform to Xerox IDP standard
                              Set to FFFF by IPX
WORD       length             Length of entire IPX packet including header
                              Set by IPX
BYTE       transportControl   Hop count - Set to zero by IPX
BYTE       packetType         IPX packet type is 4
IPXAddress destination        Address the packet is sent to
IPXAddress source             Address of node sending packet set by IPX
END of FIGURE 3

If these examples used an Event Service Routine (ESR), the ESR address would be filled with the address of a procedure to be run when the send completes, but since NULL is specified, this routine will not be run. The ESR is equivalent to the NetBIOS POST routine. When the IPX send executes, the rest of the fields in the IPX header are filled in automatically, including the source address. You must specify the socket number to be included in the source address, but the socket need not be open to send a packet. For this example, socket number 0x4444 was arbitrarily chosen.

The immediate address field described above must be filled in as well, and the IPXGetLocalTarget() API call fills in this field with the appropriate value. It is passed the final destination of the packet and it calculates the address of the "first hop" on the way to the final destination. Note that if the target workstation is on the same subnet as the sending workstation the immediate address will be the same as the final destination. Otherwise, it will be a bridge or router on the subnet.

Each of the buffers sent in the IPX packet is considered to be a fragment. Since there are two buffers (the IPX header and the data), the fragment count is equal to two. The address and size of the fragments are then entered, starting with the IPX header. As soon as all of the relevant fields are filled, the example calls IPXSendPacket() and passes it the address of the ECB.

Receiving an IPX packet is much like sending one from a programming standpoint, except that you do not need to set the IPX header fields. In the ECB, you should set the ESR address, socket number, immediate address, and fragment descriptors.

Note about socket numbers: the socket number specified for an IPX send does not need to be open, but for an IPX receive the socket must be open. The API call to receive an IPX packet is IPXListenForPacket().

SPX Connection Example

FIGURE 4: Establishing an SPX Connection

/* Start an SPX connection with the station at network
   0x11111111, node 0x222222222222, socket 0x3333, use
   local socket 0x4444 */
#define NUM_BUFFS 5
void call()
{
  ECB send, receive[NUM_BUFFS], connect, term;
  SPXHeader sendHdr, rcvHdr[NUM_BUFFS], connHdr;
  char buffer[NUM_BUFFS][80], sendbuf[] = "Hello!";
  int i, ccode, packetsReceived;
  WORD spxConnectionID;
  for (i = 0; i < NUM_BUFFS; i++) {
      receive[i].ESRAddress = NULL;
      receive[i].socketNumber = 0x4444;
      receive[i].fragmentCount = 2;
      receive[i].fragmentDescriptor[0].address
        = &(rcvHdr[i]);
      receive[i].fragmentDescriptor[0].size
        = sizeof(SPXHeader);
      receive[i].fragmentDescriptor[1].address
        = &(buffer[i]);
      receive[i].fragmentDescriptor[1].size = 80;
      SPXListenForSequencedPacket(receive[i]);
  }
  connect.ESRAddress = NULL;
  connect.socketNumber = 0x4444;
  connect.fragmentCount = 1;
  connect.fragmentDescriptor[0].address = &connHdr;
  connect.fragmentDescriptor[0].size
    = sizeof(SPXHeader);
  memset(connHdr.destination.network, 0x11, 4);
  memset(connHdr.destination.node,    0x22, 6);
  memset(connHdr.destination.socket,  0x33, 2);
  ccode = SPXEstablishConnection(0, 0,
                                 &spxConnectionID,
                                 &connect);
  printf("SPXEstablishConnection return code
         = 0x%x\n", ccode);
  if (ccode != 0)
      return;
  while (connect.inUseFlag != 0)
      IPXRelinquishControl();
  if (connect.completionCode != 0)
      return;
  send.ESRAddress = NULL;
  send.fragmentCount = 2;
  send.fragmentDescriptor[0].address = &sendHdr;
  send.fragmentDescriptor[0].size = sizeof(SPXHeader);
  send.fragmentDescriptor[1].address = sendbuf;
  send.fragmentDescriptor[1].size = 7;
  SPXSendSequencedPacket(spxConnectionID, &send);
  packetsReceived = 0;
  while (packetsReceived < 10) {
      for (i = 0; i < NUM_BUFFS; i++) {
           if (receive[i].inUseFlag != 0) {
               if (receive[i].completionCode != 0) {
                   packetsReceived = 10;
               /* If we get an error, terminate */
                   break;
               }
               printf("Received: %s\n", buffer[i]);
               packetsReceived++;
           }
           SPXListenForSequencedPacket(receive[i]);
      }
      IPXRelinquishControl();
  }
  term.ESRAddress = NULL;
  term.fragmentCount = 1;
  term.fragmentDescriptor[0].address = &connHdr;
  term.fragmentDescriptor[0].size = sizeof(SPXHeader);
  SPXTerminateConnection(spxConnectionID, &term);
  while (term.inUseFlag != 0)
      IPXRelinquishControl();
  for (i = 0; i < NUM_BUFFS; i++)
      IPXCancelEvent(receive[i]);
}
END of FIGURE 4

If the connection is established with the SPX watchdog enabled, the watchdog monitors the connection and notifies the application if the connection fails, even if the application is not currently sending data over the connection. This feature is useful for applications that start SPX connections, but use them infrequently. For simplicity, however, the example does not use the SPX watchdog.

After the listen ECBs have been posted, the connection ECB is then set up in much the same way the IPX send ECB was, except that this ECB has only one fragment: the SPX header. The destination network, node, and socket also are set the same way they were in the previous example.

SPXEstablishConnection() is passed a retry count of zero, indicating that you should use the default value for number of retries. This value is set in the workstation's NET.CFG file using the IPX RETRY COUNT parameter, which defaults to 20. The last zero passed in SPXEstablishConnection() indicates not to use the SPX watchdog. The SPX connection ID is returned as the third parameter. The SPX connection ID can be considered equivalent to the NetBIOS local session number.

Next, the sample code attempts to establish a connection. It polls the ECB's in use flag waiting for the event to complete. The IPXRelinquishControl() call is very important at this stage. If the code did nothing but sit in a tight loop, IPX and SPX would never get the chance to do any processing. IPXRelinquishControl() allows the IPX/SPX layer to get some work done.

Once the in use flag is set to zero, the example checks the return code to see if the attempt to establish a connection was successful. The code does not illustrate how to handle the various failure cases, but the most likely cause of a failure would be that the other side is not yet listening for a connection, just like in NetBIOS. After establishing the connection, packets can be sent to the remote station.

The SPXSendSequencedPacket() call requires much less information than its IPX counterpart. Since the connection is already established, all SPXSendSequencedPacket() needs is the SPX connection ID, an ESR address, and the fragment information.

After sending a packet, the example program waits for ten packets to arrive. When an ECB comes back, the example displays the data and then re-submits the ECB so that it can be used to receive a packet again. After receiving ten packets, it issues an SPXTerminateConnection() call to notify the other side that it is done.

The call to terminate the connection takes almost the same parameters that the establish connection call does, except that there is no need to fill out any information in the SPX header. Once the connection has been terminated, the pending listen ECBs must be cancelled. To do so, the example calls IPXCancelEvent(). Unlike most other ECB-related calls, IPXCancelEvent() does not return until the ECB has been cancelled so there is no need to poll the in use flag.

Event Service Routines

Figure 5 shows a generic ESR that calls a C function after allocating its own stack. This is very important since the amount of free stack space (if any) at interrupt time is unknown, and any attempt by a C function to use the stack could result in memory corruption if the stack is overflowed. The only way to guarantee that this will not occur is to allocate sufficient stack space in the ESR.

FIGURE 5: Example Event Service Routine (ESR)

  .MODEL LARGE
  public       _ReceiveESRHandler
  extrn        _ProcessReceiveData:PROC
  .DATA
; The stack segment and pointer must be saved so that you can set up
; your own stack.
  stk_seg      dw 0                ; variable to store old stack segment
  stk_ptr      dw 0                ; variable to store old stack pointer
  stk_stk      dw 512 dup (0)      ; new stack of 1024 bytes in length
  stk_end      dw 0                ; the end of the stack
  .CODE
; @datasize is TRUE if the model is MEDIUM or LARGE and FALSE if the
; model is SMALL or COMPACT. Just modify the .MODEL ???? above for the
; model you want. ES/SI holds the seg/offset of the currently used ECB
; that ProcessReceivedData needs to process.
_ReceiveESRHandler PROC far
    mov        ax,DGroup
    mov        ds,ax
    mov        stk_seg,ss          ; Save the stack segment
    mov        stk_ptr,sp          ; Save the stack pointer
    mov        ss,ax               ; move the segment of new_stk into ss
    mov        sp,offset stk_end   ; move offset of new_stk to sp
IF  @datasize
    push       es                  ; push es if mem. model medium/large
ENDIF
    push       si
    call       _ProcessReceivedData
    mov        ss,stk_seg          ; Restore old stack segment
    mov        sp,stk_ptr          ; Restore old stack pointer
    retf
_ReceiveESRHandler ENDP
    END END of FIGURE 5

FIGURE 6: Using an Event Service Routine (ESR)

int packetCount = 0;
void ProcessReceivedData(ECB *ecb)
{
    packetCount++;
    printf("%s\n", ecb->fragmentDescriptor[1].address);
    SPXListenForSequencedPacket(ecb);   /* Re-issue the listen */
}
main()
{
    .
    . /* This code is identical to SPX setup code in Fig. 4, except */
    . /* for receive[i].ESRAddress line, which will be as follows: */
        receive[i].ESRAddress = (void (far *) () ) ReceiveESRHandler;
    .
    . /* The send ECB does not normally use an ESR. */
    .
    while (packetCount < 10)
        IPXRelinquishControl();
    .
    . /* Shut down connection, cancel ECBs */
    .
}
END of FIGURE 6

NetWare System Calls & Protected Mode Programming

For the most part, porting NetWare applications to protected mode is simple. The primary challenge in this process is in making the interrupt calls from protected mode to the NetWare Shell or VLM, both of which run in real mode. This article shows how to overcome this obstacle and highlights some of the features of protected mode.

Pros & Cons of Protected Mode

Another useful advantage of protected mode is improved performance. Protected mode applications can take advantage of 80386- and 80486-specific instructions which can perform tasks far faster than their real mode equivalents. Memory fetches also can be done faster and more efficiently under protected mode.

Until recently market share was the big concern for application developers resisting the move to protected mode programming. Many felt that they would lose too much market share by excluding older machines like 8086- and 80286-based computers. However, the baseline machine these days is 80386- based, and the market percentage of machines not capable of running in 80386 protected mode is dwindling.

At this point many developers ask, "With so many protected mode environments like OS/2 and MS Windows around, why should I be interested in writing protected mode applications under DOS?"

There are several reasons for writing protected mode applications under DOS. First of all, if a software development house has been engaged in real mode development, it has a substantial investment in DOS and running under a DOS extender provides the benefits of protected mode without having to learn a new operating system and set of development kits. Also, because of its simplicity DOS can be easier to develop for and in some cases provides higher performance than more advanced operating systems.

DOS Extenders

There are several popular DOS extenders on the market, including DOS/4G from Rational Systems, Phar Lap|386 Extender from Phar Lap, as well as many others.

Making Protected Mode System Calls

• Allocate request and reply buffers
• Fill the necessary parameters in them
• Make the interrupt call

Second, you must also perform some pointer arithmetic. The NetWare Shell and VLM expect far pointers and protected mode applications use a different memory addressing scheme (see Figure 8 below).

Third, making the interrupt call requires a special technique, since a protected mode application must switch to real mode to make the system call. To make the interrupt call, protected mode applications must:

• Make the transition to real mode
• Set up the real mode registers
• Make the interrupt call
• Switch back to protected mode.

Protected Mode Example

Figure 7 displays the code that allocates a buffer in the first megabyte of memory, where DOS drivers can access it. It uses DPMI function 100h to allocate memory; this memory is always allocated at offset zero of a segment.

FIGURE 7: Allocating a Buffer with DPMI

int AllocDOSMemory(unsigned int size, int *segment, int *selector)
{
  union REGS regs;
  /* DPMI call 100h allocates a block of DOS memory.
     Note that no segment offset is returned - all blocks
     allocated begin at offset 0 of the segment. Memory
     is allocated in 16-byte paragraphs. */
  memset(®s, 0, sizeof(union REGS));
  regs.w.ax = 0x0100;
    /* Convert size from bytes to paragraphs. Be sure to add 1
     to the number of needed paragraphs after the bit shift
     so you don't allocate a block that is too small! */
  regs.w.bx = (size >> 4) + 1;
  printf("%u bytes requested. Allocating %d paragraphs (%d bytes)...\n",
     size, regs.w.bx, regs.w.bx * 16);
  int386(0x31, ®s, ®s);
  /* If carry flag is set, there was en error. */
  if (regs.w.cflag & 0x0001) {
     printf("\nAllocDosMemory DPMI call failed.  Return code = 0x%x\n",
        regs.w.ax);
     return(0);
  }
  *segment = regs.w.ax;
  *selector = regs.w.dx;
  return(1);
}
END of FIGURE 7

FIGURE 8: Simulating a Real Mode Interrupt with DPMI

#define DWORD unsigned int   /* = real mode LONG. */
#define WORD  unsigned short /* = real mode INT. */
#define BYTE  unsigned char
static struct rminfo {
  long edi;
  long esi;
  long ebp;
  long reserved_by_system;
  long ebx;
  long edx;
  long ecx;
  long eax;
  short flags;
  short es, ds, fs, gs, ip, cs, sp, ss;
} rmi;
typedef struct {
  WORD  bufLen;
  BYTE  func;
  DWORD objectID;
  WORD  objectType;
  BYTE  nameLength;
  char  objectName[47];
} REQ_BUFF;
typedef struct {
  WORD  bufLen;
  DWORD objectID;
  WORD  objectType;
  char  objectName[48];
  BYTE  objectFlag;
  BYTE  objectSecurity;
  BYTE  objectHasProperties;
} REP_BUFF;
main()
{
  REQ_BUFF far *req_buff;
  REP_BUFF far *rep_buff;
  int req_seg, req_sel, rep_seg, rep_sel;
  char name[80];
  union REGS regs;
  struct SREGS sregs;
  if (!AllocDOSMemory(sizeof(REQ_BUFF),
      &req_seg, &req_sel))
      return(-1);
  if (!AllocDOSMemory(sizeof(REP_BUFF),
      &rep_seg, &rep_sel))
      return(-1);
/* Make 32-bit pointer from real mode request pointer */
  req_buff = MK_FP(req_sel, 0);
/* Make 32-bit pointer from real mode reply pointer */
  rep_buff = MK_FP(rep_sel, 0);
  req_buff->bufLen = sizeof(REQ_BUFF);
  req_buff->func = 0x37;
  req_buff->objectID = 0xffffffff;
  req_buff->objectType = 0xffff;
  printf("Name to search for: ");
  gets(name);
  _fmemcpy(req_buff->objectName, name, 47);
  req_buff->nameLength = min(strlen(name), 47);

  rep_buff->bufLen = sizeof(REP_BUFF);
  memset(®s, 0, sizeof(union REGS));
  memset(&rmi, 0, sizeof(struct rminfo));

  segread(&sregs);
  /* Set up real-mode call structure */
  rmi.eax = 0x0000e300; /* AH = E3 */
  rmi.ds = req_seg;  /* Request buffer pointer DS:SI */
  rmi.esi = 0;       /* (real mode segment:offset) */
  rmi.es = rep_seg;  /* Reply buffer pointer ES:DI */
  rmi.edi = 0;       /* (real mode segment:offset) */
  /* Use DPMI call 300h to issue the DOS interrupt */
  regs.w.ax = 0x0300;
  regs.h.bl = 0x21;
  sregs.es = FP_SEG(&rmi);

  regs.x.edi = FP_OFF(&rmi);

  int386x(0x31, ®s, ®s, &sregs);
  if (rmi.eax & 0x000000ff) { /* Return code in AL */
      printf("Scaseem complex, but it demonstrates the most
challenging situation you will encounter when developing in protected mode under DOS. The
benefits of protected mode fan Bindery Object call failed. Return
             code = %d.\n", rmi.eax & 0x000000ff);
      return(-1);

  }

  printf("Name: %Fs, ", rep_buff->objectName);
  FreeDOSMemory(req_sel);
  FreeDOSMemory(rep_sel);

}
END of FIGURE 8

FIGURE 9: Freeing a Buffer with DPMI

int FreeDOSMemory(int selector)
{

  union REGS regs;

  /* DPMI call 101h frees a previously allocated block of DOS memory */
  memset(®s, 0, sizeof(union REGS));
  regs.w.ax = 0x0101;
  regs.w.dx = selector;
  printf("Freeing selector %d... ", selector);

  int386(0x31, ®s, ®s);

  /* If carry flag is set, there was en error. */
  if (regs.w.cflag & 0x0001) {
      printf("FreeDosMemory DPMI call failed.  Return code = 0x%x\n",
         regs.w.ax);
      return(0);
  }
  printf("Successful.\n");
  return(1);
}
END of FIGURE 9

TECHNICAL INSIGHTS:

NetWare SQL Index Optimization Update (NetWare SQL v3.00e)

WHERE fld1 = 
  AND fld2 = 

In the above example, NetWare SQL would optimize on the index for "fld1," regardless of whether "fld1" or "fld2" is defined first in the table. This new scheme gives users more control over query optimization.

Apply patch level "e" to NetWare SQL v3.00 to obtain this new optimization. Patches are available in Novell's NOVLIB forum on CompuServe (Library 7, SQL30.EXE).

NetWare Client SDK 1.0e Libraries Released (NetWare Client SDK v1.0e)

In addition to CLINEW.TXT, the file that lists the necessary files for the upgrade, You will find a file called CLIPRB.TXT that contains a list of known bugs in v1.0e. Five other .ZIP files in Library 6 supply all you need to bring the NetWare Client SDK up to date. The files are:

• CLIDBC.ZIP - Borland DOS libraries
• CLIDMC.ZIP - Microsoft DOS libraries
• CLIINC.ZIP - header files
• CLIOS2.ZIP - OS/2 DLLs & LIBs
• CLIWIN.ZIP - Windows DLLs & LIBs

• CL3XDB.ZIP, contains the debug symbol version of CLIB.NLM v3.12d. This is the debug version of the QRM for 3.x.
• CL4XDB.ZIP, contains the debug symbol version of CLIB.NLM v4.01b. This is the debug version of the QRM for 4.x.

Thunked Headers for NetWare Client SDK (NetWare Client SDK v1.0d)

Directory Service Update (NLM SDK v3.0)

General Protection Faults in WIN-OS2 (NetWare Client SDK v1.0e)

As a temporary solution, avoid using ESRs in a Windows application to signal IPX/SPX function completion. Otherwise, incorporate the queues so they are not accessed while transport is active.

Missing Memory Managing Prototypes in ADVANCED.H (NLM SDK v3.0)

These methods of manipulating memory are no longer encouraged. Use the standard C language mechanisms, malloc() and free(), instead.

Status 95 & NetWare SFT III (NetWare Btrieve (NLM) v6.10x)

To prevent these status messages, increase the "IPX Retry Count" parameter in NET.CFG to a value of 40 or more. Raising this parameter prevents workstations from timing out and NetWare from terminating their IPX connections. In addition, always use the latest VLM drivers, (see "Current Shell and Requester Versions).

UFileFmtRead() with Format String (AppWare Foundation for Windows v1.70)

nstr        aBuff[500];
:
nNumBytes = UFileFmtRead(pAccess,
                         idInFile,
                         "%s",
                         (pnstr)aBuff);
:

Null Key Path & Status 44 (NetWare Btrieve (NLM) v6.1x)

Status 44 can occur when you define the key attribute to be manual or null ("all-segment" and "any-segment"). If your existing Btrieve application checks for status 82, consider rewriting your Btrieve application to check for status 44, as well.

AppWare Foundation and List Components (AppWare Foundation (all platforms))

In the meantime, there are two ways to remove all items from a list box:

1. Loop with a UMSG_REMOVE List Component message until all items are deleted (see Figure 10, Method 1).
2. Destroy and recreate the List Instance (see Figure 10, Method 2). This method is not recommended due to application side affects, but included here as a possible solution.

Method 1
:
{
    nint32  lCount = UMsgSend( pAccess, idList, UMSG_GET_COUNT, 0, 0 );
    for ( ; lCount > 0; lCount-- )
        UMsgSend( pAccess, idList, UMSG_REMOVE, UMSG_LOC_END, 0 );
}

:

Method 2
:
UInstDestroy(&Access, idList, UINST_DEFERRED);
idList = ListCreate(idWnd);
:
END of FIGURE 10

UDSscanf() & White Space (AppWare Foundation for Windows v1.70)

When UDSscanf() encounters new line characters ("\r\n"), the line feed ('\n') is returned in the output buffer. For example:

:
UDSscanf(pAccess,
         pnstrBuff,
         "%s",
         N_NULL,
         (pnstr)strPath);
:

As a workaround, overwrite the '\n' character with a N_NULL constant. The line feed is in the last character position of the resulting buffer, so the following code sample will work:

nlen = UDStrLen(&Access,
                strPath,
                N_NULL) - 1;
strPath[nlen] = N_NULL;

SPXInitialize() Documentation Error (NetWare Client SDK v1.0d)

The return code of 0x00 is correctly documented, but the documentation for the 0xFF return code is in error. When SPX is not installed, zero is returned. SPXInitialize() returns 0xFF to indicate that SPX is installed, so 0xFF is the value returned if the function succeeds.

Drivers, DLLs & NetWare APIs (NetWare Client SDK v1.0e)

Cannot find NETWARE.DLL

To prevent this error message, install the latest version of NWCALLS.DLL from the NetWare Client SDK v1.0e. If NETX is not loaded before Windows, or if NETWARE.DRV is unavailable for any reason, NWCallsInit() returns a status 0x88FF. This status replaces the message about NETWARE.DLL. Also, if you have replaced the Program Manager with an application that makes NetWare API calls, the new version of NWCALLS.DLL implicitly loads NETWARE.DRV, so no errors are returned.

API Produces Trap D in NWCALLS (NetWare Client SDK v1.0e)

There is no workaround at this time. Novell is investigating the cause.

UFileCreatePath() & the '\' Delimiter (AppWare Foundation for Windows 1.70)

The code segment in Figure 11 appends '\' to the end of the path modifier to resolve this error. (NOTE: this workaround applies only to the Windows platform).

FIGURE 11: Appending '\' character to end of path modifier

nstr              astrPath[100];
:
UDStrCat(pAccess, astrPath, "\\", N_NULL);
idChildDir = UFileCreatePath(pAccess, idDir, astrPath);

:
END of FIGURE 11

Abend: Link Handle Returns Error (NLM SDK v3.0)

Link handle returned an error

New Btrieve Configuration Option (NetWare Btrieve (NLM) v6.10)

The NetWare Btrieve v6.10 Setup Utility (BSETUP.NLM) allows you to set this option if you want all newly created files to have balanced indexes.

However, the Btrieve configuration option of the NetWare SQL Setup Utility (NDBSETUP.NLM) does not include this new option. NetWare SQL should use BSETUP to configure Btrieve rather than NDBSETUP to enable the Index Balancing option.

NetBIOS Abend Error Messages (NetBIOS for DOS v3.14)

• NetBIOS ABEND - IPX block already on free list.
  This message returns when IPX calls the NetBIOS Event Service Routine (ESR) more than once for a single Event Control Block (ECB). This error is fatal due to the contention over the memory resource (the ECB).
• NetBIOS ABEND - Internal stack corruption.
  The amount of stack space used by applications is limited. Usually, this error is caused by an application that is attempting to interface with NetBIOS. The application is not switching stacks when it is called by the NetBIOS POST routine.
• NetBIOS ABEND - FreeIPXBlock already on free list
  This error is caused by a somewhat common problem in LAN drivers that Novell NetBIOS identifies as a fatal "FreeIPXBlock" error message.

A NetBIOS routine called FreeIPXBlock places newly available send ECBs back onto the list of available send ECBs. The routine checks to see if a previously submitted NCB was unable to locate an ECB, and performs consistency checks on the ECB address, including a check to see if the ECB is on the available list.

When IPX cancels a packet in the process of being sent, the ESR for the ECB must not be called, and IPX depends on the LAN driver to not call IPXHoldEvent. Unfortunately, some LAN drivers always call IPXHoldEvent on a transmit complete interrupt when an ECB is at the head of its send queue. If a second ECB is on a send queue when the transmit complete interrupt occurs for a cancelled ECB, the second ECB's ESR is called prematurely, and then called a second time when the second ECB's send had completed.

Set a flag when canceling an ECB that has a transmit complete interrupt pending, and test for the absence of that flag before deciding to call IPXHoldEvent in the transmit complete interrupt service routine.

New CLIB.NLM Posted on NDEVREL (CLIB.NLM for NetWare 3.x and 4.x)

Configuring Btrieve for Windows (Btrieve for Windows v5.10)

Simulating SDF Files with the Report Option (Xtrieve PLUS v4.11)

This format is automatically generated when using the "Translate - to SDF" option. However, an Xtrieve PLUS Report can be designed to simulate SDF format. Doing so allows the user to utilize groups and summaries in the resulting output. However, the report option does not put an end-of-file marker in the resulting output file. As a result, translating in such a file produces the error:

Translate File Not in Recognized Format

To make the report output compatible with the "Translate - from SDF" option, add a report summary constant of "@hex1A" to the report. Doing so places the end-of-file marker after all the data. Also, set the "Switches/Form Feed" option to "No" to avoid the page break characters.

This switch may cause blank lines to be printed to the file at the end of the report to fill out the last page, but the lines will be after the summary constant, and will be ignored by the Xtrieve PLUS "Translate" option.

Login to Print Server API Causes GPF if Called Repeatedly (NetWare Client SDK v1.0d)

Engineering is investigating the cause, but there is no solution at this time.

Error 3 from DosOpen() Named Pipe with NETX.EXE (NetWare Client SDK v1.0e)

ERROR_PATH_NOT_FOUND

When a local drive is used, or the VDM has global network resources, the call will be successful.

There is no solution at time time. Engineering is investing the cause.

Invalid iCount Parameter with xDescribe (NetWare SQL v3.00e)

However, the relational primitive, xDescribe, also has an iCount parameter, and (-1) is a legal value for this primitive, indicating that as many field descriptions as will fit in the data buffer should be returned. With the v3.00e patches applied, if you attempt to call xDescribe with:

iCount = -1

the NetWare SQL requester (NSREQ[S].EXE for DOS and Windows, XQLCALLS.DLL for OS/2) will erroneously return status 354. To avoid the status 354 with xDescribe, use the requesters from the 3.00d patch release.

Invalid Cursor Error & Stored Statements (NetWare SQL v3.00e)

CREATE PROCEDURE testsp AS
START TRANSACTION
UPDATE 
  SET f1 = f1 + 1
SELECT * FROM 
COMMIT WORK

Documentation Error: Status 849 (NetWare SQL v3.00e)

"If the problem persists, contact Novell by phone, fax, or NetWire on CompuServe (as instructed in "Where to Get Help" in "About This Manual") regarding a possible patch to increase the size of the buffer."

This instruction was for the previous version of NetWare SQL, v2.11. No patch is available for v3.00x. If you are receiving this error, contact Novell Developer Support with an example of the statement causing the error.

Using Visual Basic Controls with Btrieve (Btrieve for Windows v5.10)

[Installable ISAMs]
btrieve=c:\windows\system\btrv110.dll

Couldn't find installable ISAM

Apply Patches to NetWare SQL v3.00 (NetWare SQL v3.00e)

Patches are available in Novell's NOVLIB forum on CompuServe (Library 7, SQL30.EXE).

Update in Stored Statements (NetWare SQL v3.00e)

CREATE PROCEDURE test AS
UPDATE  SET f1 = (f1 + 1)
SELECT * FROM 

The problem has been reported and a fix is scheduled for the next patch release of NetWare SQL.

Data Buffer Length & Get Next Extended (NetWare Btrieve (NLM) v6.x)

max(sizeof(in-going structure),
    sizeof(out-going structure))

Set the first two bytes of the descriptor in the Data Buffer to the exact length of the in-going structure. Set the Data Buffer Length parameter to the larger of the in-going structure length and the out-going structure length.

Xtrieve PLUS v4.01a Reports Cannot Be Recalled by v4.11x (Xtrieve PLUS v4.11x)

Before converting to Xtrieve PLUS v4.11 from v4.01a, examine your reports to make sure that all reports follow the "one view to one layout" rule. If a layout is used with multiple views, it should be recalled with each view and then stored individually with a new report name.

NIBBLES AND BITS

Fast Answers to Common Questions

NetWare

Q - How can I get the latest release of the VLM driver?

A - VLM v1.10 is available on Novell's NOVFILES forum on CompuServe (file: DOSUP9.EXE), along with NETX and the latest ODI drivers.

NetWare Client SDK

• You buy the NetWare Client SDK
• You buy an upgrade to the NetWare Client SDK from the NetWare C Interface for (DOS, MS Windows, OS/2, or System Calls for DOS, or
• You already own a copy of the NetWare Client SDK (a free upgrade will be mailed to you).

A - The latest updates for TLI, including new STREAMS, TLI, IPXS and SPXS NLMs, can be found on Novell's NOVLIB forum on CompuServe (Library 1, STRTL2.EXE). Also included is an update to the SPXFIX1.NLM called SPXFIX2.NLM.

NetWare C Interface for Windows

A - Error 240 from IPXInitialize() indicates that IPX is not installed. Under MS Windows, this problem can take two forms. In the first case, no network activity is possible under either DOS or MS Windows. This is usually due to the IPX or IPXODI TSR not being loaded. In the second case, the user can access network functions from DOS, but not in MS Windows. In this case, the problem is with Windows applications not finding VIPX.386 (MS Windows in enhanced mode) or TBMI2.COM was not loaded before starting MS Windows in standard mode.

If you are running MS Windows in enhanced mode, do not load TBMI2.COM. In addition, the network= line in the [386enh] section of the SYSTEM.INI file should include VIPX.386. Finally, VIPX.386 should be present in the MS Windows \SYSTEM subdirectory.

When running MS Windows in standard mode, load TBMI2.COM before starting MS Windows.

NetBIOS for DOS v3.14

A - NetBIOS only opens one socket (455h) and uses this socket for all NetBIOS traffic.

NetWare SQL

     create table test
       (f1 int , f2 char(10))
and attempting to insert a record:
     insert (3,'a'bc')
NetWare SQL returned the error "Unmatched quotes."
A    The following insert statements all work correctly:

     insert into test values
       (1,'O"Leary')
     insert into test values
       (2,'o'hara')
     insert into test values
       (3,'a''bc')
The following records result from these insert statements:
     1,O"Leary
     2,o`hara
     3,a'bc
The following select statement will retrieve the last record:
     select * from test
       where f2 = 'a''bc'
The following select statement will retrieve the first record:
     select * from test
       where f2 = 'O"Leary'

NetWare Btrieve (NLM)

• Index Balanced File
• Duplicate Pointers
• Key Number Specified
• VATs used in File

are set at creation time?

Q - How much real memory is allocated by WBTRCALL.DLL v6.10x to communicate with the Btrieve DOS requester, BREQUEST.EXE?

A - WBTRCALL.DLL is a DOS Protected Mode Interface (DPMI) and allocates real mode memory according to the following formula:

      DOSPARMBLK
    + maxDataLen
    + POSBLK_SIZE
    + KEYBUF_SIZE
    + 2 bytes

• DOSPARMBLK is 28 bytes
• maxDataLen is defined by /d switch specified on the BREQUEST.EXE command line
• POSBLK_SIZE is 128 bytes
• KEYBUF_SIZE is 255

A - NETX is causing the wrong path to be passed to BREQUEST. Use VLMs instead of NETX under the NetWare v4.x operating system.

Q - NetWare Btrieve returns a status 94 (Permission Error) when I try to access the record manager on a NetWare Runtime Server. BREQUEST is loaded with /C:1, SUPERVISOR,SUPERVISOR_PW. What should I do?

A - When accessing Btrieve on a Netware Runtime Server, the user must have a username other than SUPERVISOR. The SUPERVISOR username and password cannot be used on this server to access NetWare Btrieve.

Load BREQUEST with /C:1,USERNAME,PASSWORD

A - You should use BREBUILD in cases where you are converting data files from v5.x format to a v6.x format. Once the files are in v6.x format, they are considered to be "rebuilt." If the file shows signs of data corruption, reload the data into a new file. Steps for reloading data are described in the NetWare Btrieve 6.10c README file.

Q - What does the error "BSPXCOM -Bad Connection ID on send" mean?

A - It means that Btrieve has sent a message to a workstation that has been timed out by the NetWare Watchdog. To rectify the problem, increase the SPX timing parameters on both the server and the workstation. Specifically, increase the SPX WATCHDOG ABORT TIMEOUT, SPX ACK WAIT TIMEOUT, and SPX WATCHDOG VERIFY TIMEOUT parameters on the server where BSPXCOM.NLM is loaded. On the workstation, raise the SPX ABORT TIMEOUT, SPX LISTEN TIMEOUT, and SPX VERIFY TIMEOUT parameters in the NET.CFG file.

Q - How can I direct output to a text file from an NLM (such as BUTIL.NLM) running at the server console?

A - To direct output to a text file from an NLM, enter the command:

     LOAD BUTIL -STAT BTRFILE
      (CLIB_OPT)/>sys:\output.txt

ODI Protocol Stack Developer's Kit

• Connect via FTP to FTP.NOVELL.COM (130.57.11.140)
• Login as user ANONYMOUS, password (your email id... e.g., jdoe@xyz.com)
• Change directory to DEV_DOCS/PSTACKS
• Copy (get) the documentation to a local directory
• Print the documentation (PostScript format)

MAD'S COLUMN

It seems like the January issue of every magazine, periodical or news-letter takes one of two angles: the year in review or next year's forecast. While both serve as a point of reference, I wonder about their necessity.

I know I personally do not care how much Oprah weighs, has weighed or will weigh in 1994. On the other hand, I care very much about the outcome of the Cowboys vs "Unknown Contender" in the 1994 Superbowl game. Predictions on who the contender is or what the point spread will be are non-essential. I guess I like to know the players but determine my own outcome.

I think the world of developers is much the same. There are a lot of good teams out there. Some have better offense. Some better defense. Some a very skilled "special" team. Yet, even in these teams we tend to forget the somewhat overlooked team of sidepeople: coaches, recruiters, physical therapists, equipment managers, travel arrangers. Each with a unique skill at doing their specific job well.

To underrate any one job is to imagine the Dolphins playing Thanksgiving Day in Dallas in typical Floridian clothing. Brrrrr.

For my New Year's column I'd just like to thank you, Novell's developers. I hope that we have been as good a team for you a you have been for us. So, it's a quick glimpse over my right shoulder as I and the rest of the Novell Developer Support group charge into the future.

Mad Poarch
Director
Developer Support/Services

DEVELOPER EDUCATION:

Available Novell Developer Education Courses

904 - Btrieve: An Overview
905 - Programming with Btrieve
907 - Xtrieve PLUS
911 - NetWare Database Administrator
912 - Programming with NetWare SQL
930 - Developing NetWare Loadable Modules (NLMs)
940 - NetWare Programming: Basic Services
945 - NetWare Programming: Protocol Support

CURRENT PATCHES FOR NOVELL DEVELOPMENT TOOLS

When calling, be ready to provide a shipping address, disk preference (5.25", 3.5", HD, or DD) and, if you prefer overnight delivery, your company's Federal Express account number. If you do not provide a Federal Express account number, the patch disk will be sent to you via regular mail.

Novell Professional Developers' Program members can obtain updated NetWare API SDK components from Novell's NOVDEV forum on CompuServe. For more information on Novell developer programs contact Novell at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.

Novell Developer Relations Automated Fax System

To use the AFS, call 1-800-RED-WORD (1-800-733-9673) or 512-794-1796 from a touchtone phone. Then, choose the option for the Automated Fax System, select the documents you wish to receive, and supply your fax number (the fax number to which you want the document(s) sent). Document #7805 describes the patches. Document #1 lists all other documents available through the Automated Fax System. Up to five documents can be requested per call.

CONTACTING NOVELL

Developer Support

Voice

Fax

Developer BBS

E-mail: CompuServe

E-mail: MHS

E-mail: Internet (SMTP)

NetWire on CompuServe

Novell Products and SDKs

DeveloperNet Labs

Novell Developer Relations

Voice

Fax

NetWire on CompuServe

E-mail: MHS or Internet (SMTP)

ACKNOWLEDGMENTS

Contributors: Gaurang Amin, Linda Anderson, Vitek Boruvka, Belinda Brock, Neda Eslami, Kumar Gaddam, Jack Gumaer, Laura Heater, Geert Lingier, Ken Lowrie, Clint McVey, Jeff Nelson, Chris Ojeda, Matt Pinsonneault, Jose Pruneda, Vicki L. Smith, Michael A. Spano, Glenn Stephens, John E. Stewart, Shiva E. Waldecker, Brenda Wallace, and Hans Wieser

Special thanks to the Developer Support, Development, Developer Relations, Product Marketing, and Marketing Communications staff who contributed time and valuable input.

(c) 1993 Novell, Inc. All rights reserved.

Novell, the N design, NetWare, DR DOS, Btrieve, XQL and LANalyzer are registered trademarks; LAN WorkShop, NetWare SFT III, NetWare Loadable Module, NLM, Global MHS, NetWare MHS, NetWare System Calls for DOS, NetWare Runtime, NetWare SQL, NetWare Btrieve, Report Executive, NetWare Asynchronous Services Interface (NASI), NetWare Management System, Xtrieve PLUS, DeveloperNet Labs, UnixWare, AppWare, AppWare Foundation, ALM, Visual AppBuilder, IPX, and MacIPX are trademarks; and NetWire and Professional Developers' Program are service marks of Novell, Inc. IBM and OS/2 are registered trademarks, and NetBIOS and SAA are trademarks of International Business Machines Corporation. Microsoft is a registered trademark and Windows and Visual Basic are trademarks of Microsoft Corporation. Macintosh is a registered trademark of Apple Computer, Inc. CompuServe is a registered trademark of CompuServe Corporation. NFS is a registered trademark of Sun Microsystems, Inc. UNIX is a trademark of UNIX Systems Laboratories, Inc. in the USA and other countries. UNIX Systems Laboratories is a wholly-owned subsidiary of Novell, Inc. WATCOM is a registered trademarks of WATCOM Systems, Inc.

NOVELL OFFICES

Novell, Inc.
Corporate Headquarters
122 East 1700 South
Provo, Utah 84606-6194 USA
Tel +1-801-429-7000
FAX +1-801-429-3944