Accessing the NetWare Bindery Using AppWare

Articles and Tips: article

DEAN SCHMIDT
Software Engineer
AppWare Development Team

01 Mar 1995

A series of AppWare Loadable Modules (ALMs) has recently been developed to provide access to the NetWare bindery from applications created using the Novell AppWare (formerly Visual AppBuilder) development tool. These ALMs include NW Bindery, NW Server, NW Client, and Data Stream. This DevNote offers an overview of these ALMs and tells how they can be used in applications that access the bindery. The article then describes the NW Bindery ALM in detail, offering information on such subjects as bindery object names and bindery property names.

Introduction
Bindery ALMs
Using the NW Bindery ALM
Sample Project
NetWare 4 and the NW Bindery ALM
Differences from the NW DS Data ALM
How To Obtain the ALMs

Introduction

The bindery is a database used by NetWare servers to identify and store information about network objects. The bindery stores network objects and their associated properties. NetWare servers prior to version 4 natively support the NetWare bindery. NetWare version 4 and later servers natively support NetWare Directory Services (NDS), but also support the bindery to provide backward compatibility with existing applications.

The AppWare Loadable Modules (ALMs) discussed below provide access to the bindery from applications created using the Novell AppWare (formerly Visual AppBuilder) development tool. These ALMs include the following:

NW Bindery
NW Server
NW Client
Data Stream

Comprehensive Online Help

Each of the ALMs described below is accompanied by a detailed online help file. When using the Windows version of the AppWare development tool, clicking the right mouse button on a function icon displays the detailed help for that function. Each function is described in detail, including any restrictions on the use of the function. By clicking the right mouse button on an icon in the object palette, you can display the main index of the help file for that ALM.

You can also display the help files for the NW Bindery and NW Server ALMs by selecting the help button in the corresponding object editing dialog. The help file name for each of the ALMs is listed below, and differs from the ALM file name by extension only.

ALM_BIND.HLP Help file for the NW Bindery ALM. ALM_NWWS.HLP Help file for the NW Client ALM. ALM_NWSV.HLP Help file for the NW Server ALM. ALM_STRM.HLP Help file for the Data Stream ALM.

Bindery ALMs

This section offers an overview of NW Bindery, NW Server, MW Client, and Data Stream.

NW Bindery ALM

The NW Bindery ALM was designed to provide the data and functions required to access the NetWare bindery. The NW Bindery ALM consists of an AppWare object and numerous AppWare functions. The AppWare object and function category are both named NW Bindery.

The NW Bindery object stores references to two AppWare text objects. The object editing dialog for the NW Bindery ALM, which is used to establish the text object associations, is shown in Figure 1. The first text object, object name, is used to associate a text object which specifies the object name of a bindery object to be referenced. The value of this text object should refer to a specific bindery object and may not contain wildcard characters. The second text object, object type, is used to associate a text object which specifies the object type of the bindery object to be referenced. The value of this text object should refer to a specific object type, and should not contain the string "All."

Figure 1: NW Bindery object editing screen.

The NW Bindery function category contains 33 functions, which can be categorized by the type of operation performed, as shown in Table 1. Many of the functions in the NW Bindery function category have certain requirements and restrictions for use. Consult the NW Bindery ALM online help file for detailed information.

Table 1: NW Bindery function groupings.

Locating Objects and Properties	Bindery Administration	Object Manipulation	Property Manipulation
List Object Types	Archive Bindery	Create Object	Create Property
List Objects	Restore Bindery	Delete Object	Delete Property
Object Exists ?	Assign Type Name	Rename Object	Get ... Property
List Properties		Change Object Security	Set ... Property
		Change Password	Property Supported
		Verify Password	Change Property Security
		Get Object Info	Get Property Info

NW Server ALM

The NW Server ALM was designed to encapsulate the data and functions required to communicate with a specific NetWare server. The NW Server ALM consists of an AppWare object, a function category, and several object APIs provided to ALM developers. The AppWare object and function category are both named NW Server. The NW Server ALM is useful in applications which also use the NW Bindery ALM for the following reasons:

Specification of the NetWare server that communicates with the various functions in the NW Bindery function category.
Caching of certain static data about a specific server, such as the connection handle and version information. Performance is enhanced by eliminating network requests for information which has already been obtained and is extremely unlikely to have changed.
The "Native Bindery ?" function can be used to determine if a NetWare server natively supports the bindery or NDS.
The "Set Server Name" function allows changing the NetWare server name currently stored in the NW Server object.
The "Get Server Name" function obtains the NetWare server name currently stored in the NW Server object.

The object editing dialog for the NW Server ALM is shown in Figure 2. The object editing dialog contains two fields, the first of which contains the name of the NetWare server that communicates with the NW Server ALM. The server name field can also be manipulated by calling the "Get Server Name" and "Set Server Name" functions. The second field is a check box which determines whether or not the primary server can be used if the server name field is left empty. The primary NetWare server is usually the server which contains the login script executed when the current user logged in.

Certain functions which require an NW Server object as an input parameter may override the setting of this check box and disallow use of the primary server. For example, the NW Bindery function "Create Object" will fail if the server name field is empty, regardless of the setting of the check box.

Figure 2: Object editing dialog for the NW Server ALM.

The complete list of functions available in the NW Server function category is found in Table 2. Several functions are only available for NetWare version 4 or later, as indicated. For detailed information on the NW Server ALM or any of its functions, consult the online help file.

Table 2: NW Server ALM functions.

Function Name	Description
Get Description	Retrieves the description strings from the NetWare server represented by an NW Server object.
Get Server Name	Retrieves the current NetWare server name which is associated with an NW Server object.
Get Version	Retrieves the version information about the NetWare server represented by an NW Server object.
List Detail	Fills a table object with detailed information about a specific aspect of the NetWare server represented by an NW Server object.
List Known Details	Lists the various details description strings which can be passed to the "List Detail" function. The list returned can be constrained by the specific server's version and the client workstation's security equivalence on the specified server.
List Set Categories*	Fills a table object with the various NetWare set command categories available on the NetWare server represented by an NW Server object.
List Set Commands*	Fills a table object with the various NetWare set command values from a specific set command category for the NetWare server represented by an NW Server object.
Native Bindery ?	Determines if the NetWare represented by an NW Server object natively supports the NetWare bindery.
Set Server Name	Sets the current NetWare server name which is associated with an NW Server object. This causes any static data stored in the NW Server object to be cleared.
Supports NDS ?	Determines if the NetWare server represented by an NW Server object supports NetWare Directory Services (NDS). This function can also optionally return the name of the NDS tree to which the server is a member.

*Functions which are only available for NetWare version 4 and later servers.

NW Client ALM

The NW Client ALM provides functions which can obtain detailed information about the network client workstation on which the AppWare-derived application is executing. The NW Client ALM is useful in applications which also use the NW Bindery ALM for the following reasons:

The "Get Primary Server" function can be used to determine the primary NetWare server for the client workstation.
Determining if the client workstation is capable of communicating with NetWare Directory Services (NDS).
Determining if the client workstation is logged in to a specified NetWare server as the supervisor user or as a user which has supervisor equivalence.

The NW Client ALM consists of an AppWare function category and several object APIs provided to ALM developers. The AppWare function category is named NW Client. The complete list of functions available in the NW Client function category is found in Table 3. For detailed information on the NW Client ALM or any of its functions, consult the appropriate section in the online help file.

Table 3: NW Client ALM functions.

Function Name	Description
Connectivity Test	Performs a connectivity test between the current client workstation and a specified NetWare server or network address.
First Network Drive	Determines the drive letter of the first DOS drive used for network drive mappings for the current client workstation.
Get Primary Server	Determines the name of the current client workstation's primary NetWare server. The primary NetWare server is usually the server from which the login script was executed.
Get Type / Version	Determines the type (shell or VLMs) and version of the NetWare client software running on the current client workstation.
List Connections	Lists the names of all NetWare servers conncted to the current client workstation. This function can also display the type of connection.
Maximum Connections	Determines the maximum number of concurrent connections supported by the NetWare client software running on the current client workstation.
Support NDS ?	Determines if NetWare Directory Services (NDS) is supported by the NetWare client software running on the current client workstation.
Who Am I ?	Determines the current client workstation's user name for a specified NetWare server. This function also indicates whether or not the user has supervisor equivalence.

Data Stream ALM

The Data Stream ALM was designed to provide an object and corresponding functions for storing and manipulating data which cannot be represented using the existing ALMs, such as text, number, date, and time.

The Data Stream ALM can also be used to create rudimentary data structures. The Data Stream ALM consists of an AppWare object, a function category, and numerous object APIs provided to ALM developers. The AppWare object and function category are both named Data Stream.

The Data Stream ALM is useful in applications which also use the NW Bindery ALM for the following reasons:

Storage and retrieval of bindery property values which contain known data structures.
Storage and retrieval of bindery property values, for which the underlying data structures are not known.
Storage and retrieval of bindery property values, such as sound and graphics.

The complete list of functions available in the Data Stream function category is found in Table 4. For detailed information on the Data Stream ALM or any of its functions, consult the online help file.

Table 4: Data Stream ALM functions.

Function Name	Description
Get Number	Retrieves a numeric value from a specified offset within a data stream.
Get Size	Returns the size, in bytes, of the specified data stream.
Get Text	Retrieves a text value from a specified offset within a data stream.
Load From File	Initializes the specified data stream to contain the contents of a file.
Read Only ?	Determines whether or not the specified data stream is read only.
Save To File	Saves the specified data stream to a file.
Set Access	Marks the specified data stream as read only or read/write.
Set Number	Places a numeric value into a data stream at a specified offset.
Set Size	Sets the size, in bytes, of the specified data stream.
Set Text	Places a text value into a data stream at a specified offset.
View Stream	Displays the specified data stream in a combination hexadecimal and ASCII viewing window.

Using the NW Bindery ALM

The NW Bindery ALM was designed with the following goals in mind:

Provide simplified access to the NetWare bindery for the AppWare developer.
Provide access to property values of bindery objects without requiring detailed knowledge of the underlying data structures actually stored in the NetWare bindery.
Provide a simple interface to object data not actually stored in the bindery, such as login scripts.
Provide a similar interface to that presented by the NW DS Data function category, a component of the ALM set which provides support for NDS.
Use the security inherent in NetWare in restricting access to certain bindery objects, object properties, and operations.

Specifying the NetWare Server

Many of the functions in the NW Bindery function category require an input parameter of type NW Server. This parameter is used to identify the specific NetWare server the application wishes to communicate with. Most of the functions in the NW Bindery function category require that a specific server name be identified in the NW Server object, and will override the use of the primary server. A NetWare server name can be specified in the following ways:

Initialization at design time by using the NW Server object editing dialog.
Calling the "Set Server Name" function in the NW Server function category from an executing application.
Calling the function "Get Primary Server" of the NW Client function category from an executing application.
Calling an AppWare function which uses the ONWSrvrSetName(...) NW Server object API.

Specifying Bindery Object Type

Each object in the NetWare bindery has an associated object type. The most common object types include user, user group, print queue, and print server. For ease of use, text strings have been associated with the standard set of bindery object types. The most commonly used object type name strings are described in Table 5. The object type name strings listed in the first column of the table can be used when a bindery object type is required. The type number may also be specified, by entering the hexadecimal value of the object type number, preceded by the characters 0x (zero-x).

Table 5: Common bindery object types.

Object Name String	Number	Notes
All	0xFFFF	Matches all bindery object types.
Advertising Print Server	0x4700
Archive Queue	0x0800
Archive Server	0x0900
File Server	0x0400
Job Queue	0x0A00
Job Server	0x0500
Print Queue	0x0300
Print Queue User	0x5300
Print Server	0x0700
User	0x0100
User Group	0x0200

By using the "Assign Type Name" function in the NW Bindery function category, additional object type name strings can be created and associated with specific object type numbers. This function creates a file with an extension name of INI. The name and location of the INI file can be specified as input parameters to the function, with the default name of ALM_BIND.INI and default location of the current Windows directory used if not specified.

The contents of the INI file are loaded when the "List Object Types" function in the NW Bindery function category is called. Any type name strings present in the INI file are also used in the results of the function "List Objects," but only if the "List Object Types" function has already been called.

Specifying Bindery Object Names

Each bindery object has an associated object name. Functions in the NW Bindery function category that require an input parameter of type NW Server require the associated text objects to contain the name and type of a specific bindery object. The "List Objects" function also expects an object name to be specified, but as an input parameter of type text rather than of type NW Server.

When specifying an object name filter to the "List Objects" function, the wildcard characters * and ? (asterisk and question mark) can be used. The asterisk matches any sequence of remaining characters; the question mark matches any single character value.

Specifying Bindery Property Names

Each object in the NetWare bindery may contain zero or more associated properties. Each property contains additional information which helps to define and describe the bindery object. The NW Bindery ALM simplifies access to the properties of a bindery object by assigning descriptive strings to the most commonly referenced properties. Consult the NW Bindery ALM online help file for details about the various property name strings that can be used. The NW Bindery ALM exposes three types of properties associated with NetWare bindery objects:

Complete properties as they appear natively in the bindery. Examples of this type of property include group membership lists and security equivalence lists.
A field in the data structure of a native bindery property, which is exposed as a property by the NW Bindery ALM. Examples of this type of property include the date and time of the last login, password expiration date, and account expiration date. These properties all are fields in native bindery properties.
Data not actually stored in the bindery but directly associated with a specific bindery object. Examples are the DOS and OS/2 login scripts associated with a bindery user object.

Listing Properties of a Bindery Object

To list all of the properties associated with a specific bindery object, the following sequence of events should be followed:

In the object editing dialog of a NW Bindery object, associate the object name and type fields with appropriate text objects.
Set the values of the text objects, associated in step 1, so that a specific bindery object is identified. The object name value should not contain wildcard characters and the object type value should not contain the string "All."
Invoke the "List Properties" function in the NW Bindery function category, specifying the appropriate NW Server object as an input parameter. This function returns the list of all properties for the bindery object into the table object specified as an output parameter to the function.

Retrieving and Setting Values of Bindery Properties

Each bindery property can be represented in one or more ways, closely resembling the common AppWare object types. The function "Property Supported" should be used to determine the preferred data type and corresponding functions to use to retrieve and set the value for a specific bindery property. Table 6 describes the various functions in the NW Bindery function category which relate to setting and retrieving bindery object property values.

Table 6: Bindery property data types

Data Type	Description	Functions
Text	Used to store and retrieve values of properties of bindery objects which can be represented using a text AppWare object.	Get Text PropertySet Text Property
Number	Used to store and retrieve values of properties of bindery objects which can be represented using a number AppWare object.	Get Number PropertySet Number Property
Table	Used to store and retrieve values of properties of bindery objects which are best represented in a multiple row, multiple column table AppWare object.	Get Table PropertySet Table Property
Date/Time	Used to store and retrieve values of properties of bindery objects which contain date and time values.	Set Date/Time PropertyGet Date/Time Property
Time	Used to store and retrieve values of properties of bindery objects which contain time values, without a reference to a specific date.	Get Time PropertySet Time Property
Network Address	Used to store and retrieve values of properties of bindery objects which refer to network addresses.	Get Net Addr PropertySet Net Addr Property
Stream	Used to store and retrieve values of properties of bindery objects which cannot be represented using any of the other AppWare object types, as described above.	Get Stream PropertySet Stream Property

Sample Project

A sample AppWare application which lists all of the bindery objects which match a specified name filter and object type filter will now be described. This sample application is named LISTOBJ.PJT, and is distributed with the NW Bindery ALM.

Object Instances Required

To develop the application, a total of seven AppWare objects are used. Figure 3 displays the object group from the sample application, while Table 7 describes each of the objects used.

Figure 3: Sample project object grouping.

Table 7: Sample project object descriptions.

Name	AppWare Object Type	Description
Main Window	Window	The main visual window of the application.
Obj Type List	List	Will contain the list of all valid bindery object type strings, after the function AList Object Types@ is called.
NW Server	NW Server	Used to specify the NetWare server to communicate with.
Object Type	Text	Will contain the text value of the current selection in the AObj Type List@ object.
Object Table	Table	Will contain the list of all bindery objects which match the search criteria established in the AObj Name Filter@ and AObj Type@ text objects.
Obj Name Filter	Text	Contains the object name filter which will be used to select which Bindery objects will be displayed. This value will initially be set to an asterisk, which means show all objects regardless of name.
Server Name	Text	Contains the name of the NetWare server to which we will be communicating.

Program Logic

The sample project contains a single subject window. Figure 4 contains the program logic from the subject window.

The specific functions utilized by the application are described below, with each step being labelled in Figure 4 with the step number enclosed in a diamond.

Determine the current primary server in response to the "Opened" signal from the window object. This is accomplished by calling the "Get Primary Server" function in the NW Client function category. This function has two optional parameters, an NW Server object and a text object to contain the name of the primary NetWare server for the client workstation.
Determine the list of known bindery object types by calling the "List Object Types" function from the NW Bindery function category
Call the "Set Selection" function in the List function category to select the first value, "All", from the list object which was initialized by calling the "List Object Types" function.
Change the cursor to an hour glass. Querying for all bindery objects over a slow WAN connection may take several seconds, so it is wise to inform the user that something is happening.
Display objects matching the criteria established by the object name filter and object type filter text objects. This is accomplished by calling the "List Objects" function in the NW Bindery function category.
If the list of bindery objects was properly generated, the "Sort Ascending" function from the Table function category is called to sort the table by the first column, object name.
Return the cursor to the arrow.

Steps 4 through 7 are also repeated anytime the object type filter or object name filter text objects are changed.

If the server name text object is changed, the "Set Server Name" function in the NW Server function category is called and steps 4 through 7 are repeated.

Figure 4: Sample project program logic.

The main window from the running application is shown in Figure 5. If any of the fields along the top of the window are changed, the contents of the table object will be updated to reflect the new values. In the second column of the table object is displayed the bindery object type. Type name strings defined for common bindery object types and any strings associated with object type numbers by using the "Assign Type Name" function will be displayed in column two. Any other object types will be displayed as a hexadecimal value, preceded by the characters 0x.

This application only allows specification of the object type filter from a drop down list box, which is populated by calling the "List Object Types" function. More sophisticated applications may wish to provide a multiple selection mechanism to allow filtering by several object types or a text object to allow specification of the hexadecimal value of an bindery object type.

Figure 5: Sample project main window.

NetWare 4 and the NW Bindery ALM

NetWare version 4 servers natively support NDS instead of the NetWare bindery. NDS offers many advantages over the bindery, including hierarchical structure, global naming, and replication. The NetWare bindery is supported on NetWare version 4 and later servers for backward compatibility, but most modifications should be made using NDS. As a result, certain functions are not allowed on NetWare servers which are natively supporting NDS.

In addition, operations, such as the "Create Object" function, on certain standard objects types (user, user group, print queue, print server) are not allowed to be performed using the NW Bindery ALM on NetWare servers which natively support NDS. Consult the function documentation in the NW Bindery help file for any restrictions on a specific function of interest.

Some general guidelines are given below for how to determine if a specific NetWare server should be communicated with using the NDS ALMs or the NW Bindery ALM. More detailed information is also available in the online help file for the NW Bindery and NW Server ALMs.

The "Native Bindery ?" function in the NW Server function category can be used to determine if a server should be communicated with using the NDS ALMs or the NW Bindery ALM.
When communicating with a NetWare version 4 server, use the NW DS Data object and function category to create and manipulate objects and their properties. This is enforced by the NW Bindery ALM for the object types user, user group, print queue, and print server.

Differences from The NW DS Data ALM

While the NW Bindery ALM was designed to provide an almost identical functional interface to that provided by the NW DS Data function category, there are some important differences:

The "Set... Property" functions in the NW Bindery function category immediately write the value(s) to the NetWare bindery, if successful. The NW DS Data object stores all changes until the "Modify Object" function of the NW DS Data function category is called.
The various "Get... Property" functions in the NW Bindery function category can be called directly, without the need to first call a function similar to the NW DS Data function "Read Object."
The NW Bindery ALM has two additional functions for retrieving and setting property values, "Get Stream Property" and "Set Stream Property." These functions utilize the Data Stream ALM to manipulate data which cannot be represented using the other AppWare object types. These functions will likely be added to the NW DS Data function category at a later date.

How To Obtain the ALMs

The AppWare Loadable Modules described in this article are currently in beta testing and should be available for public distribution shortly. The ALMs are expected to be distributed through the following means:

The NetWire forum on CompuServe and the Internet mirror of NetWire accessible on ftp.novell.com and www.novell.com.
The AppWare Technical Support BBS. Consult the technical support pamphlet which accompanied the AppWare product for the telephone number.
A future AppWare Loadable Module update release.
A future edition of the NetWare Support Encyclopedia in the software updates section.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.