INTRODUCTION

   Welcome to the next generation of Novell Interfaces, the Client API
   for C v1.00.  We are excited to bring you this kit and all the
   possibilities of distributed processing on NetWare.

   These disks contain libraries, header files, and sample code for C.
   This interface supports NetWare versions 2.2, 3.11, and 4.0.

   The libraries will support both NETX.COM and VLM environments under
   DOS with the exception of NWNET.  The NWNET library is for network
   support such as auditing and directory services.  This support
   requires the DOS requester to be loaded.  The new requesters and
   drivers for DOS, OS/2, and Windows that are necessary for supporting
   directory services are on the workstation software disks of the
   NetWare 4.0 release.

   This kit was tested using the following compilers and versions:

      Microsoft C v6.0
      Borland C v3.1

   and the following operating systems:

      MS DOS v3.31 and above
      DR DOS v6.0
      Windows v3.0 and above
      OS/2 v2.0

RECOMMENDED INSTALLATION

   We recommend that you copy the libraries to the appropriate locations
   for your DOS, OS/2, and Windows libraries.  Be aware that the DOS
   libraries and the Windows and OS/2 import libraries have the same
   names and should be placed in separate subdirectories or renamed to
   indicate which is which.  One suggested install sequence is as
   follows (installing from A: to C:):

      Insert Disk NWC100_1 into drive A:
         XCOPY A: C: /s
      Insert Disk NWC100_2 into drive A:
         XCOPY A: C: /s
      Insert Disk NWC100_3 into drive A:
         XCOPY A: C: /s
      Insert Disk NWC100_4 into drive A:
         XCOPY A: C: /s
      Insert Disk NWC100_5 into drive A:
         XCOPY A: C: /s
      Insert Disk NWC100_6 into drive A:
         XCOPY A: C: /s
      Insert Disk NWC100_7 into drive A:
         XCOPY A: C: /s

   To integrate more easily with your development environment, the
   choice is left to you.  Remember to specify the correct library path
   as appropriate for the linker you are using.

   The include files are the same for all three supported platforms. You
   will also need to copy these to either a NetWare include directory or
   your compiler include directory.  Remember to specify the correct
   include path as appropriate for the compiler you are using.

   The NWCALLS and NWNET libraries are compiler model independent for
   all workstation platforms.  The NWIPXSPX  and TLI libraries are model
   dependent for DOS.  The NWIPXSPX dynamic link library is model
   independent in Windows, as are the IPXCALLS and SPXCALLS dynamic link
   libraries in OS/2.

   TBMI and TBMI2 have now been combined into one module, TBMI2 v3.0.
   This TSR is necessary to use communications support under standard or
   real mode Windows.  TBMI2 v3.0 will work with TASKID v1.10.


DISK LAYOUT

   The disk organization is as follows:

   Disk 1:
      README.TXT
      DOS\MSC
         NWCALLS.LIB
         NWLOCALE.LIB
         NWNET.LIB
         SNWIPXSP.LIB
         MNWIPXSP.LIB
         CNWIPXSP.LIB
         LNWIPXSP.LIB

   Disk 2:
      DOS\MSC
         STLI.LIB
         MTLI.LIB
         CTLI.LIB
         LTLI.LIB
         NWPSRV.LIB

   Disk 3:
      DOS\BC
         NWCALLS.LIB
         NWLOCALE.LIB
         NWNET.LIB
         SNWIPXSP.LIB
         MNWIPXSP.LIB
         CNWIPXSP.LIB
         LNWIPXSP.LIB

   Disk 4:
      DOS\BC
         STLI.LIB
         MTLI.LIB
         CTLI.LIB
         LTLI.LIB
         NWPSRV.LIB
    
   Disk 5:
      OS2
         NWCALLS.DLL
         NWCALLS.LIB
         NWCONFIG.DLL
         NWCONFIG.LIB
         NWLOCALE.DLL
         NWLOCALE.LIB
         NWNET.DLL
         NWNET.LIB
         IPXCALLS.DLL
         IPXCALLS.LIB
         SPXCALLS.DLL
         SPXCALLS.LIB
         TLI_SPX.DLL
         TLI_TCP.DLL
         TLI.DLL
         TLI.LIB
         NWPSRV.DLL
         NWPSRV.LIB
         NETAPI.LIB
         NPCALLS.LIB

   Disk 6:
      WIN
         NWCALLS.DLL
         NWCALLS.LIB
         NWLOCALE.DLL
         NWLOCALE.LIB
         NWNET.DLL
         NWNET.LIB
         NWIPXSPX.DLL
         NWIPXSPX.LIB
         TLI_SPX.DLL
         TLI_TCP.DLL
         TLI_WIN.DLL
         TLI_WIN.LIB
         NWPSRV.DLL
         NWPSRV.LIB
         NETAPI.LIB

   Disk 7:
      INCLUDE
         All library include files
      INCLUDE\DOSNP
         DOS Named Pipes header file.
      INCLUDE\WINNP
         Windows Named Pipes header file.
      SAMPLES\WHO
         The VWHO sample program.
      SAMPLES\DIRSVC
         A Directory Services example program.
      SAMPLES\CONNECT
         A sample program to get various connection information.
      SAMPLES\BINDERY
         A sample program to scan the bindery.
      SAMPLES\TLI
         Sample server and client TLI programs.
      SAMPLES\BRAINSHR
         Various sample programs from BrainShare '93 talks.

BUILDING APPLICATIONS

   Some requirements exist to properly use these libraries on the
   several platforms supported.  First, the correct definitions need to
   be set up to compile properly:

   for   DOS      #define NWDOS
   for   Windows  #define NWWIN
   for   OS/2     #define NWOS2

   Second, be aware that all pointers are far pointers and the functions
   are far pascal.  The only exceptions to this are the NetWare
   equivalents to the C runtime printing calls which are cdecl
   functions.

   Third, in order to use the NWNET library, you must first call
   NWInitUnicodeTables.  To use the NWCALLS library, you must first call
   NWCallsInit.  To use the IPX and SPX functions, you must call
   IPXInitialize or SPXInitialize.  It is important to specify which
   model of runtime libraries you want you application to link with as
   well.  This should be the model that your application is built in. 
   For example, you would use llibcep.lib for OS/2, llibce.lib for MSC
   DOS, llibcew.lib for MSC Windows, or cl.lib for BC DOS if your
   application is compiled in large model.

SAMPLE CODE

   The samples provided in the samples directories are provided "as is." 
   In order to speed up the release of the Client API for C, the samples
   were gathered on a quantity basis rather than a quality basis.  The
   samples have not been fully tested and no "standardized" makes have
   been provided. In some cases, no makes have been provided at all.

   Two samples, in the WHO and DIRSVC directories, work for DOS, OS/2,
   and Windows. The make files are for POLYMAKE v4.00.  To use the make
   files properly, you will need to set the following environment
   variables: 

      1. MAKE_PATH to the directory where make.exe for POLYMAKE v4.00 is
         located.
      2. DEBUG=y if you want debug symbols.
      3. MODEL=<model size in all caps> if you want a model other than
         MEDIUM.

   These make files currently assume the structure:

      DOS\MSC
      DOS\BC
      WIN
      OS2
      INCLUDE
      SAMPLES\WHO
      SAMPLES\DIRSVC

   They also assume a path to the compilers beginning at t:\.  To use
   the make files, edit makefile.mak and change the t:\ paths to your
   paths.

   Sample Microsoft make files for Windows are also included for both
   WHO and DIRSVC and can be modified for other platforms.  They assume
   that the environment is set up to find compilers, linkers, Windows
   RC.EXE, libraries and includes.

   Two samples, in the BINDERY and CONNECT directories, have been
   completed for DOS and OS/2 in small and large models only.  In OS/2,
   the samples have not been tested or built for a multi-threaded
   environment.  These latter two samples consist of one C file each and
   do not have make files.

   In the WHO and DIRSVC directories, a sample Microsoft make file for
   Windows is available and can be modified for other platforms.  It
   assumes that the environment is set up to find compilers, linkers,
   Windows RC.EXE, libraries and includes.

   All other samples were gathered from various engineers at Novell,
   including those used for talks at BrainShare '93.

LAST MINUTE ISSUES AND CORRECTIONS

   Compilers Supported

      Although Microsoft C v7.0 was not fully tested against these
      libraries, no incompatibilities were expected.  However, one
      incompatibility has been found.  The /Gx (assume that data is near)
      switch under Microsoft C v7.0 is currently required against all
      modules that are to be linked with the DOS libraries.

   NWDSCreateContext vs NWDSDuplicateContext

      NWDSCreateContext, by design, grabs the context from the nearest
      server. This means there is no guarantee that the context will be
      on a specific server.  To guarantee that a context is returned from
      a specific server, call NWDSDuplicateContext, which allows a new
      context to be created that uses the same connection as the context
      from which it was duplicated.


   NWCallsInit

      In DOS, you must call NWCallsInit before making any calls to
      NWCalls.  This will detect and initialize the link to either NETX
      or VLM.  It will also initialize the double byte tables.

      In Windows and OS/2, the LIBMAIN function, or its equivalent, will
      call NWCallsInit.

      You can call NWCallsInit multiple times.  Subsequent calls will
      simply return the same value as the first without performing any
      operations.


   NWDS Calls - NWInitUnicodeTables

      You must call NWInitUnicodeTables successfully, before you call any
      NWDS (Directory Services) calls; otherwise, all NWDS calls will
      fail.

      If NWInitUnicode fails, do not call any NWDS calls.


   NWDS Calls - Stack Size

      When using the NWDS calls, we recommend that you add 6k bytes to
      your stack size over what you originally determined for your
      program needs.


   Return Codes from NWNET
      (see error code appendix)

      -300 errors generated by NWNET
      -600 errors generated by the server (DS only)
      89XX error generated by the server
      88xx errors generated on the client


   Directory Handles, Paths, and Namespaces 

      Directory handles, paths, and namespaces must be in agreement when
      calling functions.


   OS/2 Namespace

      In OS/2, the OS/2 namespace is assumed if the volume in question
      has the OS/2 namespace loaded; otherwise, the DOS namespace is
      used.


   NWSetDirEntryInfo

      If NWSetDirEntryInfo returns error code 0x89FF, it means that
      insufficient information was passed to the function.  The structure
      newEntryInfo requires information that is supplied by
      NWScanDirEntryInfo. Once this information is supplied, you can
      modify the structure fields as specified in the changeBits
      parameter.


   NWLOGIN_TIME

      We recommend the you avoid the use of the constant NWLOGIN_TIME.
      NWLOGIN_TIME is defined as an array of 7 bytes and can cause
      difficulties in programming.


   NWIsIDInUse

      The return values for NWIsIDInUse are incorrect.  A non-zero return
      value indicates that a connection handle is being used.

      NWIsIDInUse is useless when VLM is running since connection handles
      are abstract values generated by the VLM itself. NWIsIDInUse is in
      the library for backward compatibility only.

      To determine the number and list of actual connection handles,
      useNWGetMaximumConnections and NWGetConnectionList.


   NWScanForTrustees

      NWScanForTrustees returns DOS file names (8.3).  The reference to
      OS/2 paths pertains only to the parameters that are passed to the
      function, not to the parameters that are returned.


   NWGetKnownServersInfo

      The following structure is documented as follows in
      NWGetKnownServersInfo and is incorrect:

         struct {
            WORD Reserved
            LONG numberOfEntries;
            BYTE data[512];
         } NWFSE_KNOWN_SERVER_INFO;

      The documentation states that NWFSE_KNOWN_SERVER_INFO.DATA contains
      repetitive iterations of the following variable length structure,
      where serverName is not NULL-terminated:

         struct {
            BYTE serverAddress[12];
            WORD hopsToServer;
            BYTE serverNameLen;
            BYTE serverName[serverNameLen];
         }

      The above structure is incorrect.  NWFSE_KNOWN_SERVER_INFO.DATA
      contains repetitive iterations of the following variable length
      structure, where serverName is the first character of the
      NULL-terminated server name.

         struct {
            BYTE serverAddress[12];
            WORD hopsToServer;
            BYTE serverName;
         }


   NWGetFileServerInfo

      The serverUtilization field in the structure NWFSE_FILE_SERVER_INFO
      in the call NWGetFileServerInfo should contain the current server
      utilization; however, the number returned is sometimes a random
      number between 251 and the true utilization.


   NWDSAllocBuf

      NWDSAllocBuf cannot allocate buffers larger than 32k bytes (32768
      bytes) because of the use a signed value.  However, it is possible
      to allocate 32k bytes minus the sizeof(Buf_T) using NWDSAllocBuf
      because NWDSAllocBuf allocates the requested size plus the
      sizeof(Buf_T).


   White Space

      In canonical names for objects, numerous white spaces will be
      converted to a single space.  However, the library has problems
      with anything other than spaces.  For instance, numerous tabs may
      not be converted to a single tab, and combinations of tabs and
      spaces may not be converted to a single space.


   IPXSPX

      Diagnostics calls for Personal NetWare appear in the documentation,
      but are not supported.  They are still under development.


   IPXSPX - OS/2 DOS Boxes

      Because of the differences between OS/2 and DOS network drivers,
      you must set the in-use flags and the completion codes of all ECBs
      used in an OS/2 DOS Box to zero before you can make an IPX call. 
      The SAP and Diagnostic calls in the IPX Library have not been
      updated to accommodate this situation and will not work correctly
      in an OS/2 DOS Box.


   NWLOCALE

      The small model NWLOCALE library is compatible with Microsoft
      Windows, Microsoft DOS, and IBM OS/2.

      The small model NWLOCALE library is not compatible with the Borland
      compiler.


   NWLOCALE

      In Windows, it is essential to set the NWCodePage variable in the
      WIN.INI file.


   Structures

      Client API structures are in Appendix A of the Programmer's Guide
      for C and Appendix B of the Client API for C.  The structures in
      the Programmer's Guide for C are organized according to the chapter
      in which they are found. The structures in the Client API for C are
      organized according to the Header files in which they are found.


   NWCALDEF.H

      _WINDOWS no longer needs to be defined to make NWCALDEF.H compile
      correctly for Windows.  Define NWWIN instead.
