MARCH 1993 VOLUME 5 NUMBER 3

INDEX

• MAD'S COLUMN
• ARTICLES
• TECHNICAL INSIGHTS
• NIBBLES AND BITS
• NOVELL DEVELOPER RELATIONS
• NOVELL DEVELOPER EDUCATION
• CURRENT PATCHES FOR NOVELL DEVELOPMENT TOOLS
• CONTACTING NOVELL
• ACKNOWLEDGEMENTS

MAD'S COLUMN

"March-Madness" in the computer industry is over. As though at a basketball game, we watched at the IBM OS/2 Technical Interchange, at Interop and Uniforum, at the Microsoft Tech*Ed and at BrainShare '93 as hardware and software vendors alike dribbled, took foul shots and slam-dunked their way through hours of exciting competition.

At Interop, Novell "set the pick" for the arrival of NetWare 4.0. At BrainShare, John Landry asked us to watch our "fast break" and re-evaluate how we define future development, and Drew Majors told us that, while writing NLMs may not be "nothing but net," writing them is... "just different." And, in "three-point land," a new IBM leader said he will not hesitate to make the necessary changes. No matter where you looked, the contest was "in your face."

Competition, whether in sports or computers, is essential. This summer the Olympic Festival '93 will be held in San Antonio. Novell's NetWare SFT III has won the honor of being the hosting network on IBM PCs with a variety of popular third-party word processing, data entry and communications software invited to do the information exchange.

More on that after a word from our sponsors.

Happy_Programming!

Mad "Magic" Poarch
Director
Developer Support/Service

ARTICLES:

NWSNut: Developing NLMs with Novell's Look & Feel

NWSNut Overview

In addition to producing NLMs that look and feel like Novell NLMs, the NWSNut libraries provide a common standard for NLM user interfaces. Also included are tools that allow developers to create language-enabled, internationalized NLMs. Screens and function keys will operate the same for all NLMs written to use the NWSNut interface. As a result, this standardized interface will produce a simplified environment for end-users of NLM products.

NWSNut NLMs developed with the NLM SDK for NetWare 4.0 can also run on NetWare 3.11 servers when the AFTER311 NLM is also loaded on the server. These NLMs will run unmodified on NetWare 3.11 servers as long as NetWare 4.0-specific APIs are not used.

The NWSNut Interface is a set of C language APIs. The NWSNut library is made up of six major components:

• Portals
• Lists
• Menus
• Forms
• Screen Messages
• Help

Portals

There are two categories of portals: direct and virtual. The type of the portal depends on whether the portal's screen is accessed directly, making it a "direct" portal, or buffered in memory, indicating a virtual portal. The portal type is determined by the value of the directFlag passed to NWSCreatePortal.

A virtual portal is an area of memory into which data intended for the portal is written. The data in memory is displayed on the physical screen when NWSUpdatePortal( ) is called. A virtual portal is normally used when the data to be displayed is larger than the physical screen or portal display area size. The portal must be scrolled from side to side or top to bottom to see the hidden parts of the screen in the virtual portal.

When you use a direct portal, the information displayed in the portal is written directly to the portal screen. What you see is what you get and the portal screen area cannot be scrolled.

Lists

Lists are displayed in virtual portals. Menus and Forms are specialized lists, which users can scroll through and select the appropriate item(s). Each list type (lists, forms, menus) has related APIs that boost functionality.

Menus

Forms

Screen Messages

Help

Other Features

Default messages and help screens are an important part of the NLM. So, a French developer marketing an NLM to a primarily French audience would link in default messages in French.

When selling the same NLM to an English or German audience, the French developer would ship English or German message files with the NLM, although the default language would still be French. The multi-language capability of NWSNut NLMs will greatly increase the marketability of language- enabled NWSNut NLMs.

This article does not focus on the language enabling capabilities of the NWSNut libraries in conjunction with the Message Tools. Although not required, the Message Tools do work closely with the NWSNut Libraries, giving developers the ability to write language-enabled applications.

NWSNut NLM Development

The initial code for the sample NLM (see Figure 1) is typical of the code required for all NWSNut client NLMs.

FIGURE 1: NDemo example source code

/* Get a handle for allocating a resource tag. */

   NLMHandle = GetNLMHandle();

/* Create a screen for displaying our information. */

   CLIBScreenID = CreateScreen("NUT Demo Screen",
                               AUTO_DESTROY_SCREEN);
   if (!CLIBScreenID)
      return;

/* Allocate a resource tag to use for memory allocations. */

   allocTag = AllocateResourceTag(NLMHandle,
                                  "NUT DEMO Alloc Tag",
                                  AllocSignature);
   if (!allocTag)
   {
      DestroyScreen(CLIBScreenID);
      return;
   }

/* Initialize the screen interface. */

   ccode = NWSInitializeNut(UTILITY_MSG, VERSION_320,
                            NORMAL_HEADER, 0, 0, 0,
                            CLIBScreenID, allocTag,
&handle);
   if (ccode)
   {
      DestroyScreen(CLIBScreenID);
      return;
   }

/* Setup a procedure to be called if unloaded from the
   console with an UNLOAD XXXXXX command. */

   AtUnload(myunload);

/* Activate the screen that you have created. */

   DisplayScreen(CLIBScreenID);

END of FIGURE 1

Once all of the requirements listed above are fulfilled, the client NLM calls NWSInitializeNut( ). This initialization function creates the NWSNut screen and screen header using the screen handle of the client NLM. The initialization function also creates a NUTInfo structure to track NWSNut data for the client. The NUTInfo structure is defined in NWSNUT.H. It is used to keep track of the status of the current portal, saved lists, help context, and messages for your NLM.

An "atunload" procedure is required to allow you to cleanup resources allocated on your behalf by NWSNut. The minimum requirement of the atunload function is to call NWSRestoreNut() and to destroy the CLIB screen.

The next step is to display, or "make current," the NWSNut screen created using the CLIB screen. The screen is displayed by calling the CLIB function DisplayScreen. The newly created NWSNut screen can now be used to create portals, lists, etc.

As portals are the basis of most NWSNut screens, they deserve additional discussion. Portals are created by calling the NWSCreatePortal API. The height, width, type and attributes of the portal are required to create the portal. However, the act of creating a portal does not enable NWSNut functions to write data to the portal. A Portal Control Block (PCB) is required for all functions that write to portals. To obtain the PCB, call NWSGetPCB( ) and pass in the portal number obtained from NWSCreatePortal( ).

Whenever you make a call to NWSSelectPortal( ), the portal is activated. NWSSelectPortal( ) brings the portal to the front, highlights the portal title and border, and enables the portals cursor if a cursor was specified when the portal was created.

To deselect a portal, you use the NWSDeselectPortal function. This selection and deselection capability gives you the ability to manage several different portals on the same screen, preferably in a user-friendly manner. To destroy Portals, call NWSDestroyPortal( ).

As discussed earlier, list items are created as a doubly- linked list. The list pointers point to the message lines to be used when the list is displayed. You can add items to the linked list by calling the NWSAppendToList function (see Figure 2). Items appended to lists are normally obtained from message files using the NWSGetMessage( ).

FIGURE 2: NWSNut list example

NWSInitList (handle, Free);
NWSAppendToList (NWSGetMessage (LIST_ITEM_1,
                                &(handle->messages)),
                                (void *) 0, handle);
NWSAppendToList (NWSGetMessage (LIST_ITEM_2,
                                &(handle->messages)),
                                (void *) 0, handle);
NWSAppendToList (NWSGetMessage (LIST_ITEM_3,
                                &(handle->messages)),
                                (void *) 0, handle);
NWSAppendToList (NWSGetMessage (LIST_ITEM_4,
                                &(handle->messages)),
                                (void *) 0, handle);
NWSList( ) (LIST_HEADER, 10, 40, 4,
   strlen (NWSGetMessage (LIST_HEADER,
                          &(handle->messages))) + 4,
                          M_ESCAPE | M_SELECT, NULL,handle,

                          NULL, ListAction, 0);

/* cleanup and discard this list */

NWSDestroyList (handle);

END of FIGURE 2

To create forms, call NWSInitForm( ) and build the form by appending various types of fields to the form using append functions. Once all of the fields are appended to the form, it can be displayed by calling NWSEditForm( ). Various types of fields can be appended to the form, including integer, hexadecimal, boolean, comment, prompt string and menu fields. Menu fields allow you to give the user a group of selections from which to select for a specific field. Examples of these operations are contained in NDEMO.NLM.

One last step remains, however, that is essential to developing NWSNut client NLMs. The deallocation of NWSNut allocated resources is the responsibility of the client NLM. For every portal, list, menu or form create function there is a corresponding destroy function. The destroy function will deallocate the resources allocated on behalf of the client NLM for the specific function.

Finally, there are two steps that are common to the development of all NWSNut client NLMs. Since two of the initial steps were the NWSNut initialization and the creation of a CLIB screen, you must also recover the resources allocated by the NWSInitializeNut and destroy the CLIB screen. NWSRestoreNut( ) deallocates the tables created by the NWSInitializeNut and must be called before the termination of any NWSNut client NLM.

NWSNut client NLMs help NLM developers to create a useful and interactive computing environment. The NWSNut APIs provide a standardized, more supportable user interface NLM. Built-in language-enabling creates a larger marketing arena for NLM developers. The NWSNut APIs provide everything you need to develop NLMs with Novell's "look and feel."

For more information on the procedures described in this article, contact the Developer Support Group at 1-800- NETWARE (1-800-638-9273) or 1-801-429-5588. To purchase the NLM SDK for NetWare 4.0 or any other Novell Software Developer's Kit, contact Novell's Professional Developers' Program at 1-800-NETWARE or 1-801-429-5588.

DR DOS v6.0 Configuration & Batch Processing

Example 1: The use of GOTO in CONFIG file

The GOTO statement, as shown in Figure 3, is used to proceed directly to a label. This function works like the GOTO statement found in batch file processing.

FIGURE 3: GOTO statement in CONFIG file

?"Do you want to run QEMM (y/n)? " goto QEMM
?"Do you want to run MemoryMAX (y/n)? " goto DRDOS
:QEMM
DEVICE=c:\QTR_DECK\QEMM386.SYS
DEVICE=C:\DRDOS\HIDOS.SYS /B=FFFF
(additional QEMM driver lines go here...)
goto COMMON
:DRDOS
hidos=on
DEVICE=C:\DRDOS\EMM386.SYS /F=AUTO...
...
:COMMON
files=40
hibuffers=20

END of Figure 3

FIGURE 4: CHAIN statement in CONFIG file

?"Do you want to run QEMM (y/n)? " chain=QCONFIG.SYS
?"Do you want to run MemoryMAX (y/n)? " chain=MCONFIG.SYS
files=40
hibuffers=20

END of Figure 4

With this technique, processing pauses on the SWITCH command until the user chooses an option. The appropriate option is selected by choosing a number. The SWITCH command then goes to the corresponding label. In Figure 5, 1 selects the label :NOLIM, 2 selects the label :512K and so on. The RETURN command returns processing to the line after SWITCH. Notice the use of the ECHO statement for setting up the menu options.

FIGURE 5: Using SWITCH/RETURN and labels

ECHO =    Choose how much Extended Memory you want to
convert
ECHO =    to LIM Memory for this session.
ECHO =
ECHO =          1 (or ENTER)    No LIM Memory
ECHO =          2               512K of Memory
ECHO =          3               1024K of Memory
ECHO =          4               2048K of Memory
ECHO =
ECHO =         Make your selection...

SWITCH NOLIM, 512K, 1024K, 2048K
GOTO DEFAULTS
:NOLIM
DEVICE=C:\DRDOS\EMM386.SYS /F=NONE /K=AUTO /B=FFFF /R=AUTO
RETURN
:512K
DEVICE=C:\DRDOS\EMM386.SYS /F=AUTO /K=512 /B=FFFF /R=AUTO
RETURN
:1024K
DEVICE=C:\DRDOS\EMM386.SYS /F=AUTO /K=1024 /B=FFFF /R=AUTO
RETURN
:2048K
DEVICE=C:\DRDOS\EMM386.SYS /F=AUTO /K=2048 /B=FFFF /R=AUTO
RETURN
:DEFAULTS
SHELL=C:\COMMAND.COM \C: /P /E:512
HIDOS=ON
HIBUFFERS=20
FILES=30

END of Figure 5

The use of variables in the CONFIG is not quite the same as in batch files. Because the command processor (COMMAND.COM) is not loaded until after CONFIG processing, environment variables are stored. These variables are then passed to the command processor where they can be tested and processed through the AUTOEXEC.BAT or other batch files.

It is not possible to test an environment variable in the CONFIG. The CLS, CPOS, EXIT and SET commands are featured in the example in Figure 6.

FIGURE 6: CLS, CPOS, EXIT and SET commands in CONFIG.SYS

:DEFAULTS
SHELL=C:\COMMAND.COM \C: /P /E:512
HIDOS=ON
HIBUFFERS=20
FILES=30
etc....
ECHO =         Choose which TSRs and Utilities you want
loaded
ECHO =               at BOOT time for this session.
ECHO =
ECHO =         1 (or ENTER)   None... just continue
ECHO =         2              Mouse & Cursor Drivers
ECHO =         3              Keyboard "Speeder"
ECHO =         4              Novell Network
ECHO =         5              Done with selections
ECHO =
ECHO =         Make your selection...

:MORE
CPOS 10,33
SWITCH NOTHING, CURSMOUS, SPEEDKEY, NOVELL, DONE
GOTO MORE

:DONE
:NOTHING
CLS
EXIT

:CURSMOUS
SET THINGS=ON
RETURN

:SPEEDKEY
SET SPEEDKEY=ON
RETURN

:NOVELL
SET NETWORK=ON
RETURN

END of Figure 6

FIGURE 7: AUTOEXEC.BAT picking up environment variables.

@ECHO OFF

:drdosbeg
VERIFY OFF
PATH C:\;C:\DRDOS;C:\BATS;C:\TOOLS;C:\WINDOWS
if "%things%"=="on" prompt
$e[s$e[0;70H$e[1;36m$t$e[u$e[1;36mDR
      DOS6$p$g$e[2;32m
if not "%things%"=="on" PROMPT [DR DOS] $P$G

SET TEMP=C:\TEMP
IF NOT "%TEMP%"=="" MD %TEMP% >NUL
if "%things%"=="on" HILOAD MOUSE
if "%things%"=="on" HILOAD CURSOR /s10
if "%speedkey%"=="on" c:\drdos\mode con:rate=30 delay=1
if "%network%"=="on" hiload c:\lan\ipx
if "%network%"=="on" hiload c:\lan\net3

:drdosend

END of Figure 7

Figure 8 shows how to select different AUTOEXEC.BAT files from CONFIG.SYS using the ? and the Shell statement. In the Shell statement the /P switch can be followed by a filename. When present, the named file will be executed instead of the AUTOEXEC.BAT. The named file must have a .BAT extension and cannot exceed 11 characters including path.

FIGURE 8: Selecting different AUTOEXECs using the "?" and the Shell statement

?"Default Autoexec? (y/n) "SHELL=C:\COMMAND.COM C:\ /P
/E:256
?"Alternate Autoexec? (y/n) "SHELL=C:\COMMAND.COM C:\
        /P:ALTERNAT.BAT /E:256

END of Figure 8

FIGURE 9: Employing "menu" choices with SWITCH

 CONFIG.SYS

ECHO =    1  For Windows Configuration
ECHO =    2  For QEMM Configuration
ECHO =    3  For DR DOS MemoryMAX Configuration
ECHO =    4  For 386MAX Configuration
ECHO =    5  For no Configuration... just exit
SWITCH win, qemm, memm, 386m, none
:none

set autoexec=norm
exit

:win
set autoexec=win
chain=wconfig.sys

:qemm
set autoexec=qemm
chain=qconfig.sys

:memm
set autoexec=memm
chain=mconfig.sys

:386m
set autoexec=386m
chain=386conf.sys

AUTOEXEC.BAT

@echo off
PATH C:\DRDOS;C:\;C:\UTIL;
VERIFY OFF
PROMPT $P$G
DISKMAP C: D:
IF "%autoexec%"=="norm" goto DRDOSEXIT
SHARE /L:40
IF "%autoexec%"=="win" SUPERPCK /EM /L:2048
IF "%autoexec%"=="qemm" CALL QEMM.BAT
IF "%autoexec%"=="memm" SUPERPCK  /A /L:2048
IF "%autoexec%"=="386m" CALL 386.BAT
:DRDOSEXIT

END of Figure 9

TECHNICAL INSIGHTS:

Optimization with Duplicate Field Names (NetWare SQL v3.0)

FIGURE 10: Example tables containing duplicate field names

 CREATE TABLE T1 USING "T1.DAT"
    (Name CHAR(20), ID INT(4)) WITH INDEX (ID);
 CREATE TABLE T2 USING "T2.DAT"
    (Name CHAR(20), Cust_ID INT(4)) WITH INDEX (Name);

END of FIGURE 10

SELECT * from T2, T1 where T2.ID =
T1.Cust_ID and Name = "John";

This statement will return the proper data set, but can also cause NetWare SQL to perform an optimized search utilizing the index in table T2 on the "Name" field. Since table T2 is the primary table in the view, and the restriction is based on an indexed field in the primary table, NetWare SQL should use the index to retrieve the records to be joined to table T1. This will only occur if NetWare SQL uses the "Name" field from table T2 when performing the restriction, and not the "Name" field from table T1.

When processing this query, NetWare SQL determines which Name field to use when it searches the dictionary for a field called "Name" that is in one of the tables in the view. Whichever Name field it finds first is the "Name" field it will use to perform the restriction. Since table T1 was created first, NetWare SQL will find its "Name" field first, and so it will use "T1.Name" to perform the restriction. In this case, NetWare SQL will do a file scan of table T2, join each record to table T1, and then check the resulting record for a Name of "John" from the T1 portion of the record.

To ensure that the optimization is performed correctly, qualify the field name with the appropriate table name or alias that should be used. The following select statement performs an optimized join of the two tables:

SELECT * from T2, T1 where T2.ID =
T1.Cust_ID and T2.Name = "John";

The "Name" field in the restriction is qualified with the table name from which the field should be taken. In this case, since "T2.Name" is an indexed field, NetWare SQL will retrieve only those records from table T2 which have a value of "John", and then join those records to table T1.

New CLib Documentation (Network C for NLMs v2.0 (e))

• ASCIIZToMaxLenStr( )
• ReturnNLMVersionInfoFromFile( )
• RetrurnNLMVersionInformation( )
• RingTheBell( )
• ThreadSwitchWithDelay( )

Btrieve Programmer's Manual Correction (NetWare Btrieve (NLM) v6.00)

On page 4-69 and 4-83 the Get Next Extended and Get Previous Extended operation Filters are documented as:

1 Byte       Data type of field
2 Byte       Length of field
1 Byte       Comparison code

1 Byte       Data type of field
2 Byte       Offset of field
1 Byte       Comparison code

1 Byte       Data type of field
2 Byte       Length of field
2 Byte       Offset of field
1 Byte       Comparison code

SuspendThread() Suspends Entire Thread Group (Network C for NLMs v2.0 (e))

To avoid suspending all threads in the group, if you want to suspend one thread from a another thread, place the thread to be suspended in its own thread group.

Compiler Error Using XQL.H Header (NetWare SQL v2.11)

modify [eax ecx edx fs gs 8087];

To avoid the compiler error, modify the statement by removing the reference to fs and gs as follows:

modify [eax ecx edx 8087];

The XQL.H file is used in conjunction with XQLNLM.C when developing an NLM that can communicate with the NetWare SQL NLM. The header and source module were first distributed with the NetWare SQL Developer's Kit v2.11.

Matching Btrieve Requester and DLLs (Btrieve for Windows v5.10)

This situation results from leaving different versions of WBTRCALL.DLL in directories or having an inappropriate DLL in the default drive. If you have several DLLs in your path statement, Windows will search for DLLs in the following order:

• Application-specific directory specified in an
• .INI file
• Current directory
• Windows directory (e.g. C:\win31)
• Windows system directory (e.g., C:\win31\system)
• Application directory (i.e., path from which the program is retrieved (only Windows v3.1))
• Directories specified in path
• Mapped network directories

Reclaiming Memory from Deleted Extended Attributes (Network C for NLMs v2.00)

NetWare LU6.2 DOS Programmers Guide Update (NetWare for SAA LU6.2 Tools v1.4)

Open Btrieve Files & Non-Btrieve Apps (NetWare Btrieve (NLM) v6.0)

BTRIEVE.NLM v6.0 opens files differently than earlier versions of Btrieve. With Btrieve v6.0, files are first opened in Shared Read mode by the foreground process and, when data is written to the files, they are reopened by the Background Writer in exclusive Write, Shared Read mode. Versions of Btrieve before v6.0 opened the files with one exclusive Read/Write handle.

If you use BTRIEVE.NLM v5.x, the following scenario applies:

• Backups fail if the Btrieve file is open.
• A Sharing Violation Error is returned on any attempt to use a non-Btrieve application to open a Btrieve file that is already opened by Btrieve v5.x. With Btrieve 6.0, the outcome is different. To ensure database integrity when backing up files, either:
• Make sure all the Btrieve files are closed before running the backup.
• Use Continuous Operations.
• Use a backup utility that opens the files in exclusive write mode. Even though the backup utility is only going to read from the file, it has to open the file in a mode that will prevent other processes from writing to it. Exclusive Write mode guarantees this. Make sure the backup utility can get exclusive rights to the file.

Self-Joined Views are Read-Only NetWare SQL v3.0

Do not attempt to insert, update or delete records using a view containing a self-join. Any attempt to do so will return a status 318 - "Cannot Update View Defined in Read- Only Mode."

NIBBLES AND BITS

Fast Answers to Common Questions

NetWare C Interface for DOS

Q - When I try to delete a drive mapping, the floppy drive is accessed. Why does this happen?

A - MapDriveUsingString( ) does some processing and then calls the MapDrive API. If you look in the library source, however, you will notice that it always passes MapDrive( ) a base drive number of zero, which is the A: drive.

To avoid accessing the floppy drive, either use MapDrive( ), or correct the MapDriveUsingString( ) library source code as shown in Figure 11.

FIGURE 11: Necessary correction to MapDriveUsingString( )

Old line:

  /*-- map the drive --*/
  ccode = MapDrive( currConnectionID, (BYTE)0, fullPath,
                    searchFlag, searchOrder, &driveLetter );

New line:

  /*-- map the drive --*/
  if (searchFlag == DRIVE_DELETE)
  ccode = MapDrive( currConnectionID, 0xff, fullPath,
                    searchFlag, searchOrder, &driveLetter );
 else
  ccode = MapDrive( currConnectionID, (BYTE)0, fullPath,
                    searchFlag, searchOrder, &driveLetter );

END of FIGURE 11

     #ifdef __cplusplus
     extern "C" {
     #endif

     #include 
     #include 
     #include 

     #ifdef __cplusplus
     }
     #endif

NetWare OS/2 SDK

A - The sequence number parameter should be initialized to -1.

Q - The documentation for the NetWare OS/2 SDK v1.3 describes the sequence number parameter for NWScanFileInformation2( ) as being an integer and also does not provide an initialization value. Please clarify this information.

A - The sequence number parameter should be declared as type "long" and should also be initialized to -1.

Q - On page IPX4-9 of the NetWare OS/2 API Reference, the first parameter in IPXGetLocalTarget( ), *puchTarget, is defined as a pointer to PUCHAR. However, PUCHAR is already defined as a pointer to an unsigned character typedefed in the OS/2 DEF.H file. What is the correct definition?

A - The documentation is incorrect. Define puchTarget as an output parameter (not an input parameter) of type PUCHAR (instead of *puchTarget).

NetWare Btrieve NLM

A - When NetWare time restrictions are in force and a user's NetWare connection is terminated, Btrieve files opened to this connection remain open. If someone logs in and gets the same connection ID as the user who previously opened the files, the Monitor utilities show that the new user opened the files. Actually, Btrieve has these files open. The files should not be backed up unless they are in Continuous Operations mode.

The new user cannot access these files because he doesn't have the necessary Btrieve position blocks. The connection ID does not give the user access to the files because the user never opened the files. To avoid leaving files open, your application should perform an explicit Btrieve Reset operation, or the workstation should be rebooted before the NetWare time restrictions take effect.

NetWare SQL

A - To update a joined view, place the "*.*" string in the sTableNames parameter. The wildcard characters will ensure that all the tables associated with a joined view name will be updated. Another option is to send each table name comprising the joined view as a string (e.g., Personnel0Payroll0Dept0).

NOVELL DEVELOPER RELATIONS:

Designing Software for the International Market (Special supplement)

Novell currently receives about 51% of its revenue from markets outside the UnitedStates. For this reason, Novell is committed to expanding the international market. Third party developers are invited to join Novell in this market by making sure that their NetWare applications fit within the Novell internationalization strategy. This is the first in a series of articles to help you better understand how to develop your application for markets outside of the U.S.

Where do I start?

• Retroffiting - the process of adapting an existing product for a specific language. Retrofitting is generally undesirable if you plan to develop your application for several languages because of its high initial cost and even higher maintenance costs. In addition, the engineering effort must be repeated for each specific locale.
• Enabling - the process of designing, implementing, and testing software that is easily adaptable to different locales with a minimum of engineering effort when introducing another language. The initial investment may be as high as retrofitting, but with each subsequent additional language, costs are greatly reduced.
• Localization - the process of adapting an enabled piece of software to a particular locale. It consists of translation of user-viewable data and verification of the translation. The translation is typically done by professional translators, often in the particular locale, ideally with little or no work on the part of the application developer.
• Internationalization - the combined process of enabling and localization. In other words, the programming effort required to enable software, plus the linguistic effort to translate and adapt it to a particular locale.

How Do I Enable my Products?

• Text strings - including informational messages, abends, error messages, help text, etc.
• Panels - also sometimes called dialogs, windows, and screens. C-worthy programmers must define the panels programmatically by composing a number of screens. A similar panel in Windows would be defined as a single resource, called a dialog template.
• Program control - any shortcut commands (called accelerators in Windows) for experienced users. These accelerators are often mnemonically-based (for example, CTRL-C), and should therefore be translated.
• Graphics - icons and bit maps are also frequently culture-specific and must be translated. For example, check marks in the U.S. are used to mark desired items. In Japan, a check mark means that something is bad or should be discarded.

What Tools Are Available for Enabling?

• Isolate text messages from the source code, so that you don't have to recompile the source code whenever you want to change languages
• Place the original text messages and translated versions of the messages into Language Modules, which are bound to their respective programs
• Help test product enabling
• Simplify dealings with translation houses by providing a single interface to translators
• Provide technical support with a quick way to look up message sources
• Provide translators with terminology lists derived from messages

How do I Translate Message Files for a Particular Locale?

• Length limits - almost all messages will be longer in their translated form than they were in English. In general, you should enable your software to handle variable-length messages, but if there are some messages that must not exceed a certain length, you must tell the translator.
• Translatability - messages often contain keywords or product names that should remain the same in translation. Point these out to the translator.
• Format - some messages are padded to begin or end in a certain column on the screen. If format is important for the message, you should tell the translator how to format the translation.
• Variables - Variables, such as "%d" and "%s," must be annotated so that the translator knows if they are proper names. You must also number each variable so that the translator can indicate how they are to be reordered.
• Context - when you extract messages from the source code, make sure you extract them from their context. It may be obvious when you are running a program that "Restore Menu" is the header title of the menu, but out of context, the translator could just as easily interpret it as the command "Restore the Menu."

What Comes After Translation?

Novell uses load coupling. In load coupling, the program finds its resources and loads them into memory during program initialization. Load time coupling facilitates multilingual support. There can be a different resource subdirectory for each language. Load time provides for flexible packaging (when customers want a language update, they receive only resources, no code). This method is used and recommended by Novell.

Some other possible coupling scenarios are as follows:

• Compile/Assemble - because compilation and assembly require engineering resources, they should not be used to couple resources to executable code. It makes the logistics of the localization process more difficult (and many additional problems will come back to the engineer).
• Link - for the same reasons, linkers should not be used to couple resources.
• Static coupling - a utility either appends the resources to the executable image, or inserts the resources in a reserved area of the program. Static coupling has many of the disadvantages of compiling and linking the resources, and is not recommended.
• Run - every time the program needs a resource, it loads it in from a resource file. Conceivably, a user could change the language at any moment during the program. This has the disadvantage of causing disk operations during inconvenient (or impossible) moments.

Special Considerations with Enabling and Localization

• Monocasing - the method for converting a - z to uppercase using a simple arithmetic operation such as "if ('a' <=c && c<='z') c = 0x20;" will not support characters with diacritical marks or double-byte characters. The solution is to use monocasing tables for each locale.
• Collation - like monocasing, collation is locale- dependent and should be handled in collation tables for each locale. For example, in Danish, the ligature ' comes after Z. For languages with non-alphabetic systems, such as Japanese, collation is much more complicated.
• Date Formats - formats vary from country to country. For example, the date format in the U.S. is MMDDYY, in Spain, it is DDMMYY, and in Japan, YYMMDD.
• Time Formats - time formats vary from a 12-hour to a 24-hour clock. The U.S. is one of the only countries that does not use a 24-hour clock. Some locales use colons to separate hours, minutes and seconds, others use periods.
• Numeric and Monetary Formats - like time and date formats, these formats can vary from locale to locale.
• Character Sets - 7-bit and 8-bit character sets are insufficient to handle the scripts used by many of the world's languages. If you want to handle Oriental scripts, you mast handle double-byte character sets as well
• Hardware Enabling in the Japanese Market - the five different hardware architectures used in Japan present special challenges for software internationalization. Enabling applications for the Japanese market means converting programs to run not only on Japanese hardware, but on several different types of hardware. Thus, making sure that your application is independent of the hardware on which it is running becomes a must for applications intended for this market.

Products for International Software Development

• NetWare Client SDK for DOS, OS/2, and Windows (for client development)
• NLM SDK for NetWare 4.0 (for server development).

Are there any tools specific to development for the Japanese market?

The advantage of developing to NetWare-J is that it eliminates many of the hardware dependencies that developers encounter due to the various incompatible hardware platforms in the Japanese market. Novell Developer Relations actively supports developers who want to write to NetWare 3.11J. Contact Novell Developer Relations for more information on developing applications for the NetWare-J operating system.

YES, Our NLM is NetWare Tested & Approved! (Special supplement)

NLM Certification Program Benefits

• Your NLM will be leaner, faster, and more technically correct.
• Your NLM will be certified as running correctly with NetWare
• Your NLM will be ensured to use network resources correctly and thus, will not affect the performance of the network or its integrity adversely
• Your sales will increase as more and more customers look for the "Yes, NetWare Tested & Approved" logo on the products they consider purchasing
• You have an additional, indirect source of technical support through Novell Labs that can help you write less code, encounter fewer problems, and generate better applications.

Step 1: Purchase the NLM Certification Kit

The kit includes the following:

• NLM Certification Manual - Read this manual first. It explains what behavior testing is and how to do it, as well as how to use the utilities provided on the diskette. It also explains how to submit a product for certification and the associated fees involved.
• PCL User's Manual - A user's manual that describes how to determine the percentage of your NLM that is executed during your own testing procedure and helps you develop adequate testing procedures for your application.
• NLM Master User's Guide - describes the suite of products you are provided that allow you to automate your NLM or DOS application testing on a network. This manual lets you automate the tests you created with PCL (Procedure Coverage Logger).
• Three diskettes - that contain behavior testing utilities and user activity simulators.

Step 2: Perform Testing at Your Location

Note that you can stop at this step and never have to get your NLM certified, even if you purchase and use the kit in the design of your product. It is important to Novell that you use the kit to develop a quality NLM. Getting your NLM certified is a choice only you can make.

Step 3: Fill Out Forms and Pay Certification Fees

• Novell Labs Agreement - this form establishes the legal relationship between Novell and your company. You fill out this form only once no matter how many of your products are being certified.
• Testing Request Form - you must fill out one of these forms for each product that you want tested and certified. Note that testing is requested and paid for by product, not by NLM.

Finally, you will need to call Novell Labs and obtain an evaluation purchase order number at 1-801-429-5544.

Step 4: Submit Your NLM to Novell Labs

• Results of the behavior testing of the NLM performed at your site.
• Any specialized equipment required for your NLM (for example, your NLM may require a particular CD-ROM drive). Novell Labs has standard network equipment at their site. All equipment submitted will be returned when testing is complete.
• Two copies of your NLM: a copy containing Novell debugging information and a standard release copy.

Step 5: Novell Labs Tests and Certifies Your NLM

Step 6: Submit Shrink-Wrapped Products to Novell Labs

Special Limited Time Offer

Object Oriented Development Tools Announced (Special supplement)

PowerBuilder provides developers with an integrated suite of application painters and tools through which they completely manage the development process. PowerBuilder's object oriented approach allows developers to easily build quality graphic applications that communicate with high-performance database servers and particular NetWare services.

Under a joint development and marketing agreement, Novell will provide Powersoft with engineering support to ensure that the NetWare 3.11 and 4.0 APIs for directory, file, and print services are fully implemented as a PowerBuilder Library for NetWare.

Powersoft and Novell plan to work together to gather customer input to determine which additional services to incorporate in the future. The product will be available for all the operating systems that Powersoft supports.

In addition to the PowerBuilder Library for NetWare, Powersoft will develop interfaces to Novell's Btrieve record management system and the NetWare SQL relational database system. Database interfaces have been an integral part of PowerBuilder since its initial release. These interfaces allow developers to connect relational database servers to their applications. Currently, PowerBuilder provides access to the NLM and other versions of popular SQL engines such as Oracle, Sybase and Informix.

PowerBuilder for NetWare will be available during the third quarter of 1993.

For More Information

NOVELL DEVELOPER EDUCATION

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.

CURRENT PATCHES FOR NOVELL DEVELOPMENT TOOLS

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, you may request these files from Novell's Developer Support Group at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.

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

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

To use the AFS, call 1-800-RED-WORD (1-800-733-9673) or 512- 794-1799 from a touchtone phone. Choose the option for the Automated Fax System, select the documents you wish to receive, and supply your fax number (the fax number to which you want the document(s) sent). Document #7805 describes the patches. Document #1 lists other documents available through the AFS. You may request up to five documents per call.

CONTACTING NOVELL

Developer Support

Voice

Fax

Developer BBS

E-mail: CompuServe

E-mail: MHS

E-mail: Internet (SMTP)

NetWire on CompuServe

Novell Products and SDKs

Novell Labs

Novell Developer Relations

Voice

Fax

NetWire on CompuServe

E-mail: MHS or Internet (SMTP)

ACKNOWLEDGEMENTS

Contributors: Linda Anderson Jack Gumaer Chris Ojeda Raj Perubhatla Matt Pinsonneault Bob Quinlan Randy Reddy Michael A. Spano Wolfgang Schreiber Glenn Stephens Aslam Tejani Shiva E. Waldecker Brenda Wallace

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

(c) 1993 Novell, Inc. All rights reserved. Novell, the N design, NetWare, Btrieve, XQL, LAN WorkPlace 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 RPC, NetWare RPC 386, NetWare LU6.2, Report Executive, NetWare MHS, NetWare Asynchronous Communication Services (NACS), NetWare Management System, Professional Development Series, NetWare 3270 LAN Workstation, SFT III, 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. Apple, AppleTalk, and Macintosh are registered trademarks of Apple Computer, Inc. CompuServe is a registered trademark of CompuServe Corporation. NFS is a registered trademarks of Sun Microsystems, Inc. UNIX is a trademark of UNIX Systems Laboratories, Inc., a subsidiary of AT&T. Univel is trademark of Univel, Inc.