*********************************************
*********************************************
Professional Development Series
B  U  L  L  E  T  S
*********************************************
June 1992
Volume 4, Number 6
*********************************************
*********************************************


*********************************************
*********************************************
MAD'S COLUMN
*********************************************
*********************************************

Hello and welcome to the June 1992 issue of Bullets!

The First Article Customer Inspection (FACI) is the process through
which all Novell products must successfully pass before they are
shipped to customers. For example, with NetWare SQL 3.0 (shipping
since May 26, 1992), a certain number of copies of the software
were built and then the assembly process was halted. One copy was
sent to each support site where the support person responsible for
monitoring the product through development stages received the
shrink-wrapped product.

Both Austin and Walnut Creek support personnel performed the
NetWare SQL v3.0 FACI. The Austin support team installed each
version of NetWare SQL v3.0 on the current operating system, ran
preliminary tests, and checked diskette contents, labeling,
documentation, licensing, etc. Simultaneously, Walnut Creek
personnel performed the same process for the DAL Server component
of NetWare SQL v3.0. After both teams approved the product, Novell
Operations was notified to start the assembly process.

The last minute Service/Support FACI inspection assures us that the
product is ready to go out the door and ensures the quality of the
Novell development and database products we ship to you. It's just
another way that Novell Support/ Services supports you, the Novell
developer.

Happy_Programming!

Mad Poarch
Director
Developer Support/Service



*********************************************
*********************************************
ARTICLES:
Continuous Operations & NetWare Btrieve v6.0
*********************************************
*********************************************

NetWare Btrieve v6.0 is a core component of NetWare SQL v3.0, the
latest version of Novell's relational data access system for
NetWare v3.11. In the March 1992 issue of Bullets, a special
supplement on NetWare SQL v3.0 briefly mentioned the enhancements
to the product. One of the new features of the NetWare Btrieve v6.0
engine, Continuous Operations, allows you to back up Btrieve files
while they are in use by Btrieve or NetWare SQL applications. This
article will discuss the new design in more detail and explain how
to implement Continuous Operations to provide uninterrupted access
to Btrieve files, even during backups.

In the past, Btrieve users were unable to back up Btrieve databases
while running applications because, if Btrieve files were in use
during a backup, a file (or set of files) could be in an
inconsistent state when the file was backed up. Backups do not
occur instantaneously; they take time, so one file could be backed
up, then a change could be made to a group of files before the
other files were backed up. The backup would then be useless since
the files would be out of sync.

Versions of Btrieve prior to v6.0 used pre-image files to record
changes being made to corresponding Btrieve files. To maintain
pre-v6.0 Btrieve file consistency, the pre-image files also would
have had to be backed up. Then, after restoring the database, the
pre-image files could be used to restore the Btrieve files to their
original state (i.e., the state they were in before the changes
that occurred while the backup was being performed).

Novell also recommended that files created with earlier versions
of Btrieve should always be flagged Non-Sharable to the operating
system. This flag prevented file corruption by allowing only one
entity (such as the NetWare Btrieve NLM) to access a Btrieve file
at a time. This precaution also prevented software from backing up
Btrieve files whenever an application was accessing them. The
operating system would return a "sharing" error and the backup
would fail.

Each of these issues is addressed in NetWare Btrieve v6.0. Some
understanding of the new design is required before discussing how
to implement these online backups using Continuous Operations.


Shadow Pages & PATs

Versions of Btrieve prior to v6.0 used pre-image files extensively;
any change made to a Btrieve file required the creation of a
pre-image file. The NetWare Btrieve v6.0 file structure has been
altered to eliminate the need for pre-image files. The new design
uses a technique called shadow paging and a structure called a Page
Allocation Table (PAT). With shadow paging, each page involved in
write operations is duplicated and any changes made to the file are
written to the duplicate copy. In the event of a system failure,
recovery is accomplished by invalidating the duplicate copy of all
pages. If a change is completed successfully, the altered copy of
the page becomes "current." 

The PAT structure is integral to this file management scheme. PAT
pages keep a record of which physical pages are copies, and which
copies are "current" at any given time. This design maintains
Btrieve files in a consistent state and data integrity is managed
within the file itself, not in a pre-image file.


Continuous Operations

When Btrieve files are placed in Continuous Operation mode, NetWare
Btrieve immediately creates a "DELTA" file for each Btrieve file.
This DELTA file is given the same name as the Btrieve file except
that it has a ".^^^" extension. So, if the file "patients.btr" was
placed in Continuous Operation mode, then the resulting DELTA file
would be named "patients.^^^."

Next, if the Btrieve file is not already open (for some
application), NetWare Btrieve opens it in "Read-Only, Sharable"
mode, so that the file can be accessed by a Btrieve application
while it is in Continuous Operation mode. If the Btrieve file is
already open, the open mode for the Btrieve file is switched to
"Read-Only, Sharable." Backup software can then begin to back up
all Btrieve files that are in Continuous Operation mode.

While files are in Continuous Operation mode, NetWare Btrieve uses
the DELTA files mentioned above to record all changes made to
Btrieve files. If a user accesses Btrieve files while they are open
in Continuous Operation mode, NetWare Btrieve v6.0 writes all user
modifications to the DELTA files. DELTA files are NetWare sparse
files, and their sizes (as seen in a DIR command) are usually be
larger than the space they occupy on disk.

Because NetWare Btrieve writes all modifications to DELTA files,
the original Btrieve files can be kept in a consistent state while
the file is in Continuous Operations mode. Btrieve v6.0 files can
then be backed up without the consistency problems that would arise
with files created with previous versions.

After a backup is completed, the files can be removed from
Continuous Operation mode. When NetWare Btrieve v6.0 receives a
request to remove files from Continuous Operation mode, it:

*    Begins a TTS transaction,
*    Transfers all changes recorded in all DELTA files to the
     Btrieve files,
*    Deletes the DELTA files, and
*    Ends the TTS transaction.

TTS transactions are used to ensure that either each of these steps
are executed or none are executed. Because this is when NetWare
Btrieve actually writes to the Btrieve files, it is very important
to keep the files in sync.


Implementing Continuous Operations using BUTIL and NSUTIL

BUTIL and NSUTIL are two utilities included with NetWare SQL v3.0
which can be used to activate Continuous Operations. BUTIL and
NSUTIL are both NetWare Loadable Modules (NLMs) and can be used at
the NetWare server console.

If you want to place a single Btrieve file in Continuous Operation
mode, you can use the following command:

:load butil -startbu Btrfilename

In this command, "startbu" stands for "start backup" and
"Btrfilename" refers to the fully qualified path and filename of
the Btrieve file, including the volume name. So, if "test1.btr"
were a file in the "dir1" directory off the root level of the SYS
volume, the command would be:

:load butil -startbu sys:dir1\test1.btr

If you wish to place a group of Btrieve files in Continuous
Operation mode, list each filename in an ASCII file, and issue the
following command at your server console:

:load butil -startbu @ASCIIfilename

In this command, "ASCIIfilename" refers to the complete path and
name of the ASCII file.

To remove Btrieve files from Continuous Operation mode, use one of
the following commands:

:load butil -endbu Btrfilename
or 
:load butil -endbu @ASCIIfilename

where "endbu" stands for "end backup."

NetWare SQL v3.0 also includes support for named databases. NSUTIL
uses this feature to implement Continuous Operations. The named
database feature allows a user to link a name with a particular
database, so that operations can be performed on the database
without specifying the location of the data dictionary and each
data file.

The following command will place all files that are part of the
"Dbname" database into Continuous Operation mode:

:load nsutil -startbu dbname

Because of the way named databases are implemented, "dbname" does
not have to contain a path pointing to the location of the
database; only the name of the database is required.

If you want to place multiple named databases in Continuous
Operation mode, use the following command:

:load nsutil -startbu @ASCIIfilename

where "ASCIIfilename" is the complete path and name of the ASCII
file that lists the named databases.

To remove the databases from Continuous Operation mode, use one of
the following commands:

:load nsutil -endbu dbname
or 
:load nsutil -endbu @ASCIIfilename


Implementing Continuous Operations Using a TSA

NetWare SQL v3.0 includes a Target Service Agent (TSA) that allows
you to use any backup utility that complies with Novell's SMS
(Storage Management Services) architecture to backup named
databases. This component of NetWare SQL v3.0 is called TSA-NWS.NLM
and it uses TSA.NLM (provided with NetWare 3.11) to communicate
with the backup utility. TSA.NLM and TSA-NWS.NLM are designed to
be loaded at the target server (the server where the databases to
be backed up reside). The backup utility should be loaded at the
host server (the server where the backup device resides).

TSA-NWS allows the user to specify the names of the databases that
are to be backed up. These databases are then individually placed
in Continuous Operation mode, backed up, and then removed from
Continuous Operation mode. Additional documentation is included in
the NetWare SQL Installation and Operation manual. This method
cannot be used to back up individual Btrieve files.


Additional Tips

*    Placing files in and removing files from Continuous Operation
     mode is an atomic process; either all of the files specified
     or none of the files specified are effected. If, for any
     reason, NetWare Btrieve encounters an error in either of these
     mode change procedures, it returns a status 88 (Incompatible
     Mode Error) at the server console.

*    Do not delete DELTA files. These files contain all changes
     made to the Btrieve files since they were placed in Continuous
     Operation mode.

*    Do not back up the DELTA files. If this occurs and the DELTA
     files are later restored with the backed up Btrieve files,
     then any subsequent access to the associated Btrieve files
     will make NetWare Btrieve read the DELTA files first, and
     "roll-in" the changes.

*    If Btrieve files have been assigned Btrieve owner names,
     BUTIL, NSUTIL, and TSA-NWS can still perform their Continuous
     Operation functions without the owner names being specified.
     (This is not considered to be a security violation since these
     functions can only be performed at the server console or
     through RCONSOLE, and this implies that the user has
     SUPERVISOR rights on the file server's resources.)

*    As with previous versions of NetWare Btrieve, all Btrieve
     files should have unique names. Files with different
     extensions are not considered unique. For example, if files
     named "file1.btr" and "file1.dat" were part of a set of files
     that were placed in Continuous Operation mode, NetWare Btrieve
     would create the DELTA file, "file1.^^^," for the first file
     it encountered. For the second file, however, NetWare Btrieve
     would detect that a DELTA file already existed and return a
     status 88 to the server console. As a result, neither file
     would be placed in Continuous Operation mode.

NetWare SQL v3.0 has been released only for the NetWare 3.11
environment. The NetWare SQL VAP for NetWare v2.x and XQL client
runtimes have not been upgraded to v3.0 at this time. NetWare
Btrieve v6.0 is currently available as a component of NetWare SQL
v3.0, not as a standalone product. For questions on availability
and future product releases, please contact 1-800-RED-WORD
(1-800-733-9673) or 1-512-794-1796. For technical and developer
support questions regarding any released Novell products, please
call 1-800-NETWARE (1-800-638-9273) or 801-429-5588.



*********************************************
*********************************************
TECHNICAL INSIGHTS:
DAL Syntax for Field Names
(NetWare SQL v3.0)
*********************************************
*********************************************

DAL, Apple Computer's Data Access Language, provides Macintosh
users with a standard method of accessing databases. When trying
to access field names that contain a blank from a DAL application,
DALSVR.NLM returns an "error in line 1" message if the syntax is
not correct. Even if the field in question is on line 20 of the
statement, the message will still read "error in line 1." This
error is returned even when you use the default blank replacement
character (^) in the field name. In addition, the blank can not be
set to a character other than the caret from a DAL client, and
tables with field names containing blanks cannot be created from
a DAL client.

A special syntax supported by DAL allows access to field names
containing blanks. Such fields must have a "@" character before and
after the field name and use the "^" in place of the blanks. For
example, the Appointments table, one of the sample data files
included with NetWare SQL v3.0, consists of the following fields:

ID                       Doctor
Appointment Date         Code
Appointment Time         Amount Paid
AM/PM                    Date Paid

The syntax required for a DAL client to access these fields would
be:

SELECT ID, @Appointment^Date@, @Appointment^Time@
  FROM Appointments;



*********************************************
*********************************************
TECHNICAL INSIGHTS:
SpxTerminateConnection( ) loses ECB
(NetWare v3.11)
*********************************************
*********************************************

An SPX bug in NetWare v3.11 can cause an Event Control Block (ECB)
to be used during a call to SpxTerminateConnection( ). In this
situation, the ECB is not returned to the listening pool and your
NLM eventually will run out of ECBs.

A patch called SPXFIX1.NLM, included with 311PT5.ZIP corrects this
situation. This file can be downloaded from NetWire (NOVLIB, LIB
1).



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Required Changes to ScanFileEntry API
(NetWare C Interface DOS v1.2)
*********************************************
*********************************************

ScanFileEntry( ) does not function properly with NetWare 2.x. The
API tries to make both NetWare 3.x- specific and NetWare
2.x-specific NetWare Core Protocol (NCP) calls. The NetWare 2.x NCP
was intended to be identical to the ScanFileInformation API,
although several problems are evident in the source.

To make ScanFileEntry( ) work properly, modify the file, SCFILE.C
(in the \CLIENT directory of the NetWare C Interface for DOS v1.2),
as shown in Figure 1.

*********************************************
Figure 1: Necessary Modifications to SCFILE.C

:
:
if (!isV3)
{
  /*- Send out the package for a NW 2.x request -*/

   :
   :
   memmove( &requestBuff[8], searchPath, searchLength );

   /* MODIFICATIONS required for NW 2.x NCP to function correctly
*/

   *(WORD *)&requestBuff[0] = searchLength + 6;
   *(WORD *)&replyBuff[0]   = 94;
   replyLength = 94;

   /**** end of changes *****/

   /*...send the NW 2.x NCP...*/
   ccode = _NCPConnRequest( serverConnID, 0x17, requestLength,
                            &requestBuff[0], replyLength,
&replyBuff[2] );
}
:
:
if( !ccode )
 if( !isV3 )
  {
  /*- Fill in fileEntry according to NW 2.x return values -*/

   /* changed LONG to WORD since NW 2.x only requires 2 bytes */


   fileEntry->attributes = *( (WORD *)&replyBuff[18] );
   :
   :
  }
 else
   :
   :

(End of Figure 1)
*********************************************



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Printing In Landscape Mode with SLATE
(Xtrieve PLUS for DOS v4.10)
*********************************************
*********************************************

You can use the SLATE utility to print in landscape mode in Xtrieve
PLUS for DOS v4.10. Start SLATE as follows:

SLATE xtrieve.pdb

If your workstation hangs, consult the README.DOC file on the
Xtrieve PLUS diskette which contains a section on the -V startup
parameter. When SLATE starts, the SLATE Main Menu screen will
appear.

In SLATE, select "Add/Edit Devices (Ptr Connections)" to enter the
SLATE Devices screen. Move the cursor down to an unused line and
enter an unused number (e.g. 4001). The SLATE Device Data screen
will then be displayed. Set the options to the values listed below
(use the down arrow key to move through the options):

*    Dev. Code: 4001 (already entered)
*    Function: LandScape (and any other desired definitions)
*    Ptr Mfg: use F9 key to see options and select one, e.g.
     Hewlett Packard
*    Ptr Type: use F9 key to see options and select one, (e.g.
     LaserJet II (LS) where "LS" indicates "LandScape")

You do not need to change the options between Ptr Type and Paper
Length.

*    Paper Length: change "11.00 inches" to "8.50 inches"
*    Paper Width: change "8.50 inches" to "11.00 inches"
*    Top Margin: must be at least "0.25 inches"
*    Bottom Margin: must be at least "0.25 inches"
*    Left Margin: any value
*    Right Margin: any value

After entering each of these definitions, press the F10 key to
return to the Device Data screen. Press F10 again to return to the
SLATE Main Menu and a third time to exit from the utility.

Next, start Xtrieve PLUS. Make sure the "Printers" switch in the
Main/ Configure/Switches menu is set to "ON." From the
Main/Configure/Print menu, select the "Database" option and enter
the location of XTRIEVE.PDB (which SLATE will use to define
landscape printing). Then, select the "Printer" option and choose
the proper printer (the Hewlett Packard III is not on this list
choose Hewlett Packard II (LS) instead). Finally, select "Device"
from the Main/Configure/Print menu and choose the "LandScape"
definition (this option will be the one that was used for the
Function option in SLATE). Xtrieve PLUS will now print in LandScape
mode.



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Modifications for UNLOADNO example
(Network C for NLMs v2.0(c))
*********************************************
*********************************************

UNLOADNO is an example program  supplied with v2.0(c) which
prevents NLMs from unloading. The example does not set and restore
the ThreadGroupID inside the CHECK function. (The example also
appeared in Bullets, March 1992, on page 7.)

To ensure that the program functions properly, save one NLM's
ThreadGroupID in a global variable or any place from which the
CHECK function can retrieve it. For example, create a global
variable called "MyThreadGroupID." Store the ThreadGroupID of the
main( ) thread in this global variable when the NLM starts. Inside
the CHECK function, set the ThreadGroupID to the value in
MyThreadGroupID. Before exiting, reset the ThreadGroupID to the
value it held before the CHECK function was called.



*********************************************
*********************************************
TECHNICAL INSIGHTS:
IPX/SPX "In-Use" Flag
(NetWare C Interface for DOS v1.2)
*********************************************
*********************************************

Sometimes, after a program performs an IPX or SPX send and then
polls the "in-use" flag, your workstation may appear to lock up
while the program waits for the flag to be set to zero. In this
case, the flag is never set to zero; it is set to 0xF8, which means
that the send was attempted while IPX was busy and the ECB has been
put on a queue for later processing.

This situation usually occurs with code that runs off the Timer
tick or some other interrupt. The code posts a "Listen" with an
Event Service Routine (ESR), which re-enables interrupts. Code that
runs off the Timer tick sends a packet and then waits for the "in-
use" flag to clear. If the timer triggers while the "Listen" code
is in the ESR , the send polls forever with the "in-use" flag set
to 0xF8. The machine appears to be locked up.

The simplest way to avoid this situation is to avoid polling the
"in-use" flag. Either use an ESR or leave the timer interrupt
unchecked and check it the next time around.



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Btrieve for OS/2 Prototypes
(Btrieve for OS/2 v5.10)
*********************************************
*********************************************

The local version of Btrieve for OS/2 v5.10 (BTRCALLS.DLL) works
with OS/2 v2.0, but OS/2 v2.0 developers writing 32-bit
applications or DLLs to call the 16-bit BTRCALLS.DLL must modify
the interface in order to alias the 32-bit pointer and integer
parameters. IBM C Set/2 provides macros you can use to make these
changes.

Calling the 16-bit Btrieve for OS/2 v5.10 DLL is a simple matter
of rewriting the BTRCALL() prototype. The current prototype for
OS/2 v1.X is shown in part A of Figure 2. The prototype for a
32-bit application or DLL is shown in part B. With IBM C Set/2,
everything else is handled by the compiler and linker. (Btrieve for
OS/2 applications written for OS/2 v1.X will run successfully under
OS/2 v2.0.)

*********************************************
Figure 2: BTRCALL prototypes for OS/2

Part A: Prototype for OS/2 v1.x

extern int APIENTRY BTRCALL (USHORT, PSZ, PSZ, PUSHORT, PSZ, CHAR,
UCHAR);

Part B: Prototype for a 32-bit application or DLL

extern SHORT APIENTRY16 BTRCALL (USHORT,
                                 UCHAR   _Seg16 *,
                                 UCHAR   _Seg16 *,
                                 USHORT  _Seg16 *,
                                 UCHAR   _Seg16 *,
                                 CHAR,
                                 UCHAR);

End of Figure 2
*********************************************



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Compatible Open Mode & NetWare Lite
(NetWare Lite v1.0)
*********************************************
*********************************************

Under NetWare 2.x and 3.x, only one station can open a file in
compatible mode, unless the file is flagged "Sharable." Under
NetWare Lite v1.0, however, files are treated as if they were
flagged "Sharable" and multiple stations can open the same file in
compatible mode. Other open modes, function as you would normally
expect. Under NetWare Lite, you cannot flag files "Non-Sharable."



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Print Server File Specifications
(NetWare v3.x)
*********************************************
*********************************************

Figure 3 contains the specifications for three files that are
created by a NetWare Print Server. The three files are: 

1)   PRINT.00X
2)   QUEUE.00X
3)   NOTIFY.00X.

*********************************************
Figure 3: Specifications for files created by NetWare Print Server


QUEUE.000

struct               /* Queue to be serviced structure */
{
  BYTE  name[48];    /* Name of queue  */
  BYTE  priority;    /* Priority of this queue */
} queue;


NOTIFY.000

struct               /* Object to be notified structure */
{
  BYTE  name[48];    /* Name of object */
  WORD  type;        /* Type of object */
        intial,      /* Time before first notice */
        repeat;      /* Time between notices */
} notify;


PRINT.000

struct
{
  char  name[48];        /* Name of printer */
  WORD  printerSubtype,  /* Subtype of printer */
        useInterrupts,   /* Use interrupts or polling? */
        irqNumber,       /* IRQ number for printer interrupt */
        serviceMode,     /* Queue service mode */
        buffersize,      /* Buffer size in K */
        baudRate,        /* Baud rate  (Serial only) */
        dataBits,        /* Data bits  (Serial only) */
        stopBits,        /* Stop bits  (Serial only) */
        parity,          /* Parity type (Serial only) */
        useXonXoff,      /* Use X-On/X-Off protocol? (Serial Only)
*/
        currentForm;     /* Currently mounted form */
} PCONFIG;

End of Figure 3
*********************************************

These files are located under the SYS:\SYSTEM\PRINTERSERVERID
directory of the Print Server. The exact extension depends on the
queue number in sequence. The files are simple flat files that
store data sequentially. 

Each printer will have a unique file, PRINT.XXX, that will contain
the printer name. One QUEUE.XXX file and a NOTIFY.XXX file will be
associated with each printer. For example: if PRINT.010 corresponds
to the HPLaser, associated with it will be a QUEUE.010, which
contains all the queues for that printer, as well as a NOTIFY.010
file, which will contain any objects to be notified. (If no
notification objects are selected, NOTIFY.XXX will not exist.)



*********************************************
*********************************************
TECHNICAL INSIGHTS:
NSUTIL.NLM Usage
(NetWare SQL v3.0)
*********************************************
*********************************************

When using the NSUTIL.NLM utility provided with NetWare SQL v3.0,
many of the commands require one or more filenames as parameters
or options. For example, the syntax for the BLOAD (bulk load)
option is:

LOAD NSUTIL -BLOAD
table sequential_file
<UNF | SDF | ASC | DIF> 
  [Options]

All file names must be specified with their volume:path. In
addition, the options that indicate a particular path (such as /D:
for the dictionary path and /F: for the data file location) also
must be specified with volume:path. If the volume is not included,
a status 91 - Server Error will be returned.
The following example would only be valid if it were entered on a
single command line:

:LOAD NSUTIL -BLOAD
Patients SYS:\DB\input.txt
SDF /D:SYS:\DB /F:SYS:\DB

When running NSUTIL at the server, the command line is limited to
80 characters, so there may not be enough room to type the entire
command with fully qualified path names. In this case, there are
two options: either put the entire command in a NetWare Command
File (NCF) or use an NSUTIL command file. 

To use a NCF file, create an ASCII file with a .NCF extension.
Place the entire command as it would be entered at the console on
a single line in this file. If the command is split over multiple
lines in the NCF file, various errors might occur, including a
status 12 (File Not Found). The line in the NCF file can be up to
130 characters long. If the entire command is more than 130
characters, an NSUTIL command file must be used, as described
below.

An NSUTIL command file is used by specifying an @FileName after the
LOAD NSUTIL command, either at the server console prompt or within
a NCF file. The command file name must be fully qualified,
including the volume and path name. For example, 

:LOAD NSUTIL @sys:\db\bload1.txt

The command line can consist of multiple lines, each up to 130
characters. The only restriction is that any one parameter must
reside entirely on a single line.

The first entry in the NSUTIL command file must be the command to
be performed. This syntax allows for the longer paths to be
specified for the various parameters. NSUTIL command files can be
used with the NLM and client versions (DOS and OS/2) of NSUTIL.

As a final note, BUTIL.NLM v6.0 (a Btrieve utility does NOT require
a volume name when specifying a file or path parameter. The SYS:
volume will be assumed. The volume only needs to be specified if
the file is on a different volume than SYS:. Also, if you do not
specify a path, the root of the SYS: volume is assumed. BUTIL also
supports the command file syntax.



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Validating Key Buffers with Btrieve for Windows & OS/2
(Btrieve for Windows v5.10)
(Btrieve for OS/2 v5.10)
*********************************************
*********************************************

The client version of Btrieve for Windows will validate pointers
when using the "tracefile= <filename>" line in the [Btrieve]
paragraph of WIN.INI. When using NetWare Btrieve and the requester
for Windows, setting "chkparms=yes" in the [BrequestDPMI] paragraph
will validate pointers. Client versions of Btrieve for OS/2 will
validate pointers when the environment variable, "BTRPARMSCHK," is
set equal to "YES."

Btrieve validates the pointer parameters passed in for read/write
access over certain ranges. If the pointers passed to Btrieve do
not have access to memory specified by the pointers, a status 1015
will be returned. If you are using the "tracefile=" method, Btrieve
for Windows will return "INVALID POINTER parameter #?" in your
tracefile, where "?" would be one to four referring to the position
block, data buffer, data buffer length, and key buffer
respectively.

The key buffer parameter is always evaluated for the maximum number
of bytes (255) regardless of what is specified in the key buffer
length parameter. So, to use pointer validation effectively,
allocate the key buffer parameter as a pointer to a block of 255
bytes.



*********************************************
*********************************************
TECHNICAL INSIGHTS:
Sessions & NetWare SQL
(NetWare SQL v3.0)
*********************************************
*********************************************

As stated in "Sessions and NetWare SQL" in Bullets (May 1992),
NetWare SQL v3.0 is stratified by session count. A session is
defined as a login to NetWare SQL. A connection is defined as a
login to the NetWare operating system.

On the RESOURCE USAGE screen in the NetWare SQL Monitor Utility
(NDBMON.NLM), several values are displayed indicating how many
NetWare SQL logins are active, what the peak login count has been,
and the maximum number of logins allowed. This maximum number is
determined by the session count of each copy of NetWare SQL. A
50-user system will have "50" displayed for the maximum number of
sessions. RESOURCE USAGE uses the word "session" when referring to
the number of NetWare SQL logins.

SPX sessions are displayed in the Communication Statistics screen
in NDBMON.NLM. This session count indicates the number of SPX
connections that NSSPXCOM has in use, not the number of logins to
NetWare SQL. If an OS/2 or Windows workstation runs multiple
NetWare SQL applications, there is one SPX session per workstation.

Figure 4 contains a table illustrating the relationship between
NetWare SQL and SPX sessions. You cannot configure NetWare SQL
sessions, which are based on the number of sessions purchased.
However, SPX sessions can be configured from NDBSETUP.NLM. The
option to configure the SPX sessions is "SET NETWARE SQL
CONFIGURATION."

*********************************************
Figure 4: Relationship between NetWare SQL & SPX sessions

                         Resource Usage      Comm. Statistics

OS/2 Workstation         3  Sessions         1 SPX Connection
3 NetWare SQL Apps.
Running

Windows Workstation      3  Sessions         1 SPX Connection
3 NetWare SQL Apps.
Running

DOS Workstation               1  Session     1 SPX Connection
1 NetWare SQL App.
Running 

TOTAL:                   7 Sessions          3 SPX Connections

End of Figure 4
*********************************************



*********************************************
*********************************************
NIBBLES & BITS
(Fast answers to common questions)
*********************************************
*********************************************

*********************************************
NetWare SQL

Q:   Once Referential Integrity (RI) has been defined on a NetWare
     SQL v3.0 database and referential constraints have been
     defined on the tables, is there an easy way to disable RI for
     that database?

A:   No, there is no quick way to to disable RI. Deleting
     RELATE.DDF will not disable RI because there will still be an
     entry in FILE.DDF and the table definitions will still contain
     referential constraints. Also, you cannot drop x$Relate from
     the dictionaries. To successfully disable RI, you must alter
     all table definitions.

*********************************************
Xtrieve PLUS

Q:   With Xtrieve PLUS v4.x, can I use the double quote (")
     character as part of a string constant?

A:   Since Xtrieve PLUS v4.x uses the double quote (") character
     to delimit string constants, you can not specify a constant
     containing a double quote. For example, a restriction such as
     'StringField CONTAINS <constant>' where the constant is a
     double quote (") character returns a status 298 (Mismatched
     Quotes) when the restriction is completed. You can, however,
     use single quotes in any string constant.

*********************************************
Btrieve

Q:   Can a supplemental index be created through Btrieve or NetWare
     SQL at the time that the Btrieve file is created?

A:   No. Btrieve ignores bit 7 of the key flags at create time, and
     this is the bit that designates an index as supplemental. As
     a result all indexes are created as permanent.

Q:   Does a user need create rights in the directory where a
     Btrieve file is stored, in order to open that file in
     accelerated mode? 

A:   Yes, create rights are necessary because, even in accelerated
     mode, Btrieve may create a pre-image file. For example, during
     an Insert (2), if an index does not allow duplicates and the
     record being inserted causes a duplicates error to be
     returned, any pages that have already been updated for the
     Insert would need to be rolled back. The pages to be rolled
     back would remain in cache until the cache is full and needs
     to be flushed, and the operation would not be completed.

Q:   When  I am attached to a lot of NetWare v3.11 servers (24),
     each running the NetWare Btrieve NLM v5.15,  I get a status
     38 (Transaction Control File I/O) even though each Btrieve NLM
     is configured for transactions. What should I do?

A:   Check the /s parameter (number of file servers) on Brequest
     to see if it is large enough. A higher setting may stop the
     status 38. 

*********************************************
NetWare C Interface for Windows

Q:   When I am running a DOS application from a Windows DOS box,
     can I make windowed DOS sessions display more than the usual
     25 lines? 

A:   Yes, you can make windowed DOS sessions display 50 lines by
     adding the line, "ScreenLines=50," to the [NonWindowsApp]
     section of your SYSTEM.INI file.

*********************************************
Network C for NLMs

Q:   If any of the API functions exported by PATCH311.NLM is used
     in another NLM, my linker issues unresolved linker errors.
     What should I do?

A:   There is no .IMP file associated with the APIs exported by
     PATCH311.NLM. Therfore, if any of these APIs are used in an
     NLM, make sure to import the appropriate symbol names in the
     .LNK file of the NLM. Otherwise, the linker will return
     unresolved linker errors. These symbols are resolved at load
     time.

Q:   From an NLM, how can I force a file write( ) to the disk?

A:   Use FEFlushWrite( ), or open the file with FEsopen( ) with the
     flagBits parameter set to FILE_WRITE_THROUGH_BIT. 

Q:   Which API returns the screen handles of all loaded NLMs?

A:   ScanScreens( ) (Available with PATCH311.NLM).

*********************************************
NetWare System Calls for DOS

Q:   The NetWare System Call, IPXGetInternetworkAddress( ), 
     returns invalid data in the ES:SI register, instead of
     returning the Internetwork Address. Why does this occur?

A:   The documentation for IPXGetInternetworkAddress (function 09)
     contains an error. It states that ES:SI register will point
     to the Internetwork Address on return from the function.
     However, ES:SI should also point to the reply buffer on entry
     to the call.

*********************************************
NetWare for SAA

Q:   When I run NetWare for SAA with NetWare v3.11 in an
     environment with heavy network traffic, the server sends
     system warning messages indicating that the Alloc Short Term
     Memory pool has reached its limit. What should I do?

A:   If this happens, increase the memory pool by increments of one
     MB until the system warnings no longer appear.



*********************************************
*********************************************
PATCH LISTINGS
*********************************************
*********************************************


*********************************************
Btrieve for DOS v5.10 Patches
*********************************************
For a description of patches 1 through 114, refer to earlier issues
of Bullets.

115. Btrieve (DOS, Windows, OS/2) If Btrieve is configured with no
     compression buffer, or with a compression buffer that is not
     large enough ( /u parameter ), the Step operations will
     incorrectly return a status 54 (Variable Page Error). This
     patch ensures that the correct return code, status 58
     (Compression Buffer Too Short) is returned.


*********************************************
NetWare Btrieve (VAP, NLM) v5.15 Patches
*********************************************
For a description of patches 1 through 52, refer to earlier issues
of Bullets.

53.  (BTRIEVE.NLM) Reading or updating a particular corrupted file
     caused an unrecoverable error but did not return a status
     code. This patch returns a status 19 in that case.

54.  (BTRIEVE.NLM) On a key-only file, if an autoincrement field
     does not begin at the first byte, the second insert with
     binary zero value in that field does not work and Btrieve
     returns a status 5 (Duplicate Key). This patch resolves the
     situation.

55.  (BTRIEVE.NLM) After adding two supplemental indexes and
     removing one of them, the other index can no longer be
     accessed. This patch ensures that the second index can still
     be accessed.

56.  (BTRIEVE.NLM) If you use BREQUEST.EXE v6.0 (included with
     NetWare SQL v3.0) and attempt to open a file in Read-only
     mode, and you only have Read rights in the file's directory,
     Btrieve will incorrectly deny the Open call and return status
     94 (Permission Error). This patch resolves the situation.

57.  (BTRIEVE.NLM) A Get Next Extended (36) operation following a
     GreaterThanOrEqual with Key-only bias (59) returns a status
     19 (Unrecoverable Error). This patch ensures that the Get Next
     Extended operation will complete successfully.

58.  (BTRIEVE.NLM, BSERVER.VAP) If you set up an extended step/get
     operation to only return record positions (NumOfFields = 0)
     and no record data, BTRIEVE.NLM will return a status 62
     (Incorrect Descriptor). The operation will work with
     BSERVER.VAP, but the VAP may return a status 22 if the data
     buffer is the exact length required to return the data. This
     patch corrects both situations and returns the record
     positions. 

59.  (BTRIEVE.NLM, BSERVER.VAP) If a workstation tries to update
     or delete a record which a second workstation has changed
     since the first workstation read that record, Btrieve returns
     a status 80 (Conflict). However, Btrieve incorrectly allows
     the Conflict condition to be cleared after the first
     workstation performs any of the following operations: Stat
     (15), Unlock (27), Set Owner (29), Clear Owner (30), Create
     Supplemental Index (31), or Drop Supplemental Index (32). This
     patch corrects the situation; the first workstation must
     reread the record before changing it.

60.  (BTRIEVE.NLM) When NetWare TTS, working on disk I/O, detects
     a hardware error, it dismounts the volume. Sometimes Btrieve
     does not detect this action, and as a result, hangs the
     server. This patch ensures that Btrieve detects when a volume
     is dismounted.

61.  (BTRIEVE.NLM, BSERVER.VAP) If an application updates a record
     and changes a Zstring or Lstring key (flagged with the NULL
     or MANUAL attribute) from NULL to non-NULL (or vice versa) by
     changing bytes beyond the end of the Zstring/Lstring from the
     null character to any other character (or vice versa), the
     index is not updated to reflect the change in the key. This
     patch ensures that the index is updated.

62.  (BTRIEVE.NLM) This patch corrects a situation in which, under
     very heavy use with many Open (0) and Close (1) operations on
     the same file by several different threads, a thread can enter
     an infinite loop.

63.  (BTRIEVE.NLM, BSERVER.VAP) If a client application receives
     a status 80 on an Update (3) operation because a second client
     has updated the record since the first client read it, and
     then the first client performs a Get Position (22) operation,
     an incorrect status 8 (Invalid Positioning) is returned. This
     patch ensures that a status 0 (Successful Operation) and a
     valid record address will be returned by the Get Position
     operation.


*********************************************
Xtrieve PLUS for DOS v4.10 Patches
*********************************************
For a description of patches 1 through 15, refer to earlier issues
of Bullets.

16.  This patch ensures that Xtrieve PLUS v4.10 always translates
     date values properly when you print a report to Lotus 1-2-3.



*********************************************
*********************************************
NOVELL EDUCATION
*********************************************
*********************************************

Novell Education offers classes for many of the database &
development products including Btrieve, XQL, NetWare SQL, Xtrieve
PLUS and the NetWare Client APIs. These classes are designed to
introduce participants to the powerful features of Novell's
development tools, database products, and NetWare services. Nearly
50% of class time is devoted to hands-on activities.

*********************************************

901 - Programming with NetWare Client APIs
920 - Programming with NetWare Communication Services

901 and 920 classes can be scheduled through a Novell Authorized
Education Center. Call 1-800-233-3382 or 801-429-5508 for more
information.

*********************************************

904 - Btrieve: An Overview

     Aug. 11        Sunnyvale, CA
     Sept. 15       Chicago, IL

*********************************************

905 - Programming with Btrieve

     Aug. 12-14          Sunnyvale, CA
     Sept. 16-18    Chicago, IL

*********************************************

907 - Xtrieve PLUS

     July 14-15          Dallas, TX
     Sept. 15-16    Washington, DC

*********************************************

930 - Developing NetWare Loadable Modules (NLMs)

     July 15-17          Washington, DC
     Sept. 15-17    Washington, DC

*********************************************


To register or obtain information on pricing, location and course
content for classes held in the US, call 1-800-233-3382,
1-801-429-5508 or 1-800-NETWARE. International customers should
call 1-801-429-5508. 

All courses are subject to cancellation or rescheduling within two
weeks of the scheduled date, depending on enrollment.

For information on availability, location, and prices of
international classes, contact your local Novell office.



*********************************************
*********************************************
FUN & FACTS
*********************************************
*********************************************

Test your "developing" skills by taking our Fun & Facts quiz. Have
fun and good luck! (See the end of this section for answers.)

1.   A reentrant NLM executes the _Prelude function the first time
     the NLM is loaded and does not execute it on subsequent loads.
     A.   True
     B.   False

2.   How many simultaneous Named Pipes connections does the OS/2
     Requester v1.3 support?
     A.   255
     B.   254
     C.   250

3.   The filter portion of a Btrieve Extended Get operation must
     be an index value. 
     A.   True
     B.   False

4.   What NLM is loaded to configure SPX parameters like "timeout,"
     and "retries?"
     A.   SPXCFG
     B.   SPXCON
     C.   SPXCONFG
     D.   INSTALL

5.   What socket number is used by NetBIOS packets?
     A.   0x451
     B.   0x452
     C.   0x453
     D.   0x455

6.   What is the sequence of keystrokes in Xtrieve PLUS to switch
     between Edit mode and Browse mode?
     A.   Alt-F7
     B.   Ctrl-F8
     C.   Ctrl-M
     D.   Alt-M

7.   Under NetWare 2.x, which API allows a VAP to accept a user
     response to an error condition?
     A.   DisplayError()
     B.   ConsoleError()
     C.   DoConsoleError()
     D.   VAPError()

8.   In the NetWare 2.x VAP environment, what is returned by an
     AllocateSegment call when the call is made in protected mode?
     A.   Fragment descriptor
     B.   Segment descriptor
     C.   Offset
     D.   Pointer to a function

9.   What is the default stack size in a NetWare Loadable Module?
     A.   1024 bytes
     B.   4096 bytes
     C.   8192 bytes
     D.   None

10.  What console command is used to view the protocols registered
     on your file server?
     A.   Secure Console
     B.   Protocol
     C.   Modules
     D.   Display

11.  What is the maximum possible size for a Btrieve file?
     A.   540 Megabytes
     B.   2 Gigabytes
     C.   4 Gigabytes

12.  In the NetWare environment, which IPC protocol does Named
     Pipes use?
     A.   NetBIOS
     B.   IPX
     C.   SPX
     D.   TCP/IP



*********************************************
*********************************************
FUN & FACTS ANSWERS
*********************************************
*********************************************

1.   A
2.   A
3.   B
4.   C
5.   D
6.   B
7.   C
8.   B
9.   C
10.  B
11.  C
12.  C



*********************************************
*********************************************
CURRENT VERSIONS OF NOVELL PRODUCTS
*********************************************
*********************************************

NetWare

     NetWare 3.x                             3.11
     NetWare 2.x                             2.2
     NetWare Lite                            1.0
     NetWare for VMS                         2.1

NetWare Services

     NetWare for Macintosh                   3.01
     NetWare NFS                             1.2
     NetWare FTAM                            1.2
     NetWare for SAA                         1.1
     NetWare RMS                             n/a
     NetWare NNS                             n/a

Communication Toolkits

     LAN WorkPlace Toolkit for DOS           4.01

NetWare System Interfaces

     NetWare C Interface for DOS             1.2
     NetWare System Calls for DOS            1.0
     NetWare System Interface
     Technical Overview                      1.2

Software Developer's Kits

     OS/2 Developer's Kit                    2.0
     NetWare C Interface for Windows         1.22
     NetWare C Interface for Macintosh       1.3
     NetWare Network Management Toolkit      1.0
     LAN WorkPlace Toolkit for OS/2          2.0
     Network C for NLMs                      2.0 c
     NetWare TIRPC for DOS and NLMs          1.0
     NetWare AppleTalk Interface for NLMs    1.0
     NetWare for SAA LU6.2 Tools             1.2
     NetWare 3270 Tools                      1.6

NetWare RPC

     NetWare RPC for DOS                     1.1
     NetWare RPC 386                         1.1

Compiler Toolkits

     Network C for DOS                       2.0

XQL

     XQL for DOS                             2.11
     XQL for OS/2                            2.11

NetWare SQL

     NetWare SQL (NLM)                       3.0
     NetWare SQL (VAP)                       2.11

Btrieve

     NetWare Btrieve (NLM)                   5.15
     NetWare Btrieve (VAP)                   5.15
     Btrieve for DOS                         5.10a
     Btrieve for OS/2                        5.10
     Btrieve for Windows                     5.10

Xtrieve PLUS

     Xtrieve PLUS for DOS                    4.10
     Xtrieve PLUS for OS/2                   4.01

Report Executive

     Report Executive for DOS                4.01a
     Report Executive for OS/2               4.01a

For a complete list of the Novell product line contact Novell
Austin or your local Novell Authorized dealer.



*********************************************
*********************************************
CURRENT REQUESTER VERSIONS
*********************************************
*********************************************

NetWare Btrieve v5.15

     Requester for DOS                       5.16
     Requester for OS/2                      5.17a
     Requester Interface for Windows 3.0     5.16

NetWare SQL                                  VAP       NLM

     Requester for DOS                       2.12a     3.0
     Requester for OS/2                      2.11      3.0
     Requester Interface for Windows 3.0     2.13      3.0

NetWare Shells and Requesters

     DOS Shell                                    3.26
     IPX (DOS)                                    3.10
     VIPX.386                                     1.10
     NetWare Requester for OS/2                   2.0
     NETWARE.DRV (Windows)                        1.03.7
     VNETWARE.386 (Windows)                       1.03.2



*********************************************
*********************************************
CONTACTING NOVELL AUSTIN
*********************************************
*********************************************

To obtain technical support, call 1-800-NETWARE (1-800-638-9273),
or 1-801-429-5588. Be prepared to give the support operator your
open incident reference number. Technical support questions may
also be sent by FAX to 1-512-794-1775. 

Many international distributors provide technical support. Please
contact your distributor or local Novell office (see list on back
cover) for more information on international support options.

Software patches may be obtained from the NetWire forum on
CompuServe (NOVLIB, LIB 7), or by contacting the Developer Support
Group and specifying the patches you need by product name.

Novell database and development products can be obtained through
Novell Authorized Resellers, or by calling 1-800-RED-WORD
(1-800-733-9673) or 1-512-794-1796.

Software Developer's Kits (SDKs) are available only through
Novell's Professional Developers' Program Call 1-800-RED-WORD
(1-800-733-9673) or 1-512-794-1796.

For more information on Novell's Professional Developers' Program
and Novell development products, call 1-800-RED-WORD
(1-800-733-9673), or 1-512-794-1796, FAX 1-512-794-1770, or contact
the nearest Novell office.


*********************************************
*********************************************
ACKNOWLEDGEMENTS
*********************************************
*********************************************

Publisher:     Mad Poarch
Editor:        Kirk R. Humphries
Design:        Creative Services, Provo

Contributors:  Linda Anderson
               Vitek Boruvka
               Michael Eisa
               David Harris
               Laura Heater
               Sudz Khawaja
               Ken Lowrie
               Rudy McNeese
               Paige Parker
               Randy Reddy
               John E. Stewart
               Aslam Tejani
               Brenda Wallace

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

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

*********************************************
Novell, the N design, NetWare, Btrieve, XQL and LAN WorkPlace are
registered trademarks, NetWare Lite, NetWare System Calls for DOS,
NetWare Loadable Module (NLM), NetWare SQL, NetWare Btrieve,
Xtrieve PLUS, NetWare C Interface for DOS, NetWare System Interface
Technical Overview, NetWare RPC, NetWare RPC 386, NetWare LU6.2,
Report Executive, and Professional Development Series (PDS) are
trademarks, and NetWire and Professional Developers' Program (PDP)
are servicemarks of Novell, Inc. Apple, Macintosh and AppleTalk are
registered trademarks of Apple Computer, Inc. CompuServe is
registered trademark of CompuServe Corporation. Microsoft is a
registered trademark, and Windows is a trademark of Microsoft, Inc.
IBM and OS/2 are registered trademarks, and NetBIOS and SAA are
trademarks of International Business Machines Corporation. Sun
Microsystems and NFS are registered trademarks of Sun Microsystems,
Inc. WATCOM is a trademark of WATCOM Systems, Inc.
*********************************************

Developer Support:
1-800-NETWARE (1-800-638-9273)
Tel. (801) 429-5588
Fax  (512) 794-1775

International Customers please contact your local Novell
authorized dealer or nearest Novell office.

*********************************************

Novell, Inc.
Corporate Headquarters
122 East 1700 South
P.O. Box 5900
Provo, Utah 84606
USA
Tel.  (801) 429-7000

*********************************************

Novell Latin America
890 Ross Drive
Sunnyvale, CA 94089
USA
Tel.  (408) 747-4000
FAX   (408) 747-4033

*********************************************

Novell Australia
Level 2
2 Help Street
Chatswood NSW 2067
Australia
Tel.  61 (2) 413-3077
FAX   61 (2) 413-3116

*********************************************

Novell Benelux
Excelsiorlaan 13
1930 Zaventem
Belgium
Tel.  32 (2) 725-02-00
FAX   32 (2) 725-03-11

*********************************************

Novell France
Tour Anjou
33, Quai De Dion-Bouton
92814 Puteaux Cedex
France
Tel.  33 (1) 47.75.09.09
FAX   33 (1) 47.78.94.72

*********************************************

Novell Germany
Willsttter Strasse 13
4000 Dsseldorf 11
Germany
Tel.  49 (211) 5973-0
FAX   49 (211) 5973-250

*********************************************

Novell Hong Kong
China Resources Bldg.
Room 4601-5, 46th Floor
26 Harbour Rd.
Wanchai, Hong Kong
Tel.  852 8272223
FAX   852 8276555

*********************************************

Novell Italy
Via San Vittore 40
20123 Milan
Italy
Tel.  39-2-4801 3554
FAX   39-2-4801 3594

*********************************************

Novell Japan
Toei Mishuku Bldg.3F
1-13-1 Mishuku
Setagaya-ku, Tokyo 154
Japan
Tel.  81 (3) 5481-1161
FAX   81 (3) 5481-1855

*********************************************

Novell Spain
Paseo Castellana, 40 bis
28046 Madrid
Spain
Tel.  34 (1) 577-4941
FAX   34 (1) 577-9053

*********************************************

Novell Sweden
Kottbyjatan 7
16475 Kista
Sweden
Tel.  46 (8)-7032350
FAX   46 (8)-7039434

*********************************************

Novell Switzerland
Bahnstrasse 102
8105 Regensdorf
Switzerland
Tel.  41 (1) 870-0650
FAX   41 (1) 870-0628

*********************************************

Novell United Kingdom
Avon House, Sweetwell Road
Bracknell, Berkshire
RG12 1HH
United Kingdom
Tel.  44 (344) 860 400
FAX   44 (344) 860 353

*********************************************
Professional Development Series
B  U  L  L  E  T  S
JUNE 1992
END OF FILE
*********************************************