DECEMBER 1993 VOLUME 5 NUMBER 11

INDEX

• ARTICLES
• DEVELOPER NEWS
• TECHNICAL INSIGHTS
• NIBBLES AND BITS
• DEVELOPER EDUCATION
• CURRENT PATCHES FOR NOVELL DEVELOPMENT TOOLS
• CONTACTING NOVELL
• ACKNOWLEDGMENTS

ARTICLES:

Porting Local Communication Apps to NetWare Connect

NetWare Connect is a communications solution that allows for incoming and outgoing support. The server NLM provides access to an attached modem pool. From the network, a client can take advantage of this modem pool by loading the NASI TSR, which communicates with the server NLM via SPX, and using a communications package designed to communicate with the TSR.

Without this type of solution, individuals needing access to a modem would be required to have a modem on their desk. This means additional modems and additional phone lines. With NetWare Connect, individuals that need access to a modem need only load the NASI TSR, query for an available modem and attach, all from their workstation.

Many popular communications packages have been developed, not only as standalone, single-workstation applications, but as packages that could run with NACS. Because of NetWare Connect's backward compatibility, these as well as many others packages support remote communications with NetWare Connect.

As with many Novell products, developers can take advantage of NetWare Connect by developing their own communications package. The NetWare Asynchronous Services Interface (NASI) SDK v3.0 provides APIs that communicate with a modem pool on the network via the NASI TSR program. You can easily convert an application that accesses local COM ports to NASI. This article takes a look at a local communications application named MYCOMM (excerpted in Figure 2) and converts it to a NASI application called NWCOMM (excerpted in Figure 3).

FIGURE 2: MYCOMM.C, Example of standalone COM services

struct {
       BYTE baud;
       BYTE wordLength;
       BYTE stopBits;
       BYTE parity;
       } comConfig;
void main (void)
{
     char c, bye=0;
     unsigned int  keyPressed;
// Open com port.
     AcquireCom (&comHandle, comConfig);
// Begin communications with modem.
     while (1 && !bye)
     {
// Loop until a key is pressed. In the loop, check
// for incoming data. If data is available, read it
// and print it to screen.
       while (!bioskey (1))
       {
         if (RxData (comHandle))
       {
         c = ReadComCh (comHandle);
         cprintf ("%c", c);
       }
         CheckCom (comHandle);
       }
// Get the key & determine if it begins alt sequence.
       keyPressed = bioskey (0);
       if (AltKeyPressed (keyPressed))
       {
         switch (keyPressed)
         {
// hang up command
         case H:
           ComWriteStr (comHandle, "+++");
           delay(5000);
           ComPutStr (comHandle, "ATH0\r\n");
           break;
// initialize modem
         case I:
           ComWriteStr (comHandle, "ATZ\r\n");
           break;
// exit application
         case X:
           ReleaseCom (comHandle);
           bye=1;
           break;
         default:
           continue;
         } // end switch
       } // end if (AltKeyPressed)
// If key pressed is not alt sequence, write it out.
       else
       {
       ComWriteCh (comHandle, (char)key);
       CheckCom (comHandle);
       } // end else
     } // end while (1)
} // main
END of FIGURE 2

#include 
#include <stdio.h>
#include <stdlib.h>
#include <ctype.h>
#include <conio.h>
#include <string.h>

#include <bios.h>

#include "cintnasi.h" // NASI header file

NASI_CONFIG portConfig;

WORD vC;  BYTE port;
void main (void) {
     WORD keyPressed, c, bytesSent, bytesReturned, bye=0;
     BYTE *inBuffer=0, rxStatus=0;
// Acquire virtual connection, open port, & initialize
     Init ();
   while (1 && !bye) { // Begin modem communications
// Loop until key is pressed. Check for incoming data.
// If data available, read it and print it to screen.
     while (!bioskey (1)) {
       rxStatus = 0;
       bytesReturned = 1;
       NasiGetRxStatus (vC, &rxStatus);

 if (rxStatus) {

   NasiRead (vC, &bytesReturned, inBuffer);

   if (bytesReturned) cprintf ("%c", *inBuffer);

 } // if (rxStatus)
     } // end while (!bioskey (1))
     keyPressed = bioskey (0);
// Get key pressed & determine if it begins alt key seq.
     if (!(keyPressed & 0x00FF)) {
     switch (keyPressed) {
        case H:                  // hang up modem
             SendData ("+++");
             delay(5000);
             SendData ("ATH0\r\n");
             break;
        case I:                  // modem reset command
             SendData ("ATZ\r\n");
             break;
        case X:                  // close session
                   NasiDisconnect (vC);
             bye = 1;
             break;
        default:
                    continue;
     } // end switch
     } // end if (AltKeyPressed)
     else
     {
// If just a normal key press, write it.
       SendCh ((char)keyPressed);
     } // end else
   } // end while (1)
} // main end
void Init (void) {
     int  rCode=1;

     WORD c;
     portConfig.bufferLen = 12;
     portConfig.port = CURRENT_NACS_PORT;
     portConfig.receiveBaudRate = BAUD_9600;
     portConfig.receiveCharLen = LEN_7;
     portConfig.receiveStopBits = STOP_1;
     portConfig.receiveParity = EVEN;
     portConfig.transmitBaudRate = BAUD_9600;
     portConfig.transmitCharLen = LEN_7;
     portConfig.transmitStopBits = STOP_1;
     portConfig.transmitParity = EVEN;
     portConfig.DTRControl = ON;
     portConfig.RTSControl = ON;
     portConfig.flowControl = NONE;
// Look for a 9600 baud modem.
     NasiOpen (&vC, "D9600???", &portConfig);
// Initialize internal receive buffer.
     NasiFlushRxBuffer (vC);
// Initialize internal transmit buffer.
     NasiFlushTxBuffer (vC);
} // Init end
void SendData (BYTE *inBuffer)
{
     BYTE stringSent[80], c, xNASI, xNACS;
     WORD bytesSent, waitTime=0;

     strcpy (stringSent, inBuffer);
     bytesSent = strlen (stringSent);
     NasiWrite (vC, &bytesSent, stringSent);
     waitTime = 0;
// Used to break out of WHILE in case we get "stuck"
     do {
        c = NasiGetTxStatus (vC, &xNASI, &xNACS);
     } while (c==0 && ((xNACS !=PORT_READY_TO_XMIT) &&
                      (xNASI !=XMITTER_NOT_BUSY)) &&
                      waitTime++<TIME_OUT);
} // SendData end
void SendCh (BYTE outBuffer)
{
     BYTE c, xNASI, xNACS;
     WORD bytesSent, waitTime=0;
     bytesSent = 1;
     NasiWrite (vC, &bytesSent, &outBuffer);
     waitTime = 0;
     do {
        c = NasiGetTxStatus (vC, &xNASI, &xNACS);
     } while (c==0 && ((xNACS !=PORT_READY_TO_XMIT) &&
                      (xNASI !=XMITTER_NOT_BUSY)) &&
                      waitTime++<TIME_OUT);

} // SendCh end
END of FIGURE 3

Initialization:

MYCOMM

NWCOMM

• Acquire a virtual circuit
• Acquire a desired port
• Configure the port.

Since you are choosing from a remote modem pool, you must specify which modem, or port, you want. The specification can be as general or as specific as desired. The value of serviceName is the General Port Name or Specific Port Name. Any field can contain the wildcard character "?". NWCOMM attempts to establish a connection with a 9600 baud modem.

In a WAN environment, NetWare Connect services in other cities may be found in this search. Specificying a partial name in this instance will assure that you do not connect with a modem in a different city or farther away than your local services.

The Specific Port Name may be indicitive of some other desirable attribute in the modem connection. In this case, the Specific Port Name specifies a particular modem on a particular port, though that fact is not important to this discussion.

The example simply wants to find a 9600 baud modem in AUSTIN. The Austin services are in the form: AUS-CONN for the Service Name, D9600 for the General Port Name, and AUSNWCONN1 through AUSNWCONN8 for the Specific Port Name. NasiConfig contains information just like comConfig in MYCOMM.

Port Write:

MYCOMM

NWCOMM

Error Checking:

MYCOMM

NWCOMM

Port Read:

MYCOMM

NWCOMM

Closure:

MYCOMM

NWCOMM

Availability

The source code for the NASI application discussed in this article, NWCOMM, is available on Novell's Developer Forum, NOVDEV (NDEVSUPP forum, Library 1, NWCOM1.EXE).

For more information on porting existing standalone communications applications to the NetWare environment, call Novell Developer Support at 1-800-NETWARE. To obtain a copy of the NASI SDK v3.0 or NetWare Connect v1.1, contact Novell at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.

SIDEBAR:

NetWare Connect v1.1 and NASI Compatibility

All of the previous NASI APIs have been retained and will work with NetWare Connect. In addition, the NASI API set is being expanded to include functions that address the new options. These include:

• Enhanced modem control
• Support for modem-independent ports
• Increased support for dial-in groups
• Optional security

In addition, NetWare Connect can be configured with default configurations for each modem. If NASI does not request a specific initialization mode, the appropriate default configuration is used.

With NetWare Connect, it is not necessary to acquire a modem to receive a call on it. Ports can remain available for dial- out use while applications monitor their status for incoming calls. NetWare Connect will answer the call and initialize the modem automatically. When the application detects an incoming call, it can acquire the modem and proceed with the live connection ready to go.

Finally, security has been enhanced by allowing the application to establish the NASI session information used to maintain the link with NetWare Connect. Normally NetWare Connect prompts users for a user ID, password, and session ID. This process can be bypassed to allow the application itself to determine the user's identity.

These new features integrate tightly with the existing NASI API set. Only a half-dozen functions have been added to implement the additional capabilities associated with NetWare Connect.

Configuring an MS Windows Workstation for Btrieve

This article explores each of the possible configurations for running DOS- and MS Windows-based Btrieve applications on an MS Windows workstation.

There are two types of Btrieve workstation programs that can be configured either separately or in combination on an MS Windows workstation:

• Local (client-only)
• Requester (client/server)

The Local Implementation of Btrieve

The MS Windows implementation of local Btrieve is a DLL called WBTRCALL.DLL and is used by MS Windows applications. This client DLL has a size of approximately 51K. Initialization parameters for the local WBTRCALL.DLL are specified in the WIN.INI file in the [btrieve] paragraph.

The Requester Implementation of Btrieve

• BREQUEST.EXE (the DOS requester)
• WBTRCALL.DLL (approximate DLL size is 13K)
• WBTRVRES.DLL (resource-only DLL)

Because both the local and the requester Windows DLLs are named WBTRCALL.DLL, changing between the two configurations is invisible to the Btrieve Windows application running on the workstation. With no changes to the application and without having to recompile, you can change the environment from local to client/server and vice versa.

TSR vs. DLL

Six Different Configurations

The following sections detail each of these configurations.

1. DOS applications in an MS Windows DOS session using local BTRIEVE.EXE OR the requester, BREQUEST.EXE

   When running DOS Btrieve applications in an MS Windows DOS session that use either BTRIEVE.EXE or BREQUEST.EXE, the desired TSR should be loaded in each DOS session. Do not load either TSR before starting MS Windows.

   Running in this environment, if you exit a DOS session that has BREQUEST.EXE loaded, the workstation hangs. This problem is caused by the VIPX.386 driver that shipped with MS Windows v3.1. To correct this problem, a new VIPX.386 driver can be obtained from Novell via CompuServe in the MS Windows Client Update Kit. Currently, this kit is available in the NOVFILES forum in the file, WINUP8.EXE.

   If using BTRIEVE.EXE and the Btrieve data files reside on a local drive rather than a network drive, install SHARE.EXE before starting MS Windows if:

   1. More than one application will be accessing the data files simultaneously
   2. A single application will be accessing a data file with more than one position block simultaneously.
   In either case, if SHARE.EXE is not installed before starting MS Windows, data file corruption may result.
2. MS Windows applications using local WBTRCALL.DLL

   If you are running an MS Windows application and want to use the client Btrieve engine, place the 51K client WBTRCALL.DLL in a directory accessible by MS Windows. MS Windows searches for DLLs in the following order:

   • The current directory
   • The \WINDOWS directory
   • The MS Windows system directory
   • The directories in the PATH environment variable
   • Network search drives
   As with the DOS client version of Btrieve, you should install SHARE.EXE in the same cases when using local WBTRCALL.DLL for the same reason.
3. MS Windows applications using the requester WBTRCALL.DLL

   The Btrieve requester for MS Windows consists of a DOS portion and Windows portion. To configure the workstation to use the Btrieve Windows requester:

   1. Load BREQUEST.EXE before starting MS Windows.
   2. Place the 13K requester DLL, WBTRCALL.DLL in a directory accessible by MS Windows, along with WBTRVRES.DLL.
   WBTRVRES.DLL is a resource-only DLL that is used by the requester WBTRCALL.DLL, not by your application. Btrieve will return a status 1017 to your application if WBTRVRES.DLL is not available to MS Windows when using the requester DLL.
4. MS Windows applications using requester & local DLLs

   You can configure the workstation to use both the local DLL and the requester DLL. In this environment, you access local data files (files that reside on a drive physically located at your workstation) through the local DLL. Data files residing remotely on a NetWare server drive are accessed through the requester DLL. To configure the workstation for both local and requester access:

   1. Load BREQUEST.EXE before starting MS Windows.
   2. Place the 13K requester DLL, WBTRCALL.DLL, and resource DLL, WBTRVRES.DLL, in a directory accessible by MS Windows.
   3. Run the MS Windows utility, WNDBCNVT.EXE, against the local 51K WBTRCALL.DLL.

      WNDBCNVT.EXE renames the local WBTRCALL.DLL to "WBTRLOCL.DLL" and changes the DLL name internally to "WBTRLOCL." Do not rename the local DLL manually. If WNDBCNVT is not used to rename the DLL, the internal name conversion is not performed and the configuration will not operate properly.

   4. Place WBTRLOCL.DLL from step 3 in a directory that is accessible by MS Windows.
   5. In the NOVDB.INI file in the Windows directory, add the line:
      local=yes
      to the [brequestDPMI] paragraph.
5. MS Windows apps using the requester while running DOS applications with the DOS requester, BREQUEST.EXE

   When using the MS Windows Btrieve requester DLL, BREQUEST.EXE is loaded before going into MS Windows. When DOS applications that will be accessing the requester are run in MS Windows DOS sessions, BREQUEST.EXE must be loaded in the DOS session. This situation creates a conflict when both run simultaneously; when BREQUEST.EXE tries to load in the DOS session, the message "Brequest already loaded" is generated.

   To resolve this situation, BREQUEST.EXE v6.0 and later have implemented a new load parameter, "/L." "BREQUEST /L" makes it possible to load BREQUEST.EXE again in an MS Windows DOS session even though it was already loaded before starting MS Windows. This command loads another instance of Brequest that is only available to the DOS session. Thus, the DOS session has its own copy.

   To configure the workstation for this operating environment, BREQUEST.EXE should be loaded as usual before starting MS Windows and then in each DOS session that will be running a Btrieve application, "BREQUEST /L" should be loaded. MS Windows applications will run as described previously.

6. MS Windows apps using the requester while running DOS applications using the local engine, BTRIEVE.EXE

   While using the MS Windows Btrieve requester, DOS applications in MS Windows DOS sessions may want to simultaneously use BTRIEVE.EXE. This situation also presents a problem, since BREQUEST.EXE must be loaded before MS Windows for use with the MS Windows requester DLL, and BTRIEVE.EXE must be loaded in each MS Windows DOS session. If you do not resolve this conflict, BTRIEVE.EXE reports, "Btrieve already loaded," and BTRIEVE.EXE will not load.

   BTRIEVE.EXE does not have a special load option like the BREQUEST.EXE "/L" parameter.

   To enable this configuration, load BREQUEST.EXE before MS Windows by using the WINSTART.BAT file feature provided by MS Windows. WINSTART.BAT is a batch file that MS Windows runs automatically when it is started in 386 enhanced mode. The programs that are started from within the WINSTART.BAT file are loaded in enhanced mode and are available to MS Windows applications, but not to DOS sessions started in MS Windows. If Brequest is loaded in WINSTART.BAT, BTRIEVE.EXE can then be loaded in a DOS session.

   To load BREQUEST.EXE in this manner, create the WINSTART.BAT file in the MS Windows directory and add a line specifying the BREQUEST.EXE program name followed by the parameters that your application requires for Brequest. For example:
   BREQUEST /d:8192
   The only drawback to this solution is that MS Windows v3.1 may sometimes hang on exit if TSRs are loaded with the WINSTART.BAT file. So, if the chance of hanging on exit from MS Windows must be prevented, or if you need to run MS Windows in standard mode, this configuration is not an option.

Stay Up-To-Date

In addition, the latest patches for the current local Btrieve engines (BTRIEVE.EXE v5.10a and WBTRCALL.DLL v5.10) are available on CompuServe in NOVLIB, Library 7, in the file BTR510.EXE. These files can also be requested by mail by contacting Novell Developer Support.

DEVELOPER NEWS:

New UnixWare 1.1 Release Responds to Customer Needs

Benefits

• Improved quality and performance accross the entire family of UnixWare products.

  Extensive testing and customer feedback have gone into making this release of UnixWare more robust and stable. Existing UnixWare 1.0 customers will find it very worthwhile to upgrade to UnixWare 1.1.

• Additional support for European languages.

  Along with support for English and Japanese, UnixWare will have native versions in French, Italian, German and Spanish by Q2 1994.

• Additional support for popular low-cost PC hardware.

  Supported hardware includes video cards, CD-ROM drives, Ethernet cards and SCSI cards. Support for this hardware will make it even easier for users to configure their system of choice.

• An aggressively priced and feature-rich SoftWare Developement Kit (SDK).

This new SDK will be very popular with ISVs and corporate developers. The new SDK offers the complete set of UnixWare development tools for a suggested retail price of US $99.00. When combined with the UnixWare Personal Edition, this is the most cost-effective UNIX development environment in the industry.

Features

• Bundled TCP/IP including PPP and SNMP.
• Motif v1.2 and Motif Windowing Korn Shell (wkSh) for greater Common Desktop Environment (CDE) compliance.
• Support for NetWare 4.x.
• Support for third-party compilers without the need to purchase the SDK.
• UnixWare Software Development Kit
• Motif Development Tools, Driver Development Tools and Personal Utilities are now bundled with the SDK to create a more complete and streamlined development environment.
• Bundled Pentium compiler that boosts performance for recompiled Intel 80486 applications as well as new Pentium applications.
• Complete online documentation; hardcopy manuals will now be a separate product.

Repackaged Products

The UnixWare Advanced Merge for MS Windows (P/N 90000061) product is now bundled in the Personal Edition and Application Server products.

The Personal Utilities (P/N 98000031 and 97000041), MTF Development Tools (P/N 96000042), and Driver Development Tools (P/N 96000032) are now bundled into the lower cost UnixWare SDK and Personal Utilities 1.1.

Availability, Pricing & Upgrades

Free upgrades from UnixWare 1.0 to UnixWare 1.1 are also available to the installed base. To upgrade, call one of the phone numbers listed in Figure 4. Please be prepared to provide your old UnixWare product serial numbers or proof of purchase.

FIGURE 4: Telephone & fax numbers for UnixWare 1.1 upgrades by country

Location            Telephone           Fax
Austria             0660-8443           0660-8125
Belgium             078-111062               078-111061
Canada              317-364-7276        317-364-0787
Denmark             800-10930           800-10545
France              05-905995           05-905996
Germany             0130-812444              0130-812443
Italy                    1678-8388           1678-78398
Norway              050-11310           050-11309
Spain                    900-993170               900-993169
Sweden              020-795736               020-795735
Switzerland              155-1846            155-1847
United Kingdom      0800-960274              0800-960273
United States       800-457-1767        317-364-0787
All Others               +31-55-434472       +31-55-434435
END of FIGURE 4

TECHNICAL INSIGHTS:

Running MS Windows Apps in WIN-OS2 (NetWare OS/2 SDK v2.0)

To use MS Windows apps in WIN-OS2 with the current version of the NetWare Requester for OS/2 (2.01), the WIN-OS2 session must be configured to run in Standard Mode. You should also set the "NETWARE_RESOURCES" setting to "private."

Finally, you also must load TBMI2 so that IPX resources can be shared. The easiest way to do this is to create an AUTOEXEC file that is executed when the WIN-OS2 session starts up. This file will load NETX and TBMI2 before starting WINOS2.EXE. The standard mode setting is checked through the WIN-OS2 Settings option in the "Settings" system menu option for the icon.

Comparing NetWare 3.11 & 3.12 Binderies (NetWare v3.12)

However, unlike NetWare v3.11, the v3.12 OS will not allow you to change certain some existing standard bindery properties to have non-standard features.

For example, if you try to change the user property, "SECURITY_EQUALS" from access security "Object read, Supervisor write" to "Object read, Object write," NetWare v3.12 returns the error message:
0xF1 (241): Invalid Bindery Security
and does not complete the operation.

NetWare v4.01 bindery emulation is even more restrictive in this situation. NetWare v4.01 does not allow you to:

• Change some existing standard bindery properties to have non-standard features (as in the example above)
• Create certain standard bindery properties

DPMS_M_RELOC() Returns Status 8021h (DOS Protected Mode Services v1.0)

If the offset value passed in SI + CX is greater than the length of the extended segment allocated to the selector passed in BX, then the DPMS.EXE returns status 8021h (Invalid Value) in the AX register.

This status can be a problem when the real mode code and the relocatable code are in the same data or code segment. For example, if you have five bytes of real mode data and 0100h bytes of data to be relocated to extended memory, but both are in the same data segment:
SI=0005h and CX=0101h
Then, the size of the extended memory allocated to the selector (in the BX register) must be 0105h bytes, even though the call is moving 0100h bytes.

To avoid invalid values in the AX register, make sure the length of the extended segment is large enough to accomadate the offset passed in SI + CX (the length of the segment of code to be moved).

Client SDK Documentation Errors (NetWare Client SDK v1.0d)

• NWScanOpenFilesByConn2()
• NWSendBroadcastMessage()
• NWDownFileServer()
• Date & Time Conversion APIs

NWScanOpenFilesByConn2() Version Compatibility

NWSendBroadcastMessage() Broadcast Message Size

All of the references in this portion of the documentation to NetWare 3.11c should be changed to NetWare 3.11 (there is no NetWare 3.11c). Also, the maximum number of connections that can be specified for a single broadcast for NetWare 3.11 and later is 65 rather than 62.

NWDownFileServer() & ForceFlag

Date & Time Conversion APIs

• NWConvertDate()
• NWConvertTime()
• NWConvertDateTime()

WATCOM v9.5 Usage of 8087 FPU Not Compatible with v9.0 (WATCOM 32 Bit C/C++ Compiler v9.5)

The "/fpr" option instructs v9.5 to use the old convention. A future version of WCC386 will add the "/fpr" option to the options turned on by "/bt=netware."

NLM SDK API Integer Format Function (NLM SDK v3.00)

A format function must be provided as the fifth parameter to AppendToForm(). This function formats the value in fData that you wish to display. Figure 5 contains an example of AppendToForm() and a format function for an integer value of 4000.

FIGURE 5: AppendToForm() with format function for an integer value of 4000.

/* Before main(): */

void IntegerFieldFormat (FIELD *, BYTE *, LONG);

/* In main(): */

  BYTE fData[4]; /* for an integer field */
  *((int *)fData) = 4000;
  NWSAppendToForm (line, row, width, VNORMAL,
 IntegerFieldFormat,  /* field format function */
 NULL, NULL, NULL,
 fData,  /* field to be displayed */
 NULL, NORMAL_FIELD,
 M_INSERT|M_DELETE,
 0, handle);

/* After main(): */
void IntegerFieldFormat(FIELD *fieldPtr,
BYTE *buffer,
LONG bufLen)
{
    bufLen = bufLen;
    sprintf (buffer, "%d", *((int *)fieldPtr->fieldData));

}
END of FIGURE 5

Releasing Embedded SQL Connections (NetWare SQL v3.00d)

NetWare SQL v3.00d returns status 351 if implicit transaction tracking is disabled with the db_transaction_processing function, and no explicit transaction has been started with a START TRANSACTION statement.

To avoid the status 351 when implicit transactions are disabled, issue a START TRANSACTION statement immediately before the COMMIT WORK RELEASE or ROLLBACK WORK RELEASE. Alternatively, you can omit the RELEASE statement, and the embedded SQL application will automatically disconnect from the database when the application ends.

If the application needs to log out of one database and log into a different one, you can issue a CONNECT statement to the new database. Doing so will automatically logout the user from the original database.

Problems with TLI & Borland C++ for OS/2 (NetWare Client SDK v1.0d)

Fatal Linker Error:

THREAD fixup found in module
message.c in module TLI.LIB

The same application will compile and link sucessfully with the IBM CSET/2 or Microsoft C compilers. There is no supported solution at this time other than to switch compilers.

NetBIOS Emulator Does Not Support Multi-LAN Cards (NetBIOS for DOS v3.14)

Developers writing NetBIOS applications sometimes issue dummy commands to see how many LAN adapters are present. One way to check this number is to load up "filler" data and send a Network Control Block (NCB) to a specific LAN number. If the adapter in question is present, the error message returned is:

Invalid Command

If the adapter is not present, the network returns the error message:

Invalid LAN Adapter

Using Novell's NetBIOS emulator, only the "Invalid Command" error message is returned; that is, the network returns "Invalid Command" when you send data and an NCB to LAN Adapter 0, but the same error is returned when sending to LAN Adapter 1.

Some validation of NCBs takes place just after a request is made to NetBIOS. A check is made to make sure the LAN adapter number is 0 or 1. However, the emulator does not validate the existence of primary or secondary LAN adapters. The emulator just detects the presence of IPX, indicating there is a LAN card.

Under the Novell NetBIOS emulator, there is no way to detect the number of NetBIOS adapters present using NetBIOS calls. There will, however, always be only one adapter present.

One possible workaround is to check for IPX. If IPX is present, you can assume that the workstation is running Novell's NetBIOS and, therefore, the workstation has only one LAN adapter.

CloseScreen() & NetWare 4.01 (NLM SDK v3.0)

This situation has been resolved in the next release of CLIB. Until the new version is released, a version of CLIB that prevents the abend is available. To request a copy, contact Novell Developer Support at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.

NWSendConsoleBroadcast() Sends Blank Message (NetWare Client SDK v1.0d)

Novell Engineering is currently investigating the problem. There is no solution at this time, but as a workaround, use the function, NWSendBroadcastMessage(), which works correctly.

Linker Errors with NWSNUT.IMP (NLM SDK v3.0)

• NWSGetHandleCustomData()
• NWSSetHandleCustomData()
• NWSSetFormNoWrap()
• NWSWaitForEscapeOrCancel()

Incorrect Header File Definitions (NetWare Client SDK v1.0d)

NWERROR.H incorrectly defines SOCKET_NOT_OPEN as 0x8852 and SOCKET_ALREADY_OPEN as 0x89FF, but NXTW.H defines both SOCKET_NOT_OPEN and SOCKET_ALREADY_OPEN correctly as the value, 0xFF.

When developing an MS Windows application, either remove these two definitions from NWERROR.H, or be sure to always include NWIPXSPX.H after including NWCALLS.H so that the second set of define statements is the correct one.

When developing a DOS application, you must define these two constants, since they are not included in any of the DOS header files.

t_rcvconnect() Blocks Even in Nonblocking Mode (NetWare Client SDK v1.0d)

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

Fetching Records with SQL-Level Calls (NetWare SQL v3.00)

The first Pascal example in Figure 6 fetches unformatted data from the "Appointments" table based on the view created with the statement:

SELECT ID, Appointment^Date, Doctor
  FROM Appointments

This will accommodate the 6-character ID, the 8-character "Appoinment Date" formatted according to the default mask of mm/dd/yy, and the 12-character "Doctor" name. Each field will have two spaces after it, since iSpacing = 2. Therefore, each record will require (6+2) + (8+2) + (12+2) = 32 characters.

Using the iASCIIFlag to return formatted data (as shown in the second example in Figture 5) is especially useful when fetching data types that are not supported by your particular compiler. For example, the "Money" type is based on a COBOL packed decimal. If a C or Pascal program is used to fetch "Money" data, it can not display it without manually interpreting the values in each byte, or using the XQLConvert function to convert the internal data to a displayable string. On the other hand, if you want your program to be able to manipulate numeric data, you would want to fetch it in internal format, rather than formatted.

FIGURE 6: Two Fetch routines

Method 1:
{ To fetch unformatted data }
.
.
.
*PROCEDURE FetchRecords (CursorID : Integer);
VAR
  bDataBuf : ARRAY [1..MaxRecs] OF RECORD
               reclen  : integer;
               ID      : ARRAY [1..6] OF char;
               AppDate : RECORD
                           day, month : byte;
                           year : integer
                         END;
               Doctor  : ARRAY [1..12] OF char
             END;
  iStatus, iOption, iBufLen, iASCIIFlag, iSpacing, i : integer;
  lCount : longint;
BEGIN
  iOption    := 1;        { Fetch first records in view }
  iASCIIFlag := 0;        { return data in internal format }
  iSpacing   := 0;
  REPEAT
    lCount  := MaxRecs;   { How many records to fetch }
    iBufLen := SizeOf(bDataBuf);
    iStatus := XQLFetch (CursorID, iOption, iBufLen, bDataBuf, lCount,
                         iASCIIFlag, iSpacing);
    IF iStatus > 0
      THEN writeln('Error on XQLFetch; status = ', iStatus)
      ELSE BEGIN
             FOR i := 1 to lCount DO       { For each record returned� }
               BEGIN
                 write('Record #', i:2, ':  ');
                 write(bDataBuf[i].ID, '  ');  { display ID }
                 WITH bDataBuf[i].AppDate DO   { display Appoint. Date }
                   write(month:1, '/', day:1, '/', year:1);
                 writeln('  ', bDataBuf[i].Doctor)  { display Dr. name }
               END;
             iOption := 2 { Change option to fetch next record in view }
           END;
  UNTIL Status <> 0
END;
Method 2:
{ To Fetch data already formatted, the program can be changed as
follows: }
*PROCEDURE FetchRecords (CursorID : Integer);
VAR
  bDataBuf : ARRAY [1..MaxRecs] OF RECORD
                                     reclen : integer;
                                     data   : ARRAY [1..32] OF char
                                   END;
  iStatus, iOption, iBufLen, iASCIIFlag, iSpacing, i : integer;
  lCount : longint;
BEGIN
  iOption    := 1; { Fetch first records in view }
  iASCIIFlag := 1; { return formatted data, fields separated by spaces }
  iSpacing   := 2;    { two spaces between fields
  REPEAT
    lCount  := MaxRecs;   { How many records to fetch }
    iBufLen := SizeOf(bDataBuf);
    iStatus := XQLFetch (CursorID, iOption, iBufLen, bDataBuf, lCount,
                         iASCIIFlag, iSpacing);
    IF iStatus > 0
      THEN writeln('Error on XQLFetch; status = ', iStatus)
      ELSE BEGIN
             FOR i := 1 to lCount DO       { For each record returned� }
               BEGIN
                 write('Record #', i:2, ':  ');
                 writeln(bDataBuf[1].data);      { display all fields }
               END;
             iOption := 2 { Change option to fetch next record in view }
           END;
  UNTIL Status <> 0

END;
END of FIGURE 6

Ascending Order & Autoincrement Keys (Btrieve for DOS v5.10a)

Autoincrement keys should always be defined as Ascending.

Accessing Named Pipes Through UNC File Names (NetWare OS/2 SDK v2.0)

\\servername\pipe\pipename

Communications with a named pipe can also be established from the OS/2 command line with the copy or type commands and the UNC file name of the pipe. For example:

copy autoexec.bat \\myserver\pipe\mypipe

This command will also work from DOS sessions running under OS/2. In both cases, the target device can be either a named pipe or a NetWare volume specification. Specifically, the UNC specification for a NetWare volume:

\\servername\volname\path

will also work as a target device from OS/2 or DOS VDM copy commands.

The MS-DOS v5.0 COMMAND.COM file does not support UNC filename conventions for either NetWare volumes or Named Pipes. To access Named Pipes from a DOS machine, you must create an application that uses the DOS file commands (i.e., that issues int 21s) to copy to Named Pipes.

NetWare SQL Reject Counts (NetWare SQL v3.00x)

This discrepancy is due to the fact that NetWare SQL issues Btrieve extended calls with filters, causing Btrieve to only return records that match the filter. The reject count reflects the number of records that Btrieve returned to NetWare SQL for processing which were rejected by NetWare SQL as not meeting the view criteria.

Sometimes, NetWare SQL may return a reject count of zero, even though there are records in the file that are not returned. This reject count indicates that Btrieve filtered out the necessary records, and all data given to NetWare SQL by Btrieve matched the view restrictions.

At other times, NetWare SQL may return a reject count of one, which usually means that NetWare SQL issued a Btrieve Get First or Step First operation to establish positioning, then rejected that record for not matching the view restrictions, and finally issued the Btrieve extended calls with filters.

The types of restrictions on the view determine the types of filters that can be specified in the Btrieve extended calls. Some combinations of restrictions can be entirely filtered by Btrieve, while others can only be partially filtered by Btrieve, leaving NetWare SQL to do the rest of the processing.

NIBBLES AND BITS

Fast Answers to Common Questions

NetWare Client SDK

A - The recommended maximum packet size for any particular workstation is 576 bytes. This is based on the minimum size guaranteed to be available across any given route on a network. In many cases, the actual packet size is larger, since it is based on the architecture of the NIC (network interface cards) in use. IPX for DOS and MS Windows includes an API called IpxGetMaxPacketSize() that allows the determination of the maximum packet that a particular workstation can send. This call is not available under OS/2.

An undocumented API in IPX for OS/2 that communicates with the NIC called IpxRequest() can be used to obtain the packet size for a workstation. IpxRequest() code 0x28 returns the board length for the card addressed. The syntax is:

ret = IpxRequest(USHORT command, VOID FAR *buffer);

where command is 0x428 and buffer contains an unsigned integer identifying the card to address. The card numbers are zero-based and "-1" is used for the primary NIC. An example for IpxGetMaxPacketSize() is posted on NOVDEV (NDEVSUPP, Library 1, IPXMAX.C).

Q - How can I find all of the Directory Service (DS) Trees advertising on the network?

A - Use the QueryService() API to locate the nearest Directory Service tree. It is advertised as Server Type 0x0278. To locate all DS trees, issue a general service query.

Q - When my code calls EndDiagnostics() after BeginDiagnostics() has failed, subsequent BeginDiagnostics() calls fail. What should I do?

A - To avoid this problem, do not call EndDiagnostics() when BeginDiagnostics() has failed.

NETWARE.DRV

A - If you are using NETX.COM, you should be using NETWARE.DRV v2.02 (dated 10-27-92, file size of 126,144 bytes). This file is available in WINUP8.EXE from the NOVFILES forum. If you are using the VLMs, the correct NETWARE.DRV is v3.01 (dated 3-30-93, file size of 196,672 bytes). This file is contained in WSWIN.EXE in the CLIENT.KIT subdirectory of NOVFILES. This later version of NETWARE.DRV is intended for VLMs only and is not compatible with NETX.COM.

DOS Protected Mode Services

A - The DPMS_M_RELOC() function requires the size of the segment to be moved to be passed in the CX register minus one byte. Thus, the largest segment of code that can be moved into extended memory one call is 65535 bytes. The extended registers are not used by this call.

NetWare Btrieve

A - Raise the IPX retry count in your NET.CFG. The recommended value is 40 or more. The workstations are timing out and their SPX connections are being terminated.

Q - When moving from the NetWare Btrieve NLM v5.x to the NetWare Btrieve NLM v6.x, do I have to convert the 5.x files to a 6.x format?

A - The NetWare Btrieve NLM v6.10x has built in support for v5.x files. System administrators can choose whether or not to convert the Btrieve data files in order to upgrade the NLM to 6.10x. As always, read the README that comes with Btrieve for up to date directions on moving from one version to the next.

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

A - Btrieve has sent a message to a workstation that has been timed out by the NetWare watchdog.

To prevent the message, increase the SPX WATCHDOG ABORT TIMEOUT, SPX ACK WAIT TIMEOUT, and SPX WATCHDOG VERIFY TIMEOUT parameters on the server where BSPXCOM.NLM is loaded. Also increase the SPX ABORT TIMEOUT, SPX LISTEN TIMEOUT, and SPX VERIFY TIMEOUT parameters in the NET.CFG file on the workstation.

Q - Once I have used the NetWare Btrieve NLM v6.10x can I switch back to Btrieve for DOS, Btrieve for OS/2, or Btrieve for Windows?

A - If your system requires that the files be available for both NLM and client use, there are several steps to take to insure the proper use of the file:

• Do not convert the 5.x files to the 6.x format. The versions of Btrieve for DOS, MS Windows, and OS/2 do not support the v6.x file format.
• Read the section of the Btrieve v6.10 README file that gives instructions on preimage files. Btrieve v5.x and v6.x pre-image files are incompatible and you need to take steps to prevent the different versions of the engines from using different version of the pre-image file.
• When using BSETUP, be sure to select the option that creates files in the 5.x format. If this option is not used all files that are created will be in the new 6.x format and the clients will return status 2s when trying to access them.

Xtrieve PLUS

A - Valid characters for dictionary names are:

• a through z
• A through Z
• 0 through 9
• ^ (caret)
• _ (underscore)
• ~ (tilde
• blank space

Q - What patches are available for Xtrieve PLUS?

A - Four patch files for Xtrieve PLUS are available on Novell's NOVDEV forum on CompuServe:

• XTRDOS.EXE - patches for Xtrieve PLUS for DOS, v4.10 and v4.11
• XTROS2.EXE - patches for Xtrieve PLUS for OS/2, v4.11
• XTRNWS.EXE - patches for Xtrieve PLUS for NetWare SQL, v4.11 contains patches for both the DOS and OS/2 versions of Xtrieve PLUS that shipped with NetWare SQL v3.0.
• XTR401.EXE - patches for Xtrieve PLUS for DOS & OS/2, v4.01x

TIP: The XTRPATH environment variable can be used to tell Xtrieve PLUS where your data files are located. This can be set before getting into Xtrieve PLUS or from the Configure/ Environment menu option in Xtrieve PLUS. For example:

SET XTRPATH=F:\DATA;G:\FILES

tells Xtrieve PLUS to search for data files in the F:\DATA directory, and if they are not found, to search the G:\FILES directory.

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: Linda Anderson, Jack Gumaer, Laura Heater, Sudz Khawaja, Nancy Kromar, Clint McVey, Chris Ojeda, Bill Prentice, Matt Pinsonneault, Jose Pruneda, Bob Quinlan, Drue Reeves, Wolfgang Schreiber, Michael Spano, Aslam Tejani, and Brenda Wallace

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, Btrieve, XQL and LANalyzer are registered trademarks; LAN WorlShop, NetWare SFT III, NetWare Loadable Module, NLM, Global MHS, NetWare MHS, NetWare System Calls for DOS, NetWare SQL, NetWare Btrieve, Report Executive, NetWare Asynchronous Services Interface (NASI), NetWare Management System, Xtrieve PLUS, DeveloperNet Labs, UnixWare, AppWare, AppWare Foundation, AppWare Loadable Module, ALM, AppWare Bus, 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 is a trademark of Microsoft Corporation. Apple and Macintosh are registered trademarks of Apple Computer, Inc. CompuServe is a registered trademark of CompuServe Corporation. Sun Microsystems and NFS are registered trademarks 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.