APRIL 1993 VOLUME 5 NUMBER 4
INDEX
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
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.
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
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 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.
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.
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 [email protected]. 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 [email protected]. Use
the same address when going through the Internet E-mail system.
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.;
|