JUNE 1992 VOLUME 4 NUMBER 6

INDEX

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

MAD'S COLUMN

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

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

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

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.

Implementing Continuous Operations using BUTIL and NSUTIL

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

     load butil -startbu Btrfilename

     load butil -startbu sys:dir1\test1.btr

     load butil -startbu @ASCIIfilename

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

     load butil -endbu Btrfilename

          or

     load butil -endbu @ASCIIfilename

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

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

     load nsutil -startbu @ASCIIfilename

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

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)

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

          SELECT ID, @Appointment^Date@, @Appointment^Time@

           FROM Appointments;

SpxTerminateConnection( ) loses ECB (NetWare v3.11)

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

Required Changes to ScanFileEntry API (NetWare C Interface DOS v1.2)

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)

Printing In Landscape Mode with SLATE (Xtrieve PLUS for DOS v4.10)

          SLATE xtrieve.pdb

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")

• 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

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.

Modifications for UNLOADNO example (Network C for NLMs v2.0(c))

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.

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

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.

Btrieve for OS/2 Prototypes (Btrieve for OS/2 v5.10)

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

Print Server File Specifications (NetWare v3.x)

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

                                                 

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

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.)

NSUTIL.NLM Usage (NetWare SQL v3.0)

          LOAD NSUTIL -BLOAD

          table sequential_file

           

          [Options]

     LOAD NSUTIL -BLOAD

          Patients SYS:\DB\input.txt

          SDF /D:SYS:\DB /F:SYS:\DB

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 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.

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

 Resource Usage Comm. Statistics

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

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

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

TOTAL: 7 Sessions 3 SPX Connections

End of Figure 4

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