********************************************** ********************************************** Novell Professional Developer B U L L E T S ********************************************** FEBRUARY 1993 Volume 5 Number 2 ********************************************** ********************************************** ********************************************** ********************************************** MAD'S COLUMN ********************************************** ********************************************** Hello and welcome to the February 1993 issue of Bullets! A question of concern that I have heard lately pertains to the distinction between and the futures for the NetWare Client SDK and the NetWare C Interface SDKs (DOS, Windows, OS/2 and Macintosh). Currently, each of these products are available to members of the Professional Developers' Program. The more mature NetWare C Interface SDKs are being combined, along with additional functionality for awaited NetWare 3.x "fconsole" services and NetWare 4.0 services, into the NetWare Client SDK. (Other OS libraries will be added in the next release of the NetWare Client SDK.) The NetWare Client SDK is currently in its "Early" release stage and is not yet as complete as the existing NetWare C Interface SDKs. In anticipation of the NetWare Client SDK being upgraded from "Early" to "Evolving" in the SDK Grading System, our plan is to release it following the release of NetWare 4.0. Novell is committed to producing an SDK with one common interface -one solution for all platforms. Accomplishing this goal means the gradual replacement of the NetWare C Interface SDKs' library sets. Support for these SDKs will be provided for one year once each product has been discontinued. I hope this information assists you in purchasing and using these products. Happy_Programming! Mad Poarch Director Developer Support/Service ********************************************** ********************************************** ARTICLES: Messaging Demystified: An Overview of NetWare MHS ********************************************** ********************************************** As networks and organizations become more geographically distributed, there is an growing need to utilize store-and- forward technology. Known more commonly as "messaging," store-and-forward technology yields many benefits including control of network traffic, reduced telephone costs, better interpersonal information flow, and more efficient use of computing resources. With these benefits, messaging presents an important form of client/server communication you should keep in mind when designing and developing applications. This article provides an introduction to the different applications messaging technology, discusses Novell messaging solutions, and describes the Novell API that developers can use to build messaging-based solutions. ********************************************** Applications of Messaging Technology ********************************************** Many people think of messaging as electronic mail, but this is only one of many different applications of messaging technology. This misperception is due to the high visibility of this person-to-person form of store-and-forward technology. Messaging is actually the process of "deferred delivery" of any type of data or information between two or more cooperative end-points. After submission to the messaging system, the forwarded data or information is consumed by a person or a process at some point in the future. When received, the message might trigger the start of some automated process or it might simply update someone on important information. This deferred delivery can be used like any other form of interprocess communication where store-and-forward properties can be used to their advantage. While direct communication links generally come to mind when designing a client/server application, many business solutions do not require on-line communications to complete a task. In many situations the completion of a task can occur within some reasonable time, which might be minutes, hours, or even up to a day or two later. In these situations, asynchronous processing can be triggered by using a store- and-forward messaging system to send a set of instructions from a client application to some messaging-aware service. Four Categories of Messaging There are four categories of messaging solutions. These include: * Person-to-person * Person-to-process * Process-to-person * Process-to-process Person-to-person messaging involves the transmission of information between people. E-mail is the best example of this type of messaging in which the message content might be text and/or binary attachments that may have been generated by a word processor or spreadsheet. With person-to-process messaging, a person submits a message to a process which might cause the process to perform some action. An electronic library from which a person can request library documents is an example of this form; when the library receives the request the document is returned. With process-to-person messaging, a process sends a message to a person in an automated fashion. An example of this form of messaging might be a financial report system that creates a report at pre-defined intervals and sends a copy of the report to various people. Process-to-process messaging is another form of interprocess communications (IPC) in which one process sends information or requests to another process. An example of this would be database synchronization from a central system to remote databases for data that does not require real-time-access. More specifcally, it might include the automatic transmission of sales data from remote sites to a central accounting system in order to tally daily sales worldwide. Architectural Model of a Messaging System Another commonly misunderstood aspect of messaging is the architectural model of a messaging system. Figure 1 shows a simple layer diagram of a messaging system and the relationship of the components. ********************************************** FIGURE 1: Relationship of messaging system components |--------------------------------------------| | Messaging | | Application | |--------------------------------------------| | Application Programming | | Interface (API) | |--------------------------------------------| | | | | | Messaging | Routing | Management | | Directory | & Delivery | | | | | | |--------------------------------------------| END of FIGURE 1 ********************************************** At the top of the diagram is the messaging application. This level defines the message content and rules for submitting and processing the information exchanged through the underlying delivery system. Any process that does not require an immediate response can be defined according to a set of application-specific rules, and then be implemented on the underlying delivery system. The application level gains access into the delivery system through a set of APIs. These APIs grant the application access to a variety of messaging services, including directory services and message routing/delivery. Recently, there has been some confusion between the distinction of a messaging API and the delivery system itself. Although it is subtle, the selection of the API does not always dictate which messaging service is used. In fact it is quite possible to support a number of APIs concurrently over a common delivery service providing the delivery system is robust and comprehensive. However, selecting an API that is closely associated with the underlying messaging system can result in more complete access to the underlying richness of the messaging service. In the context of messaging, the directory is primarily a store of known addresses for potential message recipients and may contain routing information used by the messaging "engine" for message delivery. Typically applications use this directory store to select recipients' messaging addresses. One of the most important features of a directory is that synchronization of content is managed in an automated manner concurrently with normal message delivery. This ensures directory consistency, enhances reliability and robustness, and offers cleaner and less labor-intensive administration of multiple messaging servers. Non-automated synchronization or off-line synchronization results in system message downtime and added administrative overhead. Message delivery and routing is the most important and ideally the most invisible service to the application level. Among its many tasks, the messaging system expands distribution lists, canonizes messages, determines appropriate routing, communicates with other messaging servers over asynchronous or network connections, delivers the messages, and generates delivery and non-delivery notifications. If the delivery system is robust and reliable, the details at this level are transparent to the application (as they well should be). It is also important that the messaging system provide a thorough set of messaging semantics to support interoperability with any other messaging systems that might be in use. A weak implementation results in lost information during gateway translation. The manageability, configurability, and robustness of this layer are also critical to facilitate application needs. Flexibility in configuring forwarding intervals, durations, etc., facilitate coarse deterministic behavior which might be a requirement for certain applications (e.g. one hour or less delivery required), and it also facilitates more efficient use of expensive links and CPU resources. As such, the management tools for the delivery system must be complete as well. ********************************************** Novell Messaging Solutions ********************************************** Novell provides a family of messaging solutions that enable a variety of applications to leverage this technology. These solutions are based upon a core set of technology called NetWare Message Handling Service (MHS). NetWare MHS forms the delivery system for application use. In relation to the architectural model described earlier, NetWare MHS forms all of the services beneath the API, has a native API (discussed below) and can support alternate APIs. While there are over 150 commercially available products spanning e-mail, fax service, forms processing, scheduling/calendaring, and workflow, there are hundreds of corporate IS applications which are designed to use NetWare MHS for other business needs. NetWare MHS solutions are tailored for the various environments which require messaging. NetWare Global MHS provides comprehensive messaging services that are highly integrated with the NetWare 3.x and 4.0 operating systems. This NLM-based solution has the advantage of enhanced management control for both centralized and decentralized organizations. Because NetWare Global MHS is well integrated with NetWare and is based upon the existing services included in NetWare, many of the administrative functions are inherited from existing management of current NetWare services. Two of the key features of NetWare Global MHS are on-line directory synchronization and protocol module support. Directory synchronization allows a collection of cooperating messaging servers to synchronize their directories of "mailboxes" and message routes while the messaging system is up. This reduces administrative requirements and increases system reliability. Add-on protocol modules allow NetWare Global MHS to cleanly integrate with other messaging technologies including SNADS, SMTP, and X.400 environments. Protocol module integration also enables directory synchronization between SNADS hosts and UNIX-based SMTP servers, and it allows messaging "tunneling" so that non-MHS-based backbones can transport MHS messages without multiple message translations (common to today's gateway solutions). The richness of messaging semantics also has resulted in connectivity to virtually every messaging system through third-party gateways. For NetWare 2.x, NetWare Lite, and mobile DOS users, DOS- based NetWare MHS solutions offer message delivery that fully interoperates with NetWare Global MHS. NetWare MHS is also available as a "local delivery" solution (NetWare Basic MHS) providing identical message submission and delivery services for a collection of mailboxes residing on a single volume. ********************************************** Novell's Standard Message Format (SMF) API ********************************************** Messaging applications gain access to the NetWare MHS delivery system through a file-based API called Standard Message Format (SMF). While alternate messaging APIs such as VIM, MAPI, OCE and CMC can be supported over NetWare MHS, SMF is the native API to NetWare MHS. As a result, applications developed to this API will have full access to the functionality offered by the messaging system. Because it is a file-based API, SMF has a number of important characteristics. Three key benefits include cross-platform support, code efficiency, and the ability to utilize messaging from any environment capable of creating a structured text file. SMF presents an identical API for use on DOS, Windows, OS/2, Macintosh, and UNIX. As the API evolves to include future functionality, new features are immediately available to all platforms without dependence on functionally. Since an application specific subset of SMF can be chosen, applications are not burdened with the additional overhead of unnecessary code that might otherwise be included via a library. Finally, development can occur from a variety of environments such as spreadsheet macros, batch files, UNIX script files, or any high level language. SMF is a simple API, but it offers access to several very comprehensive optional services. Simple applications can send a message with as few as three text lines, or send any file attachment with as few as four text lines. At the other end of the spectrum, SMF enables sophisticated application and gateway development which can support advanced features such as: * Up to 64 attachments with file-type notification and file date(s) * Message importance indication * Message sensitivity indication * Unlimited recipients * Message expiration indication * Blind CC * Message forwarding * Efficient form transmission * Return receipt notification on delivery and message read The SMF API consists of a set of text verbs (headers) which are separated from parameters by a colon (:). The textual parameter content and number of parameters is dependent upon the header. There are over 50 standard headers defined in SMF, and SMF includes the ability to expand the verb-set through the use of "OEM" defined headers. The examples in Figure 2 show a simple person-to-person text message and a person-to-process attachment transmission. ********************************************** FIGURE 2: Example SMF messages Example A: Person-to-process messaging SMF-71 To: Documentation Library @ Marketing.California.Haley Corporation From: J P Herriman @ Marketing.New York.Haley Corporation Subject: STORE AS: New Collateral Attachment: brochure Example B: Person-to-person messaging SMF-71 To: J P Herriman @ Marketing.New York.Haley Corporation From: S D Becker @ Sales.California.Haley Corporation Subject: New Collateral Comments The new collateral you sent is very useful. These have contributed to a 50% increase in sales just this month! Thanks! END of FIGURE 2 ********************************************** In example A, J. P. Herriman is sending a brochure as an attachment to a message. The brochure is being sent to a library service which uses "STORE AS:" in the subject line as a command to save the attachment in the library under the specified name. This is an example of person-to-process messaging. In person-to-person messaging example B, S. D. Becker is sending J. P. Herriman a simple e-mail message commenting on a sales success, after using the brochure from the library. To develop an SMF-based application, only two tools are required. The SMF Programmer's Reference defines the syntax and use of the message headers and a NetWare MHS delivery system provides the test environment. No compilers, linkers, or libraries are necessary although sophisticated applications may find a high-level language useful. Simpler applications might only require batch file creation or application macro development. Using the messaging system requires at least four key phases: 1) Message creation, when an SMF-formatted file is created 2) Message submission, when the SMF file and any attachments are copied into a standard directory structure which is accessible by the NetWare MHS server 3) Message delivery is transparent to the application when NetWare MHS picks up the message from the directory and forwards it on to the destination mailbox (a directory that is associated with the specified messaging address) 4) Message receipt and processing, when the message and any attachments are extracted from the recipient "mailbox" directory structure. In this example, an SMF formatted message is created. Its associated attachment is copied into the vol:\mhs \mail\parcel directory and then the SMF file is copied into the vol:\mhs \mail\parcel\snd directory. The NetWare MHS engine recognizes the presence of the files, parses the SMF file to determine proper routing, and forwards the message to another NetWare MHS engine. This engine determines that the recipient is for a local mailbox and delivers the attachment file to the vol:\mhs\mail\user\bharris\iparcel directory, and sends the SMF file to the vol:\mhs\mail\user\bharris\mhs directory. ********************************************** For More Information ********************************************** This article provides a good introduction to messaging development using SMF to access NetWare MHS services. For more information, obtain a copy of the SMF v71 Programmer's Reference through Novell Literature Fulfillment by calling 1- 800-NETWARE and requesting part number 100-0001213-001. Registered Novell developers can also obtain the SMF v71 Software Developer's Kit for MHS by contacting the Novell Professional Developers' Programsm at 1-800-NETWARE or 1-801- 429-5588. ********************************************** ********************************************** ARTICLES: Writing 32-bit OS/2 Apps in the NetWare Environment ********************************************** ********************************************** Novell's NetWare OS/2 Developer's Kit v2.0 and the NetWare Client SDK open up the world of NetWare to OS/2 application developers. These SDKs allow you to design and implement applications that are compatible with OS/2 v2.0, the 32-bit version of IBM's multitasking operating system. While 32-bit users appreciate the better performance and flexibility of OS/2 v2.0, application developers have a more complex task when adapting projects to this new version of the operating system. One situation that requires special handling is when a development project involves the use of 16-bit APIs (like Novell's) in a 32-bit application. Such cases require special techniques like thunking to translate 32-bit addresses for variables, so they can be used inside 16-bit APIs. The APIs provided with the NetWare Client SDK and the NetWare OS/2 Developer's Kit are 16-bit functions. This article presents several examples to outline the requirements for and limitations on using these 16-bit APIs in 32-bit OS/2 v2.0 applications. ********************************************** Overview and Definitions ********************************************** In the OS/2 environment, references to 16-bit versus 32-bit usually denote the number of bits used to store an address. 16-bit addresses follow the older Intel 8086 format, in that the addresses consist of two words (each 16 bits in length), a segment word, and an offset. Together, these components create a physical memory address for either a function call or data variable. This addressing method limits the largest address within any given segment to be less than 0xFFFF or 64K. The largest data object referenced by a 16-bit address must also be less than 64K in order to be addressed by one segment. 16-bit addressing is often referred to as "tiled" memory. 32-bit applications overcome this limitation by using "linear" memory. A linear address is one 32-bit long word that maps directly to a memory location up to 4GB. 32-bit addressing requires the use of microprocessors with 32-bit registers, such as the Intel 80386 and 80486 chips. Faster processors and faster data access (because there is no need to translate tiled addresses) make 32-bit programming desirable. OS/2 v2.0 anticipates the need for running 16-bit applications in 32-bit mode. It handles this situation through the use of Local Description Tiling (LDT), which maps the two different types of addresses in a manner that is transparent to the application as it is running. Requirements for Mixed-Address Programming Successful mixed-address programming requires that all variables be translated before they are used by the addressing scheme in effect. This rule applies to both functions and data. From 32-bit OS/2 code, 16-bit function calls must be declared 16-bit using #pragma statements or special type declaratives. Further, if these 16-bit functions use pointers as formal parameters, these pointers must be converted to 16-bit addresses prior to making the function call. In some cases, a compiler will create a pointer to a variable of a size corresponding to the default addressing scheme in effect; e.g., a 32-bit pointer will point to a 32-bit variable (unless specifically cast) and a 16-bit pointer will point to a variable type modified as 16-bit. In particular, automatic variables, which are allocated on the program stack, will be allocated by default as 32-bit because the stack is allocated with the code in one 32-bit section. A non-typed pointer to these variables will be a 32-bit address. Static or external variables may be 16-bit if mixed addressing has been enabled. Limitations of Mixed-Address Programming One caveat of mixed-address programming is that you must be aware of the actual amount of storage referenced by any pointer that will be translated to a different address size. 32-bit pointers can reference large portions of memory, but when they are tiled onto 16-bit addresses, the pointers are reduced to a maximum usable storage size of 64K. The pointer will be properly aligned to the start of the segment, but data beyond 64K will be inaccessible to the APIs. If pointers referring to a data buffer larger than 64K are passed to the APIs, inconsistent results will occur. ********************************************** Using 16-bit NetWare OS/2 Libraries ********************************************** Preparing your code for compiling is the most time-consuming part of using 16-bit libraries. Each external function call in a 16-bit library must be declared as such by thunking the external reference. If any pointers are passed as formal parameters to these functions, the pointers must also be thunked. Each OS/2 compiler handles thunking differently. The net result is a macro translation or function call that will modify how the machine code addresses the reference. The examples provided in this article use IBM's C/SET2 Compiler. (Ed. Note: At the time of this article, only the C/SET2 compiler was available for testing. Other 32-bit compilers for OS/2 like the WATCOM C compiler and Borland's C++, are available. Results and examples for these compilers are available on CompuServe in Novell's NOVDEV forum.) Modifying the 16-bit APIs In The Design of OS/2, authors Deitel and Kogan define a thunk as a "layer of procedures that takes 16-bit API requests, converts them into 32-bit requests, issues the requests, and then completes the API return condition with 16-bit semantics" (p. 97). Thunking is therefore the process of making a 16-bit API function like a 32-bit API. The examples in this article demonstrate how this conversion can be achieved from within the NetWare Client SDK and OS/2 Developer's Kit v2.0 header files. The CSET/2 compiler uses the _Seg16 type modifier to declare a 16-bit pointer. The _Seg16 type modifier may only be used on a pointer. To declare a 16-bit function, CSET/2 uses the _Far16 type modifier; the #pragma seg16 statement has the same effect by declaring a data object that can be accessed by 16- or 32-bit code. The most efficient way to handle the function declaration change is to modify the header files to include the thunking information whenever the files are in use by a 32-bit compiler. Using a macro definition to trigger a conditional compile is a common method. The code in Figure 3 demonstrates the necessary modifications to implement this definition. *********************************************** FIGURE 3: Header modifications to automatically include "thunking" information #ifndef IS32BIT // we are not using 32-bit code, so undefine // the thunking types to avoid compiler errors #define _Seg16 #define _Far16 // define the default external function type #define API extern WORD far pascal #define DWAPI extern DWORD far pascal #else // 32-bit code is in effect, check the compiler type #ifndef CSET2 // for now, we are only using the CSET compiler // so undefine the types if another is being used #define _Seg16 #define _Far16 // default linkage is just far pascal #define API extern WORD far pascal #define DWAPI extern DWORD far pascal #else // CSet/2 compiler already has _Seg16 and _Far16 // defined, leave them alone. // default far linkage is 16-bit #define API extern WORD _Far16 _Pascal #define DWAPI extern DWORD _Far16 _Pascal #endif #endif END of FIGURE 3 *********************************************** The method shown in Figure 3 requires that two macros be defined in order to activate the 16-bit thunking: IS32BIT and CSET2. The IS32BIT macro will signal that mixed address code is in effect. Inside this #ifdef statement, thunking definitions for several compilers may be included. The CSET2 macro defines which compiler is in use. Since the thunking syntax may change from compiler to compiler, there must be a #if test to define the 16-bit types and function linkage. This conditional code can be inserted in the first API header file to be included (NWCALLS.H or NWCALDEF.H). The code will define a macro API that expands into the external function linkage type for each API function call. The function declarations themselves must also be modified to be of return type API. For example: API NWRemoveJobFromQueue( WORD connID, DWORD queueID, WORD JobNum); The _Seg16 and _Far16 keywords must also be defined. In the case of the CSET/2 compiler, these macros are left unchanged. However, if you are not using a 32-bit compiler, or if the compiler syntax differs from that of IBM's CSET/2 compiler, these keywords must be changed to match the thunking semantics for the other compiler. In addition to handling the 16-bit linkage, the API headers must also be modified to declare any pointers passed as formal parameters to be 16-bit pointers. This can also be done with the _Seg16 keyword, as shown below: API NWCreateQueueFile(WORD connID, DWORD queueID, QueueJobStruct far * _Seg16 job, WORD far * _Seg16 fileHandle); Notice that both the far and _Seg16 type modifiers are included. In 32-bit code, the far type modifier has no effect. With a 16-bit compiler, the _Seg16 type modifier is undefined. This situation is consistent with the goal of being able to share these header files between different compilers and target addressing schema. To complete the thunking procedure, data structures which may be declared in the 32-bit code and passed either by value or reference to the APIs must be modified so that any pointer variables use the _Seg16 type modifier. This following structure, from the SPX services, provides an example of the changes you should make to the data structure definitions: typedef struct { VOID FAR * _Seg16 fragAddress; USHORT fragSize; } SPXECBFrag; Note that using the #pragma seg16 directive for the struct, as in: #pragma seg16(ECBfrag) SPXECBFrag ECBfrag; will declare the structure as a 16-bit data item, but will not modify the pointers within the structure. Calling 16-bit APIs The modifications described above to the header files encompass the necessary changes to create thunks for each API. The use of these thunked APIs is not totally transparent, however. Certain precautions are required when using thunked APIs; in order to successfully use thunked APIs, the calling side must properly convert parameters and abide by the 64KB size restriction. As mentioned before, parameters that are passed into 16-bit APIs must be of a type compatible with 16-bit addressing. Pointer variables must be 16-bit addresses; they can be explicitly declared as 16-bit addresses through the use of the _Seg16 modifier. If the pointer is created dynamically (i.e., through the "address of" symbol (&)), its address type will be equivalent to the model in effect. That is, if a pointer to a variable is created by using its address, the address size will reflect the model in effect when the variable is declared. If the variable is an automatic variable, its reference will be a 32-bit pointer, since the stack resides within a 32-bit function. An effective solution is to declare an automatic variable of type _Seg16 and assign it to the reference created through the use of the "address of" symbol (see Figure 4). *********************************************** FIGURE 4: Automatic pointer thunk example extern funct16( WORD FAR * _Seg16 Point16); funct32(void) { WORD FAR * _Seg16 addr; WORD theVariable; // instead of: funct16(&theVariable); // use: addr = &theVariable; funct16(addr); ... END of FIGURE 4 *********************************************** Alternatively, there may be a compiler switch that signals that mixed addressing is being used. With the CSET/2 compiler, this switch is "/Gt+." When you use this switch, external and static variables are 16-bit, automatic variables are 32-bit. References to these variables via the "address of" operator are 16-bit pointers. You could then call the above function, as shown in Figure 5, which is somewhat simpler. *********************************************** FIGURE 5: Static pointer thunk example extern funct16(WORD FAR * _Seg16 Point16); WORD Var16; funct32(void) { funct16(&Var16); ... END of FIGURE 5 *********************************************** This second approach may work better for the NetWare APIs, since there are a number of variables that are passed by reference which are also shared between most of the APIs (e.g., ConnectionID). When writing mixed-address NetWare applications, pay attention to the data item size. In most cases, the compiler will correctly translate a huge data object to a 16-bit address, so that it begins at the start of a data segment and continues allocating across as many segments as required by its size. However the APIs in the NetWare libraries make no provisions for crossing segment boundaries. Therefore, with buffers less than 64KB in size that are passed to NetWare APIs, only the first 64KB of data will be used. ********************************************** Compiling Mixed-Address Applications ********************************************** The IBM CSET/2 compiler has several switches or #pragmas available which must be set to properly compile 32-bit code which references 16-bit APIs. These switches control stack options and sizes, structure allocation and dynamic memory handling with mixed addresses, as well as the default variable size switch already mentioned (/Gt+). Stacks A stack option enables a 16-bit stack, as well as the default 32-bit stack. This 16-bit stack will be allocated statically at runtime for use with calls to 16-bit APIs. The correct syntax for creating a 16-bit stack is: #pragma stack16 where "" is the value in bytes and must be between 512 and 65532. The default size is 4K. Structures Pay close attention to alignment within the structure. Structures in 32-bit models are aligned on double word boundaries, while 16-bit models align structures on word boundaries. The NetWare APIs expect structures to be aligned on byte boundaries. Once again, this requirement can usually be met with a compiler switch. IBM's CSET/2 compiler uses #pragma pack , where the size is 1, 2 or 4. The#pragma statements remains in effect from when the statement is encountered during compilation until the next #pragma pack statement, or the end of the code unit. In order to have the structure similarly aligned for use with the NetWare APIs, include the statement, #pragma pack 1 early in the compilation cycle (for example, in the first NWCalls header file). Alternatively, you can use the "/Sp" compiler switch. Memory Allocation If you allocate memory dynamically for buffers that you are going to pass to 16-bit APIs, make certain that the memory allocation routines create the buffers so that they will not cross segment boundaries. With the CSET/2 compiler, this option is again set with the "/Gt+" switch, which enables _tcalloc, _trealloc and _tfree for use in creating 16-bit compatible buffers. ********************************************** Linking Mixed-Address Applications ********************************************** Overall, there are no specific requirements for linking mixed-addresses applications, once you have created the appropriate object code. Still, when selecting C libraries, pay attention to availability of necessary OS/2 APIs. IPX/SPX Communication Services under OS/2 and its dependents (as well as Novell's implementations of NetBIOS and Named Pipes) make use of 16-bit semaphores. When linking these types of applications, the migration libraries which contain 16-bit semaphores should be used (i.e., OS2386.LIB which comes with IBM's CSET/2 compiler). ********************************************** For More Information ********************************************** Following these guidelines, the NetWare OS/2 Developer's Kit and the NetWare Client SDK allow developers to create 32-bit OS/2 applications that can take full advantage of the features of the NetWare operating system. For more information on the procedures described in this article or to request a set of thunked header files, please contact the Developer Support Group at 1-800-NETWARE or 1-801-429-5588. To purchase this SDK or any other Novell development tools, contact Novell Developer Relations at 1-800-NETWARE or 1-801- 429-5588. ********************************************** ********************************************** TECHNICAL INSIGHTS: New AIOCOMX.NLM Driver Available (Network C for NLMs v2.0 (d)) ********************************************** ********************************************** The December 1992 issue of Bullets reported that AIOWriteData() allows partial writes (Technical Insights, "AIOWriteData() Documentation Update"). This condition resulted from a problem with AIOCOMX.NLM, which has now been corrected. A new version of AIOCOMX.NLM is available that rejects partial writes and complies fully with the documentation. The new version can be downloaded from Novell's CompuServe forum NOVLIB (LIB 9, filename AIOX.ZIP). ********************************************** ********************************************** TECHNICAL INSIGHTS: Outer Joins on Computed Fields (NetWare SQL v3.0) ********************************************** ********************************************** When a CREATE VIEW statement is used to create a view with a computed field whose resulting type is an integer, that computed field is considered to be a four-byte integer. This is important when using this field as part of an outer (or null) join, since the data type and length of the join fields must match exactly for an outer join. For example, in the statement, CREATE VIEW Test (T1, T2) AS SELECT F1, 100 FROM Tbl1 the field "T2" is a four-byte integer containing the value 100. Consequently, the statement, SELECT * FROM Test, Tbl2 WHERE Test.T2 = Tbl2.fld(+) will only work if "Tbl2.fld" is a four-byte integer, and is also an index (or the first segment of an index) on table "Tbl2." Unless both of these conditions are met, NetWare SQL will return a status 220 (No Matching Index on Secondary Keys). Currently, a problem associated with NetWare SQL v3.0b causes the above SELECT statement to return an status 875 (Only a right Outer Join Is Supported), even if "Tbl2.fld" is a four- byte integer and an index. To alleviate this problem, create the view at the Relational Primitive level instead of using SQL statements. Use the xCompute function to specify the computed field, since the xCompute function has parameters that allow the application to specify both the type and size of the resulting field. In this case, the computed field can be created as either a two- or four-byte integer, whichever is needed for the outer join. ********************************************** ********************************************** TECHNICAL INSIGHTS: Using the T_MORE Flag with SPX Protocol (Network C for NLMs v2.0 (e)) ********************************************** ********************************************** When you call t_rcv(), one of the parameters passed is the size of the buffer that was passed. When this buffer is filled, t_rcv() returns. If the buffers for t_snd() and t_rcv() are exactly the same size, this is exactly how it should behave. In some cases, however , if t_rcv() has a larger buffer than t_snd(), one might expect t_rcv() to return after the first call to t_snd(), and not wait for the buffer to be filled by multiple t_snd() calls, but the actual behavior of the call depends on how the T_MORE flag. The T_MORE flag determines how the t_rcv() returns. If you call t_snd() with the T_MORE flag clear, t_rcv() will return with only a portion of its buffer filled. If you set the T_MORE flag, t_rcv() will not return, and will wait for more of its buffer to be filled. ********************************************** ********************************************** TECHNICAL INSIGHTS: Network C for NLMs Documentation Error (Network C for NLMs v2.0 (x)) ********************************************** ********************************************** The example program on Page 3-23 of the NLM Library Reference Volume 1 is incorrect. If executed as is, the custom data for the NLM, which is stored in the global variable, globalString, will be NULL. This problem results from an uninitialized global variable that is set to NULL before the program begins execution. The data is read into the globalString variable correctly, but this occurs before the uninitialized global variables have been set to NULL. When creating the globalString global variable assign a value to the string. Doing so will prevent the string from being set to NULL before the program executes. ********************************************** ********************************************** TECHNICAL INSIGHTS: Correct Usage of Btrieve Operation 42 (NetWare Btrieve (NLM) v6.0) ********************************************** ********************************************** The new NetWare Btrieve v6.0 operation 42, used to place Btrieve files into Continuous Operation mode (and return them to normal mode), can only be called from an NLM application. It cannot be called from a workstation application. If a workstation attempts to perform a Btrieve operation 42, NetWare Btrieve v6.0 returns a status 20 (Btrieve Not Loaded). NetWare Btrieve v5.x will return a status 1 (Invalid Operation). ********************************************** ********************************************** TECHNICAL INSIGHTS: NetWare System Calls Doumentation Update (NetWare System Calls for DOS v1.2) ********************************************** ********************************************** When a workstation calls VerifyNetworkSerialNumber(), if the networkSerialNumber parameter does not match the network's serial number, the calling workstation will lose its connection to the network. Although the documentation does not include this information, the function was intended to work this way. The return values are only valid if the match occurs and some other error causes a non-zero return code. The Btrieve v6.0 Developer's Kit Supplement includes a sample NLM application that demonstrates the proper usage of operation 42. Both the C source code and the compiled NLM are included. ********************************************** ********************************************** TECHNICAL INSIGHTS: Closing Temporary Socket in BeginDiagnostics() (NetWare C Interface for DOS v1.2) ********************************************** ********************************************** If you call BeginDiagnostics() multiple times, the 11th attempt fails when searching for a target. This occurs because BeginDiagnostics() does not close the temporary socket. To prevent failure of BeginDiagnostics(), modify the source code for DIAG.C as shown in Figure 6, so that IPXCloseSocket() is called when an error occurs. ********************************************** FIGURE 6: Required modifications to DIAG.C int BeginDiagnostics(destination, connectionID, componentList ) * * /* first open a socket then init receive ECB's */ tempSocket = (WORD)0x00; /* let IPX pick socket number */ ccode = IPXOpenSocket((BYTE)&tempSocket, 0); /* call to function */ if( (ccode = GetRemoteSPXSocket(destination,componentList)) != 0 ) Error = COULD_NOT_OPEN_SOCKET; else { for (i=0; i 0 will only update the first record having ID > 0, if ID is an index in the "Appointments" table. No other records will be updated. This situation was introduced by the NetWare SQL December patch release (v3.00b) and will be fixed in patch release v3.00c. Currently, the only workaround is to use NetWare SQL with the September patch release installed (v3.00a). ********************************************** ********************************************** TECHNICAL INSIGHTS: Mux Semaphores and SPX (NetWare OS/2 Developer's Kit v2.0) ********************************************** ********************************************** Under OS/2, if you issue a "wait" command on mux semaphores with one of the semaphores in the mux list being the ECB semaphore, the apparent result is that the ECB semaphore never clears. Actually, the semaphore is cleared and reset by SPX, but the application is never notified. This situation results in the "wait" never returning if it is set to "infinite." The situation does not occur with event or mutex semaphores. If you need to wait on more than one semaphore, create multiple threads that individually block one each on each semaphore. ********************************************** ********************************************** TECHNICAL INSIGHTS: File Level Access with Brequest v5.16 & v6.0 (NetWare Btrieve (NLM) v6.0) ********************************************** ********************************************** With Brequest v5.16, users are allowed to write to a Btrieve file if the user has "Write" access to the directory, even if the user does not have "Write" access to the file. This situation does not occur with Brequest v6.0, since Brequest v6.0 uses file-level access rather than directory- level access. If a user has "RWCEMFA" access to a directory but only "RF" (read and file scan) access to a file, Brequest v6.0 returns a status 94 (Permission Error) on the Open operation. "Supervisor" access to a directory works differently. If a user has "Supervisor" access, any file can be opened regardless of which requester is in use. "Supervisor" rights override all inherited rights masks in subdirectories and files. ********************************************** ********************************************** TECHNICAL INSIGHTS: Driver Load Order with LANSUP and OS/2 v2.0 (NetWare OS/2 Requester v2.0) ********************************************** ********************************************** When using the OS/2 driver LANSUP (the Open DataLink Interface that allows multiple protocols on an OS/2 machine from IBM), the order in which the drivers are loaded is different than if ODINSUP is used. If you load the drivers in the wrong order, one of three situations will result: * The machine fails to load the operating system. * The machine successfully loads the operating system, but reports numerous driver errors. * The machine sucessfullly initializes (without errors), but no NetWare services are available because the wrong protocols have been bound to the NIC. To avoid problems with LANSUP, load the drivers in CONFIG.SYS in the order shown in Figure 7. ********************************************** FIGURE 7: Correct driver load order when using LANSUP driver device=lsl.sys run=ddaemon.exe DEVICE=LANSUP.SYS device=ipx.sys device=spx.sys run=spdaemon.exe device=nmpipe.sys device=npserver.sys run=npdaemon.exe ... END of FIGURE 7 ********************************************** ********************************************** ********************************************** TECHNICAL INSIGHTS: Int 21 Function 3F Bug in NETX.EXE (NetWare Shell (NETX.EXE) v3.31) ********************************************** ********************************************** If a section of a file is locked with Int 21 function 5C00 and another workstation using that file tries to read from the locked area, the call appears to succeed, even though it should fail. The carry flag should be set and an error code should be returned in the AX register. The error code (5, in this case) is being returned, but the carry flag is not being set, so the contents of the AX register are processed as the number of bytes read rather than as an error code. In this case, it is impossible to tell if an error has occurred. This bug has been detected in v3.26 and v3.31 of NETX.EXE, and may exist in others versions. ********************************************** ********************************************** TECHNICAL INSIGHTS: Continuous Operations and File Logging (NetWare SQL v3.0) ********************************************** ********************************************** File logging and backups can both be used to rebuild Btrieve files after a system failure. However, file logging and Continuous Operations mode should never be used simultaneously. Btrieve v6.0 Continuous Operations mode allows continuous access to Btrieve files while the files are being backed up. When a file is open in Continuous Operation mode, the log file is still being updated. If you activate logging and place the file in Continuous Operations mode, at some point the file will no longer be synchronized with the log file. To illustrate, consider the following sequence of events: 1. A Btrieve file is backed up 2. File logging is activated 3. The file is modified (update, delete, or insert operation) 4. The file is placed in Continuous Operations mode 5. The file is modified again 6. Backup completes and the file is removed from Continuous Operations mode At this point, if a a backup was required, the backup from step 4 would be restored. The backup would reflect all the changes that were made in step 3. The log file, however, would contain both the changes made in step 3 and step 5. If you used the log file at a later date, you would be making the same modifications to the file and such duplication could result in errors. ********************************************** ********************************************** TECHNICAL INSIGHTS: ScrollScreenRegionUp() overwrites memory (Network C for NLMs v2.0 (e)) ********************************************** ********************************************** ScrollScreenRegionUp() can overwrite memory if used on line 0, with the title bar active.In other words, ScrollScreenRegionUp(0,1) while you have the key down will cause this to occur. If you scroll more than one line, the problem does not occur. To prevent memory overwrites, either write spaces to line 0, or always scroll more than one line. ********************************************** ********************************************** TECHNICAL INSIGHTS: XQL and .SHR Files (XQL for DOS v2.11) ********************************************** ********************************************** In the December 1992 issue of Bullets, "Handle Usage with User Rights & XQL Load" described how XQL creates and maintains a .SHR file. Another anomaly has been found regarding this issue. If XQL is patched so that it can be accessed from within Windows, and then is loaded from the WINSTART.BAT file, XQL's .SHR file is created in the user's current directory when Windows is started. Later, if a user opens a DOS session and tries to load XQL again from the same directory, one of two situations will occur: 1) If DOS SHARE was loaded before Windows, a Sharing Violation Error will be returned and XQL will not load. 2) If DOS SHARE was not loaded, XQL will overwrite the .SHR file already present with a new .SHR file. Subsequently unloading XQL from this DOS session will cause this .SHR file to be deleted, leaving the XQL that was loaded by WINSTART.BAT without an .SHR file to use. This situation will eventually cause status 202 or 821 (Invalid Cursor ID) errors to be returned. The previous situations occur only when the .SHR files are created on a local drive. If the current working directory is a NetWare drive, neither situation occurs; two .SHR files are properly created and maintained in the same NetWare directory. If using a local drive, either load XQL inside the DOS session from a different directory than the current working directory from which Windows was started, or specify an /x: parameter on the XQL load line pointing to a different directory. For more information on the /x: parameter, consult the December 1992 issue of Bullets. ********************************************** ********************************************** TECHNICAL INSIGHTS: Events Cannot Be Unregistered While In Progress (Network C for NLMs v2.0) ********************************************** ********************************************** When you register for an event "Down File Server", you provide it with a report procedure and a "warn" procedure to execute. If you attempt to call UnRegisterForEvent() for "Down File Server" in either of these functions, it will fail with a return code of (-1). You cannot call UnRegisterForEvent() while the event is occurring. In the case of the "Down File Server" event, it is unnecessary to unregister the event if the file server is going down. ********************************************** ********************************************** TECHNICAL INSIGHTS: min() & max() are Both Macros and Functions (Network C for NLMs v2.0 (d)) ********************************************** ********************************************** The functions min() and max() are defined as macros in STREAM.H, but are prototyped as functions in STDLIB.H. If STREAM.H is included before STDLIB.H, the compiler attempts to expand the prototype in STDLIB.H with the macro from STREAM.H. This situation results in syntax errors in STDLIB.H. To avoid problems, either always include STREAM.H after STDLIB.H, or modify STDLIB.H by replacing the prototypes with copies of the macro definitions from STREAM.H. ********************************************** ********************************************** TECHNICAL INSIGHTS: NWSTRM.H Header File Redefines delay() (Network C for NLMs v2.0) ********************************************** ********************************************** NWSTRM.H redefines delay() to be streamdelay() which takes ticks instead of milliseconds. Thus, a call to delay(55) will not delay for one tick, but will delay for 55 ticks. Currently, there is no "clean" workaround for this situation. Until further notice, call delay() from a module that does not include NWSTRM.H. Otherwise, you will need to modify the header file. ********************************************** ********************************************** TECHNICAL INSIGHTS: Blank Users Cause Security Problems (Xtrieve PLUS v4.1x) ********************************************** ********************************************** Recent versions of Xtrieve PLUS do not support blank users; if a blank user exists in the USER.DDF data dictionary file, then whenever Xtrieve PLUS is loaded, a status 205 (Invalid Password) will be returned. This error message is returned when Xtrieve PLUS logs into a set of .DDF files. Xtrieve PLUS first attempts an xLogin to the dictionaries. If a status 209 (Invalid User) is returned, Xtrieve PLUS attempts another xLogin, prompting for a username and a password. If anything other than a status 209 is returned on the first xLogin call, Xtrieve PLUS will not prompt the user for the username and password. When Xtrieve PLUS attempts its first xLogin call, it always passes a blank username and a blank password. Normally, this would return status 209 on a dictionary with security installed, but since there is actually a blank entry in the USER.DDF file, a status 205 is returned instead. Since Xtrieve PLUS does not trap for anything but a status 209 on the xLogin, the status 205 would be relayed to the Xtrieve PLUS user. It is interesting to note that XQLI will prompt for a username and password if security is installed on the data dictionary files, without attempting an initial XQLLogin call. XQLI will prompt the user for a password even if the user name is blank. So, the status 205 will not occur when logging in through XQLI, unless the password specified is actually invalid. To prevent the status 205, remove the blank user from USER.DDF using BSIM.EXE, B.EXE, or any utility that provides Btrieve or XQLP function calls. The .DDF files have Btrieve owner names defined for them when security is installed. The Btrieve owner name on the .DDF files is the same as the Master password specified when security was installed. You can check USER.DDF for a blank user by generating an ASCII file with BUTIL -SAVE on key path 0. If there is a blank user, then read and delete the record with the blank user using a Btrieve or XQL utility. ********************************************** ********************************************** TECHNICAL INSIGHTS: NSD201 Interferes with NWTools (NetWare OS/2 Requester v2.0) ********************************************** ********************************************** NWTools script files (.NWS files) created with version 2.0a of the OS/2 Requester will not run properly after the drivers are updated with the OS/2 v2.0 requester patch file (NSD201). Specific examples include not being able to attach to a server with an .NWS file. This situation is apparently caused by NWTOOLS.EXE and NWTOOLS.DLL, which are included with NSD201. New script files may also function incorrectly. To ensure that script files work properly, save a backup of NWTOOLS.EXE and NWTOOLS.DLL before installing NSD201. Otherwise, install the latest version, NSD202, which is fully compatible with the files mentioned above. ********************************************** ********************************************** NIBBLES AND BITS Fast Answers to common questions ********************************************** ********************************************** ********************************************** Network C for NLMs Q When I try to retrieve the status for a Macintosh file in the root directory, the stat() function returns "0" rather than "1" for the st_originatingNameSpace field. What should I do? A If you need to obtain originating name space for a Macintosh file, use AFPDirectoryEntry() instead. ********************************************** ********************************************** NetWare C Interface for DOS Q How can I get the System UP time for a NetWare v3.11 server from a client application? A In the NetWare 3.x and 4.0 environments, you have to write an NLM to be placed in the AUTOEXEC.NCF file that reads the system time and writes it to a text file. Then, the client applcation must read this text file and the current system time on the fileserver and subtract the current time from the time that was recorded by the NLM. ********************************************** ********************************************** NetWare C Interface for Windows Q No matter what structure size I specify in GetServerInformation() under Windows, it always returns 128 bytes of data. What should I do? A Always allocate at least 128 bytes for the received statistics buffer to avoid overwriting memory. ********************************************** ********************************************** NACS/NASI Q My NASI application has run fine under NACS/NASI v2.x, but seems to hang under NACS/NASI v3.x. A The reply buffer to the call Query Name Service (function 0x21) is 32 bytes long. The current documentation (Sept. 1988, Rev. 2.06) shows the reply buffer as 30 bytes. The extra two bytes are at the end of the reply buffer and have the following values: 31: Port number located by query 32: Port status: 0x00:Port Idle 0x01:Port Down (hardware fail) 0x02:Port Connected (no data transfer yet) 0x03:Port Suspended (on hold) 0x04:Port Busy (data being transfered) Q Under NACS/NASI v3.00, a call to Query Name Service (function 0x21) returns only those ports which are not connected. How can I retrieve all ports? A Download the PTF-359 patch file from CompuServe (NOVLIB, LIB 9). This patch will add the necessary functionality to the Query Name Service call. Then, when the Query Name Service is called, all ports will be returned and the 32nd byte of the Query Name Service reply buffer will indicate the port status: 0x00:Port Idle 0x01:Port Down (hardware failure) 0x02:Port Connected (no data transfer yet) 0x03:Port Suspended (on hold) 0x04:Port Busy (data being transferred) ********************************************** ********************************************** NetWare OS/2 Developer's Kit Q When I call PeekPipe() and ReadPipe() with a zero buffer length specified, the pipe is disconnected and error 109, "Pipe Broken," is returned, even on a valid pipe. What should I do? A Specify that a buffer of at least one byte is used. In the case of the peek, doing so will not cause a problem, since the contents are left in the pipe anyway. ********************************************** ********************************************** NetWare Btrieve Q What version of the Btrieve reques-ter should I use with BSERVER.VAP v5.15 on NetWare 2.2? A For all versions of NetWare Btrieve (VAP or NLM), you should have the latest Btrieve requester loaded at each workstation. The latest versions are: * Btrieve Requester for DOS (BREQUEST.EXE) v6.00b * Btrieve Requester for OS/2 (BTRCALLS.DLL) v6.00b * Btrieve Requester for Windows (WBTRCALL.DLL) v6.00c ********************************************** ********************************************** Windows Q How can I determine if a DOS application is running under Windows? A The assembly code in Figure 8 demonstrates an interrupt that determines if a DOS application is running under Windows v3.1. ********************************************** FIGURE 8: Determining if a DOS application is running under Windows v3.1 mov ax, 160ah ; int 2fh ; Check if in Windows 3.1 DOS box or ax, ax ; jz Windows31 ; Jump if Windows 3.1 END of FIGURE 8 ********************************************** This function call also will determine if Windows v3.1 is running in 386 Enhanced Mode or Standard Mode. If the function determines that Windows v3.1 is running, it sets CX equal to two if Windows is running in Standard Mode. If Windows is running in Enhanced mode, it sets CX equal to three. ********************************************** ********************************************** ********************************************** B R A I N S H A R E 1 9 9 3 March 22-26 Salt Lake City, Utah A special supplement to Novell Professional Developer B U L L E T S ********************************************** ********************************************** BrainShare '93 is your chance to hook up with the leading technical experts in the network computing industry. This technical development conference brings together the industry's top minds in development, integration and support with the top technical minds at Novell for the most informative, comprehensive event of its kind in the network computing industry. More than 2,000 people attended BrainShare '92, and BrainShare '93 promises to be bigger and better than ever. Who Should Attend BrainShare '93 offers a valuable opportunity to anyone who develops or supports network computing solutions. If you're a software or hardware developer, member of a support staff, systems integrator or consultant, Certified NetWare Engineer, Certified NetWare Instructor, or company executive, you shouldn't miss this gathering of network computing professionals. Technical Content The conference features more than 235 technical breakout sessions dealing with all phases of NetWare development, integration and support. These sessions are presented by the Novell architects and engineers who write and support NetWare, so you get the information you need straight from the experts. NetWare v4.0, the industry's first distributed operating system for local area networks, will be a featured topic. Breakout sessions will be presented at BrainShare on the following topics: Accessing host systems Building a secure and reliable network Certified NetWare Instructors Client application development Client-server development Communications Database technologies Directory Services Hardware support issues International issues Macintosh connectivity Messaging and E-mail The NetWare desktop NetWare hubs and routers NetWare Loadable Module development The NetWare operating system NetWare transports and protocols Network management New NetWare technologies Service and support Systems integration issues UNIX UnixWare Wide area networks BrainShare '93 will be held on the University of Utah campus. The conference will take over a majority of the campus, utilizing 25 classrooms for the technical breakout sessions. In response to requests from last year's conference attendees, many of the sessions have been extended in length, to allow for greater technical content. Technical breakout sessions have also been extended into Friday afternoon, giving you more access to the sessions. BrainShare Scheduler Utility With over 235 breakout sessions from which to choose, scheduling your week could be a nightmare. To make scheduling your week easier, BrainShare provides the BrainShare Scheduler. This GUI utility, available for Windows v3.1 and OS/2 v2.0, allows to interactively schedule the breakout sessions you want to attend. With it you can access all session abstracts, with cross referencing tools and filters available. The result of using the utility is a printed schedule. After returning the printed schedule to the BrainShare registration office, you will receive tickets to the sessions you have selected. These tickets give you priority access to the sessions. Attendees without tickets will not be allowed into the classrooms until five minutes before the start of each session. This insures that you get the technical information you need and get the most from the BrainShare conference. Keynotes BrainShare '93 features outstanding industry luminaries. Here's the lineup: Monday Bob Supnik V.P. & Tech. Director of Engineering Digital Equipment Corporation Tuesday John Landry Chief Tech. Officer & VP Development Lotus Development Corporation Wednesday Philippe Kahn President & Chief Executive Officer Borland International, Inc. Thursday John Sculley Chairman, CEO & Technology Officer Apple Computer, Inc. Friday John Edwards Executive V.P. & General Manager, Desktop Systems Group, Novell, Inc. Drew Major Senior Scientist & Systems Architect Novell, Inc. Friday's General Session There are a few suprises in store for attendees at Friday's general session. John Edwards will start the morning with a strategic perspecitive on Novell and NetWare, especially as they are affected by the USL announcement. Drew Major will again be giving us his vision on the future of the NetWare operating system. The Management Q & A Panel is your best opportunity to get direct feedback from Novell executives. At the conclusion of the Management Q & A there will be several valuable prizes awarded to attendees. Since you must be present to win, you won't want to miss this opportunity. NetWare 4.0 NetWare 4.0 will be a major topic of discussion at BrainShare '93. As an added bonus, all attendees will receive a CD containing NetWare 4.0. This limited-used version will give you the head start you need in developing enterprise-wide applications or learning to install and maintan this next generation operating system. Labs BrainShare '93 retains many of the features of past Novell technical conferences. The BrainShare Lab will again demonstrate solutions to real customer problems, using the latest NetWare technologies and products. One of the most exciting new features of BrainShare '93 is the addition of the Certified NetWare Engineer Professional Association (CNEPA) Hands-On Lab. Hands-on sessions will cover a variety of subjects, including: Advanced NetWare printing Tuning and optimization PC/UNIX connectivity NetWare SFT Level III Dial-in/dial-out connectivity Network support tools Analyzing the LAN using LANalyzer for Windows Multiple protocol routing NetWare 4.0 UnixWare and NetWare The labs are conducted by CNEs and run concurrently with the breakout sessions. They allow you to experience many of the technologies you will be learning about in the classroom. Sponsor Hospitality Night One of the most popular BrainShare events is Monday's Sponsor Hospitality Night. This provides a forum for Novell's industry partners to present technologies and products of interest to you. Sponsor Hospitality Night is again split between the Marriott and Red Lion Hotels. Confirmed sponsors include: 3Com Blue Lance Borland Digital Equipment Hewlett-Packard IBM Intel Lotus Micropolis Microsoft OURS SMC Storage Dimensions Thomas-Conrad Univel Wang WordPerfect Save $300 on Registration Fees Between now and March 20, the registration price for the conference is $1,295. Registration at the door is $1,595. $100 Discount If you are a member of a Novell program such as the CNE, CNI or Novell Professional Developers' Program, you receive a $100 discount off the registration price, no matter when you register. Register Today! Register by phone, fax or mail: BrainShare '93 Phone: 1-800-253-2819, code 104 1395 N. Highway Dr. or 1-314-827-5629 Fenton, MO 63099 Fax: 1-314-827-6858 BrainShare International Novell is taking BrainShare on the road -make your plans now for BrainShare Europe and BrainShare Japan. BrainShare Europe '93 BrainShare Japan '93 May 12-14 June 22-24 Nice, France Tokyo, Japan ********************************************** ********************************************** CURRENT PATCHES FOR NOVELL DEVELOPMENT TOOLS ********************************************** ********************************************** Many problems encountered by Novell developers can be resolved by using the current drivers and applying the latest patches. In many cases, proper patching can save you a call to the Developer Support Group. NetWire The latest NetWare drivers, example code for NetWare API development tools, OS/2 requester patches, and patches for Novell's database products 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. NOVDEV Members of the Novell Professional Developers' Program can obtain updated NetWare API SDK components from Novell's NOVDEV 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. For a Complete List... A document describing available patches and other files and their location on CompuServe is available through Novell Developer Relation's Automated Fax System (AFS). This system can provide you other useful information as well. To use the AFS, call 1-800-RED-WORD (1-800-733-9673) or 512- 794-1796 from a touchtone phone. Then, 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 lists all other documents available through the Automated Fax System. Up to five documents can be requested per call. ********************************************** ********************************************** 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, scheduling, & 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 U.S. should call 1-801-429-5508. For information on availability, location, and prices of classes outside of the U.S., contact your local Novell office. ********************************************** ********************************************** FUN AND FACTS Developer Trivia ********************************************** ********************************************** Test your developing skills with the development products by taking our Fun & Facts quiz. (See the end of this section for answers.) 1. With Btrieve 5.x, can you create a supplemental index at the same time you create the file? A. Yes B. No 2. What error message does OS/2 v1.3 return if you try to run Brequest in a Global DOS box? A. Error: Sys2090 B. "The system has encountered an error and cannot continue." C. IpxOpenSocketFailed 3. What is the syntax for thunking in OS/2 when thunking pointers to 16 bit pointers? A. _Seg16 B. (thunk) C. (far16) 4. How large is an OS/2 SPX header? A. 36 bytes B. 42 bytes C. 43 bytes 5. Under DOS, SPX uses Event Service Routines (ESRs) to perform certain requests when interrupted. What does OS/2 use to fulfill these types of requests? A. ESRs B. semaphores C. pipes 6. Xerox has assigned Novell a set of sockets to be used by NetWare. What is socket 456 used for? A. Diagnostics B. NetBIOS C. Named Pipes 7. Currently, three data streams are defined for NetWare. What are they? A. DOS, MAC, & OS/2 B. DOS, MAC, & UNIX (NFS) C. DOS, MAC, & FTAM ********************************************** FUN AND FACTS ANSWERS 1. B 2. C 3. A 4. B 5. B 6. A 7. C ********************************************** ********************************************** ********************************************** CURRENTLY SUPPORTED VERSIONS OF NOVELL PRODUCTS ********************************************** ********************************************** Communication Products NetWare for SAA 1.3 NetWare 3270 LAN Workstation for DOS 2.0 NetWare 3270 LAN Workstation for Macintosh 1.0 NetWare 3270 LAN Workstation for Windows 1.1 NetWare Access Server (NAS) 1.2 NetWare Asynchronous Communication Services (NACS) 3.0 Database Products NetWare Btrieve (NLM) 5.15 NetWare Btrieve (VAP) 5.15 NetWare SQL (NLM) 3.00b NetWare SQL (VAP) 2.11 Report Executive for DOS 4.11a Report Executive for OS/2 4.11a Xtrieve PLUS for DOS 4.11b Xtrieve PLUS for OS/2 4.11b Development Products Btrieve for DOS 5.10a Btrieve for OS/2 5.10 Btrieve for Windows 5.10 NetWare C Interface for DOS 1.2 NetWare RPC for DOS 1.1 NetWare RPC 386 1.1 NetWare SQL Developer's Kit 3.00a NetWare System Calls for DOS 1.0 NetWare System Interface Technical Overview 1.2 Network C for DOS 2.0 XQL for DOS 2.11 XQL for OS/2 2.11 Internetworking Products NetWare WAN Links 2.0 NetWare MultiProtocol Router 2.0 NetWare Messaging NetWare Global Messaging 1.0 NetWare MHS Personal Ed. 1.5p NetWare MHS 10-User 1.5p NetWare MHS 50-User 1.5b NetWare MHS Unlimited-Users 1.5n NetWare Operating System Products NetWare v3.11 3.11 NetWare v2.2 2.2 NetWare NFS 1.2 NetWare Runtime NetWare FTAM 1.2 NetWare for Macintosh (NLM) 3.011 NetWare Name Services Network Management Products LANalyzer for Windows 1.1 NetWare Services Manager 1.1 LANalyzer Kit for Ethernet Networks 3.11a LANalyzer Kit for 4/16 Mbps Token Ring Networks 3.11a LANalyzer Kit for Ethernet & 4/16 Mbps Token Ring Networks 3.11a Software Developer's Kits Btrieve v6.0 Developer's Kit Supplement 1.0 LAN WorkPlace for DOS Toolkit 4.1 LAN WorkPlace for Macintosh Toolkit 1.3 LAN WorkPlace for OS/2 Toolkit 3.0 MacIPX 1.0a5 NASI: Programmer Reference Manual NetWare AppleTalk Interface for NLMs 1.1 Network C for NLMs 2.0 (e) NetWare C Interface for Macintosh 1.3 NetWare C Interface for Windows 1.3 NetWare Client SDK 1.0b NetWare for SAA LU6.2 Tools 1.4 NetWare Management System 1.15 NetWare Network Management Toolkit 1.0 NetWare OS/2 Developer's Kit 2.0 NetWare SMF v71 Developer's Kit 1.0 NetWare 3270 Tools 1.6 NetWare TIRPC for DOS and NLMs 1.0 NLM SDK for NetWare v4.0 1.0b Palm DOS SDK 1.0 ********************************************** ********************************************** REQUESTER VERSIONS ********************************************** ********************************************** NetWare Shells and Requesters DOS Shell 3.31 IPX (DOS) 3.31 VIPX.386 1.14 NetWare Requester for OS/2 2.0 NETWARE.DRV (Windows) 2.0 VNETWARE.386 (Windows) 1.04 NetWare SQL VAP NLM Requester for DOS 2.12a 3.00b Requester for OS/2 2.11 3.00b Requester Interface for Windows 3.0 2.13 3.00b NetWare Btrieve v5.15 Requester for DOS 6.0b Requester for OS/2 6.0b Requester Interface for Windows 3.0 6.0c ********************************************** ********************************************** CONTACTING NOVELL ********************************************** ********************************************** To contact Developer Support, call 1-800-NETWARE (1-800-638-9273), or 1-801-429-5588. Be prepared to give the support operator your open incident reference number. Developer Support questions may also be sent by fax to 1-512-794-1775. Many international distributors provide technical support. Please contact your distributor or local Novell office (see list at the end of this file) for more information on international support options. Software patches may be obtained from Novell's NetWire forum on CompuServe (NOVLIB, LIB 7), or by contacting Developer Support and specifying the patches you need by product name. Novell database and development products can be obtained through Novell Authorized Resellers, or by calling 1-800-NETWARE (1-800-638-9273), or 1-801-429-5588. Software Developer's Kits (SDKs) are available only through Novell's Professional Developers' Program. Call 1-800-NETWARE (1-800-638-9273), or 1-801-429-5588. For more information on Novell Labs' development tools, education classes and product certification, call 1-800-453-1267 or 1-801-429-5544. For more information on Novell education classes, call 1-800-NETWARE (1-800-638-9273), or 1-801-429-5588. ********************************************** ********************************************** ACKNOWLEDGEMENTS ********************************************** ********************************************** Publisher: Mad Poarch Editor: Kirk R. Humphries Design: Creative Services, Provo Feature Articles: Ron Cully and Vicki L. Smith Contributors: Gaurang Amin, Linda Anderson, Neda Eslami, John King, Nancy Kromar, Rudy McNeese, Chris Ojeda, Matt Pinsonneault, Bill Prentice, Bob Quinlan, Drue Reeves, Michael A. Spano, Howard Thamm, Aslam Tejani, and Brenda Wallace 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. ********************************************** (c) 1992 Novell, Inc. All rights reserved. Novell, the N design, NetWare, Btrieve, XQL, LAN WorkPlace and LANalyzer are registered trademarks; NetWare Loadable Module (NLM), NetWare Global Messaging, NetWare System Calls for DOS, NetWare Runtime, NetWare SQL, NetWare Btrieve, NetWare C Interface for DOS, NetWare System Interface Technical Overview, NetWare for SAA, NetWare RPC, NetWare RPC 386, NetWare LU6.2, Report Executive, NetWare MHS, NetWare Asynchronous Communication Services (NACS), NetWare Management System, NetWare 3270 LAN Workstation, LANtern and Xtrieve PLUS are trademarks; and NetWire and Professional Developers' Program are service marks of Novell, Inc. IBM and OS/2 are registered trademarks, and NetBIOS and SAA are trademarks of International Business Machines Corporation. Microsoft is a registered trademark, and Windows is a trademark of Microsoft Corporation. Macintosh and AppleTalk are registered trademarks of Apple Computer, Inc. CompuServe is a registered trademark of CompuServe Corporation. NFS is a registered trademark of Sun Microsystems, Inc. ********************************************** ********************************************** ********************************************** NOVELL OFFICES ********************************************** ********************************************** Novell, Inc. Corporate Headquarters 122 East 1700 South Provo, Utah 84606-6194 USA Tel.1 (801) 429-7000 FAX 1 (801) 429-3944 ********************************************** Novell Australia Level 2 2 Help Street Chatswood NSW 2067 AUSTRALIA Tel.61 (2) 413-3077 FAX 61 (2) 413-3116 ********************************************** Novell Benelux Excelsiorlaan 13 1930 Zaventem BELGIUM Tel.32 (2) 7250200 FAX 32 (2) 7250311 ********************************************** Novell Brazil Av. Ribererao Preto 13012 Sa› Paulo BRAZIL Tel. 55 11 284 4866 ********************************************** Novell Canada 3100 Steeles Avenue E. Suite 500 Markham, ONT L3R 8T3 CANADA Tel.(416) 940-2670 ********************************************** Novell France Tour Anjou 33, Quai De Dion-Bouton 92814 Puteaux Cedex FRANCE Tel.33 (1) 4775-0909 FAX 33 (1) 4778-9472 ********************************************** Novell Germany WillstŠtter Strasse 13 4000 DŸsseldorf 11 GERMANY Tel.49 (211) 59730 FAX 49 (211) 5973250 ********************************************** Novell Hong Kong China Resources Bldg. 26 Harbour Rd. Room 4601-5 Wanchai HONG KONG Tel.852 8272223 FAX 852 8276555 ********************************************** Novell India Onward Novell Software Kriston House, 2nd Floor Saki Vihar Rd., Chandivali Andheri (E) Bombay 400 072 INDIA Tel.41 (1) 750-0504 FAX 41 (1) 750-0957 ********************************************** Novell Italy Via San Vittore 40 20123 Milan ITALY Tel.39 2 4801-3554 FAX 39 2 4801-3594 ********************************************** Novell Japan Toei Mishuku Bldg.3F 1-13-1 Mishuku Setagaya-ku, Tokyo 154 JAPAN Tel.81 (3) 5481-1161 FAX 81 (3) 5481-1855 ********************************************** Novell Korea Donghwa Building 13F-5 25-5, Youido-dong Youngdeungda-Ku Seoul KOREA Tel.822 786 1141 FAX 822 786 1140 ********************************************** Novell Mexico Insurgentes Sur No. 1160 P.H. Mexico D.F. 03100 MEXICO Tel.52 (5) 575 5998/4192 FAX 52 (5) 559 0133 ********************************************** Novell Singapore Level 36 Hong Leong Bldg. 16 Raffles Quay Singapore 0104 SINGAPORE Tel.(65) 322-8503 FAX (65) 321-8966 ********************************************** Novell Spain Paseo Castellana, 40bis 28046 Madrid SPAIN Tel.34 (1) 577-4941 FAX 34 (1) 577-9053 ********************************************** Novell Sweden Kottbyjatan 7 16475 Kista SWEDEN Tel.46 (8) 703 2350 FAX 46 (8) 703 9434 ********************************************** Novell Switzerland vor Ort 21 CH-8104 Weiningen-Zurich SWITZERLAND Tel.41 (1) 750-0504 FAX 41 (1) 750-0957 ********************************************** Novell Taiwan 2F2 383 Jen Al Road Section 4 Taipei TAIWAN, R.O.C. Tel.886 2775 3183 FAX 886 2731 2284 Novell United Kingdom Avon House, Sweetwell Road Bracknell, Berkshire RG12 1HH UNITED KINGDOM Tel.44 (344) 860 400 FAX 44 (344) 860 353 ********************************************** ********************************************** Novell Professional Developer B U L L E T S ********************************************** FEBRUARY 1993 Volume 5 Number 2 ********************************************** ********************************************** END OF FILE u±f„Jg(((¸©ft3A Qé@5.‘Ì5/ N¬ûÊx"_`p0( (g°ifD`°im