> developer support home

APRIL 1993 VOLUME 5 NUMBER 4

INDEX


MAD'S COLUMN

Hello and welcome to the April 1993 issue of Bullets!

Recently, Novell began shipping NetWare 4.0, its next generation operating system designed for global enterprise networks. The new release represents the ninth generation of NetWare development.

NetWare 4.0 provides developers with the ability to deliver advanced network services, regardless of time, distance, location and network diversity. NetWare 4.0 allows developers to write applications that satisfy their customers' multiserver, multiplatform and multilingual needs, within the framework of a secure system that is easy to use, administer and manage.

To support NetWare 4.0, Novell is working closely with third-party developers to provide added capabilities through NetWare Loadable Modules (NLMs). NLMs that run on NetWare 4.0 will generally be divided into two categories. The first category is NetWare 3.11 NLMs that will be compatible with NetWare 4.0. The second category of NLMs will take advantage of the new NetWare 4.0 capabilities, such as NetWare 4.0 Directory Services.

Together, NetWare 4.0 and the applications produced from your development efforts will make a boundless computing environment a reality.

Happy_Programming!

Mad Poarch
Director
Developer Support/Service


ARTICLES:

Booting Multiple Operating Systems with the DR Multiuser DOS LOADER Utility

If you have ever installed DR Multiuser DOS, you may have noticed a utility called LOADER. This utility is similar to the OS/2 Boot Manager utility and is automatically installed by DR Multiuser DOS systems that contain a pre-existing single-user version of DOS. LOADER lets you to select between DR Multiuser DOS and a single-user operating system.

If you are in the business of supporting more than one operating system, LOADER is an ideal testing utility. The documentation, however, does not fully detail how to use LOADER with multiple operating systems. This article explains how you can use this utility to load DR Multiuser DOS, DR DOS, MS-DOS and OS/2 on one computer. It also discusses how to customize LOADER to meet various testing and support requirements.

General Precautions

When LOADER is installed, it includes two hidden, system, read-only (HSR) files: LOADER.SAV and IBMBIO.LDR. These files are location-sensitive and must not be moved or deleted except through LOADER. LOADER.SAV contains an exact duplicate of the Master Boot Record (MBR) before LOADER was installed. Moving or deleting LOADER.SAV will prevent the system from being restored to its previous state should it be necessary. If the files are removed, LOADER will return an error indicating "Bad or missing IBMBIO.LDR" on bootup. This message does not signal the demise of your hard drive; LOADER simply cannot find a key file. LOADER always allows you to load the default operating system (by striking any key), but if one of these files is missing, no other configured operating system will be able to boot.

Use caution when using LOADER with compressed drives such as SuperStor or Stacker. All installed operating systems need to be compatible with the compression program. Also, be aware that compression programs sometimes "swap" drives. Novell recommends that you turn off the compression software when LOADER is installed.

Because using LOADER changes the MBR, be sure you have full backups of all partitions on the first physical drive, including DOS and non-DOS partitions.

Creating a Bootfile

The "basic" installation of LOADER by the DR Multiuser DOS INSTALL program gives you the option to load DR Multiuser DOS. However, when you use LOADER to boot between multiple operating systems, you must create a separate file list called a "bootfile." This ASCII list contains the names of other operating system kernel files that are on the drive. Typically, the bootfile is named "BOOTLIST.TXT," but the name can be any valid DOS filename.

The bootfile must reside in the root directory of the primary DOS partition (bootable drive). It will contain a list of the available operating systems. The bootfile can contain up to 20 lines, each of which must have the following format:

FILENAME.EXT TYPE [NUM] COMMENT

"FILENAME.EXT" is the complete name of the operating system kernel file that is loaded first. For example, the DR Multi-user DOS filename is DRMDOS.SYS.

"TYPE" identifies the kind of operating system. For TYPE, enter one of the single-character codes shown in Figure 1.

FIGURE 1: Single character TYPE codes for different OS's

Code      Operating System
----      ------------------------------------------
 C        Concurrent DOS
 M        Multiuser DOS with or without secured fixed-disks
 D        DR DOS
 P        CP/M
 O        OS/2
 S        DR DOS with or without secured fixed-disks
 F        FlexOS
 B        Binary file
 3        MS DOS/PC DOS prior to version 3.3

END of FIGURE 1
Below is an example of a small bootfile:
CCPM.SYS     C   Concurrent DOS 3.0
DRMDOS.SYS   M   [5] Multiuser DOS
IBMBIO.COM   D   DR DOS 6.0
The optional "[NUM]" setting specifies a "timeout" for the OS kernel file. Only one timeout can be used in a bootfile.

If a user wanted DR Multiuser DOS to load automatically after five seconds, you would place "[5]" after the TYPE on the DR Multiuser DOS line (as shown in the previous example, the brackets are required). With this setting, the operating system would load in five seconds if no other selection is made.

"COMMENT" is optional and can be used to help identify which operating system will be loaded. Any text can be entered, including spaces and tabs. This information will be used in the LOADER menu.

Use either a space or a tab to separate FILENAME, TYPE and COMMENT. LOADER does not care which delimiter you use, but some type of delimiter must be present for proper execution of the bootfile.

Booting Multiple Operating Systems with the DR Multiuser DOS LOADER Utility

Installing the Bootfile Once you have created the bootfile, execute LOADER to install its components. The bootfile name is added as a parameter:
LOADER BOOTLIST.TXT
When installed, LOADER will consist of the following files:
  • LOADER.COM
  • LOADER.SYS
  • IBMBIO.LDR
  • LOADER.SAV
  • The bootfile
  • A modified MBR

Selecting Operating Systems

Each filename in the bootfile is assigned a function key. F1 is always reserved for the default operating system. LOADER then goes to the bootfile and verifies that the file is in the root directory. If the kernel filename is not in the root directory, LOADER will remove the file name from the menu. Once LOADER has verified that all files in the bootfile exist, it assigns each valid operating system a function key beginning with F2.

The default operating system (F1) is the last operating system to "SYS" the drive. In other words, the default operating system is always the operating system that has its code in the boot record of the bootable partition. The boot record is not the same as the MBR; the MBR exists outside of all partitions of a disk, while the boot record is the first sector of a partition. The partition table has a flag that indicates which partition is the bootable partition.

So, if the operating system is the default (F1), the bootable partition boot record is loaded and executed. If any other function key is chosen, then the file in the bootfile is located in the root directory, loaded in memory and executed.

If a "timeout" value is required for the default operating system, type:

LOADER BOOTLIST.TXT[15]
This line will give the default operating system (such as MS-DOS v5.0) a 15-second timeout. Make sure that the timeout value is not separated by a space from the bootfile name. There can only be one timed operating system with LOADER. Since the default operating system does not have a bootfile entry, the timeout must be run from the command line when LOADER is installed.

Booting Multiple Operating Systems with the DR Multiuser DOS LOADER Utility

Notes on Specific Operating Systems
  • DR DOS v6.0 DR DOS has enhancements that allow it to coexist more flexibly with other operating systems.

    DR DOS 6.0 first looks for a file called DCONFIG.SYS before looking for CONFIG.SYS. If it finds DCONFIG.SYS, it ignores CONFIG.SYS.

    There is also an option in the SHELL command of the (D)CONFIG.SYS that substitutes a different batch file name for AUTOEXEC.BAT. The parameter,

    /P:[filename]

    in the (D)CONFIG.SYS shell statement instructs the shell to use the named batchfile to replace AUTOEXEC.BAT. Only files with the extension .BAT may be substituted.

    SHELL=C:\DRDOS\COMMAND.COM

    C:\DRDOS /P:AUTODR6.BAT /E:512

    If the statement above is used in a file called DCONFIG.SYS, DR DOS will not use CONFIG.SYS or AUTOEXEC.BAT. This situation allows the CONFIG.SYS and AUTOEXEC.BAT files to be used exclusively by another operating system.

    Be aware that changing the names of configuration and batch files for DR DOS prevents you from using the DR DOS Setup utility to configure these files. In this case, you will need to make all adjustments manually. The manual installation instructions are contained in a document called FYI-M-1106. All FYI (For Your Information) documents from the Novell Desktop Systems Group (DSG) are available on NetWire, or from the Novell Desktop Systems Group FaxBack system at 1-800-638-9273 and the Novell DSG Bulletin Board Service at 1-408-649-3443.

    If installing DR DOS with MS-DOS, follow the manual installation instructions in FYI-M-1106, but do not "SYS" the drive. Instead use the command:

    XCOPY A:IBM*.COM C:\ /H

    Doing so will copy the system files from the DR DOS floppy diskettes, while leaving the special attributes HSR intact. Then, add the DR DOS kernel name (IBMBIO.COM) to the bootfile.

    For shell statements, COMMAND.COM is loaded from the DRDOS directory which prevents you from accidentally loading the wrong command processor due to an incorrect path statement. In fact, when using LOADER, no command processor should be located in the root directory. Most user paths contain the root directory.

  • MS-DOS v1.0-v4.x

    All versions of MS-DOS prior to v5.0 require that system files be located in contiguous space at the beginning of the partition. The MS-DOS operating system also requires that the two system kernel files be the first two entries in the root directory. If you intend to use MS-DOS in a partition with another single-user operating system such as DR DOS, the second operating system should not "SYS" the drive. With DR DOS, this would require a manual installation. For more information you should refer to the previous section on DR DOS 6.0.

    Various versions of MS-DOS use the same kernel file names: IO.SYS and MSDOS.SYS. Because of these identical file names and the special booting requirements, you can only use one version of MS-DOS on any computer.

  • MS-DOS v5.0

    If you want to run MS-DOS 5.0, you must install it as the default operating system. Other operating systems like OS/2, DR Multiuser DOS and DR DOS can be installed first but LOADER must not be executed until MS-DOS 5.0 has been installed. "SYSing" a drive with MS-DOS v5.0 will remove LOADER from the MBR and remove the DR DOS files IBMBIO.COM, IBMDOS.COM and COMMAND.COM. Use the steps described under "DR DOS v6.0" to replace them.

    If your boot record is overwritten by another installed operating system, then remove LOADER and "SYS" the drive with MS-DOS v5.0 to make it the default once again. Then, reinstall the LOADER utility.

    MS-DOS v5.0 also requires you to use the first two directory entries in the root directory. However, system files are not physically position sensitive. This is what allows MS-DOS v5.0 to be installed when the disk already contains data. The MS-DOS SYS utility will reorder the directory to fit the MS-DOS v5.0 boot requirements.

  • MS-DOS v6.0

    LOADER has not been tested with MS-DOS v6.0.

  • PC-DOS

    All versions of PC-DOS prior to v5.0 have the same requirements as their corresponding MS-DOS versions.

    PC-DOS and DR DOS both use the same system file names: IBMBIO.COM and IBMDOS.COM. Because of this duplication of names, installing both DR DOS and PC-DOS on the same computer requires special handling.

    Making PC-DOS and DR DOS work together requires an undocumented switch from the DR DOS SYS command. This switch, "/DR:ext," lets you change the extensions of IBMBIO.COM, IBMDOS.COM and CONFIG.SYS. For example, if you "SYSed" the drive using the command "SYS /DR:DR6", the boot record would be modified to load IBMBIO.DR6. Then, IBMBIO.DR6 would load IBMDOS.DR6 and execute the config file, CONFIG.DR6.

    Be sure to change the shell command in CONFIG.DR6 to execute an alternate AUTOEXEC file such as AUTODR6.BAT. Also, make sure that COMMAND.COM is not loaded in the root directory (see "DR DOS v6.0"). Once you have accomplished these steps, you must "SYS" the drive with PC-DOS again to make it the default operating system. This is the only documentation on this switch. Because it is otherwise undocumented, it may not be available in future versions. Novell support is not available for this option.

  • OS/2

    OS/2 should be installed after installing all other operating systems. OS/2 should also be installed using the dual boot method of installation. Doing so will preserve the default operating system. After OS/2 installation, the dual boot function should never be used. Instead, use LOADER to select the operating system. The bootfile should contain the following line:

    OS2KRNL O OS/2

    "OS2KRNL" is the name of the OS/2 kernel file. "O" is the TYPE for OS/2.

  • Interactive UNIX

    The FDISK utility provided with FLEXOS, DR DOS and DR Multiuser DOS may change the position of partitions in the partition table. Sunsoft's Interactive UNIX (and possibly other UNIX versions) will not load DOS if this repositioning occurs. However, the ability to load UNIX is unaffected when this repositioning occurs.

    Interactive UNIX uses a program with superficial similarity to LOADER. However, this program searches for a position dependent partition entry to execute alternate operating systems. LOADER makes it possible to load the alternate operating systems. Make sure that the UNIX partition is the Active (bootable) partition and then install LOADER with UNIX as the default operating system.

Booting Multiple Operating Systems with the DR Multiuser DOS LOADER Utility

Running LOADER from Another Operating System

LOADER is not DOS-version-sensitive, but it should be run from either DR Multiuser DOS or DR DOS.

DR DOS and DR Multiuser DOS Security

If either DR DOS or DR Multiuser DOS security is enabled, these two operating systems will be the only ones that LOADER will allow to boot. Specifically, if LOADER detects security, only TYPE M and S operating systems will have function keys assigned to them.

Do not attempt to fool LOADER by setting another type of operating system (for instance, M or S). Doing so may cause boot failure.

Removing LOADER

To remove LOADER, type "LOADER /U." This command will restore the MBR preserved in LOADER.SAV.

Online Help

To access online help, enter the command, LOADER /H. LOADER will display command line options and an outline of the contents of a sample bootfile.

The DR Multiuser DOS LOADER utility, is now available on the Novell Desktop Systems Group BBS. Novell is making it available at no charge to all interested developers for internal use during development and testing. To download a copy of LOADER, contact the Novell Desktop Systems Group BBS at 1-408-649-3443.

New Features of the NetWare 4.0 Interface for AppleTalk for NLMs

The NetWare 4.0 Interface for AppleTalk for NLMs SDK v1.0 provides the power to create powerful utilities, tools, applications, and make a wide range of network services available to the Macintosh community. This SDK offers developers a way to design a cross-platform set of NLMs that use a variety of protocols and integrate Macintoshes more fully in the NetWare environment.

This article examines enhancements to the NetWare 4.0 Interface for AppleTalk for NLMs. It also compares native AppleTalk calls with TLI calls and discusses special considerations for porting NLMs developed using the previous version of the SDK.

AppleTalk Protocols & TLI

AppleTalk system architecture consists of a stack of protocols. LAP, the Link Access Protocol, is the lowest layer and AFP, AppleTalk Filing Protocol, is the highest; Zone Information Protocol (ZIP) and Printer Access Protocol (PAP) add more levels of networking support at a Session Level. The native calls provided with the NLM SDK are specific to each of these protocols.

The Transport Layer Interface (TLI) is a transport interface standard available across many platforms. It allows you to support multiple protocols with common source code, so makes it a good choice in situations where the specific methods in use at the lower layers are not known. During the opening of a TLI connection on a Macintosh you need only specify which delivery protocol to use, as well as ADSP-specific information.

New Features & Changes

A number of changes have been made to the native AppleTalk calls support since v1.1 of the NetWare AppleTalk Interface for NLMs. Syntactically, "AT" has been added to the beginning of all names, "_" has been removed, and the words have been capitalized. This aids in API clarification and consistency across NetWare development platforms. As an example, nbp_make_entity() has now been changed to ATNbpMakeEntity().

The Name Binding Protocol (NBP)

NBP Lookup provides two extra parameters to control buffer overflow; the more flag and the buffer size field. The more flag lets you control whether the call will return the buffer contents immediately, or wait until it overflows by one tuple. For example, if you want to have NBP return when the buffer fills up, you would set the more flag to 0 (zero). If the more flag is set to 1 (one) and the buffer never overflows, approximately six seconds will elapse before the call returns the buffer's contents.

If you do not use the more flag and choose to let the NBP call time out, you should check your resources before you permit the NLM to unload. One of the resources in use by NBP is a STREAMS file descriptor. You should make sure that your NLM doesn't unload itself while an NBP call is in progress, otherwise CLIB (the library that provides standard C language and NetWare API interfaces) will clean up the resources in use.

The buffer size field informs the API the size of the buffer by passing in {1 to n} as the maximum number of tuples the buffer will hold. There is no maximum to the number of tuples that can be generated by the network, since a large number of NBP entities can be registered for each end node in a zone.

A typical Macintosh may use 1-4 entities: one for InterPoll/Responder, one for a mail package, one for personal Apple-Share, and perhaps one for another entity. So, if a zone has 1,000 Macintoshes, 1,000 to 4,000 tuples would typically be received on a wild card lookup. The buffer size field restricts the amount of data returned from a lookup call.

AppleTalk Transaction Protocol (ATP)

The AppleTalk Transaction Protocol (ATP) implementation has also changed for NetWare 4.0 NLMs. One example is in the ATP Get Next Transaction Request. The difference between the old function call atp_getreq() and the new call ATAtpGet() is that the new call adds a much fuller range of functionality, including non-blocking operation and multiple outstanding request capability.

With the previous version of the SDK, the atp_getreq() function returned only the next ATP transaction request (TREQ). The revised ATAtpGet() call receives TREQs as well as ATP transaction responses (TRESP). Now, if you need to send two TREQs, the added functionality allows you to either wait for an incoming TREQ or any TRESPs with a single call to ATAtpGet. Previously, atp_sendreq() would be used, which would block until the response packet was received from the other end.

ATP matches up requests and responses across the API boundary using transaction IDs (TIDs). When your application receives a request, ATP creates a TID that must be passed to ATAtpSendResp() as a part of the response. If you need to cancel a request, you would pass this TID to the ATAtpCancelReq() call.

When using the ATP "At Least Once" (ALO) delivery method, you may want to consider the use of "packetization" as a means of flow control. This technique is a way of telling ATP the response packet sequence and length. In addition, you may find it useful to use "packetization" in an "eXactly Once" (XO) transaction such as the printer access protocol (PAP), which only allows responses up to 512 bytes per packet.

The Printer Access Protocol (PAP)

The new Printer Access Protocol support allows you to make your NLM act like an AppleTalk spooler. Since all LaserWriters use PAP exclusively, and since Macintoshes come with a LaserWriter driver, this feature can save you from writing a front-end print handler on the Macintosh. Moreover, the back-end does not have to use PAP. Once your NLM receives the print job from the Macintosh, you have complete control over how the printer will service the print job.

The NetWare 4.0 AppleTalk PAP interface for NLMs can also be used in non-blocking mode as in the ATP interface.

AppleTalk Session Protocol (ASP)

ASP allows you to write an NLM that takes advantage of the native session-oriented protocol on the Mac. The AppleShare client, which ships with the Macintosh operating system software, uses ASP and the AppleTalk Filing Protocol (AFP) to send commands to the server. The server in this case could be a NetWare file server with the AFP support loaded. ASP is a new addition to the SDK which your NLM may use to communicate with ASP clients.

AppleTalk Data Stream Protocol (ADSP)

ADSP is a connection-oriented protocol that guarantees data delivery and sequencing. You must use the TLI interface to access ADSP from an NLM.

ADSP is no longer part of APPLETLK.NLM. Your NetWare 4.0 NLM will need to check to see that ADSP is loaded. Otherwise you may receive the error "Invalid transport provider name" when tli_open() tries to open "dev/adsp".

New Features of the NetWare 4.0 Interface for AppleTalk for NLMs

Other Parameter Changes

As previously discussed, several function call parameters have changed in the NBP support. Additional parameters that have been modified include those passed to the atp_sendreq() call. This function used to take many arguments that have now included in the ATAtpPass_t structure. With the call ATAtpSendReq(), you pass in two arguments: the file descriptor and the ATAtpPass_t structure. Another change is that the RTMP API, rtmp_netinfo(), is no longer supported. To get network information, use the new DDP call ATDdpNetinfo instead of rtmp_netinfo (see Figure 2).

FIGURE 2: Get Network Information

int my_fd;            /* The client's transport endpoint.*/
ATInet_t info;        /* The client's AppleTalk internet address.*/
ATInet_t router_info; /* Router's AppleTalk internet address */

/* Open a socket. */

my_fd = 0;

if (err = ATDdpOpen(&my_fd))
   {
      printf("ATDdpOpen failed: err = %x\n",err);
      exit(__LINE__);
   }

if(err = ATDdpNetinfo(my_fd,&info,&router_info,NULL))
   {
      printf("ATDdpNetinfo failed: err = %x\n", err);
      ATDdpClose(my_fd);
      exit(__LINE__);
   }

END of FIGURE 2

Porting NetWare 3.11 NLMs to NetWare 4.0

Porting the sample code that shipped with the NetWare AppleTalk Interface for NLMs v.1.1 to run on NetWare 4.0 presents a number of challenges. Even if you are not porting code and plan on writing an all-new NLM using this SDK, the following information will be useful.

Using NBP you should register your zone name as "*". If you explicitly registered your NLM in a zone, this will fail if your end users do not use the internal network since the network may change out from under the registrar. There is no way to notify the registrar if this happens. According to Apple, you should always register under "*". When you do a "*" registration and MY_ZONE changes, all the "*" registrations change automatically. EFAULT is a specific error which indicates that an explicit registration is not valid. When this error occurs, perform a "*" registration.

In order to receive packets on a stream, the client must register a listener with the new call ATDdpRegisterListener(). This requirement is documented but is easy to overlook.

ASP is a state-dependent protocol which sets up sessions between clients and servers. ASP is used to guarantee messages are delivered to the server in the order issued. ASP calls send a message up to the stream head, which is outside ASP's jurisdiction. This causes the machine state to change in the respect that it expects a certain response. A typical error in the use of ASP is making the wrong call at the wrong time.

When using ADSP, it may help to think of the data transfer occurring over a pipe: from the local application, through TLI, STREAMS, and ADSP, over the physical wire(s), and back up to the remote end's application. While that pipe is open, you must be aware of the size of send and receive buffers (windows). Both local and remote ends could "shut-down" at various points in the data transfer because of either the receive or send buffers filling up. This causes the session to appear "hung;" that is, the two sides of the pipe just send ADSP Probes to each other stating the size of their send/receive windows.

Under certain circumstatnces, the ADSP receive window on the Macintosh can go to zero and never increase, causing the session to hang. To avoid this, make sure you service your buffer frequently on the Macintosh side. If you suspect a hung session, verify it by running a trace and looking at the receive window on an ADSP Probe. This test provides enough information to determine which end is causing the flow problem. Since the ADSP receive window on the NLM side defaults to 8K, it should not be a problem if you are not using options.

In a typical ADSP session, an application sends a certain amount of data before waiting for a reply. This data represents a single ADSP message. The application need not send all of its data in the message at the same time. It can accomplish the data transfer by sending sequenced blocks of data. Each block of data is transferred with a call to t_snd().

Your application should use the T_MORE bit for flow control. The following guidelines may help:

  • Set the T_MORE bit when you are sure the application has more data to send.
  • Clear the T_MORE bit when the application has completed its data transfer and is waiting to receive a reply from the remote connection end.
The NetWare 4.0 Interface for AppleTalk for NLMs SDK v1.0 is the right tool for developers who want to communicate using the AppleTalk protocols via TLI, the native AppleTalk calls, or both. Through TLI, it provides resources for programmers using DDP and ADSP. In addition, this SDK documents the native function calls that enable you to use the other protocols discussed in this article.

For More Information

For more information about the AppleTalk protocols discussed in this article, consult the April 1992 issue of NetWare Application Notes (AppNotes); the article, "AppleTalk Protocol Routing and NetWare," describes AppleTalk routing. In addition, Inside AppleTalk (Addision-Wesley, 2nd Ed., authors Sidhu, Andrews, Oppenheimer) is the source for the AppleTalk specifications used in this article and provides a detailed explanation of the implementation of the AppleTalk protocols.

The NetWare 4.0 Interface for AppleTalk for NLMs SDK v1.0 is available to members of the Novell Professional Developers' Program. For more information, call 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.


TECHNICAL INSIGHTS:

Interfacing GFA-Basic for Windows & WBTRCALL.DLL (Btrieve for Windows (all versions))

To call Btrieve for Windows from a GFA-Basic Windows application, the declaration shown in Figure 3, Part A, must be made in the global section of your code. Since the Position Block, Data Buffer, Data Buffer Length, and Key Buffer parameters need to be FAR pointers, the "l" argument means LONG for the four-byte FAR address. The "w" argument stands for WORD, or two-byte addresses.

FIGURE 3: Declaration and Btrieve call for GFA-Basic for Windows

Part A: Declaration

   DLL #10,"C:\WINDOWS\SYSTEM\WBTRCALL.DLL"
      DecL Word btrcall (w,l,l,l,l,w,w) Pascal
   EndDLL


Part B: Btrieve Call

   Status& = ^btrcall(opcode&,
                      V:Posblk$,
                      V:DataBuf,
                      V:DataBufLen,
                      V:KeyBuf$,
                      KeyBufLen&,
                      KeyNum&)

END of FIGURE 3
The actual Btrieve call to the DLL should look like the call shown in Part B of Figure 3. The "^" character before the btrcall function name tells the GFA compiler that the next variable name is an external function name. The "&" character after the variable name means "integer" in GFA-Basic, just as the "%" sign would in Microsoft Basic. The "V:" designation is equivalent to VARPTR in Microsoft Basic, which stands for "variable pointer."

Incorrect searchBitMap Description (Network C for NLMs v2.00)

The searchBitMap diagram in the Network C for NLMs documentation for AFPScanFileInformation() shows the descriptions shifted one left from the bits to which they belong. This shift will prevent the function from finding entries with the correct attributes.

The searchBitMap descriptions in the NetWare C Interface for DOS documentation are correct.

  • Bit 0 is for hidden.
  • Bit 1 is for system.
  • Bit 2 is for subdirectories.
  • Bit 3 is for files.

xDDCreate Manual Correction (NetWare SQL v3.0)

When you create a table through NetWare SQL, you can assign an owner name to the Btrieve file that is created. You can create the file with the SQL CREATE statement or the Primitive API, xDDCreate. Three of the NetWare SQL manuals incorrectly describe the File Owner Flag of value 1 as:

"Permits read-only data access with the owner name; does not enable data encryption."

These manuals should read:

"Permits read-only data access without the owner name; does not enable data encryption."

The NetWare SQL manuals that need to be corrected are:

  • SQL Language User's Manual, page 4-27, table 4-1
  • SQL Language Reference, page 2-26, table 2-1
  • Application Programming Interface, page 3-59, table 3-9

Documentation Update (NetWare C Interface for DOS v1.2)

The documentation for GetObjectDiskRestrictions() incorrectly states that, if there is no restriction set for the object, the volRestriction parameter will contain 0x40000000. Actually, if there is no restriction set, volRestriction is returned with 0. You can assume that, if volRestriction is returned with zero, either there is no restriction set, or there is a restriction of zero bytes set for the object.

Using xUser to Create Users and Groups (NetWare SQL v3.0)

When using the relational primitive xUser (option 0) to create users and groups, it is important to set the iFlags parameter properly. If you do not set this parameter correctly, a user may be created as a group and vice versa. To create a user, place the username in the sUser parameter, and place the user's password in the sPassword parameter. The iFlags parameter should be set to zero or one, depending on whether you want the user to be able to define new tables or not (see page 3-235 of the Application Programming Interface manual included with the NetWare SQL Developer's Kit v3.0). To create a group, place the groupname in the sUser parameter, and set the first byte of the sPassword parameter to binary zero. The iFlags parameter should be set to two or three, depending on whether you want users in this group to be able to define new tables or not. When you attempt to create a user, if you set the iFlags parameter to two or three, the user will be created as a group instead. Similarly, when you attempt to create a group, if the iFlags parameter is set to zero or one, the group will be created as a user instead. Always be sure to use the correct iFlags value when creating users and groups with the xUser function.

Formats for NetWare Bindery Object Types (NetWare C Interface for DOS v1.2)

If predefined object types are not used, object types may be explicitly specified. The format of the object type is dependent on whether you are using the NetWare Client SDK. For example, the constant for a bindery object of type OT_USER is shown in Figure 4. Note that the OS/2 and Client SDKs require byte-swapped object IDs.

FIGURE 4: Constant corresponding to bindery object of type OT_USER

NetWare C Interface for DOS v1.2                  0x01
NetWare C Interface for Windows v1.22 and v1.3    0x0001
NetWare C Interface for OS/2 v1.2 and v2.0        0x0100
NetWare Client SDK v1.0a (all platforms)          0x0100

END of FIGURE 4

SPXS.NLM & STREAMS (Network C for NLMs v2.0 (e))

When using TLI to send data via SPX, if an application sends large amounts of data quickly, an "out of memory" condition can occur at the server. This situation results because SPXS.NLM (the interface between SPX and the STREAMS module) does not limit the growth of the stream as it "puts" data into the stream.

To avoid running out of memory, insert flow control into your communication. The next release of SPXS.NLM should limit stream growth.

LU6.2 Implementation for CPIC Under Windows (NetWare C Interface for Windows v1.3)

Novell has implemented CPIC as non-blocking and does not support blocking mode. CPIC normally will attach to a local LU6.2 LU and issue a CMACCP function call. This call fails with a CM_OPERATION_INCOMPLETE return code, which indicates that no conversation is available.

After you call the CMWAIT function, CPIC will wait for an incoming conversation for an indefinite amount of time. Novell has not implemented the CMWAIT function, so this cannot be used when porting an application to the Novell environment. As a workaround, modify the current design of the software

to create a timer and call CMACCP each time the timer goes off. Keep in mind, however, that the CMACCP function is hard-coded to wait for a conversation for approximately three minutes. During this time, the user is unable to do anything under Windows because the CMACCP function is system model.

This situation will be unacceptable in some situations. If the application is executed long before the host partner application and is forced to use the timer method of polling for conversations, then the user will not be able to function at his workstation.

The fixed, hard-coded value will be changed to a variable value in the next release of CPIC under Windows.

FEsopen() & FECreat() in CLIB.NLM (Network C for NLMs v2.0 (e))

According to the documentation for FEsopen() and FECreat(), if the FILE_WRITE_THROUGH_BIT is enabled, write() will not return until it has committed the data to disk. When the file is created via FECreat() or FEsopen(), setting the FILE_WRITE_THROUGH_BIT has no effect until the file has been closed and reopened.

Modifying MOwnerID Field (Network C for NLMs v2.0 (e)

The documentation for the Network C for NLMs SDK does not indicate that the MOwnerID field in the ModifyStructure should be long-swapped. The function call ChangeDirectoryEntry() reports a return code of 1 if the value in this field is not swapped.

For example, as shown in the code segment in Figure 5, to modify the supervisor MOwnerID, the ID value must be long swapped.

FIGURE 5: Modifying SUPERVISOR

MOwnerID by long-swapping ID value

GetBinderyObjectID( "SUPERVISOR", OT_USER, &superID );
ModifyStructure.MOwnerID = LongSwap(superID);
result = ChangeDirectoryEntry("SYS:\\SYSTEM",
                              &ModifyStructure,
                              MOwnerIDBit, 0);

END of FIGURE 5

NIBBLES AND BITS

Fast Answers to Common Questions

NetWare Btrieve

Q - What happens when you use NetWare Btrieve v6.x to access a Btrieve file that was created in the v5.x file format?

A - Everything will work properly. NetWare Btrieve v6.x can access both v5.x and v6.x format files simultaneously.

Q - What happens when you use NetWare Btrieve v5.x to access a Btrieve file that was created in the v6.x format?

A - A status 2 (I/O error) will be returned when you attempt to open a v6.x file with v5.x.

Q - Is it true that the pathname conventions for the local and requester versions of WBTRCALL.DLL are the same as for local and NetWare Btrieve? For example, can you use server/volume names for the requester DLL and only drive letters for the local DLL?

A - Yes, the pathname conventions are the same for Windows as they are for DOS.

Q - How can a Btrieve file format version be checked? In other words, how can someone determine whether a Btrieve file is stored in 5.x or 6.x format?

A - One way would be to run the version 6.x BUTIL NLM from the file server. This utility displays the file format version after executing a STAT call. However, there is no 'client' BUTIL program available which shows this information.

An easy way to check the format version of a Btrieve file is by using DOS DEBUG. Just type 'debug <filename.btr>' and then 'd' at the hyphen prompt. The first two bytes of the FCR (the first page in the file) will be set to FC if the file is stored in 6.x format. Otherwise, the bytes will be set to 0x00.

NetWare Client SDK

Q - Where is the latest version of the DOS requester for NetWare?

A - The DOS requester can be downloaded from Novell's NDEVREL forum on CompuServe (Library 1, DOSB3.ZIP).

Network C for NLMs

Q - How do I set a Netware Server's configuration parameters from an NLM?

A - In CLIB.NLM V.4.0, the functions GetSetableParameterValue(), SetSetableParameterValues(), and ScanSetableParameters() will do the job. However, these functions are not available in CLIB.NLM v.3.x.

Q - The documentation does not indicate why AllocateResourceTag() would return unsuccessful. Why does it fail?

A - AllocateResourceTag() can return unsuccessful for any one of the following several reasons:

  • A bad NLM handle was passed as the first parameter.
  • A bad resource type (resource tag signature) was passed as the third parameter.
  • The description string passed as the second parameter was already in use.
  • The resource type (resource tag signature) was passed as a NULL.

NetWare C Interface for DOS

Q - The documentation for the AttachToFileServerWithAddress() function call states that, if the connection is still valid, the function returns the connection number. However, the function always returns a status code and not a connection number. Which should be returned?

A - The documentation is incorrect. AttachToFileServerWithAddress() returns a status code rather than a connection number.

Q - Is there an API to perform NetWare 2.x specific functions such as GetConnectionsUsingFile and GetConnectionsOpenFiles in the NetWare 3.x environment?

A - The F2 interface in SC3X03.ZIP in the NOVLIB forum on CompuServe provides this functionality.

Netware 3270 LAN Workstation for Windows

Q - Is there a HLLAPI DLL for Windows?

A - The Netware 3270 LAN Workstation for Windows v1.2 has two DLLs, WSHLLAPI.DLL and WSLLAPI.DLL, for HLLAPI and LLAPI interfaces. Version 1.1 does not include this support.

General

Q - Where are the workstation drivers for DOS 6.0 support?

A - These drivers can be downloaded from Novell's CompuServe forum NetWire (NOVLIB, section 1, DOSUP7.ZIP).


NOVELL DEVELOPER EDUCATION

Novell Developer Education offers several 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. 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, sche12-794-1796 from a touchtone phone. Choose the option for the Automated Fax System, select the documents you wish to receive, and supply your fax number (the fax number to which you want the document(s) sent). Document #7805 describes the patches. Document #1 lisduling, & 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.

CURRENT PATCHES FOR NOVELL DEVELOPMENT TOOLS

Often, proper patching can save you a call to the Developer Support Group. The latest NetWare drivers, example code for NetWare API development tools, OS/2 requester patches, and patches for Novell database tools are available on Novell's NetWire forum on CompuServe. Back issues of Bullets and developer FYIs are also available (NOVLIB, library 11). New information is first stored in NOVLIB library 1, and moved to library 7 after a period of 30 days. If you do not have access to CompuServe, request these files from Novell's Developer Support Group at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.

When you call, be ready to provide a shipping address, disk preference (5.25", 3.5", HD, or DD) and, if you prefer overnight delivery, your company's Federal Express account number. If you do not provide a Federal Express account number, the patch disk will be sent to you via regular mail. Updated NetWare API SDK components can be obtained from Novell's NDEVREL forum on CompuServe. For more information on Novell developer programs contact Novell at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.

A document describing available patches and other files and their location on CompuServe is available through Novell Developer Relation's Automated Fax System (AFS). AFS can provide you other useful information as well.

To use the AFS, call 1-800-RED-WORD (1-800-733-9673) or 5ts other documents available through the AFS. You may request five documents per call.


CONTACTING NOVELL

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 local 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 products may post pre-sales product information questions on all Novell SDKs.

E-mail: MHS or Internet (SMTP)

You may direct your questions and comments 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.

ACKNOWLEDGEMENTS

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

Articles: Steve Iribarne, Robert Rodriguez, Vicki L. Smith

Contributors: Linda Anderson, Michael Eisa, Jack Gumaer, Laura Heater, Nancy Kromar, Clint McVey, Paige Parker, Randy Reddy, Drue Reeves, Robert Rodriguez, Mike Shoemaker, Gayle Simmons, Aslam Tejani

Novell Professional Developer Bullets is a publication from Novell's Developer Support Group. Special thanks to the Developer Support, Development, Developer Relations, Product Marketing, and Marketing Communications staff who contributed time and valuable input.

(c) 1993 Novell, Inc. All rights reserved. Novell, the N design, NetWare, Btrieve, XQL, LAN WorkPlace, DR DOS and LANalyzer are registered trademarks; NetWare Loadable Module (NLM), NetWare Global Messaging, NetWare System Calls for DOS, DR Multiuser 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, NetWare 3270 LAN Workstation and Xtrieve PLUS are trademarks; and NetWire and Professional Developers' Program are service marks of Novell, Inc. OS/2 is a registered trademark, 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, AppleTalk, HyperCard and Macintosh are registered trademarks of Apple Computer, Inc. CompuServe is a registered trademark of CompuServe Corporation. NFS and Solaris are registered trademarks, and SunSoft is a trademark of Sun Microsystems, Inc. UNIX is a registered trademark of UNIX Systems Laboratories, Inc., a subsidiary of AT&T.