SUMMARY.API.txt

 		  Lan Manager API Table of Contents


   1.    Introduction and Overview  .... 1
   1.1     Architecture of the API 
   1.2     Using APIs Remotely 
   1.3     Admin Rights 
   1.4     API Naming Convention 
   1.5     API Parameters and Data Structures 
   1.5.1     ASCIZ Strings 
   1.5.2     Structure Alignment 
   1.5.3     Level of Detail 
   1.5.4     Fixed-Length and Variable-Length Data 
   1.6     Return Values 
   1.7     GetInfo Calls 
   1.8     Enum Calls 
   1.9     SetInfo Calls 
   1.10    Time Stamps 
   1.11    Calling Lan Manager APIs 
   1.11.1     Calling APIs from Microsoft C 
   1.11.2     Calling APIs from Assembly Language 
   1.11.3     Linking to the API Libraries 
   1.12    Protection Violations and Faults in the DLL 
   1.13    General Error Codes 

   2.    SHARES  .... 13
   2.1     NetShareEnum 
   2.2     NetShareGetInfo 
   2.3     NetShareSetInfo (Admin only) 
   2.4     NetShareAdd (Admin only) 
   2.5     NetShareDel (Admin only) 
   2.6     NetShareCheck 

   3.    SESSIONS  .... 19
   3.1     NetSessionEnum (Admin only) 
   3.2     NetSessionGetInfo (Admin only) 
   3.3     NetSessionDel (Admin only) 

   4.    CONNECTIONS  .... 22
   4.1     NetConnectionEnum (Admin only) 

   5.    FILES  .... 24
   5.1     NetFileEnum (Admin only) 
   5.2     NetFileGetInfo (Admin only) 
   5.3     NetFileClose (Admin only) 

   6.    SERVER  .... 26
   6.1     NetServerEnum 
   6.2     NetServerGetInfo (Admin only) 
   6.3     NetServerSetInfo (Admin only) 
   6.4     NetServerDiskEnum (Admin Only) 
   6.5     NetServerAdminCommand (Admin only) 

   7.    AUDITING  .... 33
   7.1     NetAuditOpen (Admin only) 
   7.2     NetAuditWrite (Admin only) (Local only) 
   7.3     NetAuditClear (Admin only) 

   8.    ERROR LOGGING  .... 42
   8.1     NetErrorLogOpen (Admin only) 
   8.2     NetErrorLogWrite (Admin only) (Local only) 
   8.3     NetErrorLogClear (Admin only) 

   9.    CHARACTER DEVICES  .... 46
   9.1     NetCharDevEnum 
   9.2     NetCharDevGetInfo 
   9.3     NetCharDevControl (Admin only) 
   9.4     NetCharDevQEnum 
   9.5     NetCharDevQGetInfo 
   9.6     NetCharDevQSetInfo (Admin only) 
   9.7     NetCharDevQPurge (Admin only) 
   9.8     NetCharDevQPurgeSelf 

  10.    MESSAGE SERVER  .... 52
  10.1     NetMessageNameEnum 
  10.2     NetMessageNameGetInfo 
  10.3     NetMessageNameAdd 
  10.4     NetMessageNameDel 
  10.5     NetMessageNameFwd 
  10.6     NetMessageNameUnFwd 
  10.7     NetMessageBufferSend 
  10.8     NetMessageFileSend 
  10.9     NetMessageLogFileSet 
  10.10    NetMessageLogFileGet 

  11.    SERVICE  .... 59
  11.1     General Information 
  11.1.1     Data Structures 
  11.1.2     UIC (Uninstall) Codes 
  11.1.3     IP (Install Pending) Codes 
  11.2     NetServiceGetInfo 
  11.3     NetServiceEnum 
  11.4     NetServiceInstall 
  11.5     NetServiceControl 
  11.6     NetServiceStatus 

  12.    CONFIG  .... 69
  12.1     NetConfigGet 
  12.2     NetConfigGetAll 

  13.    ALERT  .... 71
  13.0.1     Print Alert, Class-specific Information 
  13.0.2     Message Alert, Class-specific Information 
  13.0.3     Errlog Alert, Class-specific Information 
  13.0.4     Admin Alert, Class-specific Information 
  13.0.5     User Alert, Class-specific Information 
  13.1     NetAlertStart 
  13.2     NetAlertStop 
  13.3     NetAlertRaise 

  14.    ACCESS PERMISSIONS  .... 77
  14.1     General Information 
  14.2     NetAccessEnum 
  14.3     NetAccessGetInfo 
  14.4     NetAccessSetInfo 
  14.5     NetAccessAdd (Admin only) 
  14.6     NetAccessDel (Admin only) 
  14.7     NetAccessCheck 

  15.    GROUPS  .... 83
  15.1     NetGroupEnum (Admin only) 
  15.2     NetGroupAdd (Admin Only) 
  15.3     NetGroupDel (Admin Only) 
  15.4     NetGroupAddUser (Admin only) 
  15.5     NetGroupDelUser (Admin only) 
  15.6     NetGroupGetUsers (Admin only) 

  16.    USERS  .... 87
  16.1     NetUserEnum (Admin only) 
  16.2     NetUserAdd (Admin Only) 
  16.3     NetUserDel (Admin Only) 
  16.4     NetUserGetInfo (Admin only) 
  16.5     NetUserSetInfo (Admin Only) 
  16.6     NetUserPasswordSet 
  16.7     NetUserValidate 
  16.8     NetUserGetGroups (Admin only) 

  17.    WORK STATIONS  .... 92
  17.1     NetWkstaGetInfo 
  17.2     NetWkstaSetInfo (Admin Only) 
  17.3     NetWkstaSetUID (Admin Only) 

  18.    REDIRECT / USE  .... 98
  18.1     NetUseEnum (Admin only) 
  18.2     NetUseAdd (Admin only) 
  18.3     NetUseDel (Admin only) 
  18.4     NetUseGetInfo (Admin only) 

  19.    PRINT QUEUES  .... 104
  19.1     DosPrintQEnum 
  19.2     DosPrintQGetInfo 
  19.3     DosPrintQSetInfo (Admin only) 
  19.4     DosPrintQAdd (Admin only) 
  19.5     DosPrintQDel (Admin only) 
  19.6     DosPrintQPurge (Admin only) 
  19.7     DosPrintQPause (Admin only) 
  19.8     DosPrintQContinue 

  20.    PRINT JOBS  .... 110
  20.1     DosPrintJobEnum 
  20.2     DosPrintJobGetInfo 
  20.3     DosPrintJobSetInfo 
  20.4     DosPrintJobAdd 
  20.5     DosPrintJobSchedule 
  20.6     DosPrintJobDel 
  20.7     DosPrintJobPause 
  20.8     DosPrintJobContinue 
  20.9     DosPrintJobGetId 

  21.    PRINT DESTINATIONS  .... 116
  21.1     DosPrintDestEnum 
  21.2     DosPrintDestGetInfo 
  21.3     DosPrintDestControl (Admin only) 
  21.4     DosPrintDestStatus 
  21.5     Writing a Print Queue Processor 

  22.    PIPES  .... 121
  22.1     DosMakeNmPipe 
  22.2     DosQNmPipeInfo 
  22.3     DosConnectNmPipe 
  22.4     DosDisconnectNmPipe 
  22.5     DosQNmpHandState 
  22.6     DosSetNmpHandState 
  22.7     DosPeekNmPipe 
  22.8     DosTransactNmPipe 
  22.9     DosCallNmPipe 
  22.10    DosWaitNmPipe 
  22.11    DosQNmPipeSemState 
  22.12    DosSetNmPipeSem 
  22.13    DosOpen 
  22.14    DosClose 
  22.15    DosDupHandle 
  22.16    DosQHandType 
  22.17    DosQFHandState 
  22.18    DosSetFHandState 
  22.19    DosWrite, DosWriteAsync 
  22.20    DosRead, DosReadAsync 
  22.21    DosBufReset 

  23.    MAILSLOTS  .... 132
  23.1     DosMakeMailslot 
  23.2     DosDeleteMailslot 
  23.3     DosMailslotInfo 
  23.4     DosReadMailslot 
  23.5     DosPeekMailslot 
  23.6     DosWriteMailslot 

  24.    PROFILE  .... 137
  24.1     NetProfileSave (Admin Only) 
  24.2     NetProfileLoad (Admin Only) 

  25.    STATISTICS  .... 141
  25.1     NetStatisticsGet (Admin only) 
  25.2     NetStatisticsClear (Admin only) 

  26.    NETBIOS  .... 144
  26.1     NetBiosEnum (Admin Only) 
  26.2     NetBiosGetInfo (Admin Only) 
  26.3     NetBiosOpen 
  26.4     NetBiosClose 
  26.5     NetBiosSubmit 

  27.    REMOTE UTILITIES  .... 150
  27.1     NetRemoteTOD 
  27.2     NetRemoteCopy 
  27.3     NetRemoteMove 
  27.4     NetRemoteExec 

  28.    Standard Lan Manager Services  .... 155
  28.1     Workstation Service 
  28.2     Server Service 
  28.3     Spooler Service 
  28.4     Messenger Service 
  28.5     Alerter Service 
  28.6     NetPopup Service 
  28.7     RunServer Service 
  28.8     NetLogon Service 

  29.    Writing Lan Manager Service Programs  .... 159
  29.1     Summary of Service Program Requirements 
  29.2     Services and LANMAN.INI 
  29.3     A Day in the Life of a Lan Manager Service Program 
  29.4     Communication Amongst Applications, Lan Manager, and the Service 
  29.4.1     Services and NetServiceControl 
  29.4.2     Services and NetServiceStatus 
  29.4.3     Other NetService APIs. 
  29.4.4     The Signal Handler 
  29.5     Service Startup 
  29.6     Service Operation 
  29.7     Service Pause and Continue 
  29.8     Service Shutdown 
  29.9     Multi-Process Services 

  30.    Alphabetical List of APIs  .... 167

  31.    OS/2 NETBIOS DEVICE DRIVER INTERFACE  .... 169
  31.1     Introduction 
  31.2     Netbios Driver Configuration 
  31.3     Netbios Driver Initialization 
  31.4     Netbios NCB Handler 
  31.5     Common problems and hints 




                Microsoft LAN Manager API

1.   Introduction and Overview 

This document describes the Applications Programming Interface
(API) for the Microsoft OS/2 LAN Manager.  Read it carefully,
ESPECIALLY THIS CHAPTER.  This initial chapter provides essential
information on the API system as a whole.  The remaining chapters can
be used as a reference for the various API functions, but will make
only brief mention of topics covered in the first chapter.

The Applications Programming Interfaces (API) for the Microsoft LAN
Manager give access to network functions through a well-defined
interface for high level languages. The API provides two categories
of functions:

    - applications oriented calls: These calls allow network
      aware applications to perform functions such as using or 
      unusing network resources, interrogating or controlling 
      remotely spooled printing, sending or receiving network 
      messages, etc.

    - administration oriented calls: These calls allow complete
      access to or control over local remote server functions. 
      Examples start or stop server programs, share or unshare
      server resources, interrogate/control server sessions, etc.

You should print out a copy of the file NETCONS.H for reference
when reading this document.  NETCONS.H defines many of the sizes
of items in the API data structures.  In this document such sizes
are given only symbolically, using the manifests defined in NETCONS.H.


1.1  Architecture of the API 

All of the OS/2 Lan Manager APIs are in Dynamic Link Libraries
(DLLs).  Applications may access these APIs using the same methods as
they access the OS/2 API DLLs.  Standard LIB files have been provided
to simplify the task;  applications need only link with the proper
LIB files, and the loader will complete any references to the Lan
Manager APIs at application load time.


1.2  Using APIs Remotely 

The API allows remote servers and server resources to be controlled
just like local resources.  Most functions have a servername
parameter that indicates the machine which is the target of the
operation, and is of the form "\\SERVERNAME".  This parameter is NULL
when the operation is performed locally.    

A servername which matches the local machine will cause the
operation to be performed locally, just as if NULL were specified
for that parameter.

To protect remote systems, some APIs require admin privilege on the
part of the caller, or they will be rejected by a remote machine. 
Such calls are marked "Admin Only".  Such security is not implemented
for local calls, only for remote calls.  See the next section for
more information on Admin Rights.

Some APIs require that certain services be running, for example the
DosPrint APIs require the Spooler service.  This requirement is only
for LOCAL operation.  As long as the Workstation service is running,
any API which can has a remote-servername parameter can be used
remotely, provided the remote server specified accepts the call. 
This allows an application to, for example, query the status of
print queues on a server, even though the local spooler is not
running.

In order to use APIs remotely to a server, that server must be sharing
IPC$, the special inter-process communication (IPC) share.  You
can do this from the command line (on the server) by typing 
"NET SHARE IPC$", or from a program using the NetShareAdd API.  If
you attempt to remote an API to a server which is not sharing IPC$,
you will be the error NERR_BadTransactConfig.  User-security servers
automatically share IPC$ and ADMIN$ at startup, but share-security
servers do not.
      
For more infomation about user and share security, see the Microsoft
LAN Manager Administrator's Guide.
          
1.3  Admin Rights 

Some APIs require admin rights when you attempt to execute them
remotely.  These APIs are marked "Admin Only" in the reference.
Other APIs will have restricted operation for non-admin users.
Such restrictions are noted in the reference.

An API which fails because of lack of admin privilege for a
remote operation which requires it, will return 
ERROR_NETWORK_ACCESS_DENIED.

The determination of admin rights depends on the type of server you
are accessing.  On user security servers, a user has ADMIN rights if
the user's privilege level (in the user account definition) is
ADMIN.  On share security servers, a user has ADMIN rights if the
user has a connection to the ADMIN$ share; the ADMIN$ share should
have a password to prevent unauthorized users from connecting to it
and thus gaining admin rights.

Note that "Admin" calls can always be executed on the local system.
The restrictions are only on calls made to remote machines.


1.4  API Naming Convention 

The Lan Manager API is partitioned into categories according to the
resources that it lets you manipulate, such as network sessions,
shared devices, user and group lists, etc.  For example, all APIs
dealing with the workstation are called NetWksta<something>.

Each API also contains a "verb". There are verbs for adding and
deleting resources, enumerating defined resources, getting and
setting resource parameters, and performing control operations on
resources. The common API verbs are as follows:

    Add          Add the specified resource.  The parameters
                 for the new resource are supplied.

    Del          Delete the named resource.

    GetInfo      Return parameters for the named resource.  All or
                 partial parameters can be requested.

    SetInfo      Change parameters for the named resource.  All or
                 partial parameters can be changed.

    Enum         Enumerate the names of all defined resources of the
                 specified type (e.g., all print queue names or print job IDs).
                 Optionally provide full parameter information for each
                 one (as in GetInfo).

There are several other miscellaneous verbs that have specific
functions for specific resources (eg, NetServiceControl to
pause/continue network services and NetWkstaSetUID to set the local
username and ID).

The following function categories are defined by the Lan Manager API:

Class                       Description
-----                       -----------

WORKSTATION                 workstation configuration information
USE                         workstation use of network resources
MESSAGING                   user to user messaging
ALERT                       monitor and raise network alerts
PIPES                       two way interprocess communication
MAILSLOTS                   one way interprocess communication
NETBIOS                     direct access to NETBIOS drivers
PROFILE                     save/restore active uses/shares
CONFIG                      get entries from the LANMAN.INI file
SERVICE                     install, control, and query network services
SERVER                      server configuration and statistics
SHARES                      server file and device shares
SESSIONS                    server machine sessions
CONNECTIONS                 server user connections
FILES                       server open files
AUDITING                    audit trail logging
ERROR LOGGING               system error logging
CHAR DEVICES                remote character device connections
PRINT QUEUES                spooler job queues
PRINT JOBS                  spooler print jobs
PRINT DESTINATIONS          virtual devices in the spooler
ACCESS                      access permissions for files and other resource 
GROUP                       group definition and membership
USER                        user accounts
STATISTICS                  workstation and server operating statistics
REMOTE                      remote execution functions


1.5  API Parameters and Data Structures 

The API function parameters are defined in the reference sections
on each API.  Note that all pointers are declared "far".  Even when
calling the API functions from small-model programs, far pointers
must be provided.

Data structures are defined using C syntax.  Where such syntax cannot
describe the structure, approximations are used.  For example, a
structure holding an unsigned integer and a signed integer, followed
by two ASCIZ strings, would be defined as follows:

        struct x 
        {
                unsigned int    x_a;
                int             x_b;
        }

                followed by:

        x_name1[];              /* ASCIZ */
        x_name2[];              /* ASCIZ */


1.5.01 ASCIZ Strings 

Fields noted as ASCIZ are nul-terminated ASCII strings, the string
type used by C.  This is a sequence of non-zero bytes terminated by a
zero byte.  

  o  Where the field is an array, the whole string fits in the 
     array given.  Such arrays are usually declared with a size
     of "X+1", to allow room for the terminating nul byte.

  o  Where the field is a pointer, it points to an area of memory
     whch contains the ASCIZ string.  Use of a pointer allows the
     size of the string to not be fixed by the structure definition.

  o  Where the field is an unsized array, designated by the pseudo-C
     code "x[]" or "x[..]", the ASCIZ string is defined as beginning
     after some other field, or at some offset from the structure.
     Such strings may be defined to occur in series, as "x_name1" and
     "x_name2" above.  The second string begins immediately after
     the end (bul byte) of the first string.

1.5.02 Structure Alignment 

The Lan Manager data structures are intended to be used with or
without packing (Microsoft C 5.1 option -Zp).  Fields called "pad",
such as shi1_pad1 in the structure "share_info_1", are used to pad
the structure and word align the next element.  Where a structure
ends with such a pad byte, it exists to force the structure to be an
even number of bytes, so that an array of such structures will be
word-aligned.  It is up to the application to insure that the start
of such a structure is on a word boundary.


1.5.03 Level of Detail 

Some data structures are provided with various levels of detail. 
Each level of information is represented by a C structure.  The more
detailed levels usually include all the information in the previous
level. Although this is NOT guaranteed to always be true in the
future, it is true in all current structures.  

Where an API accepts or provides more than one level of information,
a parameter is provided to indicate the level of information
desired/provided.  Some calls, such as Add, may require a specific
level.  If an unacceptable level parameter is passed to an API
function, the function will return ERROR_INVALID_LEVEL.

Not all fields are fully readable and writeable, for example the
password field of a user_info_1 structure will be returned as a null
string always.  GetInfo and Enum will return unreadable parameters as
null.  Add and SetInfo will ignore parameters that are not writeable.
For Add, unless otherwise specified, all fields are writeable.  For
SetInfo, each call explicitly lists the settable fields.

Note also that requesting certain levels of information is
pointless.  Many times the level-0 information wil be the same as
what you pass to the GetInfo API to get the info.  Most level-0
structures are provided for use with Enum calls.


1.5.04 Fixed-Length and Variable-Length Data 

All calls that take data structures do so via a buffer pointer and
length, where the structure is contained at the start of the
specified buffer.  Although each resource structure has a fixed
format, some parameters are pointers to variable length strings. When
such parameters are present on Add and SetInfo calls, it is desirable
for the caller to provide a buffer large enough for both the fixed
size structure and the variable length information (e.g., ASCIZ
strings).  This is allows the API to optimize processing if the call
is to a remote host.  Null pointers may be specified for variable
length parameters that are not supplied.

Note that because a buffer length is specified, result parameters are
provided on API calls to indicate how much data was available if the
supplied buffer was too small.  Where a variable-length item could not
fit in the buffer, its pointer is set to NULL.

NOTE:  None of the API calls will return partial fixed-data
structures.  If GetInfo is passed a buffer too small to contain the
fixed structure, it will return an error code NERR_BuffTooSmall.
Enum will stop stuffing items in the buffer when it cannot fit the
fixed portion completely.  Given a buffer which will hold the fixed
struct, both types of routines will happily stuff as much variable
data as will fit after the fixed stuff.

EXCEPTION:  The NetStatisticsGet API will return as much of the
structure as will fit into the buffer.  This API treats the data as
an array of longs (DWORDs), even though the header file and reference
define this data as a structure.


1.6  Return Values 

All LAN Manager APIs return an unsigned int, which is 0 if they were
successful.  Each function's documentation lists the error codes
which may be expected.  This list is not guaranteed to be exhaustive,
but does list all errors an application should be prepared to handle
routinely and gracefully.


1.7  GetInfo Calls 

GetInfo calls are used to get information on a specific instance of 
something, such as a workstation, a connection, a user, etc.

The caller specifies what level of information is desired,
a "key" designating the resource of interest, a buffer
for the returned data, and the size of that buffer.

If a call to GetInfo provides a buffer too small to hold the
fixed portion of the data, the API returns NERR_BufTooSmall,
and no information is placed in the caller's buffer.  However, the
total amout of data available, in bytes, is placed at the location
pointed to by the "totavail" parameter.  It is quite valid to
call the API with a buffer of zero bytes (buffer may be NULL).
If the error returned is NERR_BufTooSmall, allocate a buffer using
the number of bytes from "totavail" and call the API with this
new buffer and size.  

If the buffer is big enough for the fixed-length data, but not
for ALL of the data, the API function will return ERROR_MORE_DATA.
In this case, the buffer contains the data structure expected,
but some of the pointer fields may be NULL.  See "Variable-Length
Data", above.  As for NERR_BufTooSmall, the "totavail" field gives
and indication of the amount of data available and thus the buffer
size needed.

Totavail is NOT filled in if the API encounters an error during
processing, so the totavail value returned is valid only if the call
returns one of:

        0
        ERROR_MORE_DATA
        NERR_BufTooSmall


1.8  Enum Calls 

Enum calls enumerate a list of items within a given domain, such
as all servers on a network, all users on a system, all connections
to a given server, etc.  

Enum calls will always return an integral number (zero or more) of
fixed length structures.  API functions never return partial
structures.

The fixed structures returned will start at the low address of the
buffer and be packed contiguously into the buffer.  Variable-length
data (see above) will be packed somehwere past the last fixed
structure.  Usually this starts at the high address of the buffer
and works downward, but do not rely on this -- use the pointers in
the fixed structures to refer to variable-length data fields.

If the user buffer is not large enough, some of the variable length
data may not be returned, possibly only for the last entry but not
necessarily.  The return code is ERROR_MORE_DATA whenever the
user-supplied buffer is not large enough to hold all entries,
including all variable-length data. The "entriesread" parameter
indicates the number of fixed length portions that were returned. 
Some or all of these may have only a part of the associated variable
data returned with them.  If a given varlen value has NOT been
returned, its pointer will be returned as NULL in the fixed length
structure.

Enum calls usually return both the number of entries read and the
number of entries available.  Entries available is the total number
that could be retrieved and is always equal to or greater than the
number of entries read.  These values are valid after a call which
returns either ERROR_MORE_DATA or success (zero).

All Enum calls can be called with a buflen of zero and a NULL
pointer.  You won't get any data, but you will learn the total number
of entries available, as noted above.


1.9  SetInfo Calls 

SetInfo calls are used to set one or more fields of an item.  

The easiest way to set a single field is to use the "parmnum"
parameter to indicate which field to set, and pass the value directly
in the buffer.  For example, to set the workstation's error-log file
size limit to 200K, use the following code fragment:

        unsigned short errsize = 200;

        NetWkstaSetInfo ( 
            NULL,                       /* Local machine */
            0,                          /* Level, must be zero for wksta */
            &errsize,                   /* Buffer */
            sizeof(errsize),            /* Buffer size */
            WKSTA_ERRLOGSZ_PARMNUM      /* parmnum, from wksta.h */
                        );

Note that in this case the buffer is only two bytes, and consists
only of the value being set.  For a string parameter, the buffer is
the string itself, and the size must include the NUL terminator.  DO
NOT pass pointers when using the single-field mode. Pass the ASCIZ
string itself as the buffer.  Example:

        static char comment[] = "New comment here";
        int clen;

        
        clen = sizeof(comment);
                <or>
        clen = strlen(comment) + 1;

        NetServerSetInfo (
            NULL,                       /* Local machine */
            0,                          /* Level, not used for single-field */
            comment,                    /* Buffer */
            clen,                       /* Buffer length */
            SV_COMMENT_PARMNUM          /* parmnum, from server.h */
                         );

To set multiple fields, either make multiple calls using the
"parmnum", or set the entire structure at once.  In this case, the
buffer is a structure of the proper format, and parmnum is zero.

When setting the whole structure, fields that are not settable are
ignored.  If a string is settable, but the pointer is set to NULL, it
is left unchanged.  To set a string to the empty string, use a
pointer to the empty string.

NOTE:  When setting the whole structure, ALWAYS do a GetInfo into the
buffer, change the fields, and then do a SetInfo.  Do this even if
you think you are placing values in all settable fields.  This will
protect you from future changes, which might define more fields as
settable.  If you do a SetInfo without a prior GetInfo, you could
end up with garbage in those fields, or have your call rejected with
the error ERROR_INVALID_PARAMETER.  

Example:  suppose we wanted to make user "Fred" an administrator, and
set his comment to reflect that status.

        struct user_info_1 ubuf;
        unsigned err;

        err = NetUserGetInfo ( NULL, "Fred", 1, &ubuf, sizeof(ubuf), &avail );

        if (err == 0 || err == ERROR_MORE_DATA)
        {
                ubuf.usri1_priv = USER_PRIV_ADMIN;
                ubuf.usri1_comment = "Newly promoted admininstrator";

                NetUserSetInfo ( NULL, "Fred", 1, &ubuf, sizeof(ubuf), 0 ); 
        }


1.10 Time Stamps 

All absolute date/time parameters are in seconds since Jan 1, 1970.
Date/time is returned as local time relative to the caller of the
api.  A future release of LAN Manager will do automatic date/time
zone conversion to local time if the target of the api is in a
different time zone.


1.11 Calling Lan Manager APIs 

The APIs for Lan Manager for OS/2 are very similar to the OS/2
API functions.

  o  All API calls are far.

  o  All API parameters are pushed on the stack, in the order they
     are declared, before the far call is made.

  o  The API function itself will remove the parameters from the stack
     as part of the return to the caller.


1.11.01 Calling APIs from Microsoft C 


C programs that call Lan Manager API functions should include the
proper header files, as noted in each API's reference section.
These header files provide #define's for various values used with
the APIs, and complete function prototypes.

If you do not use the function prototypes (we suggest you do),
be sure to at least declare the API functions as "extern unsigned
far pascal".  The "pascal" keyword is essential and causes the compiler
to generate the proper calling sequence, defined above.


1.11.02 Calling APIs from Assembly Language 

As noted above, all calls are far, and parameters are pushed on the
stack.  The first parameter is pushed first.  When the API function
returns, the stack pointer will have been adjusted so that the parameters
have been removed from the stack.   This is the "pascal" or "PLM"
calling convention.

Return values are all in AX.  All API functions return a WORD-sized
value which is the success or error code.

Make no assumptions about preservation of registers across a call to
the API functions, except that DS,SS will be preserved, SP will be
adjusted as above, and of course CS:IP will be the value pushed
on the stack during the CALL.  

Function names should be given in all uppercase, for example,
NETWKSTAGETINFO.  

Assembly language programmers may make the following assumptions 
about data sizes:

        char                    BYTE
        unsigned char           BYTE
        short                   WORD
        unsigned short          WORD
        long                    DWORD
        unsigned long           DWORD   

        unsigned                currently WORD




1.11.03 Linking to the API Libraries 

SInce the Lan Manager APIs are stored in a set of DLLs
(dynamic link libraries),  applications may use any of the
methods defined for linking to these libraries.

The most convenient way is to link to the .LIB files provided.
These files cause the MS Link program to resolve references
to Lan Manager API functions properly, by providing information
about the name and entrypoint ordinal of the DLL.

The following library files are provided:

        NETAPI.LIB              Net API functions
        NETOEM.LIB              Net API functions
        NETSPOOL.LIB            DosPrint API functions
        NAMPIPES.LIB            DosNmPipe API functions
        MAILSLOT.LIB            DosMailslot API functions


1.12 Protection Violations and Faults in the DLL 

The API functions probe the buffers passed to them and scan string
parameters in an attempt to insure that the data is accessable.
These probings may cause faults if the pointers are bad, such as
pointing beyond the end of a segment, or when a pointer is NULL and a
NULL pointer is not allowed.

If you get a fault within a Lan Manager DLL, attempt to trace your
code through the call.  You can usually recognize, by noting which
values are being tested, exactly which parameter is causing the
problem.  Carefully check buffer sizes, since the APIs will probe the
first and last byte of a buffer even if the actual data to be
returned or recieved is small.

If you get a stack overflow, extend your stack.  There is no hard
rule for the depth of stack required by Lan Manager APIs in this
release.  In general, allow 2K free stack space for an API call. This
should be quite safe, even if the thread in question will be
interrupted by signals.


1.13 General Error Codes 

The error codes described here are nearly universal throughout the
Lan Manager APIs.  These error codes can be found in either "neterr.h"
or the standard OS/2 error header files, which were called "error.h"
and "error2.h" in the OS/2 SDK.


o ERROR_MORE_DATA

This error is returned when the buffer supplied to the API is not big
enough to hold all the data available.  As much data as possible has
been returned in this buffer.  Some indication of the amount of data
has been returned, usually in the form of a pointer-to-value
parameter.  More information is available above, under the general
information on Enum and GetInfo APIs.

To get the rest of the data, you can allocate a bigger buffer and try
the call again.  If the data you need is in the buffer, there is no
need to retry.  


o ERROR_INVALID_LEVEL

For APIs which take a "level" parameter, there is a defined set of
values which are acceptable.  Note that for some APIs, even though
there may be multiple levels of data defined, only one level may be
acceptable.  For example, NetShareAdd requires level 2 share data.
This error is returned in all cases where the value of level was not
acceptable.


o NERR_BufTooSmall

This error is returned when the buffer supplied to the API is not big
enough to the hold data, either input or output.  In this case, NO
DATA is returned in the buffer, in contrast to ERROR_MORE_DATA, which
indicates that some, though not all, of the data was returned.
Allocate a bigger buffer (using the value returned in the
"totalavail" parameter, if such is provided) and try again.  


o ERROR_INVALID_PARAMETER

This is a generic error which indicates a parameter is invalid.  Each
API's documentation will give some hints as to which parameters could
cause this error to be returned.  In general, parameters to check
include 

        SetInfo:        Parmnum parameter.
                        The value(s) you are trying to set.

        Add:            Any field used by the API.  Be sure you
                        have filled in all required values.


o NERR_NetNotStarted

Despite the name, this error really means that the network software
is not INSTALLED.  That is, the core drivers were not loaded at boot
time.  Almost no APIs will work without these drivers installed.


o NERR_WkstaNotStarted

The network software is installed, but the workstation is not
running.  To start the workstation at the command line, type "NET
START WKSTA".  Or, use the NetServiceInstall API.  A few APIs will
work even with the workstation not running, and so will not return
this error.


o NERR_ServerNotStarted

The network software is installed, but the server is not running.  To
start the server at the command line, type "NET START SERVER".  Or,
use the NetServiceInstall API.  Note that before you can start the
server, the workstation service must be running.  The Lan Manager
command-line interface handles this automatically.


o NERR_ACFNotLoaded     

This API requires that a user-level security server be running.


o NERR_BadTransactConfig

The remote station is not configured for remote transactions. 
Usually this means the server you are attempting to access with a
remote API is not sharing IPC$.  A server must share IPC$ to allow
other machines to submit remote API calls to it.


o ERROR_NETWORK_ACCESS_DENIED

This error is the generic "security violation" error, and indicates
that the operation failed due to insufficient privilege.  


2.   SHARES 

These functions deal with resource sharing at a server.  
All of these functions should be used with the include file "shares.h".
The access bits are defined in "access.h".
There are three levels of information available:


    struct share_info_0 {
        char            shi0_netname[NNLEN+1];
    };
    

    struct share_info_1 {
        char            shi1_netname[NNLEN+1];
        char            shi1_pad1;
        unsigned short  shi1_type;
        char far *      shi1_remark;
    };


    struct share_info_2 {
        char            shi2_netname[NNLEN+1];
        char            shi2_pad1;
        unsigned short  shi2_type;
        char far *      shi2_remark;
        unsigned short  shi2_permissions;
        unsigned short  shi2_max_uses;
        unsigned short  shi2_current_uses;
        char far *      shi2_path;
        char            shi2_passwd[SHPWLEN+1]; 
        char            shi2_pad2;
    };


netname         The netname is the name by which a share is exported
                to the network.  This name may be between 1 and NNLEN 
                characters long.
                Only standard file-system component characters are allowed.

type            Type of resource being shared, may be one of:

                        STYPE_DISKTREE  0       File system share
                        STYPE_PRINTQ    1       Spooled print queue
                        STYPE_DEVICE    2       Character device queue
                        STYPE_IPC       3       Special IPC share

remark          Remark or comment describing a share (optional).
                An ASCIZ string which provides information about a share,
                visible to users on the network.

permissions     Share-level permissions, bitmapped usinjg the same
                values as given under the Access APIs.  

                   0    ACCESS_READ    0x1      Read from existing resources
                   1    ACCESS_WRITE   0x2      Write to existing resources
                   2    ACCESS_CREATE  0x4      Create new files
                   3    ACCESS_EXEC    0x8      Open file for execution
                   4    ACCESS_DELETE  0x10     Delete existing files
                   5    ACCESS_ATRIB   0x20     Set the resource's attribute,
                   6    ACCESS_PERM    0x40     Special, see below

                The ACCESS_PERM bit has special meaning for shares.  
                If this bit is set, a user must have ADMIN rights
                to connect to the share.  
                
                In share-level security, all bits above are used.
                These access permissions apply to ALL access through 
                the given share.  Note that a share with no permissions
                is nearly worthless;  you can connect to it but that is
                all.

                In user-level security, share-level permissions are INGORED.
                Only the ACCESS_PERM bit, with the special meaning given
                above, is used.  All other bits are completely ignored,
                and the normal user-level access permission system is
                used (see NetAccess APIs).


max_uses        The maximum number of connections which may exist to this
                resource, may be from 1 to 0xffff.  0xffff is a special 
                value, meaning unlimited connections.

current_uses    Number of current connections to this resource.

path            Generally, the local resource which is being shared.
                For print queue hares, name of print queue.
                For character device shares, the list of devices, separated
                  by spaces (e.g. "COM1 COM2 COM6").
                For disk shares, the path being shared, e.g. "C:\BIN".
                For IPC shares, usually NULL.

passwd          Password for this share, must be supplied when a user
                makes a connection to this resource (see NetUseAdd).
                Used in share-level security only.
                

------------------------
2.1  NetShareEnum 

Purpose: Supply information about all shares on a server.

unsigned far pascal
NetShareEnum( servername, level, buf, buflen, entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested; 0, 1, or 2
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Supply information about existing shares at three levels of detail.

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct share_info_0".
    Level 1 contains a "struct share_info_1".
    Level 2 contains a "struct share_info_2".

Returns 0 if successful.  Possible error returns:

        - ERROR_INVALID_LEVEL
        - ERROR_MORE_DATA
        - NERR_NetNotStarted
        - NERR_ServerNotStarted

------------------------
2.2  NetShareGetInfo 

Purpose: Read complete information about a single outstanding share.

unsigned far pascal
NetShareGetInfo( servername, netname, level, buf, buflen, totalavail )
char far *          servername;     asciz remote server name or NULL if local
char far *          netname;        asciz network name of share being queried
short               level;          level of info requested
char far *          buf;            for returned entry
unsigned short      buflen;         size of buffer
unsigned short far *totalavail;     total size needed for buffer

Buffer contents on response:
    Level 0 contains a "struct share_info_0".
    Level 1 contains a "struct share_info_1".
    Level 2 contains a "struct share_info_2".

Returns 0 if successful.  Possible error returns:
        - ERROR_INVALID_LEVEL
        - ERROR_INVALID_PARAMETER
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - NERR_NetNameNotFound
        - ERROR_MORE_DATA
        - NERR_BufTooSmall

------------------------
2.3  NetShareSetInfo (Admin only) 

Purpose: Write settable fields of a specified existing share.

unsigned far pascal
NetShareSetInfo( servername, netname, level, buf, buflen, parmnum )
char far *      servername;     asciz remote server name or NULL if local
char far *      netname;        asciz network name of share being set
short           level;          level of info provided
char far *      buf;            contents described below
unsigned short  buflen;         size of buffer
short           parmnum;        which parameter to set

Buffer contents on call if parmnum is zero:
    Level 1 contains a "struct share_info_1".
    Level 2 contains a "struct share_info_2".

Settable fields are:
    shi1_remark
    shi2_remark
    shi2_permissions
    shi2_max_uses
    shi2_passwd

Returns 0 if successful.  Possible error returns:
        - ERROR_INVALID_LEVEL
        - ERROR_INVALID_PARAMETER
        - ERROR_NOT_ENOUGH_MEMORY
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - NERR_NetNameNotFound
        - NERR_BufTooSmall

------------------------
2.4  NetShareAdd (Admin only) 

Purpose:  Share a resource

unsigned far pascal
NetShareAdd( servername, level, buf, buflen )
char far *      servername;     asciz remote server name or NULL if local
short           level;          must be 2
char far *      buf;            contents described below
unsigned short  buflen;         size of buffer

Buffer contents on call: a "struct share_info_2"


When sharing a part of a disk file sytem:

        shi2_netname            Name of the shared resource on the net
        shi2_type               STYPE_DISKTREE (0)
        shi2_remark             Remark or comment about this resource
        shi2_permissions        See above.
        shi2_max_uses           Maximum number of users (or -1 for unlimited)
        shi2_current_uses       n/a (ingored)
        shi2_path               File path (i.e. C:\TMP or D:\)
        shi2_password           Password (share security only)

When sharing a print queue (must already exist, see DosPrintQAdd to create):

        shi2_netname            Name of the shared resource on the net
        shi2_type               STYPE_PRINTQ (1)
        shi2_remark             Remark or comment about this resource
        shi2_permissions        See above.
        shi2_max_uses           Maximum number of users (or -1 for unlimited)
        shi2_current_uses       n/a (ingored)
        shi2_path               Name of the print queue
        shi2_password           Password (share security only)

When sharing a character-device queue (creates queue at this time):

        shi2_netname            Name of the shared resource on the net
        shi2_type               STYPE_DEVICE (2)
        shi2_remark             Remark or comment about this resource
        shi2_permissions        See above.
        shi2_max_uses           Maximum number of users (or -1 for unlimited)
        shi2_current_uses       n/a (ingored)
        shi2_path               List of devices (i.e. "COM1 COM2 COM5")
        shi2_password           Password (share security only)

When sharing the special IPC share:

        shi2_netname            "IPC$"
        shi2_type               STYPE_IPC (3)
        shi2_remark             Remark or comment about this resource
                                  (will default to "Remote IPC")
        shi2_permissions        See above.
        shi2_max_uses           Maximum number of users (or -1 for unlimited)
        shi2_current_uses       n/a (ingored)
        shi2_path               NULL
        shi2_password           Password (share security only)

When sharing the special ADMIN share:

        shi2_netname            "ADMIN$"
        shi2_type               STYPE_DISKTREE (0)
        shi2_remark             Remark or comment about this resource
                                  (will default to "Remote Admin")
        shi2_permissions        See above.  WARNING:  if you set the 
                                  ACCESS_PERM bit on a share-level server,
                                  for the ADMIN$, NO REMOTE ADMIN will be
                                  allowed.  See "User/Share Security".
        shi2_max_uses           Maximum number of users (or -1 for unlimited)
        shi2_current_uses       n/a (ingored)
        shi2_path               NULL.  This is automatically set to the
                                  LAN Root.
        shi2_password           Password (share security only)

Returns 0 if successful.  Possible error returns:

        - ERROR_INVALID_LEVEL
        - ERROR_INVALID_PARAMETER
        - ERROR_NOT_ENOUGH_MEMORY
        - NERR_UnknownDevDir
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - NERR_RedirectedPath
        - NERR_DuplicateShare
        - NERR_BufTooSmall
        - NERR_DeviceShareConflict
        - NERR_QNotFound

------------------------
2.5  NetShareDel (Admin only) 

Purpose: Delete an existing share from the server's list.

unsigned far pascal
NetShareDel( servername, netname, reserved )
char far *      servername;     asciz remote server name or NULL if local
char far *      netname;        asciz network name of share being deleted
unsigned short  reserved;       MBZ

Returns 0 if successful.  Possible error returns:

        - ERROR_INVALID_PARAMETER
                        Parameter "reserved" not zero.
                        Parameter "servername" poorly formed
                        Parameter "netname" poorly formed

        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - NERR_NetNameNotFound

WARNING: Deleting a share will also delete any existing connections to
the shared resource, and close open files within the connections.

------------------------
2.6  NetShareCheck 

Purpose: Query whether a disk or device is shared

unsigned far pascal
NetShareCheck( servername, devname, type )
char far *           servername;     asciz remote server name or NULL if local
char far *           devname;        asciz device name
unsigned short far * type;           type of share (return)

Given a character device or disk name (X:), this api determines
whether the resource is shared.  A device is considered to be shared
if it is in the routing list of a print or character device queue
that is shared.

If the device is shared, the type argument returns the type of share.
The following types are defined in "shares.h".

    STYPE_DISKTREE      0 = disk
    STYPE_PRINTQ        1 = print queue
    STYPE_DEVICE        2 = character device

Note:  this api may not be used to determine if a print QUEUE is shared,
but only whether a particular device is part of a shares queue.

Returns 0 if device is shared. Possible error returns are:

        - ERROR_INVALID_PARAMETER
        - ERROR_NOT_ENOUGH_MEMORY
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - NERR_DeviceNotShared


3.   SESSIONS 

These calls deal with network sessions between a client workstation and
the server. The session functions do not have a SetInfo or an Add call.
There are two levels of information:

    struct session_info_0 {
        char far *     sesi0_cname;
    };

    struct session_info_1 {
        char far *     sesi1_cname;
        char far *     sesi1_username;
        unsigned short sesi1_num_conns;
        unsigned short sesi1_num_opens;
        unsigned short sesi1_num_users;
        unsigned long  sesi1_time;
        unsigned long  sesi1_idle_time;
        unsigned long  sesi1_user_flags;
    };

cname           Client computername.  Does not have leading "\\".

username        Client username

num_conns       Number of connections on this session

num_opens       Number of currently open files, pipes, devices, etc.
                on this session.

num_users       Number of users on this session.  ALways 0 or 1 in this
                implementation, may change in future releases.

time            Number of seconds since session began.

idle_time       Number of seconds since last activity on the session.

user_flags      Bit definitions are:

                    Bit 0 set => user logged on via the guest account
                    Bit 1 set => user session is using password encryption

                    All others: Reserved

                Bitmasks for these bits are defined in "shares.h", as
                SESS_GUEST and SESS_NOENCRYPTION.  

All of these functions should be used with the include file "shares.h".

------------------------
3.1  NetSessionEnum (Admin only) 

Purpose: Supply information about existing sessions at two levels of detail.

unsigned far pascal
NetSessionEnum( servername, level, buf, buflen, entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested; 0 or 1
char far *          buf;            for returned entries
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct session_info_0".
    Level 1 contains a "struct session_info_1".

Returns 0 if successful. Error return information:

    - ERROR_INVALID_LEVEL       - Level parameter specified is invalid
    - NERR_NetNotStarted        - Network not installed on local machine
    - NERR_ServerNotStarted     - Server is not started
    - ERROR_MORE_DATA             - The buffer supplied was too small to
                                  enumerate all the sessions on the server.

------------------------
3.2  NetSessionGetInfo (Admin only) 

Purpose: Read complete information about a single existing session.

unsigned far pascal
NetSessionGetInfo( servername, clientname, level, buf, buflen, totalavail )
char far *          servername;     asciz remote server name or NULL if local
char far *          clientname;     asciz client name (remote computer name)
                                    of session being queried
short               level;          level of data requested
char far *          buf;            for returned entry
unsigned short      buflen;         size of buffer
unsigned short far *totalavail;     total size needed for buffer

Buffer contents on response:
    Level 0 contains a "struct session_info_0".
    Level 1 contains a "struct session_info_1".

Returns 0 if successful. Error return information:

    - ERROR_INVALID_LEVEL       - Level parameter specified is invalid
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NetNotStarted        - Network not installed on local machine
    - NERR_ServerNotStarted     - Server is not started
    - NERR_ClientNameNotFound   - The client name supplied currently has
                                  no sessions established with the server
    - NERR_BufTooSmall          - The buffer supplied was to small to
                                  return the fixed length structure requested.
    - ERROR_MORE_DATA             - The buffer supplied was too small to return
                                  all the imformation available for this
                                  session.


------------------------
3.3  NetSessionDel (Admin only) 

Purpose: Delete an active session described by clientname.

unsigned far pascal
NetSessionDel( servername, clientname, reserved )
char far *  servername;         asciz remote server name or NULL if local
char far *  clientname;         asciz client name (remote computer name)
                                of session being deleted
short       reserved;           MBZ

This api forces a client session to be logged off.  

WARNING: This will disconnect all of the user's current connections
and close any files currently open within those connections.

Returns 0 if successful. Error return information:

    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
                                    Parameter reserved was not zero.
                                    Parameter clientname poorly formed. 
                                    Parameter servername poorly formed

    - NERR_NetNotStarted        - Network not installed on local machine
    - NERR_ServerNotStarted     - Server is not started
    - NERR_ClientNameNotFound   - The client name supplied currently has
                                  no sessions established with the server

4.   CONNECTIONS 

These api calls deal with connections between a workstation and a
server shared resource.  The connection API has only an Enum
function.  There are two levels of information:

    struct connection_info_0 {
        unsigned short coni0_id;
    };

    struct connection_info_1 {
        unsigned short coni1_id;
        unsigned short coni1_type;
        unsigned short coni1_num_opens;
        unsigned short coni1_num_users;
        unsigned long  coni1_time;
        char far *     coni1_username;
        char far *     coni1_netname;
    };


id              Connection ID, an arbitrary number identifying this
                connection.

type            Type of connection, defined by the type of resource connected
                to.  Can be one of:

                        STYPE_DISKTREE  0       File system share
                        STYPE_PRINTQ    1       Spooled print queue
                        STYPE_DEVICE    2       Character device queue
                        STYPE_IPC       3       Special IPC share

num_opens       Number of open files, pipes, devices, etc. on this 
                connection.

num_users       Number of users on this session.  ALways 0 or 1 in this
                implementation, may change in future releases.

time            Time (in seconds) since connection was established.

username        Username (user security server) or machine name (share
                security server).

netname         Contents depend on the "qualifier" parameter.

                If qualifier is a computername, this field is the netname of
                a shared resource.              

                If qualifier is the netname of a shared resource, then this    
                field is a client computername.

 

This function should be used with the include file "shares.h".

------------------------
4.1  NetConnectionEnum (Admin only) 

Purpose: Supply information about existing connections within a share or
         session at two levels of detail.

unsigned far pascal
NetConnectionEnum( servername, qualifier, level, buf, buflen,
                                                entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL if local
char far *          qualifier;      asciz network name of share
                                    or client name of session (\\computername)
short               level;          level of detail requested; 0 or 1
char far *          buf;            for returned entries
unsigned short      buflen;         size of buffer on call;
                                    # of bytes supplied on return
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct connection_info_0".
    Level 1 contains a "struct connection_info_1".

If the qualifier argument is the computername of a client session, in
the form "\\CLIENT", then this api returns a list of all connections
that belong to that session.  

If the qualifier argument is the netname of a shared resource,
then this api returns a list of all connections to that resource.

Qualifier cannot be a NULL pointer or the null string.


Returns 0 if successful.  Possible error returns:

        - ERROR_INVALID_LEVEL
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - ERROR_MORE_DATA
        - NERR_ClientNameNotFound
        - NERR_NetNameNotFound


5.   FILES 

These calls describe open files ( plus open devices and pipes ) at a
server. The File functions do not support SetInfo or Add.  For
clarity, the function to "delete" an open file instance (i.e, close
the file) is called NetFileClose rather than NetFileDel.  There are
two levels of information:


    struct file_info_0 {
        unsigned short fi0_id;
    };

    struct file_info_1 {
        unsigned short fi1_id;
        unsigned short fi1_permissions;
        unsigned short fi1_num_locks;
        char far *     fi1_pathname;
        char far *     fi1_username;
    };


id              An arbitrary number identifying this occurance of an open
                file.  A single file may be opened several times by
                the same or different users, so this number is used to 
                uniquely identify each instance.  

permissions     The access permissions granted to the user when he
                made the DosOpen call.

num_locks       Number of locks currently existing against this open.

pathname        The local (to the server) full pathname of the
                resource that is opened.

username        Either client's username (user-level security) or 
                client's machine name (share-level security).


All of these functions should be used with the include file "shares.h".

------------------------
5.1  NetFileEnum (Admin only) 

Purpose: Supply information about some or all open resources on a server.

unsigned far pascal
NetFileEnum( servername, basepath, level, buf, buflen,
                                                entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL if local
char far *          basepath;       base path for enumeration (see below)
short               level;          level of detail requested; 0 or 1
char far *          buf;            for returned entries
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

The basepath parameter, if non-NULL, serves as a prefix to qualify
the enumeration.  The entries returned are limited to those whose
names begin with the qualifier string.  For example, a basepath of
"C:\TMP" would enumerate only open files whose pathnames
begin with "C:\TMP", including "C:\TMPFILE" and "C:\TMP\DOCUMENT".

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct file_info_0".
    Level 1 contains a "struct file_info_1".

Returns 0 if successful.  Possible error returns:

        - ERROR_INVALID_PARAMETER
        - ERROR_INVALID_LEVEL
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - ERROR_MORE_DATA

------------------------
5.2  NetFileGetInfo (Admin only) 

Purpose: Read complete information about a single open file instance.

unsigned far pascal
NetFileGetInfo( servername, fileid, level, buf, buflen, totalavail )
char far *          servername;     asciz remote server name or NULL if local
unsigned short      fileid;         file id supplied by EnumFiles
short               level;          level of info requested
char far *          buf;            for returned entry
unsigned short      buflen;         size of buffer
unsigned short far *totalavail;     total size needed for buffer

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct file_info_0".
    Level 1 contains a "struct file_info_1".

Returns 0 if successful.  Possible error returns:

        - ERROR_INVALID_LEVEL
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - ERROR_MORE_DATA
        - NERR_BufTooSmall
        - NERR_FileIdNotFound

------------------------
5.3  NetFileClose (Admin only) 

Purpose: Close a resource that has been opened by a user.

unsigned far pascal
NetFileClose( servername, fileid )
char far *      servername;         asciz remote server name or NULL if local
unsigned short  fileid;             file id supplied by NetFileEnum

Returns 0 if successful.  Possible error returns:

        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - NERR_FileIdNotFound


6.   SERVER 

These calls deal with configuring a server.  There are no Add or Del
calls.  There is an additional call to enumerate the server disks and
a call for executing remote commands at the server.
There are three levels of information:


    struct server_info_0 {
        char            sv0_name[CNLEN + 1];
    };

    struct server_info_1 {
        char            sv1_name[CNLEN + 1];
        unsigned char   sv1_version_major;
        unsigned char   sv1_version_minor;
        unsigned long   sv1_type;
        char far *      sv1_comment;
    };


    struct server_info_2 {
        char            sv2_name[CNLEN + 1];
        unsigned char   sv2_version_major;
        unsigned char   sv2_version_minor;
        unsigned long   sv2_type;
        char far *      sv2_comment;
        unsigned long   sv2_ulist_mtime;
        unsigned long   sv2_glist_mtime;
        unsigned long   sv2_alist_mtime;
        unsigned short  sv2_users;
        unsigned short  sv2_disc;
        char far *      sv2_alerts;
        unsigned short  sv2_security;
        unsigned short  sv2_auditing;
        unsigned short  sv2_numadmin;
        unsigned short  sv2_lanmask;
        unsigned short  sv2_hidden;
        unsigned short  sv2_announce;
        unsigned short  sv2_anndelta;
        char            sv2_guestacct[UNLEN + 1];
        unsigned char   sv2_pad1;
        char far *      sv2_userpath;
        unsigned short  sv2_chdevs;
        unsigned short  sv2_chdevq;
        unsigned short  sv2_chdevjobs;
        unsigned short  sv2_connections;
        unsigned short  sv2_shares;
        unsigned short  sv2_openfiles;
        unsigned short  sv2_sessopens;
        unsigned short  sv2_sessvcs;
        unsigned short  sv2_sessreqs;
        unsigned short  sv2_opensearch;
        unsigned short  sv2_activelocks;
        unsigned short  sv2_numreqbuf;
        unsigned short  sv2_sizreqbuf;
        unsigned short  sv2_numbigbuf;
        unsigned short  sv2_numfiletasks;
        unsigned short  sv2_alertsched;
        unsigned short  sv2_erroralert;
        unsigned short  sv2_logonalert;
        unsigned short  sv2_accessalert;
        unsigned short  sv2_diskalert;
        unsigned short  sv2_netioalert;
        unsigned short  sv2_maxauditsz;
        char far *      sv2_srvheuristics;
    };

name            Server's machine name, e.g. SERVER (without leading \\).

version_major   Major version number of Lan Manager software.  This is
                a 1 (decimal, not ASCII) for this version.

version_minor   Minor version number of Lan Manager software.  This is
                a 0 (decimal, not ASCII) for this version.

type            Type of resources and services on this machine.  Bitmapped,
                currently only two bits define.  Bit masks are defined in
                "server.h"

                   Bit     Mask         Mask symbol

                    0       0x1         SV_TYPE_WORKSTATION
                    1       0x2         SV_TYPE_SERVER

                Note that a standard Lan Manager server will have both bits
                set, since every server is also a workstation.

comment         Server comment or remark.  Currently limited to a length
                of MAXCOMMENTSZ, this should briefly identify or describe
                the server, e.g. "Print Server for Building Seven".

ulist_mtime     Last modification time (see "timestamps") of the
                user list (user-security servers only ).

glist_mtime     Last modification time (see "timestamps") of the
                group list (user-security servers only ).

alist_mtime     Last modification time (see "timestamps") of the
                access control list (user-security servers only ).

users           Maximum number of simultaneous sessions allowed.

disc            Auto-disconnect timeout (in seconds).  Sessions which
                are idle for longer that this time will be disconnected.

alerts              /* alert names (semicolon separated)    */

security        Security mode of this server.  May be one of:

                  SV_SHARESECURITY      0       Share-level security
                  SV_USERSECURITY       1       User-level security

auditing        0 = no auditing; 1 = auditing.  If auditing in ON, audit
                records will be written for various events.  See the
                NetAudit API and NetAccess API.

numadmin        Maximum number of administrators allowed simultaneously.

lanmask         Bit mask representing the srv'd nets.

hidden          May be one of:

                  SV_VISIBILE   0       Server visible via NetServerEnum.
                  SV_HIDDEN     1       Server not visible via NetServerEnum

announce        Announce rate (for a visible server, see "hidden" field
                above), in seconds.  The server will announce it's presence
                on the network, even "announce" seconds.  

anndelta        Announce rate randomization delta in milliseconds.

guestacct       Name of the guest logon account.

userpath        ASCIZ path, root of the user directories.

chdevs          Maximum number of shared character devices.

chdevq          Maximum number of character device queues.

chdevjobs       Maximum number of character device jobs.

connections     Maximum number of connections.

shares          Maximum number of shares.

openfiles       Maximum number of open files (total).

sessopens       Maximum number of open files (per session).

sessvcs         Maximum number of virtual circuits per client.

sessreqs        Maximum number of open files simultaneous reqs.
                from a client.  This basically the number of requests
                that the server will allow from a client on one VC at
                one time.

opensearch      Maximum number of open searches.

activelocks     Maximum number of active file locks.

numreqbuf       Number of server (standard) buffers.

sizreqbuf       Size of server (standard) buffers (bytes).

numbigbuf       Number of big (64K) buffers,

numfiletasks    Number of file worker processes.  To optimize performance
                the server can have mulitple fileworker processes so
                that multiple requests can be made to the OS at the
                same time.

alertsched      Alert counting interval (minutes).  This is the time sample
                interval for alerting the administrators of problems.

erroralert      Error log alerting threshold.  This is the number of times
                that the error log has to be written to in alertsched
                period of time that causes an alert to notify the
                administrator that a very high number of errors are occurring.

logonalert      Logon violation alerting threshold. This is the number of
                bad passwords supplied in the time period of alertsched
                that will cause the administrators to be notified that
                there are too many bad passwords being supplied.

accessalert     Access violation alerting threshold.  If this number of
                access violations occur in alertsced length of time,
                the administartors will be sent an alert that large
                numbers of access violations are occurring.

diskalert       Low disk space alert threshold (KB).  This is the amount
                of space left on each disk on the server, at which the
                administrator wishes to be sent an alert that disk space
                is running low.

netioalert      Net I/O error ratio alert threshold in tenths of a percent.
                If the number of network I/O errors exceed this percent
                in the alertsched time period, the administrators are
                notified of this through an alert.

maxauditsz      Maximum audit file size in kilobytes.  The audit file will
                not grow beyond this size (within a margin of error of
                on audit record).  

srvheuristics   Performance related server switches.  For a detailed
                explanation of these fields see the Administrators guide.


All of these functions should be used with the include file "server.h".

------------------------
6.1  NetServerEnum 

Purpose: NetServerEnum enumerates the set of all machine names visible on the
         network.

unsigned far pascal
NetServerEnum(servername, level, buf, buflen, entriesread, totalentries)
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of information to be returned
char far *          buf;            buffer to contain returned info
unsigned short      buflen;         number of bytes available in buffer
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on response (format for a single entry):

    Level 0 contains a "struct server_info_0".
    Level 1 contains a "struct server_info_1".

    NOTE:  Level 2 is not valid for Enum


Returns 0 if successful. Error return information:

    - ERROR_INVALID_LEVEL       - Level parameter specified is invalid
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NetNotStarted        - Network not installed on local machine
    - NERR_BrowserNotStarted    - The information required for NetServerEnum
                                  is not available.  This will occur if
                                  the workstation is started with the
                                  option "mailslots = no".
    - ERROR_MORE_DATA           - The buffer supplied was too small to return
                                  complete information about all the known
                                  servers.


------------------------
6.2  NetServerGetInfo (Admin only) 

Purpose: Read the current configuration parameters of the server.

unsigned far pascal
NetServerGetInfo( servername, level, buf, buflen, totalavail )
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of information to be returned
char far *          buf;            for returned data
unsigned short      buflen;         size of buffer
unsigned short far *totalavail;     total size needed for buffer

Buffer contents on response (format for a single entry):

    Level 0 contains a "struct server_info_0".
    Level 1 contains a "struct server_info_1".
    Level 2 contains a "struct server_info_2".

Returns 0 if successful. Error return information:

    - ERROR_INVALID_LEVEL       - Level parameter specified is invalid
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NetNotStarted        - Network not installed on local machine
    - NERR_ServerNotStarted     - Server is not started
    - NERR_BufTooSmall          - The buffer supplied was to small to
                                  return the fixed length structure requested.
    - ERROR_MORE_DATA             - The buffer supplied was too small to return
                                  all the information available for this
                                  server.


------------------------
6.3  NetServerSetInfo (Admin only) 

Purpose: Write the settable configuration parameters of the server.

unsigned far pascal
NetServerSetInfo( servername, level, buf, buflen, parmnum )
char far *      servername;     asciz remote server name or NULL if local
short           level;          level of information provided
char far *      buf;            contents described below
unsigned short  buflen;         size of buffer
short           parmnum;        which parameter to set

Buffer contents on call if parmnum is zero:

    Level 0 contains a "struct server_info_0".
    Level 1 contains a "struct server_info_1".
    Level 2 contains a "struct server_info_2".

Settable fields are:

        comment
        disc
        alerts
        hidden
        announce                
        anndelta                
        alertsched
        erroralert
        logonalert
        accessalert
        diskalert
        netioalert
        maxauditsz

Returns 0 if successful.  Possible error returns:
        - ERROR_INVALID_LEVEL
        - NERR_NetNotStarted
        - NERR_ServerNotStarted
        - NERR_NetNameNotFound
        - NERR_BufTooSmall
        - NERR_RemoteErr
        - ERROR_MORE_DATA
        - NERR_NoAdminRights
        - NERR_NoRoom
        - ERROR_INVALID_PARAMETER       One of:
                                          Parmnum is invalid
                                        

------------------------
6.4  NetServerDiskEnum (Admin Only) 

Purpose:  Supply information about server's disk drives.

unsigned far pascal
NetServerDiskEnum (servername, level, buf, buflen,
                    entriesread, totalentries)
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail; MBZ
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available


Only level 0 is curently supported.

Buffer content on return is a list of drive names on the server, as
consecutive three character strings, each string containing a drive
letter, a colon and a string terminator.


Returns 0 if successful. Error return information:

    - ERROR_INVALID_LEVEL       - Level parameter specified is invalid
    - NERR_NetNotStarted        - Network not installed on local machine
    - ERROR_MORE_DATA             - The buffer supplied was too small to
                                  enumerate all the drives on the server.


NOTE. This API may be used locally without a server or workstation installed.
------------------------
6.5  NetServerAdminCommand (Admin only) 

Purpose: Execute a command at a server and returns command's output.

unsigned far pascal
NetServerAdminCommand(servername, command, result, buf, buflen,
                      bytesread, totalavail)

char far *              servername;     asciz remote server name, NULL if local
char far *              command;        command to be executed
short far *             result;         place for completion code to be returned
char far *              buf;            buffer for stdout to be returned
unsigned short          buflen;         size of buffer
unsigned short far *    bytesread;      length of stdout data returned in buf
unsigned short far *    totalavail;     total stdout available from execution

Returns 0 if successful. Error return information:

    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NetNotStarted        - Network not installed on local machine
    - ERROR_MORE_DATA             - The supplied buffer was to small to contain
                                  the output resulting from the execution
                                  of the requested command.
    - NERR_TooMuchData          - The output resulting from the execution of
                                  the requested command was > 64K which is the
                                  maximum data size which may be returned with
                                  this API. The supplied buffer will contain
                                  the first buflen bytes of the output data.
    - NERR_ExecFailure          - An error occured executing the requested
                                  command.
    - NERR_TmpFile              - The server was unable to complete the
                                  requested command due to an error while
                                  using the temporary file required to
                                  return the STDOUT and STDERR from the
                                  command.



7.   AUDITING 

These calls manipulate the audit trail.  Calls are provided for
writing an audit record (local only), opening the audit file for
reading records, and clearing/saving the audit log.

NOTE:  No API call exists to read the audit trail file.  To read the
file, applications should use the NetAuditOpen API to obtain a DOS
file handle to the audit log, and use normal OS/2 calls DosRead,
DosChgFilePtr, etc. to read the file as desired.  The data structure
is set up to allow the file to be scanned forward or backward.  When
done with the file, the application should call DosClose with the
handle.   The audit trail will be made up of variable length
entries.  Each entry will contain the time the entry was made and an
entry type.  The format of the remainder of the entry will be
specific to the entry type.

Each entry/record in the file is composed of:

        struct audit_entry {
            unsigned short      ae_len;
            unsigned short      ae_reserved;
  +-------  unsigned short      ae_data_offset;
  |         unsigned long       ae_time;
  |         unsigned short      ae_type;
  |     };
  |
  |             followed (not necessarily immediately) by:
  |
  +-->  char                ae_data[..];

        unsigned short      ae_len2;

ae_len          Total length of the record, in bytes.  This includes
                the whole record, including this field.  
                Since every audit record consists of a standard audit_entry
                structure, optional data, and a trailing length, the minimum
                length of an audit record is:

                    sizeof(struct audit_entry) + sizeof(unsigned short)

                        <the fixed structure>       <ae_len2>

ae_reserved     This field is reserved and it's value is undefined.

ae_data_offset  This is an offset, from the beginning of the fixed
                record, of the optional data.  This data gives
                infomation specific to the type of audit record.
                See explanation of ae_data, below.

ae_time         Timestamp (see chapter 1) of the event.

ae_type         Type of audit record.  Currently defined types are listed
                below.  More detail is vailable further below, in the
                explanation of the ae_data for each defined type.

                  AE_SRVSTATUS          Server status change            0
                  AE_SESSLOGON          Session logon                   1
                  AE_SESSLOGOFF         Session logoff                  2
                  AE_SESSPWERR          Password error                  3
                  AE_CONNSTART          Connection start                4
                  AE_CONNSTOP           Connection stop                 5
                  AE_CONNREJ            Password rejection              6
                  AE_RESACCESS          Access granted                  7
                  AE_RESACCESSREJ       Access rejected                 8
                  AE_CLOSEFILE          Close of file/device/pipe       9


                Entry type values of 0 - 0x7FFF are reserved for 
                Microsoft and values 0x8000 - 0xFFFF are available 
                to OEM's.  

ae_data         This data area's contents are specific to each type
                of audit record, and are defined below.  Although in
                the current implementation this data immediately
                follows the standard structure, DO NOT assume this.
                Use the field ae_data_offset to determine the start
                of the data.

                Likewise, use the following expression to determine
                the size of the data area:

                   size = ae_len - (ae_data_offset + sizeof(unsigned short));

                This takes into account where the data starts, and the
                prescence of the ae_len2 field at the end.

ae_len2         This contains exactly the same value as ae_len.  It
                appears so that the file can be scanned backwards.


Note that, due to the "variable record" portion of the entry, only
the fixed header portion is defined in the C structure audit_entry.
It is possible for the ae_data field to have a size of zero bytes,
although none of the Microsoft-defined records are so designed.

The following contents of ae_data are defined by Microsoft for this
release.  The items noted as 'offsets' are offsets withing the
buffer, which point to ASCIZ strings.  The 'offset' values are all
'unsigned short'.  To make a pointer to the text string, add the
offset value to the address of the start of ae_data.

In the following example, assume that "ap" points to a buffer
containing a complete audit record.  Further assume that we know,
from the "type" field, that this is an AE_CONNSTOP record.  We want
"computer_name" to point to the ASCIZ string which is the computer
name of the client whose connection was stopped.

        struct audit_entry * ap;
        struct ae_connstop * acp;
        char * computer_name;

        acp = (struct ae_connstop *) ((char *) ap + ap->ae_data_offset);

        computer_name = (char *) acp + acp->ae_cp_compname;

Note the use of casts.  This is key for C programmers, especially the
user of (char *) on the pointers before performing the addition.


Type 0: AE_SRVSTATUS, Server status record

    struct ae_srvstatus {
        unsigned short    ae_ss_status;
    };

    ss_status           Server status (new state), values are:

                          0 - Server started    AE_SRVSTART
                          1 - Server paused     AE_SRVPAUSED
                          2 - Server continued  AE_SRVCONT
                          3 - Server stopped    AE_SRVSTOP


Type 1: AE_SESSLOGON, Session logon record

    struct ae_sesslogon {
        unsigned short    ae_so_compname;       *OFFSET*
        unsigned short    ae_so_username;       *OFFSET*
        unsigned short    ae_so_privilege;      
    };

    so_compname         (offset to) Computername of client, ASCIZ string

    so_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero if it
                           is the same as the computername.

    so_privilege        Privilege of the user logging in, one of:

                           AE_GUEST     0
                           AE_USER      1
                           AE_ADMIN     2

                        See NetUser APIs for more explanation of these
                        values.


Type 2: AE_SESSLOGOFF, Session logoff record

    struct ae_sesslogoff {
        unsigned short    ae_sf_compname;       *OFFSET*
        unsigned short    ae_sf_username;       *OFFSET*
        unsigned short    ae_sf_reason;
    };

    sf_compname         (offset to) Computername of client, ASCIZ string

    sf_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero if it
                           is the same as the computername.

    sf_reason           Reason for logoff, one of:

                            AE_NORMAL    0   Normal logoff by user
                            AE_ERROR     1   Disconnect due to error
                            AE_AUTODIS   2   Auto-disconnect (idle timeout)
                            AE_ADMINDIS  3   Administrator disconnected user

Type 3: AE_SESSPWERR, Session password violation record

    struct ae_sesspwerr {
        unsigned short    ae_sp_compname;       *OFFSET*
        unsigned short    ae_sp_username;       *OFFSET*
    };

    sp_compname         (offset to) Computername of client, ASCIZ string

    sp_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero if it
                           is the same as the computername.


Type 4: AE_CONNSTART, Connection start record

    struct ae_connstart {
        unsigned short    ae_ct_compname;       *OFFSET*
        unsigned short    ae_ct_username;       *OFFSET*
        unsigned short    ae_ct_netname;        *OFFSET*
        unsigned short    ae_ct_connid; 
    };

    ct_compname         (offset to) Computername of client, ASCIZ string

    ct_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero  if it
                           is the same as the computername.

    ct_netname          (offset to) Netname of resource connected to,
                        ASCIZ string.

    ct_connid           ID of this connection, unique to this server.


Type 5: AE_CONNSTOP, Connection end record

    struct ae_connstop {
        unsigned short    ae_cp_compname;       *OFFSET*
        unsigned short    ae_cp_username;       *OFFSET*
        unsigned short    ae_cp_netname;        *OFFSET*
        unsigned short    ae_cp_connid;
        unsigned short    ae_cp_reason;
    };

    cp_compname         (offset to) Computername of client, ASCIZ string

    cp_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero  if it
                           is the same as the computername.

    cp_netname          (offset to) Netname of resource, ASCIZ string.

    cp_connid           ID of this connection, unique to this server.

    cp_reason           Reason for disconnection, one of:

                            AE_NORMAL    0   Normal client disconnect
                            AE_SESSDIS   1   Session disconnected
                            AE_UNSHARE   2   Connection ended because 
                                              server resource was unshared
                                              (see NetShareDel API)


Type 6: AE_CONNREJ, Connection reject record

    struct ae_connrej {
        unsigned short    ae_cr_compname;       *OFFSET*
        unsigned short    ae_cr_username;       *OFFSET*
        unsigned short    ae_cr_netname;        *OFFSET*
        unsigned short    ae_cr_reason;
    };

    cr_compname         (offset to) Computername of client, ASCIZ string

    cr_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero  if it
                           is the same as the computername.

    cr_netname          (offset to) Netname of resource, ASCIZ string.

    cr_reason           Reason for rejection, one of:

                         AE_USERLIMIT     0 - User limit exceeded.
                         AE_BADPW         1 - Bad password submitted.
                         AE_ADMINPRIVREQD 2 - Admin privileges required to
                                                connect to this shared
                                                resource.
                         AE_NOACCESSPERM  3 - No access permissions to 
                                                this shared resource.
                        

Type 7: AE_RESACCESS, Resource access record

    struct ae_resaccess {
        unsigned short    ae_ra_compname;       *OFFSET*
        unsigned short    ae_ra_username;       *OFFSET*
        unsigned short    ae_ra_resname;        *OFFSET*
        unsigned short    ae_ra_operation;
        unsigned short    ae_ra_returncode;
        unsigned short    ae_ra_restype;
        unsigned short    ae_ra_fileid;
    };

    ra_compname         (offset to) Computername of client, ASCIZ string

    ra_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero if it
                           is the same as the computername.

    ra_resname          (offset to) Resource name, ASCIZ string.

    ra_operation        Operation or type of access performed, a bit-mapped
                        field using the following bit defintions.  See
                        NetAccess API documentation or "access.h" for
                        values and meaning.

                            ACCESS_READ   
                            ACCESS_WRITE  
                            ACCESS_CREATE 
                            ACCESS_EXEC   
                            ACCESS_DELETE 
                            ACCESS_ATRIB  
                            ACCESS_PERM   

    ra_returncode       Return code from the operation, which may have
                        been DosOpen, DosDelete, NetPrintJobAdd, etc.
                        This is normally 0 if the operation succeeded.

    ra_restype          SMB request function code       

    ra_fileid           A unique access ID (ie,FID, file handle ).  
                        This is 0 for operations (like delete) that generate 
                        no FID. The unique access ID lets this record 
                        be correlated
                        with the matching access end record (see below).



    NOTE:  A DosMove operation shows up as two audit records, one to
           delete the original resource name, and one to create the
           new resource name.

    Note that a type 7 record is generated whether or not the attempted
    operation succeeds.  If the result code indicates success and the
    access ID is nonzero, a matching type 9 record will be generated
    when the resource is closed.


Type 8: AE_RESACCESSREJ, Access denied record

    struct ae_resaccessrej {
        unsigned short    ae_rr_compname;       *OFFSET*
        unsigned short    ae_rr_username;       *OFFSET*
        unsigned short    ae_rr_resname;        *OFFSET*
        unsigned short    ae_rr_operation;
    };

    rr_compname         (offset to) Computername of client, ASCIZ string

    rr_username         (offset to) Username of client, ASCIZ string.
                           This value may be zero if it
                           is the same as the computername.

    rr_resname          (offset to) Resource name, ASCIZ string.

    rr_operation        Operation or type of access attempted, a bit-mapped
                        field using the following bit defintions.  See
                        NetAccess API documentation or "access.h" for
                        values and meaning.

                            ACCESS_READ   
                            ACCESS_WRITE  
                            ACCESS_CREATE 
                            ACCESS_EXEC   
                            ACCESS_DELETE 
                            ACCESS_ATRIB  
                            ACCESS_PERM   


Type 9:  AE_CLOSEFILE, Resource access end record

    struct ae_closefile {
        unsigned short    ae_cf_compname;       *OFFSET*
        unsigned short    ae_cf_username;       *OFFSET*
        unsigned short    ae_cf_resname;        *OFFSET*
        unsigned short    ae_cf_fileid;
        unsigned long     ae_cf_duration;
        unsigned short    ae_cf_reason;
    };

    cf_compname         (offset to) Computername of client, ASCIZ string

    cf_username         (offset to) Username of client, ASCIZ string.
                           The value may be zero if it
                           is the same as the computername.

    cf_resname          (offset to) Resource name, ASCIZ string.

    cf_fileid           A unique access ID (ie, FID (file handle)).
                        This is 0 for operations (like delete) that generate 
                        no FID. The unique access ID lets this record 
                        be correlated
                        with the matching access end record (see below).

    cf_duration         Duration of resource access, in seconds.

    cf_reason           Reason for ending access, one of:

                            AE_NORMAL       0 - Normal client close
                            AE_SES_CLOSE    1 - Session disconnected
                            AE_ADMIN_CLOSE  2 - Close was forced by 
                                                administrator (see
                                                NetFileClose API).


NOTE:  The maximum size of the audit trail is set by the workstation
at startup from the command line or lanman.ini, and can be set via
the API NetWkstaSetInfo.  NERR_LogOverflow is returned when the audit
trail is 100% full.  The NetAuditWrite API will issue an admin alert
(via NetAlertRaise) when the audit trail gets to the 80% and 100%
full marks, respectively.


------------------------
7.1  NetAuditOpen (Admin only) 

Purpose: Return a DOS file handle for audit trail at a server.

unsigned far pascal
NetAuditOpen( servername, handle, reserved )
char far *      servername;     /* asciz remote server name or NULL if local */
unsigned far *  handle;         /* place to return file handle */
char far *      reserved;       /* must be NULL */

The audit file is opened for read access.  All of the handle oriented DOS
file system functions for accessing files in read-only mode can be used.

Returns 0 if successful.  Possible error returns:
    - ERROR_BAD_NETPATH         (remote server not found)
    - ERROR_NET_WRITE_FAULT     (remote server communication failure)
    - ERROR_ACCESS_DENIED       (Access to file denied, may be due to:
                                        remote file system error
                                        ADMIN$ not shared on server
                                        ADMIN$ share not accessable due
                                          to number of users attached)
                                        no admin rights on server
                                        remote file system error)
    - NERR_NetNotStarted        (Redirector not installed)
    - NERR_WkstaNotStarted      (Workstation software not installed)
    - OS/2 file system errors   (error from DosOpen of the file)

------------------------
7.2  NetAuditWrite (Admin only) (Local only) 

Purpose: Create an entry in the audit trail file.

unsigned far pascal
NetAuditWrite( type, buf, buflen, reserved1, reserved2)
unsigned short  type;           /* entry type */
char far *      buf;            /* buffer containing ae_data ONLY! */
unsigned short  buflen;         /* size of buffer */
char far *      reserved1;      /* must be NULL */
char far *      reserved2;      /* must be NULL *

This call adds an entry to the audit trail.  Note that the supplied
buffer must contain only the ae_data part of the record.  The call
automatically supplies the other values--ae_len, ae_len2, ae_time,
and ae_data_offset.

Returns 0 if successful.  Possible error returns:
    - NERR_NetNotStarted        (Redirector not installed)
    - NERR_WkstaNotStarted      (Workstation software not installed)
    - NERR_LogOverflow          (Log file has grown too large)
    - ERROR_NOT_ENOUGH_MEMORY                (Server ran out of memory queueing request)
    - NERR_OS2FileError         (Seek to end-of-file failed)
    - OS/2 file system errors   (error from DosOpen of logfile)

------------------------
7.3  NetAuditClear (Admin only) 

Purpose: Clear the audit log file.

unsigned far pascal
NetAuditClear( servername, backup_file, reserved )
char far *      servername;     /* asciz remote server name or NULL if local */
char far *      backup_file;    /* asciz file name or NULL */
char far *      reserved;       /* must be NULL */

This call clears the audit trail (sets it to zero length) and
optionally saves the original contents to another file.  The clearing
and saving of the file is done atomically, so that audit records
cannot be lost in between the saving and clearing operations.

If backup_file is not NULL, it must specify a valid pathname to which
the caller has write privileges.  If the path is relative, it will be
taken as RELATIVE TO THE LANMAN LOG DIRECTORY, usually
C:\LANMAN\LOGS.  The path MUST BE ACCESSABLE to the DosMove OS/2 API,
which means it must reside on the same drive as the Lan Manager tree.

Note that OS/2 errors which are returned may be somewhat ambiguous,
since the errors may come from attempts to access/delete the log file
or to create the new (backup) file.  Intelligent error recovery will
require examining both files' current states.

Returns 0 if successful.  Possible error returns:
    - NERR_NetNotStarted        (Redirector not installed)
    - NERR_WkstaNotStarted      (Workstation software not installed)
    - ERROR_NOT_ENOUGH_MEMORY                (Server ran out of memory queueing request)
    - OS/2 file system errors   (error from Dos{Move,Delete,Open} of logfile)


8.   ERROR LOGGING 

These calls allow opening, writing to, and clearing an error log. 
Each error log entry is composed of a fixed portion, possibly
followed by zero or more ASCIZ strings and block of raw data.  The
ASCIZ strings are merge strings for the error message indicated by
the error code  (el_error).  The remaining data may be useful for
administrators of OEM service technicians.

The format of the error log is:

    struct error_log {
        unsigned short  el_len;
        unsigned short  el_reserved;
        unsigned long   el_time;
        unsigned short  el_error;
        char            el_name[SNLEN+1];
 +----  unsigned short  el_data_offset;
 |      unsigned short  el_nstrings;
 |  };
 |
 |              followed by:
 |
 |     char                el_text[];
 +-->  char                el_data[];
       unsigned short      el_len2;  


In the file, the fixed structure is followed by the variable-length
text area (ASCIZ strings in el_text) and variable length data area
(el_data), both optional.  These are followed by the length (el_len2,
an unsigned short, same value as el_len).  These "fields" are not
defined in the header files since C offers no syntax for defining
variable-length fields.

The data in the error log is used as follows:

el_len          The size of the entry record, including all the
                fixed portion (including itself), the strings, the data, and
                the trailing length.  It is used in reading the records,
                determining size of el_data, etc.  

el_time         The timestamp of the error log entry, 
                set by the NetErrorLogWrite API.

el_error        The error code.  This code can be used to obtain
                a text message from the NET.ERR file.  The fullscreen 
                and command-line
                interfaces use this when displaying the error log.

el_name         An asciz name identifying the service that
                logged the error.

el_data_offset  This is an offset, from the beginning of the fixed
                record, of el_data.  See explanation of el_data, below.

el_nstrings     The number of ASCIZ strings in the area el_text.

el_text         Zero or more ASCIZ strings, consecutively appearing 
                immediately after the end of the fixed structure.
                These strings are inserted into the text of the 
                error messages
                when the user interface obtains the message from the file.

el_data         Zero or more bytes of data associated with the error.
                This data is displayed in 'dump' form by the user interfaces.

                The size of el_data may be calculated by:

                     el_len - (el_data_offset + sizeof(el_len2))

el_len2         This contains exactly the same value as ae_len.  It
                appears so that the file can be scanned backwards.


NOTE:  No API call exists to read the error log file.  To read the
file, applications should use the NetErrorLogOpen call to obtain a
DOS file handle to the log, and use normal OS/2 calls DosRead,
DosChgFilePtr, etc.  to read the log.  When done with the file, the
application should issue a DosClose against the handle.

NOTE:  The maximum size of the error log is set by the workstation at
startup from the command line or lanman.ini, and can be changed via the
API NetWkstaSetInfo.  NERR_LogOverflow is returned when the error log
is 100% full.

NOTE:  The NetErrorLogWrite API will issue an admin alert (via
NetAlertRaise) for each error log entry written.  An additional alert
of the admin class will be issued at the 80% and 100% full marks.

All of these functions should be used with the include file "errlog.h".

------------------------
8.1  NetErrorLogOpen (Admin only) 

Purpose: Return a DOS file handle of the open error log.

unsigned far pascal
NetErrorLogOpen( servername, handle, reserved )
char far     *  servername;     /* asciz remote server name, NULL if local */
unsigned far *  handle;         /* place to return file handle */
char far *      reserved;       /* must be NULL */

The error file is opened for read access. All of the handle oriented DOS
file system functions applicable to read-only files can be used.

Returns 0 if successful.  Possible error returns:

    - ERROR_INVALID_PARAMETER
    - ERROR_ACCESS_DENIED       (Access to file denied, may be due to:
                                        remote file system error
                                        ADMIN$ not shared on server
                                        ADMIN$ share not accessable due
                                          to number of users attached)
                                        no admin rights on server
                                        remote file system error)
    - NERR_NetNotStarted        (NetWksta not installed)
    - NERR_WkstaNotStarted      (Wkstation software not running)
    - OS/2 file system errors

------------------------
8.2  NetErrorLogWrite (Admin only) (Local only) 

Purpose: Make an error log entry.

unsigned far pascal
NetErrorLogWrite( reserved1, code, compname, buf, buflen, insbuf, nstrings,
                 reserved2)
char far *      reserved1;      /* must be NULL                */
unsigned short  code;           /* error code number           */
char far *      compname;       /* asciz component name        */
char far *      buf;            /* error data                  */
unsigned short  buflen;         /* size of buffer              */
char far *      insbuf;         /* buffer of ASCIZ strings     */
unsigned short  nstrings;       /* number of strings in insbuf */
char far *      reserved2;      /* must be NULL                */

Returns 0 if successful.  Possible error returns:

    - NERR_LogOverflow             (errlog full, unable to write entry)
    - ERROR_INVALID_PARAMETER
    - NERR_NetNotStarted
    - NERR_WkstaNotStarted
    - OS/2 file system errors

------------------------
8.3  NetErrorLogClear (Admin only) 

Purpose: Clear the error log.

unsigned far pascal
NetErrorLogClear( servername, backup_file, reserved )
char far *    servername;       asciz remote server name or NULL if local
char far *    backup_file;      asciz file name or NULL
char far *    reserved;         must be NULL

Deletes the error log file.  Will fail if the file is currently opened
by anyone, or for other reason a call to DosDelete might fail.

If backup_file is not NULL, it must specify a valid pathname to which
the caller has write privileges.  If the path is relative, it will be
taken as RELATIVE TO THE LANMAN LOG DIRECTORY, usually
C:\LANMAN\LOGS.  The path MUST BE ACCESSABLE by the DosMove OS/2 API
(used by NetErrorLogClear), which means it must reside on the same
drive as the Lan Manager tree.

Note that OS/2 errors which are returned may be somewhat ambiguous,
since the errors may come from atempts to access/delete the log file
or to create the new (backup) file.  Intelligent error recovery
will require examining both files' current states.

Returns 0 if successful.  Possible error returns:
    - ERROR_INVALID_PARAMETER
    - ERROR_BAD_NET_NAME        (the server has not shared ADMIN$)
    - NERR_NetNotStarted
    - NERR_WkstaNotStarted
    - OS/2 file system errors   (may be on log file *or* backup file if
                                 specified)


9.   CHARACTER DEVICES 

These calls deal with shared character devices and their associated queues.

The NetCharDev calls have two levels of detail:

    struct chardev_info_0 {
        char           ch0_dev[DEVLEN+1];
    };

    struct chardev_info_1 {
        char           ch1_dev[DEVLEN+1];
        char           ch1_pad1;
        unsigned short ch1_status;
        char           ch1_username[UNLEN+1];
        char           ch1_pad2;
        unsigned long  ch1_time;
                                          /* current user                       */
    };

    
dev             Device name, ASCIZ string.

status          Device status, bitmapped as:

                   Bit
                    0           <reserved>
                    1           On = Opened, Off = Idle
                    2           On = Error,  Off = No error
                  3-15          <reserved>

username        Name of device's current user.  Null string if none.

time            Count in seconds of how long device has been open by
                current user.


The NetCharDevQ calls also have two levels of detail:

    struct chardevQ_info_0 {
        char           cq0_dev[NNLEN+1];
    };
    
    struct chardevQ_info_1 {
        char           cq1_dev[NNLEN+1];
        char           cq1_pad;
        unsigned short cq1_priority;
        char far *     cq1_devs;
        unsigned short cq1_numusers;
        unsigned short cq1_numahead;
    };


dev             Queue name

priority        Queue priority (1 - 9)  (1 is the highest priority and
                9 is the lowest)  This is the same as is used for spool
                queues.  A request that is on a queue of higher priority
                that another request is guaranteed to open the device
                before the request on a lower queue.

devs            Names of devices assigned to queue, separated by
                spaces, ASCIZ string.  For example, "COM1 COM3".

numusers        Total number of users waiting in queue.

numahead        Number of users in queue ahead of the specified
                user.  The user can be specified as a parameter to
                NetCharDevQGetInfo.  This is 0xffff if the
                user is not in the queue or no user is specified.


All of these functions should be used with the include file "chardev.h".

A character device is any device which is associated with character
device queue.  A character device queue is a set of devices which are
intended to be accessed in a direct, "char-by-char" manner by an
application.  This is in contrast to spooled devices, which are
accessed in a "job-by-job" manner.

An example of character device access is a modem, or bank of modems.  
Normally the application must interact directly with such a device,
or the device drvier (which is "the same thing" from an application
standpoint).  

Devices shared in a chardev queue may appear in more that one queue.
However, a device may not be simultaneously shared in both spooled
(PrintQ) and directy (CharDevQ) modes.

Character device queues exist ONLY WHEN SHARED, as opposed to print
queues, which may exist even when not shared.  SO, character device
queues are created using the "NetShareAdd" command.  Unsharing a
chardev queue (NetShareDel) will also delete the queue.

When a remote application issues an open on a chardev queue, the
opening thread may be suspended if all the devices in that queue's
pool are in use.  When a device becomes available, the open will
complete.  An application can determine where is it on the waiting
list by using NetCharDevQGetInfo.  This assumes the application
uses one thread to do the Open, while another thread is available to
call the API and possibly keep the user informed of the status of
the queue.  

The DosOpen call may time out.  This timeout is controled by the client
and is sent over in the open request.  On the client machine, the timeout
is set by the CHARWAIT parameter in the LANMAN.INI file or as an override
on the command line.




------------------------
9.1  NetCharDevEnum 

Purpose: Supply information about shared character devices at two
         levels of detail.

unsigned far pascal
NetCharDevEnum( servername, level, buf, buflen, entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested; 0 or 1
char far *          buf;            for returned entries
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct chardev_info_0".
    Level 1 contains a "struct chardev_info_1".

Returns 0 if successful.  Possible error returns:
    - ERROR_INVALID_LEVEL --  The level parameter passed in is incorrect.
    - NERR_ServerNotStarted -- The server is not currently running.
    - NERR_BufTooSmall -- see Enum documentation.
    - ERROR_MORE_DATA -- See Enum documentation.

------------------------
9.2  NetCharDevGetInfo 

Purpose: Read complete information about a single shared device.

unsigned far pascal
NetCharDevGetInfo( servername, devname, level, buf, buflen, totalavail )
char far *          servername;     asciz remote server name or NULL if local
char far *          devname;        asciz name of device being queried
short               level;          level of detail requested; 0 or 1
char far *          buf;            for returned entry
unsigned short      buflen;         size of buffer
unsigned short far *totalavail;     total size needed for buffer

Buffer contents on response:
    Level 0 contains a "struct chardev_info_0".
    Level 1 contains a "struct chardev_info_1".

Returns 0 if successful.  Possible error returns:
    - ERROR_INVALID_LEVEL --  The level parameter passed in is incorrect.
    - NERR_ServerNotStarted -- The server is not currently running.
    - NERR_BufTooSmall -- see Enum documentation.
    - NERR_DevNotFound -- The devname parameter does not refer to a shared
                              comm device.

------------------------
9.3  NetCharDevControl (Admin only) 

Purpose: Change the state of the given character device.

unsigned far pascal
NetCharDevControl(servername, devname, opcode)
char far *  servername;         asciz remote server name or NULL if local
char far *  devname;            asciz device name
short       opcode;             0 close device (disconnect current client)
                                1 - 127 reserved
                                128 and up, OEM defined

Returns: 0 if successful. Possible errors:
    - NERR_ServerNotStarted -- server shared memory is unavailable.
    - NERR_DevNotFound -- Device is not shared as a comm device.
    - NERR_DevInvalidOpCode -- The operation requested was invalid.
    - ERROR_SEM_TIMEOUT -- the comm device resources could not be accessed
      because they were in use by some other process.

------------------------
9.4  NetCharDevQEnum 

Purpose: Supply information about character device queues at two
         levels of detail.

unsigned far pascal
NetCharDevQEnum( servername, username, level, buf, buflen, entriesread,
                totalentries )
char far *          servername;     asciz remote server name or NULL if local
char far *          username;       asciz user name
short               level;          level of detail requested; 0 or 1
char far *          buf;            for returned entries
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Note:  The username is used in calculating the value of cq1_numahead in
       the chardevQ_info_1 structure.

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct chardevQ_info_0".
    Level 1 contains a "struct chardevQ_info_1".

Returns 0 if successful.  Possible error returns:
    - ERROR_INVALID_LEVEL --  The level parameter passed in is incorrect.
    - NERR_ServerNotStarted -- The server is not currently running.
    - NERR_BufTooSmall -- see Enum documentation.
    - ERROR_MORE_DATA -- See Enum documentation.

------------------------
9.5  NetCharDevQGetInfo 

Purpose: Read complete information about a single character device queue.

unsigned far pascal
NetCharDevQGetInfo( servername, queuename, username, level, buf,
                    buflen, totalavail )
char far *          servername;     asciz remote server name or NULL if local
char far *          queuename;      asciz queue name (net name)
char far *          username;       asciz user name
short               level;          level of detail requested; 0 or 1
char far *          buf;            for returned entry
unsigned short      buflen;         size of buffer;
unsigned short far *totalavail;     total size needed for buffer

Note:  The username is used in calculating the value of cq1_numahead in
       the chardevQ_info_1 structure.

Buffer contents on response:
    Level 0 contains a "struct chardevQ_info_0".
    Level 1 contains a "struct chardevQ_info_1".

Returns 0 if successful.  Possible error returns:
    - ERROR_INVALID_LEVEL --  The level parameter passed in is incorrect.
    - NERR_ServerNotStarted -- The server is not currently running.
    - NERR_BufTooSmall -- see Enum documentation.
    - ERROR_MORE_DATA -- see Enum documentation.
    - NERR_QueueNotFound -- The queuename parameter does not refer to a shared
      comm device.

------------------------
9.6  NetCharDevQSetInfo (Admin only) 

Purpose: Write the settable fields of a specified character device queue.

unsigned far pascal
NetCharDevQSetInfo( servername, queuename, level, buf, buflen, parmnum )
char far *      servername;         asciz remote server name or NULL if local
char far *      queuename;          asciz queue name
short           level;              level of detail provided; only 1 is valid.
char far *      buf;                contents described below
unsigned short  buflen;             size of buffer
short           parmnum;            which parameter to set

Buffer contents on call if parmnum is zero:
    contains a "struct chardevQ_info_1".

Settable fields are:
    priority
    devs

Returns 0 if successful.  Possible error returns:
    - NERR_ServerNotStarted -- Could not access the server's shared memory.
    - ERROR_INVALID_LEVEL -- level number is not 1.
    - NERR_InvalidParmnum -- parmnum supplied was not valid not one for one
      of the settable fields.
    - NERR_BadQueuePriority -- value to set the queue's priority to was
      not in the range of MIN_Q_PRIORITY and MAX_Q_PRIORITY.
    - NERR_QueueNotFound -- the value of queuename did not match any existing
      queue name in the server.
    - NERR_BadDevString -- syntax of device name string was incorrect.
    - NERR_NoRoom -- the maximum number of devices has already been defined.
    - NERR_RedirectedPath -- the device specified is redirected to another
      server.
    - NERR_InUseBySpooler -- device is currently in use by the spooler.
    - NERR_BadDev -- device specifed is not an actual device.
    - ERROR_SEM_TIMEOUT -- the comm device resources could not be accessed
      because they were in use by some other process.

------------------------
9.7  NetCharDevQPurge (Admin only) 

Purpose: Delete the contents of a character queue.

unsigned far pascal
NetCharDevQPurge ( servername, queuename )
char far *  servername;         asciz remote server name or NULL if local
char far *  queuename;          asciz queue name (net name)

This call purges all queued request in a character device queue.
DosOpen errors are returned to all clients that had queued requests.

Returns 0 if successful.  Possible error returns:
    - NERR_ServerNotStarted -- server shared memory is not accessable.
    - NERR_QueueNotFound -- no server to purge by the name of the value of
      queuename.
    - ERROR_SEM_TIMEOUT -- the comm device resources could not be accessed
      because they were in use by some other process.

------------------------
9.8  NetCharDevQPurgeSelf 

Purpose: Delete the contents of a character queue for a computer name.

unsigned far pascal
NetCharDevQPurge ( servername, queuename, computer )
char far *  servername;         asciz remote server name or NULL if local
char far *  queuename;          asciz queue name (net name)
char far *  computer;           asciz computer name

This call purges all queued request in a character device queue for
a specified computer name.  DosOpen errors are returned for all requests
waiting to open a comm device from that computer.

Returns 0 if successful.  Possible error returns:
    - ERROR_ACCESS_DENIED -- remote user trying to delete some other
                             computers requests.
    - NERR_ServerNotStarted -- server shared memory is not accessable.
    - NERR_QueueNotFound -- no server to purge by the name of the value of
      queuename.
    - NERR_InvalidComputer -- not a valid computer name.
    - NERR_ItemNotFound -- no opens for this queue.
    - ERROR_SEM_TIMEOUT -- the comm device resources could not be accessed
      because they were in use by some other process.

10.   MESSAGE SERVER 
These calls provide a set of functions for sending messages to other
users, logging the received messages, forwarding messages to 
another machine, etc.  The Enum call has two levels of detail:

    struct msg_info_0 {
        char            msgi0_name[CNLEN + 1];
    };

    struct msg_info_1 {
        char            msgi1_name[CNLEN + 1];
        unsigned char   msgi1_forward_flag;
        unsigned char   msgi1_pad1;
        char            msgi1_forward[CNLEN + 1];
    };


name            The name to send the message to.  Message names are
                ASCIZ strings up to CNLEN characters long.

forward_flag    Currently has the follow bit definitions:

                   Bit 2 set => This is a local name currently 
                                forwarded to a remote station.

                   Bit 4 Set => This is a remote name currntly 
                                forwarded to this station by
                                another station.

                Bit masks for these two bits are defined in "message.h"
                as MSGNAME_FORWARDED_TO and MSGNAME_FORWARDED_FROM.

                All other bits are reserved.

forward         If bit 2 of forward_flag is set, this is an ASCIZ
                string containing the name of the remote station to which
                this name is forwarded.

                If bit 4 of forward_flag is set, this is an ASCIZ
                string containing the name of the remote station from which
                this name is forwarded.

                Otherwise, undefined.


All of these functions should be used with the include file "message.h".

------------------------
10.1  NetMessageNameEnum 

Purpose: Supply information about the local name table at two 
         levels of detail.

unsigned far pascal 
NetMessageNameEnum( servername, level, buf, buflen, entriesread, totalentries)
char far *          servername;     asciz remote server name or NULL if local
short               level;          Level of detail requested
char far *          buf;            Pointer to buffer for name
unsigned short      buflen;         Buffer size available
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on successful completion:
    Level 0 contains a "struct msg_info_0".
    Level 1 contains a "struct msg_info_1".

Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed
    - ERROR_INVALID_LEVEL       - Level parameter specified is invalid 
    - ERROR_MORE_DATA           - The buffer supplied was too small for
                                  a complete enumeration of all message names
                                  currently active.

------------------------
10.2  NetMessageNameGetInfo 

Purpose: Supply complete information about a name in the name table.

unsigned far pascal
NetMessageNameGetInfo( servername, name, level, buf, buflen, totalavail)
char far *          servername;     asciz remote server name or NULL if local
char far *          name;           Ptr to asciz name to query
short               level;          Level of detail requested
char far *          buf;            Ptr to buffer for info
unsigned short      buflen;         Buffer size available
unsigned short far *totalavail;     total size needed for buffer

Buffer contents on successful completion:
    Level 0 contains a "struct msg_info_0".
    Level 1 contains a "struct msg_info_1".


Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed
    - ERROR_INVALID_LEVEL       - Level parameter specified is invalid 
    - NERR_BufTooSmall          - Buffer too small for the level of 
                                  information requested about the messaging
                                  name.
    - NERR_NotLocalName         - Name requested is not currently an active
                                  messanging name.
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.

    
------------------------
10.3  NetMessageNameAdd 

Purpose: Add a name to the local name table.
     
unsigned far pascal
NetMessageNameAdd( servername, name, fwd_action)
char far *  servername;         asciz remote server name or NULL if local
char far *  name;               Ptr to asciz name to add    
short       fwd_action;         Action to take if name is forwarded: 
                                    TRUE  (non-zero)    - Add name  
                                    FALSE (zero)        - Return error        
                     
Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed 
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_AlreadyExists        - Name already exists on this machine
    - NERR_DuplicateName        - Name already exists on the net
    - NERR_TooManyNames         - The local name table is full
    - NERR_AlreadyForwarded     - WARNING - The new name is forwarded

    
------------------------
10.4  NetMessageNameDel 

Purpose: Delete a name from the local name table.
     
unsigned far pascal
NetMessageNameDel( servername, name, fwd_action)
char far *      servername;     asciz remote server name or NULL if local
char far *      name;           Ptr to asciz name to delete 
short           fwd_action;        Action to take if name is forwarded: 
short       fwd_action;         Action to take if name is forwarded: 
                                    TRUE  (non-zero)    - Delete name  
                                    FALSE (zero)        - Return error        
                    
Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed 
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NotLocalName         - Name not found in local name table
    - NERR_DelComputerName      - The computer name cannot be deleted
    - NERR_NameInUse            - The specified name is temporarily locked,
                                   - retry command later.
    - NERR_AlreadyForwarded      - name is currently forwarded and fwd_action 
                                   was specified FALSE.


------------------------
10.5  NetMessageNameFwd 

Purpose: Start forwarding all messages to name to forward_name.
     
unsigned far pascal
NetMessageNameFwd( servername, name, forwardname, del_for)
char far *      servername;     asciz remote server name or NULL if local
char far *      name;           Ptr to asciz name to forward 
char far *      forwardname;    Ptr to asciz forward name   
short           del_for;        Action to take if name is forwarded: 
                                    TRUE - Del existing forward 
                                    FALSE -Return Error         

Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed 
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NotLocalName         - Name not found in local name table
    - NERR_AlreadyForwarded     - Name is already forwarded and del_for 
                                   was specified FALSE.
    - NERR_LocalForward         - forward_name is a local name.
    - NERR_NameNotFound         - forward_name not found on network.
    - NERR_RemoteFull           - Remote computer name table full.
    - NERR_NameInUse            - The specified name is temporarily locked,
                                  retry the command later.


------------------------
10.6  NetMessageNameUnFwd 

Purpose: Stop forwarding messages to name.
     
unsigned far pascal
NetMessageNameUnFwd( servername, name)
char far *  servername;         asciz remote server name or NULL if local
char far *  name;               Ptr to asciz name to Unforward
                    
Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed 
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NotLocalName         - Name not found in local name table
    - NERR_NameNotForwarded     - name not currently forwarded.
    - NERR_NameInUse            - The specified name is temporarily locked,
                                  retry the command later.
    - NERR_NameNotFound         - forwarded name not found on net


------------------------
10.7  NetMessageBufferSend 

Purpose : Send a message buffer to a remote message receiver.

unsigned far pascal
NetMessageBufferSend( server_name, name, buf, buflen)
char far *      servername;     asciz remote server name or NULL if local
char far *      name;           Ptr to asciz name to send to 
char far *      buf;            Ptr to buffer to send   
unsigned short  buflen;         Length of buffer to send    

The length of the message send buffer is limited only by the size
of an unsigned short (65535). However, only messages which will fit
in the receive buffer specified as the sizmessbuf parameter at startup
of the receiving message server will be successfully delivered.
The default sizmessbuf is 4096, which should be the limit on the
send message buffer length unless the receiving station has been 
configured to receive larger messages.

The message buffer should contain only printable characters.

Note that "name" may be "*" to send a broadcast message.  Broadcast 
messages are limited to 128 bytes and are not guaranteed to be delivered.


Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_TruncatedBroadcast   - Message was too long for a broadcast, sent
                                   the first packet only.
    - NERR_NameNotFound         - remote name not found on network
    - NERR_BadReceive           - message sent but not received
    - NERR_NotListening         - remote computer found but not listening
    - NERR_PausedRemote         - The remote message server is currently paused
    - NERR_NoComputerName       - Local computer name not set


------------------------
10.8  NetMessageFileSend 

Purpose : Send a message file to a remote message receiver.

unsigned far pascal
NetMessageFileSend( server_name, name, file_spec)
char far *  servername;         asciz remote server name or NULL if local
char far *  name;               Ptr to asciz name to send to 
char far *  file_spec;          Ptr to path\filename of file to send            

The length of the message send file is unlimeted. However, only messages 
which will fit in the receive buffer specified as the sizmessbuf parameter 
at startup of the receiving message server will be successfully delivered.
The default sizmessbuf is 4096, which should be the limit on the
send message file length unless the receiving station has been 
configured to receive larger messages.

The message file should contain only printable characters.

Note that "name" may be "*" to send a broadcast message.  Broadcast 
messages are limited to 128 bytes and are not guaranteed to be delivered.
    
Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_TruncatedBroadcast   - Message was too long for a broadcast, sent
                                   the first packet only.
    - NERR_NameNotFound         - remote name not found on network
    - NERR_BadReceive           - message sent but not received
    - NERR_NotListening         - remote computer found but not listening
    - NERR_PausedRemote         - The remote message server is currently paused
    - NERR_NoComputerName       - Local computer name not set

    Additional Error classes:
                
        File system error reading the message File
        
------------------------
10.9  NetMessageLogFileSet 

Purpose: Set log file and/or turn logging on or off.
 
Purpose : Specifies the file or device which will be use to log received 
           messages and turns on/off message logging to that file or device.

           depending on the value of the ON flag. If file_spec is NULL then
           the current log is turned on or off.

unsigned far pascal 
NetMessageLogFileSet( server_name, file_spec, on)

char far *              server_name     /* admin only. else blank       */
char far *              file_spec;      /* Ptr to path\filename of file */
                                        /*  or device to log received   */
                                        /*  messages to.                */
short                   on              /* Flag for logging on/off      */
           
Parameter "file_spec" is an ASCIZ string specifying the path of the
new logging device or file.  If file_spec is NULL then the current 
logging file/device is not changed.  A logging file/device of "",
the null string (not NULL pointer), means no logging device or
file is to be used.  In this case, parameter "on" must be zero.

Parameter "on", if TRUE (non-zero) turns on logging, and if FALSE (zero)
turns off logging.  If the "file_spec" is the null string, or if the
"file_spec" is NULL and the current logging file is the null string,
this parameter must be zero.  It is illegal to turn on logging unless
a logging file or device is specified.  The error for this is
NERR_NoLogFile.

Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed 
    - ERROR_INVALID_PARAMETER   - An invalid input parameter was detected.
    - NERR_NoLogFile            - no file or device currently specified for
                                   logging received messages ( only when 
                                   file_spec is NULL and on is TRUE)
    - NERR_InvalidDevice        - Invalid device for message logging 
    - NERR_WriteFault           - Write error occured flushing messages
                                   to log, log state is now off.
    - ERROR_VIO_DETACHED        - Console device not available for 
                                   message logging as message server is
                                   a detached process.

    Additional Error classes:
                
        File system error setting the message log
                                        
------------------------
10.10 NetMessageLogFileGet 

Purpose: Get log file name and current state (logging on of off)
 
unsigned far pascal 
NetMessageLogFileGet( server_name, buf, buf_len, on)

char far *              server_name     /* admin only. else blank       */
char far *              buf;            /* Ptr to buffer for log device */
                                        /*  or log file path\filename   */
unsigned short          buf_len;        /* Length of buffer available   */
short far *             on;             /* Storage for on/off status    */
                                        
The filename or device currently specified for message logging is
returned in "buf", and the current logging state (off=0, on=non-zero)
is placed in the variable pointed to by "on".
           
Returns 0 if successful. Error return information:

    - NERR_NetNotStarted        - Network not installed on local machine                        
    - NERR_MsgNotStarted        - Message server not installed 
    - NERR_BufTooSmall          - Buffer length was too short for log path.

    

11.   SERVICE 

The service api provides a standardized way to start/stop network
service programs, and interrogate/control their status, locally and on
remote servers.  Programs written as Lan Manager services 
can be started, stopped, paused, and continued by the existing Net
command-line user interface, and by applications using these APIs.

See section 29 for more information on writing Lan Manager
service programs, or adapting existing applications to the
requirements of the Service APIs.  See section 28 for information on
the standard Lan Manager services.


11.1  General Information 

Data structures and constants for the service APIs are defined in
the files:

        netcons.h
        service.h
        

11.1.01 Data Structures 

Service Information has three levels of detail:

    struct service_info_0 {
        char            scvi0_name[SNLEN+1];
    };

    struct service_info_1 {
        char            scvi1_name[SNLEN+1];
        unsigned short  scvi1_status;
        unsigned long   scvi1_code;
        unsigned short  scvi1_pid;
    };

    struct service_info_2 {
        char            scvi2_name[SNLEN+1];
        unsigned short  scvi2_status;
        unsigned long   scvi2_code;
        unsigned short  scvi2_pid;
        char            scvi2_text[STXTLEN+1];
    };

name            Service name, up to SNLEN characters.

status          Bitmapped field defining the current status of the service.
                The bits are defined as follows:

                Bits  Mask      Mask/Values

                 0,1   0x3      SERVICE_INSTALL_STATE

                                SERVICE_UNINSTALLED          0
                                SERVICE_UNINSTALL_PENDING    0x1
                                SERVICE_INSTALL_PENDING      0x2
                                SERVICE_INSTALLED            0x3

                 2,3   0xC      SERVICE_PAUSE_STATE

                                SERVICE_ACTIVE               0
                                SERVICE_CONTINUE_PENDING     0x4
                                SERVICE_PAUSE_PENDING        0x8
                                SERVICE_PAUSED               0xC

                 4     0x10     SERVICE_ININSTALLABLE        0
                                SERVICE_NOT_UNINSTALLABLE    0x10

                 5     0x20     SERVICE_PAUSABLE             0
                                SERVICE_NOT_PAUSABLE         0x10


                 6-15     <reserved>    
        

code            A special value, whose meaning is dependent on the current
                service status.  The service's primary status is that part
                of the "status" field masked by SERVICE_INSTALL_STATE,
                defined above.

                INSTALL_PENDING: the code is used to keep the installing 
                  process informed of the progress of the installation,
                  and to give estimates of how long installation will take.
                  See the discussion of IP codes below.

                INSTALLED: the code is reserved for future use and should
                  be zero in this implementation.  This is not enforced
                  by the APIs, but failure to conform may result in an
                  incompatibility with future Lan Manager releases.

                UNINSTALL_PENDING: the code is reserved for future use and 
                  should be zero in this implementation.  This is not 
                  enforced by the APIs, but failure to conform may result in 
                  an incompatibility with future Lan Manager releases.

                UNINSTALLED: the code gives information about why the
                  service is uninstalled.  See the discussion of the
                  UIC codes below.

pid             Process ID of the service program.

text            This field is currently reserved and should be a null
                ASCIZ string (that is, begin with a zero byte), except
                for services in the UNINSTALLED state.  For services in
                the UNINSTALLED state, the text field is used in conjunction
                with the code field (above) to give information about the
                service's demise.  See the discussion of UIC codes below.


The following structure is used for the buffer passed to NetServiceStatus.
This information is supplied by a service to set the information describing
the current status of that service.

    struct service_status {
        unsigned short  scvs_status;
        unsigned long   scvs_code;
        unsigned short  scvs_pid;
        char            scvs_text[STXTLEN+1];
    };


status          As per status field of service_info structs above.

code            As per code field of service_info structs above.

pid             Used to change PID of service.  If zero, means do
                no change PID, otherwise change PID to this value.
                Useful when the initially executed module is only
                an init program, that in turn execs the main service
                program.  The init program must use NetServiceStatus
                to set the service PID to the PID of the main module.

text            As per text field of service_info, above.


11.1.02 UIC (Uninstall) Codes 

When a service is UNINSTALLED, the "code" field gives information about
the reason for the service's uninstallation.  The "code" field is
browken into a high and low word:

        unsigned short high, low;
        struct service_info_2 si;

        high = (unsigned short) ((si.svci2_code & 0xffff0000) >> 16);
        low  = (unsigned short) (si.svci2_code & 0xffff);

The high word of 'code' is a UIC (uninstalled code) value, and the
low word is a modifier (UIC_M) value.  UIC values include:

        SERVICE_UIC_BADPARMVAL          Bad parameter value
        SERVICE_UIC_MISSPARM            Missing required parameter
        SERVICE_UIC_UNKPARM             Unknown parameter
        SERVICE_UIC_AMBIGPARM           Ambiguous parameter name
        SERVICE_UIC_DUPPARM             Duplicated parameter
        SERVICE_UIC_RESOURCE            Insufficient resource
        SERVICE_UIC_CONFIG              Configuration problem
        SERVICE_UIC_SYSTEM              Unexpected (and fatal) OS/2 error
        SERVICE_UIC_INTERNAL            Internal error
        SERVICE_UIC_KILL                Killed by NetServiceControl
                                          (see NetServiceControl)
        SERVICE_UIC_EXEC                Could not exec service program file
        SERVICE_UIC_SUBSERV             A subservice of this service failed
                                          to install

The low word is a modifier.  A modifier of 0 is the NULL modifier,
meaning no further info available.  Where a UIC code is specified
as having no modifiers, the modifier should be set to zero for
compatibility with future extensions.  Modifiers are defined
for each UIC code as follows:


        SERVICE_UIC_BADPARAMVAL
                No modifier, but text field is the parameter name

        SERVICE_UIC_UNKPARAM
                No modifier, but text field is the parameter name

        SERVICE_UIC_MISSPARAM
                No modifier, but text field is the parameter name

        SERVICE_UIC_AMBIGPARM
                No modifier, but text field is the parameter name

        SERVICE_UIC_DUPPARM
                No modifier, but text field is the parameter name

        SERVICE_UIC_RESOURCE
                SERVICE_UIC_M_MEMORY           Insufficient memory
                SERVICE_UIC_M_DISK             Insufficient disk space
                SERVICE_UIC_M_THREADS          Can't create thread
                SERVICE_UIC_M_PROCESSES        Can't create process

        SERVICE_UIC_CONFIG
                SERVICE_UIC_M_NETBIOS           Unable to open NetBios
                SERVICE_UIC_M_WKSTA             Wksta not started
                SERVICE_UIC_M_REDIR             Redirector not installed
                SERVICE_UIC_M_SERVER            Server not started
                SERVICE_UIC_M_USERVER           Requires user-level security

        SERVICE_UIC_SYSTEM
                system (OS/2 or Lan Manager) error code

        SERVICE_UIC_INTERNAL
                system (OS/2 or Lan Manager) error code

        SERVICE_UIC_SUBSERV
                No modifier, but text field is the subservice name
                

Note that some UIC codes require that the text field contain the
name of some item, always as an ASCIZ string.  For all other
UIC codes the text field should be a null string.


11.1.03 IP (Install Pending) Codes 

The install-pending (IP) code values are used when a service expects
to take a long time to install. A long time is loosely defined as
two seconds, but any service which has a non-trivial init task should
use this method.

If a service is not using IP codes, the "code" field should always be
set to zero while the service status is INSTALL_PENDING.

The IP codes devide the "code" field into fields as below:


    33322222 222221111 111111
    21098765 432109876 54321098 76543210

    xxxxxxxx xxxxxxxxH TTTTTTTT CCCCCCCC

        x =  not used
        H =  hint is given              SERVICE_IP_QUERY_HINT
        T =  time to wait               SERVICE_IP_WAIT_TIME
        C =  checkpoint number          SERVICE_IP_CHKPT_NUM


Bits not used should be set to zero for compatiblity with future
uses of the IP codes.

Time-to-wait is the expected time to install, in tenths of a second.

Checkpoint number is a number that should be incremented, or at
least changed to a higher value, each time the service calls
NetServiceStatus.  A "nice" service would call NetServiceStatus
fairly often to keep updating this number - remembering of course
that it is an eight-bit quantity.

In any case, an installer who sees this value constantly changing
will assume the service is still alive and not hung.  For that reason,
the code that calls NetServiceStatus to update the IP code should
be in the main installation path, and not just some timer-triggered
thread that might live on even while the installation is halted.

The "hint is used" bit tells the application installing the service that
the other (time and count) information is valid.


------------------------
11.2  NetServiceGetInfo 

Purpose: Get information about a service

unsigned far pascal
NetServiceGetInfo(servername, service, level, buf, buflen, avail )
char far *          servername;     asciz remote server name or NULL if local
char far *          service;        Service name
short               level;          level of detail requested
char far *          buf;            Buffer for return data
unsigned short      buflen;         Length of return buffer
unsigned short far *avail;          total bytes available

Buffer contents on return:
    Level 0 contains a "struct service_info_0".
    Level 1 contains a "struct service_info_1".
    Level 2 contains a "struct service_info_2".

NOTE: that NetServiceGetInfo WILL RETURN SUCCESS for entries that are 
UNINSTALLED.  This allows post-mortem examination of the service data,
such as the uninstall code.  You MUST check the status field of a 
service's data to know if the service entry you retrieved is current.
For this reason, using level 0 with GetInfo is rather useless but is
allowed to maintain orthogonality.

Further, note that information about an uninstalled service is not
guarantted to be available, since such table entris are re-used
and overwritten as needed.  Unless the table has no vacant entries,
this will not happen, but be aware of the possiblity.

Returns 0 if successful. Possible error returns:

    ERROR_INVALID_LEVEL         Level parameter invalid, must be {0,1,2}.
    NERR_ServiceNotInstalled    Service specified is not found in the table.
                                   <see note above about SUCCESS and
                                    dead services>
    NERR_BufTooSmall            Buffer too small for structure.
    ERROR_MORE_DATA             


------------------------
11.3  NetServiceEnum 

Purpose: Return list of services installed at a server.

unsigned far pascal
NetServiceEnum(servername, level, buf, buflen, entriesread, totalentries)
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested
char far *          buf;            Buffer for return data
unsigned short      buflen;         Length of return buffer
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on return:
    Level 0 contains a "struct service_info_0".
    Level 1 contains a "struct service_info_1".
    Level 2 contains a "struct service_info_2".

Note that NetServiceEnum will not return entries that are UNINSTALLED.

Returns 0 if successful. Possible error returns:

    ERROR_INVALID_LEVEL         Level parameter invalid, must be {0,1,2}.
    ERROR_MORE_DATA               See "Enum APIs" summary

------------------------
11.4  NetServiceInstall 

Purpose: Cause a service to be started at a server

unsigned far pascal
NetServiceInstall(servername, service, cmdargs, buf, buflen)
char far *      servername;     asciz remote server name or NULL if local
char far *      service;        Service name
char far *      cmdargs;        Arguments for services (ASCIZ+)
char far *      buf;            Status of installed service
unsigned short  buflen;         Size of buf

This routine starts a network service at the specified server.
Admin privilege is required at the target server.  Services are
started using DosExecPgm.  The name of the executable file is found
in LANMAN.INI;  the service names is matched to an entry in the
[services] component, and the right side of that entry is the
executable name.  If a relative path, it is taken as being relative
to the Lan Manager SERVICES directory.

The user-supplied cmdargs may be NULL, or may point to a series of
ASCIZ arguments, terminated by a NULL argument.  Arguments should be
in one of the forms show in the example below:

        arg\0                   <- ASCIZ argument
        arg=value\0             <-   "     "
        arg:value\0             <-   "     "
        \0                      <- Null argument terminates list

Arguments in cmdgars is merged with arguments from the LANMAN.INI
file.  The LANMAN.INI arguments are found in the file under the
header [xxx], where "xxx" is the name of the service.  If an argument
appears in both cmdargs and LANMAN.INI, the cmdargs parameter has
precedence.

The result of the merge is passed to the service program as exec
args.  That formatting will be done insinde NetServiceInstall, along
with the merge of the arguments.

Buf will contain a struct service_info_2 after a successful call.
Check the status word in this structure to determine the status of
the service after installation.  The buffer MUST be big enough to
hold service_info_2.

Returns 0 if successful. Possible error returns:


    NERR_BufTooSmall            Buffer too small for service_info_2
                                  structure.

    NERR_BadServiceName         Service name poorly formed, or not listed in
                                  [services] area of LANMAN.INI.

    NERR_BadServiceProgName     Program name given for this service in the
                                  [services] area of LANMAN.INI is poorly
                                  formed.

    NERR_LineTooLong            A line in LANMAN.INI, in the section for
                                  the requested service, is too long.  See
                                  NetConfigGetAll API.

    NERR_ServiceInstalled       Service already installed.  Note that the
                                  instance "already installed" may in fact
                                  be INSTALL_PENDING or UNINSTALL_PENDING.

    NERR_ServiceCtlTimeout      Service did not set its status within the
                                  timeout period.  The service will be killed
                                  via DosKillProcess and marked as UNINSTALLED.

    NERR_ServiceTableLocked     Service table locked by another
                                  caller, try later.

    NERR_ServiceEntryLocked     Service table entry locked by another
                                  caller, try later.

    NERR_ServiceTableFull       Service table is full.  The number of
                                  services that may be installed is set by
                                  the /numservices switch (or LANMAN.INI
                                  entry) at WORKSTATION start time.

    NERR_LanmanIniError         Unable to find LANMAN.INI, or the [services]
                                  component in LANMAN.INI.

    NERR_ServiceCtlBusy         Service currently respoding to another
                                  NetServiceControl call, try later.

    ERROR_NOT_ENOUGH_MEMORY                  Not enough memory for merging arguments and
                                  building command line.

    OS/2 Exec errors            From DosExec for the service program

------------------------
11.5  NetServiceControl 

Purpose: Interrogate and Control operating status of a service.

unsigned far pascal
NetServiceControl(servername, service, opcode, arg, buf, buflen)
char far *     servername;         asciz remote server name or NULL if local
char far *     service;            Service name
unsigned char  opcode;             Control opcode
unsigned char  arg;                Control arg (service/opcode specific)
char far *     buf;                Buffer for return results
unsigned short buflen;             Size of buffer

Buffer contents on return:
    struct service_info_2

Valid values for Control Opcode:

    0  SERVICE_CTRL_INTERROGATE         Interrgoate service status
    1  SERVICE_CTRL_PAUSE               Pause service (see next paragraph)
    2  SERVICE_CTRL_CONTINUE            Un-Pause service (see next paragraph)
    3  SERVICE_CTRL_UNINSTALL           Uninstall service

    4-127 reserved by Microsoft
    128-255 OEM defined

Services may choose to ignore any or all of the opcodes.  A service
should 'ignore' an opcode by treating it as an INTERRGOATE.  Services
which intend to ingore UNINSTALL and/or PAUSE opcodes should so indicate
in their 'status' word (see service_info field "status" above).

The meaning of PAUSE/CONTINUE will vary from service to service.  For
the meaning to standard Lan Manager services see STANDARD SERVICES.
Other services should document the meaning of PAUSE and CONTINUE opcodes
as far as each service is concerned.

Values for 'arg' depend on the opcode being used and the service being
controlled.  It is usually ignored.  For an example of 'arg' being used,
see the information on WORKSTATION in STANDARD SERVICES.

Note that if the requested control operation takes a long
time to complete, the status and code values returned by
NetServiceControl may be intermediate (e.g., return one of the
"pending" status results defined in struct service_info_2); the
application in this case would have to issue a subsequent
NetServiceControl to check when the requested operation has
completed.

The INTERROGATE opcode is always valid for a service, provided
that service has been installed at some point.  If the service
being interrogated is INSTALLED, then the service will be signaled, and
the up-to-date status returned to the caller.  If the service is
INSTALL_PENDING, UNINSTALL_PENDING, or UNINSTALLED, then the last
known state of the service will be returned to the caller, with no
attempt made to contact the service itself.  If the service has never
been installed, NetServiceControl will return NERR_ServiceNotInstalled.

Not that interrogating a service which has never been installed
will result in NERR_ServiceNotInstalled.  However, once a service has
been installed, its information remains in the service table (*) so
that NetServiceControl can be used to interrogate the status of the
service.  This allows applications to determine the reason for the
service's uninstalled state, by examining the service_status.code
field.  See the discussion of SERVICE_UIC codes above.

Opcodes other than INTERROGATE are valid only for INSTALLED services.
Such opcodes, when used with a service which is INSTALL_PENDING
or UNINSTALL_PENDING, will return NERR_ServiceCtlNotValid.  When
used with an UNINSTALLED service or one never installed at all,
NetServiceControl will return NERR_ServiceNotInstalled.

(*) Since the service information is kept in a table of finite size,
set by the "numservices" workstation initialization paramater, it is
possible the information of a service which is uninstalled will be
overwritten by a newly installed service.  However, to preserve the
information about the previous service, entries are not resued unless
the table is otherwise full.

Returns 0 if successful. Possible error returns:

    NERR_BufTooSmall            Buffer too small for service_info_2
                                  structure.

    NERR_ServiceNotInstalled    Service specified is not installed.

    NERR_ServiceTableLocked     Service table locked by another
                                  caller, try later.

    NERR_ServiceCtlBusy         Service currently responding to another
                                  NetServiceControl call, try later.

    NERR_ServiceCtlNotValid     Service has registered itself as not pausable
                                  or uninstallable, so the opcode specified
                                  is invalid.

    NERR_ServiceCtlTimeout      Service did not respond to the signal.
                                  Usually means the service is dead, but
                                  it is possible that in a heavily loaded
                                  system, if the service's signal-handler
                                  thread has low priority, this will occur
                                  with a perfectly healty service.

    NERR_ServiceKillProc        Service did not respond to an UNINSTALL
                                  signal, so KILL signal was used.  Service
                                  is marked UNINSTALLED in the table.

    NERR_ServiceNotCtrl         Service is not in INSTALLED state, and the
                                  opcode specified cannot be performed.


------------------------
11.6  NetServiceStatus 

Purpose: Update status and code information.

NOTE:  This call is for use by installed service programs.  For more 
detailed information on this call, see the Chapter on Writing Lan
Manager Service Programs.

unsigned far pascal
NetServiceStatus(buf, buflen)
char far *     buf;                      Buffer for args
unsigned short buflen;                   Length of args


Buffer (see status_info structure above).

NetServiceStatus is used BY SERVICE PROGRAMS to update their
status information.  Only service programs, which have been started
via NetServiceInstall, can call this API.  NetServiceStatus uses the PID
(process ID) of the calling process as an indetifying key.  Callers
which are not installed services will fail, recieving error code
NERR_ServiceNotInstalled.

Service programs are required to use this call to update their status
information in the service table.  For example, upon being
successfully installed, the service should call NetServiceStatus to
set status to "installed".  If install fails, the service program
should set status to "uninstalled" and the code field to an error
number.  Services must also use this api to acknowlegde pause, continue,
interrogate, and uninstall requests.

Services that are active may use this api at any time to update
their status.  In this way, they can set the code and text fields
of their status record to indicate their current operating status.

Returns 0 if successful. Possible error returns:

    NERR_ServiceNotInstalled    Caller is not an service started
                                  via NetServiceInstall.  This error
                                  will also occur if a service accidentally
                                  set the "pid" field of the status buffer
                                  on a previous call.

    NERR_BufTooSmall            Buffer too small to contain the
                                  service_status structure

    NERR_ServiceTableLocked     Service table locked by another
                                  caller, try later


12.   CONFIG 

The config API is used to get information from the LANMAN.INI file.
This allows any application to store configuration information
in a central place and retreive it with a simple mechanism.

The file LANMAN.INI is the central repository for configuration
information for all Microsoft-supplied Lan Manager services.  Other
Lan-related applications are encouraged to use this file for the same
purpose.  Lan Manager Services will recieve information from this
file automatically;  see chapter 29 for futher information on Lan
Manager Service programs.

The LANMAN.INI file is an ASCII file containing comment lines,
component lines, and parameter lines.

  o A COMMENT LINE is any blank line or a line whose first non-blank
    character is a semi-colon (';').

  o A COMPONENT LINE marks the start of a new component's information.
    It is of the form:

        [component-name]

  o A PARAMETER LINE contains a parameter and a value, in the form:

        parameter = value

    The value portion may be any arbitrary text, and is not processed
    by the NetConfig APIs, except that leading and trailing spaces
    are stripped.  Any interpretation of the value string is left
    to the caller.


All parameters appearing under a component line belong to that
component.  A component should only appear in the file once;  if
a component appears in the file twice, only the first entry will
be recognized.

If a parameter appears twice in a given component, it will appear
twice in the buffer if NetConfigGetAll is used.  The value of the
first appearance will be returned if NetConfigGet is used.  A parameter
may appear any number of times under different components, however.


WARNING:  NO QUOTATION MARKS MAY BE USED IN THE VALUE.


All of these functions should be used with the include file "config.h".

------------------------
12.1  NetConfigGet 

Purpose: Get a specific value from the LANMAN.INI file.

unsigned far pascal
NetConfigGet(component, parameter, buf, buflen, parmlen)
char far *      component;      component name
char far *      parameter;      paramter name
char far *      buf;            buffer to load parm value into
unsigned short  buflen;         bytes requested
unsigned short far *  parmlen;        actual parameter length (returned)

Returns the value (ASCIZ string) for a single parameter of a
specified component in buf.  This string is the entire VALUE content
of the LANMAN.INI line for the specified parameter, which is all text
to the right of the '=' sign.  Leading and trailing spaces will be
stripped from this text.  No other processing is performed on it.

Returns 0 if there were no errors. Possible error returns:

        NERR_NetNotStarted              network not installed
        NERR_CfgCompNotFound            component name not found
        NERR_CfgParamNotFound           parameter name not found
        NERR_BufTooSmall                buffer too small for data
        OS/2 file system errors         e.g. ERROR_SHARING_VIOLATION

------------------------
12.2  NetConfigGetAll 

Purpose: Get all config info for a component

unsigned far pascal
NetConfigGetAll(component,buf,buflen,bytesRead,bytesAvail)
char far *      component;       component name in LANMAN.INI
char far *      buf;             buffer to load parm strings into
unsigned short  buflen;          bytes requested
unsigned short far *    bytesRead;       bytes returned (returned)
unsigned short far *    bytesAvail;      bytes of config info avail for component (returned)

Returns in buf a set of concatenated asciz strings, representing
config info for the specified component.  Each string is terminated
by a null byte (ascii 0), and the whole buffer is terminated by a
null string.  Information is returned in the canonicalized form
Parm=Value.

The parameter name (left of the '=') is upper-cased.

BytesRead and BytesAvail are filled in as for GetInfo calls.


Example:

    "   foo = Bar,1,long comment string  "

in LANMAN.INI file is returned as:

    "FOO=Bar,1,long comment string"


Returns 0 if there were no errors. Possible error returns:

        OS/2 file system errors         e.g. ERROR_SHARING_VIOLATION
        NERR_NetNotStarted              network not installed
        NERR_CfgCompNotFound            component name not found
        ERROR_MORE_DATA                 buffer too small for all data


13.   ALERT 

The alert api provides a standardized way for network service
programs and applications to receive notification of network events
such as print job completion, receipt of net messages, or server
conditions that require human intervention.  New types of events may
be defined for specific applications.

A program registers to be notified of a specific class of events
usng the NetAlertStart API.  When the program no longer wishes to
be notified, it uses the NetAlertStop API.  A program can register
to use one of two delivery mechanisms:  a mailslot or a system 
semaphore.  If a program will need detailed information about an
event, it should use a mailslot, since a semaphore cannot transmit
such information.  See NetAlertRaise, below, for more discussion.

Other programs, Lan Manager services, or internal network components
use the NetAlertRaise API to "raise" an alert, notifying all 
registered applications that such an event has occured.

The following pseudo-code outlines a function which uses the NetAlert
APIs to recieve notification of printing events, and to pass such
notification to the user.


        print_job_alert_handler()
        {
                DosMakeMailslot ( );

                NetAlertStart ( );

                while ( still_running )
                {
                        DosReadMailslot ( );

                        notify_user ( );
                }

                NetAlertStop ( );

                DosDeleteMailslot ( );
        
                return;
        }


There are 5 standard events raised by the LAN Manager server:

    ALERT_PRINT_EVENT    "printing"  completion or problem with a print job

    ALERT_MESSAGE_EVENT  "message"   receipt of a net message

    ALERT_ERRORLOG_EVENT "errorlog"  write to error log

    ALERT_ADMIN_EVENT    "admin"     administrative alert condition

    ALERT_USER_EVENT     "user"      user alert condition


Programs registered with the mailslot mechanism will receive
information about each event in the class(es) for which the program
has registered.  This data consists of a standard fixed-length
header, followed by variable length data which is specific to the
type of event.

The standard header has the following format:

   struct std_alert
   {
        long    alrt_timestamp;           
        char    alrt_eventname[EVLEN+1];
        char    alrt_servicename[SNLEN+1];
   };

timestamp       Time of the event (see "timestamps", Chapter 1).

eventname       Name of the event, the "event type", as an ASCIZ string.

servicename     Name of the Lan Manager service (if any) which detected
                or caused the event.

Immediately following this standard structure may be additional information
in a form specific to the event class.  Structures for the currently
defined classes are given in "alert.h".  Note that these structures
define only the fixed-length portions of the information, and not the
ASCIZ strings which follow some of these items.

To help you access the fields in the alert structure, macros have been
defined in "alert.h":  ALERT_OTHER_INFO() and ALERT_VAR_DATA().  You
can see examples of these macros at work in the example function in
this section.  Also, macros ALERT_OTHER_INFO_F and ALERT_VAR_DATA_F
are provided for use with "far" pointers.

   o ALERT_OTHER_INFO, when given a pointer to the start of the std_alert
     structure, resolves to a pointer to the "other data", that data which
     is specific to the event class.

   o ALERT_VAR_DATA is less universally applicable, and is written to
     work with the structures defined in "alert.h" for the class-specific
     data.  Given a pointer to such data, it returns a pointer to the first
     ASCIZ string in the alert buffer.


13.0.01 Print Alert, Class-specific Information 

The format of the class-specific information for a print alert is:

    struct print_other_info {
        short       alrtpr_jobid;  
        short       alrtpr_status; 
        long        alrtpr_submitted; 
        long        alrtpr_size;      
    };

        Followed by the following packed ASCIZ strings:

        char        computername[]    
        char        username[]        
        char        queuename[]       
        char        destname[]        
        char        status_string[]   


jobid           Job ID of the print job related to the event.

status          A job status indicator.  See the values described for
                DosPrintJobStatus.  Note that the highest bit (bit 15), 
                if set, indicates if the job is deleted.

submitted       The time the job was submitted.  See "timestamps" in
                Chapter 1.

size            The size of the job in bytes.

computername    The name of the machine that submitted the job.

username        The name of the user that submitted the job.

queuename       The name of the queue to which the job was submitted.

status_string   The extra status info that is posted by the print processor.


13.0.02 Message Alert, Class-specific Information 

Other_info for a message alert is the text of the received message.


13.0.03 Errlog Alert, Class-specific Information 

    struct errlog_other_info {
        short       alrter_errcode;
        long        alrter_offset;
    };

errcode         Error code used when logging the error-log entry.

offset          Offset in bytes of this error-log entry in the error log
                file.  See NetErrorLog API documentation for information
                on retrieving the complete error-log entry from this file.

13.0.04 Admin Alert, Class-specific Information 


The format of the class-specific information for an admin alert is:

    struct admin_other_info {
        short       alrtad_errcode;   
        short       alrtad_numstrings;
    };

        Followed by the following packed ASCIZ fields:

        char        mergestrings[][]    

errcode         Error code related to the cause of the alert.

numstrings      Number of strings in the var-len data area, value can
                be 0 through 9.

mergestrings    Zero or more (up to 9) ASCIZ strings, containing information
                related to the cause of the alert.  If the code
                in "errcode" has an associated text message in the
                OS/2 or Lan Manager message files, these strings can
                be used as "mergestrings" with such text when calling
                DosGetMessage.


13.0.05 User Alert, Class-specific Information 

The format of the class-specific information for a user alert is:

    struct user_other_info {
        short       alrtus_errcode;
        short       alrtus_numstrings;
    };

        Followed by the following packed asciz fields:

        char        mergestrings[][]
        char        username[]      
        char        computername[]   

errcode         Error code related to the cause of the alert.

numstrings      Number of merge strings in the var-len data area, 
                value can be 0 through 9.  This DOES NOT include the
                username or computername strings, which always appear,
                following any merge strings.

mergestrings    Zero or more (up to 9) ASCIZ strings, containing information
                related to the cause of the alert.  If the code
                in "errcode" has an associated text message in the
                OS/2 or Lan Manager message files, these strings can
                be used as "mergestrings" with such text when calling
                DosGetMessage.

computername    The name of the machine the user is on.

username        The name of the user that this alert is about.


------------------------
13.1  NetAlertStart 

Purpose: Start an event-watch on "event" such that "recipient" will
         be notified on the event happening.

unsigned far pascal
NetAlertStart(event, recipient, maxdata)
const char far * event;                /* Name of event to watch */
const char far * recipient;            /* Recipient to notify of event */
unsigned short   maxdata;              /* Max bytes of event data to notify */

The "recipient" may be the name of a system semaphore or local mailslot.
Any other type of name in "recipient" makes NetStartAlert return with an
error NERR_BadRecipient.

Event names are ASCIZ strings.  Microsoft has defined several
standard events (see NetAlertRaise); however, OEMs or applications
can define their own events simply by specifying the name when
calling NetAlertStart and NetAlertRaise.  Choose names that are not
likely to conflict with other applications' or OEMs' event names.

If "recipient" starts with \SEM\, a NetAlertRaise (q.v.) on the
specified event will open, clear, reset, and close the system
semaphore named.  The process owning the semaphore must have created
it with the NoExclusive option set; presumably such a process will be
executing a DosSemWait or DosMuxSemWait on this semaphore, and so
will be aware of the semaphore's state transition.

If "recipient" starts with \MAILSLOT\, NetAlertRaise will write a
packet of data to that mailslot, up to a maximum of "maxdata" bytes. 
The content of this packet is completely dependent upon the event
type.

Returns 0 if there were no errors.
Possible error returns:
    NERR_BadRecipient           - bad recipient specified
    NERR_AlertExists            - alert already exists
    NERR_TooManyAlerts          - alert table is full
    NERR_ShareMem               - couldn't access alert table
                                  (WORKSTATION service probably not started)

------------------------
13.2  NetAlertStop 

Purpose: Terminates any event-watch on "event" by "recipient".
         It is an error to terminate a watch that does not exist.

unsigned far pascal
NetAlertStop(event, recipient)
const char far *  event;                /* Name of event to stop watching */
const char far *  recipient;            /* Recipient that was watching */

Returns 0 if there were no errors.
Possible error returns:
    NERR_NoSuchAlert            - no such alert exists
    NERR_ShareMem               - couldn't access alert table
                                  (WORKSTATION service probably not started)

------------------------
13.3  NetAlertRaise 

unsigned far pascal
NetAlertRaise(event, timeout, buffer, buflen)
const char far * event;                /* Name of event on which to alert */
const char far * buffer;               /* Pointer to buffer of data to pass */
unsigned short   buflen;               /* Number of bytes in "buffer" */
unsigned long    timeout;              /* Timeout used for mailslot writes */

Alerts all clients who have registered themselves (via NetAlertStart)
as monitoring a particular event.  This call will either strobe a
system semaphore or write alert information to a mailslot for each
registered client (see NetAlertStart).

A mailslot client will receive the "buflen" bytes of data in
"buffer", written via DosWriteMailslot (q.v.) with the specified
timeout; notice however that the mailslot may receive less than
buflen bytes if it was registered with a smaller "maxdata".

Returns 0 if there were no errors.
Possible error returns:
    NERR_ShareMem               - couldn't access alert table
                                  (WORKSTATION service probably not started)


14.   ACCESS PERMISSIONS 

These calls provide information and control over access privileges for
resources available at a server.  

14.1  General Information 

Resource access control on user-security services is implemented as
a permission list.  Each resource has an associated list of permission
records (struct access_list), which give the name of an entity (user
or group) and the permissions associated with that entity for this
resource.

User's permission has precedence over groups' permissions which he
is a member of. If the user is not in the access list of the named resource,
his access right is the union of all groups he is a member of.


The basic access data structures are:

    struct access_info_0 {
        char far *  acc0_resource_name;
    };

    struct access_info_1 {
        char far *  acc1_resource_name;
        short       acc1_acl_attr;
        short       acc1_count;
    };


resource_name   ASCIZ strings formatted as follows:

                    Directory:        Absolute path, with drive  
                                                (e.g. C:\BIN)
                    File:             Absolute path, with drive  
                                                (e.g. C:\BIN\LS.EXE)
                    Pipe:             Pipe name (e.g. \PIPE\SQLIO)
                    Print queue:      \PRINT\Queuename
                    Char device:      \COMM\Devname
                    All pipes:        \PIPE
                    All print queues: \PRINT
                    All char queues:  \COMM

attr            Various atrributes of this resource.  Only bit 0
                is currently defined. 

                The bits of the attr fields are used as
                  0             Audit ( == 1)/ NoAudit( == 0)
                  1-15            reserved, MBZ

                If the audit bit is on, an audit trail record 
                will be generated each time the named resource 
                is being accessed.

count           Number of access_list structures associated with this
                resource.  Current implementation has a maximum of 64.

When obtaining or setting level-1 information about a resource, the
access_info_1 structure is followed by zero or more access_list
structures, which define permissions for this resource for individual
users or groups.  The maximum number of access list entries
associated with a resource is 64 in this release.


The "access_list" structure is:

    struct access_list {
        char   acl_ugname[UNLEN+1];
        char   acl_ugname_pad_1;
        short  acl_access;
    };

ugname          The name of an entity (user or group).

access          Bits defining the permissions of this entity on this
                resource.


                  Bit   Symbol        Mask      Meaning 

                   0    ACCESS_READ    0x1      Read from existing resources

                   1    ACCESS_WRITE   0x2      Write to existing resources

                   2    ACCESS_CREATE  0x4      Create new files

                   3    ACCESS_EXEC    0x8      Open file for execution

                   4    ACCESS_DELETE  0x10     Delete existing files

                   5    ACCESS_ATRIB   0x20     Set the resource's attribute,
                                                 i.e. can use the OS/2 API
                                                 DosSetFileInfo.

                   6    ACCESS_PERM    0x40     Change the resource's access
                                                 record.  See following 
                                                 paragraph.

                 7..14  <reserved>

                  15    ACCESS_GROUP   0x8000   When returned, indicate if
                                                the above ugname is a group.    



A user can read or change the access record using NetAccessGetInfo or
NetAccessSetInfo only if he either has ADMIN priviledge, or has
ACCESS_PERM on the named resource.  Likewise, NetAccessEnum will
return only the entries for which the user has ACCESS_PERM.

ACCESS_READ implicitly includes ACCESS_EXEC and any permission bit will
also grant the access of DosFindFirst.


All of these functions should be used with the include file "access.h".

-------------------------
14.2  NetAccessEnum 

Purpose:  Enumerate access privileges for all defined net resources
          at a server.

unsigned far pascal
NetAccessEnum( servername, basepath,  recursive, level, buf, buflen,
                entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL
char far *          basepath;       base path for enumeration (see below)
short               level;          level of detail requested; 0, 1
short               recursive;      see below
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

The basepath parameter, if not NULL string, serves as a prefix to
qualify the enumeration.  The entries returned are limited to those
whose names begin with the qualifier string.  For example, a
qualifier of "C:" would enumerate only access records for drive C.

The resource names are returned as fully qualified path names where
appropriate.  However, if basepath is not a null string, then resource
names are returned as names relative to the basepath.

If the recursive parameter is true (non-zero), all entries in the
file system tree starting from the basepath down will be returned.
If false, only resources within the specified basepath are returned,
as if the call was a "dir" of that basepath.

Note that totalentries is the total number of entries that would be
available, given the specified basepath and recursive setting, not the
total of all entries in the access control file.

NOTE:  A user which does not have admin privileges will recive
information only about resources for which they have the ability to
control permissions.  Such permission is indicated by the bit
ACCESS_PERM.

Buffer contents on response (format for a single entry):

    Level 0 contains a "struct access_info_0".

    Level 1 contains a "struct access_info_1", followed
        by zero or more "struct access_list" entries.
        The number of such entries is indicated by the
        count field in the access_info_1.  



Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_MORE_DATA
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       user-level security is not running.

-------------------------
14.3  NetAccessGetInfo 

Purpose:  Read access privilege information about a net resource.

unsigned far pascal
NetAccessGetInfo( servername, resource, level, buf, buflen, totalavail )
char far *          servername;     asciz remote server name or NULL if local
char far *          resource;       resource name (see below)
short               level;          level of detail requested; 0, 1
char far *          buf;            returned entry
unsigned short      buflen;         size of buffer
unsigned short far *totalavail;     total size needed for buffer

NOTE:  "resource" must be a fully qualified pathname (including drive
       letter) for file or directory resources, \PIPE\pipename for pipe
       resources, \PRINT\queuename for a spooled print resource or
       \COMM\queuename for character device resources (note that
       the queuename for a COMM resource is in fact the netname
       of its share).

NOTE:  A user may issue this call to a remote server only if the user
has admin privileges, OR the user has permission to modify the access
list of the named resource.  Such permission is indicated by the bit
ACCESS_PERM.

Buffer contents on response:
    Level 0 contains a "struct access_info_0".
    Level 1 contains a "struct access_info_1", followed
        by zero or more "struct access_list" entries.
        The number of such entries is indicated by the
        count field in the access_info_1.

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_ACCESS_DENIED     access denied (doesn't have ACCESS_PERM
                                        or is not an ADMIN)
        NERR_BufTooSmall
        ERROR_MORE_DATA
        NERR_ACFNotLoaded       user-level security is not running.
        NERR_ServerNotStarted   server is not started
        NERR_ACFFileIOFail      fail in accessing database NET.ACC
        NERR_ResourceNotFound   resource not found

-------------------------
14.4  NetAccessSetInfo 

Purpose:  Set access privilege information for a net resource.

unsigned far pascal
NetAccessSetInfo( servername, resource, level, buf, buflen, parmnum )
char far *      servername;         asciz remote server name or NULL if local
char far *      resource;           resource name (see NetAccessGetInfo)
short           level;              level of detail provided; must be 1
char far *      buf;                see below
unsigned short  buflen;             size of buffer
short           parmnum;

Buffer contents on call if parmnum is zero:

    Level 1 contains a "struct access_info_1", followed
        by zero or more "struct access_list" entries.
        The number of such entries is indicated by the
        count field in the access_info_1.

NOTE:  A user may issue this call to a remote server only if the user
has admin privileges, OR the user has permission to modify the access
list of the named resource.  Such permission is indicated by the bit
ACCESS_PERM.  It is quite possible for a user to use this call in a
way that obliterates their own ability to further modify the access
privileges of a resource, by removing the record which entitles them
to have ACCESS_PERM access to it.

Settable fields:

   If using the "parmnum" option, only "attr" is settable.

   If setting the whole buffer (parmnum == 0), "attr", "count", and
   all fields of the access_list structures may be set.  The entire
   current access record including all access_list structures is
   replaced by the entries provided in the buffer.


Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_ACCESS_DENIED     access denied
        NERR_UserNotFound       user name not found
        NERR_ACFNoRoom          out of resource(e.g., memory)
        NERR_ACFTooManyLists    maximum number of access lists exceeded
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       user-level security is not running.
        NERR_ACFFileIOFail      fail in accessing database NET.ACC
        NERR_ResourceNotFound   resource not found

-------------------------
14.5  NetAccessAdd (Admin only) 

Purpose:  Add an access record (ie, define resource and access privileges
          for it)

unsigned far pascal
NetAccessAdd( servername, level, buf, buflen )
char far *      servername;         asciz remote server name or NULL if local
short           level;              must be 1, currently
char far *      buf;                see below
unsigned short  buflen;             size of buffer

Buffer contents on call: "struct access_info_1", followed by zero or
more "struct access_list" entries.  The number of such entries is
indicated by the count field in the access_info_1.

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        NERR_UserNotFound       user name not found
        NERR_ACFNoRoom          out of resource(e.g., memory)
        NERR_ACFTooManyLists    maximum number of access lists exceeded
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       user-level security is not running.
        NERR_ACFFileIOFail      fail in accessing database NET.ACC
        NERR_ResourceExists     resource  already exists

-------------------------
14.6  NetAccessDel (Admin only) 

Purpose:  Delete an access record (ie, remove all access privileges for a
          resource)

unsigned far pascal
NetAccessDel( servername, resource)
char far *  servername;         asciz remote server name or NULL if local
char far *  resource;           resource name (see NetAccessGetInfo)


Returns 0 if successful. Possible error returns:
        NERR_ACFNotLoaded       user-level security is not running.
        NERR_ServerNotStarted   server is not started
        NERR_ACFFileIOFail      fail in accessing database NET.ACC
        NERR_ResourceNotFound   resource not found

-------------------------
14.7  NetAccessCheck 

Purpose:  Check if a user has access to an access record

unsigned far pascal
NetAccessCheck( reserved, uname, resource, operation, result)

char far *  reserved;           reserved must be NULL
char far *  uname;              user name
char far *  resource;           resource name (see NetAccessGetInfo)
unsigned short operation;       operation requested
unsigned short far *result;     0 (permitted) or ERROR_ACCESS_DENIED

NetAccessCheck checks if the user has the specified privilege on the
named resource. The result field
tells if the user has permission to do so. Result
field is meaningful only when the returned status is 0.

Note that the "operation requested" is encoded as a permission
bitmask using the following definitions:

#define ACCESS_READ   0x1
#define ACCESS_WRITE  0x2
#define ACCESS_CREATE 0x4
#define ACCESS_EXEC   0x8
#define ACCESS_DELETE 0x10
#define ACCESS_ATRIB  0x20
#define ACCESS_PERM   0x40

Note that NetAccessCheck emulates the way server checks permission.
If the user's record cannot be found, it will try to use guest account's
instead.

Returns 0 if successful. Possible error returns:
        NERR_ACFNotLoaded       user-level security is not running.
        NERR_ServerNotStarted   server is not started
        NERR_ACFFileIOFail      fail in accessing database NET.ACC
        NERR_UserNotFound       User not found


15.   GROUPS 

These calls deal with groups in the user-level server security system.

Groups can be thought of as a name for a collection of users.  Group
names can be is specifying access permissions, and so provide
a handy way to assign identical permissions to a number of users
without extra work by the administrator.

There is a group called "USERS" to which all normal users and all 
administrators belong.  Only "guest" privilege accounts do not belong
to the "USERS" group.  The members of this special group belong to it
because of their privilege level (USER_PRIV_USER or USER_PRIV_ADMIN),
and you cannot delete users from this group, delete the group itself,
etc.  If you attempt to perform such an operation on this group you
will get the error NERR_SpeGroupOp.


The basic data structure for Group information is:

    struct group_info_0 {
        char      grpi0_name[GNLEN+1];
    };

name            Name of the group.

    
The basic data structure for Group Membership information is:

    struct group_users_info_0 {
        char      grui0_name[UNLEN+1];
    };

name            Name of a user who is a member of the group.

All of these functions should be used with the include file "access.h".

-------------------------
15.1  NetGroupEnum (Admin only) 

Purpose:  Supply information about groups.

unsigned far pascal
NetGroupEnum( servername, level, buf, buflen, entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested; MBZ currently
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_MORE_DATA
        NERR_ACFNotLoaded       User-level security is not running
        NERR_ServerNotStarted   server is not started

-------------------------
15.2  NetGroupAdd (Admin Only) 

Purpose:  Add new group.

unsigned far pascal
NetGroupAdd( servername, level, buf, buflen)
char far *     servername;         asciz remote server name or NULL if local
short          level;              MBZ
char far *     buf;                buffer to return entries in
unsigned short buflen;             size of buffer on call;

NetGroupAdd will fail if the name already is used as a user name.

Contents of buffer on call:
        struct group_info_0

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        NERR_BadUsername        bad formed group name
        NERR_ACFNotLoaded       User-level security is not running
        NERR_ServerNotStarted   server is not started
        NERR_GroupExists        name exists as a group
        NERR_UsersEXists        name exists as a user
        NERR_ACFFileIOFail      fail in accessing database
        NERR_ACFNoRoom          No resource available

-------------------------
15.3  NetGroupDel (Admin Only) 

Purpose:  Remove a group.

unsigned far pascal
NetGroupDel( servername, groupname)
char far *  servername;         asciz remote server name or NULL if local
char far *  groupname;          asciz group name to be deleted

There is a special group called USERS that cannot be removed. Trying to
delete the reserved group name will cause error NERR_SpeGroupOp to be returned.

Returns 0 if successful. Possible error returns:
        NERR_GroupNotFound      Group name not found
        NERR_ACFNotLoaded       User-level security is not running
        NERR_ServerNotStarted   server is not started
        NERR_ACFFileIOFail      fail in accessing database file 
        NERR_SpeGroupOp         invalid operation on reserved group USERS

-------------------------
15.4  NetGroupAddUser (Admin only) 

Purpose:  Add a user to a group.

unsigned far pascal
NetGroupAddUser( servername, groupname, username)
char far *  servername;         asciz remote server name or NULL if local
char far *  groupname;          asciz group name
char far *  username;           asciz user name

There is an automatically maintained group called USERS for which
membership is based on the user's priviledge.  Any user who has
either user or admin priviledge is a member of this special group. 
Trying to add a user to this special group will cause error
NERR_SpeGroupOp to be returned.

Returns 0 if successful. Possible error returns:
        NERR_GroupNotFound      Group name not found
        NERR_UserNotFound       User  name not found
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       User-level security is not running
        NERR_ACFFileIOFail      fail in accessing database file 
        NERR_SpeGroupOp         invalid operation on reserved group USERS
        NERR_UserInGroup        User already in group

-------------------------
15.5  NetGroupDelUser (Admin only) 

Purpose:  remove a user from a group.

unsigned far pascal
NetGroupDelUser( servername, groupname, username)
char far *  servername;         asciz remote server name or NULL if local
char far *  groupname;          asciz group name
char far *  username;           asciz user name

There is an automatically maintained group called USERS for which
membership is based on the user's priviledge.  Any user who has
either user or admin priviledge is a member of this special group. 
Trying delete a user from this special group will cause error
NERR_SpeGroupOp to be returned.

Returns 0 if successful. Possible error returns:
        NERR_GroupNotFound      Group name not found
        NERR_UserNotFound       User  name not found
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       User-level security is not running
        NERR_ACFFileIOFail      fail in accessing database file 
        NERR_SpeGroupOp         invalid operation on reserved group USERS
        NERR_UserNotInGroup     User not in group

-------------------------
15.6  NetGroupGetUsers (Admin only) 

Purpose:  Return information about users who belong to a group.

unsigned far pascal
NetGroupGetUsers( servername, groupname, level, buf, buflen,
                                        entriesread, totalentries )
char far *            servername;     asciz remote server name or NULL if local
char far *            groupname;      asciz groupname
short                 level;          level of detail requested, currently MBZ
char far *            buf;            buffer to return entries in
unsigned short        buflen;         size of buffer on call;
unsigned short far *  entriesread;    # of entries supplied on return
unsigned short far *  totalentries;   total # of entries available

This is the only API in ACCESS which doesn't require user-level security
running.  Note that it may be very expensive to do this call if user-level
security is not running, since the API itself may need to access the
security database.

This is functionally equivalent to an Enum call, since it enumerates
the users in a group.  See the general information in section 1 on
Enum calls.

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct group_users_info_0".

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_MORE_DATA
        NERR_GroupNotFound      Group name not found
        NERR_ACFFileIOFail      fail in accessing database file 
        NERR_ACFNoRoom          out of resource

16.   USERS 

These calls deal with users in the server file security system.  There are
two levels of information:

    struct user_info_0 {
        char           usri0_name[UNLEN+1];
    };

    struct user_info_1 {
        char           usri1_name[UNLEN+1];
        char           usri1_name_pad;
        char           usri1_password[ENCRYPTED_PWLEN];
        long           usri1_password_age;
        unsigned short usri1_priv;
        char far *     usri1_home_dir;
        char far *     usri1_comment;
        unsigned short usri1_flags;
        char far *     usri1_script_path;
    };

name            Name of the user.

password        User's password.  

password_age    Time in seconds since the password was last
                changed.

priv            User's privilege level, may be one of:

                   USER_PRIV_GUEST  0 
                   USER_PRIV_USER   1
                   USER_PRIV_ADMIN  2

home_dir        User's home directory, may be NULL.  Refers to a path on
                this server.

comment         Remark of comment, may contain any text.

flags           Bitmapped as follows:

                  Bit   Mask               Meaning

                   0    UF_SCRIPT          Logon script enabled
                   1    UF_ACCOUNTDISABLE  This account is disabled
                  2-15  <reserved>


script_path     Pathname of user's logon script.  Used by the Logon 
                Server (NetLogon service) during centralized user
                verification.  Points to a file on the server which
                contains a script (.CMD or .PRO) which is loaded when
                the user first logs onto the network.


All of these functions should be used with the include file "access.h".

-------------------------
16.1  NetUserEnum (Admin only) 

Purpose:  Supply information about users

unsigned far pascal
NetUserEnum( servername, level, buf, buflen,
                                        entriesread, totalentries )

char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested; 0 or 1
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct users_info_0".
    Level 1 contains a "struct users_info_1".

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_MORE_DATA
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       User-security is not running.
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC

-------------------------
16.2  NetUserAdd (Admin Only) 

Purpose:  Add new user

unsigned far pascal
NetUserAdd( servername, level, buf, buflen)

char far *      servername;         asciz remote server name or NULL if local
short           level;              must be 1
char far *      buf;                see below
unsigned short  buflen;             size of buffer

Buffer contents on call: "struct user_info_1".

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_INVALID_PARAMETER
        NERR_BufTooSmall        buffer too small
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       User-security is not running.
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC
        NERR_UserExists         User name exists
        NERR_GroupExists        Group name exists
        NERR_ACFNoRoom          No resource available
        NERR_BadUsername        ill-formed user name


-------------------------
16.3  NetUserDel (Admin Only) 

Purpose:  Remove a user

unsigned far pascal
NetUserDel( servername, username)

char far *  servername;         asciz remote server name or NULL if local
char far *  username;           asciz user name to be deleted


Returns 0 if successful. Possible error returns:
        NERR_ACFNotLoaded       User-security is not running.
        NERR_ServerNotStarted   server is not started
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC
        NERR_UserNotFound       Cannot find the user specified

-------------------------
16.4  NetUserGetInfo (Admin only) 

Purpose:  Get user-related information

unsigned far pascal
NetUserGetInfo( servername, username, level, buf, buflen, totalavail)

char far *          servername;     asciz remote server name or NULL if local
char far *          username;       asciz user name to be deleted
short               level;          level of detail requested; 0 or 1
char far *          buf;            buffer to return info in
unsigned short      buflen;         size of buffer on call
unsigned short far *totalavail;     total size needed for buffer

Buffer contents on response:
    Level 0 contains a "struct users_info_0".
    Level 1 contains a "struct users_info_1".

Note that password is not a readable field, and will be empty,
as a null string.  

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        NERR_BufTooSmall
        ERROR_MORE_DATA
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       User-security is not running.
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC
        NERR_UserNotFound       Cannot find the user specified

-------------------------
16.5  NetUserSetInfo (Admin Only) 

Purpose:  Set user-related information

unsigned far pascal
NetUserSetInfo( servername, username, level, buf, buflen, parmnum)

char far *          servername;     asciz remote server name or NULL if local
char far *          username;       asciz user name yo be deleted
short               level;          level of detail provided;  must be 1
char far *          buf;            buffer to return info
unsigned short      buflen;         size of buffer on call
short               parmnum;        which parameter to set

If parameter "parmnum" is zero, Level has to be 1 and buffer must contain
a structure "user_info_1".  

Settable fields include:
        - password
        - priv
        - home_dir
        - comment
        - user_flags
        - script_path

Returns 0 if successful. Possible error returns:
        ERROR_INVALID_LEVEL
        ERROR_INVALID_PARAMETER
        NERR_BufTooSmall
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       User-security is not running.
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC
        NERR_UsersNotFound      user name is not found

-------------------------
16.6  NetUserPasswordSet 

Purpose:  Change password associated with a user.

unsigned far pascal
NetUserPasswordSet( servername, username, oldpasswd, newpasswd )

char far *  servername;         asciz remote server name or NULL if local
char far *  username;           asciz user name
char far *  oldpasswd;          asciz old (current) user password
char far *  newpasswd;          asciz new user password

Password will be set to newpasswd only if oldpasswd matches the current
user password for this user and the newpasswd is not the same as the
oldpasswd.  This call allows users to change their own password
without admin priviledge.

If a user has the admin priviledge and needs to change a user's
password without knowing his old password, he can use NetUserSetInfo
instead.  

Returns 0 if successful. Possible error returns:
        NERR_ServerNotStarted   server is not started
        NERR_ACFNotLoaded       User-security is not running.
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC
        NERR_UsersNotFound      User name not found
        NERR_InvalidPassword    either the oldpasswd doesn't match the current
                                one or the oldpasswd is the same as newpasswd.

-------------------------
16.7  NetUserValidate 

Purpose:  Validate a user with its password

unsigned far pascal
NetUserValidate( reserved, username, password, priv )

char far * reserved;            Must be NULL
char far *  username;           asciz user name
char far *  password;           asciz user password
unsigned short far *  priv;     the user's privilege level

This call checks if a username/password are valid.  If so, the user's
privilege level is returned in priv.

Returns 0 if successful. Possible error returns:

        NERR_ACFNotLoaded       User-security is not running.
        NERR_ServerNotStarted   server is not started
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC
        NERR_UsersNotFound      User name not found
        NERR_InvalidPassword    password doesn't match the current one.

-------------------------
16.8  NetUserGetGroups (Admin only) 

Purpose:  Supply information about a user's group memberships.

unsigned  far pascal
NetUserGetGroups( servername, username, level, buf, buflen,
                                        entriesread, totalentries )
char far *          servername;     asciz remote server name or NULL if local
char far *          username;       asciz username
short               level;          level of detail requested, currently MBZ;
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents on response:

    A "struct group_info_0", repeated "entriesread" times.

This is functionally equivalent to an Enum call, since it enumerates
the groups a user is a member of.  See the general information in
section 1 on Enum calls.

Returns 0 if successful. Possible error returns:

        ERROR_INVALID_LEVEL
        NERR_BufTooSmall
        ERROR_MORE_DATA
        NERR_ACFNotLoaded       User-security is not running.
        NERR_ServerNotStarted   server is not started
        NERR_ACFFileIOFail      Fail in accessing Account database NET.ACC
        NERR_UsersNotFound      User name not found


17.   WORK STATIONS 

These calls deal with the workstation environment (redirector configuration).

    struct wksta_info_0 {
        unsigned short  wki0_reserved_1;
        unsigned long   wki0_reserved_2;
        char far *      wki0_root;
        char far *      wki0_computername;
        char far *      wki0_username;
        char far *      wki0_langroup;
        unsigned char   wki0_ver_major;
        unsigned char   wki0_ver_minor;
        unsigned long   wki0_reserved_3;
        unsigned short  wki0_charwait;
        unsigned long   wki0_chartime;
        unsigned short  wki0_charcount;
        unsigned short  wki0_reserved_4;
        unsigned short  wki0_reserved_5;
        unsigned short  wki0_keepconn;
        unsigned short  wki0_keepsearch;
        unsigned short  wki0_maxthreads;
        unsigned short  wki0_maxcmds;
        unsigned short  wki0_maxpipes;
        unsigned short  wki0_numworkbuf;
        unsigned short  wki0_sizworkbuf;
        unsigned short  wki0_maxwrkcache;
        unsigned short  wki0_sesstimeout;
        unsigned short  wki0_sizerror;
        unsigned short  wki0_numalerts;
        unsigned short  wki0_numservices;
        unsigned short  wki0_errlogsz;
        unsigned short  wki0_printbuftime;
        unsigned short  wki0_numcharbuf;
        unsigned short  wki0_sizcharbuf;
        char far *      wki0_logon_server;
        char far *      wki0_wrkheuristics;
        unsigned short  wki0_mailslots;
    };


NOTE:  Most of these fields are explained in more detail in the
Lan Manager Administrator's Reference, Appendix A.

root                Ptr to ASCIZ string, path to LANMAN root.

computername        Ptr to ASCIZ string, machine name.

username            Ptr to ASCIZ string, current user name.

langroup            Ptr to ASCIZ string, lan group (used internally).

ver_major           LANMAN version, major portion.

ver_minor           LANMAN version, minor portion.

charwait            Amount of time, in seconds, that workstation will
                     wait for a requested remote communication device
                     to be available.

chartime            Time in msec that workstation will collect data to
                     send to a remote communicaton device.

charcount           Number of bytes that that workstation will collect
                     to send to a remote communicaton device.

keepconn            Time to maintain an inactive connection.

keepsearch          Time to maintain an inactive search.

maxthreads          Maximum number of threads that can use the network.

maxcmds             Maxmimum number of NetBios commands that can be
                     sent simultaneously by the redirector.  

maxpipes            Maxmimum number of named pipes.

numworkbuf          Number of workstation internal buffers.

sizworkbuf          Size of workstation internal buffers.

maxwrkcache         Maximum size of large-transfer buffer pool.

sesstimeout         Time in seconds to wait before disconnecting a
                     session from a server which is not responding.

sizerror            Size of the workstation internal buffer.

numalerts           Maximum number of clients that may recieve alerts.
                    Note that each mailslot or semaphore registered
                    via NetAlertStart is a different "client", and
                    also note that the Alerter Service consumes at 
                    least three of these slots when it is running.

numservices         Maximum number of services installed at one time.

errlogsz            Maximum error log file size.

printbuftime        Time (in seconds) after which inactive compatibity-
                     mode print jobs are closed.

numcharbuf          Number of character pipe buffers and device buffers.

sizcharbuf          Size of character pipe buffers and device buffers.

logon_server        Ptr to ASCIZ string, Logon server name.  Blank
                     means none, \\* means use any available, otherwise
                     is name of logon server to use.  See NetLogon
                     service.

wrkheuristics       String of option flags controlling workstation
                     performance heuristics as defined below:

                        workheuristics = 11111111212111111000011
                                         abcdefghijklmnopqrstuvw

                     Where not otherwise defined, value 0 means turn off
                     a feature, 1 means turn it on.  The result of using
                     values other than those listed (or 0/1 where no values
                     are listed) is undefined.

                         a: Request an "Opportunistic" lock of files.  This
                            allows a files to be buffered if we are the only
                            ones haveing the file open.  The server will
                            notify us if a second workstation opens the file
                            allowing us to flush any data before granting the
                            second open thus "breaking" our "opportunistic 
                            lock".

                         b: Do special handling of batch files for 
                            performance. This eliminates some of the open,
                            seek, read, close per line processing of ".cmd"
                            and ".bat" files.

                         c: Do Async Unlock (and async WriteUnlock).

                         d: Do Async Close (and async WriteClose).

                         e: Buffer named pipes and char devices.

                         f: Do LockRead and WriteUnlock.

                         g: Do "Open And Read".

                         h: Do readahead to sector boundry.

                         i: Use chain send NetBios NCB: 
                              0 = never 
                              1 = do if server buf larger
                              2 = always (to avoid copy)

                         j: Buffer Small read/write requests 
                            (read full buffer when less asked for and wait 
                            fill buffer before write).

                         k: Buffer Mode (assuming shared access ok):
                              0 - always read bufsize if request < bufize
                              1 - if file open read/write
                              2 - only if reading/writing sequential

                         l: Use RAW read/write protocols.

                         m: Use Large RAW read ahead buffer.

                         n: Use Large RAW Write Behind buffer.

                         o: Use Read MPX protocols.

                         p: Use Write MPX protocols.

                         q: Use Big Buffer for large core reads.

                         r: Use same size small RA or to sector boundry.

                         s: Use same size small WB or to sector boundry.

                         t: Use max 512 byte data xfer to/from core.

                         u: Flush Control, controls how flushing is done
                            for *every* call to DosBufReset or DosClose.

                             0 = Only flush files/devices opened by caller.
                                   Spin until flushed on pipes/devices.
                             1 = Only flush files/devices opened by caller.
                                   Only try once to flush pipes/devices.
                             2 = Flush all files and all short term
                                 pipe/device I/O.
                                   Spin until flushed on pipes/devices.
                             3 = Flush all files and all short term
                                 pipe/device I/O.
                                   Only try once to flush pipes/devices.
                             4 = Flush all files and pipe/device I/O.
                                   Spin until flushed on pipes/devices.
                             5 = Flush all files and pipe/device I/O.
                                   Only try once to flush pipes/devices.

                         v: Use Encryption if server supports it.

                         w: Controls degree of error sensitivity.
                              0 = Log every occurance of a given error.
                              1 = Only log some occurances of a given error.


All of these functions should be used with the include file "wksta.h".

-------------------
17.1  NetWkstaGetInfo 

Purpose: Gets information about the configuration of the
         local workstation.

unsigned far pascal
NetWkstaGetInfo(servername, level, buffer, buflen, totalavail)
char far *          servername;     asciz remote server name or NULL if local
short               level;          MBZ
char far *          buffer;         Buffer for returned data
unsigned short      buflen;         Size of given buffer/returned data
unsigned short far *totalavail;     total size of available information

The returned data buffer returns a "struct wksta_info_0".


Returns 0 if successful. Possible error returns:

      ERROR_INVALID_PARAMETER
      ERROR_INVALID_LEVEL
      NERR_BufTooSmall
      NERR_NetNotStarted


-------------------------
17.2  NetWkstaSetInfo (Admin Only) 

Purpose: Sets information about the configuration of the
         local workstation.

unsigned far pascal
NetWkstaSetInfo(servername, level, buffer, buflen, parmnum)
char far *      servername;     asciz remote server name or NULL if local
short           level;          MBZ
char far *      buffer;         Buffer for passed data
unsigned short  buflen;         Size of given buffer
short           parmnum;        which parameter to set

The buffer on call is a "struct wksta_info_0" if parmnum is zero.

Settable fields are:

    - charwait
    - chartime
    - charcount
    - errlogsz
    - printbuftime
    - wrkheuristics

Returns 0 if successful. Possible error returns:

      ERROR_INVALID_PARAMETER
      ERROR_INVALID_LEVEL
      NERR_BufTooSmall
      NERR_NetNotStarted

--------------------
17.3  NetWkstaSetUID (Admin Only) 

Purpose:  Set workstation user ID

unsigned far pascal
NetWkstaSetUID ( server, username, password, parms, ucond )
char far *    servername;       remote server name of NULL if local
char far *    username;         asciz user name
char far *    password;         asciz user password
char far *    parms;            optional OEM-defined parameter string
unsigned short ucond;           See below


This routine logs a user onto the network and configures the user's
workstation with username and user ID information.  

If a user is already logged on at the workstation (user ID already in
effect) NetWkstaSetUID will act depending on ucond.  

The password given here becomes the machine's default password,
and is used whenever the workstation attempts to use a remote
resource.

WARNING:  Use ucond values above 0 with extreme care.

        0:  Fails if anything but dormat connections exist.
            Otherwise drops all dormant connections and succeeds.

        1:  Fails if any connections are active or in use as a
            process' current drive.  Otherwise drops all dormant
            or inactive connections and succeeds.

        2:  Fails if any connection is used by a process as a
            current drive.  Otherwise closes files on active
            connections, drops all connections, and succeeds.

        3:  Forces all disconnections, always succeeds.  

NetWkstaSetUID uses NetWkstaLogon, NetWkstaRelogon, NetWkstaInit,
NetWkstaReinit, and NetWkstaLogoff to perform actual (network
dependent) logon/logoff processing.  The OEM-defined parms string is
passed unchanged to NetWkstaLogon and NetWkstaRelogon for use by
those routines.

Returns 0 if successful. Possible error returns:

                All Times

    NERR_ActiveConns            Active Connections exist, SetUserName
                                  not allowed.  See explanation of ucond
                                  parameter above, for the circumstances
                                  which will cause this error.
    ERROR_INVALID_FUNCTION      Function is not allowed at this time, might
                                  be in use by another process.

                During Logoff

    NERR_NotLoggedOn            No user currently logged on.
    NERR_UnableToDelName        Couldn't delete messaging name corresponding
                                  to the username.
    NERR_UnableToDelName_W      Couldn't delete messaging name corresponding
                                  to the username;  this is a warning level
                                  error.

                During Logon

    NERR_AlreadyLoggedOn        User is currently logged in.
    NERR_UnableToAddName        Unable to add messageing name corresponding
                                  to the username.
    NERR_UnableToAddName_W      Unable to add messageing name corresponding
                                  to the username;  this is a warning level
                                  error.
    NERR_LogonScriptError       An error occurred while loading/executing the 
                                  logon script.  This is not fatal to the
                                  logon procedure.
    NERR_CentralLogonFailed     Unable to use the resources provided for 
                                  centralized logon.  User may not have a
                                  valid account on the logon server.
    NERR_LogonServerNotFound    Unable to find logon server




18.   REDIRECT / USE 

These calls deal using and unusing network resources, and mapping
network resources them to local device names.  

Note that network resources can be used without mapping them to local
devices.  These are called "UNC-style" uses; such resources are
referenced using their fully qualified network names, as in
\\servername\resourcename, as opposed to referencing them via a
redirected device name.


    struct use_info_0 {
        char            ui0_local[DEVLEN+1];
        char            ui0_pad_1;
        char far *      ui0_remote;
    };

    struct use_info_1 {
        char            ui1_local[DEVLEN+1];
        char            ui1_pad_1;
        char far *      ui1_remote;
        char far *      ui1_password;
        unsigned short  ui1_status;
        short           ui1_asg_type;
        unsigned short  ui1_refcount;
        unsigned short  ui1_usecount;
    };

local           Local device name, which is mapped to the network resource.
                If no local device is mapped, this will be a null string.

remote          The remote resource to which is in use.  This will
                be some form of remote pathname.  In this release of
                Lan Manager, it will be of the form \\SERVER\RESOURCE.

password        Used only by NetUseAdd.  Password to use when attempted to
                connect to the resource.  See NetUseAdd for more
                information.

status          Current status of the connection to the remote resource.

                  USE_OK        0       Noromal status
                  USE_PAUSED    1       Connection paused by local wksta.
                                          (see Workstation Service for
                                           more info on pausing redirction)
                  USE_SESSLOST  2       Disconnected.
                  USE_NETERR    3       Network error.
                  USE_CONN      4       Connection being made.
                  USE_RECONN    5       Reconnection being made.


asg_type        Type of resource this connection is to.

                  USE_DISKDEV   0       Disk / file system
                  USE_SPOOLDEV  1       Spooled print queue
                  USE_CHARDEV   2       Character device queue
                  USE_IPC       3       IPC connection

refcount        Count of all open handles to files, devices, etc., that
                reside on the remote resource.

usecount        Count of all uses, explicit and implicit, to this
                resource from this machine.

All of these functions should be used with the include file "use.h".


NOTE:  The NetUse APIs deal with connections between a client (usually
a workstation) and a server.  Since these APIs can also be used remotely,
there is potential for confusion.

The servername paramater is used only for remote administration of 
a server.  It is used when you want to make or break connections
FROM THAT SERVER to ANOTHER SERVER, not when you want to connect
the local machine to something.

Example 1:  using NetUseAdd to make a connection from the local
            machine to a server.


        struct use_info_1 u;

        strcpy ( u.ui1_local, "J:");
        u.ui1_remote = "\\S1\C_DRIVE";
        u.ui1_password = NULL;
        u.ui1_asg_type = USE_DISKDEV;

        NetUseAdd ( NULL, 1, &u, sizeof(u));


         local machine                    server S1


        +--------+   connection      +------------------+
        |        |                   |                  |
        |    J: ==================>  |  share 'C_DRIVE' |
        |        |                   |                  |
        +--------+                   +------------------+


Example 2:  using NetUseAdd to make a connection on behalf of a
            remote server (requires Admin privledge).  Note that
            the only difference from Example 1, is that the first
            parameter to NetUSeAdd is "\\S2", not NULL.


        struct use_info_1 u;

        strcpy ( u.ui1_local, "J:");
        u.ui1_remote = "\\S1\C_DRIVE";
        u.ui1_password = NULL;
        u.ui1_asg_type = USE_DISKDEV;

        NetUseAdd ( "\\S2", 1, &u, sizeof(u));


        local machine       server s2             server S1

        +--------+         +--------+           +------------------+
        |        |         |        |           |                  |
        |        |         |    J: ==========>  |  share 'C_DRIVE' |
        |        |         |        |           |                  |
        +--------+         +--------+           +------------------+
            \               /
             \_____________/

                API executed 
                remotely to \\S2



-------------------------
18.1  NetUseEnum (Admin only) 

Purpose: Enumerate all currently redirected disks and character
         devices on the workstation, as well as all UNC (deviceless)
         resource uses.

unsigned far pascal
NetUseEnum(servername, level, buf, buflen, entriesread, totalentries)
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of information to be returned
char far *          buf;            buffer to contain returned info
unsigned short      buflen;         number of bytes available in buffer
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available


Buffer contents on response (format for a single entry):

    Level 0 contains a "struct use_info_0".
    Level 1 contains a "struct use_info_1"  

Note that the password field is always nul string in returned entries.
This is a security feature.


Returns: 0 if successful. Possible error returns:

    ERROR_INVALID_LEVEL
    ERROR_MORE_DATA

-------------------------
18.2  NetUseAdd (Admin only) 

Purpose: Redirect a local disk or character device to a shared resource
         on a remote server.  If the device name is NULL, it makes a
         deviceless connection.

unsigned far pascal
NetUseAdd(servername, level, buffer, buflen)
char far *      servername;     asciz remote server name or NULL if local
short           level;          Must be 1 in current implementation
char far *      buffer;
unsigned short  buflen;

Information in buffer on call:
    Level 1 contains a "struct use_info_1"


The following fields from the structure do not apply and are ignored:

        status
        refcount
        usecount


The password field has the following meanings:

        A NULL password pointer means use the default machine password.
        This machine password is set using NetWkstaSetUID, i.e. when
        the user logs in using the "NET LOGON" command.

        A pointer to a null string means use NO PASSWORD.  The connection
        will be attempted without any password.

        A pointer to any other string uses that string as the password
        when attempting the connection.


A user may have any number of connections to the same resource.  Each
connection will succeed.  For example, if a UNC redirection already
exists which matches the attempted redirection, the use count will be
incremented, and the call will succeed.  As another exmaple, a user
can redirect both drives X: and Y: to the same resource.  Each explicit
connect (i.e. eacn redirection added via NetUseAdd) must be deleted
by an explicit call to NetUseDel.

A device may not be redirected more than once.  For example, if drive 
E: is redirected to \\SERVER\DISK, that redirection must be broken
via NetUseDel before E: may be redirected to \\SERVER\DISK2 or to
\\OTHERSERVER\DISK.

The "asg_type" field indicates what sort of device to use resource as.
It may be any of the values listed under "asg_type" above, or may
be set to USE_WILDCARD (-1), *ONLY* for a connection with a null local
device.  A connection that maps a local device to the resource MUST
use the appropriate, specific value for asg_type, selected from the
values listed above.


Returns: 0 if successful. Possible error returns:

    ERROR_INVALID_LEVEL         Parameter "level" is illegal. It must be 1.

    ERROR_INVALID_PARAMETER     One of the fields in the buffer is bad.

    ERROR_BAD_NET_NAME          The net name given is not shared at the
                                  server given.  Example, if you gave
                                  \\SERVER\PRINTER as the remote name,
                                  this error means that \\SERVER has no
                                  share named PRINTER.

    ERROR_INVALID_PASSWORD      The password provided was wrong.  If you
                                  provided a NULL pointer, it means that
                                  the default password (givne when the user
                                  logged in via NetWkstaSetUID) was wrong
                                  for this share or server.

    ERROR_ALREADY_ASSIGNED      The device name given is already redirected.

    ERROR_ACCESS_DENIED         Request of Print or char Redirection is 
                                 disallowed due to service being paused.
                                Remote request does not have admin priv

    ERROR_BAD_DEV_TYPE          Bad device type field

    ERROR_NOT_SUPPORTED         Bad device type field

    NERR_BufTooSmall            Buffer too small for use_info_1 structure.

    NERR_BadAsgType             The given value for ui1_asg_type is invalid.

    NERR_LOCALDRIVE             The device name given is in use locally


-------------------------
18.3  NetUseDel (Admin only) 

Purpose: Cancel the redirection of a local device, or cancels
         a UNC-oriented deviceless use.

unsigned far pascal
NetUseDel(servername, usename, uncond)
char far *  servername;     asciz remote server name or NULL if local
char far *  usename;        Local redirected device name or remote resource
unsigned short uncond;      0, 1, or 2

The usename may be either a device name or a UNC name.  

When the usename specified in the NetUseDel call is a device, the
device is dis-associated from the remote resource.  If there are open
files handles referencing the device, the device will be
dis-associated from the remote resource only if the ucond flag is set
to 2.  A disk device can not be dis-associated from a remote resource
if some process has the device as its current drive.

The effect of the ucond flag when the usename is a UNC name are:  If
the uncond parameter is 0, deleting a use decrements the use count. 
However, this will not be permitted if the use count would become
zero with the ref count still nonzero.  A nonzero ref count indicates
that there are open files or other I/O activity pending against the
redirected resource.  

If the uncond parameter is 1, then the delete will attempt to set the
use count to zero regardless of the current value.  This will fail if
the ref count is nonzero.  

If the uncond parameter is 2, then the use is deleted unconditionally.
Any open files are closed and pending I/O activity cancelled.

Returns: 0 if successful. Possible error returns:


    ERROR_INVALID_PARAMETER     Bad ucond parameter, must be {0,1,2}.

    ERROR_INVALID_DRIVE         requested Drive macro not found

    ERROR_BAD_NET_NAME          The Redirection name specified is invalid

    ERROR_PROTECTION_VIOLATION  The buffer passed into the IOCTL is smaller than
                                  required by the IOCTL

    ERROR_ACCESS_DENIED         Request of Print or char Redirection is disallowed
                                  due to service being paused
                                Remote request does not have admin priv

    ERROR_BAD_DEV_TYPE          Bad device type field

    ERROR_NOT_SUPPORTED         Bad device type field

    NERR_DevInUse               Open Files on this connection, or Drive is
                                  current drive of some process

    NERR_OpenFiles              Open Files exist for this device

    NERR_NoSuchUNCRedir         A delete was attempting using the remote
                                  name of a redirection.  This is valid
                                  only for UNC-style connections.  A
                                  device-style connection must be deleted
                                  using the local device name.



-------------------------
18.4  NetUseGetInfo (Admin only) 

Purpose: Get information about a single use of a remote resource.

unsigned far pascal
NetUseGetInfo(servername, usename, level, buffer, buflen, totalavail)

char far *          servername;     asciz remote server name or NULL if local
char far *          usename;        Name of local device or remote name
short               level;          level of information to be returned
char far *          buffer;         Buffer for returned data
unsigned short      buflen;         Size of given buffer
unsigned short far *totalavail;     total size needed for buffer

The redirection is specified as per the NetUseDel call above.

Information in buffer on return:
    Level 0 contains a "struct use_info_0".
    Level 1 contains a "struct use_info_1"  (password field is nul string).

Returns: 0 if successful. Possible error returns:

    ERROR_INVALID_LEVEL         Parameter "level" has illegal value, must
                                  be {0,1}.

    ERROR_INVALID_PARAMETER     Usename is invalid or poorly formed.

    NERR_UseNotFound            No such redirection.

    NERR_BufTooSmall
    ERROR_MORE_DATA


19.   PRINT QUEUES 

Print queues accept print jobs from applications, queue them, and
print them on one or more devices, which are known as "print 
destinations".

For related information, see the DosPrintJob and DosPrintDest APIs.



Print Queue Data Structure:

   struct PRINTQ {
      char              prq_name[QNLEN+1];
      char              prq_pad;
      unsigned short    prq_priority;
      unsigned short    prq_starttime;
      unsigned short    prq_untiltime;
      char far *        prq_separator;
      char far *        prq_processor;
      char far *        prq_destinations;
      char far *        prq_parms;
      char far *        prq_comment;
      unsigned short    prq_status;
      unsigned short    prq_jobcount;
   };


name            The name of the print queue.

priority        Priority of the queue, from 1 (high) to 9 (low).  The
                priority of a queue is used to arbitrate access to
                print destinations.  Where more that one queue attempts
                to submit print jobs to a destination, the higher-priority
                queue takes precedence.

starttime       Time at which print queue becomes active.  This time is
                a representation of a time from 0:0  (midnight) to 23:59
                in minutes;  e.g. 1:00 would be 60.  The print queue
                will print from "starttime" until "untiltime" each day.
                Setting starttime to untiltime will make queue active
                continuously throughout the day.

untiltime       See starttime above.

separator       ASCIZ path name of a file which contains formatting
                information for the page(s) to separate print jobs.
                The meta language that describes the format of the
                separator page is the same as in MS-NET.

processor       ASCIZ path name of a .EXE file that will be invoked
                when the print job in the named queue is scheduled
                to print. For more information, see the technical note
                on how to write a print processor.

destinations    A list of devices, separated by a space, to which jobs from
                this queue will be sent.  One queue can print to multiple
                destinations, with each job being sent to the next available
                destination.  Likewise, a destination may be used by
                multiple queues -- see "priority" above.

parms           An implementation-defined parameter string. 

comment         An optional text string describing the queue, for
                example:  "High-Priority Laser Printer Jobs".

status          the status of  print queue
                = 0,    queue active
                = 1,    queue paused
                = 2,    queue error
                = 3,    queue pending delete.

jobcount        Current count of outstanding print jobs in the queue.
                

Note:  the format of the implementation defined parms should be
PARM=VALUE, with a single space separating each keyword/value pair.  The
following standard keyword parameters are defined:

1. TYPES=X, where X is one or more spool file data type names separated by
   commas, e.g., TYPES=IBM_Q_STD or TYPES=IBM_Q_STD,IBM_Q_RAW.  An application
   can check for this parameter to determine which queue(s) can handle
   printing of a given (meta)file format.  Wildcards are allowed in data type
   names (e.g, IBMQ*).  The first data type in the TYPES list is the default
   for the queue.  A print job that is submitted with a null data type will be
   assumed to be of this type.  A print job with a non-null data type will be
   refused if the target queue does not hava a matching data type in its
   TYPES= parameter.

2. EJECT=X, where X is "YES", "NO", or "AUTO".

   EJECT=YES           Always issue formfeed at end of job
   EJECT=NO            Don't issue formfeed at end of job
   EJECT=AUTO          Issue formfeed depending on print data

   The default value is AUTO if EJECT= is not specified.

   The heuristic for AUTO eject is to issue a formfeed only if there
   is no formfeed within the last 64 bytes of the print stream, or if
   the last such formfeed is followed by any character(s) greater than
   0x20.  Formfeeds that are one or two characters after an ESC character
   are ignored for the sake of these checks.

   Note that the processing of the EJECT= option is the responsibility
   of the print queue processor program.  The LAN Manager default
   printing logic behaves as described above when no queue processor
   is specified for a given print queue.  If a queue processor is
   specified, however, the processor must recognize and handle this
   argument.  (See item 82 below).

These calls should include "spool.h".

-------------------------
19.1  DosPrintQEnum 

Purpose: Enumerate all print queues on a given server.

unsigned far pascal
DosPrintQEnum(servername, level, buf, buflen, entriesread, totalentries)
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested; 0, 1, or 2
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents in the response:

    level 0 contains:
        char[QNLEN+1][entriesread]             array of queue names

    level 1 contains:
        PRINTQ[entriesread]                  array of PRINTQ structures

    level 2 contains:

        An array of PRINTQ structures, where each structure is
        followed by an array of PRINTJOB structures (one job structure
        for each job in the print queue).  This returns from the single API
        call comprehensive information about all queues and all jobs in 
        those queues.

        See the DosPrintJob APIs and/or spool.h for the PRINTJOB
        structure.


Returns: 0 if successful. Possible errors:

        ERROR_INVALID_LEVEL
        ERROR_MORE_DATA
        NERR_SpoolerNotLoaded
        NERR_BufTooSmall


-------------------------
19.2  DosPrintQGetInfo 

Purpose: Get the current information about a queue.

unsigned far pascal
DosPrintQGetInfo(servername, queuename, level, buf, buflen, totalavail)
char far *          servername;     asciz remote server name or NULL if local
char far *          queuename;      asciz queue name
short               level;          level of info requested
char far *          buf;            return buffer
unsigned short      buflen;         length of buffer
unsigned short far *totalavail;     total size needed for buffer

On return, buffer contains:
    Level 0:    char[QNLEN+1] queue name
    Level 1:    One PRINTQ structure, up to buflen.
    Level 2:    One PRINTQ structure, followed by an array of PRINTJOB


Returns: 0 if successful. Possible errors:

        ERROR_INVALID_LEVEL
        ERROR_MORE_DATA
        NERR_BufTooSmall
        NERR_SpoolerNotLoaded
        NERR_QNotFound

-------------------------
19.3  DosPrintQSetInfo (Admin only) 

Purpose: Changes the configuration of the queue.

unsigned far pascal
DosPrintQSetInfo(servername, queuename, level, buf, buflen, parmnum)
char far *      servername;        asciz remote server name or NULL if local
char far *      queuename;         asciz queue name
short           level;             level of info provided (must be 1 currently)
char far *      buf;               buffer of information
unsigned short  buflen;            length of buf
short           parmnum;           which parameter to set

Buffer contents on call if parmnum is zero:
        Level 0:        Illegal
        Level 1:        PRINTQ structure
        Level 2:        Illegal

Settable PRINTQ parameters are
        priority,
        starttime,
        untiltime,
        separator,
        destinations,
        processor,
        parms,
        comment

Returns: 0 if successful. Possible errors:

        ERROR_INVALID_LEVEL
        ERROR_INVALID_PARAMETER
        NERR_BufTooSmall
        NERR_QNotFound
        NERR_InvalidParmnum
        NERR_SpoolerNotLoaded
        NERR_InvalidParms
        NERR_SpoolNoMemory
        NERR_RedirectedPath
        NERR_CommDevInUse
        NERR_BadDev
        NERR_DestNoRoom

-------------------------
19.4  DosPrintQAdd (Admin only) 

Purpose:  Add a print queue to the server.

unsigned far pascal
DosPrintQAdd(servername, level, buf, buflen)
char far *      servername;        asciz remote server name or NULL if local
short           level;             levle of information
char far *      buf;               buffer of information
unsigned short  buflen;            length of buf

Level must be 1 in this implementation.

On entry, if the named queue does not exist, it will be created.
If the queue exists, but has been marked for deletion, it will
be undeleted.

The buffer contains a PRINTQ structure (level 1).  PRINTQ parameters that
can be set at add time are priority, starttime, untiltime, separator,
processor, destinations, parms, and comment.  Other parameters are
ignored (does not matter what they contain).

Returns: 0 if successful. Possible errors:

        ERROR_INVALID_LEVEL
        NERR_BufTooSmall
        NERR_QExists
        NERR_QNoRoom
        NERR_DestNoRoom
        NERR_SpoolNoMemory
        NERR_SpoolerNotLoaded
        NERR_InvalidParms
        NERR_SpoolNoMemory
        NERR_RedirectedPath
        NERR_CommDevInUse
        NERR_BadDev
        NERR_DestNoRoom


-------------------------
19.5  DosPrintQDel (Admin only) 

Purpose: Delete a queue from a server.

unsigned far pascal
DosPrintQDel(servername, queuename)
char far *    servername;        asciz remote server name or NULL if local
char far *    queuename;         asciz queue name

On entry, if there are any jobs in the queue, the queue will be marked
"pending delete".  The Spool Manager will delete the queue when it is
empty.  Otherwise, the queue and the associated spool directory will be
deleted immediately.

Returns: 0 if successful. Possible errors:

        NERR_QNotFound
        NERR_SpoolerNotLoaded


-------------------------
19.6  DosPrintQPurge (Admin only) 

Purpose: Purge all print jobs in the  queue.

unsigned far pascal
DosPrintQDel(servername, queuename)
char far *    servername;        asciz remote server name or NULL if local
char far *    queuename;         asciz queue name

This will purge all print jobs in the named queue.  Note that an alert
will not be raised for each deletion of the job.

Returns: 0 if successful. Possible errors:

        NERR_QNotFound
        NERR_SpoolerNotLoaded


-------------------------
19.7  DosPrintQPause (Admin only) 

Purpose: Pause a specific print queue (hold scheduling of jobs).

unsigned far pascal
DosPrintQPause(servername, queuename)
char far *    servername;        asciz remote server name or NULL if local
char far *    queuename;         asciz queue name

Pausing a queue will prevent jobs from being scheduled for printing
but won't affect jobs from this queue that are already printing.

Returns: 0 if successful. Possible errors:

        NERR_QNotFound
        NERR_SpoolerNotLoaded


-------------------------
19.8  DosPrintQContinue 

Purpose: Continue a paused queue on a server (allow scheduling).

unsigned far pascal
DosPrintQContinue(servername, queuename)
char far *    servername;         asciz remote server name or NULL if local
char far *    queuename;          asciz queue name

Returns: 0 if successful. Possible errors:

        NERR_QNotFound
        NERR_SpoolerNotLoaded


20.   PRINT JOBS 

Print Job Structure:

    struct PRINTJOB {
       unsigned short   prjob_id;
       char             prjob_username[UNLEN+1];
       char             prjob_notifyname[MNLEN+1];
       char             prjob_datatype[DTLEN+1];
       char             prjob_pad;
       char far *       prjob_parms;
       unsigned short   prjob_position;
       unsigned short   prjob_status;
       char far *       prjob_status_string;
       unsigned long    prjob_submitted;
       unsigned long    prjob_size;
       char far *       prjob_comment;
    };


id              A number uniqiely identifying a job on this server.  These
                numbers are on a PER SERVER basis, so that two jobs on a
                server will never have the same job ID, even if submitted
                to different queues.

username        User name of submitter.

notifyname      Message name to be notified about print status.

datatype        see parms in PRINTQ structure about TYPES=XX.

parms           Implementation defined string.

position        Position of the job in the queue.  1 = next to print.

status          A bitmapped field giving the current status of the job.

                 Bit(s)   Mask

                  0,1     PRJOB_QSTATUS      0x3        Queueing status
                  2-8     PRJOB_DEVSTATUS    0x1fc      Destination status
                   2      PRJOB_COMPLETE     0x4        Complete if set
                   3      PRJOB_INTERV       0x8        Intervention required
                   4      PRJOB_ERROR        0x10       Error on destination
                   5      PRJOB_DESTOFFLINE  0x20       Destination offline
                   6      PRJOB_DESTPAUSED   0x40       Destination paused
                   7      PRJOB_NOTIFY       0x80       Set by print processor,
                                                        indicate if a printing
                                                        alert should be raised.
                   8      PRJOB_DESTNOPAPER  0x100      out of paper.
                 9-14     <reserved>
                  15      PRJOB_DELETED      0x8000     used by spooler to 
                                                        inform alerter if the
                                                        alert is raised because
                                                        the job is being deleted

                Bits (0,1) may have the following values:

                   PRJOB_QS_QUEUED    0    Job is queued
                   PRJOB_QS_PAUSED    1    Job is paused in queue
                   PRJOB_QS_SPOOLING  2    Job is spooling (being created)
                   PRJOB_QS_PRINTING  3    Job is printing


status_string   A text (ASCIZ) string explaining the current status of
                the printer;  this is  set by the print processor
                to provide extra information about the status. The default
                print processor that is built in the spooler will always
                set this field to NULL.

submitted       Time when the job is submitted.  See "timestamps" in
                Chapter 1.

size            Print job size in bytes. 

comment         Optional ASCIZ comment or remark about the print job.


These calls should include "spool.h".

-------------------------
20.1  DosPrintJobEnum 

Purpose: Enumerate all jobs in a given print queue on a given server.

unsigned far pascal
DosPrintJobEnum(servername,queuename,level,buf,buflen,entriesread,totalentries)
char far *          servername;     asciz remote server name or NULL if local
char far *          queuename;      asciz queue name
short               level;          level of detail requested; 0 or 1
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents in the response:

    Level 0 contains:
        unsigned short [entriesread]         array of job ids

    Level 1 contains:
        PRINTJOB[entriesread]                array of PRINTJOB structures

NOTE:  Supplying a buflen of zero can be used to get the number of total
       entries available without reading any actual data.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_LEVEL
        ERROR_MORE_DATA
        NERR_BufTooSmall
        NERR_QNotFound
        NERR_SpoolerNotLoaded


-------------------------
20.2  DosPrintJobGetInfo 

Purpose: Get information about a specified print job.

unsigned far pascal
DosPrintJobGetInfo(servername, jobid, level, buf, buflen, totalavail)
char far *          servername;     asciz remote server name or NULL if local
unsigned short      jobid;          job identifier
short               level;          level of info requested
char far *          buf;            buffer of information
unsigned short      buflen;         length of buf
unsigned short far *totalavail;     total size needed for buffer

On return, the buffer contains:
    Level 0:    Job Id
    Level 1:    A PRINTJOB structure, up to buflen.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_LEVEL
        NERR_JobNotFound
        NERR_SpoolerNotLoaded
        ERROR_MORE_DATA
        NERR_BufTooSmall


-------------------------
20.3  DosPrintJobSetInfo 

Purpose: Changes parameters of a given job.

unsigned far pascal
DosPrintJobSetInfo(servername, jobid, level, buf, buflen, parmnum)
char far *      servername;         asciz remote server name or NULL if local
unsigned short  jobid;              job identifier
short           level;              must be 1
char far *      buf;                buffer of information
unsigned short  buflen;             length of buf
short           parmnum             which parameter to set

If multiple parameters are to be set, parmnum is 0 and the buffer
contains a PRINTJOB structure.

Settable PRINTJOB parameters are
        position
        parms
        comment
        notifyname
        datatype

The value of position is interpreted as

        position == 0 means don't change postion
        position == 1  means put the job first in queue
        position == n means put job nth in queue
        position greater than number of jobs in queue means put job last

Note:   Only the user who owns the job and the administrator have the
        ablility to update a job.  In addition, the user only can only
        move his position in the queue down.  An administrator is the
        only one allowed to move a jobs position up in the queue.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_LEVEL
        NERR_BufTooSmall
        NERR_JobNotFound
        NERR_InvalidParmnum
        NERR_SpoolerNotLoaded
        NERR_JobInvalidState
        NERR_SpoolNoMemory

-------------------------
20.4  DosPrintJobAdd 

Purpose: Creates a spool file and returns its name.

unsigned far pascal
DosPrintJobAdd(servername, queuename, buf, buflen, spoolname, jobid)
char far *          servername;     asciz remote server name or NULL if local
char far *          queuename;      asciz queue name
char far *          buf;            buffer for writing the filename
unsigned short      buflen;         length of buf
char far *          spoolname;      returned pathname of spool file
unsigned short far *jobid;          returned job id for print job


The buffer contains a PRINTJOB structure.  PRINTJOB parameters that
can be specified at add time include username, notifyname, datatype,
comment, and parms.  Other parameters are ignored (does not matter what they
contain).

The spoolname pointer must point to a user buffer of at least
PATHLEN+1 bytes.  Upon successful return the spoolname buffer is
filled in with the full pathname of a spool file (this may be a
remote file).

The caller is responsible for opening the file, writing the
information to be spooled into the file, and closing the file.  The
job can then be scheduled using DosPrintJobSchedule.

While a print job is being written (after DosPrintJobAdd but before
DosPrintJobSchedule) its status is recorded as SPOOLING.

Returns: 0 if successful. Possible errors:
        NERR_BufTooSmall
        NERR_QNotFound
        NERR_SpoolerNotLoaded
        NERR_JobNoRoom
        NERR_SpoolNoMemory


-------------------------
20.5  DosPrintJobSchedule 

Purpose: Schedule a completed spool file for printing

unsigned far pascal
DosPrintJobSchedule(server, jobid)
char far *     servername;         asciz remote server name or NULL if local
unsigned short jobid;              job ID


The jobid must be a valid job ID that is created via DosPrintJobAdd.
This function is to be used once the information has been written into
the file.  If successful, this call sets the job's status to QUEUED.

Returns: 0 if successful. Possible errors:
        NERR_JobNotFound
        NERR_SpoolerNotLoaded
        NERR_JobInvalidState


-------------------------
20.6  DosPrintJobDel 

Purpose: Delete a job currently in the print queue.

unsigned far pascal
DosPrintJobDel(servername, jobid)
char far *      servername;         asciz remote server name or NULL if local
unsigned short  jobid;              job identifier

Note:  If the job is currently printing, it will be killed immediately.
       Only the user who submitted the job or an administrator have the
       privilege to delete a job.

Returns: 0 if successful. Possible errors:
        NERR_JobNotFound
        NERR_SpoolerNotLoaded
        NERR_ProcNoRespond
        NERR_InsufficientPriv

-------------------------
20.7  DosPrintJobPause 

Purpose: Pause a job currently in the print queue.

unsigned far pascal
DosPrintJobPause(servername, jobid)
char far *      servername;         asciz remote server name or NULL if local
unsigned short  jobid;              job identifier

Causes a job to be held in the print queue.  This call will NOT pause a
currently printing job (the api will return an error instead).

Note:  Only the user who submitted the job or an administrator have the
       privilege to delete a job.

Returns: 0 if successful. Possible errors:
        NERR_JobNotFound
        NERR_SpoolerNotLoaded
        NERR_JobInvalidState             - job is currently printing
        NERR_InsufficientPriv

-------------------------
20.8  DosPrintJobContinue 

Purpose: Continue a paused print job.

unsigned far pascal
DosPrintJobContinue(servername, jobid)
char far *      servername;         asciz remote server name or NULL if local
unsigned short  jobid;              job identifier

Release a queued job that was held by DosPrintJobPause.

Note:  Only the user who submitted the job or an administrator have the
       privilege to delete a job.

Returns: 0 if successful. Possible errors:
        Remote server communication failure.
        NERR_JobNotFound
        NERR_SpoolerNotLoaded
        NERR_JobInvalidState
        NERR_InsufficientPriv


-------------------------
20.9  DosPrintJobGetId 

Purpose: To Get a Remote Print Job ID

unsigned far pascal
DosPrintJobGetId(handle, buf, size )
unsigned short handle;          /* handle to the redirected printing device*/
char far *buf;                  /* Buffer pointer */
unsigned short size;            /* Size of Buffer, must be at least GetPrintId*/


On return, if successful, the buffer contains the following structure:

struct GetPrintId {
        unsigned short id;
        char server[MAXNAMESZ];         /* server name */
        char qname[QNLEN+1];            /* queue to which the job is queued */
};

Applications can use this information to control the job via PrintJob API, such
as to pause/continue it or to set job parameters.


Returns: 0 if successful. Possible errors:
        NERR_DevNotRedirected
        NERR_BufTooSmall



21.   PRINT DESTINATIONS 

Print Destination Data Structure:

   struct PRINTDEST {
       char             prdest_name[PDLEN+1];
       unsigned short   prdest_jobid;
       unsigned short   prdest_status;
       char far *       prdest_status_string;
       char             prdest_username[UNLEN+1];
       unsigned short   prdest_time;
   };

name            Name of print destination.

jobid           Job ID of currently printing job.  See NetPrintJob
                APIs.  This will be zero if no job is printing.

status          A bitmapped status field:

                 Bits           Meaning

                  0-1                                   0 - Normal 1- Paused
                   2      PRJOB_COMPLETE     0x4        Complete if set
                   3      PRJOB_INTERV       0x8        Intervention required
                   4      PRJOB_ERROR        0x10       Error on destination
                   5      PRJOB_DESTOFFLINE  0x20       Destination offline
                   6      PRJOB_DESTPAUSED   0x40       Destination paused
                   7      PRJOB_NOTIFY       0x80       Indicates if an alert
                                                        should be raised.
                   8      PRJOB_DESTNOPAPER  0x100      Destination out of 
                                                        paper.
                 9-15     <reserved>

                Note that bits 2-8 are meaningful only if there
                is a job printing.  See "jobid" above.

status_string   Meaningful only if a job is printing.  See "jobid"
                above.  If a job is printing, the status string is an 
                optional ASCIZ string that is posted by the print 
                queue processor.  This allows an installable printing 
                processor to specify detailed status to complement the 
                status bit encodings.  For example, this string could 
                be "OUT OF PAPER", "PEN CHANGE REQUIRED", etc.

username        Meaningful only if a job is printing.  See "jobid"
                above.  User name of user who submitted the currently
                printing job.

time            Printing time in minutes since job started



Pausing an idle destination is a valid operation. In this case, the
first two bits of status will be 01 and the jobid will be 0.


NOTE:  The Spool Manager API does not provide Add or Del verbs for
       print destinations.  This function is performed implicitly by
       the Spool Manager when print queues are added or deleted
       (see Section 1).  No SetInfo call is provided since print
       destinations have no settable parameters.  They are defined
       entirely by their name and status information.

These calls should include "spool.h".

-------------------------
21.1  DosPrintDestEnum 

Purpose: DosPrintDestEnum enumerates all print destinations in a given machine.

unsigned far pascal
DosPrintDestEnum(servername, level, buf, buflen, entriesread, totalentries)
char far *          servername;     asciz remote server name or NULL if local
short               level;          level of detail requested; 0 or 1
char far *          buf;            buffer to return entries in
unsigned short      buflen;         size of buffer on call;
unsigned short far *entriesread;    # of entries supplied on return
unsigned short far *totalentries;   total # of entries available

Buffer contents in the response:

    level 0 contains:
        char[PDLEN+1][entriesread]          array of print destination names

    level 1 contains:
        PRINTDEST[entriesread]              array of PRINTDEST structures

NOTE:   Supplying a buflen of zero can be used to get the number of total
        entries available without reading any actual data.

Returns: 0 if successful. Possible errors:

        ERROR_INVALID_LEVEL  The level parameter passed in is incorrect.
        NERR_BufTooSmall     See Enum documentation.
        ERROR_MORE_DATA      See Enum documentation.
        NERR_SpoolNotLoaded  Spooler is not running

-------------------------
21.2  DosPrintDestGetInfo 

Purpose: Get information about a print destination.

unsigned far pascal
DosPrintDestGetInfo(servername, destname, level, buf, buflen, totalavail)
char far *          servername;     asciz remote server name or NULL if local
char far *          destname;       asciz print destination name
short               level;          level of info requested
char far *          buf;            return buffer
unsigned short      buflen;         length of buf
unsigned short far *totalavail;     total size needed for buffer

On return the buffer contains:
        Level 0:    PrintDest name
        Level 1:    A PRINTDEST structure, up to buflen.

Returns: 0 if successful. Possible errors:

        ERROR_INVALID_LEVEL  The level parameter passed in is incorrect.
        NERR_BufTooSmall     See Enum documentation.
        ERROR_MORE_DATA      See Enum documentation.
        NERR_SpoolNotLoaded  Spooler is not running
        NERR_DestNotFound    Cannot find the named destination
        NERR_DestNotFound    Cannot find the named destination

-------------------------
21.3  DosPrintDestControl (Admin only) 

Purpose: Control the status of the current job on a print destination

unsigned far pascal
DosPrintDestControl(servername, destname, opcode)
char far *    servername;        asciz remote server name or NULL if local
char far *    destname;          asciz destination name
unsigned short  opcode;          0 kill current printing job
                                 1 pause printing
                                 2 continue the current (paused) job
                                 3 restart the current printing job
                                 4 -127 reserved
                                 128 and up, OEM defined

Pausing an idle destination will prevent the destination from accepting
new jobs.  Killing/restarting an idle destination will return an error
NERR_DWstIdle.

Returns: 0 if successful. Possible errors:
        NERR_SpoolNotLoaded     Spooler is not running
        NERR_DestNotFound       Cannot find the named destination
        NERR_InvalidOp          Invalid opcode
        NERR_DestIdle           Destination idle
        NERR_ProcNoRespond      Printing processor won't respond


-------------------------
21.4  DosPrintDestStatus 

Purpose:  Indicate status of current job on print destination.
          This call is used by print processors only.  It is used
          1) In response to DosPrintDestControl, to indicate results
          2) Spontaneously, to indicate job progress or problems

unsigned far pascal
DosPrintDestStatus(destname, pid, status, status_string)
char far *     destname;        destination name reporting status
unsigned short pid;             process ID to be registered
unsigned short status;          print destination status mask
char far *     status_string;   asciz string (print processor defined,
                                   may be NULL pointer)

Note: this call does not take a servername parameter.  It functions
locally only (print processors report status only to the local spool
manager that invoked them).

Supplying a nonzero PID changes the pid to which DosPrintDestControl
signals will be sent (used when a Print Processor spawns another 
process).

The definition of the status mask:
    0-1     Status opcode
            0 -- posting unsolicited status change
            1 -- responding to DosPrintDestControl with success
            2 -- responding to DosPrintDestControl with intermediate status
            3 -- responding to DosPrintDestControl with failure
    2       Job complete/not complete
    3       Intervention required/not required
    4       Error/no error on print destination (device)
    5       Print destination (device) online/offline
    6       Print destination (device) paused/not paused
    7       Notify user/do not notify user
    8-15    Reserved.

When a print processor responds to a DosPrintDestControl, it must set
the status opcode to either 1 (success), 2 (intermediate), or 3
(failure).

Turning on bit 7 (Notify) will cause a printing alert to be raised via
NetAlertRaise.  This will result in the user getting a message about the
printing event, if the network Alerter program is running at the server where
the event occurred.

Returns: 0 if successful. Possible errors:
        NERR_DestNotFound       Cannot find the named destination


21.5  Writing a Print Queue Processor 

The following is additional information on writing print queue processors.
A print queue processor is an .EXE program that is invoked by the
spooler to print a print job.  The program is normally installed
in the root of the configured spool directory.  Queue processors
are configured on a per-queue basis, via the "processor" variable
in the PRINTQ structure.  This variable can be set via the
DosPrintQAdd and DosPrintQSetInfo calls.  If no processor is set,
default printing logic is used.  Print queue processors are invoked
with command-line arguments as follows.

The first arguments on the command line are taken from the "processor"
variable.  In other words, this variable can specify both the processor
pathname and a set of command-line arguments (eg, MYPROC.EXE ARG1 ARG2).
Note that processor arguments should be of KEYWORD=VALUE form.

Following the arguments taken from the "processor" variable, the following
additional arguments are appended to the command line:

INPUT=<pathname>        full pathname of input spool file
OUTPUT=<pathname>       full pathname of output print destination
PARMS="<job parms>"     job-specific parameters (taken from the
                        "parms" variable in the PRINTJOB structure
                        structures)
JOB=nnnn                where nnnn is the hex ascii job id (eg, 0013)
QUEUE=<queuename>       name of print queue the job is printing from


Note 1:  If the print destination (OUTPUT=) is an OS/2 COM or LPT device,
the spooler opens this device and passes it to the print processor
as stdout.  In this case, the print processor should not attempt
to open the device, but should simply write to stdout.

Note 2:  A print queue processor is free to use any LAN Manager api,
including print api's.  For example, it may want to use the job id
and queue name information to get job- and queue-related information
(for example, if the print queue processor supports the EJECT= option,
it should use DosPrintQGetInfo to fetch the queue-related parms variable
where this option is specified).

Note 3:  Print processors are responsible for establishing a signal
handler to field print job control requests that result from
calls to DosPrintDestControl.  The processor must also use
DosPrintDestStatus to acknowledge these control operations,
or to indicate spontaneous changes in print job status (like
printer problems) which require human intervention.  Control
signals are received via Flag A with the Flagarg indicating
the control operation.  The value of the Flagarg corresponds
to the opcode in DosPrintDestControl for pausing, continuing,
restarting, and killing a print job.  See the documentation for
the DosPrint api's for more information.  The following is
partial pseudocode for the signal handling logic:

    /* template */
    void pascal far
    SignalHandler(opcode,flag)
    WORD flag;      /* should be value 5 -- flag A */
    WORD opcode;    /* opcode */
    {
            switch(opcode) {
            case SPOOLRESTART:
                    ...
            case SPOOLKILL:
                    ...
            case SPOOLPAUSE:
                    ...
            case SPOOLCONT:
                    ...
            }

            /* handshake */
            DosPrintDestStatus(destination,
                    0,      /* don't change pid */
                    0,      /* success */
                    NOCARE);/* no new status string */

            /* Re-Enable signal handling */
            DosSetSigHandler(SignalHander,
                    &prevaddr,      /* previous addr */
                    &prevact,       /* previous action */
                    4,              /* Re-Enable */
                    5 };            /* flag A */
    }


22.   PIPES 

Named pipes are a bidirectional inter-process communication facility
that operate locally and across the network.  Named pipes are
full-duplex communication paths akin to virtual circuits.  Like
virtual circuits, what is written into one end can be read at the
other end and vice versa; continuing the analogy, what you write at
one end CANNOT be read at that end, only at the other end.

A pipe is created using the call DosMakeNmPipe, which returns a
handle to one end of the pipe.  This end is called the "serving" end.
The process which creates the pipe can then use the DosConnectNmPipe
to determine when another process has connected to the other end of
the pipe.

The other end of the pipe, called the "client" end, is accessed
through DosOpen.

Multiple clients can be served using unique instances of the same
named pipe -- see the "ICount" portion of the "Pmode" parameter to
DosMkNmPipe, below.

-------------------------
22.1  DosMakeNmPipe 

Purpose:  Creates a named pipe and returns its handle.

unsigned far pascal
DosMakeNmPipe(name, handle, omode, pmode, size1, size2, timeout)
char far *      name;           asciz pipe name
unsigned far *  handle;         place for handle to be returned
unsigned short  omode;          DOS open mode
unsigned short  pmode;          pipe open mode
unsigned short  size1;          hint of outgoing buffer size
unsigned short  size2;          hint of incoming buffer size
long            timeout;        time out for DosWaitNmPipe

The handle returned from DosMakeNmPipe accesses one end of the pipe,
called the serving end, while handles returned from DosOpen access
the other (client) end.  Unlike anonymous pipes, each handle to a
named pipe can be both read and written (unless the access modes at
the two ends restrict this).  Note that the DosConnectNmPipe call
must be used to determine when the other end of the pipe has actually
been DosOpened by another process.

Name:   Asciz name of pipe.  Pipes are named \PIPE\NAME.

Handle: Handle of named pipe that is created.

Omode:  Open mode mask as for DosOpen call.  The following bits are
        defined.

               Open Mode Bits
       5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
       0 W * * * * * * I 0 0 0 * A A A

       I  Inheritance:  0 => spawned processes inherit the pipe handle
                        1 => spawned processes don't inherit the pipe

       W  Write-through 0 => write-behind to remote pipes is allowed
                        1 => write-behind to remote pipes is not allowed

     AAA  Access mode:  000 => inbound pipe (client to server)
                        001 => outbound pipe (server to client)
                        010 => full duplex pipe (server to/from client)
                        Other values invalid


Pmode:  Pipe-specific mode parameters.

      5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
      B * * * T T R R |--- Icount --|

       B  Blocking: 0 => reads/writes block if no data available
                    1 => reads/writes return immediately if no data

            Reads normally block until at least partial data
            can be returned.  Writes by default block until
            all bytes requested have been written.   Nonblocking
            mode (B=1) changes this behavior as follows:

            1) Reads will return immediately with BytesRead=0
               if no data is available.

            2) Writes will return immediately with BytesWritten=0
               if the data transfer cannot be started.  Otherwise,
               the entire data area will be transferred.

      TT  Type of pipe: 00 => Pipe is a byte stream pipe
                        01 => Pipe is a message stream pipe

            All writes to message stream pipes record the
            length of the write along with the written data
            (see DosWrite).

      RR  Read mode:    00 => Read pipe as a byte stream
                        01 => Read pipe as a message stream

            Message pipes can be read as byte or message
            streams, depending on the setting of RR.  Byte
            pipes can only be read as byte streams.  For
            more details, see DosRead.

      Icount:  8-bit count to control pipe instancing.  When making
            the first instance of a named pipe, Icount specifies
            how many instances can be created:  1 means that this
            can be the only instance (pipe is unique) and -1
            means the number of instances is unlimited; 0 is
            a reserved value.  Subsequent attempts to make a pipe
            will fail if the maximum number of allowed instances
            already exists.  The Icount parameter is ignored when
            making other than the first instance of a pipe.
            When multiple instances are allowed, multiple clients can
            simultaneously DosOpen to the same pipe name and get
            handles to distinct pipe instances.

Size1:   Hint to system, number of bytes to allocate for outgoing
         buffer.

Size2:   Hint to system, number of bytes to allocate for incoming
         buffer.

Timeout: Default value for timeout parameter to PipeWait.  This value
         may be set only at the creation time of the first instance of
         the pipe name.  If at that time the value is zero, a system
         wide default value (50 ms) will be chosen.

Returns: 0 if successful. Possible errors:
        ERROR_PATH_NOT_FOUND    Illegal pipe name.
        ERROR_INVALID_PARAMETER Illegal or inconsistent parameters.
        ERROR_PIPE_BUSY         All allowed instances exist.
        ERROR_OUT_OF_STRUCTURES An internal data structure could not
                                be allocated.
        ERROR_NOT_ENOUGH_MEMORY Pipe buffers could not be allocated.

-------------------------
22.2  DosQNmPipeInfo 

Purpose:  Returns information about a pipe.

unsigned far pascal
DosQNmPipeInfo(handle, level, buf, buflen)
unsigned        handle;         handle returned by DosMakeNmPipe or DosOpen
short           level;          level of detail requested
char far *      buf;            buffer to return entries in
unsigned short  buflen;         size of buffer on call

Pipe information is returned in the supplied buffer.  The level 1
information is returned in the following format:

    Word    actual size of buffer for outgoing I/O
    Word    actual size of buffer for incoming I/O
    Byte    Maximum allowed number of instances
    Byte    Current number of instances
    Byte    Length of pipe name
    Asciz   Name of pipe (including \\ComputerName if remote)


Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_INVALID_LEVEL     Unsupported level parameter.
        ERROR_BUFFER_OVERFLOW   Supplied buffer too small.  The
                                buffer will be filled to the length
                                specified.

-------------------------
22.3  DosConnectNmPipe 

Purpose:  Waits for a new client to open a pipe

unsigned far pascal
DosConnectNmPipe(handle)
unsigned        handle;         handle returned by DosMakeNmPipe or DosOpen

DosConnectNmPipe causes a newly made or disconnected pipe to enter a
listen state that will accept a DosOpen from a client (DosOpens to
pipes not in listen state will fail).  If the client end of a pipe is
currently open, DosConnectNmPipe returns immediately and has no
effect.  If the client end is not open, DosConnectNmPipe either waits
until it is open (if blocking mode is set) or else returns
immediately with an error code (if non-blocking mode is set).  If the
pipe was previously opened but has been closed by the client and not
yet disconnected by the server, DosConnectNmPipe always returns an
error ERROR_PIPE_BROKEN.  Multiple DosConnectNmPipe can be issued in
non-blocking mode; the first one puts the pipe into listen state (if
it is not already open or closing) and subsequent ones simply test
the pipe state.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_INVALID_FUNCTION  Handle refers to client end of pipe.
        ERROR_PIPE_NOT_CONNECTED State of pipe is disconnected.
        ERROR_PIPE_BROKEN       State of pipe is closing.
        ERROR_INTERRUPT         Interrupted wait.

-------------------------
22.4  DosDisconnectNmPipe 

Purpose:  Forces a pipe closed

unsigned far pascal
DosDisconnectNmPipe(handle)
unsigned        handle;         handle returned by DosMakeNmPipe or DosOpen

If the client end of the pipe is currently opened,
DosDisconnectNmPipe forces it closed (the client gets an error code
on its next operation).  Note that this may discard data which has
not yet been read by the client.  If the client end is currently
closing (DosClose has been issued), DosDisconnectNmPipe acknowledges
the close and makes the pipe available to be reopened.  A client that
gets forced off a pipe by a DosDisconnectNmPipe must still issue
DosClose to close its end of the pipe.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_INVALID_FUNCTION  Handle refers to client end of pipe.

-------------------------
22.5  DosQNmpHandState 

Purpose:  Return pipe-specific state information.

unsigned far pascal
DosQNmpHandState(handle, pmode)
unsigned             handle;    handle returned by DosMakeNmPipe or DosOpen
unsigned short far * pmode;     pipe state bits

      Pipe Handle State Bits
      5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
      B E * * T T R R |--- Icount --|

The E (endpoint) bit is 0 if this handle is the client end of a pipe
and 1 if the serving end.  See DosMakeNmPipe for the other field
definitions.  At the serving end, the values returned by
DosQNmpHandState are those originally established by DosMakeNmPipe or
a subsequent DosSetNmpHandState.  For the client end, the values
returned are those originally established by DosOpen or a subsequent
DosSetNmpHandState.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_PIPE_NOT_CONNECTED Client pipe handle was disconnected.

-------------------------
22.6  DosSetNmpHandState 

Purpose:  Set pipe-specific handle states.

unsigned far pascal
DosSetNmpHandState( handle, pmode )
unsigned        handle;         handle returned by DosMakeNmPipe or DosOpen
unsigned short  pmode;          pipe state bits

      Pipe Handle State Bits
      5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
      B * * * * * R R 0 0 0 0 0 0 0 0

See DosMakeNmPipe for field definitions.  Note that only the read
mode (byte vs message) and blocking/nonblocking mode of a named pipe
can be changed.  Some combinations of parameters may be illegal and
will be rejected as an error.   

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_PIPE_NOT_CONNECTED Client pipe handle was disconnected.
        ERROR_INVALID_PARAMETER Invalid or inconsistent state specified.

-------------------------
22.7  DosPeekNmPipe 

Purpose:  Read pipe without removing the read data from the pipe.

unsigned far pascal
DosPeekNmPipe(handle, buffer, buflen, bytesread, availdata, status)
unsigned             handle;     handle returned by DosMakeNmPipe or DosOpen
char far *           buffer;     address of buffer to receive peeked data
unsigned short       buflen;     number of bytes to read
unsigned short far * bytesread;  number of bytes actually read (could be 0)
unsigned short far * availdata;  two words: bytes in pipe (including message
                                 header bytes), bytes in current message
                                 (zero for a byte pipe)
unsigned short far * status;     state of the pipe (Listening, Connected,
                                 Closing, Disconnected)

DosPeekNmPipe acts like DosRead except as follows:

1) The bytes read are not removed from the pipe.

2) The peek may return only part of a message (that part currently in the
   pipe), even if the size of the peek would accommodate the whole
   message.

3) DosPeekNmPipe never blocks, regardless of the blocking mode.

4) Additional information about the status of the pipe and remaining data
   are returned.  The caller can use this, for example, whether the peek
   returned all of the current message or whether the pipe is at EOF (pipe
   is at EOF when there are no bytes left in the pipe and Status is Closing
   or Disconnected).  The available data information includes the size
   of the data being peeked.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_PIPE_NOT_CONNECTED Client pipe handle was disconnected.
        ERROR_PIPE_BUSY         Some other thread is currently reading pipe.

-------------------------
22.8  DosTransactNmPipe 

Purpose: Perform a write followed by a read on a message pipe.

unsigned far pascal
DosTransactNmPipe(handle, inbuffer, inlength, outbuffer, outlength, bytesout)
unsigned              handle;         handle returned by DosMakeNmPipe or DosOpen
char far *            inbuffer;       Address of buffer to write to the pipe
unsigned short        inlength;       Number of bytes to write
char far *            outbuffer;      Address of buffer for returned data
unsigned short        outlength;      Max size of returned data
unsigned short far *  bytesout;       Number of bytes actually returned

This provides an optimum way to implement transaction-oriented
dialogs.  DosTransactNmPipe will fail if the pipe currently contains
any unread data or is not in message read mode.  Otherwise the call
will write the entire InBuffer to the pipe and then read a response
from the pipe into the OutBuffer.  The state of blocking/nonblocking
has no affect on this call--DosTransactNmPipe does not return until a
message has been read into the OutBuffer.  If the OutBuffer is too
small to contain the response message, a MORE DATA error code will be
returned as described for DosRead.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_PIPE_NOT_CONNECTED Client pipe handle was disconnected.
        ERROR_BROKEN_PIPE       Write to single-ended pipe.
        ERROR_MORE_DATA         More data exists in message.  All
                                data requested has been transferred.

-------------------------
22.9  DosCallNmPipe 

Purpose:  Provide an efficient "procedure call" transaction via a named pipe.

unsigned far pascal
DosCallNmPipe(name, inbuffer, inlength, outbuffer, outlength,
                        bytesout, timeout)
char far *          name;           Asciz name of pipe
char far *          inbuffer;       Address of buffer to write to the pipe
unsigned short      inlength;       Number of bytes to write
char far *          outbuffer;      Address of buffer for returned data
unsigned short      outlength;      Max size of returned data
unsigned short far * bytesout;      Number of bytes actually returned
long                timeout;        Time to wait for availability

This routine has the combined effect on a named pipe of DosOpen,
DosTransactNmPipe, DosClose.  It provides a very effiecient means of
implementing local and remote procedure-call (RPC) interfaces between
processes.

Returns: 0 if successful. Possible errors:
        ERROR_FILE_NOT_FOUND    Specified pipe does not exist.
        ERROR_PIPE_BUSY         All available instances are in use.
        ERROR_PIPE_NOT_CONNECTED Pipe disconnected during transaction.
        ERROR_BROKEN_PIPE       Write to single-ended pipe.
        ERROR_MORE_DATA         More data exists in message.  All
                                data requested has been transferred.
        ERROR_SEM_TIMEOUT       Wait timed out.
        ERROR_INTERRUPT         Interrupted wait.

-------------------------
22.10 DosWaitNmPipe 

Purpose:  Waits for the availability of a named pipe instance.

unsigned far pascal
DosWaitNmPipe(Name, Timeout)
char far *  Name;               name of pipe to wait for
long        Timeout;            length of time to wait

DosWaitNmPipe allows an application to wait for a server on a pipe
for which all instances are currently busy.  This call should be used
only when the error PIPE_BUSY is returned from a DosOpen call.  The
call will wait up to Timeout milliseconds (or a default time if
Timeout is zero) for a pipe of the name given to become available.
When a pipe instance becomes available, an effort is made to give it
to the process which has been waiting longest, but no guarantee of
fairness is given.


Name:    Asciz name of pipe.

Timeout: Time in milliseconds to wait for the pipe to become available.
         If zero is given, a default value specified at DosMakeNmPipe
         time will be used.  If -1 is given, an indefinite wait will be
         entered.

Returns: 0 if successful. Possible errors:
        ERROR_FILE_NOT_FOUND    Specified pipe does not exist.
        ERROR_PIPE_BUSY         All available instances are in use.
        ERROR_SEM_TIMEOUT       Wait timed out.
        ERROR_INTERRUPT         Interrupted wait.
 
-------------------------
22.11 DosQNmPipeSemState 

Purpose:  Returns information about pipes associated with a semaphore

unsigned far pascal
DosQNmPipeSemState(SemHandle, InfoBuf, InfoBufLen)
long           SemHandle;        semaphore handle associated with named pipes
char far *     InfoBuf;          buffer to return entries in
unsigned short InfoBufLen;       size of buffer


For each local named pipe in the system, if the system semaphore
handle matches a semaphore attached to the named pipe, and a blocking
mode I/O could be started on the pipe, or if the pipe has been
closed, a record is placed in InfoBuff.  Records in InfoBuff are of
the following form:

        Byte    status
            coded value indicating the state of the named pipe:
                00h - end of information; other fields in this
                    record have no significance.
                01h - read data available
                02h - write space available
                03h - pipe is closed

        Byte    flags
            bit mask indicating additional information about the
            state of the pipe
                01h - a thread is waiting on the other end of
                        the pipe.

        Word    keyhand
            key value associated with SemHandle at the time of the
            call to DosSetNmPipeSem.

        Word    avail
            if status is 1, this word contains the
            write space available in the pipe.
            if status is 2, this word contains the
            amount of read data available in the pipe.


Note that there is no guarantee that records in the buffer refer to
named pipes opened by the process making this system call.  If the
same system semaphore is attached to different named pipes by
multiple processes, information about named pipes which were
inaccessible could be returned.  Cooperating processes could agree on
a convention for the formation of Key values to help distinguish the
attached process.

Note that since semaphores are used as a signalling mechanism, the
use of exclusive semaphores may not be correct if the named pipe is
in use by two or more processes since processes other than the owner
of the semaphore cannot SemClear the semaphore.

A process will normally use DosQNmPipeSemState in the case that it
has associated a single semaphore with multiple pipes (via
DosSetNmPipeSem).  After waking up from a wait on this semaphore, the
call to DosQNmPipeSemState would return the I/O state information for
all pipes associated with that semaphore.       The process could scan this
information to determine which pipes can be read or written.  This is
far more efficient than polling the pipes with a nonblocking I/O on
each pipe.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_PARAMETER Zero length buffer specified.
        ERROR_SEM_NOT_FOUND     Specified semaphore does not exist.
        ERROR_BUFFER_OVERFLOW   Buffer is too small.  The buffer
                                will be filled with as many complete
                                records as possible.

-------------------------
22.12 DosSetNmPipeSem 

Purpose   A system semaphore is attached to a named pipe.

unsigned far pascal
DosSetNmPipeSem(Handle, SemHand, KeyHand)
unsigned        Handle;         handle returned by DosMakeNmPipe or DosOpen
long            SemHand;        semaphore handle associated with named pipes
unsigned short  KeyHand;        key value

The system semaphore described by SemHand is attached to the named
pipe described by Handle.  Up to two semaphores may be attached to a
named pipe, one for the serving side and one for the client side.  If
there is already a semaphore attached to this side of the pipe, it
will be overridden.

This call works for local named pipes only.  If an attempt is made to
attach a semaphore to a remote named pipe, ERROR_INVALID_FUNCTION is
returned.

KeyHand is an arbitrary value which is also associated with the named
pipe.  Its purpose is to distinguish events arriving on different
named pipes attached to the same semaphore.

The primary purpose of this call is to support serving applications
that need to handle a large number of incoming pipes. DosSetNmPipeSem
lets such applications avoid the need to dedicate a thread per
incoming pipe or the need to poll the pipes with nonblocking I/O. The
application can instead do a DosSemWait or a DosMuxSemWait on the
pipe semaphore(s) to determine when I/O can be performed.  This way,
a large number of pipes can be handled with a small number of
threads, in an event driven way.  DosQNmPipeSemState can be used to
provide additional information about what I/O can be performed on the
set of pipes.

Returns: 0 if successful. Possible errors:
        ERROR_INVALID_HANDLE    Bad file handle.
        ERROR_BAD_PIPE          Not a named pipe file handle.
        ERROR_INVALID_FUNCTION  Handle refers to remote pipe.
        ERROR_SEM_NOT_FOUND     Specified semaphore does not exist.
        ERROR_PIPE_NOT_CONNECTED Client pipe handle was disconnected.

-------------------------
22.13 DosOpen 

Opens the client end of a pipe by name and returns a handle.  The
pipe must be in listen state for the open to succeed; otherwise the
open fails with PIPE BUSY (this happens, for example, if all
instances of the pipe are already open, if the pipe is closed but not
yet disconnected by the serving end, or if no DosConnectNmPipe has
been issued against the pipe since it was last disconnected).  Once a
given instance has been opened by a client that same instance cannot
be opened by another client at the same time (i.e., pipes can only be
two-ended at present); the opening process can of course dup the open
handle as many times as desired.  The access and sharing modes
specified on the open must be consistent with those specified on the
DosMakeNmPipe.  Pipes are always opened with the pipe-specific states
set to B = 0 (blocking reads/writes), RR = 00 (read as byte stream).
The client can change these modes via DosSetNmpHandState if desired.


-------------------------
22.14 DosClose 

Closes a pipe by handle.  When all handles referencing one end of a
pipe are closed the pipe is broken.  If the client end closes, no
other process can reopen the pipe until the serving end issues a
DosDisconnectNmPipe followed by a DosConnectNmPipe.  If the server
end closes, the pipe will be deallocated when the last client handle
is closed or immediately if the pipe is already broken.


-------------------------
22.15 DosDupHandle 

As specified in the OS/2 reference.


-------------------------
22.16 DosQHandType 

Returns HandType = 2 (pipe handle) in the low-order 8 bits.  Bits in
the high-order byte are reserved for future use.  Bit 15 will be used
in the future to indicate whether a named pipe is remote or local.


-------------------------
22.17 DosQFHandState 

As defined by Dos.  D = 0.  Other bits as defined by DosMakeNmPipe
(serving end), DosOpen (client end), or the last DosSetFHandState.


-------------------------
22.18 DosSetFHandState 

Allows setting of the inheritance (I) and write-through (W) bits.
Note that setting W to 1 prevents write-behind operations on remote pipes.


-------------------------
22.19 DosWrite, DosWriteAsync 

Writes bytes or messages to a pipe.  Each write to a message pipe
writes a message whose size is the length of the write;  DosWrite
automatically encodes message lengths in the pipe, so applications
need not encode this information in the buffer being written.

Writes in blocking mode always write all requested bytes before
returning.  In nonblocking mode, writes return either with all bytes
written or none written; the latter will occur in certain cases where
the DosWrite would have to block in order to complete the request
(e.g., no room in pipe buffer or buffer currently being written by
another client).

An attempt to write to a pipe whose other end has been closed will
return with a PIPE BROKEN error.


-------------------------
22.20 DosRead, DosReadAsync 

Reads bytes or messages from a pipe.  There are three cases:

1) Byte pipe.  The pipe must be in byte read mode.  All currently
   available data, up to the size requested, is returned.

2) Message pipe, message read mode.  A read that is larger than the next
   available message returns only that message and BytesRead is set to
   indicate the size of the message returned.  A read that is smaller than
   the next available message returns with the number of bytes requested and
   a MORE DATA error code.  Subsequent DosReads will continue reading the
   message.  DosPeekNmPipe may be used to determine how many bytes are left in
   the message.

3) Message pipe, byte read mode.  Reads the pipe as if it were a byte
   stream, skipping over message headers.  This is like reading a byte
   pipe in byte mode.

When blocking mode is set, a read blocks until data is available.  In
this case, the read will never return with BytesRead=0 except at
EOF.  Note that in message read mode, messages are always read in
their ENTIRETY, except in the case where the message is bigger than
the size of the read.

When nonblocking mode is set, an error, ERROR_NO_DATA will be
returned if no data is available at the time of the read.

Note:  when resuming the reading of a message after a MORE DATA
indication, the reads will always block until the next piece (or
rest) of the message can be transferred.  Non-blocking mode only
allows an immediate return with the ERROR_NO_DATA error when trying
to read at the start of a message and no message is available.


-------------------------
22.21 DosBufReset 

Performs an operation analogous to the defined one of forcing the
buffer cache to disk.  For named pipes, DosBufReset blocks the caller
until all data written by the caller has been successfully read by
the other end.  This allows communicating processes to synchronize
their dialogs.




23.   MAILSLOTS 

Mailslots provide one way inter-process communication.  Data sent
trhough the mailslot mechanism is sent and recieved in blocks
called "messages" -- there is no way to read a mailslot byte-by-byte.
Multiple pprocesses on multiple machines may write to the same 
mailslot, but only the creating process may read the messages
or otherwise manipulate the mailslot.

The order of arrival of mailslots is not guaranteed to follow any
particular order.  The priority of a message will be considered
when determining the delivery order, but IS NOT BINDING upon the
underlying implementation.

Mail can be sent either 1st class or 2nd class.  1st class mail is
"guaranteed delivery", meaning that reasonable precautions are taken
to insure that the message arrives at the other end.  This only
gurantees that the mail reaches the remote mailbox, and NOT that
the intended recipient ever read the message from the mailbox.

2nd class mail is non-guaranteed.  The implementation will try to
deliver the message, but it is possible that the message will
not reahc the remote mailbox, and NO ERROR will be returned to
the sender.

On the other hand, 2nd class mail is usually faster, since smaller
messages can be sent using features of the underlying implementation
(for example datagrams)  that may be quicker that those methods
used for establishing a "reliable connection".  Also, the implementation
is free to return to the caller more quickly, since there is no
need to wait for confirmation from the remote machine.  Given a
realiable network, 2nd class mail will serve reasonably well,
there is just not a guarantee.

Also, 2nd class mail can be recieved over the net by workstations
(limited to approximately 512 bytes), while 1st class mail can only be sent
to servers under Lan Manager 1.0.


-------------------------
23.1  DosMakeMailslot 

Purpose:  Creates a mailslot and returns its handle.  Mailslots are
          named \MAILSLOT\NAME.

unsigned far pascal
DosMakeMailslot(Name, MessageSize, MailslotSize, Handle)
char far *     Name;
unsigned short MessageSize;
unsigned short MailslotSize;
unsigned far * Handle;

Name:           Asciz name of mailslot to create.  No other mailslot of
                this name must exist on this machine or the call returns 
                an error.

MessageSize:    Size of the largest message the mailslot will accept.
                Limit is implementation-dependent.

MailslotSize:   Size of mailslot to allocate (bytes).  Must be larger
                than MessageSize.  NOTE:  Advisory parameter only.  The
                implementation is free to round this up as required for
                message-header overhead, efficient memory usage, etc.,
                or if the size is below the minimum for a message of the
                MessageSize specified.  The implementation should not 
                make the buffer smaller than specified, since the
                caller is usually trying to advise the implementation to
                make room for at least some number of messages of the
                given MessageSize.

Handle:         Mailslot handle is returned in the location pointer to by
                Handle.  This returned value is used with DosDeleteMailslot, 
                DosMailslotInfo, DosReadMailslot and DosPeekMailslot.  
                Mailslot handles are not inherited across DosExecPgm, 
                but they may be shared among threads in a single process.

Returns: 0 if successful. Possible errors:

    ERROR_PATH_NOT_FOUND        Not a valid local mailslot name
    ERROR_FILE_EXISTS           Mailslot already exists with this name
    ERROR_INVALID_PARAMETER     Message size too small or too big

-------------------------
23.2  DosDeleteMailslot 

Purpose:  Deletes a mailslot and discards any unread messages.
          Only the mailslot's creator can delete a mailslot.

unsigned far pascal
DosDeleteMailslot(Handle)
unsigned Handle;

Handle:   Handle of mailslot to delete.

Returns: 0 if successful. Possible errors:

    ERROR_INVALID_HANDLE        Mailslot handle parameter not valid

-------------------------
23.3  DosMailslotInfo 

Purpose:  Returns configuration and status information about a
          mailslot.

unsigned far pascal
DosMailslotInfo(Handle,MessageSize,MailslotSize,NextSize,NextPriority,MsgCount)
unsigned               Handle;
unsigned short far *   MessageSize;
unsigned short far *   MailslotSize;
unsigned short far *   NextSize;
unsigned short far *   NextPriority;
unsigned short far *   MsgCount;

Handle:         Handle of mailslot.

MessageSize:    Maximum size of message the mailslot will accept.

MailslotSize:   Number of bytes allocated to the mailslot.

NextSize:       Size of next message in mailslot, or 0 if none.

NextPriority:   Priority of next message in mailslot.

MsgCount:       Number of messages currently in the mailslot.


Returns: 0 if successful. Possible errors:

    ERROR_INVALID_HANDLE        Mailslot handle parameter not valid

-------------------------
23.4  DosReadMailslot 

Purpose:  Reads the next message from the mailslot.

unsigned far pascal
DosReadMailslot(Handle, Buffer, BytesRead, NextSize, NextPriority, Timeout)
unsigned               Handle;
char far *             Buffer;
unsigned short far *   BytesRead;
unsigned short far *   NextSize;
unsigned short far *   NextPriority;
long                   Timeout;

Handle:         Handle of mailslot to read.

Buffer:         Buffer to put message into.  This must be at least as
                large as the MessageSize specified to DosMakeMailslot.

BytesRead:      Length of message actually read.  Set to zero if no
                message was read.

NextSize:       Length of next message in mailslot, or 0 if none.

NextPriority:   Priority of next message in mailslot (undefined if NextSize
                is 0).

Timeout:        Length of time (in milliseconds) to wait if a message
                is not immediately available.  If 0, the process will
                not wait for the availability of a message.  If -1,
                the process will wait indefinitely.

Returns: 0 if successful. Possible errors:

    ERROR_INVALID_HANDLE        Mailslot handle parameter not valid
    ERROR_BROKEN_PIPE           Mailslot was deleted while the process
                                  was waiting for a message.
    ERROR_SEM_TIMEOUT           Timeout value was reached.
    ERROR_INTERRUPT             Wait for message was interrupted, try again.

-------------------------
23.5  DosPeekMailslot 

Purpose:  Reads the next message from the mailslot but does not
          remove it from the mailslot and does not wait for a
          message to become available.

unsigned far pascal
DosPeekMailslot(Handle, Buffer, BytesRead, NextSize, NextPriority)
unsigned               Handle;
char far *             Buffer;
unsigned short far *   BytesRead;
unsigned short far *   NextSize;
unsigned short far *   NextPriority;

Handle:         Handle of mailslot to read.

Buffer:         Buffer to put message into.  This must be at least as
                large as the MessageSize specified to DosMakeMailslot.

BytesRead:      Length of message actually read.  Set to zero if no
                message was read.

NextSize:       Length of next message in mailslot, or 0 if none.

NextPriority:   Priority of next message in mailslot (undefined if NextSize
                is 0).

NOTE:  Since the delivery order of mailslot messages is not defined,
it is not guaranteed that the message read by DosPeekMailslot will be
the next one read by DosReadMailslot.  A higher-priority message
may be inserted at the head of the queue between calls.

Returns: 0 if successful. Possible errors:

    ERROR_INVALID_HANDLE        Mailslot handle parameter not valid
    ERROR_BROKEN_PIPE           Mailslot was deleted while the process
                                  was waiting for a message.


-------------------------
23.6  DosWriteMailslot 

Purpose:  Sends a message to the specified mailslot.

unsigned far pascal
DosWriteMailslot(Name, Message, Size, Priority, Class, Timeout)
char far *     Name;
char far *     Message;
unsigned short Size;
unsigned short Priority;
unsigned short Class;
long           Timeout;

Name:    Asciz name of destination mailslot.  \\MACHINE\MAILSLOT\NAME
         refers to a remote mailslot.  \\*\MAILSLOT\NAME causes the
         write to occur to all computers on the local net (valid only
         if Class = 2).

Message: Message to send.

Size:    Size of message (bytes).

Priority: Priority of message.  0 is lowest.  The system will generally
          deliver higher priority messages ahead of lower priority ones;
          this ordering may be violated when writing to a remote mailslot
          or when a mailslot becomes full with multiple simultaneous
          writes outstanding.

Class:    Class of mail service to be provided (mainly used for
          writing remote mailslots):

          o First class mail is transported reliably and returns an
            error if the mail cannot be delivered.  The DosWriteMailslot
            will block until the write completes all the way to the
            destination mailslot or an error occurs.

          o First class mail may not be sent to a workstation (a system
            not running as a server).

          o Second class mail is transported on a best effort basis
            and can fail to succeed without reporting an error.

          o Second class mail sent to a workstation (a system not running
            as a server) is limited to at most 512 bytes, and maybe less
            depending upon the implementation.

Timeout:  Controls how long the request will block waiting for room in the
          mailslot to write the supplied buffer.  If Timeout is 0, the call
          will not block.  If -1, it will block indefinitely.  Any other
          value causes the call to wait up to that number of msec before
          failing if there still isn't room in the mailslot.

Returns: 0 if successful. Possible errors:

    ERROR_PATH_NOT_FOUND        Not a mailslot name, or no such mailslot
                                  was found.
    ERROR_BROKEN_PIPE           Mailslot was deleted while the process
                                  was trying to send the message.
    ERROR_SEM_TIMEOUT           Timeout value was reached.
    ERROR_INTERRUPT             Wait for message was interrupted, try again.
    ERROR_INVALID_PARAMETER     One of:
                                  Size == 0
                                  Priority value invalid, must be 0-9
                                  Class value invalid, must be 1 or 2
                                  Broadcast attempted to be sent class 1
Local-only version:

    ERROR_PATH_NOT_FOUND        A network mailslot name was specified.


24.   PROFILE 

The Profile APIs allow the current network profile to be saved and
later loaded, restoring the current set of network connections (Uses),
Shares, the status of Shared Print Queues and Comm Queues.  On
a workstation, only the Uses apply.

UNC-style (deviceless) redirections are not saved as part of the profile.
Passwords are not saved for redirections (Net Use commands).
PAsswords ARE saved for password-protected shares (share-level
security serves only).

On a server, all shares are saved as part of the profile.  Comments,
user limits, passwords (share-security mode only) and permissions are
saved with the share.

The special shares IPC$ and ADMIN$ are only saved when in
share-security mode.

When a profile is loaded, the API first deletes all existing uses
and shares.  If any share or redirection cannot be deleted, the profile
load fails.  Exception:  in user-security mode IPC$ and ADMIN$ are
not deleted, and any share record in the profile which relates to
IPC$ or ADMIN$ will be ignored.

  struct profile_load_info {
      short          pli_code;
      unsigned long  pli_resume_offset;
      char far *     pli_text;
      unsigned long  pli_retry_offset;
  };

The fields of this structure are explained in detail under NetProfileLoad.

Profile records are ASCII text, but should not be edited.  This is because
the profile parsing code depends on a very specific ordering of parameters
and presence of specific switches.  However, profiles may be edited if
the intention is to rename their extension to .CMD and to use them as
batch files.

-------------------------
24.1  NetProfileSave (Admin Only) 

Purpose: Write a copy of the current user profile into
         the specified file.

unsigned far pascal
NetProfileSave(servername, pathname, save_options, open_flags)
char far *      servername;     /* remote server or NULL if local */
char far *      pathname;       /* pathname of file to which to save profile */
unsigned long   save_options;   /* what to save in profile */
unsigned short  open_flags      /* file open flags */

Pathname, if not an absolute path, is taken to be relative to the
LANMAN root.  If no extension is supplied on the file, the extension
is assumed to be ".PRO".  To access a file which actually has no
extension, use an empty extension, e.g. "FOO.".

The save_options is a bitmapped field, with bits indicating which
part of the current network environment to save.  Current options are:

        Option            Bit   Mask  Result

        Uses               0     1    Save redirections as Net Use commands
        Shares             1     2    Save shares as Net Share commands
        Print Queue Info   2     4    Save print settings as Net Print commands
        Comm Queue Info    3     8    Save comm settings as Net Comm commands
        <reserved>        4..31

The open_flags parameter is passed to DosOpen as the open_flags for
opening the profile file.  This allows control over whether the
profile is to be overwritten, etc.  The following values are valid:

        0x2     Truncate exisitng file, fail if file does not exist
        0x10    Create file, or fail if file exists
        0x12    Create file, or truncate existing file

See the OS/2 documentation on DOSOPEN for more information on this
parameter.  Any error from DosOpen is returned without translation.

Returns: 0 if successful. Possible error returns:
    - NERR_NetNotStarted
    - NERR_WkstaNotStarted
    - ERROR_FILE_NOT_FOUND          (couldn't open specified file)
    - ERROR_PATH_NOT_FOUND          (some part of specified path is illegal)
    - ERROR_BAD_NETPATH             (server not found)
    - ERROR_NETWORK_ACCESS_DENIED   (admin privilege required)

-------------------------
24.2  NetProfileLoad (Admin Only) 

Purpose: Set the current user configuration from the specified file.

unsigned far pascal
NetProfileLoad(servername, pathname, start, buf, buflen, reserved)
char far *      servername;     /* remote server or NULL if local */
char far *      pathname;       /* pathname of file from which to restore */
unsigned long   start;          /* start offset (see below) */
char far *      buf;            /* buffer for returned information */
unsigned short  buflen;         /* length of buf */
unsigned long   reserved;       /* must be zero */

Pathname must be either a fully-qualified path, or a relative path with no
drive.  A relative path is taken as being relative to the standard
profile directory.  If no extension is supplied on the file, the extension
is assumed to be ".PRO".  To access a file which actually has no
extension, use an empty extension.  For example, assuming the
local machine has a LanRoot of C:\LANMAN:

    NetProfileLoad ( NULL, "X", ....
    NetProfileLoad ( NULL, "X.PRO", ....

        both load profile C:\LANMAN\PROFILES\X.PRO


    NetProfileLoad ( NULL, "X.", ....

        loads profile C:\LANMAN\PROFILES\X


    NetProfileLoad ( NULL, "D:\TMP\X", ....

        loads profile D:\TMP\X.PRO


    NetProfileLoad ( NULL, "\\MAINSERVER\PSHARE\STD.PRO", ....

        loads profile STD.PRO, from the remote file share PSHARE,
        on server MAINSERVER.


    NetProfileLoad ( NULL, "C:X", ....
    NetProfileLoad ( NULL, "\X", ....
    NetProfileLoad ( NULL, "..\X", ....

        are all illegal, the do not contain either a fully-qualified
        path or LanRoot-relative path.


    NetProfileLoad ( "\\SERVER", "X", ....

        executes NetProfileLoad remotely, on server SERVER.  The
        profile used will be X.PRO, in the SERVER's standard profile
        directory.


NetProfileLoad deletes all current uses and shares, then loads the
specified profile.  Network profiles are stored as ASCII files that
contain Net Use, Net Share, Net Print, and Net Comm commands.  These
commands are interpreted and executed by NetProfileLoad.  They can
also be used as batch files, if renamed to a ".CMD" extension.

If NetProfileLoad cannot find the profile specified, or cannot access the
file, or encounters a file-system error reading the file, NetProfileLoad
will return an error code.  Otherwise, EVEN IF THE PROFILE WAS NOT
FULLY EXECUTED, NetProfileLoad returns zero (success).  If NetProfileLoad
returns 0, the buffer will contain a "profile_Load_info" structure,
as defined above.  The fields will be used as follows:

 code           The error code of the command which failed, if any.

 text           The text of the command which failed, as an ASCIZ
                string.  If there is not enough room in the buffer 
                for the text, the pointer 'text' will be NULL.  

 resume_offset  See below

 retry_offset   See below

To determine if NetProfileLoad completed all commands, check the "code"
field in the return buffer.  If this is zero (success), then all
commands in the file were executed successfully.

If "code " is nonzero, one of the commands in the profile failed.
The "code" field is the error from that command, and "text" is the
text of the command.  (If "text" is NULL, the buffer was too small to
hold the text of the command).

The application may examine the command text and error code, and take
one of several courses of action:

     o  Abort the operation.  Give up on loading this profile.


     o  Skip over the bad command.  Call NetProfileLoad as before,
        except use the "resume_offset" from the buffer as the
        "start" parameter to the API.

        This is useful when the application wants to handle the 
        command itself, or when the application does not want to
        trouble with diagnosing such errors.


     o  Retry the command.  Especially useful if done after correcting
        something that caused the error.  For example, if a "NET SHARE"
        command line failed with an error indicating that the server
        had not been started, the application could start the server
        using NetShareAdd, and then retry this command in the profile.

        To retry a command, call NetProfileLoad as before, but use
        the "retry_offset" value from the buffer as the "start"
        parameter to the API.

        Do not do this is the error in the "code" field is
        NERR_ProfileUnknownCommand.  This means NetProfileLoad
        could not parse the command, so it isn't worth retrying.
        Use the "skip/resume" approach above.


Returns: 0 if successful. Possible error returns:
    - NERR_NetNotStarted
    - NERR_WkstaNotStarted
    - ERROR_FILE_NOT_FOUND              couldn't open specified file
    - ERROR_PATH_NOT_FOUND              some part of specified path is illegal
    - other OS/2 file error
    - NERR_ProfileFileTooBig            Profile file bigger than 64K
    - NERR_ProfileOffset                Start offset out-of-range
    - NERR_ProfileCleanup               Error deleting current uses or shares
    - NERR_ProfileUnknownCmd          * Unable to parse command line in file
    - ERROR_BAD_NETPATH                 server not found
    - ERROR_NETWORK_ACCESS_DENIED       admin privilege required

Errors with (*) will be returned only in the "code" field of 
profile_load_info.  Note again that any non-zero return from the
NetProfileLoad API means that the contents of the buffer are not
valid, and indicates a problem accessing or reading the file, not
just one command.  


25.   STATISTICS 

Theses calls allow interrogation and reset of the operating statistics
for the workstation and server components.  The statistics are
returned in a single structure as follows:

    struct statistics_info_0 {
        unsigned long   st0_start;        /* time statistics collection started   */
        unsigned long   st0_wknumNCBs;    /* # workstation NCBs issued            */
        unsigned long   st0_wkfiNCBs;     /* # workstation NCBs failed issue      */
        unsigned long   st0_wkfcNCBs      /* # workstation NCBs failed completion */
        unsigned long   st0_wksesstart;   /* # workstation sessions started       */
        unsigned long   st0_wksessfail;   /* # workstation session failures       */
        unsigned long   st0_wkuses;       /* # workstation uses                   */
        unsigned long   st0_wkusefail;    /* # workstation use failures           */
        unsigned long   st0_wkautorec     /* # workstation auto-reconnects        */
        unsigned long   st0_reserved1;       /* reserved for future use              */
        unsigned long   st0_reserved2;       /* reserved for future use              */
        unsigned long   st0_reserved3;       /* reserved for future use              */
        unsigned long   st0_reserved4;       /* reserved for future use              */
        unsigned long   st0_reserved5;       /* reserved for future use              */
        unsigned long   st0_reserved6;       /* reserved for future use              */
        unsigned long   st0_reserved7;       /* reserved for future use              */
        unsigned long   st0_reserved8;       /* reserved for future use              */
        unsigned long   st0_svfopens;     /* # of server file opens               */
        unsigned long   st0_svdevopens;   /* # of server device opens             */
        unsigned long   st0_svjobsqueued; /* # of server print jobs spooled       */
        unsigned long   st0_svsopens;     /* # of server session starts           */
        unsigned long   st0_svstimedout;  /* # of server session auto-disconnects */
        unsigned long   st0_svserrorout;  /* # of server sessions errored out     */
        unsigned long   st0_svpwerrors;   /* # of server password violations      */
        unsigned long   st0_svpermerrors; /* # of server access permission errors */
        unsigned long   st0_svsyserrors;  /* # of server system errors            */
        unsigned long   st0_svbytessent;  /* # of server bytes sent to net        */
        unsigned long   st0_svbytesrcvd;  /* # of server bytes received from net  */
        unsigned long   st0_svavresponse; /* average server response time in msec */
    };



NOTE:  A value of -1 or 0xffffffff for any field means that information
       is not available.


start           Time statistics collection started (see "timestamps" 
                in Chapter 1).   This field indicates the date/time 
                that the statistics were last cleared by NetStatisticsClear;  
                i.,e., it indicates the time period
                over which the returned statistics were collected.

wknumNCBs       Number of workstation NCBs issued.

wkfiNCBs        Number of workstation NCBs failed issue.

wkfcNCBs        Number of workstation NCBs failed completion.

wksesstart      Number of workstation sessions started.

wksessfail      Number of workstation session failures.

wkuses          Number of workstation uses.

wkusefail       Number of workstation use failures.

wkautorec       Number of workstation auto-reconnects.

reserved1       \
reserved2        \
reserved3         \
reserved4          \ reserved for future use, always -1 in this release
reserved5          /
reserved6         /
reserved7        /
reserved8       /

svfopens        Number of server file opens.

svdevopens      Number of server device opens.

svjobsqueued    Number of server print jobs spooled.

svsopens        Number of server session starts.

svstimedout     Number of server session auto-disconnects.

svserrorout     Number of server sessions errored out.

svpwerrors      Number of server password violations.

svpermerrors    Number of server access permission errors.

svsyserrors     Number of server system errors.

svbytessent     Number of server bytes sent to net.

svbytesrcvd     Number of server bytes received from net.

svavresponse    Average server response time in milliseconds.




25.1  NetStatisticsGet (Admin only) 

Purpose: Get operating statistics for workstation and server

unsigned far pascal
NetStatisticsGet( servername, buf, buflen, bRead, bAvail )
char far *           servername;    asciz remote server name or NULL if local
char far *           buf;           buffer for returned statistics
unsigned short       buflen;        size of buffer
unsigned short far * bRead;         bytes read
unsigned short far * bAvail;        bytes available

Buffer contents on return:

    struct statistics_info


Returns 0 if successful.  Possible error returns:
    - NERR_NetNotStarted
    - NERR_WkstaNotStarted
    - NERR_OS2IoctlError
    - ERROR_MORE_DATA

------------------------
25.2  NetStatisticsClear (Admin only) 

Purpose: Clear operating statistics for workstation and server

unsigned far pascal
NetStatisticsClear( servername )
char far *      servername;         asciz remote server name or NULL if local

Returns 0 if successful.  Possible error returns:
    - NERR_NetNotStarted
    - NERR_WkstaNotStarted
    - NERR_OS2IoctlError

Clears the workstation and server statistics for the specified server
and resets the statistics start time to the current date/time.


26.   NETBIOS 

These calls allow direct access to the NetBios.  Microsoft encourages
application programmers to consider using other means of network
communication, such as Mailslots or Named Pipes, which are more
independent of the transport implementation.

The NetBiosSubmit API allows applications to submit NCBs to NetBios
drivers under OS/2.  The format of NCBs is not discussed in detail
here.  One major change from real-mode NCBs is that, with Asycnronous
NCBs, the post-address field contains a semaphore handle, not the
address of a post function.  See the Protected-Mode NetBios
information below.

An application should use the calls NetBiosOpen and NetBiosClose to
obtain and release and handle to the NetBios driver.  This handle is
intended for use with the NetBiosSubmit command.  Alternatively,
applications which use only a small number of NCBs can use the
reserved handle value 0 when submitting NCBs.  Such NCBs will be
submitted to the first network driver, and implicit calls to Open and
Close are perfomed.  Due to the various modes in which the driver can
be opened (see NetBiosOpen), Microsoft encourages applications to use
NetBiosOpen and CLose explicitly to obtain a handle.

NOTE:  Lan Manager for OS/2 supports all NCBs under real mode in the
compatibility box, except that Async NCB's may not have post addresses,
the application must poll for completion.  NCBs in real mode are
submitted using the same method as always for real mode NetBios
access, and not these APIs.


    struct netbios_info_0 {
        char            nb0_net_name[NETBIOS_NAME_LEN+1];
    };

    struct netbios_info_1 {
        char            nb1_net_name[NETBIOS_NAME_LEN+1];
        char            nb1_driver_name[DEVLEN+1];
        unsigned char   nb1_lana_num;
        char            nb1_pad_1;
        unsigned short  nb1_driver_type;
        unsigned short  nb1_net_status;
        unsigned long   nb1_net_bandwidth;
        unsigned short  nb1_max_sess;
        unsigned short  nb1_max_ncbs;
        unsinged short  nb1_max_names;
    };


net_name        Name of the network.  This is defined in the LANMAN.INI
                file under the "networks" component, which is read by
                the portion of Lan Manager installed at boot time.

driver_name     The name of the OS/2 device driver which supports this
                network.

lana_num        Lan adapter number of this network.  A single driver may 
                drive more than one Lan Adapter, so this distinguishes
                amongst the various network cards controlled by this 
                driver.

driver_type     Network driver type.

                   Val  Type            Symbol (netbios.h)

                    1  NCB driver       NB_TYPE_NCB
                    2  MCB driver       NB_TYPE_MCB

net_status      Bitmapped field, defined as:

                  Bit

                   0    Net Managed by Lan Manager
                   1    This driver is a Loopback driver.
                 2-13   <reserved>
                14-15   Open status, values of these two bits means:

                                0    net not opened          
                                1    opened in regular mode    
                                2    opened in privileged mode 
                                3    opened in exclusive mode  

                The open status will be set to (2) if any process has the
                net open in privileged mode, even though other processes
                may simultaneously have it open in regurlar mode.

                See NetBiosOpen for details on the different open
                modes.


net_bandwidth   Raw network bandwidth in bits-per-second.

max_sess        Maximum number of sessions.

max_ncbs        Maximum number of outstanding NCBs.

max_names       Maximum number of names.


These calls should include "ncb.h" and "netbios.h".



-------------------------
26.1  NetBiosEnum (Admin Only) 

Purpose: Enumerate NetBios drivers.

unsigned far pascal
NetBiosEnum(servername, level, buf, bufLen, entriesRead, totalEntries)
char far *            servername;     /* Name of target PC (null if local) */
short                 level;          /* Level of info requested */
char far *            buf;            /* Pointer to info buffer */
unsigned short        bufLen;         /* Byte length of info buffer */
unsigned short far *  entriesRead;    /* # of entries supplied on return */
unsigned short far *  totalEntries;   /* total # of entries available */

Buffer contents on response (format for a single entry):
    Level 0 contains a "struct netbios_info_0".
    Level 1 contains a "struct netbios_info_1".

Returns 0 if successful. Possible error returns:
    - ERROR_MORE_DATA             buffer too small for all data
    - NERR_NetNotStarted        network software not installed

-------------------------
26.2  NetBiosGetInfo (Admin Only) 

Purpose: Get information about a given NetBios driver.

unsigned far pascal
NetBiosGetInfo(servername, netBiosName, level, buf, buflen)
char far *     servername;        /* Name of target PC (null if local)  */
char far *     netBiosName;       /* NetBios network name               */
short          level;             /* Level of info requested            */
char far *     buf;               /* Pointer to info buffer             */
unsigned short buflen;            /* Byte length of info buffer         */
unsigned short far * totavail;    /* Total bytes available              */

    Level 0 contains a "struct netbios_info_0".

    Level 1 contains a "struct netbios_info_1".

Returns 0 if successful. Possible error returns:
    - NERR_BufTooSmall          buffer too small for any data
    - ERROR_MORE_DATA             buffer too small for all data

-------------------------
26.3  NetBiosOpen 

Purpose: Get a handle to a NetBios driver.

unsigned far pascal
NetBiosOpen(netBiodName, netReserved, netOpenOpt, netHandle)
char far *           netBiosName;  /* Name of NetBios network */
char far *           netReserved;  /* Reserved pointer; must be 0 */
unsigned short       netOpenOpt;   /* Open options */
unsigned short far * netHandle;    /* Word for returned handle */

Creates a handle for sending NCBs to a NetBios driver.  A program can
determine what these names are by calling NetBiosEnum.  The null
string can be used as device name to refer implicitly to the first
installed NetBios driver.

NetOpenOpt is bitmapped as follows:

        Bits    Use

        0,1     Access Mode  (more information below)

                  0  <reserved>
                  1  NB_REGULAR
                  2  NB_PRIVILEDGED
                  3  NB_EXCLUSIVE

        2-15    <reserved>


The ACCESS MODE specifies how the opener is willing to share access
to the NetBios driver with other processes.  

   NB_REGULAR:  Any number of processes may open a driver in regular 
   mode.

   NB_PRIVLEDGED:  On process may open the driver in privileged mode.
   This mode is comptaible with NB_REGULAR;  other processes may open 
   the driver in regular mode, even while it is opened by a single
   process in privileged mode.  A privileged open will fail if any
   other process has a current *privileged* or *exclusive* open 
   handle to the driver.

   NB_EXCLUSIVE:  One and only on process may open the driver, if that
   process opens it in exclusive mode.  The open will fail if any
   other process has a current open handle to the driver.

NCB operations are restricted depending on the access mode of the
opener:

  o Regular:     Does not allow Reset, Receive Broadcast
                 Datagram, Receive Any-to-Any NCBs, or
                 use of permanent names in any NCB.

  o Privileged:  Does not allow Reset or Receive Any-to-Any.

  o Exclusive:   Any NCB operation is allowed.



Returns 0 if successful. Possible error returns:
   ERROR_FILE_NOT_FOUND         - netbios driver does not exist
   ERROR_ACCESS_DENIED          - open-mode conflict with existing open(s)
   ERROR_INVALID_PARAMETER      - invalid options


NOTE: A netbios handle is a process-to-driver association.  Only the
process that opened the handle may use it.

-------------------------
26.4  NetBiosClose 

Purpose: Close a NetBios driver handle.

unsigned far pascal
NetBiosClose(netHandle, netReserved)
unsigned short   netHandle;           /* Handle to close */
unsigned short   netReserved;         /* Reserved, must be zero */

Terminates access to a NetBios driver, invalidates the handle, and
cancels any NCBs issued by the process that owned the handle.

Returns 0 if successful. Possible error returns:

    ERROR_INVALID_HANDLE        invalid handle
    ERROR_ACCESS_DENIED         networks not started

-------------------------
26.5  NetBiosSubmit 

Purpose: Passes an NCB to a NetBios driver.

unsigned far pascal
NetBiosSubmit(netHandle, netNCBOpt, netNCB)
unsigned short    netHandle;      /* Handle to issue NCB against */
unsigned short    netNCBOpt;      /* Option flags */
struct ncb far *  netNCB;         /* Address of NCB */

NetHandle is a handle returned from a previous call to NetBiosOpen,
or else 0.  A handle of 0 always refers to the first installed
NetBios driver.  This driver will be automatically NetBiosOpen'ed if
necessary (in regular access mode) the first time a NetBios call
refers refers to it using the 0 handle.

NetNCB points to the NCB to be executed (unchained NCB) or to the
link word preceding the NCB (chained NCB, see below).  The caller
need not fill in the ncb_lana_num field, this will be done based on
the netHandle used.  

If the NCB is an asynchronous NCB, the ncb_post field of the NCB
should be zero, or a SYSTEM SEMAPHORE HANDLE.  If a handle is given,
that semaphore will be cleared upon completion of the NCB.  The system
semaphore must be "public", i.e. created without the "exclusive"
option.

NetNCBOpt specifies NCB processing options, which include:

          Chaining:    0  Single NCB is being passed
          (mask 0x3)   1  Single NCB with error retry
                       2  NCB chain with proceed-on-error
                       3  NCB chain with stop-on-error

          The chaining option specifies whether a single NCB
          or an NCB chain is being passed.  A single NCB can
          be executed with optional error retry, in which
          case the net kernel will reissue the NCB a set
          number of times in response to the following
          errors:

                       09H - No resource available
                       12H - Session open rejected
                       21H - Interface busy

          Chained NCBs must be in the same segment and are
          linked by a 16-bit offset pointer that precedes the
          NCB.  An offset of 0xFFFF specifies the end of
          chain.

          Although any sequence of NCB commands may be
          chained, not all possibilities are useful.  For
          example, you can't open a session and send a
          data packet on it by chaining the Send to the Call,
          because the NCB_LSN field returned in the Call
          NCB must be copied into the Send NCB, and the
          net kernel support doesn't do this automatically.


          The following NCB errors are retried when the Error retry
          option is selected
                NCB_ERR_NR
                NCB_ERR_SOR
                NCB_ERR_BUSY

          A stop-on-error chain is terminated by the net
          kernel when an NCB in the chain causes an error.
          NCBs that were not processed because of an error
          earlier in the chain will have their NCB_CMD_CPLT
          field set to 0xB (Command Cancelled).  This kind
          of chain should normally have wait-mode NCBs only.
          No-wait NCBs are accepted, but in this case it is
          the immediate return and not the final return that
          determines whether the chain stops or proceeds.


          A proceed-on-error chain call will return to the caller
          the completion code returned by the last NCB in the chain.


Returns 0 if successful. Possible error returns:

    ERROR_INVALID_HANDLE        invalid handle
    NCB_ERR_NR                  (No Resource) either No Resource OR Not Started
    ERROR_INVALID_PARAMETER     invalid options


    - netBios-defined immediate return codes (no wait NCB)
    - netBios-defined final return codes (wait mode NCB)


27.   REMOTE UTILITIES 

These APIs provide access to certain remote functions offered by
LAN Manager server.  The funtions are NetRemoteTOD, NetRemoteCopy,
NetRemoteMove, and NetRemoteExec.

NetRemoteCopy does optimized remote file copies.  Files on remote
servers are copied without moving the data to and from the
local workstation.

NetRemoteMove moves directory entries from one place to another
on a remote file system, without physically copying data if the
source and dest are on the same drive (and without copying data
to and from the local workstation if the source and dest are on
different drives).

NetRemoteExec provides a mechanism for executing programs on a
remote CPU.

NetRemoteTOD provides a means to access time-of-day information on
a remote server.

   struct copy_info {
       unsigned short  ci_num_copied;
       char            ci_err_buf[1];
   };


   struct move_info {
       unsigned short  mi_num_moved;
       char            mi_err_buf[1];
   };


   struct time_of_day_info {
       unsigned long   tod_elapsedt;    /* time from 1-1-1970 in seconds */
       unsigned long   tod_msecs;       /* milliseconds */
       unsigned char   tod_hours;       /* hours */
       unsigned char   tod_mins;        /* minutes */
       unsigned char   tod_secs;        /* seconds */
       unsigned char   tod_hunds;       /* hundredths */
       unsigned short  tod_timezone;    /* time zone in minutes from GMT */
       unsigned short  tod_tinterval;   /* timer interval (units = 0.0001 sec */
       unsigned char   tod_day;         /* day */
       unsigned char   tod_month;       /* month */
       unsigned short  tod_year;        /* year */
       unsigned char   tod_weekday;     /* day of week */
   };

-------------------------
27.1  NetRemoteTOD 

Purpose: Return the time of day information from a specified server.

unsigned far pascal
NetRemoteTOD(server, buf, buflen)
char far *  servername;         /* remote server or NULL if local */
char far *  buffer;             /* Buffer for retured data */
unsigned short buflen;          /* Buffer length */

On return, buffer contains struct time_of_day_info.

Returns 0 if successful. Possible error returns:
    - NERR_BufTooSmall

------------------------
27.2  NetRemoteCopy 

unsigned far pascal
NetRemoteCopy( sourcepath, destpath, sourcepass, destpass, openflags,
copyflags, buf, buflen, )
char far *          sourcepath;     ASCIIZ source path
char far *          destpath;       ASCIIZ dest path
char far *          sourcepass;     password for source path (NULL for default)
char far *          destpass;       password for dest path (NULL for default)
unsigned short      openflags;      flags for open of destpath; see below
unsigned short      copyflags;      flags to control the copy; see below
char far *          buf;            buffer to return error text in
unsigned short      buflen;         size of buffer on call;

Purpose:  Copy a file or files from one path to another, with network
optimization.

In this release of LAN Manager, both sourcepath and destpath
must refer to paths on the same server or an error is returned.
The following cases are valid:

1. Source and dest are both file names.  The source file is copied to
   the destination file, subject to open and copy flag options.

2. Source is a file name or template and dest is a directory name.
   The source file(s) are copied into the destination directory, subject
   to open and copy flag options.

The openflags bit field mapping is:

       1111 11
       5432 1098 7654 3210
       rrrr rrrr rrrC rrOO

  where:
       O - Open (action to be taken if destination file exists).
         0 - Fail.
         1 - Append file.
         2 - Truncate file.

       r - reserved (must be zero).

       C - Create (action to be taken if destination file does not exist).
         0 -- Fail.
         1 -- Create file.

The copyflags bits have the following meaning:
        bit 0 - destination must be a file.
        bit 1 - destination must be a directory.
        bit 2 - copy destination mode: 0 = binary, 1 = ascii.
        bit 3 - copy source mode: 0 = binary, 1 = ascii.
        bit 4 - verify all writes.

Buffer contents on response:
        copy_info structure

Returns 0 if successful.  Possible error returns:
    - ERROR_FILE_NOT_FOUND
    - ERROR_PATH_NOT_FOUND
    - ERROR_ACCESS_DENIED
    - ERROR_NO_MORE_FILES
    - ERROR_SHARING_VIOLATION
    - ERROR_FILE_EXISTS
    - NERR_BufTooSmall
    - NERR_BadSource
    - NERR_BadDest
    - NERR_DifferentServers
    - NERR_NetNotStarted
    - NERR_OS2IoctlError

------------------------
27.3  NetRemoteMove 

unsigned far pascal
NetRemoteMove( sourcepath, destpath, sourcepass, destpass, openflags,
moveflags, buf, buflen, )
char far *          sourcepath;     ASCIIZ source path
char far *          destpath;       ASCIIZ dest path
char far *          sourcepass;     password for source path (NULL for default)
char far *          destpass;       password for dest path (NULL for default)
unsigned short      openflags;      flags for open of destpath; see below
unsigned short      moveflags;      flags to control the move; see below
char far *          buf;            buffer to return error text in
unsigned short      buflen;         size of buffer on call;

Purpose:  Move a file or files from one path to another with network
optimization.

In this release of LAN Manager, both sourcepath and destpath
must refer to paths on the same server or an error is returned.
The following cases are valid:

1. Source and dest are both file names.  The source file is moved to
   the destination file, subject to open and move flag options.

2. Source is a file name or template and dest is a directory name.
   The source file(s) are moved into the destination directory, subject
   to open and move flag options.

Note that if the source and dest paths are in the same directory, this
call accomplishes a rename.  If they are different directories on the
same server drive, the move is accomplished without physically copying
data.  If the paths are on different drives, the files are individually
copied to the destination drive and then deleted from the source drive.

Buffer contents on response:
    move_info structure

The openflags bit field mapping is:

       1111 11
       5432 1098 7654 3210
       rrrr rrrr rrrC rrOO

  where:
       O - Open (action to be taken if destination file exists).
         0 - Fail.
         1 - Append file.
         2 - Truncate file.

       r - reserved (must be zero).

       C - Create (action to be taken if destination file does not exist).
         0 -- Fail.
         1 -- Create file.

The moveflags bits have the following meaning:
        bit 0 - destination must be a file.
        bit 1 - destination must be a directory.
        bit 2 - reserved (must be zero)
        bit 3 - reserved (must be zero)
        bit 4 - reserved (must be zero)

Returns 0 if successful.  Possible error returns:
    - ERROR_FILE_NOT_FOUND
    - ERROR_PATH_NOT_FOUND
    - ERROR_ACCESS_DENIED
    - ERROR_NO_MORE_FILES
    - ERROR_SHARING_VIOLATION
    - ERROR_FILE_EXISTS
    - NERR_BufTooSmall
    - NERR_BadSource
    - NERR_BadDest
    - NERR_DifferentServers
    - NERR_NetNotStarted
    - NERR_OS2IoctlError

------------------------
27.4  NetRemoteExec 

NetRemoteExec is a network extension of the DosExecPgm API.  The
exec'ed program is run on a remote Lan Manager server.  It is 
otherwise identical to the DosExecPgm API, with the following
limitations:

1. AsyncTraceFlags must have a value of 0 (synchronous), 1 (asynchronous
   without result code), or 2 (asynchronous with result code).

2. The program filename must be of the form filename[.ext].  The name
   must not include path separators or a drive letter.  The program
   filename is located according to path searching rules configured
   at the server.

3. The remotely exec'ed process only inherits handles 0, 1, and 2.
   The inherited handles are stdin, stdout, and stderr.

4. The envinoment pointer can not be NULL for this release of
   LAN Manager.

5. The TerminateCode in the ResultCodes struct upon return is meaningless.

The exec'ed process is run on the CPU connected to the caller's current
drive.  If the caller's current drive is on a remote LAN Manager server,
the child process is exec'ed on that server.  If the caller's current
drive is a local disk, the child is exec'ed locally.

The limitations above (1 - 5), are only enforced when the exec is done on
a remote LAN Manager server.

The child process's current drive and current directory are the
same as the calling program's current defaults.  When remote, the process
will (in most cases) have a different drive letter and directory
path.  The drive and directory referred to will, however, be the
same.

This is best illustrated by example.

        - The server shares c:\foo as c_foo.
        - The wksta redirects g: \\server\c_foo.
        - The wksta's current drive is g:
        - The wksta's current directory on g: is g:\bar.

On the server, the NetRemoteExec'ed program's current drive will be c:,
and its current directory will be c:\foo\bar.

When asynchronous execution is requested, the PID returned
in the first word of ReturnCodes is a valid local PID that represents
the remote program.  It is valid to use DosFlagProcess on this PID to
send signals to the remote programs.  Similarly, it is valid to issue
DosCWait to wait for the remote program to exit, or DosKillProcess to
kill it.

unsigned far pascal
NetRemoteExec( reserved1, objnamebuf, objnamebufl, asynctraceflags, argpointer,
envpointer, returncodes, pgmpointer, reserved2, remexecflags)
char far *          reserved1;      must be 0xFFFFFFFF 
char far *          objnamebuf;     address of object name buffer
unsigned            objnamebufl;    length of object name buffer
unsigned            asynctraceflags;  execute async / trace flags
char far *          argpointer;     address of Argument strings
char far *          envpointer;     address of Environment string
struct ResultCodes far * returncodes;  address to put termination codes
char far *          pgmpointer;     address of program filename
char far *          reserved2;      must be 0
unsigned short      remexecflags;   RemExec Flags.  Bit map is below.

remexecflags bit map:

bit 0:          0 - use msg mode pipe for std in
                1 - use char mode pipe for std in
bit 1:          0 - CWait for process tree before returning ExitCode to Ghost
                1 - CWait for exec'ed process before returning ExitCode to Ghost
bit 2:          0 - Map SIGINTR and SIGBREAK to SIGKILL when remoting signals
                1 - Send signals as received
others:         must be 0


Returns 0 if successful.  In addition to the DosPgmExec errors, the
following are other possible error returns:
    - ERROR_INVALID_PARAMETER
    - NERR_ErrConnRunSrv
    - NERR_ErrCommRunSrv
    - NERR_InternalError
    - NERR_ErrorExecingGhost
    - NERR_RunSrvPaused
    - NERR_PgmNotFound
    - NERR_ShareNotFound
    - Error returned by DosExecPgm
28.   Standard Lan Manager Services 

The Microsoft OS/2 Lan Manager includes the following
standardized network service components:


                W S P U (*)
                -------

   WORKSTATION      x x         Main Lan Manager service.

   MESSENGER    x     x         Recieves messages.

   NETPOPUP     x     x         Displays recieved messages.

   SPOOLER      x     x         Manages print queues.

   SERVER       x   x x         Provides resources to the network.

   ALERTER      x x   x         Monitors alert events and sends messages
                                  about them.

   RUNSERVER    x x x x         Allows remote process execution.

   NETLOGON     x x   x         Provides for centralized user/password
                                  verification.


  (*) W -- requires Workstation service installed
      S -- requires Server service installed
      P -- is pausable (see below for what "paused" means to each service)
      U -- in uninstallable



28.1  Workstation Service 

The workstation service is the primary service of Lan Manager.
It maintains much of the internal information and activiates
the networking capabilities of the NetBios drive and the part
of Lan Manager that is installed at boot time.

The workstation is both pausable and uninstallable.  

NOTE: so long as the SERVER is installed, the WORKSTATION cannot be
uninstalled.  Any uninstall command sent to it will be ingored, and
the WORKSTATION will remain in the installed state.

Pausing the workstation pauses printer and/or comm redirection.  All
remote devices of that type that are already opened can still be
used, but new connections canot be made, and once closed, existing
redirections cannot be reopened.  Any DosOpen against a device name
will open a LOCAL device of that name, as long as the workstation is
paused.

The workstation componments are paused and continued (un-paused)
using NetServiceControl and the SERVICE_CTRL_PAUSE / CONTINUE
opcodes.  The "arg" parameter is defined as follows:

        Bit       Pauses/continues

         0              <reserved>
         1       Print redirection
         2       Character device redirection
        3-8             <reserved>

When the workstation is paused in any way, bits 8-10 in the
status word indicate what is paused:

         8              <reserved>
         9       Print redirection
        10       Character device redirection


28.2  Server Service 

The Server provides the functions necessary to share local resources
with the network.

Pausing the server causes it to refuse all further session,
connection, and open functions.  Existing open files and devices
continue to be serviced.


28.3  Spooler Service 

The Spooler service maintains the spooled print queues.  This service
is usually installed on a server, and must be installed to use many
of the DosPrint APIs locally.

Uninstalling the spooler cancels all currently printing jobs but
leaves them in queue.  Queue contents are maintained so that printing
of the jobs that were interrupted can restart, and all submitted jobs
will resume their places in the queue, the next time the spooler is
started.


28.4  Messenger Service 

The Messenger service recieves messages sent from remote stations
which use the NetMessage APIs.  It can log these messages to a file
or device.  See the NetMessage APIs for more information on logging 
messages.

The Messenger service will also write messages it recieves to a mailslot,
which is usually monitored by NetPopup (below).

The Messenger must be installed in order to use many of the NetMessage
APIs.  Exceptions are NetMessageBufferSend and NetMessageFileSend.


28.5  Alerter Service 

The Alerter is provided as a convenient way to use the Alert ssytem
described under the NetAlert APIs.  You should read that section
before attempting to understand the following explanation.  In
summary, the Alerter monitors events on the local machine, and
sends messages about occuring events, to the users who who
be interested. 

The Alerter registers it self to recieve all PRINT, ERROR and ADMIN
alerts on the machine on which is in installed.  It registers itself
as a mailslot client, so it can recieve full information about these
events. When it recieves an alert, the Alerter converts the
information on the event into text and sends a message using the
NetMessageBufferSend API.  

When it recieves a PRINT event, if the event is a normal printing
event and not a printer problem, the Alerter sends the message only to the
user who printed the job.

When it recieves an ADMIN or ERROR event, the Alerter sends 
the message to all users listed in the field "sv2_alerts", 
obtained from NetServerGetInfo.




    Spooler  -- print alerts ----+
                                 |
    Server  --- security alerts -+
                                 +--->  NetAlertRaise API ----+
    Other services  -------------+                            |
                                 |                            |
    Other apps ------------------+
                                                         through local
                                                           mailslot
                                    
                                                              |
            NetMessageBufferSend  <------  ALERTER  <---------+
                                    text              event
                       |
                . . . .|. . . .
                       |
                       |
               +-------+----------+----------- - ->
               |                  |
          . . .|. . .        . . .|. . .
               |                  |
               |                  |
               V                  V

         Remote Messenger    Remote Messenger 
            Service             Service



28.6  NetPopup Service 

NetPopup reads messages from a mailslot, which is written to by
the Messenger Service.  These messages are displayed in a popup screen.

NetPopup is not pausable.


28.7  RunServer Service 

The RunServer supports remote execution of processes.  Remote
machines which want to execute processes on a server, communicate
through the NetRemoteExec API with the RunServer service, running
on that server.

Pausing the RunServer does not effect any current running processes,
but new requests (via NetRemoteExec) will be rejected with the
error NERR_RunSrvPaused.

When Uninstalling, the RunServer will attempt to stop all processes
it has started.  It issues a DosKillProc on each one.  This can
fail if the processes have installed signal handlers and choose to
ignore the Kill.  No errors are logged in this case.


28.8  NetLogon Service 

The NetLogon service provides centralized logon and user/password
verification.  This is described in the Network Administrator's
Guide.



29.   Writing Lan Manager Service Programs 

Lan Manager services are programs which conform to certain rules
of behaviour, detailed below.  Such programs can then be
controlled and interrogated using the NetService APIs.


29.1  Summary of Service Program Requirements 

A service program consist of at least one OS/2 executable file,
and must follow all the rules listed below.  There is no restriction
on size, type of application, etc.

The rules in general are:

     o  The service program executable file name must be listed in 
        the LANMAN.INI file.

     o  The service program itself will be executed in detached mode,
        and cannot access screen or keyborad functions except
        through a popup (see VioPopup).

     o  The service program must notify Lan Manager of changes in
        status, using the NetServiceStatus command.

     o  The service program must respond to signals sent by the
        NetServiceControl API.


29.2  Services and LANMAN.INI 

Services must be listed in the LANMAN.INI file under the [services]
component.  The entry consists of the service name, and '=', and the path
of the executable module used to start the service.  


        [services]
            carwash = c:\bin\carwash.exe
            billing = c:\bin\billinit.exe

Note that the module named in LANMAN.INI need not contain the entire
service program.  This module may execute other modules, link to
dynamic libraries, etc.  If you are planning on using multiple
processes within your service, see the section below on Multi-Process
Services.

A service program may also store configuration information in the
LANMAN.INI file.  This information should be stored in the standard
LANMAN.INI format show below (see NetConfig APIs for more detail).

        [component]
            parameter = value

In this case, the component name should be the same as the name of the
service, as listed under [services].  Following our example above:

        [carwash]
           ourname = Jiffy Car Wash Service
           waxcost = $2.00
           raining = no
           gallons_per_car = 100

Note that the parameter strings can have any string as the "value".
Once again, consult NetConfig APIs for more information.

IMPORTANT:  When a service is started, using the DosExecPgm call
(from inside NetServiceInstall), ALL THE INFORMATION in that service's
section of the LANMAN.INI file is provided on the command line passed
to the service.  The service program does not need to read the INI
file using NetConfigGet or NetConfigGetAll, provided that the
information is stored under a component name the same as the service
name.

More information on how this information is formatted, is provided
below under Life of a Service, Installation.


29.3  A Day in the Life of a Lan Manager Service Program 


Here is a brief overview of the life-cycle of a Lan Mmanager service.
Details of each step are discussed below.  This summary is
intended only to give an overall feel of the complete cycle.


  The service program starts, having been executed by NetServiceInstall.

  The service briefly verifies it's parameters, and if there is a
problem, notifies Lan Manager (via NetServiceStatus) and terminates.

As soon as possible, the program installs a signal handler to interact
with NetServiceControl, and then sets it's status to INSTALL_PENDING.

The service completes it's installation, busily twiddling bits and
tweaking I/O devices or whatever.  If this takes a long time, it
should periodically update it's status so that Lan Manager knows the
service is not dead.

When the service is ready, it sets it's status to INSTALLED.

During the service's working period, it will occaisionly recieve
signals (commands), which are handled by it's signal handler.
Such commands could be requests to pause service, continue service
after being paused, etc.

After a hard day's work, the service may recieve the command to
uninstall (shut down) from NetServiceControl.  The service
should immedialtely set it's status to UNINSTALL_PENDING, and
begin to shut down.

After completely shutting down, just before calling DosExit, the
service set's it's status to UNINSTALLED.


29.4  Communication Amongst Applications, Lan Manager, and the Service 


Each call to NetServiceControl generates a signal to the service
being controlled.  The service responds via NetServiceStatus.


    Application         LAN Manager             Service
    -----------         -----------             -------


      calls NetServiceControl

               |
               +------->  sends signal
                          to service   -------> Signal handler
                                                interprets command.


                          updates service <---  calls NetServiceStatus
                          info table

                                |
      NetServiceControl  <------+
        returns to app 
        with info about
        service.


It is essential that the service respond promptly.  If the operation
is going to take a while to complete, the service should reply with
some intermediate state (such as UNINSTALL_PENDING), and only then
go on to complete the operation.


29.4.01 Services and NetServiceControl 


Applications, or even other services, call NetServiceControl to
interrogate or control services.  The API has four defined commands
which get passed to the service thorugh the signal mechanism (see
below).

    SERVICE_CTRL_INTERROGATE    0       Interrogate only
    SERVICE_CTRL_PAUSE          1       Pause service
    SERVICE_CTRL_CONTINUE       2       Continue service
    SERVICE_CTRL_UNINSTALL      3       Uninstall (shut down) service

Besides the opcode, an eight-bit "argument" is passed, with the value
given to the "arg" parameter passed to NetServiceControl.  This
argument may be defined by the service as a sub-opcode or for
whatever other information might be appropriate.  Of course,
only applications which know what the service expects in this
parameter will use it correctly.  The service should always make a
reasonable interpretation of an "arg" set to zero.

A service is not required to accept PAUSE or UNINSTALL commands.
However, a service which will not UNINSTALL at all will prevent the
Lan Manager workstation from being shut down.  The ability of a
services to indicate that it will not accept UNISTALL commands is
meant to be used briefly, i.e. while a service is performed some
extended operation that cannot be interrupted.

While a service is in the INSTALL_PENDING state, the only command it
will recieve (currently) is UNINSTALL.  While the service is in
the UNINSTALL_PENDING state, it will recieve no commands or signals
from NetServiceControl.

Commands from NetServiceControl which are not approproiate to the
service state will be rejected at the API level, and not reach the
service.  Exception:  INTERROGATE commands can often be satisfied
by getting information from the table without signalling the service.
This is done whenever the service is not INSTALLED.


29.4.02 Services and NetServiceStatus 

The service status is set by calling NetServiceStatus.  See the API
documentation for a summary of the parameters and the structure which
is passed in the buffer.  Information presented there is not
duplicated here.

If you get an error calling NetServiceStatus, use the error log
to record such an event, and if approproate, shut down the service.
If possible, retry the call to NetServiceStatus severla times.
See NetErrorLogWrite for recording entries in the error log.

The service program must set the status word every time NetServiceStatus
is called.  Be sure to "or" together all the bits which are pertinent.

Note the various values that may be used in the "code" field.  When
 the
code field does not have defined set of values, such as when the
service is fullly INSTALLED, set the "code" field to zero.

The "pid" field should normally be zero.  See below, under Multi-Process
Services, for use of the "pid" field.  Be careful not to set this
acidentally or your service will be unable to communicate further
with Lan Manager.

NOTE:  On every call to NetServiceStatus, the service is setting the
WHOLE STATUS STRUCTURE, including status, code and pid (*).  Be sure
that the status set includes the proper values for the bits which
indentify the service as pausable, uninstallable, etc.


29.4.03 Other NetService APIs. 

Services should not be disturbed by the other NetService APIs.  These
APIs (GetInfo, Enum) are handled by Lan Manager and do not require
interaction with the service(s).


29.4.04 The Signal Handler 


When initializeing your service, you should register a function as
a signal handler for the FlagA signal.  This signal is opcode 5 to
DosSetSigHandler.  A constant SERVICE_RCV_SIG_FLAG is defined in
"service.h" containing this value.

The service will recieve the FlagA signal from NetServiceControl.
The service should respond to the signal promptly, by performing the
requested action, calling NetServiceStatus, and then re-enabling the
signal.

The signal handler should be robust and treat all unrecognized
opcodes as INTERROGATE.

If the requested task will take some time, the service should set it's
status to a PENDING state, and set the final state when the task is
complete.

The general format of a signal handling function written in C is:

    void far pascal 
    signal_handler(sig_arg,sig_no)
    unsigned sig_arg;
    unsigned sig_no;
    {
        struct service_status svci;

        unsigned char opcode;   /* Opcode parameter from NetServiceControl */
        unsigned char arg;      /* Arg parameter from NetServiceControl */
    
        opcode = (unsigned char)(sig_arg & 0xff);
        arg    = (unsigned char)((sig_arg >> 8) & 0xff);

        /* Set up default values for NetServiceStatus buffer */

        svci.svcs_pid = 0;
        svci.svcs_status = SERVICE_INSTALLED | SERVICE_UNINSTALLABLE ;
        svci.svcs_code = 0L;
    
        switch (opcode)
        {
                default:        /* Treat unknown commands as "interrogate" */
                case SERVICE_CTRL_INTERROGATE:

                     set_wksta_status ( & svci );
                     break;
    
                     break;


                /* Handle other opcodes as appropriate ..
                 *      :
                 *      :
                 */
    
                case SERVICE_CTRL_UNINSTALL:

                     svci.svcs_status = SERVICE_UNINSTALL_PENDING;
                     set_wksta_status ( &svci );
    
                     Terminate();
        }
    
        /* Issue a 'reset' for this signal */

        DosSetSigHandler(0,0,0,SIG_RESET,sig_no);

        return;
    }


WARNING:  If you write your handler in C, the source module in which
the handler is written must be compiled using the auto-load DS
option.  This is a part of the -A compiler option.  Without this, the
DS register will not be loaded to the service program's default data
segment when the handler is called and the code in the handler may
make incorrect assumptions about the location of data.  See your
compiler manual for more information.

Signal handlers should preserve registers as noted in the OS/2
documentation on writing signal handlers.
    

    

29.5  Service Startup 

When an application, including the Lan Manager user interfaces,
want to start a service, it calls NetServiceInstall (q.v.).
The module named in the [services] section of LANMAN.INI as the
executable portion of a certain service, is loaded via a
DosExecPgm call from within NetServiceInstall.

The program is executed in DETACHED MODE, and inherits no (????)
handles from the parent process.  The service thus cannot use screen
or keyboard calls, except through popups (see VioPopup). 

A service will recieve a copy of the environment of the parent,
i.e. the caller of NetServiceInstall.

The service will recieve a "command line" consisting of a merger
of the service's information in LANMAN.INI (see ???? above) and
information passed into NetServiceInstall through the "cmdargs"
parameter.

As soon as possible after startup, the service program should
register a signal handler using DosSetSigHandler (see above) and set
it's status to INSTALL_PENDING using the NetServiceStatus API.

If the service is going to take a while (more that a second or two)
to install, it should make provisions to use the IP codes described
under the NetService APIs.

If during installation a service encounters a "fatal error" and
decides to abort installation, the service should set it's status to
UNINSTALLED (or UNINSTALL_PENDING) and shut down.  The last call to
NetServiceStatus MUST set status to UNINSTALLED.  The service is
strongly encouraged to use the UIC codes (see NetService APIs) to
provide a clue as to why installation failed.  See Service Shutdown 
below.


29.6  Service Operation 

During normal operation the service's signal handler, discussed above,
will recieve INTERROGATE requests, and possibly PAUSE or CONTINUE
reuqests (discussed below).  The signal handler may act on these
in whatever way is appropriate.  For example, it may set a global
flag or variable, clear a semaphore, etc.  

Services which are temporarily unable to install, perhaps due to the
processing of some extended task that must be completed, can set the
bit SERVICE_NOT_UNINSTALLABLE in the status field.


29.7  Service Pause and Continue 

A service defines what is meant by pause and continue.  See the
documentation on the standard Lan Manager services for several
interpretations of Pause and Continue.

The service may define various values for the parameter "arg"
which is passed to NetServiceControl.  Note that the generic
"Pause" signal, for example from NET PAUSE <service>, normally
hs this value set to zero, so some reasonable interpretation
of the zero "arg" should be included.

If a service chooses not to support the Pause/Continue opcodes,
it should set the appropriate bit (SERVICE_NOT_PAUSABLE) in the
service status.  See NetServiceStatus API.

When a service is paused for whatever reason, it should set the
proper portion of it's status to SERVICE_PAUSED.  Note that the
paused/continued bits are independent of the bits identifying a
service as INSTALLED;  a service's status should always be all
the proper fields OR'ed together.  


29.8  Service Shutdown 

Services should respond promptly to the uninstallation request.
If the service will take a while to uninstall, it should return 
status as UNINSTALL_PENDING early in the uninstallation process.

If a service is forced to uninstall asynchronously, due to some
problem or timeout or even justy completion of it's task,
it should follow the same path when possible, posting the
UNINSTALL_PENDING code early in the process.  This protects the
service from excess signals and notifies applications that the
service is going down.

At the time a service posts UNINSTALL status, it should set the code
word of the status structure to one of the SERVICE_UIC values defined
in service.h, and described in the API documentation.  Since a
service is Exec'd in detached mode, this UIC code is the service's
only opportunity to provide a clue as to the reason for its demise.

If and only if the reason for shutdown cannot be communicated via 
UIC codes, the service can log an error using NetErrorLogWrite.


29.9  Multi-Process Services 

If the service consists of more than one process, the proces that is
initially executed is the process which will recieve signals from
NetServiceControl, and is the only process that may issue
NetServiceStatus calls.  This process is referred to as the
"main service process".

If the main service process wishes to tranfer it's title to another
process, the main process should set the "pid" field of the
service_status structure to the PID of the process which is to
become the "main service process".  When NetServiceStatus is
called with the PID set to a non-zero value, the process whose PID
matches that value becomes the "main service process" for that service.

This is a useful technique for transferring the responsiblity for
maintaining a service's status, for example from an initialization
program to the main program of a service.


30.   Alphabetical List of APIs 


        W   requires workstation
        M   requires messenger
        P   requires print spooler
        S   requires server
        U   requires user-level security
        R   can be remnoted
        A   admin priv required for remote use
        O   OEM-only API, not for use by applications
        L   has a local-only library available


API Name                Library         W M P S U R A O L

DOSCALLNMPIPE           NAMPIPES        *               L       Note 1
DOSCONNECTNMPIPE        NAMPIPES        *               L       Note 1
DOSDELETEMAILSLOT       MAILSLOT        *               L       Note 1
DOSDISCONNECTNMPIPE     NAMPIPES        *               L       Note 1
DOSMAILSLOTINFO         MAILSLOT        *               L       Note 1
DOSMAKEMAILSLOT         MAILSLOT        *               L       Note 1
DOSMAKENMPIPE           NAMPIPES        *               L       Note 1
DOSPEEKMAILSLOT         MAILSLOT        *               L       Note 1
DOSPEEKNMPIPE           NAMPIPES        *               L       Note 1
DOSPRINTDESTCONTROL     NETSPOOL        W   P         
DOSPRINTDESTENUM        NETSPOOL        W   P         
DOSPRINTDESTGETINFO     NETSPOOL        W   P         
DOSPRINTDESTSTATUS      NETSPOOL        W   P         
DOSPRINTJOBADD          NETSPOOL        W   P         
DOSPRINTJOBCONTINUE     NETSPOOL        W   P         
DOSPRINTJOBDEL          NETSPOOL        W   P         
DOSPRINTJOBENUM         NETSPOOL        W   P         
DOSPRINTJOBGETID        NETSPOOL        W   P         
DOSPRINTJOBGETINFO      NETSPOOL        W   P         
DOSPRINTJOBPAUSE        NETSPOOL        W   P         
DOSPRINTJOBSCHEDULE     NETSPOOL        W   P         
DOSPRINTJOBSETINFO      NETSPOOL        W   P         
DOSPRINTQADD            NETSPOOL        W   P         
DOSPRINTQCONTINUE       NETSPOOL        W   P         
DOSPRINTQDEL            NETSPOOL        W   P         
DOSPRINTQENUM           NETSPOOL        W   P         
DOSPRINTQGETINFO        NETSPOOL        W   P         
DOSPRINTQPAUSE          NETSPOOL        W   P         
DOSPRINTQSETINFO        NETSPOOL        W   P         
DOSQNMPHANDSTATE        NAMPIPES        *               L       Note 1
DOSQNMPIPEINFO          NAMPIPES        *               L       Note 1
DOSQNMPIPESEMSTATE      NAMPIPES        *               L       Note 1
DOSREADMAILSLOT         MAILSLOT        *               L       Note 1
DOSSETNMPHANDSTATE      NAMPIPES        *               L       Note 1
DOSSETNMPIPESEM         NAMPIPES        *               L       Note 1
DOSTRANSACTNMPIPE       NAMPIPES        *               L       Note 1
DOSWAITNMPIPE           NAMPIPES        *               L       Note 1
DOSWRITEMAILSLOT        MAILSLOT        *               L       Note 1
NETACCESSADD            NETAPI          W     S U R A
NETACCESSCHECK          NETAPI          W     S U R A
NETACCESSDEL            NETAPI          W     S U R A  
NETACCESSENUM           NETAPI          W     S U R A
NETACCESSGETINFO        NETAPI          W     S U R A
NETACCESSSETINFO        NETAPI          W     S U R A  
NETALERTRAISE           NETAPI          W   
NETALERTSTART           NETAPI          W   
NETALERTSTOP            NETAPI          W   
NETAUDITCLEAR           NETAPI          *         R A           Note 2
NETAUDITOPEN            NETAPI          *         R A           Note 2
NETAUDITWRITE           NETAPI          W     S
NETBIOSCLOSE            NETAPI          W   
NETBIOSENUM             NETAPI          W         R A
NETBIOSGETINFO          NETAPI          W         R A
NETBIOSOPEN             NETAPI          W   
NETBIOSSUBMIT           NETAPI          W   
NETCHARDEVCONTROL       NETAPI          W     S   R A
NETCHARDEVENUM          NETAPI          W     S   R 
NETCHARDEVGETINFO       NETAPI          W     S   R
NETCHARDEVQENUM         NETAPI          W     S   R 
NETCHARDEVQGETINFO      NETAPI          W     S   R 
NETCHARDEVQPURGE        NETAPI          W     S   R A
NETCHARDEVQSETINFO      NETAPI          W     S   R A
NETCONFIGGET            NETAPI          *                       Note 2
NETCONFIGGETALL         NETAPI          *                       Note 2
NETCONNECTIONENUM       NETAPI          W     S   R A
NETERRORLOGCLEAR        NETAPI          *         R A           Note 2
NETERRORLOGOPEN         NETAPI          *         R A           Note 2
NETERRORLOGWRITE        NETAPI          W         
NETFILECLOSE            NETAPI          W     S   R A
NETFILEENUM             NETAPI          W     S   R A
NETFILEGETINFO          NETAPI          W     S   R A
NETGROUPADD             NETAPI          W     S U R A
NETGROUPADDUSER         NETAPI          W     S U R A
NETGROUPDEL             NETAPI          W     S U R A
NETGROUPDELUSER         NETAPI          W     S U R A
NETGROUPENUM            NETAPI          W     S U R A
NETGROUPGETUSERS        NETAPI          W     S * R A           Note 3
NETMESSAGEBUFFERSEND    NETOEM          W         R A
NETMESSAGEFILESEND      NETOEM          W         R A
NETMESSAGELOGFILEGET    NETAPI          W M       R A    
NETMESSAGELOGFILESET    NETAPI          W M       R A    
NETMESSAGENAMEADD       NETAPI          W M       R A    
NETMESSAGENAMEDEL       NETAPI          W M       R A    
NETMESSAGENAMEENUM      NETAPI          W M       R A    
NETMESSAGENAMEFWD       NETAPI          W M       R A    
NETMESSAGENAMEGETINFO   NETAPI          W M       R A    
NETMESSAGENAMEUNFWD     NETAPI          W M       R A    
NETPROFILELOAD          NETAPI          W     *   R A           Note 4
NETPROFILESAVE          NETAPI          W     *   R A           Note 4
NETREMOTECOPY           NETAPI          W         R
NETREMOTEEXEC           NETAPI          W         R
NETREMOTEMOVE           NETAPI          W         R
NETREMOTETOD            NETAPI          W         R
NETSERVERADMINCOMMAND   NETAPI          W     S   R A
NETSERVERDISKENUM       NETAPI          W     S   R A
NETSERVERENUM           NETOEM          *         R             Note 5
NETSERVERGETINFO        NETAPI          W     S   R A
NETSERVERSETINFO        NETAPI          W     S   R A
NETSERVICECONTROL       NETAPI          W         R *           Note 6
NETSERVICEENUM          NETAPI          W         R
NETSERVICEGETINFO       NETAPI          W         R
NETSERVICEINSTALL       NETAPI          *         R A           Note 7
NETSERVICESTATUS        NETAPI          W   
NETSESSIONDEL           NETAPI          W     S   R A 
NETSESSIONENUM          NETAPI          W     S   R A
NETSESSIONGETINFO       NETAPI          W     S   R A
NETSHAREADD             NETAPI          W     S   R A
NETSHARECHECK           NETAPI          W     S   R 
NETSHAREDEL             NETAPI          W     S   R A
NETSHAREENUM            NETAPI          W     S   R 
NETSHAREGETINFO         NETAPI          W     S   R 
NETSHARESETINFO         NETAPI          W     S   R A
NETSTATISTICSCLEAR      NETAPI          W     *   R A           Note 8
NETSTATISTICSGET        NETAPI          W     *   R A           Note 8
NETUSEADD               NETAPI          W         R A
NETUSEDEL               NETAPI          W         R A
NETUSEENUM              NETAPI          W         R A
NETUSEGETINFO           NETAPI          W         R A
NETUSERADD              NETAPI          W     S U R A
NETUSERDEL              NETAPI          W     S U R A
NETUSERENUM             NETAPI          W     S U R A
NETUSERGETGROUPS        NETAPI          W     S U R A
NETUSERGETINFO          NETAPI          W     S U R A
NETUSERPASSWORDSET      NETAPI          W     S U R 
NETUSERSETINFO          NETAPI          W     S U R 
NETUSERVALIDATE         NETAPI          W     S U R A
NETWKSTAGETINFO         NETAPI          W         R A
NETWKSTASETINFO         NETAPI          W         R A
NETWKSTASETUID          NETAPI          W         R A
                                            

Note 1:  These APIs require the workstation to be running in order for
remote resoures to be accessed, but will otherwise function locally
without the workstation software.

Note 2:  These APIs require the network software to be installed,
but the workstation need not been running.

Note 3:  This API will work on a server which is running in either
security mode.  However, under share security it may prove to be slow,
since it must access the security database.

Note 4:  Requires server to load or save info about shares, print queues
and character device queues.

Note 5:  This function works on any workstation started with the mailslots
parameter set to "yes".  This is reflected in the "mailslots" field
on the workstation info (wksta_info_0).

Note 6:  The only operation which can be done remotely that does NOT
require admin privledges in INTERROGATE.

Note 7:  This API may be used to start the workstation.  It cannot
start any other services until the workstation is started.

Note 8:  These APIs will return only workstation statistics when the
server is not running.


31.   OS/2 NETBIOS DEVICE DRIVER INTERFACE 

        Last update: 4/26/88


There have been some changes to this document.  Especially note the
sections marked with the tag: *** NEW ***



31.1  Introduction 

Netbios drivers install as standard OS/2 device drivers.  All
programming considerations for device drivers apply to Netbios
drivers, with the additions noted herein.

Because Netbios drivers get called by the operating system to do I/O,
a direct ring 0 linkage mechanism has been defined.  This allows OS/2
to request network I/O services via a direct call to the Netbios
driver, as opposed to going through standard device driver
interfaces.

OS/2 performs a standard DosDevIoctl to the Netbios driver to get the
far address of the direct I/O routine.  This routine is analogous to
a real mode INT 5C handler--i.e., it gets called with a pointer to an
NCB.  All NCBs passed to this routine contain physical buffer
addresses only and the NCB and buffers have already been locked if
appropriate.  A convention is defined to support oem-defined NCBs
such that the operating system can still perform appropriate locking
on behalf of the extended NCBs.

To support Netbios drivers, the operating system provides a
standardized routine, NCBDONE, for handling NCB completion.  Netbios
drivers need not process synchronous or asynchronous Netbios options;
they just call the NCBDONE routine when processing is complete.  The
linkage to NCBDONE is defined below.

*** NEW ***

We recommend that NetBios drivers for LanMan support a configurable
"call" timeout.  This parameter specifies the maximum amount of time
that the driver will wait for a response from the remote machine when
handling Call, AddName, and AddGroupName NCBs.  The parameter should
be settable from the device= line in the config.sys file.


31.2  Netbios Driver Configuration 

Netbios drivers are normal OS/2 device drivers and are installed by
inserting a DEVICE= statement in config.sys.  Note that Netbios
drivers depend on the Microsoft-supplied NETWKSTA.SYS driver.  This
must be installed AFTER all Netbios drivers.

Multiple Netbios drivers can be installed in a single system.  Each
is described by a set of parameters in a configuration file,
LANMAN.INI, as follows:

  [networks]
      net1 = toknet$,0,LM10,32,32,16
      net2 = ethnet$,0,LM10,32,32,16

The format of each Netbios network definition is:

  <network name> = <DN>,<LN>,<type>,<NCBs>,<Sess>,<Name>

  <DN>   = os/2 driver name    Required
  <LN>   = Lana Number         Not required, default is 0
  <type> = driver type         Not required, default is "LM10"
  <NCBs> = Number NCBs         Not required, default is driver default
  <Sess> = Number Sessions     Not required, default is driver default
  <Name> = Number Names        Not required, default is driver default

When the workstation is initialized, it will initialize each driver
using the <NCBs>, <Sess>, and <Name> parameters.  This configuration
information is processed by the NETWKSTA.SYS driver in support of the
protected mode Netbios API.  It allows applications to open Netbios
drivers by logical name, independent of the actual OS/2 driver name
and Lana number.  The NETWKSTA.SYS driver also handles OS/2-related
processing that is common to all Netbios drivers, including
translation of NCBs from virtual to physical form and synchronization
between interrupt time and task time async NCB completion.


31.3  Netbios Driver Initialization 

Network drivers perform device initialization at load
time just like any other device drivers.  They must
also support a DosDevIoctl command that is issued from
OS/2 to the Netbios driver during system initialization.
The driver initialization sequence is:

 1. Respond to the device Init command at driver load time by
    allocating packet buffers, setting up tables, and running
    startup diagnostics as appropriate.
    Note that GDT selectors (allocated via the AllocGDTSelector
    Device Help) are not valid to use during initialization.
    Any access to memory that normally would be done via an
    allocated GDT selector must be done via PhysToVirt.

 2. Respond to the sequence DosOpen, DosDevIoctl: NetbiosLinkage,
    DosClose.  This passes in the pointer of NCBDone and returns a
    pointer a table of parameters that the operating system needs.

Note that a driver must be prepared to respond to multiple
initialization sequences of DosOpen/DosDevIoctl/DosClose.
For a driver supporting multiple Lanas, this would happen
once for each Lana defined to the system.

   NetbiosLinkage: DosDevIoctl Category 81, Subfunction 62
   --------------------------------------------------------

   Purpose         Get Netbios driver linkage table

   Request packet  13-BYTE   Request header
                   BYTE      Function category = 81h
                   BYTE      Function code = 62h
                   DWORD     Parameter buffer address
                   DWORD     Data buffer address (returned)

    Parameter   Packet
                   WORD    Parm Packet length in Bytes
                   WORD    Data Packet length in Bytes
                   DWORD   NCBDone handler address
                            NOTE! This address is only valid after
                                  completion of config.sys processing
                                  by OS/2.  Hence it may not be called
                                  until the first NCB has been
                                  received through the Netbios NCB
                                  Handler entry point.
                   BYTE    Lana Number (as specified in the NetBios
                            network definition in lanman.ini)


   The data buffer is filled in by the Netbios driver to contain
   the following NetbiosLinkage structure:

   NetbiosLinkage  structure:

                   WORD      Bytes of data returned in this table
                   WORD      Bytes of data actually available
                   BYTE      Reserved do not change.
                   WORD      Net driver type (1=NCB, 2=MCB)
                   WORD      Network Status:
                                 Bit 0:     Reserved, must be zero
                                 Bit 1:     Cleared = normal driver
                                            Set = loopback driver
                                 Bit 2-15:  Reserved, must be zero
                   DWORD     Network bandwidth (bits/s)
                   WORD      Maximum sessions
                   WORD      Maximum number of NCBs
                   WORD      Maximum number of names
                   WORD      Netbios driver's DS value
                   DWORD     Netbios NCB Handler address
                   BYTE      # of commands in OEM extension table
   OemExtTable:
                   WORD      ExtStruct
                   o
                   o
                   o
                   WORD      ExtStruct

   where

   ExtStruct structure:

   Cmd             BYTE      Extended NCB Command Opcode Value
   CmdInfo         WORD      Command descriptor bits
                             bit 0 == 1: standard buffer used
                                 1 == 1: second buffer used
                                 2 == 1: lock buffers
                                 3 == 1: async option allowed
                                 4 == 1: command is cancellable
                               6/7 == 1: if regular command
                                      2: if privileged command
                                      3: if exclusive command
                                 8 == 1: Uses LSN field
                                 9 == 1: Uses NamNum field
                                10 == 1: Uses Local Name Field
                                         (ncb_name)
                                11 == 0: Buffer segments must be
                                         read-write.
                                      1: Buffer segments may be
                                         read-only.


   The OemExtTable is optional (can have 0 entries).  It
   defines NCB commands that are OEM-defined extensions to
   the standard Netbios interface.  The CmdInfo parameter
   describes the extended NCB's usage of buffers and
   asynchronous notification.  It also indicates whether the
   command is cancellable and whether requesting application
   needs to have opened the Netbios driver in privileged or
   exclusive mode to issue the command.  The operating system
   needs this information to provide correct addressability
   and protection in making application-level buffers
   available to the Netbios driver in physical address form.
   The highest three bits are used to protect Server and Redir
   Sessions and Names from interferance from user submitted NCBs



31.4  Netbios NCB Handler 

The Netbios NCB handler is entered via a far call.  The
calling conventions are essentially identical to those for
real-mode INT 5C, except that ES:BX is the virtual address
of the NCB to be executed.  The physical address of the
NCB is available in DX:AX.

  Entry:    ES:BX         Virtual address of NCB
            DX:AX         Physical address of NCB
            DS            Netbios driver's DS
            TOS:DWORD     Return address
            TOS+4:DWORD   Virtual address of NCB
            TOS+8:DWORD   Physical address of NCB

  Return:   AX            Netbios-defined result code

  Errors:   Netbios-defined immediate result codes

Parameters are passed both in registers and on the stack.
The NCB Handler must always exit via a far return, with
parameters removed from the stack and an immediate NCB return
code in AX.  These conventions allow the handler to be coded
in high level languages.

Note that if the immediate result code returned is non-zero,
the NCB is considered to be completed, NCBDONE must NOT
be called.

The addresses within the NCB are physical addresses that are
guaranteed to be valid until invocation of NCBDONE.  OS/2 will
handle locking and unlocking of these data regions.

Note! When transferring blocks of data via Rep Instructions,
      a maximum size of 2k is allowed.  See the OS/2 Device
      driver guidelines.

The values of the NCB_POST and the NCB_CMD_CPLT fields are
reserved and must not be modified during the course of processing

The Netbios NCB handler should not distinguish between synchronous
and asynchronous NCBs.  It need just start the necessary I/O
going and return.  NCB completion and synchronization is
handled by a Microsoft supplied routine, NCBDONE.

Note! The NCB Handler MUST NOT block at any time.

The interrupt routine must issue a far call to NCBDONE upon
completing processing of an NCB (usually at Interrupt time).
The physical address of the NCB being completed must be
passed to NCBDONE on the stack (the far address of NCBDONE is
passed to the driver via initialization-time DosDevIoctl described
in Section III).  Entry conditions for NCBDONE:

  1. Mode = ProtMode.  See DevHlp GoProt and GoReal documentation.

  2. SS == SS at driver entry point (either interrupt handler
            or at task time).
           (Note: if GoProt is used in an interrupt handler,
                  SS == SS upon return from GoProt)

  3. Entry:    TOS:DWORD     Return address
               TOS+4:DWORD   Physical address of NCB
   
     Return:   AX, CX, DX modified
               Parameters removed from stack.

  4. The NCB_RETCODE field has the correct Return Code value.

  5. The Following fields must contain the values present at
     NCB submission time:  NCB_POST, NCB_CMD_CPLT.

  6. All Netbios processing of this NCB must be complete.  The
     internals of NCBDONE reserve the right to modify the
     NCB in any way.


*** NEW ***

31.5  Common problems and hints 

Note! For performance reasons, it is recommended that PhysToGDT
      be used whenever possible instead of PhysToVirt.

Note! When a Reset NCB is received, the driver MUST complete
      (call NCBDone) all outstanding NCBs with a canceled or
      name deleted status.  It is recommended that for the
      drivers own protection, the driver should not accept any
      NCBs while a reset is in progress.  The handler should
      complete all other outstanding NCBs before completing
      the reset NCB.

Note! The NCB Handler MUST NOT block at any time.

Note! When a session is aborted (as opposed to hung-up), the
      driver should be return error code 18H (Session Ended
      Abnormally).  The error code 0AH (Session Closed) should
      only be returned when either end hangs up the session.
      The redirector needs this information for its session
      handling.





			Lan Manager API Index

Access Permissions ......................................... 78
ACCESS_ATRIB ............................................... 78
ACCESS_CREATE .............................................. 78
ACCESS_DELETE .............................................. 78
ACCESS_EXEC ................................................ 78
ACCESS_GROUP ............................................... 78
ACCESS_PERM ................................................ 78
ACCESS_PERM, special meaning for share permissions ......... 14
ACCESS_READ ................................................ 78
ACCESS_WRITE ............................................... 78
Admin Only ................................................. 2
Admin Rights ............................................... 2
ADMIN$ Share ............................................... 2,17,137
Alert Names ................................................ 27
Alert thresholds for Server ................................ 28
Alert time period .......................................... 28
Alerter Service ............................................ 93,156
Alerts, maximum clients .................................... 93
ASCIZ ...................................................... 4
Audit Log .................................................. 27,33
Audit log, maximum size .................................... 29,39
Audit Log, resource records ................................ 77

Character Device Redirection ............................... 92

DosBufReset ................................................ 94,131
DosCallNmPipe .............................................. 126
DosClose ................................................... 94,130
DosConnectNmPipe ........................................... 123
DosDeleteMailslot .......................................... 133
DosDisconnectNmPipe ........................................ 124
DosDupHandle ............................................... 130
DosMailslotInfo ............................................ 133
DosMakeMailslot ............................................ 132
DosMakeNmPipe .............................................. 121
DosOpen .................................................... 129,138
DosPeekMailslot ............................................ 134
DosPeekNmPipe .............................................. 125
DosPrintDestControl ........................................ 118
DosPrintDestEnum ........................................... 117
DosPrintDestGetInfo ........................................ 117
DosPrintDestStatus ......................................... 118
DosPrintJobAdd ............................................. 113
DosPrintJobContinue ........................................ 114
DosPrintJobDel ............................................. 114
DosPrintJobEnum ............................................ 111
DosPrintJobGetInfo ......................................... 112
DosPrintJobPause ........................................... 114
DosPrintJobSchedule ........................................ 113
DosPrintJobSetInfo ......................................... 112
DosPrintQAdd ............................................... 107
DosPrintQContinue .......................................... 109
DosPrintQDel ............................................... 108
DosPrintQEnum .............................................. 105
DosPrintQGetInfo ........................................... 106
DosPrintQPause ............................................. 109
DosPrintQPurge ............................................. 108
DosPrintQSetInfo ........................................... 107
DosQFHandState ............................................. 130
DosQHandType ............................................... 130
DosQNmpHandState ........................................... 124
DosQNmPipeInfo ............................................. 123
DosQNmPipeSemState ......................................... 127
DosRead .................................................... 131
DosReadAsync ............................................... 131
DosReadMailslot ............................................ 134
DosSetFHandState ........................................... 130
DosSetFileInfo ............................................. 78
DosSetNmpHandState ......................................... 125
DosSetNmPipeSem ............................................ 129
DosTransactNmPipe .......................................... 126
DosWaitNmPipe .............................................. 127
DosWrite ................................................... 130
DosWriteAsync .............................................. 130
DosWriteMailslot ........................................... 135

Enum calls, general information ............................ 6
Error Log .................................................. 42
Error Log, maximum size .................................... 43,93
ERROR_INVALID_LEVEL ........................................ 5,10
ERROR_INVALID_PARAMETER .................................... 11
ERROR_MORE_DATA ............................................ 6,10
ERROR_NETWORK_ACCESS_DENIED ................................ 12

GetInfo calls, general information ......................... 6

IP Codes ................................................... 62,164
IPC$ Share ................................................. 2,11,16,137

Lan Manager Version ........................................ 27,92
LANMAN.INI ................................................. 69
LANMAN.INI, NetBios parameters in .......................... 170
LANMAN.INI, service information ............................ 159
Logon Server ............................................... 93,158

Messenger Service .......................................... 156

Named Pipes ................................................ 93,121
NERR_ACFNotLoaded .......................................... 11
NERR_BadTransactConfig ..................................... 2,11
NERR_BufTooSmall ........................................... 6,11
NERR_NetNotStarted ......................................... 11
NERR_ServerNotStarted ...................................... 11
NERR_SpeGroupOp ............................................ 83
NERR_WkstaNotStarted ....................................... 11
NetAccessAdd ............................................... 81
NetAccessCheck ............................................. 82
NetAccessDel ............................................... 82
NetAccessEnum .............................................. 79
NetAccessGetInfo ........................................... 80
NetAccessSetInfo ........................................... 80
NetAlertRaise .............................................. 75
NetAlertStart .............................................. 74
NetAlertStop ............................................... 75
NetAuditClear .............................................. 40
NetAuditOpen ............................................... 39
NetAuditWrite .............................................. 40
NetBios Device Drivers ..................................... 169
NetBiosClose ............................................... 147
NetBiosEnum ................................................ 145
NetBiosGetInfo ............................................. 146
NetBiosOpen ................................................ 146
NetBiosSubmit .............................................. 148
NetCharDevControl .......................................... 48
NetCharDevEnum ............................................. 47
NetCharDevGetInfo .......................................... 48
NetCharDevQEnum ............................................ 49
NetCharDevQGetInfo ......................................... 49
NetCharDevQPurge ........................................... 50,51
NetCharDevQSetInfo ......................................... 50
NetConfigGet ............................................... 69
NetConfigGetAll ............................................ 70
NetConnectionEnum .......................................... 23
NetErrorLogClear ........................................... 44
NetErrorLogOpen ............................................ 43
NetErrorLogWrite ........................................... 44
NetFileClose ............................................... 25
NetFileEnum ................................................ 24
NetFileGetInfo ............................................. 25
NetGroupAdd ................................................ 84
NetGroupAddUser ............................................ 84
NetGroupDel ................................................ 84
NetGroupDelUser ............................................ 85
NetGroupEnum ............................................... 83
NetGroupGetUsers ........................................... 85
NetLogon Service ........................................... 158
NetMessageBufferSend ....................................... 55
NetMessageFileSend ......................................... 56
NetMessageNameAdd .......................................... 53
NetMessageNameDel .......................................... 54
NetMessageNameFwd .......................................... 54
NetMessageNameGetInfo ...................................... 53
NetMessageNameUnFwd ........................................ 55
NetPopup Service ........................................... 157
NetProfileLoad ............................................. 138
NetProfileSave ............................................. 137
NetRemoteCopy .............................................. 151
NetRemoteExec .............................................. 154,158
NetRemoteMove .............................................. 152
NetRemoteTOD ............................................... 150
NetServerAdminCommand ...................................... 32
NetServerDiskEnum .......................................... 31
NetServerEnum .............................................. 28,29
NetServerGetInfo ........................................... 30
NetServerSetInfo ........................................... 30
NetServiceControl .......................................... 66,161
NetServiceEnum ............................................. 64
NetServiceGetInfo .......................................... 63
NetServiceInstall .......................................... 64
NetServiceStatus ........................................... 68,162
NetSessionDel .............................................. 20
NetSessionEnum ............................................. 19
NetSessionGetInfo .......................................... 20
NetShareAdd ................................................ 16
NetShareCheck .............................................. 18
NetShareDel ................................................ 17
NetShareEnum ............................................... 14
NetShareGetInfo ............................................ 15
NetShareSetInfo ............................................ 15
NetStatisticsClear ......................................... 143
NetStatisticsGet ........................................... 5,142
NetUseAdd .................................................. 100
NetUseDel .................................................. 102
NetUseEnum ................................................. 100
NetUseGetInfo .............................................. 103
NetUserAdd ................................................. 88
NetUserDel ................................................. 88
NetUserEnum ................................................ 88
NetUserGetInfo ............................................. 89
NetUserPasswordSet ......................................... 90
NetUserSetInfo ............................................. 89
NetUserValidate ............................................ 90
NetWkstaGetInfo ............................................ 95
NetWkstaSetInfo ............................................ 95
NetWkstaSetUID ............................................. 96

Pad bytes .................................................. 4
password to NetUseAdd ...................................... 101
password, setting default password for a workstation ....... 96
Permissions on a Share ..................................... 13
Print Processor ............................................ 104,119
Profiles ................................................... 137

RunServer Service .......................................... 158

Server Service ............................................. 11,156
servername (parameter to APIs) ............................. 1
Services ................................................... 155,159
SetInfo calls, general information ......................... 7
Share-level security ....................................... 27
Share-level security and Admin Rights ...................... 2
Spooler Service ............................................ 156

Timestamps ................................................. 8

UIC Codes .................................................. 61,165
User-level security ........................................ 27
User-level security and Admin Rights ....................... 2
username, logging into a workstation ....................... 96

Version of Lan Manager ..................................... 27,92

Workstation Service ........................................ 11,155