DECEMBER 1992 VOLUME 4 NUMBER 11
INDEX
Hello and welcome to the December 1992 issue of Bullets! Is last year over or is the new year
just starting? The power of positive thinking keeps all of us going, whether we are coding,
debugging or just enjoying life.
Novell developers have quite a bit of new "stuff" to expect during this next year. In addition to
new Novell software developer kits (SDKs) such as the cross-platform APIs, expect support for
additional compilers and platforms. You can also look forward to the Developer Relations
group's announcement of a number of specialized developer programs throughout the coming
year.
Start penning in trade show dates such as NetWorld Boston '93 -- traditionally a February affair,
now set for January 12 through 14. NetWorld Europe '93 is scheduled for late April. Global
BrainShare '93 activities are slated to begin March 22 through 26 in Salt Lake City.
Also during the next year, you will see this publication growing and changing to maintain the
flow of technical information to you on these SDKs and programs. Traditionally focusing on
core NetWare and database API information, technical notes and tips, Bullets is expanding to
encompass topics of developer interest from all Novell engineering sites and platforms.
Happy_Holidays!
Mad Poarch
Director
Developer Support/Service
LANalyzer: The NetWare Detective
The LANalyzer for NetWare is a Windows-based application that allows you to monitor
network operations and analyze packet traffic on Ethernet networks using NetWare or AppleTalk
protocols. Developers and System Administrators can use the LANalyzer to debug hard-to-find
application and network problems. This article will discuss LANalyzer as a development and
maintenance tool, and examine the most useful features by debugging an application problem.
Uses of the LANalyzer
The LANalyzer for NetWare allows you to monitor your network at the packet level on a
day-to-day or long term basis. It also gives you the ability to analyze specific problems occurring
on the network. These problems may be application-, hardware-, topology-, or driver-related. The
LANalyzer provides real-time "snapshots" of network operations and allows you to capture
network packets for protocol analysis. These "snapshots" allow you to be the network "detective"
when isolating application and network problems.
You can use the LANalyzer to perform detailed analyses of your network and how applications
affect it. Statistics can be obtained in two different areas. Current network statistics can be
viewed via the "dashboard," which provides a broad analysis of network performance. For a
more detailed view, short and long term network statistics can be displayed in graphs and tables
that can be printed and used in application design, prototyping and testing processes.
Station Filtering
With the LANalyzer, you can monitor and analyze packets by filtering in one of two ways,
station filtering and protocol filtering. Station filtering lets you monitor network traffic between
various entities on the network in four different ways:
- Between two selected stations on a network
- From one selected station to another selected station
- From one selected station to all other stations
- To a selected station from all other stations on the network
Stations are tracked by their network addresses and can be either network workstations or
file servers. Station network addresses can be mapped to user/station names to simplify the
network administration and maintenance process. The station names can be used instead of
network addresses when setting up filter conditions between various network nodes.
Protocol Filtering
Protocol filtering lets you filter network packets of a specified protocol (either NetWare or
AppleTalk protocols). The LANalyzer supports all of the common protocols used with NetWare,
including IPX, NCP, SPX, RIP, Watchdog, SAP and NetBIOS. By filtering packets in this
manner, you can isolate the packets that are of interest in debugging or analyzing an application.
Filtered packets are captured and then displayed in the Capture Buffer. The Capture Buffer
includes a Summary window, a Decode window and a Hexadecimal window. The Summary
window gives the developer an overview of the conversation between the source and destination
stations. The Decode window displays detailed information about the contents of a selected
packet. The Hexadecimal window shows interpreted packet data in hexadecimal and ASCII
formats (similar to the DOS DEBUG utility). This article provides additional information on
each window in the section on debugging the sample application.
Applications for Developers
The LANalyzer is a very useful tool for developers. There are a number of specific cases
in which data from a LANalyzer packet "dump" can help you identify and resolve application
problems and performance issues, including situations in which:
- An application runs properly once loaded, but takes a long time to load.
- An IPX/SPX/NetBIOS based application is not receiving data.
- An application is receiving "garbage" or corrupted data.
- An application runs unusually slow.
- Frequent network errors are generated while running an application.
These are just a few of the possibilities the LANalyzer offers as a development tool. This
article will examine the second situation in the sample application.
Sample Application
The sample application is an application that is familiar to many developers: SPXChat.
Included with the Novell's NetWare C Interface for DOS SDK, SPXChat is an example of SPX
communications between two workstations. In our example, STATION1 is unable to establish an
SPX connection with STATION2.
The first symptom of trouble is an error code 237 (0xED, SPX_CONNECTION_FAILED)
returned from the SPXEstablishConnection. Because the network address was obtained from a
GetInternetAddress call, the address passed to SPXChat should be correct. The network address
can be validated by issuing the command, "USERLIST STATION2 /A" (/A gives us the network
address of the specified user), and then comparing this address with the address returned from the
GetInternetAddress call. In this example, the two addresses match.
If the network address is correct, the SPXEstablishConnection call should have succeeded. At
this point, you could add additional debug code to the application and look for obvious memory
corruption or the packet header. Unfortunately, this process is time-consuming. Another option is
to use the LANalyzer as a diagnostic tool to see what is happening at the packet level. Figure 1
contains a segment of code from SPXChat that we will analyze with the LANalyzer.
FIGURE 1: Code excerpt from SPXChat
void CreateConnectionECBandHeader(int connectionNumber)
{
connectionECB = (ECB *) calloc(1, sizeof(ECB)) ;
sendHeader = (SPXHeader *) calloc(1, sizeof(SPXHeader)) ;
GetInternetAddress((WORD) connectionNumber,
(char *) sendHeader->destination.network,
(char *) sendHeader->destination.node,
(WORD *) &fSocket);
*(WORD *) sendHeader->destination.socket = socket ;
*sendHeader->destination.node=0x01;
connectionECB->socketNumber = socket ;
connectionECB->fragmentCount = 1;
connectionECB->ESRAddress = (void (far *) () ) 0 ;
IPXGetDataAddress((BYTE *) (sendHeader),
(WORD *)
&connectionECB->fragmentDescriptor[0].address) ;
connectionECB->fragmentDescriptor[0].size = sizeof(*sendHeader)
;
}
End of Figure 1
Figure 2 shows a GetInternetAddress request for the connection number of the user
logged into STATION2. STATION2 is logged into connection 1, which the LANalyzer lists as
the "Target Connection." This demonstrates the direct correlation between the API call and the
packet that was sent over the wire.
FIGURE 2: GetInternetAddress request for STATION2
Packet Number : 197 4:02:42PM
Length : 64 bytes
802.3: =============== IEEE 802.3 Datalink Layer ===============
Station: STATION1 --> AUS-TIN
Length: 42
ipx: ============= Internetwork Packet Exchange ==============
Checksum: 0xFFFF
Length: 41
Hop Count: 0
Packet Type: 17(NCP)
Network: AB BB DD DD --> 41 44 A0 00
Node: STATION1 --> CSHAW
Socket: 0x4003 --> NCP
ncp: ================= NetWare Core Protocol =================
NCP Request: Get Internet Address
Request Type: 0x2222 (Request)
Sequence Number: 182
Connection Number Low: 12
Task Number: 15
Connection Number High: 0
Function Code: 23
Subfunction Length: 2 bytes
Subfunction Code: 19
Target Connection: 1
End of Figure 2
Figure 3 shows the file server's reply to the GetInternetAddress request. To identify this
packet, examine the NetWare Core Protocol (NCP) portion of the packet. The LANalyzer
identifies it as an NCP reply of type "Get Internet Address." Although other information is
included in the packet breakdown, we are primarily interested in the completion status and the
network address.
FIGURE 3: File server's reply to the GetInternetAddress request
Packet Number : 198 4:02:42PM
Length : 68 bytes
802.3: ================ IEEE 802.3 Datalink Layer ================
Station: AUS-TIN --> STATION1
Length: 50
ipx: =============== Internetwork Packet Exchange ==============
Checksum: 0xFFFF
Length: 50
Hop Count: 0
Packet Type: 17(NCP)
Network: 41 44 A0 00 --> AB BB DD DD
Node: CSHAW --> STATION1
Socket: NCP --> 0x4003
ncp: ================== NetWare Core Protocol ==================
NCP Reply: Get Internet Address
Reply Type: 0x3333 (Reply)
Sequence Number: 182
Connection Number Low: 12
Task Number: 1
Connection Number High: 0
Completion Code: 0 (Success)
Connection Status: 0x00
Network Address: 0xAB 0xBB 0xDD 0xDD 0x00 0x00 0x1B 0x31
0x8D 0x13 0x40 0x03
End of Figure 3
The Completion Code returned by the LANalyzer is zero, indicating success. The
NetworkAddress is displayed. The destination network address is "0xAB 0xBB 0xDD 0xDD
0x00 0x00 0x1B 0x31 0x8D 0x13 0x40 0x03." This network address really contains three
different fields, as shown below:
Network: 0xAB 0xBB 0xDD 0xDD
Node: 0x00 0x00 0x1B 0x31 0x8D 0x13
Socket: 0x40 0x03
This address agrees with the address obtained with the USERLIST /A command and with the
information obtained via the debugger. Figure 4 contains the SPXEstablishConnection request.
FIGURE 4: SPXEstablishConnection request
Packet Number : 199 4:02:42PM
Length : 64 bytes
802.3: ================ IEEE 802.3 Datalink Layer ================
Station: STATION1 --> 01-00-1B-31-8D-13 (STATION2 ?)
Length: 42
ipx: =============== Internetwork Packet Exchange ==============
Checksum: 0xFFFF
Length: 42
Hop Count: 0
Packet Type: 5(SPX)
Network: AB BB DD DD --> AB BB DD DD
Node: STATION1 --> 01-00-1B-31-8D-13
Socket: 0x4545 --> 0x4545
spx: ======== NetWare Sequenced Packet Exchange Protocol =======
Connection Control: 0xC0 (System Packet; Send ACK; )
Datastream Type: 0
Source Connection ID: 47901
Destination Connection ID: 65535
Sequence Number: 0
Acknowledge Number: 0
Allocation Number 4
End of Figure 4
The IPX section of the packet displays the network addresses of the sending and
receiving network stations. The destination address in the packet is shown below:
Network: 0xAB 0xBB 0xDD 0xDD
Node: 0x01 0x00 0x1B 0x31 0x8D 0x13
Socket: 0x45 0x45
The first byte of the node address is incorrect--the value should be 0x00, not 0x01. Normally,
this is a sign of memory corruption or of an accidentally reassigned field value. In this case, a
field value has been changed. (The value of the first byte of the node address was intentionally
changed in the application to demonstrate using the LANalyzer for NetWare.) However, there
have been numerous cases where application memory corruption has produced the same
symptoms.
You might have noticed that the socket number is different as well. The socket number is correct,
because the application is using socket 0x45 0x45. The network uses it's own socket for NCP
requests; in this example, the request/reply for GetInternetAddress. So, our detective work pays
off, we have discovered why the SPXEstablishConnection call failed.
When used to debug applications, the LANalyzer for NetWare is a very effective tool for
NetWare developers. This example only demonstrates a very small portion of the functionality of
the LANalyzer. It has many other capabilities for monitoring network and application problems.
The LANalyzer can also aid in application design and prototyping by providing an accurate view
of application load and it's impact on the network. The LANalyzer is a unique and helpful
development tool that can make you a more effective "NetWare Detective."
For more information on the LANalyzer product family, contact the Professional Developers'
Program at 1-800-RED-WORD (512-794-1796), or your local Novell authorized reseller.
Setting Directory Attributes (Network C for NLMs v2.0)
When setting the hidden or system attributes of a directory when using ChangeDirEntry,
in addition to setting the MFileAttributes field (in the ModifyStructure) to the desired value, you
must also set the MFileAttributesMask. The MFileAttributesMask specifies the maximum rights
that can be changed when setting the MFileAttributes.
NetWare C Interface Documentation Correction (NetWare C Interface for DOS v1.2)
The documentation for the NetWare C Interface for DOS v1.2 incorrectly describes the
nextResetTime field in the LOGIN_CONTROL bindery property. It states that the value is stored
in seconds since January 1, 1985. The value is actually measured in minutes since January 1,
1985.
Be sure to calculate in minutes instead of seconds when setting the nextResetTime for an account
lockout or reset.
NetWare SQL Zstring & Lstring Optimization (NetWare SQL v3.0)
When attempting to restrict on a Zstring or Lstring field in an SQL-Level or Relational
Primitive application, NetWare SQL does not fully optimize the search, even when there is an
index on the field. For example, if a zstring field contains the data:
"T", "T1", "Test", and "Test1"
in four different records, and the statement:
SELECT * FROM Tbl WHERE fld = "T"
is executed, NetWare SQL will correctly return the single record with "T," but will reject the
other three records. Normally with an indexed search, NetWare SQL does not have to reject any
records. This applies to both Zstring and Lstring fields that are defined as case-sensitive. (If the
field is case-insensitive, NetWare SQL must check additional records for "t.") If the field in the
example had been defined with the CHAR data type instead of Zstring or Lstring, the indexed
search would be fully optimized, selecting the one correct record and rejecting zero records.
The logic currently used by NetWare SQL to find the correct records matching the restriction sets
up a "stopping point" to tell NetWare SQL when to stop asking Btrieve for more records. For
Zstring and Lstring fields, this stopping point is defined as "less than (value+1)," which in the
above example would be "less than 'U'." Since "T1," "Test" and "Test1" are less than "U,"
NetWare SQL doesn't stop until after getting those records from Btrieve. However, only the
correct "T" record is returned to the calling application.
Bullets AIO.NLM Correction (Network C for NLMs v2.0 (e))
The October issue of Bullets incorrectly stated that "the AIO NLM supports intelligent
boards, such as ARTIC and WNIM+." Neither the ARTIC nor the WNIM+ boards are supported;
only the DigiBoard PC/Xe and CX boards and the Newport Systems ACI board are currently
supported.
Support for these intelligent serial I/O boards actually comes from the AIO "driver" NLMs that
are typically written by hardware vendors, rather than the AIO NLM. The relationship between
these NLMs is portrayed in Figure 5.
FIGURE 5: AIO NLM relationship
+----------------------------+
| |
| Application NLM |
| |
+----------------------------+
|
|
|
+----------------------------+
| |
| AIO NLM |
| (supplied by Novell) |
+----------------------------+
|
|
|
+----------------------------+
| |
| AIO Driver NLM |
| (supplied by vendor) |
+----------------------------+
End of Figure 5
The NACS Server is an example of an Application NLM. Another Novell application for
the AIO services is the NetWare Global Messaging product (NGM) released in July, 1992. The
MHS-Async NLM, which is a part of the basic NGM NLM set, uses the AIO interface to deliver
mail via modems connected to either the telephone system or to leased analog lines.
NetBIOS & OS/2 (NetWare OS/2 Developer's Kit v2.0)
When a DOS machine sends a NetBIOS remote adapter status call to a machine running
OS/2 v2.0 with Novell's NetBIOS installed, the OS/2 machine will abend if you are not using the
latest versions of NetBIOS and NBDAEMON.
To prevent the abend, use the latest versions of NETBIOS.SYS (9-18-92 or later) and
NBDAEMON.EXE (5-22-92 or later). This version of NetBIOS only works after the patch file
NSD201.ZIP has been applied (available on NetWiresm, NOVLIB, LIB 5).
Floating Point Operations & VAPs (NetWare C Interface for DOS v1.2)
Performing floating point operations from within a VAP will produce undesirable results,
unless you supply floating point startup code. Floating point startup code is usually supplied with
compilers.
If you choose not to modify the startup code, another alternative is to write your own floating
point libraries.
Calling _msize() with Protected Memory (NetWare v3.x)
PROTECT.NLM is a NetWare Loadable Module (NLM) that ensures that other NLMs
cannot access resources to which they have no rights. Calling realloc() while running under
PROTECT.NLM may cause a server abend. This situation occurs when you attempt to reallocate
a memory block that is part of the AllocNonMovableCacheMemory pool. During this process,
_msize(), which is called by realloc(), attempts to determine the type of memory that has been
allocated, and triggers the abend.
This situation only arises when an NLM is running under PROTECT.NLM. Currently, the only
workaround is to avoid running under PROTECT.NLM.
AIOWriteData() Documentation Update (Network C for NLMs v2.0 (d))
The documentation for AIOWriteData() incorrectly states that the function will not
succeed unless the entire requested data length can be copied to the transmit buffer all at once. In
fact, AIOWriteData() will allow partial writes, in which case the unsent characters must be
resent.
The DESKTOP.AFP Directory (NetWare v3.x)
To support Macintosh workstations, NetWare's AFP NLM keeps a set of files in a hidden
directory on the SYS: volume named DESKTOP.AFP. This directory contains several files used
to store the locations where Macintosh files can find their supporting utilities and other
information. This directory controls how and where programs and files reside on the volumes
and must be maintained precisely.
You should not restore DESKTOP.AFP from a backup. If any files or AFP-related programs
(utilities) have been moved or deleted since the last backup, a restored DESKTOP.AFP directory
will contain incorrect and out-of-date information about the current configuration. Rather than
restoring DESKTOP.AFP from a backup, you should rebuild the desktop from a Macintosh
workstation. The Macintosh will update the desktop to reflect the current directory setup and the
location of programs and files.
Accidentally Linking with CLIB3S (Network C for NLMs v2.0 (d))
If a symbol that is not included in CLib is referenced in an OBJ, and the symbol is in the
DOS static library, CLIB3S, WLINK will not only pull in the definition for the DOS function,
but will also pull in other modules that contain symbols referenced by that object module. For
example, if dup() is referenced by an NLM, not only is dup() imported, but unlink(),
__get_errno_ptr(), and many other APIs, as well.
This accidental link to CLIB3S will produce many undesirable results and subtle bugs can go
unnoticed. In one case, a DOS API failed with "-1," but errno showed "0," since the errno from a
library module was being set instead of CLib's thread errno. If an INT 21 is executed, the server
will abend, making the situation very easy to resolve.
To avoid accidentally linking to CLIB3S, always use Option NOD when linking. This option
prevents WLINK from searching the libraries whose names are imbedded into the OBJs.
Otherwise, avoid setting the LIB386 environment variable, so that the LINKER cannot access
the DOS libraries.
Data Types for Group Aggregates (NetWare SQL v3.0)
The data types returned by various group aggregates available for an SQL SELECT
statement vary depending on the data type of the field and the type of aggregate. This fact is
important when fetching the data in its internal format, since a databuffer must be set up properly
to receive the data. For the COUNT group aggregate, the data is always returned as a four-byte
integer. For the MAX and MIN aggregates, the data is returned as the same data type and length
as the field used for the aggregate. For the SUM and AVG group aggregates, the data type
returned varies for different field data types. Figure 6 contains a chart describing the data types
returned for SUM and AVG group aggregates.
FIGURE 6: Data types returned for SUM and AVG group aggregates
Field data type SUM or AVG data type
-----------------------------------------------------
autoinc float(8)
bfloat float(8)
bit float(8)
decimal(x,y) decimal(10,y)
float float(8)
integer float(8)
logical float(8)
money(x,2) money(10,2)
numeric(x,y) numeric(15,y)
numericsts(x,y) numericsts(15,y)
End of Figure 6
Notice that Decimal, Money, Numeric, and NumericSTS all return the same data type as
the field, except the size is the maximum allowable for that data type (10 for decimal and money,
15 for numeric and numericsts). For all other data types, an eight-byte float is returned. (This
information applies to NetWare SQL v3.0 only. With XQL v2.11 NetWare SQL v2.11, SUM and
AVG always return an eight-byte float value.)
NDBCOMM.DLL Configuration Parameter (NetWare SQL v3.0)
NDBCOMM.DLL is part of the NetWare SQL OS/2 requester, and is used in conjunction
with the XQLCALLS.DLL by NetWare SQL applications running on an OS/2 client. A special
configuration parameter, NDBTIMEOUT, can be set to tell the NDBCOMM.DLL how long to
wait before resetting the session. If this parameter is not set, NDBCOMM.DLL will wait 60000
milliseconds (60 seconds) for a response. This parameter can be set to increase the time
NDBCOMM will wait, or it can be set to "-1," which tells NDBCOMM to wait indefinitely. The
syntax is:
SET NDBTIMEOUT=
This statement can be executed from the workstation's CONFIG.SYS file, or from the command
line before the first NetWare SQL application is started (i.e. before NDBCOMM.DLL loads).
Some example settings are:
SET NDBTIMEOUT=-1
(NDBCOMM will wait indefinitely)
SET NDBTIMEOUT=900000
(NDBCOMM will wait 15 minutes for a reply)
Certain NetWare SQL queries may cause NetWare SQL to build one or more temporary sort
files. When tables with many records are involved, this process may take a while, in which case
you may need to set this parameter to a very high value, or use the "-1" option.
NetWare Utilities & Object Names (NetWare C Interface for DOS v1.2)
To ensure that NetWare utilities recognize object names, all object names should be
entered in upper case when passed as parameters to the API functions.
If a lower case string is passed into the fileServerName parameter of AttachToFileServer(), the
API will attach you to the appropriate file server. At this point, the NetWare WHOAMI utility
works correctly. However, after the LoginToFileServer() is performed, the WHOAMI utility
returns the error message "unable to get connection status [89FC]." The NetWare LOGOUT
command also will not recognize the lower case server name.
Btrieve for Windows & File Handles (Btrieve for Windows v5.10)
Btrieve for DOS and Btrieve for Windows manage handles differently. Btrieve for DOS
v5.10a allocates its own Program Segment Prefix (PSP) with a file handle table of size (/f
parameter * 2) entries (with patch #99 applied). Btrieve for DOS does not use the calling
application's file handles. This means that when a DOS application has opened 20 Btrieve files,
the application still has 15 handles (20 DOS default handles minus 5 standard handles) available
for use to issue DOS Open calls to non-Btrieve files.
Btrieve for Windows manages handles using the calling application's file handle table. When
the application's available handles are exhausted, WBTRCALL will "rotate" the handles as in
versions of Btrieve for DOS prior to v5.10. Once 15 Btrieve files are open, there are no handles
available to the calling application for DOS Open calls to non-Btrieve files, since DOS will not
rotate handles.
At this point, if another Btrieve Open call is issued, WBTRCALL will close one of its open files
and use the handle to open the new file. This process occurs invisibly to the application and
WBTRCALL can handle up to its current "/f:" parameter of rotating files at one time.
WBTRCALL will use whatever application handles are available. If DOS Open calls to
non-Btrieve files are needed along with more than 15 Btrieve Opens, one solution is to open the
DOS files before the Btrieve files. Otherwise, you could increase the number of handles available
to the application at compile time. The process of increasing the number of open files to more
than the default 20 varies depending on which compiler you use.
XQLStatus Function Call & Microsoft BASIC PDS 7.x (NetWare SQL v3.0)
The XQLStatus function call provides information about the last SQL statement executed.
The call requires three parameters with the following options:
CALL XQLSTATUS(iStatus%,
iCursorID%,
iOption%,
sStatBuf$)
where:
- iOption = 0 indicates that the Status Buffer must be at least eight-bytes long or
two four-byte integers. On certain SQL statements (SELECT, UPDATE, DELETE or INSERT),
NetWare SQL will return the number of records selected in the first four bytes followed by a
reject count in the next four bytes, otherwise, it will return a zero for both values.
- iOption = 1 requests more detailed information about a non-zero status code returned
on a previous SQL call. The status buffer must be at least thirty bytes long.
If option 0 is used, set up this status buffer by creating a structure containing two LONG
variables types. With Microsoft BASIC PDS 7.X, this structure is created using the TYPE and
END TYPE statements:
TYPE StatBuffer
SelectCount AS Long
RejectCount AS Long
END TYPE
DIM sStatBuf As StatBuffer
However, if this structure is passed in the XQLStatus call using the appropriate calling
convention (as specified by the NWSQLBA7.OBJ interface), a status 0 (Successful) is returned
on the call, but no values are returned in the status buffer.
User-defined TYPE structures cannot be defined and passed as the status buffer parameter
using the NWSQLBA7.OBJ interface. All the assembly level calls associated with this parameter
are string operations. Therefore, an empty eight-byte variable-length string must be defined for
the status buffer parameter. Upon a successful return code, this string variable can be parsed to
extract the appropriate integer values. The code segment in Figure 7 demonstrates this procedure.
FIGURE 7: Parsing sting variables to extract integer values
iOption% = 0
sStatBuf$ = SPACE$(8)
CALL XQLStatus (iStatus%, iCursorID%, iOption, sStatBuf$)
IF iStatus% = 0 THEN
PRINT "XQLStatus Successfull!"
ELSE
PRINT "Error in XQLStatus. Status = "; iStatus%
END IF
SelectCount& = CVL(MID$(sStatBuf$,1,4))
RejectCount& = CVL(MID$(sStatBuf$,5,4))
End of Figure 7
Handle Usage with User Rights & XQL Load Errors (XQL for DOS v2.x)
When loading XQL for DOS (XQL.EXE, XQLO.EXE, XQLP.EXE, or XQLPO.EXE), a
"TAnnnnnn.SHR" (where "nnnnnn" is a random number) file is created in the current working
directory. XQL uses this file to manage session information. If a user does not have Create rights
in the current working directory, a "File Initialization Error" will be returned by XQL and it will
fail to load since it cannot create this .SHR file.
Additionally, if a user has Create rights in the directory, but does not have Write rights, XQL
will load successfully and the .SHR file will be created, but any subsequent attempt to login to an
XQL dictionary will return a Btrieve status 94 (Permission Error). This error results from XQL
being unable to write to the .SHR file.
Finally, if the user has Create and Write rights, but does not have Delete rights, XQL will load
and applications will run, but when XQL is unloaded, the existing .SHR files in the current
working directory will not be deleted. The undeleted files will not cause any harm, except they
will stay in the directory taking up space until they are cleared out by a user with Delete rights in
that directory.
To ensure that XQL for DOS loads and runs properly, the user should have Create, Write and
Delete rights in the current working directory.
BSPXCOM & SPX Sessions (NetWare Btrieve (NLM) v5.x & v6.x)
BSPXCOM.NLM appears to hang after running out of sessions if users continuously try to
obtain an SPX session with Btrieve after exceeding the limit. The workstation receives either a
status 95 (Session No Longer Valid) or a status 91 (Server Error). This situation occurs in both
the NetWare Btrieve v5.x and NetWare Btrieve v6.0 environments. Once BSPXCOM.NLM
hangs, Btrieve must be unloaded and reloaded.
To avoid this situation, apply the NetWare patch, SPXFIX1.NLM which is available on NetWire
with the NetWare operating system patches (LIB 5, filename 311PT9.ZIP).
NetBIOS Broadcast Parameter Settings (NetWare System Calls for DOS v1.0)
When attempting to send data to an invalid or non-existent username with the NetBIOS
INTERNET parameter set to "ON," the NetBIOS function SendDataGram() takes a long time to
resolve the invalid or non-existent user name.
NetBIOS attempts to resolve this invalid or non-existent user name by broadcasting a name
resolution packet. It continues broadcasting until broadcasting time (in timer ticks) is equal to the
NetBIOS BROADCAST COUNT multiplied by the NetBIOS BROADCAST DELAY. These
two parameters are located in SHELL.CFG or NET.CFG, depending on the configuration of the
workstation that is calling SendDataGram().
To decrease the delay time, set the parameters to a lower value. Doing so decreases the resolution
time, but the call will not resolve names that are valid and require more resolution time than
allowed for by the parameters setting.
Renaming NetWare Subdirectories (NetWare System Calls for DOS v1.0)
DOS allows a subdirectory to be renamed even when a full path is specified in the
destination subdirectory name. NetWare, however, does not support this capability. For example:
DOS rename command:
\SUBDIR1\OLDNAME \SUBDIR\NEWNAME
NetWare rename command:
\SUBDIR1\OLDNAME NEWNAME
DOS also supports the syntax supported by NetWare.
Set Spool Flags Call Fails (NetWare System Calls for DOS v1.0)
The Set Spool Flags call (E0h(02h)) used to set the form number fails while sending a job
to a print queue. This failure can be verified through PCONSOLE. The form number remains set
to zero. Set Spool Flags fails to set the form number with the NetWare shell v3.26, but performs
properly under v3.22.
Currently, the only workaround is to use the older version of the shell (version 3.22).
NetWare SQL NLM Fails to Load (NetWare SQL v3.0)
If you use the NSSTART.NCF file to load the NetWare SQL v3.0 NLMs, the console may
display the following messages:
Loader cannot find public symbol:
NSDBNamesList
Loader cannot find public symbol:
NSAdvertiseDBNames
Loader cannot find public symbol:
NSSRBProcess
Loader cannot find public symbol:
NSSBTBGetStats
Loader cannot find public symbol:
NSResetClient
These messages may be followed by additional messages about resources not being released. The
end result is that NetWare SQL fails to load.
If you use the BSTART.NCF file to load the BTRIEVE NLMs and then run the NSSTART.NCF
file, the same messages appear. If you then attempt to load the NWSQL.NLM manually (by
typing LOAD NWSQL at the server console prompt), the next message displayed on the console
pinpoints the real problem:
NetWare SQL: Unable to open database names configuration file.
This message is displayed whenever NetWare SQL cannot open the DBNAMES.CFG file, which
is located in the SYS:SYSTEM directory. This file has probably been damaged in some way.
Rename or delete this file, and then try to load the NLMs again with the NSSTART command.
When NetWare SQL is loading, if it cannot find the DBNAMES.CFG file, it automatically
creates a new one.
Remember, if there were named databases defined in the damaged or corrupted DBNAMES.CFG
file, they must each be redefined in the new file using the NetWare SQL Setup Utility
(NDBSETUP.NLM).
Fast Answers to Common Questions
(The database Qs and As in this month's "Nibbles and Bits" segment were provided by
Novell's European Support Center in D sseldorf.)
NetWare
Q - Why do I run out of file handles when I have set "Files=255" in my
CONFIG.SYS and "File Handles=255" in my network configuration?
A - There can only be a total of 254 file handles (less than 255) for both DOS and
NetWare combined. If you set DOS Files too high, NetWare cannot set up enough file handles
for network files. Make sure that the total of DOS Files added to NetWare File Handles is
always less than 255.
NetWare C Interface for DOS
Q - Why does AllocTemporaryDirectoryHandle() fail when I try to use a temporary
drive letter apostrophe (')?
A - The documentation incorrectly displays the drive letter of handle 31 as an
apostrophe ('). The correct drive letter for this handle is a backwards apostrophe, or grave accent
(`).
Q - Why do my NetWare C Interface API calls return incorrect results or fail to work at all
when I use a temporary directory handle?
A - Some of the temporary directory handles do not function correctly. Temporary directory
handle 26 ([) gets deallocated by several API calls and temporary directory handle 27 (\)
performs operations relative to the root directory even if the handle was defined in a
subdirectory. Handles 28 (]) through 31 (`) work properly.
Q - When I call ScanEntryForTrustee() to return the assigned trustees for the root directory of
a volume, NetWare returns a status 156, 0x9C. What should I do?
A - The CONVHNDL.C function, called by ScanEntryForTrustee() and other functions,
contains a typographical error. To correct it, open CONVHNDL.C (under \SOURCE \CLIENT),
find line 120 and replace the single quotation marks with double quotation marks. as shown
below.
Before:
strcpy ( newDirPath, '' );
After:
strcpy ( newDirPath, "" );
Then, recompile CONVHNDL.C and replace it in the NIT library.
NetWare C Interface for Windows
Q - Normally, I can load and run ten Windows applications. However, if I load my
NetWare C Interface for Windows application first (or any app that uses NWIPXSPX.DLL), I
am only able to load two of the Windows applications. What should I do?
A - Try adding the statement "load=NWIPXSPX.DLL" to the WIN.INI file. Doing so
will free up more low memory.
Btrieve
Q - German umlauts are not displayed correctly with the version of BTRTOOLS.EXE
that comes with Btrieve for Windows v5.10. What should I do?
A - The ASCII characters for umlauts belong to the extended (unstandardized) ASCII
set defined by IBM for their PC line. Microsoft Windows uses a different ASCII extended
character set. Choose the appropriate Windows Font that matches the IBM ASCII set (Font
"Terminal").
Q - When I run the NetWare Btrieve v5.15 NLM with some applications on NetWare
v3.11, retrieved Btrieve data is incorrect (but not corrupted). It appears, as if the wrong records
are being accessed intermittently. What should I do?
A - To ensure that Btrieve data is retrieved correctly:
- Use the most current version of the NetWare Shell (IPX v3.10, NETX v3.22 or
NETX v3.26).
- In addition to patching the NetWare Btrieve NLM, make sure that you are running the
latest version of BREQUEST.EXE (v6.0).
- Check the page size of your Btrieve data files. NetWare sometimes mishandles pages that
are not evenly divisible into 4K. Although Btrieve allows you to define the page size that you
want, use only the page sizes of 512K, 1024K, 2048K or 4096K. This situation has been resolved
by the NetWare patch ASNCROFX.NLM.
NetWare SQL/XQL
Q - After using the XCONVERT command to store/retrieve data in ASCII format,
some operations return status 330 (Invalid Data Format). What should I do?
A - Date and time are stored in a format defined by the format statement (e.g.
European format). However, they are retrieved in American format. To resolve the status:
- Store date and time in American format, or
- Upgrade to NetWare SQL v3.0
Q - When using security features in NetWare SQL (XQL v2.11) only one user can
login to the data base. Why and what should I do?
A - This limitation is specific to XQLP v2.01. Upgrade to XQLP v2.11.
Novell Education offers several new and updated courses for developers who use Novell's
development & database tools, including NetWare SQL, Btrieve, Xtrieve PLUS, and the
NetWare Client APIs.
- 904: Btrieve: An Overview
- This new course provides a general overview of NetWare Btrieve v6.x and its new
features. It covers file structures, indexing, data integrity, record and file locking, caching,
operating modes, segmented keys, backward compatibility and utilities.
- 905: Programming with Btrieve
- This course has been enhanced to cover all Btrieve operations & environments, including
COBOL. It provides a complete introduction to Novell's server-based record manager. 50% of
class time is spent in programming workshops. Working knowledge of C, BASIC, Pascal, or
COBOL required. Prerequisite: 904: Btrieve: An Overview
- 907: Xtrieve PLUS
- This course has been updated to include new features introduced with NetWare SQL v3.0.
It teaches developers to use Xtrieve PLUS as a Btrieve or NetWare SQL programming utility.
Trains users of Btrieve- or NetWare SQL-based database applications to work effectively with
this menu driven utility.
- 911: NetWare Database Administrator
- This new course gives a complete, hands-on look at installing and configuring NetWare
SQL and NetWare Btrieve. It covers the basics of ANSI Standard Structured Query Language
(SQL), focusing on NetWare SQL and key database features like security, referential integrity
(RI), database design, data normalization and performance.
- 912: Programming with NetWare SQL
- This new course is designed for developers and experienced network and database
administrators who will be developing NetWare SQL applications or enhancing existing Btrieve
applications with NetWare SQL. It provides an in-depth look at the functionality of NetWare
SQL and discusses optimizing database systems for development of efficient applications using
Novell database tools.
- 930: Developing NetWare Loadable Modules (NLMs)
- This course introduces C programmers to server-based application development in the
32-bit NetWare 3.x environment. It covers basic concepts for writing server-based C applications
that access the NetWare 3.x C library (CLib). Requires working knowledge of the C language.
- 940: NetWare Programming: Basic Services
- This new lab-oriented class (40 percent lab work) introduces NetWare programming
concepts. It covers topics such as bindery services, file system services, print services, queue
management, connection and file-server services, and accounting and synchronization services.
This class requires knowledge of the C programming language.
- 945: NetWare Programming: Protocol Support
- This new class covers protocol support features. It also discusses network programming
concepts and techniques for developing client-side applications, including Service Advertising
Protocol (SAP) IPX/SPX, diagnostics, NetBIOS, TLI, and Named Pipes. This class requires
strong knowledge of the C programming language.
To obtain information on pricing, location, scheduling, & course content for classes held in the
US, call 1-800-233-3382, 1-801-429-5508 or 1-800-NETWARE. Customers outside of the US
should call 1-801-429-5508. For information on availability, location, and prices of classes
outside of the US, contact your local Novell office.
(Developer Trivia)
Test your developing skills with the development products by taking our Fun & Facts quiz. (See
below for answers.)
1. How large is an OS/2 SPX header?
A. 24 bytes
B. 36 bytes
C. 42 bytes
2. Under DOS, SPX uses Event Service Routines to perform certain requests when
interuppted. Under OS/2, this is not allowed, so it uses semaphores instead.
A. True
B. False
3. To use IPX under OS/2, you must supply an Asynchronous Event Scheduler.
A. True
B. False
4. To use Named Pipes, you must have a NetWare file server present.
A. True
B. False
5. Continous operations can be performed on Btrieve files with owner names without
specifying the owner.
A. True
B. False
6. How long can a stored SQL statement's name be?
A. 28 bytes
B. 30 bytes
C. 56 bytes
7. What special character does the DAL engine use to indicate that the field name contains
blanks?
A. "@"
B. "&"
C. "%"
8. What other Novell products use Btrieve as a record manager?
A. NetWare for SAA
B. LANtern
C. NetWare Management System
D. All of the above
Fun & Facts Answers
1. C
2. A
3. B
4. B
5. A
6. B
7. A
8. D
Developer Support
Developers in the U.S. and Canada may contact Novell Developer Support via telephone, fax,
BBS or electronic mail via CompuServe, MHS or the Internet.
Voice
For both presales and postsales support, call Novell Developer Support between 8:00 a.m. and
5:00 p.m. Mountain Time at 1-801-429-5588. Many calls to Novell Developer Support are
passed to a software support engineer immediately. Calls to Novell Developer Support generally
will be acknowledged or answered within four hours.
Fax
If you prefer, you may contact Novell Developer Support via fax at 1-801-429-2990. Faxed
questions are acknowledged or answered within 24 hours.
Developer BBS
If you do not have access to either CompuServe or the Internet, send test cases to our BBS. Set
your communication software to N-8-1 and call 1-801-429-5836.
E-mail: CompuServe
Post your messages in the appropriate section addressed to Novell at 76701,171. These messages
will receive a response within 24 hours.
E-mail: MHS
You may direct your questions and comments to Novell Developer Support via Novell's Message
Handling Service E-mail facility. Address your messages to devsup@novell. These messages
will receive a response within 24 hours.
E-mail: Internet (SMTP)
An alternative method of contacting Novell Developer Support is through the Internet E-mail
system. Send your messages to devsup@novell.com. These messages will receive a response
within 24 hours.
NetWire on CompuServe
Novell's NetWire forum is open to all registered CompuServe subscribers. Through the
NDEVSUP forum, professional developers writing applications with Novell development tools
can gain access to information specific to Novell development. Support, patches, periodicals and
product information, as well as information on all of the programs and services provided for
Novell developers are accessible through this forum. Post your messages in the appropriate
section addressed to Novell at 76701,171. Technical questions will be acknowledged or
answered by Novell Developer Support within 24 hours.
Novell Products and SDKs
Novell products on the "Currently Shipping Developer Products" list (see page 15 of this
issue), including the Red Box Products, are available to Novell Professional Developer's
Program members. Call 1-800-RED-WORD (1-800-733-9673) or 1-303-894-4135 to order these
products or to receive additional information. To order other Red Box Products not listed,
contact your l products may post
pre-sales product information questions on all Novell SDKs.
E-mail: MHS or Internet (SMTP)
You may direct your questions and commentsocal Novell office or Novell Authorized Reseller.
Novell Labs
For information on Novell Labs development tools, education classes and product certification,
in the U.S. and Canada call 1-800-453-1267 ext. 5544 or 1-801-429-5544, or call your local
Novell office (see back cover of this issue).
Novell Developer Relations
Novell Professional Developers or those wishing to become members may contact Novell
Developer Relations via telephone, fax, or electronic mail via Compuserve, MHS or the Internet.
Voice
For general information or questions on Novell Developer Relations programs, in the U.S.
or Canada call 1-800-RED-WORD (1-800-733-9673). All others call 1-801-429-5281.
Fax
If you prefer, you may contact Novell Developer Relations via fax at 1-801-429-7207.
NetWire on CompuServe
Novell's NetWire forum is open to all registered Compuserve subscribers. Through the
NDEVREL forum, Novell Professional Developer's Program-related issues or general questions
may be posted. Through the NDEVINFO forum, customers who do not have to Novell Developer Relations via Novell's
Message Handling Service E-mail facility. Address your messages to devprog@novell.com. Use
the same address when going through the Internet E-mail system.
Publisher: Mad Poarch
Editor: Kirk Humphries
Design: Creative Services, Provo
Contributors: Gaurang Amin,
Linda Anderson,
Vitek Boruvka,
Laura Heater,
Gerald Herbel,
Ken Lowrie,
Rudy McNeese,
Clint McVey,
Chris Ojeda,
Matt Pinsonneault,
Bill Prentice,
Bob Quinlan,
Drue Reeves,
Wolfgang Schreiber,
Mike Shoemaker,
Michael A. Spano,
John E. Stewart,
Brenda Wallace
Special thanks to the Developer Support, Development, Developer Relations, Product
Marketing, and Marketing Communications staff who contributed time and valuable input.
Novell, the N design, NetWare, Btrieve, XQL, LAN WorkPlace and LANalyzer are
registered trademarks; NetWare Loadable Module (NLM), NetWare Global Messaging, NetWare
System Calls for DOS, NetWare Runtime, NetWare SQL, NetWare Btrieve, NetWare C
Interface for DOS, NetWare System Interface Technical Overview, NetWare RPC, NetWare
RPC 386, NetWare LU6.2, Report Executive, NetWare MHS, NetWare Asynchronous
Communication Services (NACS), NetWare Management System, Professional Development
Series, NetWare 3270 LAN Workstation, LANtern and Xtrieve PLUS 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, Macintosh and AppleTalk are registered trademarks of Apple
Computer, Inc. CompuServe is a registered trademark of CompuServe Corporation. NFS is a
registered trademark of Sun Microsystems, Inc.
(c) 1992 Novell, Inc. All rights reserved.
Professional Development Series
BULLETS
DECEMBER 1992
|