 Microsoft LAN Manager - Programmer's Reference








 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
              Microsoft(R) LAN Manager - Programmer's Reference

                              Covers version 2.0
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


                  Network APIs for MS(R) OS/2 and MS-DOS(R)








 Microsoft Corporation

 PUBLISHED BY
 Microsoft Press
 A Division of Microsoft Corporation
 One Microsoft Way, Redmond, Washington 98052-6399

 Copyright (C)1990 by Microsoft Corporation. All rights
 reserved.

 Information in this document is subject to change without notice and
 does not represent a commitment on the part of Microsoft Corporation.
 The software described in this document
 is furnished under a license agreement or nondisclosure agreement.
 The software may be
 used or copied only in accordance with the terms of the agreement.
 It is against the law to
 copy the software on any medium except as specifically allowed in
 the license or nondisclosure agreement. No part of this manual may
 be reproduced or transmitted in any form or by any means, electronic
 or mechanical, including photocopying and recording, for any purpose
 without the written permission of Microsoft Corporation.

 Library of Congress Cataloging-in-Publication Data

 Microsoft LAN manager programmer's reference : network APIs for OS/2

   and MS-DOS / Microsoft Corporation.
      p.  cm. Ä (Microsoft OS/2 programmer's reference library)
    Includes index.
    ISBN 1-55615-313-9
    1. Local area networks (Computer networks) Ä Computer
 programs.
   2. Microsoft LAN manager (Computer program) 3. OS/2 (Computer

   operating system) 4. MS DOS (Computer operating system)
   I. Microsoft. II. Series.
   TK5105.7.M53 1990                90-41578
   004.6'8'02855369 Ä dc20                 CIP


 Printed and bound in the United States of America.

 123456789FGFG43210

 Distributed to the book trade in Canada by General Publishing Company,
 Ltd.
 Distributed to the book trade outside the U.S. and Canada by Penguin
 Books Ltd.
 Penguin Books Ltd., Harmondsworth, Middlesex, England
 Penguin Books Australia Ltd., Ringwood, Victoria, Australia
 Penguin Books N.Z. Ltd., 182-190 Wairau Road, Auckland 10, New
 Zealand

 British Cataloging in Publication Data available



 CodeView(R), Microsoft(R), MS(R),
 MS-DOS(R), XENIX(R), and the Microsoft logo
 are registered trademarks and Windows(tm) is a trademark
 of Microsoft Corporation.

 Apple(R) is a registered trademark of Apple Computer,
 Inc. 386(tm) is a trademark of
 Intel Corporation. IBM(R) is a registered trademark of
 International Business Machines Corporation. Novell(R)
 is a registered trademark of Novell, Inc.

 Writers:  Lewis Campbell, Bruce Legge, John Murray, Barry Potter
 Contributors:  Alec Barker, Paul Canniff, Liz Chalmers, Chuck Chan,
 Brendan Dixon,
  Helen Dolmas, Diane Friedman, Danny Glasser, Andy Held, Joe Holman,

  Jim Horne, Jeffery Howard, Jan Keller, Rustan Leino, Mark Lewin,

  Lesley Link, Pradyumna Misra, Yuval Neeman, Judy Nessen, Larry Osterman,

  Thomas Payne, Eric Peterson, A. J. Rizer, Kevin Schofield, Bharat
 Shah,
  Alok Sinha, Ed Stubbs, Lori Walker, Manny Weiser, William Wu, Sue
 Wyble,
  LAN Manager development team



 Document Number:  OEM-D/P787-2Z




 Table of Contents
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Before You Begin
      How to Use This Manual
      Notational Conventions
      For More Information

 Chapter 1  Overview of the LAN Manager API

      Identifying API Components
             API Function Names
             API Data Structure Names
             API Variable Names
      Including LAN Manager API Definitions
      Calling a LAN Manager API Function
             Calling Privileges
             Parameter Formats
             Using Buffers with API Functions
             Interpreting Return Codes
      Compiling and Linking Applications
      Debugging Tips
             Stack Overflow
             Errors in Hard-Coded Values
             Errors During Pointer Type Conversion
             MS OS/2 Protection Violations and Faults
             MS-DOS, Windows 2.x, and Real-Mode Windows 3.0 Applications
             Windows 3.0 Protected-Mode Applications

 Chapter 2  API Function Descriptions

      Format Reference Pages
      Access Permissions Category
             Description
             Data Structures
             NetAccessAdd
             NetAccessCheck
             NetAccessDel
             NetAccessEnum
             NetAccessGetInfo
             NetAccessGetUserPerms
             NetAccessSetInfo
             Access Permissions Category Example
      Alert Category
             Description
             Data Structures
             NetAlertRaise
             NetAlertStart
             NetAlertStop
             Alert Category Example
      Auditing Category
             Description
             Data Structures
             NetAuditClear
             NetAuditRead
             NetAuditWrite
             Auditing Category Example
      Character Device Category
             Description
             Data Structures
             NetCharDevControl
             NetCharDevEnum
             NetCharDevGetInfo
             NetCharDevQEnum
             NetCharDevQGetInfo
             NetCharDevQPurge
             NetCharDevQPurgeSelf
             NetCharDevQSetInfo
             Character Device Category Example
      Configuration Category
             Description
             NetConfigGet2
             NetConfigGetAll2
             Configuration Category Example
      Connection Category
             Description
             Data Structures
             NetConnectionEnum
             Connection Category Example
      Domain Category
             Description
             Data Structures
             NetGetDCName
             NetLogonEnum
             Domain Category Example
      Error Logging Category
             Description
             Data Structure
             Error Log Codes
             NetErrorLogClear
             NetErrorLogRead
             NetErrorLogWrite
             Error Logging Category Example
      File Category
             Description
             Data Structures
             NetFileClose2
             NetFileEnum2
             NetFileGetInfo2
             File Category Example
      Group Category
             Description
             Data Structures
             NetGroupAdd
             NetGroupAddUser
             NetGroupDel
             NetGroupDelUser
             NetGroupEnum
             NetGroupGetInfo
             NetGroupGetUsers
             NetGroupSetInfo
             NetGroupSetUsers
             Group Category Example
      Handle Category
             Description
             Data Structures
             NetHandleGetInfo
             NetHandleSetInfo
             Handle Category Example
      Mailslot Category
             Description
             DosDeleteMailslot
             DosMailslotInfo
             DosMakeMailslot
             DosPeekMailslot
             DosReadMailslot
             DosWriteMailslot
             Mailslot Category Example
      Message Category
             Description
             Data Structures
             NetMessageBufferSend
             NetMessageFileSend
             NetMessageLogFileGet
             NetMessageLogFileSet
             NetMessageNameAdd
             NetMessageNameDel
             NetMessageNameEnum
             NetMessageNameFwd
             NetMessageNameGetInfo
             NetMessageNameUnFwd
             Message Category Example
      Print Destination Category
             Description
             Data Structures
             DosPrintDestAdd
             DosPrintDestControl
             DosPrintDestDel
             DosPrintDestEnum
             DosPrintDestGetInfo
             DosPrintDestSetInfo
             Print Destination Category Example
      Print Job Category
             Description
             Data Structures
             DosPrintJobContinue
             DosPrintJobDel
             DosPrintJobEnum
             DosPrintJobGetId
             DosPrintJobGetInfo
             DosPrintJobPause
             DosPrintJobSetInfo
             Print Job Category Example
      Printer Queue Category
             Description
             Data Structures
             DosPrintQAdd
             DosPrintQContinue
             DosPrintQDel
             DosPrintQEnum
             DosPrintQGetInfo
             DosPrintQPause
             DosPrintQPurge
             DosPrintQSetInfo
             Printer Queue Category Example
      Remote Utility Category
             Description
             Data Structures
             NetRemoteCopy
             NetRemoteExec
             NetRemoteMove
             NetRemoteTOD
             Remote Utility Category Example
      Server Category
             Description
             Data Structures
             NetServerAdminCommand
             NetServerDiskEnum
             NetServerEnum2
             NetServerGetInfo
             NetServerSetInfo
             Server Category Example
      Session Category
             Description
             Data Structures
             NetSessionDel
             NetSessionEnum
             NetSessionGetInfo
             Session Category Example
      Share Category
             Description
             Data Structures
             NetShareAdd
             NetShareCheck
             NetShareDel
             NetShareEnum
             NetShareGetInfo
             NetShareSetInfo
             Share Category Example
      Statistics Category
             Description
             Data Structures
             NetStatisticsGet2
             Statistics Category Example
      Service Category
             Description
             Data Structures
             NetServiceControl
             NetServiceEnum
             NetServiceGetInfo
             NetServiceInstall
             NetServiceStatus
             Service Category Example
      Use Category
             Description
             Data Structures
             NetUseAdd
             NetUseDel
             NetUseEnum
             NetUseGetInfo
             Use Category Example
      User Category
             Description
             Data Structures
             NetUserAdd
             NetUserDel
             NetUserEnum
             NetUserGetGroups
             NetUserGetInfo
             NetUserModalsGet
             NetUserModalsSet
             NetUserPasswordSet
             NetUserSetGroups
             NetUserSetInfo
             NetUserValidate2
             User Category Example
      Workstation Category
             Description
             Data Structures
             NetWkstaGetInfo
             NetWkstaSetInfo
             NetWkstaSetUID2
             Workstation Category Example

 Appendix A  Return Codes

      Return Codes by Class
      LAN Manager and MS OS/2 Return Codes

 Appendix B  Upgrading LAN Manager 1.0 Applications

      Table of API Changes
      Superseded API Functions
             Superseded Function Descriptions
             NetAuditOpen
             NetErrorLogOpen
             NetStatisticsClear
             NetStatisticsGet
             NetUserValidate
             NetWkstaSetUID

 Appendix C  Creating LAN Manager Services

      A Simple Service
      How a Service Works
      Installing a Service
             Reporting Installation Status
             Disabling Standard Input and Output
             Parsing Service Parameters
             Installing the Signal Handler
             Spawning the Application Thread
             Completing Installation
      Handling Signals
             Example Service

 Appendix D  Building the Sample Programs

      Building SAMPLES.LIB
      Building the Sample Programs
      Binding the Sample Programs
      Running the Programs
             SAMPLES.C
             SAMPLES.H

 Appendix E  NetBIOS Category

             Description
             Data Structures
             NetBiosClose
             NetBiosEnum
             NetBiosGetInfo
             NetBiosOpen
             NetBiosSubmit
             NetBIOS Category Example

 Appendix F  Network Considerations for Named Pipes

             Description
             MS-DOS Considerations
             Named Pipes Category Example

 Appendix G  Workstation and Server Heuristics

             Workstation Heuristics
             Server Heuristics

 Appendix H  Defined Constants


 Glossary


 Index




 Before You Begin
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 The Microsoft(R) LAN Manager application programming interface (API) is the
 set of functions, datatypes, structures, and constants that enable
 applications to use and control network resources. The Microsoft LAN Manager
 Programmer's Reference describes the components of the LAN Manager API.

 To use this book effectively, you should have a sound working knowledge of
 Microsoft Operating System/2 (MS(R) OS/2) and be familiar with systems
 programming in C or in assembly language.

 LAN Manager API functions work in essentially the same way with both the MS
 OS/2 and MS-DOS(R) operating systems. However, this book primarily addresses
 the MS OS/2 programming environment. Where appropriate, specific notes about
 MS-DOS are included.


 How to Use This Manual

 The Microsoft LAN Manager Programmer's Reference is intended to be your
 master reference for Microsoft LAN Manager API functions. For background
 information about using LAN Manager API functions, read Chapter 1, "Overview
 of the LAN Manager API," which provides an introduction to the LAN Manager
 API. Read Chapter 2, "API Function Descriptions," for information about
 specific LAN Manager API function categories and individual functions. The
 categories, and the functions within them, are arranged alphabetically.

 Read the appendixes for reference information about additional topics, such
 as return codes, constants, named pipes, workstation and server heuristics,
 and upgrading LAN Manager 1.0 applications. Use the glossary to find
 definitions of general network terms and specific LAN Manager terms.


 Notational Conventions

 This manual uses different type styles and special characters to distinguish
 elements of text:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Convention                        Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 bold                              Represents function names and portions
                                   of syntax that must be typed exactly as
                                   shown.

 italics                           Used for variables (such as parameter
                                   names) and text that represents the type
                                   of text to be entered rather than a
                                   literal series of characters. Also used
                                   for data structure names and names of
                                   data structure elements.

 monospace                         Used for data structure syntax, API
                                   function syntax, and code examples.

 FULL CAPITALS                     Represent filenames and pathnames.

 SMALL CAPITALS                    Used for return codes and constants.

 Convention                        Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 [brackets]                        Represent optional items in syntax
                                   statements. For example, [password]
                                   indicates a password can be used with
                                   the command but is not required. Type
                                   only the information within the brackets,
                                   not the brackets themselves.

 . . . (ellipsis)                  Indicates that you can repeat the
                                   previous item(s). For example,
                                   devicename [. . .] indicates that you
                                   can specify more than one device,
                                   separating the devicenames with a space.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 For More Information

 This manual gives general information about using the LAN Manager API, and
 it details the individual components of the LAN Manager API. For information
 about LAN Manager features, see your LAN Manager administrator's manual(s).


 For information about MS OS/2, see your MS OS/2 programming manual(s). For
 information about Microsoft Windows(tm), see your Microsoft Windows
 programming manual(s).






 Chapter 1  Overview of the LAN Manager API
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 The Microsoft LAN Manager application programming interface (API) is the set
 of functions, datatypes, structures, and constants that allow applications
 to use and control network resources.

 This chapter describes how to create applications that call the LAN Manager
 API functions. You will learn the following:


   þ   How to identify API functions, data structures, and variables

   þ   How to include API definitions in your application

   þ   How to call a LAN Manager API function

   þ   How to compile and link LAN Manager applications

   þ   Tips for debugging LAN Manager applications


 For a detailed description of each LAN Manager API function and data
 structure, see Chapter 2, "API Function Descriptions."


 Identifying API Components

 The purpose of LAN Manager API functions, data structures, and variables is
 encoded in their names. All function names and data structure names include
 the name of the network resource. LAN Manager API functions and data
 structures (and this manual) are organized by these categories of network
 resources:

 (This figure may be found in the printed book.)


 API Function Names

 LAN Manager API function names have at least three parts: a keyword (Dos or
 Net), the name of the network resource manipulated by the function, and a
 verb that identifies the action performed on the network resource.

 For example, the API function name NetUserAdd consists of the keyword Net,
 the category User, and the verb Add. Functions in the User category control
 user accounts. Add indicates that the NetUserAdd function adds a user to the
 user accounts database.

 Some verbs appear in many categories: Add adds a resource, Del deletes a
 resource, Enum lists all resources of a particular type, GetInfo returns
 information about one particular resource, and SetInfo sets one or all
 parameters for a particular resource.

 Other verbs describe familiar operations, such as Read, Write, Open, Clear,
 and Close. Some verbs describe tasks that are specific to network resources,
 such as Purge (for a communication-device or printer queue), Forward (for a
 message name), and Raise (for an alert).

 An API function name can also contain an optional fourth part: the object of
 the action. For example, the API function NetGroupDelUser deletes a user
 from the specified group. This function differs from NetGroupDel, which
 deletes the specified group from the user accounts database.


 API Data Structure Names

 LAN Manager API functions use one or more data structures associated with
 each network resource. A data structure name usually contains three parts:
 the name of the resource, the word info, and the level of detail. For
 example, the name share_info_0 indicates that the data structure contains
 information about a share (shared resource) at level 0.

 LAN Manager API functions can accept or return information at different
 levels of detail. Level 0 usually means the least detailed information
 (often a single element). Level 1 usually includes all information provided
 at level 0 plus additional data.

 A higher level of detail often (but not always) indicates that the data
 structure is a superset of data structures provided at lower levels of
 detail. For complete information about available levels and data structures,
 see the "Data Structures" section for each function category in Chapter 2,
 "API Function Descriptions."

 The three data structures of the Share category illustrate the levels of
 detail. The share_info_0 data structure contains only the sharename of a
 particular resource:

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

 The constant NNLEN is defined in the NETCONS.H header file, along with other
 constants that also specify string lengths.

 The share_info_1 data structure contains not only the sharename of the
 resource, as provided at level 0, but also its type and an optional remark.
 The shi1_pad1 element is used only to align the next structure element
 (shi1_type) on a word boundary. Pad elements should not be used to store
 data.

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

 The share_info_2 data structure contains all information present in the
 share_info_1 data structure plus additional information about the sharename
 permissions, path, password, and the number of current and maximum uses:

   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;
   };


 API Variable Names

 The variable names used in the API function prototypes follow the Microsoft
 LAN Manager naming convention. These rules help anyone reading the code
 identify the type and purpose of the variable. Although this naming
 convention is not required to success- fully call the API functions, it is
 recommended because it helps make applications more readable and improves
 programming quality.

 Using the LAN Manager naming convention, variable names have three parts: a
 prefix, a base type, and a qualifier.

 The prefix and base type are always written in lowercase characters. From
 the prefix and base type, you can easily determine the type of a variable.

 Prefix - The prefix provides information about the variable type, such as
 whether it is an array, count, index, or pointer. Prefixes can be combined
 (for example, an array of pointers to indexes). If the base type completely
 describes the variable, the variable name does not need a prefix. The
 following prefixes are used in this manual:

 Prefix  Description  Example
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 a       Array        char             achFileName[ ]
 c       Count        unsigned short   cbAvail
 i       Index        unsigned short   iArgv
 p       Pointer      unsigned char *  pszServer
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Base Type - The base type corresponds to the C-language type. For example,
 ch is used for character, l for long, and s for short. The following base
 types are used in this manual:

ÖÚÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Base Type  Description             Example
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 b          Byte                    unsigned char   bMenuSel
 ch         Character               char            chDriveLetter
 f          Boolean flag            unsigned short  fSuccess
 h          Handle                  unsigned short  hLogFile
 l          Long integer            long            lSeconds
 s          Short integer           short           sIdNumber
 sz         Zero-terminated string  char            szRemark[ ]
 uch        Unsigned character      unsigned char   uchBitMask
 ul         Unsigned long           unsigned long   ulSeconds
 us         Unsigned short          unsigned short  usReturnCode
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Qualifier - The qualifier is a short word or phrase that indicates how the
 variable is used. The qualifier can use both uppercase and lowercase
 characters; the first letter of each word is capitalized. For example, the
 qualifier Available suggests that the variable has to do with some resource
 that is available. The prefix and base type help pinpoint the variable's
 meaning. If the complete variable name is cbAvailable, the name suggests the
 variable contains a count of available bytes. The variable name fAvailable
 suggests that the variable is a Boolean flag that indicates whether the
 resource is available.

 For a description of the naming convention used with MS OS/2, see your MS
 OS/2 programming manual(s).


 Including LAN Manager API Definitions

 LAN Manager API function and data structure definitions are organized by
 category. Your source program can include all the definitions needed for a
 particular category of network resources by using the C-language #define
 statement for that category and the #include <lan.h> statement.

 The LAN.H header file is the master file of the set of LAN Manager header
 files. LAN.H is the LAN Manager equivalent of OS2.H, the MS OS/2 master
 header file. When a constant is defined in your source file, the LAN.H file
 includes all the header files associated with that category. You should
 define constants for only those resource categories used in your
 application.

 For example, use these statements to provide access to all functions,
 datatypes, structures, and constants associated with workstations, and to
 all LAN Manager error codes:

   #define INCL_NETWKSTA
   #define INCL_NETERRORS
   #include <lan.h>

 Programs that use the LAN.H master header file can be more easily maintained
 than programs that specify individual header files. For examples of how to
 use the LAN.H header file, see the "Example" section at the end of each
 category in Chapter 2, "API Function Descriptions."

 The following table lists each LAN Manager API category and the constants
 that must be defined to include definitions associated with that category:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Category                           #define Constant
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 All categories except print        INCL_NET
 Errors for all categories          INCL_NETERRORS
 Access Permissions                 INCL_NETACCESS
 Alert                              INCL_NETALERT
 Audit                              INCL_NETAUDIT
 Character Device                   INCL_NETCHARDEV
 Configuration                      INCL_NETCONFIG
 Connection                         INCL_NETCONNECTION
 Domain                             INCL_NETDOMAIN
 Error Logging                      INCL_NETERRORLOG
 File                               INCL_NETFILE
 Group                              INCL_NETGROUP
 Handle                             INCL_NETHANDLE
 Mailslot                           INCL_NETMAILSLOT
 Message                            INCL_NETMESSAGE
 Category                           #define Constant
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Message                            INCL_NETMESSAGE
 NetBIOS                            INCL_NETBIOS
 Print                              (Uses #include <pmspl.h>)
 Remote Utility                     INCL_NETREMUTIL
 Server                             INCL_NETSERVER
 Service                            INCL_NETSERVICE
 Session                            INCL_NETSESSION
 Share                              INCL_NETSHARE
 Statistics                         INCL_NETSTATS
 Use                                INCL_NETUSE
 User                               INCL_NETUSER
 Workstation                        INCL_NETWKSTA
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Note that the categories relating to printer resources cannot be included
 using this method. The structures and definitions for printer resources are
 defined in the PMSPL.H header file. An application should include this
 header file by using an #include statement:

   #include <pmspl.h>


 Calling a LAN Manager API Function

 An API function call can succeed if the application has privilege to call
 that API function and if the application provides all necessary parameters
 in the correct format. One parameter required by many API functions is a
 pointer to a buffer. If the buffer is used for input data, it must contain
 the correct data; if the buffer is used for output data, it must be large
 enough to contain the data returned by the API function. The application may
 need to examine the codes returned by the API function and take specific
 action.


 Calling Privileges

 LAN Manager API functions check security on servers that have local security
 enabled and on remote servers. If local security is not enabled, LAN Manager
 does no local checking.

 The accounts database, NET.ACC, contains information about all users who are
 allowed access to the computer's resources. Three privilege levels are
 defined: admin, user, and guest. An account with user privilege can also
 have up to four types of operator privilege (an operator privilege allows a
 user to perform some limited administrative functions).  An account with
 user privilege can have the print, comm, server, and accounts operator
 privileges.


 For remote computers and local computers running a secure shell or other
 form of local security, each API function verifies that the user has
 sufficient privilege to execute the function. For more information about
 security and privilege levels, see your Microsoft LAN Manager
 administrator's manual(s). If your account does not have correct privilege
 levels, contact your system administrator.

 The privilege level required for each API function is specified in Chapter
 2, "API Function Descriptions."


 Parameter Formats

 The parameters needed to successfully call each LAN Manager API function are
 defined in Chapter 2, "API Function Descriptions."

 Many parameters required by the API functions are ASCIIZ strings that
 represent names such as computernames, sharenames, usernames, and pathnames.
 (An ASCIIZ string is a sequence of ASCII characters terminated by the ASCII
 character NUL, the C-language character constant '\0'. Remember to allow for
 the final NUL when calculating string and buffer lengths.)

 One of the most common parameters required by LAN Manager API functions is a
 servername. This parameter usually appears first in the API function call
 and is specified in the function prototypes as pszServer. The servername
 parameter specifies whether the function call is a local or remote call. A
 null pointer or null string indicates that the operation is to be performed
 on the local computer. An ASCIIZ string containing the servername must start
 with two backslash characters (\\). Because the backslash is a special
 character in the C language, you must use additional backslashes when
 specifying servernames. For example, to specify the remote server named
 MARKETING in a C-language program, use the following:

   pszServer = "\\\\MARKETING";

 Other parameters in LAN Manager API functions follow two naming conventions:
 one for pathnames and one for all other names. Pathnames generally follow
 the naming convention of the installed file system.

 The convention for all other names is very similar to the convention used
 for file allocation table (FAT) file system names.

 These naming conventions are usually enforced only by Add functions. For
 example, if the supplied name is incorrect, Add functions return an error
 message that indicates an improper name was used; GetInfo functions usually
 return an error that indicates the resource was not found.

 Length Restrictions - The file system defines the maximum length of the
 pathname. The FAT file system supports names that have up to eight
 characters, an optional period (.), and an optional filename extension with
 as many as three characters. This is often called the "8.3" format.

 The high-performance file system (HPFS) supports longer names. The MS OS/2
 function DosQSysInfo can be used to determine the maximum path length. For
 more information, see your MS OS/2 programming manual(s).

 The maximum lengths of other names are defined by constants in the NETCONS.H
 header file. For example, sharenames are limited to the number of characters
 specified by the constant value NNLEN, defined in NETCONS.H. For more
 information, see Appendix H, "Defined Constants."

 Character Restrictions  - The file system also defines the set of characters
 allowed in network names. The FAT file system has the most restrictive rules
 and HPFS has the least restrictive rules.

 Network names cannot use nonprinting ASCII characters (characters 0x00
 through 0x1F) or any characters recognized as special characters by the
 operating system command shell.

 The following characters are not allowed in network names on a computer that
 has the FAT file system installed:

 \ / : * ? " <  > | , + = [ ] ;

 The following characters are not allowed in network names on a computer that
 has HPFS installed:

 \ / : * ? " <  > |

 The period (.) is allowed in pathnames as permitted by the file system. It
 is also allowed in other network names. The asterisk (*) is allowed as part
 of the network name by some Mailslot category API functions. For more
 information, see the Mailslot category functions in Chapter 2, "API Function
 Descriptions."


 Using Buffers with API Functions

 Many API functions require a pointer to a buffer. This pointer parameter is
 often associated with other parameters that indicate the level of detail
 provided in the buffer, the size of the buffer, the amount of data
 successfully returned in the buffer, and the amount of data that was
 available to be returned in the buffer.

 The buffer can be used for both output and input. GetInfo and Enum functions
 use the buffer for return data; Add and SetInfo functions use the buffer for
 input.

 Buffers for Return Data - GetInfo and Enum functions return data in the
 supplied buffer. GetInfo functions return information about a single
 resource; Enum functions return information about all instances of the
 resource type. The supplied buffer should be large enough to contain all
 data returned by the API function.

 This data usually consists of fixed-length and variable-length elements.
 Fixed-length elements have a known, defined size; variable-length elements
 are allowed to vary, up to a maximum length. (For example, ASCIIZ strings
 are variable-length elements.) If the buffer cannot hold all available data,
 the API function returns a code that indicates more information is
 available.

 Even if the buffer is too small, GetInfo functions report the available
 number of bytes, and Enum functions return the number of records.
 Applications that must optimize memory use can make two calls to these
 functions. So that the application can allocate a buffer large enough to
 hold the return data, the first call determines the size of the buffer
 needed to hold the return data. The second call can then fill the buffer
 with data.

 For example, if the application supplies a null buffer pointer and a buffer
 length of 0, the first GetInfo call returns the code NERR_BufTooSmall, but
 also returns a pcbTotalAvail value that indicates the size of the return
 data (in bytes). The application can then allocate a buffer this size and
 make a second GetInfo call with valid buffer pointer and size values.

 GetInfo and SetInfo functions are commonly used together. You can call the
 GetInfo function to learn the value of the parameters associated with the
 resource, then change the values of the parameters and call the SetInfo
 function to set the new values.

 Buffers for Input Data - Add and SetInfo functions set information about a
 network resource. These functions require a parameter that points to a
 buffer (pbBuffer); this buffer parameter is associated with other parameters
 that represent the level of detail (sLevel) and the buffer size (cbBuffer).


 SetInfo functions also require a parameter number code (sParmNum) that
 specifies whether to set a single element or all elements of the data
 structure for the resource. If sParmNum is PARMNUM_ALL, all elements are to
 be set, and pbBuffer should point to a buffer that contains the complete
 data structure at the specified level. If sParmNum is any other defined
 value, it should contain a code that specifies the single element of the
 data structure to be set, and pbBuffer should point to a variable that
 contains the new value for that element.

 Add and SetInfo functions that specify a remote server will successfully
 transmit variable-length data only if the pointers point outside the
 supplied data buffer. This optimizing technique for remote calls minimizes
 the amount of data transmitted over the network. The buffer is determined by
 the pbBuffer and cbBuffer parameters. To assure that the data is
 transmitted, the buffer size can be set to the size of the fixed-length data
 structure, or all pointers can be reset to point to data that is not within
 the buffer.

 To change a string to an empty string, you must use a valid pointer to an
 empty string rather than using a null pointer. If a null pointer is used in
 a SetInfo call, the string is not changed.


 Interpreting Return Codes

 The name of the return code suggests the result. For example,
 NERR_ServerNotStarted means, as the name suggests, that the Server service
 must be started for the API function to succeed. The return code
 NERR_BadTransactConfig indicates that a server is not configured to allow
 interprocess communication. The description for this return code explains
 that to allow remote API function requests, the server must share IPC$ (the
 special interprocess communication resource).

 Typical return codes for each function are included with that function's
 description in Chapter 2, "API Function Descriptions." Appendix A, "LAN
 Manager Return Codes," lists all codes that can be returned by LAN Manager
 API functions. For your con- venience, some MS OS/2 return codes are given;
 for more information about MS OS/2 return codes, see your MS OS/2
 programming manual(s).

 Descriptions of return codes are also available using the MS OS/2
 DosGetMessage function. If you supply the return code and the LAN Manager
 error message file NET.MSG as parameters, DosGetMessage returns a string
 that contains a description

 of the return code. For more information about DosGetMessage, see your MS
 OS/2 programming manual(s). For an example, see the Session category example
 program in Chapter 2, "API Function Descriptions."

 In a few cases, a code returned by an API function has a meaning that is
 relevant only for that API function. The "Remarks" section of each API
 function description in Chapter 2, "API Function Descriptions," describes
 how to interpret the return codes in these special cases.

 Return Codes Relating to the Buffer - The return codes NERR_BufTooSmall and
 ERROR_MORE_DATA are related not only to the buffer, but also to the buffer
 size and the byte count or record count parameters.

 If the buffer is too small to store the fixed-length part of the data
 record, GetInfo functions return NERR_BufTooSmall. In this case, all data in
 the return buffer is invalid, but the count  of available data bytes,
 pcbTotalAvail, is valid. The application can use the value of pcbTotalAvail
 to allocate a buffer large enough to contain the return data, and then make
 another GetInfo call to obtain the data. If the fixed-length part of the
 data record does fit but the variable-length part does not fit, GetInfo
 functions return ERROR_MORE_DATA, and all pointers to variable-length parts
 are set to NULL.

 If the available data cannot fit in the supplied buffer, Enum functions
 return the code ERROR_MORE_DATA. In this case, the Enum function stores in
 the return buffer as many complete data records as possible (both the
 fixed-length and variable-length parts). If the complete data record cannot
 be returned, the function tries to store its fixed-length part in the
 buffer. If only the fixed-length part fits, the function sets all pointers
 to variable-length parts to NULL, and then returns ERROR_MORE_DATA.

 When ERROR_MORE_DATA is returned by an Enum function, the value returned in
 pcEntriesRead does not necessarily represent the number of complete records
 in the buffer; it may represent the number of complete records and records
 that contain only the fixed-length element. In this case, all fixed-length
 data in the buffer is valid and the value of pcTotalEntries is valid, but
 some pointers to variable-length data may have been set to NULL if the
 variable-length data did not fit in the buffer.


 Compiling and Linking Applications

 LAN Manager applications can be compiled like any other applications for the
 target operating system. For example, Microsoft Windows applications
 compiled with the Microsoft C Optimizing Compiler should use the -Gw switch.


 The application should be linked with the libraries that contain the LAN
 Manager API functions. These functions reside in static-link or dynamic-link
 libraries. The type of link library used depends on the operating system
 used by the application (MS-DOS, Microsoft Windows 2.x, Microsoft Windows
 3.0, MS OS/2 1.1, or MS OS/2 1.2).

 LAN Manager operates in similar ways with MS OS/2, MS-DOS, and Windows,
 although the operating system allows more functionality when LAN Manager
 operates with MS OS/2. MS OS/2 supports multiple program threads and all LAN
 Manager services; when installed with HPFS, MS OS/2 also supports long file
 names. MS-DOS and Windows support only one program thread, FAT "8.3"
 filenames, and the Messenger, Netpopup, and Workstation services.

 In systems with MS-DOS, the LAN Manager API functions reside in the
 static-link library DOSLAN.LIB. MS-DOS applications are linked with
 static-link libraries in one step at link time. Only one library is needed.


 In systems with MS OS/2 and Windows, the LAN Manager API functions reside in
 the dynamic-link library (.DLL) file. Note that Microsoft Windows 2.x
 dynamic-link libraries use the file extension .EXE instead of .DLL.

 More than one link library may be needed for these operating system
 platforms, depending on the platform and the LAN Manager API functions
 called by the application. The Print category API functions reside in the
 PMSPL library; all other API functions reside in the LAN library. These are
 the link libraries:

                              Dynamic-Link
 Platform     Import Library  Library            Function Category
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 MS OS/2 1.2  PMSPL.LIB       PMSPL.DLL          Print categories.
              LAN.LIB         NETAPI.DLL         All other categories.
                              MAILSLOT.DLL
                              NETOEM.DLL

 MS OS/2 1.1  NETSPOOL.LIB    NETSPOOL.DLL       Print categories.
              LAN.LIB         NETAPI.DLL         All other categories.
                              MAILSLOT.DLL
                              NETOEM.DLL

 Windows 3.0  PMSPL.LIB       PMSPL.DLL          Print categories.
              LAN.LIB         NETAPI.DLL         All other categories.

 Windows 2.x  PMSPL.LIB       PMSPL.EXE          Print categories.
              LAN.LIB         NETAPI.EXE         All other categories.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Debugging Tips

 Incorrect buffer sizes and incorrect input parameters often cause software
 flaws in applications that call LAN Manager API functions. The following
 sections discuss some common problems and give some tips for debugging LAN
 Manager applications.


 Stack Overflow

 When calling LAN Manager API functions, be sure that at least 4 kilobytes
 (K) of stack is available, or the API function may exceed the stack limits
 and cause the application to fail. MS OS/2, MS OS/2 Presentation Manager,
 and Microsoft Windows also have their own minimum stack size requirements.
 LAN Manager applications using these platforms require an additional 4K of
 stack.


 Errors in Hard-Coded Values

 The LAN Manager header files define symbolic constants for bit values, mask
 values, and return codes. You should always use these defined constants
 instead of hard-coded numeric values. The use of symbolic constants makes an
 application program easier to debug and maintain.


 Errors During Pointer Type Conversion

 LAN Manager API functions, like MS OS/2 API functions, must be referenced
 using far calls. LAN Manager API function pointer parameters are defined as
 far pointers in the function prototypes.

 Other common software flaws can be avoided if you use LAN.H to access the
 LAN Manager header files.

 If you include the LAN Manager header files in small or medium memory model
 programs, all pointer parameters to LAN Manager API functions are promoted
 to far pointers.

 You should be aware that values for null pointers can be different for far
 and near pointers. Null far pointers have the segment:offset value 00:00;
 most compilers promote near pointers that have the value NULL to far
 pointers that have the value DS:00. Even when the program explicitly casts
 the near pointer as a far pointer before the LAN Manager API function call,
 the pointer is converted to the value DS:00.

 LAN Manager API functions have been designed to avoid many bugs resulting
 from pointer promotion. The API functions accept either a null string or a
 null pointer for the servername parameter. This takes advantage of a feature
 of many compilers: the compiler places four bytes containing the value 0 at
 the location DS:00. Although the near pointer promoted to a far pointer may
 no longer be a null pointer, it points to the location DS:00, which contains
 a null string.

 To avoid software flaws, use the symbolic constant NULL rather than the
 value 0, as shown in the following example:

   if ((p = malloc(SOME_SIZE)) == NULL) ...


 MS OS/2 Protection Violations and Faults

 MS OS/2 runs under protected mode. In protected mode, each process on a
 computer is protected from errors generated by another process. Software
 flaws in an application that might crash a system with MS-DOS are trapped by
 MS OS/2 as process-specific protection violations and faults. This fault may
 stop that process but will not affect other programs.

 Protection violations and faults in the LAN Manager API dynamic-link
 libraries are often caused by invalid input parameters and invalid buffer
 length values. When API functions access invalid data, MS OS/2 generates a
 protection fault. For example, a fault can occur if a pointer points beyond
 the end of a segment or outside a valid memory region.

 If a fault occurs within a LAN Manager dynamic-link library, check the
 values of the parameters passed to the API function.


 MS-DOS, Windows 2.x, and Real-Mode Windows 3.0 Applications

 Invalid pointer data can cause unpredictable results in LAN Manager
 applications with MS-DOS, Microsoft Windows 2.x, and real-mode Microsoft
 Windows 3.0 applications.

 Windows manages memory resources to optimize memory use and performance.
 Like any other Windows application, a LAN Manager application should
 carefully monitor its use of pointers. If Windows moves a data segment as
 part of its memory management, pointers may no longer be valid; you should
 lock all buffers before passing them to LAN Manager API functions. For more
 information, see your Microsoft Windows programming manual(s).


 Windows 3.0 Protected-Mode Applications

 Applications written for Microsoft Windows 3.0 can be executed in protected
 mode. Software flaws in applications running with Windows 3.0 protected mode
 cause the application to terminate, and control is returned to Windows 3.0.
 The user is notified of an unrecoverable program error.

 Software flaws in LAN Manager applications running with Microsoft Windows
 3.0 protected mode are often caused by invalid input parameters, invalid
 buffer lengths, and invalid pointer values. If an error occurs, check the
 values of the parameters passed to the API functions.






 Chapter 2  API Function Descriptions
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 This chapter provides detailed information about each LAN Manager
 application programming interface (API) function. It describes the syntax of
 each API function, describes operations the API function performs, and lists
 the data structures and header files the function uses.

 This chapter is divided into sections according to API function category.
 The following function categories are presented in this chapter:

 (This figure may be found in the printed book.)

 Each category begins with an overview that explains how the API functions in
 that category interrelate and how they work with LAN Manager. Data
 structures common to several or all of the functions are described.

 A detailed description of each API function follows the overview, and
 includes the operating system platforms supported by the API function, the
 privilege level required to successfully execute the API function, the
 function's syntax, and a detailed description of each parameter.

 The most common error codes returned by the function are also listed. A list
 of all error codes returned by the LAN Manager API functions is provided in
 Appendix A, "Return Codes."

 At the end of each section you will find an example that demonstrates calls
 to the API functions in that category.

 The category sections and the entries within them are ordered
 alphabetically. To make information easy to find and use, each category and
 each API within the category begins on a new page.

 The functionality of some LAN Manager API functions is different in LAN
 Manager 2.0 from LAN Manager 1.0. Some 1.0 functions are no longer
 supported, and some 1.0 functions, although still supported by LAN Manager
 2.0, have been superseded by new functions and should not be used. For
 information about the functions that have changed, see Appendix B,
 "Upgrading LAN Manager 1.0 Applications." The NetBIOS category is presented
 in Appendix E, "NetBIOS Category." It is recommended that you use Mailslot
 and Named Pipe API functions in LAN Manager 2.0 instead of the NetBIOS API
 functions.


 Format Reference Pages

 This section illustrates what you will see in each API function description.



 API Function

 The description of each API function begins with a general description of
 the purpose of the API function.


 Operating Systems Supported

 This section indicates whether the API function can be used remotely,
 locally only, or if it is not supported by a particular operating system.


 Privilege Level

 This section indicates the privilege level a user must have to execute this
 particular API function.


 Syntax

 This section lists the constants that must be defined so that the LAN.H
 header file will include the appropriate definitions. It also describes, in
 sequence, each of the parameters required to successfully call the API
 function.


 Return Codes

 This section lists the return codes the API function is most likely to
 return. Note that this list is not exhaustive. For a complete list of LAN
 Manager return codes, see Appendix A, "Return Codes."


 Remarks

 This section describes important details about the performance of the API
 function. You should take these details into consideration so your
 application can successfully call the API function and efficiently use its
 results.


 See Also

 This section refers you to other sections or chapters in this manual or to
 other manuals that may help you better understand and use the API function.






 Access Permissions Category

 Access Permissions API functions examine or modify user or group access
 permissions for specified resources. Access Permissions API functions
 require that the user account subsystem (UAS) be started. On most computers
 the UAS is started when the Workstation service is started, provided a valid
 user accounts database file exists. On computers using the high-performance
 file system 386 (HPFS386) with local security enabled, the UAS is started
 automatically as part of the boot process.

 The Access Permissions category functions, datatypes, structures, and
 constants are defined in the NETCONS.H, NETERR.H, and ACCESS.H header files.
 A source program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETACCESS, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Access Permissions API functions:


   þ   NetAccessAdd

   þ   NetAccessCheck

   þ   NetAccessDel

   þ   NetAccessEnum

   þ   NetAccessGetInfo

   þ   NetAccessGetUserPerms

   þ   NetAccessSetInfo



 Description

 An access control list (ACL) contains the name of a resource, an audit
 attribute field, and a list of access control entries. An access control
 entry (ACE) is a username or groupname and its corresponding access
 permissions.

 The audit attribute field defines what type of events will be audited for
 that resource. It is possible to audit various types of events, depending on
 whether the resource is a file or a directory. It is possible to audit
 events such as opening, writing, and deleting a file; creating or deleting a
 directory; and changing the ACL of the resource.

 There is no restriction on the number of ACLs for computers using HPFS386.
 Computers not using HPFS386 can have as many as 8192 ACLs defined. Each ACL
 can have as many as 64 ACEs.

 By default, non-admin class users have no access permissions. For a
 non-admin class user to access a resource on a remote server that has
 user-level security enabled or on a computer that has local security, there
 must be an ACL for the resource and there must be an ACE for the user. If
 local security is not enabled, non-admin class users can access all local
 resources.

 A user with admin privilege can access all resources, both local and remote,
 because LAN Manager does not check ACLs for this class of user.

 Access permission for a resource is determined according to the following
 rules:


   þ   File permissions override directory permissions. If a user is assigned
       specific permissions for a file, directory level permissions no longer
       apply to that file.

   þ   Individual permissions override group permissions. If a user is
       assigned specific individual permissions, group permissions no longer
       apply.

   þ   Group permissions are combined. If a user belongs to more than one
       group, the permissions are all the permissions for the groups to which
       the user belongs.

   þ   Access is checked for the guest user when there is no ACE for the user
       or for any groups to which the user belongs. If the guest account
       exists and has access to the resource, the user is granted that same
       level of access.


 Access permission is checked on three levels for file-system resources:
 first, the resource itself; then the parent of the resource; then the drive
 on which the resource is located. For example, in checking permission for
 the resource C:\XXX\YYY\ZZZ, the resource C:\XXX\YYY\ZZZ is searched for,
 then C:\XXX\YYY is searched for, and finally C: is searched for. Note that
 the last check is on the drive-level permissions, not the root directory of
 the drive.

 Access permission is also checked on three levels for logical resources:
 first, the resource itself; then the parent of the resource; then the root
 of the resource. For example, in checking permission for the resource
 \PIPE\XXX\YYY\ZZZ, the resource \PIPE\XXX\YYY\ZZZ is searched for, then
 \PIPE\XXX\YYY is searched for, and finally \PIPE is searched for.

 NetAccessAdd creates an ACL for a resource and sets username or groupname
 access permissions. NetAccessDel deletes the ACL for a resource.
 NetAccessGetInfo returns the ACL for a particular resource. NetAccessEnum
 returns information about all ACLs.

 Only users or applications with admin privilege or special permission for
 the resource can define or examine access permissions on a remote server or
 on a computer that has local security. Users have special permissions for a
 resource when they are granted ACCESS_PERM permission for that resource;
 this is also known as P permission.

 NetAccessCheck verifies whether a user has permission to perform a specified
 operation on a particular resource. If access permission is needed, you can
 use NetAccessSetInfo to change the ACL. NetAccessGetUserPerms returns a
 specified user's or group's permission for a specified resource.

 Note that the ACL does not specify permissions on a server that has
 share-level security. Each resource is verified on a share-by-share basis
 (each shared resource has its own password). After establishing a connection
 to a shared resource (by providing the appropriate password), users can
 access the resource any way they choose, as defined by the resource.

 All Access Permissions API functions executed on a remote server require
 that the server have user-level security. An attempt to execute an Access
 Permissions API function on a remote server that has share-level security
 returns the ERROR_NOT_SUPPORTED error code.


 Data Structures

 The sLevel parameter controls the level of information provided to or
 returned from the NetAccessAdd, NetAccessEnum, NetAccessGetInfo, and
 NetAccessSetInfo functions. NetAccessEnum and NetAccessGetInfo use either an
 access_info_0 or access_info_1 data structure. NetAccessAdd and
 NetAccessSetInfo use only an access_info_1 data structure.


 Access Permissions Information (level 0)

 The access_info_0 data structure has this format:

   struct access_info_0 {
       char far *  acc0_resource_name;
   };

 where

 acc0_resource_name
   Points to an ASCIIZ string that contains the name of a resource. The
   resource name cannot be a null string. Resources can be of the following
   types, and are specified using the associated name format:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Resource Type            Name Format              Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Drive                    drive:                   No path is specified;
                                                   the drive must exist.

 Path                     \path                    No drive is specified;
                                                   the path need not exist.


 Directory                drive:\pathname          The path must exist.

 File                     drive:\pathname          The file must exist.

 UNC                      \\server\sharename\path  The path must exist.

 Pipe                     \pipe\pipename

 Printer queue            \print\queuename

 Communication-device     \comm\chardevqueue
 queue
 Resource Type            Name Format              Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
queue

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   Calls to Access Permissions functions can also use the universal naming
   convention (UNC) to access a device, computer, or resource over the
   network (for example, \\server\sharename\file.ext is a UNC name). If a UNC
   name is given, the function ignores any servername given in the pszServer
   parameter.


 Access Permissions Information (level 1)

 The access_info_1 data structure has this format:

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

 where

 acc1_resource_name
   Points to an ASCIIZ string that specifies the name of a particular
   resource. For more information, see the preceding section.

 acc1_attr
   Specifies the auditing attributes of acc1_resource_name. If acc1_attr is
   0, no auditing is required. If acc1_attr is 1, all access events should be
   audited. Other values indicate auditing of specific access events, as
   defined by the bits of acc1_attr, as follows:

ÖÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Bit    Files                                          Directories
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0      Audit all. When this bit is set, all access    Same.
        attempts are audited. No other bits in the
 Bit    Files                                          Directories
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
       attempts are audited. No other bits in the
        field can be set at the same time.

 1-2    Reserved; must be 0.                           Reserved; must be 0.

 3      Ignored.                                       Reserved.

 4      Successful opens.                              Reserved.

 5      Successful writes.                             Successful creates.

 6      Successful deletes/truncates.                  Successful deletes.

 7      Successful ACL changes.                        Same.

 8      Failed opens.                                  Reserved.

 9      Failed writes.                                 Failed creates.

 Bit    Files                                          Directories
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 10     Failed deletes/truncates.                      Failed deletes.

 11     Failed ACL changes.                            Same.

 12-15  Reserved; must be 0.                           Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   Other resources that can be accessed over the network, including printer
   queues, communication-device queues, and pipes, are audited the same way
   as files.

   When write auditing is enabled, the write audit record is generated the
   first time the record is opened with write permission.

   File size changes (including truncation) are audited under the control of
   the write audit bits, 5 and 9.

 acc1_count
   Specifies the number of access_list data structures that follow the
   access_info_1 data structure. As many as 64 access_list data structures
   can follow. The access_list structures define resource permissions for
   individual users or groups.


 Resource Permissions

 The access_list data structure has this format:

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

 where

 acl_ugname
   Specifies an ASCIIZ string that contains a particular username or
   groupname. The constant UNLEN is defined in the NETCONS.H header file.

 acl_ugname_pad_1
   Aligns the next data structure element on a word boundary.

 acl_access
   Specifies the permissions for the username or groupname. The ACCESS.H
   header file defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code           Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ACCESS_READ    0x01    Permission to read data from a resource and, by
                        default, execute the resource.

 ACCESS_WRITE   0x02    Permission to write data to the resource.

 ACCESS_CREATE  0x04    Permission to create an instance of the resource
                        (for example, a file); data can be written to the
 Code           Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                       (for example, a file); data can be written to the
                        resource when creating it.

 ACCESS_EXEC    0x08    Permission to execute the resource.

 ACCESS_DELETE  0x10    Permission to delete the resource.

 ACCESS_ATRIB   0x20    Permission to modify the resource's attributes (for
                        example, the date and time a file was last
                        modified).

 ACCESS_PERM    0x40    Permission to modify the permissions (read, write,
                        create, execute, and delete) assigned to a resource
                        for a user or an application.

 ACCESS_ALL     0x7F    Permission to read, write, create, execute, or
                        delete a resource, or to modify attributes or
                        permissions.

 Code           Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ACCESS_GROUP   0x8000  Permission for a particular group; this value
                        indicates that the entry is for a group.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Connecting to resources           Use Category

 Sharing resources                 Share Category


 NetAccessAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessAdd creates a new access control list (ACL) for a resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetAccessAdd on a remote
 server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETACCESS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAccessAdd (const char far *  pszServer,
                 short             sLevel,
                 char far *        pbBuffer,
                 unsigned short    cbBuffer
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAccessAdd. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail provided; must be 1.

 pbBuffer
   Points to the buffer that contains the data to be added. The buffer should
   contain an access_info_1 data structure that specifies the name of the
   resource for which to create an ACL, the resource's audit attributes, and
   a count of the number of access control entries that follow. The structure
   can be followed by access_list data structures that specify a username or
   groupname and associated access permissions for the resource.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_ResourceNotFound             2222    The resource name was not found.

 NERR_ResourceExists               2225    The resource access record
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ResourceExists               2225    The resource access record
                                           already exists.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFNoRoom                    2228    The user accounts database is
                                           full.

 NERR_ACFTooManyLists              2230    Each resource can have no more
                                           than 64 access records defined.


 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetAccessAdd returns ERROR_NOT_SUPPORTED when executed remotely on a server
 that has share-level security.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Add functions                     Chapter 1, "Overview of the LAN Manager
                                   API"

 Deleting an access control list   NetAccessDel

 Listing permissions and           NetAccessEnum
 resources

 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"


 NetAccessCheck
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessCheck verifies that a user has permission to perform a specified
 operation on a particular resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1 not supported

   þ   MS-DOS not supported



 Privilege Level

 Admin privilege is required to successfully execute NetAccessCheck on a
 computer that has local security enabled.


 Syntax

   #define INCL_NETACCESS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAccessCheck (char far *            pszReserved,
                   char far *            pszUserName,
                   char far *            pszResource,
                   unsigned short        usOperation,
                   unsigned short far *  pusResult
                  );

 where

 pszReserved
   Reserved; must be set to NULL.

 pszUserName
   Points to an ASCIIZ string that contains a username. If pszUserName
   specifies a groupname, NetAccessCheck returns NERR_UserNotFound.

 pszResource
   Points to an ASCIIZ string that contains the name of the resource.

 usOperation
   Specifies the type of access operation requested. Any combination of the
   following operations can be requested, as defined in the ACCESS.H header
   file:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code           Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ACCESS_READ    0x01   Permission to read data from a resource and, by
                       default, execute the resource.

 ACCESS_WRITE   0x02   Permission to write data to the resource.

 ACCESS_CREATE  0x04   Permission to create an instance of the resource
                       (for example, a file); data can be written to the
                       resource when creating it.

 ACCESS_EXEC    0x08   Permission to execute the resource.

 ACCESS_DELETE  0x10   Permission to delete the resource.

 Code           Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ACCESS_ATRIB   0x20   Permission to modify the resource's attributes (for
                       example, the date and time a file was last modified).

 ACCESS_PERM    0x40   Permission to modify the permissions (read, write,
                       create, execute, and delete) assigned to a resource
                       for a user, group, or application.

 ACCESS_ALL     0x7F   Permission to read, write, create, execute, or
                       delete a resource, or to modify attributes or
                       permissions.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 pusResult
   Points to an unsigned short integer that specifies whether or not the
   operation is allowed. This parameter is valid only when NetAccessCheck
   returns NERR_Success. If the username has the requested permissions and
   the operation is allowed, pusResult is 0; otherwise, pusResult is set to
   ERROR_ACCESS_DENIED.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_UserNotFound                 2221    The username was not found, or a
                                           groupname was specified instead
                                           of a username.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If NetAccessCheck cannot find an entry for the resource/username combination
 on the specified server, it searches for an entry for the guest account, a
 special account set up for temporary users of the resource. In this case,
 the user has the same access permissions as the guest account. The guest
 account can be defined in the LANMAN.INI file, or it can be specified at
 server startup time. For more information about guest accounts, see your LAN
 Manager administrator's manual(s).

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Defining username or groupname    NetAccessAdd
 access permissions

 Listing all permissions and       NetAccessEnum
 resources


 NetAccessDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessDel deletes the access control list (ACL) for a particular
 resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or P permission for the resource is required to successfully
 execute NetAccessDel on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETACCESS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAccessDel (const char far *  pszServer,
                 char far *        pszResource
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAccessDel. A null pointer or null string specifies the local
   computer.

 pszResource
   Points to an ASCIIZ string that contains the name of the resource to
   delete.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_ResourceNotFound             2222    The resource name was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetAccessDel returns ERROR_NOT_SUPPORTED when executed remotely on a server
 that has share-level security.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Defining username or groupname    NetAccessAdd
 access permissions

 Listing all permissions and       NetAccessEnum
 resources


 NetAccessEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessEnum lists all access permissions records.

 It is recommended that you not use NetAccessEnum because it is unlikely to
 be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or P permission for the resource is required to successfully
 execute NetAccessEnum on a remote server or on a computer that has local
 security enabled.

 If NetAccessEnum is called by a non-admin class user, only those resources
 for which the user has P permission will be listed.


 Syntax

   #define INCL_NETACCESS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAccessEnum (const char far *      pszServer,
                  char far *            pszBasePath,
                  short                 fsRecursive,
                  short                 sLevel,
                  char far *            pbBuffer,
                  unsigned short        cbBuffer,
                  unsigned short far *  pcEntriesRead,
                  unsigned short far *  pcTotalAvail
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAccessEnum. A null pointer or null string specifies the
   local computer.

 pszBasePath
   Points to an ASCIIZ string that contains a base pathname for the
   resources. A null pointer or null string means no base path is to be used.
   The path can be specified as a universal naming convention (UNC) pathname.

 fsRecursive
   Enables or disables recursive searching. If fsRecursive is 0,
   NetAccessEnum returns entries only for the resource named as the base path
   by pszBasePath and for the resources directly below that base path. If
   fsRecursive is nonzero, NetAccessEnum returns entries for all access
   control lists (ACLs) that have pszBasePath at the beginning of the
   resource name. The fsRecursive parameter interacts with pszBasePath in the
   following way:

 fsRecursive  pszBasePath = NULL             pszBasePath set
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0            Nondirectory and nonfile       The path itself and all
              resources are listed (\comm,   resources immediately below
              \pipe, \print).                the path are listed.

 1            All resources are listed.      The path itself and all
                                             resources anywhere below
                                             the path are listed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of access_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested. If called
   at level 1, each access_info_1  data structure is followed by as many
   access_list data structures as specified in the acc1_count element of that
   access_info_1 data structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer that specifies how many entries were
   returned. This count is valid only if NetAccessEnum returns NERR_Success
   or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer that specifies how many entries were
   available. This count is valid only if NetAccessEnum returns NERR_Success
   or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_ResourceNotFound             2222    The resource name was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 The pszBasePath parameter limits the entries returned by NetAccessEnum. If
 pszBasePath points to a string that is not null, it serves as a prefix for
 the pathname. For example, if pszBasePath is C:\PROG, NetAccessEnum returns
 access permissions records for resources that begin with C:\PROG (such as
 C:\PROGRAM, C:\PROG\TEST.EXE, and C:\PROGDIR\SUBDIR\SUBTEST.EXE). The
 resource names are returned with the base path omitted from the front of the
 name, and the resource names are not returned in any particular order.

 The pcTotalAvail parameter points to an unsigned short integer that
 specifies how many entries were available for the given pszBasePath and
 fsRecursive parameters, not the total number of entries in the access file.
 NetAccessEnum can provide as many as 64K of data for any given base path.

 If more data is available than can fit in the buffer, NetAccessEnum returns
 the code ERROR_MORE_DATA. More data can be read by increasing the size of
 the buffer or by calling NetAccessEnum with the same size buffer but
 different base paths.

 With computers using the high-performance file system 386 (HPFS386), HPFS
 files have their associated ACL information stored on the disk with the
 file. This is unlike non-HPFS386 systems, where the ACL information is
 grouped in the resource database. If NetAccessEnum is used with the
 recursive switch set and no pszBasePath, a complete downward traversal of
 each HPFS drive is necessary. This can cause the call to be substantially
 slower on an HPFS386 system than on a non-HPFS386 system. It is recommended
 that a base path be provided when using NetAccessEnum with the recursive
 flag enabled, so that only the information needed is returned.

 NetAccessEnum returns ERROR_NOT_SUPPORTED when executed remotely on a server
 that has share-level security.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Defining access permissions       NetAccessAdd

 Enum functions                    Chapter 1, "Overview of the LAN Manager
                                   API"

 Retrieving the access             NetAccessGetInfo
 permissions for a specific
 resource

 Verifying the access permissions  NetAccessCheck
 for a resource


 NetAccessGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessGetInfo retrieves the access control list (ACL) for a specific
 resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or P permission for the resource is required to successfully
 execute NetAccessGetInfo on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETACCESS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAccessGetInfo (const char far *      pszServer,
                     char far *            pszResource,
                     short                 sLevel,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcbTotalAvail
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAccessGetInfo. A null pointer or null string specifies the
   local computer.

 pszResource
   Points to an ASCIIZ string that contains the name of the resource.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains an access_info_X data structure, where X is 0
   or 1, depending on the level of detail requested. If called at level 1,
   the access_info_1 data structure is followed by as many access_list data
   structures as specified in the acc1_count element of that access_info_1
   data structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer that specifies how many bytes of
   information are available to be returned in the buffer. This count is
   valid only if NetAccessGetInfo returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_ResourceNotFound             2222    The resource name was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_InvalidDatabase              2247    The user accounts database file,
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 One way to determine the size of the data buffer required is to first call
 NetAccessGetInfo with cbBuffer set to 0. NetAccessGetInfo then returns in
 pcbTotalAvail the buffer size required (in bytes).

 NetAccessGetInfo returns ERROR_NOT_SUPPORTED when executed remotely on a
 server that has share-level security.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 GetInfo functions                 Chapter 1, "Overview of the LAN Manager
                                   API"

 Listing all resources and         NetAccessEnum
 permissions on a server

 Modifying the current             NetAccessSetInfo
 permissions for a resource


 NetAccessGetUserPerms
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessGetUserPerms returns a specified user's or group's access
 permissions for a particular resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or P permission for the resource is required to successfully
 execute NetAccessGetUserPerms on a remote server or on a computer that has
 local security enabled, except when users request their own access
 permissions. In this case, no special privilege is required.


 Syntax

   #define INCL_NETACCESS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAccessGetUserPerms (char far  *           pszServer,
                          char far  *           pszUgName,
                          char far  *           pszResource,
                          unsigned short far *  pusPerms
                         );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAccessGetUserPerms. A null pointer or null string specifies
   the local computer.

 pszUgName
   Points to an ASCIIZ string that contains the name of the user or group to
   query.

 pszResource
   Points to an ASCIIZ string that contains the name of the resource.

 pusPerms
   Points to a field in which the permission bit field is returned.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_ResourceNotFound             2222    The resource name was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 The permissions returned are based on the user's entry in the access control
 list. If the user does not have an entry, the permissions for any groups to
 which the user belongs are returned.

 NetAccessGetUserPerms returns ERROR_NOT_SUPPORTED when executed remotely on
 a server that has share-level security.


 NetAccessSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessSetInfo changes the access control list (ACL) for a resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or P permission for the resource is required to successfully
 execute NetAccessSetInfo on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETACCESS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAccessSetInfo (const char far *  pszServer,
                     char far *        pszResource,
                     short             sLevel,
                     char far *        pbBuffer,
                     unsigned short    cbBuffer,
                     short             sParmNum
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAccessSetInfo. A null pointer or null string specifies the
   local computer.

 pszResource
   Points to an ASCIIZ string that contains the name of the resource.

 sLevel
   Specifies the level of detail provided; must be 1.

 pbBuffer
   Points to the data to be set.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to reset the entire ACL or to change only the attribute
   element. If sParmNum is PARMNUM_ALL, pbBuffer must point to an
   access_info_1 data structure that can be followed by access_list data
   structures. The entire set of access control entries (ACEs) in the ACL is
   then replaced by this new data. The only other valid value for sParmNum is
   ACCESS_ATTR_PARMNUM, which indicates that the acc1_attr element of the
   access_info_1 data structure is to be set (acc1_attr is the only element
   of the structure that can be set individually). When sParmNum is
   ACCESS_ATTR_PARMNUM, pbBuffer must point to a valid value for acc1_attr,
   and the ACL remains unaltered.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_ResourceNotFound             2222    The resource name was not found.


 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFNoRoom                    2228    The user accounts database is
                                           full.

 NERR_ACFTooManyLists              2230    Each resource can have no more
                                           than 64 access records defined.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetAccessSetInfo returns ERROR_NOT_SUPPORTED when executed remotely on a
 server that has share-level security.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing permissions and           NetAccessEnum
 resources

 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"

 Retrieving the access             NetAccessGetInfo
 permissions for a specific
 resource

 SetInfo functions                 Chapter 1, "Overview of the LAN Manager
                                   API"





 Access Permissions Category Example

   /*
      NETACC.C -- a sample program demonstrating NetAccess API functions.

      This program requires that you have admin privilege if a servername
      parameter is supplied.

         usage:  netacc [-s \\server] [-u username] [-r resource] [-b
   basepath]

         where  \\server = Name of the server. A servername must be
                           preceded by two backslashes (\\).
                username = Name of the user.
                resource = Name of the resource.
                basepath = Enumerate resources with this base path.

      API                  Used to...
      ================     ================================================
      NetAccessEnum        Display a list of access permissions
      NetAccessCheck       Check a user's write access to the resource
      NetAccessGetInfo     Check that an ACL exists for the resource
      NetAccessAdd         Add an ACL for the resource if one does not
   exist
      NetAccessSetInfo     Give all users read/write access to the resource
      NetAccessDel         Delete the ACL for the resource

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_BASE
   #include    <os2.h>        // MS OS/2 base header files

   #define     INCL_NETACCESS
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   #define DEFAULT_USER       "ADMIN"
   #define DEFAULT_RESOURCE   "\\pipe\\restrict"
   #define BIG_BUFFER         32768

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      API_RET_TYPE uReturnCode;              // API return code
      char * pszServer = NULL;               // Servername
      char * pszUserName = DEFAULT_USER;     // Username
      char * pszResource = DEFAULT_RESOURCE; // Resource to check
      char * pszBasePath = NULL;             // No default base path
      char * pbBuffer;                       // Pointer to data buffer
      struct access_info_1 *pAclBuf;         // Pointer to ACL info
      struct access_list   *pAceInfo;        // Pointer to ACE info
      int            iArgv;                  // Index for arguments
      short          iACE;                   // Index for ACEs
      unsigned short iACL;                   // Index for ACLs
      unsigned short cAclRead;               // Count of ACLs read
      unsigned short cAclTotal;              // Count of ACLs available
      unsigned short cbAvail;                // Count of bytes available
      unsigned short cbBuffer;               // Size of buffer, in bytes
      unsigned short usResult;               // Result of access check
      unsigned short fAttrib;                // Auditing attribute flag
      char cGroup;
      BOOL fResourceFound = FALSE;

      for (iArgv = 1; iArgv < argc; iArgv++)
      {
         if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/'))
         {
            switch (tolower(*(argv[iArgv]+1)))    // Process switches
            {
               case 's':                          // -s servername
                  pszServer = argv[++iArgv];
                  break;
               case 'u':                          // -u username
                  pszUserName = argv[++iArgv];
                  break;
               case 'r':                          // -r resource
                  pszResource = argv[++iArgv];
                  break;
               case 'b':                          // -b base path
                  pszBasePath = argv[++iArgv];
                  break;

   case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   // NetAccessEnum
   //
   // This API displays the list of resource access permissions.
   // Note: Details other than resource name are available only at info
   // level 1. If all resources are wanted, then no base pathname should
   // be supplied. Recursive searching is enabled.
   //========================================================================

      cbBuffer = BIG_BUFFER;                 // Can be up to 64K

      /*
       * You can determine the number of entries by calling NetAccessEnum
       * with pbBuffer=NULL and cbBuffer=0. The size of the buffer needed
       * to enumerate the users is, however, larger than
       * cAclTotal * sizeof(struct access_info_1) because of the
       * variable-length data (referenced by pointers in the structure).
       * It is easiest to use a big buffer.
       */

      pbBuffer = SafeMalloc(cbBuffer);       // Start of memory block

      uReturnCode = NetAccessEnum(
                        pszServer,           // Servername
                        pszBasePath,         // Base path to search from
                        1,                   // Nonzero, recursive search
                        1,                   // Information level
                        pbBuffer,            // Data returned here
                        cbBuffer,            // Size of buffer, in bytes
                        &cAclRead,           // Count of ACLs read
                        &cAclTotal);         // Count of ACLs available


      printf("NetAccessEnum returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         pAclBuf = (struct access_info_1 *) pbBuffer;
         for (iACL = 0; iACL < cAclRead; iACL++)
         {
            printf("   resource = %Fs\n", pAclBuf->acc1_resource_name);
            pAceInfo = (struct access_list *)(pAclBuf + 1);
            for (iACE = 0; iACE < pAclBuf->acc1_count; iACE++)
            {
                                             // Print a * before groupnames
               cGroup = ' ';
               if (pAceInfo->acl_access & ACCESS_GROUP)
               {                             // Strip group access bit
                  pAceInfo->acl_access &= ACCESS_ALL;
                  cGroup = '*';
               }
               printf("\t%c%s:%x \n", cGroup, pAceInfo->acl_ugname,
                           pAceInfo->acl_access);
               pAceInfo++;
            }
            pAclBuf = (struct access_info_1 *)pAceInfo;
         }
         printf("%hu out of %hu entries returned\n", cAclRead, cAclTotal);
      }

   //========================================================================
   // NetAccessCheck
   //
   // This API checks that a user has permission to write to a resource.
   // Unlike other Access Category API functions, NetAccessCheck input
   can
   // specify only a username; it cannot specify a groupname.
   // Note: NetAccessCheck cannot be executed remotely.
   //========================================================================


      uReturnCode = NetAccessCheck(
                        NULL,                // Reserved field
                        pszUserName,         // Check for user
                        pszResource,         // Resource to check
                        ACCESS_WRITE,        // Check for write permission
                        &usResult);

      /*
       * The result field is valid only if the API returns NERR_Success.
       * If there is no ACL for the resource, its parent directory, or
       * the drive label, the API sets the result field to NERR_Success
       * for an admin-class user and ERROR_ACCESS_DENIED for any other
       * type of user.
       */


      printf("\nNetAccessCheck for write permission returned %u\n",
                    uReturnCode);
      printf("   User name = %s,  Resource = %s\n",
                    pszUserName, pszResource);

      if (uReturnCode == NERR_Success)
      {
         printf("   Result field returned = %hu\n", usResult);
      }

   //========================================================================
   // NetAccessGetInfo
   //
   // Call NetAccessGetInfo at level 0 to see if the resource exists.
   //========================================================================

      uReturnCode = NetAccessGetInfo(
                        pszServer,           // Servername
                        pszResource,         // Pointer to resource name
                        0,                   // Only want to know if
   it exists
                        pbBuffer,            // Data returned here
                        cbBuffer,            // Size of buffer, in bytes
                        &cbAvail);           // Count of bytes available

      printf("\nNetAccessGetInfo of %s returned %u\n",
                     pszResource, uReturnCode);

      switch (uReturnCode)
      {
         case NERR_Success:
            printf("    Resource %s exists\n\n", pszResource);
            fResourceFound = TRUE;
            break;
         case NERR_ResourceNotFound:
            printf("    Resource %s does not exist\n\n", pszResource);
            break;
      }

   //========================================================================
   // NetAccessAdd
   //
   // This API adds an ACL for the resource (if one does not exist)
   // and sets the attribute flag so all access attempts are audited.
   //========================================================================

      if (!fResourceFound)
      {                                      // Set up access permission
   info
         pAclBuf = (struct access_info_1 *) pbBuffer;

         pAclBuf->acc1_resource_name = (char far *) pszResource;
         pAclBuf->acc1_attr = 1;             // Audit all access attempts
         pAclBuf->acc1_count = 0;            // Set no user/group info

         uReturnCode = NetAccessAdd(
                           pszServer,            // Servername
                           1,                    // Info level; must
   be 1
                           (char far *)pAclBuf,  // Data to be set
                           cbBuffer);            // Size of buffer, in
   bytes

         printf("NetAccessAdd of %s returned %u\n\n",
                        pszResource, uReturnCode);
      }

   //========================================================================
   // NetAccessSetInfo
   //
   // This API changes the access record for the resource so that
   // any user who has user permission has read permission only. This

   // can be overwritten by setting special access permissions for
   // individual usernames.
   //========================================================================

      /*
       * There are two ways to call NetAccessSetInfo.
       * If sParmNum == PARMNUM_ALL, you must pass it a whole structure.
       * Otherwise, you can set sParmNum to the element of the structure

       * you want to change. Both ways are shown here.
       */







                                             // Set up access permission
   info
      pAclBuf = (struct access_info_1 *) pbBuffer;
      pAclBuf->acc1_resource_name = (char far *) pszResource;
      pAclBuf->acc1_attr = 1;                // Audit all access attempts
      pAclBuf->acc1_count = 1;
                                             // Set up access_list structure
      pAceInfo = (struct access_list *)(pAclBuf+1),
      strcpy(pAceInfo->acl_ugname, "USERS");
      pAceInfo->acl_access = ACCESS_READ;

      uReturnCode = NetAccessSetInfo(
                        pszServer,           // Servername
                        pszResource,         // Pointer to resource name
                        1,                   // Info level; must be 1
                        (char far *)pAclBuf, // Data to be set
                        cbBuffer,            // Size of buffer, in bytes
                        PARMNUM_ALL);        // Supply full set of info

      printf("NetAccessSetInfo with full buffer returned %u\n", uReturnCode);

      /*
       * Sets sParmNum to ACCESS_ATTR_PARMNUM to change the acc1_attr
   element
       * of the access_info_1 structure. To specify no audit logging,
   set
       * acc1_attr to 0.
       */

      fAttrib = 0;

      uReturnCode = NetAccessSetInfo(
                        pszServer,             // Servername
                        pszResource,           // Pointer to resource
   name
                        1,                     // Info level
                        (char far *)&fAttrib,  // Turn off all auditing
                        sizeof(short),         // Size of buffer, in
   bytes
                        ACCESS_ATTR_PARMNUM);  // Give audit attribute
   only

      printf("NetAccessSetInfo with audit bit only returned %u\n\n",
                       uReturnCode);

   //========================================================================
   // NetAccessDel
   //
   // This API deletes the access record for the resource.
   //========================================================================

      uReturnCode = NetAccessDel(
                        pszServer,           // Servername
                        pszResource);        // Pointer to resource name

      printf("NetAccessDel of %s returned %u\n", pszResource, uReturnCode);

      free(pbBuffer);
      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-u username]"\
                      " [-r resource] [-b basepath]\n", pszProgram);
      exit(1);
   }







 Alert Category

 Alert API functions notify network service programs and applications of
 network events. They require that the Workstation service be started.

 The Alert category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and ALERT.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETALERT, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Alert API functions:


   þ   NetAlertRaise

   þ   NetAlertStart

   þ   NetAlertStop



 Description

 An event is a particular instance of a process or state of hardware as
 defined by an application. The Alert API functions allow applications to
 indicate when predefined events occur.

 The ALERT.H header file defines the following types of events for alerts
 sent by the LAN Manager services:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                  ASCIIZ String  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ALERT_ADMIN_EVENT     ADMIN          Notify an administrator.

 ALERT_ERRORLOG_EVENT  ERRORLOG       An entry is added to the error log.

 ALERT_MESSAGE_EVENT   MESSAGE        A user or application received a
                                      message.

 ALERT_PRINT_EVENT     PRINTING       A print job completed or a print
                                      error occurred.
 Code                  ASCIIZ String  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                     error occurred.

 ALERT_USER_EVENT      USER           An application or resource was used.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Other types of alerts can be defined as needed by applications. For example,
 you could define the new alert type ALERT_CHANGE_EVENT as the ASCIIZ string
 CHANGE. A monitor program could check for ALERT_CHANGE_EVENT alerts by
 calling NetAlertStart with the new alert. If an application that modified a
 resource then called NetAlertRaise with the ALERT_CHANGE_EVENT alert, the
 monitor program would be notified.

 An application can receive alert messages through one of two delivery
 mechanisms: a mailslot (registered as \mailslot\mailslotname) or a system
 semaphore (registered as \sem\semaphorename).

 If an application requires detailed information about an event, it should
 use a mailslot. The mailslot can receive data; the semaphore can only
 indicate the occurrence of an event.

 The number of alerts a system can handle is determined by the numalerts
 entry in the [workstation] section of the LANMAN.INI file. To change this
 number, alter the numalerts entry and stop and restart the workstation.

 NetAlertStart indicates that an application is checking for events of a
 particular type to occur, and indicates whether the application is
 monitoring a mailslot or waiting for a semaphore to be cleared. An
 application can register to monitor several alert types by calling
 NetAlertStart multiple times.

 NetAlertRaise is used to indicate that an event has occurred. Any
 applications checking for the event then receive the data sent by the alert
 being raised, or they have their semaphore cleared. The LAN Manager Alerter
 service is an example of an application that has registered to receive LAN
 Manager alerts.

 To discontinue checking for alerts of a particular type, call NetAlertStop
 with the appropriate alert type specified.

 If an application calls NetAlertStart to start checking for an alert, and
 then exits without ever calling NetAlertStop, the entry remains in the table
 of alerts until the Workstation service stops; the alert table may fill up.
 To avoid this, applications should always call NetAlertStop when they are
 done checking for the alert.


 Data Structures

 An application registered as a mailslot client receives information about
 each type of alert for which it is registered. This information consists of
 a fixed-length header followed by variable-length information specific to
 the type of alert. The LAN Manager alert data structures are defined in the
 ALERT.H header file.


 Header Structure

 The fixed-length header contains the standard alert data structure. The
 std_alert data structure has the following format:

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

 where

 alrt_timestamp
   Specifies the time and date when the alert event was raised. This value is
   stored as the number of seconds elapsed since 00:00:00, January 1, 1970.

 alrt_eventname
   Contains an ASCIIZ string that specifies the type of alert. The constant
   EVLEN is defined in the NETCONS.H header file.

 alrt_pad1
   Aligns the next data structure element on a word boundary.

 alrt_servicename
   Contains an ASCIIZ string that specifies which application raised the
   alert. The constant SNLEN is defined in the NETCONS.H header file.


 Alert Structures

 The ALERT.H header file contains data structures for predefined alert
 classes. These structures define only the fixed-length part of the
 information, not the ASCIIZ strings that follow some of the structures.
 These alert data structures are described in the following sections.

 ALERT_ADMIN_EVENT Alert - The admin_other_info data structure has this
 format:

   struct admin_other_info {
       short  alrtad_errcode;
       short  alrtad_numstrings;
   };

   /* Followed by consecutive ASCIIZ strings; the count
       is in the alrtad_numstrings element. */

   char  mergestrings[];

 where

 alrtad_errcode
   Specifies the error code for the new message in the message log.

 alrtad_numstrings
   Specifies the number (0-9) of consecutive ASCIIZ strings contained in
   mergestrings.

 mergestrings
   Contains a series of consecutive ASCIIZ strings that make up the error
   message indicated by alrtad_errcode.

 ALERT_ERRORLOG_EVENT Alert - The errlog_other_info data structure has this
 format:

   struct errlog_other_info {
       short  alrter_errcode;
       long   alrter_offset;
   };

 where

 alrter_errcode
   Specifies the error code that was written to the error log.

 alrter_offset
   Specifies the offset for the new entry in the error log.

 ALERT_MESSAGE_EVENT Alert - This alert does not define a data structure; the
 text from the received message is in this format:

   char msg_text[];

 where

 msg_text
   Specifies an ASCIIZ string that contains message text.

 ALERT_PRINT_EVENT Alert - The print_other_info data structure has this
 format:

   struct print_other_info {
       short  alrtpr_jobid;
       short  alrtpr_status;
       long   alrtpr_submitted;
       long   alrtpr_size;
   };
   /* Followed by consecutive ASCIIZ strings. */

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

 where

 alrtpr_jobid
   Specifies the print job's identification number.

 alrtpr_status
   Specifies the status of the print job.

 alrtpr_submitted
   Specifies the time when the print job was submitted. This value is stored
   as the number of seconds elapsed since 00:00:00, January 1, 1970.

 alrtpr_size
   Specifies the size (in bytes) of the print job.

 computername
   Contains an ASCIIZ string that specifies which workstation or server
   submitted the print job.

 username
   Contains an ASCIIZ string that specifies which user requested the
   printing.

 queuename
   Contains an ASCIIZ string that specifies which queue handled the print
   job.

 destname
   Contains an ASCIIZ string that specifies which printer handled the job.

 status_string
   Specifies information the print processor returns. This string corresponds
   to the pszStatus component of the PRJINFO data structure for the print
   job. For more information, see the Print Job category API functions.

 ALERT_USER_EVENT Alert - The user_other_info data structure has this format:


   struct user_other_info {
       short  alrtus_errcode;
       short  alrtus_numstrings;
   };
   /*
    * Followed by a number of consecutive ASCIIZ strings;
    * the count is in the alrtus_numstrings element. */
    */
   char  mergestrings[];

   /* Further followed by two more consecutive ASCIIZ strings. */
   char  username[];
   char  computername[];

 where

 alrtus_errcode
   Specifies the error code for the new message in the message log.

 alrtus_numstrings
   Specifies the number (0-9) of consecutive ASCIIZ strings contained in
   mergestrings.

 mergestrings
   Specifies a series of consecutive ASCIIZ strings that make up the error
   message specified by alrtus_errcode.

 username
   Specifies the name of the user or application affected by the alert.

 computername
   Specifies the name of the computer that the user or application is
   accessing.


 ALERT.H Header File Macros

 The ALERT.H header file contains the following macros that simplify access
 to the variable-length elements in the alert data structure:

 Macro                            Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ALERT_OTHER_INFO(ptr)            Given a pointer to the start of the
 ALERT_OTHER_INFO_F(ptr)          std_alert
                                  data structure (designated by ptr), the
                                  ALERT_OTHER_INFO macro returns a pointer
                                  to the variable-length part of the alert
                                  message
                                  (the information specific to the alert
                                  class).
                                  Use ALERT_OTHER_INFO_F when a far pointer

                                  is required.

 ALERT_VAR_DATA(ptr)              Given a pointer to the address of the
 ALERT_VAR_DATA_F(ptr)            alert
                                  data structure (for example, a pointer to
                                  an admin_other_info data structure,
                                  designated
                                  by ptr), ALERT_VAR_DATA returns a pointer

                                  to the first variable-length ASCIIZ
                                  string.
                                  Use ALERT_VAR_DATA_F when a far pointer
                                  is required.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Creating mailslots                Mailslot Category

 Error log                         Error Logging Category

 Message API functions             Message Category

 Printer API functions             Print Destination Category, Print Job
                                   Category, and Printer Queue Category


 NetAlertRaise
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAlertRaise notifies all registered clients that a particular event
 occurred.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to successfully execute
 NetAlertRaise.


 Syntax

   #define INCL_NETALERT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAlertRaise (const char far *  pszEvent,
                  const char far *  pbBuffer,
                  unsigned short    cbBuffer,
                  unsigned long     ulTimeout
                 );

 where

 pszEvent
   Points to an ASCIIZ string that specifies which type of alert to raise.

 pbBuffer
   Points to the data to be sent to the clients listening for this alert. The
   data should consist of the std_alert data structure followed by any
   additional alert data.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 ulTimeout
   Specifies how many milliseconds to wait for alert information to be
   written to the mailslot. The ALERT.H header file defines these three time
   intervals:

 Code              Value   Time Interval
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ALERT_SHORT_WAIT  100L    0.1 second
 ALERT_MED_WAIT    1000L   1 second
 ALERT_LONG_WAIT   10000L  10 seconds
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_NoSuchAlert                  2432    An invalid or nonexistent
                                           alertname was raised.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetAlertRaise clears the client's semaphore or sends messages to mailslots.


 For mailslot clients, NetAlertRaise writes information from pbBuffer to the
 client's mailslot. For semaphore clients, NetAlertRaise clears and
 automatically resets the semaphore.

 The alert types defined in ALERT.H are raised by LAN Manager services.
 Applications using the Alert category functions should define their own
 alert types and associated data structures. One exception is the use of the
 ALERT_ADMIN_EVENT code to generate messages.

 An application can use the ALERT_ADMIN_EVENT alert type together with the
 Alerter service to generate messages. If the alert is raised with the
 alrtad_errcode element of the admin_other_info data structure set to -1, the
 alert is received by the Alerter service. The message text in mergestrings
 is then sent as a message to all names listed in the alertnames entry of the
 local LANMAN.INI file. For a demonstration of this, see the "Example"
 section at the end of this category.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Mailslots                         DosMakeMailslot and DosReadMailslot in
                                   MSOS/2 programming manual(s)

 Registering a client for an       NetAlertStart
 alert

 Semaphores                        DosCreateSem, DosMuxSemWait, and
                                   DosSemSet in MSOS/2 programming manual(s)

 Terminating alert monitoring      NetAlertStop


 NetAlertStart
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAlertStart registers a client so that it will be notified of a particular
 type of alert.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to successfully execute
 NetAlertStart.


 Syntax

   #define INCL_NETALERT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAlertStart (const char far *  pszEvent,
                  const char far *  pszRecipient,
                  unsigned short    cbMaxData
                 );

 where

 pszEvent
   Points to an ASCIIZ string that specifies the alert type for which the
   client will be notified.

 pszRecipient
   Points to an ASCIIZ string that specifies the mailslot or semaphore client
   to receive the alerts. This must be a local mailslot or system semaphore.

 cbMaxData
   Specifies the maximum number of bytes of information the mailslot client
   can receive for alerts of this type.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.

 NERR_NetNotStarted    2102    The LAN Manager NETWKSTA driver is not
                               installed.

 NERR_WkstaNotStarted  2138    The Workstation service is not started.

 NERR_BadEventName     2143    The event name is invalid.

 NERR_AlertExists      2430    A program requested to be notified by the
                               alerter of an event for which it is already
                               receiving notifications.

 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_TooManyAlerts    2431    The number of alert notifications requested
                               exceeded the number specified by the
                               numalerts entry in the LANMAN.INI file.

 NERR_BadRecipient     2433    The alert recipient is invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Applications can define their own alerts, specifying the alert name when
 they call NetAlertStart and NetAlertRaise. Be sure to choose a name that
 does not duplicate an alert name already used by another application.

 If pszRecipient is a mailslot, a NetAlertRaise call for the specified alert
 sends data to the mailslot. The process monitoring the alert must call the
 DosMakeMailslot function to create the mailslot, then call NetAlertStart to
 register to receive the alert, and then call DosReadMailslot to read the
 data raised by the alert.

 If pszRecipient is a semaphore, a NetAlertRaise call for the specified alert
 clears the system semaphore. The process monitoring the alert must first
 create the semaphore by calling DosCreateSem with the fNoExclusive flag set
 to CSEM_PUBLIC, then call DosSemSet to set the semaphore, then call
 NetAlertStart to register to receive the alert, and then call DosMuxSemWait
 to wait for the semaphore to be cleared. NetAlertRaise clears and
 automatically resets the semaphore.

 The pszRecipient parameter must be a local mailslot or system semaphore. Any
 other name results in NERR_BadRecipient.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Discontinuing receiving alerts    NetAlertStop
 of a particular type

 Mailslots                         DosMakeMailslot and DosReadMailslot in
                                   MSOS/2 programming manual(s)

 Raising an alert                  NetAlertRaise

 Semaphores                        DosCreateSem, DosMuxSemWait, and
                                   DosSemSet in MSOS/2 programming manual(s)


 NetAlertStop
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAlertStop stops a client from receiving the specified type of alert.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to successfully execute NetAlertStop.



 Syntax

   #define INCL_NETALERT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAlertStop (const char far *  pszEvent,
                 const char far *  pszRecipient
                );

 where

 pszEvent
   Points to an ASCIIZ string that specifies the type of alert from which to
   exclude the registered client.

 pszRecipient
   Points to an ASCIIZ string that specifies the mailslot or semaphore where
   the alert was received.

 Return Codes

 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.

 NERR_NetNotStarted    2102    The LAN Manager NETWKSTA driver is not
                               installed.

 NERR_WkstaNotStarted  2138    The Workstation service is not started.

 NERR_NoSuchAlert      2432    An invalid or nonexistent alertname was
                               raised.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Remarks

 If either pszEvent or pszRecipient does not exist, NetAlertStop returns
 NERR_NoSuchAlert.





 Alert Category Example

   /*
      NETALRT.C -- a sample program demonstrating the interaction between
                    the Alerter service and NetAlertRaise.

      This program requires that the Alerter service be started.
      It relies on that service to monitor the admin alert events.
      To receive the alert and display it in a popup, the Messenger
      and Netpopup services must be running and one of the current
      message alias names must be listed in the alertnames entry of
      the LANMAN.INI file on the computer that raises the alert.

         usage:  netalrt [-m message1 [message2 [message3...]]]

         where  message1 = First message to appear in the popup
                message2 = Second message to appear in the popup
                message3 = Third message to appear in the popup
                etc.

      API               Used to...
      =============     =================================================
      NetAlertRaise     Raise an admin-class alert that will appear as
   a
                        popup on machines with the Messenger and Netpopup
                        services running.

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETALERT
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>
   #include    <time.h>

   #include    "samples.h"    // Internal routine header file

   #define DEFAULT_MESSAGE    "Hi there!"
   #define ALERT_BUFFER       512
   #define PROGRAM_NAME       "NETALRT"


   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      API_RET_TYPE uReturnCode;               // API return code
      char * pbBuffer;                        // Pointer to data buffer
      char * psMergeString;                   // Pointer to alert strings
      int    iCount;                          // Index counter
      unsigned short cbBuffer = ALERT_BUFFER; // Buffer size
                                              // Alert data header info
      struct std_alert *pAlertInfo = (struct std_alert *) pbBuffer;
      struct admin_other_info * pAdminInfo;   // Admin alert data

      // Allocate a data buffer large enough to store the messages.
      pbBuffer = SafeMalloc(cbBuffer);

      // Set up the alert data structure.
      pAlertInfo = (struct std_alert *) pbBuffer;
      strcpy(pAlertInfo->alrt_eventname, ALERT_ADMIN_EVENT);
      strcpy(pAlertInfo->alrt_servicename, PROGRAM_NAME);

      pAdminInfo = (struct admin_other_info *)ALERT_OTHER_INFO(pAlertInfo);
      pAdminInfo->alrtad_errcode = -1;
      pAdminInfo->alrtad_numstrings = 0;
      psMergeString = ALERT_VAR_DATA(pAdminInfo);

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 'm':                        // -m Message
                  for ( ; iCount < argc-1; )    // Merge all message
   strings
                  {
                     iCount++;
                     strcpy(psMergeString, argv[iCount]);
                     psMergeString = psMergeString+1+strlen(argv[iCount]);
                     pAdminInfo->alrtad_numstrings++;
                  }
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }


         else
            Usage(argv[0]);
      }
      // Display at least one string.
      if (pAdminInfo->alrtad_numstrings == 0)
      {
         strcpy(psMergeString, DEFAULT_MESSAGE);
         (pAdminInfo->alrtad_numstrings)++;
      }

   //========================================================================
   //  NetAlertRaise
   //
   //  This API sends an admin alert. If alrtad_errcode is -1, the Alerter
   //  service receives the alert and sends the alert message to all
   //  message aliases listed in the alertnames entry of the LANMAN.INI
   //  file. These messages are then displayed in a popup if the receiving

   //  computer is running the Messenger and Netpopup services.
   //========================================================================

      time(&(pAlertInfo->alrt_timestamp));

      uReturnCode = NetAlertRaise(ALERT_ADMIN_EVENT,  // Admin alert
                          (char far *)pbBuffer,       // Alert information
                          cbBuffer,                   // Buffer size
                          ALERT_MED_WAIT);            // Time-out value

      printf("NetAlertRaise returned %u\n", uReturnCode);
      free (pbBuffer);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-m message1 [message2 [message3...]]]\n",
                 pszProgram);
      exit(1);
   }





 Auditing Category

 Auditing API functions control the audit log. All Audit API functions
 require that the NETWKSTA device driver be installed. NetAuditRead requires
 that the Workstation service be started. NetAuditWrite requires that the
 Server service be started.

 The Audit category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, ACCESS.H, and AUDIT.H header files. A
 source  program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETAUDIT, and including the master header file,
 LAN.H. For more information about these definitions, see the "Example"
 section, later in this category.

 These are the Auditing API functions:


   þ   NetAuditClear

   þ   NetAuditRead

   þ   NetAuditWrite



 Description

 Auditing API functions monitor operations on the specified server. If
 auditing is enabled, each monitored operation generates an audit entry. For
 example, when a user establishes a connection to the server, a single audit
 entry is generated.

 Audit entries are stored in a binary file called an audit trail or audit
 log. The default audit trail file is NET.AUD in the LAN Manager LOGS
 directory. All Auditing API functions perform their operations on this file.


 LAN Manager defines many types of audit entries. You can find these audit
 entries listed in the table in the "Fixed-Length Header" section, later in
 this category.

 NetAuditRead reads the audit log. NetAuditClear clears the audit log.
 NetAuditWrite creates additional audit entries and writes them to the audit
 log.

 To set a maximum size for the audit log, you can use one of these methods:


   þ   Use the net config command with the /maxauditlog option. For more
       information, see  your LAN Manager administrator's manual(s).

   þ   Set the maxauditlog entry in the [server] section of the LANMAN.INI
       file. For more information, see your LAN Manager administrator's
       manual(s).

   þ   Call NetServerSetInfo with sParmNum set to SV_MAXAUDITSZ_PARMNUM.



 Data Structures

 All audit entries include a fixed-length header used in conjunction with
 variable-length data specific to the entry type. Because of the variable
 lengths and structures of the ae_data element of the audit entry (it is
 possible for ae_data to be zero bytes), only the fixed header is defined in
 the audit_entry data structure.

 The variable-length portion of the audit entry can contain an offset to a
 variable-length ASCIIZ string. The offset values are unsigned short
 integers. To determine the value of the pointer to this string, add the
 offset value to the address of the ae_data data structure.

 The following example illustrates this procedure. Assume that pAE points to
 a buffer that contains a complete audit entry and that the ae_type element
 of the audit_entry data structure contains the value AE_CONNSTOP, which
 specifies the predefined ae_connstop data structure. To point the variable
 pszComputerName to the ASCIIZ string that contains the name of the client
 whose connection was stopped, an application would perform the following
 algorithm:

   struct audit_entry * pAE;      /* Fixed part of audit entry
   */
   struct ae_connstop * pAEvar;   /* Variable-length structure */
   char * pszComputerName;        /* Pointer to variable-length string
   */

   /* Calculate the offset to the variable-length structure. */
   pAEvar = (struct ae_connstop *) ((char *) pAE + pAE->ae_data_offset);

   /* Calculate the offset to the computername. */
   pszComputerName = (char *) pAEvar + pAEvar->ae_cp_compname;


 Fixed-Length Header

 The audit_entry data structure has this format:

   struct  audit_entry {
       unsigned short  ae_len;
       unsigned short  ae_reserved;
       unsigned long   ae_time;
       unsigned short  ae_type;
       unsigned short  ae_data_offset;  /* Offset from beginning
                                           address of audit_entry */
   };







   /* Variable-length data specific to type of audit entry */

   char            ae_data[];

   /* Terminating length indicator */

   unsigned short  ae_len2;

 where

 ae_len and ae_len2
   Specify the length of the audit entry. Both have the same value. The
   ae_len element is included at the beginning and at the end of the audit
   entry to enable both backward and forward scanning of the log. To
   calculate the entry size, add the size of the audit_entry data structure
   to the size of the variable-length data, ae_data, and the size of an
   unsigned short integer, as follows:

   totalsize = sizeof (struct audit_entry) +     sizeof (ae_data) + sizeof
   (unsigned short);

 ae_reserved
   Reserved; must be 0.

 ae_time
   Specifies when the audit entry was generated. The value is stored as the
   number of seconds elapsed since 00:00:00, January 1, 1970.

 ae_type
   Specifies the type of audit entry. Type values from 0x0000 through 0x07FF
   are reserved. OEMs and other applications programmers can reserve values
   from 0x0800 through 0xFFFF. The AUDIT.H header file defines the following
   types of audit entries:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_SRVSTATUS     0      Status of server changed.

 AE_SESSLOGON     1      Session was logged on.

 AE_SESSLOGOFF    2      Session was logged off.

 AE_SESSPWERR     3      Password error occurred.
 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
AE_SESSPWERR     3      Password error occurred.

 AE_CONNSTART     4      Connection was started.

 AE_CONNSTOP      5      Connection was stopped.

 AE_CONNREJ       6      Connection was rejected.

 AE_RESACCESS     7      Access was granted.

 AE_RESACCESSREJ  8      Access was rejected.

 AE_CLOSEFILE     9      File, device, or pipe was closed.

 Ä                10     Undefined.

 AE_SERVICESTAT   11     Service status code or text changed.

 AE_ACLMOD        12     Access control list (ACL) was modified.
 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
AE_ACLMOD        12     Access control list (ACL) was modified.

 AE_UASMOD        13     User accounts subsystem (UAS) database was
                         modified.

 AE_NETLOGON      14     User logged on to network.

 AE_NETLOGOFF     15     User logged off from network.

 AE_NETLOGDENIED  16     Not supported in LAN Manager 2.0.

 AE_ACCLIMITEXCD  17     Account limit was exceeded.

 AE_RESACCESS2    18     Access was granted.

 AE_ACLMODFAIL    19     ACL modification failed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 ae_data_offset
   Specifies the byte offset from the beginning of the audit entry to the
   beginning of the variable-length portion (ae_data) of the audit entry. To
   calculate the beginning of ae_data, add the value of ae_data_offset to the
   starting address of the fixed-length portion of the entry.

 ae_data
   Specifies the variable-length portion of the audit entry; it differs
   depending on the type of entry specified by ae_type. The information
   begins at ae_data_offset bytes from the top of the audit entry. For
   information about the structure of each entry type defined by LAN Manager,
   see the following section.


 Variable-Length Data

 The following data structures, specific to the audit entry type, are defined
 in the AUDIT.H header file. The structures follow the audit_entry header,
 but they are not necessarily contiguous.

 Server Status Changed  - The ae_srvstatus data structure is associated with
 an audit entry of type AE_SRVSTATUS. The ae_srvstatus data structure has
 this format:

   struct ae_srvstatus {
       unsigned short  ae_ss_status;
   };

 where

 ae_ss_status
   Specifies a server's status. The AUDIT.H header file defines these
   possible values:

 Code          Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_SRVSTART   0      Server software started.
 AE_SRVPAUSED  1      Server software paused.
 AE_SRVCONT    2      Server software restarted.
 AE_SRVSTOP    3      Server software stopped.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Session Begun - The ae_sesslogon data structure is associated with an audit
 entry of type AE_SESSLOGON. The ae_sesslogon data structure has this format:


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

 where

 ae_so_compname
   Specifies the offset (from the beginning of the ae_sesslogon data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_so_username
   Specifies the offset (from the beginning of the ae_sesslogon data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_so_username is 0, the username and
   workstation name are assumed to be the same.

 ae_so_privilege
   Specifies the privilege level assigned to ae_so_username. The AUDIT.H
   header file defines these possible values:

 Code      Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_GUEST  0      Guest privilege.
 AE_USER   1      User privilege.
 AE_ADMIN  2      Admin privilege.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Session Ended - The ae_sesslogoff data structure is associated with an audit
 entry of type AE_SESSLOGOFF. The ae_sesslogoff data structure has this
 format:

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

 where

 ae_sf_compname
   Specifies the offset (from the beginning of the ae_sesslogoff data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_sf_username
   Specifies the offset (from the beginning of the ae_sesslogoff data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_sf_username is 0, the username and
   workstation name are assumed to be the same.

 ae_sf_reason
   Specifies the reason the session was disconnected. The AUDIT.H header file
   defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code            Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_NORMAL       0      Normal disconnection or username limit.

 AE_ERROR        1      Error, session disconnect, or bad password.

 AE_AUTODIS      2      Autodisconnect (time-out), sharename removed, or
                        administrative permissions required.

 AE_ADMINDIS     3      Administrative disconnection (forced).

 AE_ACCRESTRICT  4      Forced off by account system due to account
                        restriction such as logon hours.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Password Error - The ae_sesspwerr data structure is associated with an audit
 entry of type AE_SESSPWERR. The ae_sesspwerr data structure has this format:


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

 where

 ae_sp_compname
   Specifies the offset (from the beginning of the ae_sesspwerr data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_sp_username
   Specifies the offset (from the beginning of the ae_sesspwerr data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_sp_username is 0, the username and
   workstation name are assumed to be the same.

 Connection Started - The ae_connstart data structure is associated with an
 audit entry of type AE_CONNSTART. The ae_connstart data structure has this
 format:

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

 where

 ae_ct_compname
   Specifies the offset (from the beginning of the ae_connstart data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_ct_username
   Specifies the offset (from the beginning of the ae_connstart data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_ct_username is 0, the username and
   workstation name are assumed to be the same.

 ae_ct_netname
   Specifies the offset (from the beginning of the ae_connstart data
   structure) to an ASCIIZ string that specifies the sharename of the
   connected resource.

 ae_ct_connid
   Specifies the connection identification number.

 Connection Stopped - The ae_connstop data structure is associated with an
 audit entry of type AE_CONNSTOP. The ae_connstop data structure has this
 format:

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

 where

 ae_cp_compname
   Specifies the offset (from the beginning of the ae_connstop data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_cp_username
   Specifies the offset (from the beginning of the ae_connstop data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_cp_username is 0, the username and
   workstation name are assumed to be the same.

 ae_cp_netname
   Specifies the offset (from the beginning of the ae_connstop data
   structure) to an ASCIIZ string that specifies the sharename of the
   connected resource.

 ae_cp_connid
   Specifies the connection identification number.

 ae_cp_reason
   Specifies the reason the session was disconnected. The AUDIT.H header file
   defines these possible values:

 Code        Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_NORMAL   0      Normal disconnection occurred or the username limit was
                    exceeded.

 AE_SESSDIS  1      An error, session disconnection, or bad password
                    occurred.

 AE_UNSHARE  2      Autodisconnection (time-out) occurred, the sharename
                    was removed, or administrative permissions were lacking.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Connection Rejected - The ae_connrej data structure is associated with an
 audit entry of type AE_CONNREJ. The ae_connrej data structure has this
 format:

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

 where

 ae_cr_compname
   Specifies the offset (from the beginning of the ae_connrej data structure)
   to an ASCIIZ string that specifies the name of the workstation that
   established the session.

 ae_cr_username
   Specifies the offset (from the beginning of the ae_connrej data structure)
   to an ASCIIZ string that specifies the name of the user who initiated the
   session. If ae_cr_username is 0, the username and workstation name are
   assumed to be the same.

 ae_cr_netname
   Specifies the offset (from the beginning of the ae_connrej data structure)
   to an ASCIIZ string that specifies the sharename of the desired resource.

 ae_cr_reason
   Specifies the reason the session was disconnected. The AUDIT.H header file
   defines these possible values:

 Code              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_USERLIMIT      0      Normal disconnection occurred or the username
                          limit was exceeded.

 AE_BADPW          1      An error, session disconnection, or bad password
                          occurred.

 AE_ADMINPRIVREQD  2      Autodisconnection (time-out) occurred, the
                          sharename was removed, or administrative
                          permissions were lacking.

 AE_NOACCESSPERM   3      No access permissions exist for the shared
                          resource.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Access Granted (level 1) - The ae_resaccess data structure is associated
 with an audit entry of type AE_RESACCESS. The ae_resaccess data structure
 has this format:

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

 where

 ae_ra_compname
   Specifies the offset (from the beginning of the ae_resaccess data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_ra_username
   Specifies the offset (from the beginning of the ae_resaccess data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_ra_username is 0, the username and
   workstation name are assumed to be the same.

 ae_ra_resname
   Specifies the offset (from the beginning of the ae_resaccess data
   structure) to an ASCIIZ string that specifies the name of the resource
   accessed.

 ae_ra_operation
   Specifies which operation was performed. The ACCESS.H header file defines
   these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code           Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ACCESS_READ    0x01      Data was read or executed from a resource.

 ACCESS_WRITE   0x02      Data was written to a resource.

 ACCESS_CREATE  0x04      An instance of the resource (for example, a file)
                          was created; data may have been written to the
                          resource when creating it.

 ACCESS_EXEC    0x08      A resource was executed.

 ACCESS_DELETE  0x10      A resource was deleted.

 ACCESS_ATRIB   0x20      Resource attributes were modified.

 ACCESS_PERM    0x40      Resource permissions (read, write, create,
 Code           Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ACCESS_PERM    0x40      Resource permissions (read, write, create,
                          execute, and delete) for a user were modified, or
                          an application was modified.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 ae_ra_returncode
   Specifies the return code from the particular operation. If
   ae_ra_returncode is 0, the operation was successful.

 ae_ra_restype
   Specifies the server message block (SMB) request function code.

 ae_ra_fileid
   Specifies the identification number of the file.

 Access Granted (level 2) - The ae_resaccess2 data structure is associated
 with an audit entry of type AE_RESACCESS2. The ae_resaccess2 data structure
 has this format:

   struct ae_resaccess2 {
       unsigned short  ae_ra2_compname;
       unsigned short  ae_ra2_username;
       unsigned short  ae_ra2_resname;
       unsigned short  ae_ra2_operation;
       unsigned short  ae_ra2_returncode;
       unsigned short  ae_ra2_restype;
       unsigned long   ae_ra2_fileid;
   };

 where

 ae_ra2_compname through ae_ra2_restype
   Are the same as the corresponding elements of the ae_resaccess data
   structure. For more information, see the "Access Granted (level 1)"
   section.

 ae_ra2_fileid
   Specifies the identification number of the file. It is given as an
   unsigned long value, rather than as an unsigned short value as in the
   ae_resaccess structure.

 Access Denied - The ae_resaccessrej data structure is associated with an
 audit entry of type AE_RESACCESSREJ. The ae_resaccessrej data structure has
 this format:

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

 where

 ae_rr_compname
   Specifies the offset (from the beginning of the ae_resaccessrej data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_rr_username
   Specifies the offset (from the beginning of the ae_resaccessrej data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_rr_username is 0, the username and
   workstation name are assumed to be the same.

 ae_rr_resname
   Specifies the offset (from the beginning of the ae_resaccessrej data
   structure) to an ASCIIZ string that specifies the name of the resource to
   which access was denied.

 ae_rr_operation
   Specifies the operation requested. The possible values are the same as
   those for the ae_ra_operation element of the ae_resaccess data structure
   and the ae_ra2_operation element of the ae_resaccess2 data structure. For
   more information, see the previous two sections, "Access Granted (level
   1)" and "Access Granted (level 2)."

 File Closed - The ae_closefile data structure is associated with an audit
 entry of type AE_CLOSEFILE. The ae_closefile data structure has this format:


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

 where

 ae_cf_compname
   Specifies the offset (from the beginning of the ae_closefile data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_cf_username
   Specifies the offset (from the beginning of the ae_closefile data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_cf_username is 0, the username and
   workstation name are assumed to be the same.

 ae_cf_resname
   Specifies the offset (from the beginning of the ae_closefile data
   structure) to an ASCIIZ string that specifies the name of the resource
   that owns the accessed files.

 ae_cf_fileid
   Specifies the identification number of the file.

 ae_cf_duration
   Specifies how many seconds the resource was used.

 ae_cf_reason
   Specifies the reason the session was disconnected. The AUDIT.H header file
   defines these possible values:

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_NORMAL_CLOSE  0      Normal client disconnection.
 AE_SES_CLOSE     1      Session disconnection.
 AE_ADMIN_CLOSE   2      Administrative disconnection.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Service Status Code or Text Changed  - The ae_servicestat data structure is
 associated with an audit entry of type AE_SERVICESTAT. The ae_servicestat
 data structure has this format:

   struct ae_servicestat {
       unsigned short  ae_ss_compname;
       unsigned short  ae_ss_username;
       unsigned short  ae_ss_svcname;
       unsigned short  ae_ss_status;
       unsigned long   ae_ss_code;
       unsigned short  ae_ss_text;
       unsigned short  ae_ss_returnval;
   };

 where

 ae_ss_compname
   Specifies the offset (from the beginning of the ae_servicestat data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_ss_username
   Specifies the offset (from the beginning of the ae_servicestat data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_ss_username is 0, the username and
   workstation name are assumed to be the same.

 ae_ss_svcname
   Specifies the offset (from the beginning of the ae_servicestat data
   structure) to an ASCIIZ string that specifies the name of a service.

 ae_ss_status
   Specifies the service status to set.

 ae_ss_code
   Specifies the service code to set.

 ae_ss_text
   Specifies the offset to the text to set.

 ae_ss_returnval
   Specifies the return value.

 Access Control List (ACL) Modification  - The ae_aclmod data structure is
 associated with audit entries of type AE_ACLMOD and AE_ACLMODFAIL. The
 ae_aclmod data structure has this format:

   struct ae_aclmod {
       unsigned short  ae_am_compname;
       unsigned short  ae_am_username;
       unsigned short  ae_am_resname;
       unsigned short  ae_am_action;
       unsigned short  ae_am_datalen;
   };

 where

 ae_am_compname
   Specifies the offset (from the beginning of the ae_aclmod data structure)
   to an ASCIIZ string that specifies the name of the workstation that
   established the session.

 ae_am_username
   Specifies the offset (from the beginning of the ae_aclmod data structure)
   to an ASCIIZ string that specifies the name of the user who initiated the
   session. If ae_am_username is 0, the username and workstation name are
   assumed to be the same.

 ae_am_resname
   Specifies the offset (from the beginning of the ae_aclmod data structure)
   to an ASCIIZ string that specifies the name of the resource whose ACL was
   modified.

 ae_am_action
   Specifies the action performed on the ACL record. It is one of the
   following values:

 Value                   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                       Modification.
 1                       Deletion.
 2                       Addition.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ae_am_datalen
   Specifies the length of data that follows the fixed data structure. This
   is always 0 in records generated by Microsoft LAN Manager 2.0.

 User Accounts Subsystem (UAS) Modification  - The ae_uasmod data structure
 is associated with an audit entry of type AE_UASMOD. The ae_uasmod data
 structure has this format:

   struct ae_uasmod {
       unsigned short  ae_um_compname;
       unsigned short  ae_um_username;
       unsigned short  ae_um_resname;
       unsigned short  ae_um_rectype;
       unsigned short  ae_um_action;
       unsigned short  ae_um_datalen;
   };

 where

 ae_um_compname
   Specifies the offset (from the beginning of the ae_uasmod data structure)
   to an ASCIIZ string that specifies the name of the workstation that
   established the session.

 ae_um_username
   Specifies the offset (from the beginning of the ae_uasmod data structure)
   to an ASCIIZ string that specifies the name of the user who initiated the
   session. If ae_um_username is 0, the username and workstation name are
   assumed to be the same.

 ae_um_resname
   Specifies the offset (from the beginning of the ae_uasmod data structure)
   to an ASCIIZ string that specifies the name of the resource whose entry
   was modified.

 ae_um_rectype
   Specifies the type of UAS record. It is one of the following values:

 Value                   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                       User record.
 1                       Group record.
 2                       UAS modals.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ae_um_action
   Specifies the action performed on the UAS record. It is one of the
   following values:

 Value                   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                       Modification.
 1                       Deletion.
 2                       Addition.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ae_um_datalen
   Specifies the length of the data that follows the fixed data structure.
   This is always 0 in records generated by Microsoft LAN Manager 2.0.

 Network Logon Record - The ae_netlogon data structure is associated with an
 audit entry of type AE_NETLOGON. The ae_netlogon data structure has this
 format:

   struct ae_netlogon {
       unsigned short  ae_no_compname;
       unsigned short  ae_no_username;
       unsigned short  ae_no_privilege;
       unsigned short  ae_no_authflags;
   };

 where

 ae_no_compname
   Specifies the offset (from the beginning of the ae_netlogon data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_no_username
   Specifies the offset (from the beginning of the ae_netlogon data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_no_username is 0, the username and
   workstation name are assumed to be the same.

 ae_no_privilege
   Specifies the privilege level of the user logging on. The AUDIT.H header
   file defines these possible values:

 Code      Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_GUEST  0      Guest privilege.
 AE_USER   1      User privilege.
 AE_ADMIN  2      Administrative privilege.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ae_no_authflags
   Reserved; must be 0.

 Network Logoff Record - The ae_netlogoff data structure is associated with
 an audit entry of type AE_NETLOGOFF. The ae_netlogoff data structure has
 this format:

   struct ae_netlogoff {
       unsigned short  ae_nf_compname;
       unsigned short  ae_nf_username;
       unsigned short  ae_nf_reserved1;
       unsigned short  ae_nf_reserved2;
   };

 where

 ae_nf_compname
   Specifies the offset (from the beginning of the ae_netlogoff data
   structure) to an ASCIIZ string that specifies the name of the workstation
   that established the session.

 ae_nf_username
   Specifies the offset (from the beginning of the ae_netlogoff data
   structure) to an ASCIIZ string that specifies the name of the user who
   initiated the session. If ae_nf_username is 0, the username and
   workstation name are assumed to be the same.

 ae_nf_reserved1
   Reserved; must be 0.

 ae_nf_reserved2
   Reserved; must be 0.

 Account Limit Exceeded  - The ae_acclim data structure is associated with an
 audit entry of type AE_ACCLIMITEXCD. The ae_acclim data structure has this
 format:

   struct ae_acclim {
       unsigned short  ae_al_compname;
       unsigned short  ae_al_username;
       unsigned short  ae_al_resname;
       unsigned short  ae_al_limit;
   };

 where

 ae_al_compname
   Specifies the offset (from the beginning of the ae_acclim data structure)
   to an ASCIIZ string that specifies the name of the workstation that
   established the session.

 ae_al_username
   Specifies the offset (from the beginning of the ae_acclim data structure)
   to an ASCIIZ string that specifies the name of the user who initiated the
   session. If ae_al_username is 0, the username and workstation name are
   assumed to be the same.

 ae_al_resname
   Specifies the offset to the resource name; must be 0. This field is not
   used in LAN Manager 2.0.

 ae_al_limit
   Specifies the limit that was exceeded. The AUDIT.H header file defines
   these possible values:

 Code               Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AE_LIM_UNKNOWN     0      Unknown or unavailable.
 AE_LIM_LOGONHOURS  1      Logon hours.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 LAN Manager network commands      LAN Manager administrator's manual(s)

 LANMAN.INI file                   LAN Manager administrator's manual(s)

 Permission levels                 Access Permissions Category and User
                                   Category


 NetAuditClear
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAuditClear clears the audit log on a server and, optionally, saves the
 entries in a backup file. When executed locally, NetAuditClear requires that
 the NETWKSTA device driver be installed, but does not require that the
 Workstation service be started. When a servername parameter is supplied,
 NetAuditClear requires that the local Workstation service be started.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetAuditClear on a
 remote server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETAUDIT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAuditClear (const char far *  pszServer,
                  const char far *  pszBackupFile,
                  char far *        pszReserved
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAuditClear. A null pointer or null string specifies the
   local computer.

 pszBackupFile
   Points to an ASCIIZ string that contains a name for the optional backup
   file. The calling application must have create and write permissions for
   the path specified by pszBackupFile, and the path must already exist. If
   the pathname is relative, it is assumed to be relative to the LAN Manager
   LOGS directory. A null pointer specifies not to back up the audit log.

 pszReserved
   Reserved; must be a null pointer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 ERROR_FILENAME_EXCED_RANGE        206     The filename specified is
                                           invalid for the file system.
                                           This code is returned when
                                           checking a FAT disk partition
                                           only. It cannot be returned for
                                           an HPFS partition.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Getting the status of audit log   NetServerGetInfo
 capacity

 Reading an entry from the audit   NetAuditRead
 log

 Writing an entry to the audit     NetAuditWrite
 log


 NetAuditRead
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAuditRead reads from the audit log on a server. It requires that the
 Workstation service be started.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts, comm, print, or server operator privilege is
 required to successfully execute NetAuditRead on a remote server or on a
 computer that has local security enabled.


 Syntax

   #define INCL_NETAUDIT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAuditRead (const char far *      pszServer,
                 const char far *      pszReserved1
                 HLOG far *            phAuditLog,
                 unsigned long         ulOffset,
                 unsigned short far *  pusReserved2,
                 unsigned long         ulReserved3,
                 unsigned long         flOffset,
                 char far *            pbBuffer,
                 unsigned short        cbBuffer,
                 unsigned short far *  pcbReturned,
                 unsigned short far *  pcbTotalAvail
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAuditRead. A null pointer or null string specifies the local
   computer.

 pszReserved1
   Reserved; must be a null pointer.

 phAuditLog
   Points to the handle for the audit log. An application calling
   NetAuditRead for the first time must initialize the audit log handle as
   follows:

 Bits                             Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 127 (MSB) - 64                   0
 63 - 0 (LSB)                     1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   The most significant bit (MSB) is the leftmost bit; the least significant
   bit (LSB) is the rightmost bit. After the first call, each call to
   NetAuditRead must be given the value for the handle returned by the
   previous call.

 ulOffset
   Specifies the record offset at which to begin reading. This parameter is
   ignored unless bit 1 in the flOffset parameter is set. If flOffset bit 1
   is set, ulOffset is taken as an offset based on the record number (not
   bytes) at which the returned data should begin. Note that the record
   offset parameter is zero-based from both directions, depending upon the
   direction of the read. If reading backward, record 0 is the last record in
   the log. If reading forward, record 0 is the first record in the log.

 pusReserved2
   Reserved; must be a null pointer.

 ulReserved3
   Reserved; must be 0.

 flOffset
   Specifies the open flags, as follows:

 Bit(s)                            Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 If 0, the log is read forward. If 1, the
                                   log is read backward and records are
                                   returned in the buffer in reverse
                                   chronological order (newest records
                                   first).

 1                                 If 0, reading proceeds sequentially. If
                                   1, reading proceeds from the nth record
                                   from the start of the log, where n is
                                   the offset parameter.

 2-31                              Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 pbBuffer
   Points to the buffer for returned data. After a successful read operation,
   this buffer contains a sequence of audit entries with the accompanying
   variable-length data structures.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbReturned
   Points to an unsigned short integer in which a count of the number of
   bytes read into the buffer is returned.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the number of
   bytes available is returned.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_LogFileChanged               2378    The log file has changed since
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_LogFileChanged               2378    The log file has changed since
                                           it was last read.

 NERR_LogFileCorrupt               2379    The log file is corrupt.

 NERR_InvalidLogSeek               2440    The log file does not contain
                                           the requested record number.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 To read the contents of an audit log, an application calls NetAuditRead
 repeatedly until it returns information (via the pcbTotalAvail parameter)
 that indicates there is no more data to be read. Each call to NetAuditRead
 returns a handle that must be provided to any subsequent call to
 NetAuditRead. This handle changes with each subsequent call; it is not a
 system file handle and should never be treated as such.

 Note that the audit log can contain much more than 64K of data. If
 pcbTotalAvail is returned with a value of 0xFFFF, there can be 0xFFFF or
 more bytes of data available. The application should continue to read the
 log until 0 is returned in pcbTotalAvail.

 NetAuditRead passes data back in the buffer in whole records. The
 application never receives a partial record in the buffer. Use the value
 pointed to by pcbReturned to determine the end of valid data in the buffer.


 The audit log is written with the newest records appended to the end of the
 log. The flOffset parameter determines whether to read the log in forward or
 in reverse order.

 If the audit log is read partially, and then the log is cleared or a new
 record is written, subsequent reading with the handle returned from the
 first call to NetAuditRead returns an error. An application that finds the
 audit log changed between calls can reread the changed log by reissuing the
 call with the audit handle initialized as if it were making the call for the
 first time.

 Attempting to read the log while another application is writing an entry to
 the log results in NetAuditRead returning ERROR_SHARING_VIOLATION.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Clearing an audit log             NetAuditClear

 Writing an entry to the audit     NetAuditWrite
 log


 NetAuditWrite
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAuditWrite writes an audit entry to the local audit log. For audit
 entries to be written to the log, the Server service must be started with
 auditing enabled.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1 not supported

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to successfully execute
 NetAuditWrite.


 Syntax

   #define INCL_NETAUDIT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAuditWrite (unsigned short    usType,
                  const char far *  pbBuffer,
                  unsigned short    cbBuffer,
                  char far *        pszReserved1,
                  char far *        pszReserved2
                 );

 where

 usType
   Specifies the type of entry to write to the audit log.

 pbBuffer
   Points to a buffer that contains the data structure associated with the
   specified audit entry.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pszReserved1
   Reserved; must be a null pointer.

 pszReserved2
   Reserved; must be a null pointer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_NET_WRITE_FAULT             88      A network data fault occurred.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          is not installed.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_LogOverflow                  2377    The log file is too big.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetAuditWrite issues an admin alert by calling NetAlertRaise when the audit
 log reaches 80% capacity and again when the log reaches 100% capacity. At
 100% audit log capacity, NetAuditWrite fails and returns NERR_LogOverflow.
 Applications should periodically clear the audit log of outdated information
 to avoid the log reaching 100% capacity.

 Events of a particular type cannot be written to the audit log unless
 auditing for that type of event is enabled. If auditing for the event type
 is not enabled, NetAuditWrite still returns NERR_Success, but no entries are
 written.

 You can use one of these methods to enable auditing:


   þ   Set the auditing entry in the [server] section of the LANMAN.INI file
       to yes or to a list of event types to be audited.

   þ   Use the net start server command with the /auditing option.


 For more information, see the your LAN Manager administrator's manual(s).

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Alerts                            Alert Category

 Clearing the audit log            NetAuditClear

 Getting the status of audit log   NetServerGetInfo
 capacity

 Reading the audit log             NetAuditRead

 Setting the maximum size of the   NetServerSetInfo
 audit log





 Auditing Category Example

   /*
      NETAUD.C -- a sample program demonstrating NetAudit API functions.

      This program requires that you have admin privilege on the specified
      server.

         usage:  netaud [-s \\server] [-b backup]

         where  \\server = Name of the server. A servername must be preceded

                           by two backslashes (\\).
                backup   = Name of the backup file.

      API               Used to...
      =============     ===========================================
      NetAuditRead      Read the audit log and display its contents
      NetAuditClear     Copy the audit log and then clear it
      NetAuditWrite     Write entries into the audit log

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETERRORS
   #define     INCL_NETAUDIT
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <malloc.h>
   #include    <time.h>

   #define DEFAULT_BACKUP     "AUDIT.BCK"
   #define BIG_BUFFER         32768

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pszServer = "";         // Servername
      char *         pszBackup = DEFAULT_BACKUP;  // Backup audit log

      int            iCount;                 // Index counter
      HLOG           hLogHandle;             // Audit log handle
      time_t         tTime;                  // Time of entry
      unsigned short cbBuffer;               // Size of buffer, in bytes
      unsigned short cbRead;                 // Count of bytes read
      unsigned short cbAvail;                // Count of bytes available
      API_RET_TYPE   uReturnCode;            // API return code
      struct audit_entry far * fpBuffer;     // Pointer to the data buffer
      struct audit_entry far * fpEntry;      // Single entry in the audit
   log
      struct ae_servicestat far * fpService; // Service status structure

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'b':                        // -b backup file
                  pszBackup = argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetAuditRead
   //
   //  This API reads and displays the audit log for the specified server.
   //  If the entry is for Service Status Code or Text Changed, print
   //  the service and computername.
   //========================================================================

      /*
       * Allocate a large buffer space to handle large audit logs.
       * The largest buffer allowed is 64K. If the audit log is
       * larger than the buffer specified, the API returns as many
       * full records as it can and the NERR_Success return code.
       * Subsequent reading starts from the end of the last record
       * read. To read the whole log, reading must continue until 0
       * is returned for the bytes available counter.
       */

   cbBuffer = BIG_BUFFER;                 // Can be up to 64K

      /*
       * Set the log handle for reading from the start of the audit log.
       * This handle is modified by the API; any subsequent reading
       * of unread data should use the returned handle.
       */

      hLogHandle.time = 0L;
      hLogHandle.last_flags = 0L;
      hLogHandle.offset = 0xFFFFFFFF;
      hLogHandle.last_flags = 0xFFFFFFFF;

      fpBuffer = _fmalloc(cbBuffer);         // Allocate memory for buffer

      if (fpBuffer == NULL)
      {
         fprintf(stderr, "Malloc failed -- out of memory.\n");
         exit(1);
      }
      uReturnCode = NetAuditRead(
                        pszServer,               // Servername
                        NULL,                    // Reserved; must be
   NULL
                        (HLOG far *)&hLogHandle, // Audit log handle
                        0L,                      // Start at record 0
                        NULL,                    // Reserved; must be
   NULL
                        0L,                      // Reserved; must be
   0
                        0L,                      // Read the log forward
                        (char far *)fpBuffer,    // Data returned here
                        cbBuffer,                // Size of buffer, in
   bytes
                        &cbRead,                 // Count of bytes read
                        &cbAvail);               // Count of available
   bytes

      printf("NetAuditRead returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         for ( fpEntry = fpBuffer;
               fpEntry < (struct audit_entry far *)
                               ((char far *)fpBuffer + cbRead); )
         {
            tTime = (time_t) fpEntry->ae_time;

            printf("   Type %d, at %s", fpEntry->ae_type,
                           asctime( gmtime ((const time_t *) &tTime)
   ) );

   /*
             * If the entry is for Service Status Code or Text Changed,
             * print the service and computername. This demonstrates
   how
             * to extract information using the offsets to the log.
             */

            if (fpEntry->ae_type == AE_SERVICESTAT)
            {
               fpService = (struct ae_servicestat far *)
                        ((char far *)fpEntry + fpEntry->ae_data_offset);
               printf("\tComputer = %Fs\n",
                        (char far *)fpService+fpService->ae_ss_compname);

               printf("\tService  = %Fs\n",
                        (char far *)fpService+fpService->ae_ss_svcname);

            }
            fpEntry = (struct audit_entry far *)
                        ((char far *)fpEntry + fpEntry->ae_len);
         }

         printf("\nBytes Read = 0x%X\n", cbRead);

         // To read the whole log, keep reading until cbAvail is 0.

         if (cbAvail)
            printf("Data still unread.\n\n");
         else
            printf("All data read.\n\n");
      }

   //========================================================================
   //  NetAuditClear
   //
   //  This API clears the audit log for the specified server. A backup

   //  will be kept in the file specified by pszBackup. If a null pointer

   //  is supplied, no backup is kept.
   //========================================================================

      uReturnCode = NetAuditClear(
                        pszServer,           // Servername
                        pszBackup,           // Name of backup file
                        NULL);               // Reserved; must be NULL

      printf("NetAuditClear returned %u\n", uReturnCode);
      printf("   backup file = %s \n", pszBackup);

   //========================================================================
   //  NetAuditWrite
   //
   //  This API writes back the entries read by the NetAuditRead call.
   //  Each entry read consisted of a fixed-length header, a variable-
   //  length data section, and a terminating size indicator. Only
   //  the variable-length data area is supplied in the NetAuditWrite
   //  buffer. Note: For any entries to be written to the audit log,
   the
   //  Server service must be started with auditing enabled.
   //========================================================================

      for ( fpEntry = fpBuffer;
            fpEntry < (struct audit_entry far *)
                            ((char far *)fpBuffer + cbRead); )
      {
         uReturnCode = NetAuditWrite(
                           fpEntry->ae_type,      // Entry type
                                                  // Buffer address
                           (char far *)fpEntry + fpEntry->ae_data_offset,
                                                  // Buffer length
                           fpEntry->ae_len - fpEntry->ae_data_offset

                              - sizeof(unsigned short),
                           NULL,                  // Reserved; must be
   NULL
                           NULL);                 // Reserved; must be
   NULL

         if (uReturnCode != NERR_Success)
         {
            printf("NetAuditWrite returned %u", uReturnCode);
            break;
         };

         fpEntry = (struct audit_entry far *)
                            ((char far *)fpEntry + fpEntry->ae_len);
      }

      _ffree(fpBuffer);
      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-b backup]\n", pszProgram);
      exit(1);
   }









 Character Device Category

 Character Device API functions control shared communication devices and
 their asso- ciated queues. They require that the Workstation service be
 started and that the Server service be started on the specified server.

 The Character Device category functions, datatypes, structures, and
 constants are defined in the NETCONS.H, NETERR.H, and CHARDEV.H header
 files. A source program can access these definitions by defining the
 constants INCL_NETERRORS and INCL_NETCHARDEV, and including the master
 header file, LAN.H. For more information about these definitions, see the
 "Example" section, later in this category.

 These are the Character Device API functions:


   þ   NetCharDevControl

   þ   NetCharDevEnum

   þ   NetCharDevGetInfo

   þ   NetCharDevQEnum

   þ   NetCharDevQGetInfo

   þ   NetCharDevQPurge

   þ   NetCharDevQPurgeSelf

   þ   NetCharDevQSetInfo



 Description

 A modem, FAX machine, or serial printer may require that an application
 submit commands or change protocols dynamically. Such devices, which require
 direct and interactive communication, are called communication devices.

 A LAN Manager server can share one or more communication devices of the same
 type from a communication-device queue. A communication-device queue stores
 communication-device requests and sends the requests, one at a time, to a
 communication device. Multiple applications can use a server's communication
 devices by establishing connections to the communication-device queue. The
 server gives each application exclusive access to a device until the
 application is done using the device. The server allocates available devices
 based on the priority assigned to the queue.

 Three things must occur before an application can communicate with a
 communication device: the server must have a communication device connected
 to one of its available parallel or serial ports; the server must share a
 communication-device queue; and the requesting application must establish a
 connection to the shared communication-device queue.

 When the application is done using the communication device, it should close
 the device. Closing the device returns control of the device to the
 communication-device queue, making it available to another application.

 NetCharDevGetInfo returns information about a particular communication
 device. NetCharDevQGetInfo returns the status of a communication-device
 queue or the position in the waiting list of an application's request.

 NetCharDevEnum returns the status of all communication devices. All queues
 can be checked by calling NetCharDevQEnum.

 Applications can call NetCharDevQPurgeSelf to eliminate all requests
 submitted to a particular communication-device queue by the specified
 computer. NetCharDevQPurge removes all pending requests to a particular
 communication-device queue, but it does not affect a process that has a
 device open.

 NetCharDevControl can be used to close the communication device when other
 methods fail. An application usually closes the communication device by
 calling the DosClose function. If DosClose fails, a user with admin
 privilege or comm operator privilege can use NetCharDevControl to close the
 device.

 The following scenario illustrates how communication devices and queues
 work. Three communication devices are connected to a server's serial ports:


 Port                    Device
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 COM1:                   Modem.
 COM2:                   Modem.
 COM3:                   FAX machine.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Note that communication-device queues are not created the same way printer
 queues are created. A communication-device queue exists from the time the
 sharename is created by NetShareAdd until it is deleted by NetShareDel. In
 contrast, a printer queue exists from the time the queue is created by
 DosPrintQAdd until it is removed by DosPrintQDel, whether or not the printer
 queue is shared.

 After communication devices are connected to the ports, the application
 creates three communication-device queues by calling NetShareAdd three
 times:

 Queuename  Priority  Devicename
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 FAXQ       5         COM3
 MODEMQ     5         COM1, COM2
 VIPMODEM   1         COM2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Note that the COM2: port is allocated to two different queues, MODEMQ and
 VIPMODEM.

 The application assigns a priority to the communication-device queue by
 calling NetCharDevQSetInfo. The priority can range from 1 (highest) through
 9 (lowest). LAN Manager processes requests to queues that have high priority
 before granting requests to queues that have lower priorities. The VIPMODEM
 queue is given the highest priority, 1.

 The application then establishes an implicit or explicit connection to the
 shared communication-device queue. An implicit connection is established by
 calling DosOpen, which opens the device. An explicit connection is
 established by calling NetUseAdd to redirect a local or null devicename to
 the queue. An explicit connection does not open the device. For more
 information about redirecting a local devicename to a shared resource, see
 the Use category API functions.

 If there is more than one device in a communication-device queue, the queue
 returns the first available device. If no devices are available, the queue
 holds the request until a device becomes available. The requesting computer
 waits for the time specified by the charwait entry in the [workstation]
 section of its LANMAN.INI file. If the commu- nication device does not
 become available within that time, the DosOpen function returns the
 ERROR_BAD_NET_RESP error code.

 For example, if requests are made to both the MODEMQ and VIPMODEM queues
 while all communication devices are in use, and if COM2 becomes the next
 device available, COM2 is made available to the requesting application in
 the VIPMODEM queue because the VIPMODEM queue has higher priority than the
 MODEMQ queue.

 Once an available device is made available to the request, the application
 begins communicating with that device.

 When an application successfully opens a remote communication device, the
 values of the wkiX_chartime and wkiX_charcount elements of the wksta_info_X
 data structure (where X is the level of detail requested by the function)
 control how information flows over the network. Because of the following
 effects, use care when changing these values:


   þ   The wkiX_chartime and wkiX_charcount elements affect all applications
       running on the workstation.

   þ   Network performance can be degraded. Network efficiency, response
       time, and throughput can be adversely affected.


 For more information about the wksta_info_X data structure and wkiX_chartime
 and wkiX_charcount elements, see the Workstation category API functions and
 your LAN Manager administrator's manual(s).


 Data Structures

 The sLevel parameter controls the level of information provided to or
 returned from the data structures used by NetCharDevEnum, NetCharDevGetInfo,
 NetCharDevQEnum, NetCharDevQGetInfo, and NetCharDevQSetInfo.


 Communication Device Information (level 0)

 NetCharDevEnum and NetCharDevGetInfo use the chardev_info_0 data structure
 when the sLevel parameter is 0. The chardev_info_0 data structure has this
 format:

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

 where

 ch0_dev
   Contains an ASCIIZ string that specifies the devicename associated with
   the commu- nication device. The constant DEVLEN is defined in the
   NETCONS.H header file.


 Communication Device Information (level 1)

 NetCharDevEnum and NetCharDevGetInfo use the chardev_info_1 data structure
 when the sLevel parameter is 1. The chardev_info_1 data structure has this
 format:

   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;
   };

 where

 ch1_dev
   Contains an ASCIIZ string that specifies the devicename associated with
   the communication device.

 ch1_pad1
   Aligns the next data structure element on a word boundary.

 ch1_status
   Specifies the status of the device, as follows:

 Bit(s)                            Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 Reserved; must be 0.

 1                                 If 0, the device is idle; if 1, the
                                   device is open.

 2                                 If 0, the device encountered no errors;
                                   if 1, the device encountered
                                   an error.

 3-15                              Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


   The following bit masks are used with ch1_status. The CHARDEV.H header
   file defines these possible values:

 Code                 Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 CHARDEV_STAT_OPENED  0x02      The communication device is open.

 CHARDEV_STAT_ERROR   0x04      The communication device  encountered an
                                error.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 ch1_username
   Contains an ASCIIZ string that specifies the name of the user currently
   using the device. The constant UNLEN is defined in the NETCONS.H header
   file.

 ch1_pad2
   Aligns the next data structure element on a word boundary.

 ch1_time
   Specifies how many seconds the current application has been connected to
   the communication device.


 Communication Device Queues Information (level 0)

 NetCharDevQEnum and NetCharDevQGetInfo use the chardevQ_info_0 data
 structure when the sLevel parameter is 0. The chardevQ_info_0 data structure
 has this format:

   struct chardevQ_info_0 {
       char  cq0_dev[NNLEN+1];
   };

 where

 cq0_dev
   Contains an ASCIIZ string that specifies the queuename. The constant NNLEN
   is defined in the NETCONS.H header file.


 Communication Device Queues Information (level 1)

 NetCharDevQEnum, NetCharDevQGetInfo, and NetCharDevQSetInfo use the
 chardevQ_info_1 data structure when the sLevel parameter is 1. The
 chardevQ_info_1 data structure has the following format:

   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;
   };

 where

 cq1_dev
   Contains an ASCIIZ string that specifies the queuename. The constant NNLEN
   is defined in the NETCONS.H header file.

 cq1_pad
   Aligns the next data structure element on a word boundary.

 cq1_priority
   Specifies the queue priority. The value of cq1_priority can range from 1
   (highest priority) through 9 (lowest priority).

 cq1_devs
   Points to an ASCIIZ string that contains the devicenames assigned to the
   queue. The devicenames are separated by a space (for example, COM1 COM3).

 cq1_numusers
   Specifies the number of requests in the queue.

 cq1_numahead
   Specifies the number of requests ahead of a particular user in the queue.
   A value of CHARDEVQ_NO_REQUESTS means that the username pointed to by
   pszUserName in the call to NetCharDevQEnum has no requests in the queue.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Creating a communication-device   Share Category
 queue

 Data structure architecture       Chapter 1, "Overview of the LAN Manager
                                   API"

 Setting LANMAN.INI parameters     LAN Manager administrator's manual(s)

 Using a communication device      Use Category


 NetCharDevControl
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevControl changes the state of a communication device according to
 the specified operation code (opcode). The supplied opcode, CHARDEV_CLOSE,
 closes the communication device.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm operator privilege is required to successfully
 execute NetCharDevControl on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevControl (const char far *  pszServer,
                      const char far *  pszDevName,
                      short             sOpCode
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevControl. A null pointer or null string specifies the
   local computer.

 pszDevName
   Points to an ASCIIZ string that specifies the device to modify.

 sOpCode
   Specifies how to modify pszDevName. This value, defined in the CHARDEV.H
   header file, can be CHARDEV_CLOSE (0), which indicates to close the
   communication device and disconnect any current clients.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_SEM_TIMEOUT                 121     A time-out occurred from the
                                           Semaphore API functions.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_DevInvalidOpCode             2331    The operation is invalid for
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_DevInvalidOpCode             2331    The operation is invalid for
                                           this device.

 NERR_DevNotFound                  2332    This device cannot be shared.

 NERR_DevNotOpen                   2333    The device is not open.

 NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 A communication device is usually closed by a call to the DosClose function.
 If the process that opened the device cannot close it, NetCharDevControl can
 be called to force the device closed.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Modifying a communication-device  NetCharDevQSetInfo
 queue

 Retrieving information about a    NetCharDevGetInfo
 communication device

 Retrieving information about a    NetCharDevQGetInfo
 communication-device queue


 NetCharDevEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevEnum provides information about all communication devices in
 shared communication-device queues on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege is required to successfully execute NetCharDevEnum.


 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevEnum (const char far *      pszServer,
                   short                 sLevel,
                   char far *            pbBuffer,
                   unsigned short        cbBuffer,
                   unsigned short far *  pcEntriesRead,
                   unsigned short far *  pcTotalAvail
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevEnum. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0 or 1) requested for the returned
   chardev_info data structure.

 pbBuffer
   Points to the buffer in which to store the return data. On a successful
   return, the buffer contains a sequence of chardev_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer that specifies how many entries were
   returned. This count is valid only if NetCharDevEnum returns NERR_Success
   or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer that specifies how many entries were
   available. This count is valid only if NetCharDevEnum returns NERR_Success
   or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NoCommDevs                   2337    There are no shared
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Enum functions                    Chapter 1, "Overview of the LAN Manager
                                   API"

 Listing communication-device      NetCharDevQEnum
 queues on a server


 NetCharDevGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevGetInfo retrieves information about a particular communication
 device in a shared communication-device queue on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege is required to successfully execute NetCharDevGetInfo.



 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevGetInfo (const char far *      pszServer,
                      const char far *      pszDevName,
                      short                 sLevel,
                      char far *            pbBuffer,
                      unsigned short        cbBuffer,
                      unsigned short far *  pcbTotalAvail
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevGetInfo. A null pointer or null string specifies the
   local computer.

 pszDevName
   Points to an ASCIIZ string that contains the name of the specified
   communication device.

 sLevel
   Specifies the level of detail (0 or 1) to be provided in the return
   buffer.

 pbBuffer
   Points to the buffer in which to store the return data. On a successful
   return, the buffer contains the chardev_info_X data structure, where X is
   0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer that specifies how many bytes of
   information were available. This count is valid only if NetCharDevGetInfo
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_DevNotFound                  2332    This device cannot be shared.

 NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 GetInfo functions                 Chapter 1, "Overview of the LAN Manager
                                   API"

 Listing all communication         NetCharDevEnum
 devices

 Modifying the state of a          NetCharDevControl
 communication device


 NetCharDevQEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevQEnum enumerates all communication-device queues on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege is required to successfully execute NetCharDevQEnum.


 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevQEnum (const char far *      pszServer,
                    const char far *      pszUserName,
                    short                 sLevel,
                    char far *            pbBuffer,
                    unsigned short        cbBuffer,
                    unsigned short far *  pcEntriesRead,
                    unsigned short far *  pcTotalAvail
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevQEnum. A null pointer or null string specifies the
   local computer.

 pszUserName
   Points to an ASCIIZ string that contains the name of a user. When level 1
   is specified, the cq1_numahead element of the chardevQ_info_1 data
   structure represents the number of requests ahead of the request submitted
   by this user.

 sLevel
   Specifies the level of detail (0 or 1) to be returned in the buffer
   pointed to by pbBuffer.

 pbBuffer
   Points to the buffer in which to store the return data. On a successful
   return, the buffer contains a sequence of chardevQ_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the return buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer that specifies how many entries were
   returned. This count is valid only if NetCharDevQEnum returns NERR_Success
   or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer that specifies how many entries were
   available. This count is valid only if NetCharDevQEnum returns
   NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Enum functions                    Chapter 1, "Overview of the LAN Manager
                                   API"

 Listing all communication         NetCharDevEnum
 devices associated with
 communicationdevice queues on a
 server

 Retrieving information about a    NetCharDevQGetInfo
 specific communication-device
 queue


 NetCharDevQGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevQGetInfo retrieves information about a particular
 communication-device queue on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege is required to successfully execute NetCharDevQGetInfo.



 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevQGetInfo (const char far *      pszServer,
                       const char far *      pszQueueName,
                       const char far *      pszUserName,
                       short                 sLevel,
                       char far *            pbBuffer,
                       unsigned short        cbBuffer,
                       unsigned short far *  pcbTotalAvail
                      );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevQGetInfo. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that contains the name of the
   communication-device queue about which information is requested.

 pszUserName
   Points to an ASCIIZ string that contains the name of a user. The
   cq1_numahead element in the returned chardevQ_info_1 data structure
   represents the number of requests in the queue ahead of the request
   submitted by this user.

 sLevel
   Specifies the level of detail (0 or 1) to be provided in the return
   buffer.

 pbBuffer
   Points to the buffer in which to store return data. On a successful
   return, the buffer  contains the chardevQ_info_X data structure, where X
   is 0 or 1, depending on the level of detail specified.

 cbBuffer
   Specifies the size (in bytes) of the return buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer that specifies how many bytes of
   information were available. This count is valid only if NetCharDevQGetInfo
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_BadUsername                  2202    The username or groupname is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadUsername                  2202    The username or groupname is
                                           invalid.

 NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 NERR_QueueNotFound                2338    The sharename does not exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 GetInfo functions                 Chapter 1, "Overview of the LAN Manager
                                   API"

 Listing all communication-device  NetCharDevQEnum
 queues on a server

 Modifying the state of a          NetCharDevQSetInfo
 communication-device queue


 NetCharDevQPurge
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevQPurge deletes all pending requests in a communication-device
 queue.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm operator privilege is required to successfully
 execute NetCharDevQPurge on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevQPurge (const char far *  pszServer,
                     const char far *  pszQueueName
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevQPurge. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that contains the name of the queue from which
   to purge pending requests.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_SEM_TIMEOUT                 121     A time-out occurred from the
                                           Semaphore API functions.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 NERR_QueueNotFound                2338    The sharename does not exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetCharDevQPurge deletes only requests that have not yet been assigned to a
 device. It does not affect a process that currently has a device open. All
 pending requests in the queue pointed to by pszQueueName are canceled, and
 ERROR_BAD_NET_RESP is returned for each call to the DosOpen function. All
 handles remain valid.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Closing the current session of a  NetCharDevControl
 communication device

 Deleting the                      NetCharDevQPurgeSelf
 communication-device queue
 requests made by the specified
 computer

 Listing the communication-device  NetCharDevQEnum
 queues on a server


 NetCharDevQPurgeSelf
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevQPurgeSelf deletes all pending requests submitted by a particular
 computer in a communication-device queue.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm operator privilege is required to successfully
 execute NetCharDevQPurgeSelf on a remote server or on a computer that has
 local security enabled.


 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevQPurgeSelf (const char far *  pszServer,
                         const char far *  pszQueueName,
                         const char far *  pszComputerName
                        );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevQPurgeSelf. A null pointer or null string specifies
   the local computer.

 pszQueueName
   Points to an ASCIIZ string that contains the name of the queue from which
   to purge requests.

 pszComputerName
   Points to an ASCIIZ string that contains the name of the computer whose
   requests are to be deleted from the queue specified by pszQueueName.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_SEM_TIMEOUT                 121     A time-out occurred from the
                                           Semaphore API functions.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_ItemNotFound                 2115    The queue is empty.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 NERR_QueueNotFound                2338    The sharename does not exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetCharDevQPurgeSelf is similar to NetCharDevQPurge, except that it deletes
 only requests made from the computer specified by pszComputerName. A process
 that has a device open is unaffected.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Deleting the contents of a        NetCharDevQPurge
 communication-device queue

 Listing communication-device      NetCharDevQEnum
 queues on a server

 Modifying the state of a          NetCharDevQSetInfo
 communication-device queue


 NetCharDevQSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevQSetInfo modifies the settable fields of a specified
 communication-device queue on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm operator privilege is required to successfully
 execute NetCharDevQSetInfo on a remote server or on a computer that has
 local security enabled.


 Syntax

   #define INCL_NETCHARDEV
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetCharDevQSetInfo (const char far *  pszServer,
                       const char far *  pszQueueName,
                       short             sLevel,
                       char far *        pbBuffer,
                       unsigned short    cbBuffer,
                       short             sParmNum
                      );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetCharDevQSetInfo. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that contains the name of the
   communication-device queue to set.

 sLevel
   Specifies the level of detail; must be 1.

 pbBuffer
   Points to the buffer that contains the data to set. The buffer contains
   the entire chardevQ_info_1 data structure or an individual record as
   specified by sParmNum.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to set one or all elements of the chardevQ_info_1 data
   structure. If sParmNum is PARMNUM_ALL, all elements are to be set, and
   pbBuffer must point to a chardevQ_info_1 data structure. If sParmNum is
   any other defined value, only one element is to be set, and pbBuffer must
   point to that element.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The CHARDEV.H and NETCONS.H
   header files define these possible values for sParmNum:

 Code                       Value  Element of chardevQ_info_1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL                0      All elements.
 CHARDEVQ_PRIORITY_PARMNUM  2      cq1_priority
 CHARDEVQ_DEVICES_PARMNUM   3      cq1_devs
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_SEM_TIMEOUT                 121     A time-out occurred from the
                                           Semaphore API functions.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_RedirectedPath               2117    The operation is invalid for a
                                           redirected resource. The
                                           devicename specified is assigned
                                           to a shared resource.

 NERR_NoRoom                       2119    The server could not access
                                           enough of a resource, such as
                                           memory, to complete the task.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_UseNotFound                  2250    This network connection does not
                                           exist.

 NERR_BadQueuePriority             2335    The queue priority is invalid.

 NERR_NoCommDevs                   2337    There are no shared
                                           communication devices.

 NERR_QueueNotFound                2338    The sharename does not exist.

 NERR_BadDevString                 2340    The list of devices is invalid.

 NERR_BadDev                       2341    The devicename is invalid
                                           because it does not represent a
                                           physical device, or because the
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          physical device, or because the
                                           device hardware is faulty.

 NERR_InUseBySpooler               2342    The device is already used with
                                           a printer queue. It cannot be
                                           used
                                           with both printer queues and
                                           communication-device queues.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all communication-device  NetCharDevQEnum
 queues on a server

 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"

 Retrieving information about a    NetCharDevQGetInfo
 specific communication-device
 queue on a server

 SetInfo functions                 Chapter 1, "Overview of the LAN Manager
                                   API"





 Character Device Category Example

   /*
      NETCHAR1.C -- a sample program demonstrating NetCharDev API functions.

      This program requires that you have admin privilege or comm operator
      privilege on the specified server.

         usage:  netchar1 [-s \\server] [-d device] [-q queue]
                          [-u user] [-w wksta] [-p priority]
         where  \\server = Name of the server. A servername must be preceded
                           by two backslashes (\\).
                device   = Actual physical devicename.
                queue    = Shared communication-device queue.
                user     = Name of logged-on user.
                wksta    = Workstation name.
                priority = Queue priority (1 through 9).

      This program spawns the child process netchar2.exe.

      API                      Used to...
      ====================     ==========================================
      NetCharDevQPurge         Remove all inactive jobs from a queue
      NetCharDevControl        Close a communication device
      NetCharDevQPurgeSelf     Remove own inactive jobs from a queue
      NetCharDevQGetInfo       Get information about a particular queue
      NetCharDevQSetInfo       Set priority level, comm devices for queue
      NetCharDevQEnum          Get information about all device queues
      NetCharDevEnum           Get information about all devices
      NetCharDevGetInfo        Get information about a particular device

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_BASE
   #include    <os2.h>        // MS OS/2 base header files

   #define     INCL_NETCHARDEV
   #define     INCL_NETERRORS
   #define     INCL_NETWKSTA
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <ctype.h>
   #include    <conio.h>
   #include    <string.h>
   #include    <process.h>

   #include    "samples.h"    // Internal routine header file

   /*
    * List max. size of buffer for each character-device queue.
    * Note: In this program there is only one device attached.
    */

   #define MAX_CHARDEVQ_INFO_1 (sizeof(struct chardevQ_info_1) + DEVLEN
   + 1)

   #define  SEMAPHORE            "\\sem\\chardev"
   #define  CHILD_PROCESS        "netchar2.exe"

   #define  START_JOB            '0'
   #define  STATUS_DEVICE        '1'
   #define  LIST_DEVICES         '2'
   #define  ENUM_QUEUES          '3'
   #define  VIEW_PRIORITY        '4'
   #define  CHANGE_PRIORITY      '5'
   #define  KILL_ACTIVE_JOB      '6'
   #define  PURGE_OWN_JOBS       '7'
   #define  PURGE_QUEUE          '8'
   #define  EXIT                 '9'

   #define STACK_SIZE             4096

   // Function prototypes
   BOOL GetDeviceInfo (char *, char *);
   BOOL EnumerateQueues (char *, char far *);
   BOOL EnumerateDevices (char *);
   BOOL ViewPriority (char *, char * , char far *);
   BOOL ChangePriority (char *, char * , unsigned short);
   BOOL OpenPort (HSYSSEM, char *, char *);
   BOOL StopInactiveJobs (char *, char *, char far *);
   void DisplayPrompt (void);
   char GetNextAction (void);
   char far * FarStrcpy (char far *, char far *);

   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      char *pszDevice = "COM1";       // Default comm device
      char *pszQueue = "COMQUEUE";    // Default comm-queue name
      char *pszServer = "";           // Default to local computer
      char far *pszUser = "";         // far * from NetWkstaGetInfo call
      char far *pszWksta = "";        // far * from NetWkstaGetInfo call
      char chAction;                  // Menu selection
      char pszShare[RMLEN+1];         // Server, queuename for semaphore
      HSYSSEM hssmClose;              // Handle to system semaphore
      USHORT cbBuflen;                // Size of buffer
      int    iCount;                  // Index counter
      USHORT usPriority = 1;          // Priority assigned to queue
      USHORT cbTotalAvail;            // Value for NetWkstaGetInfo call
      USHORT usRet;                   // MS OS/2 return code
      unsigned uRet;                  // LAN Manager return code
      struct wksta_info_10 *pBuf;     // Pointer to return buffer

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'q':                        // -q queuename
                  pszQueue = argv[++iCount];
                  break;
               case 'u':                        // -u username
                  pszUser = (char far *)argv[++iCount];
                  break;
               case 'd':                        // -d devicename
                  pszDevice = argv[++iCount];
                  break;
               case 'w':                        // -w workstation
                  pszWksta = (char far *)argv[++iCount];
                  break;
               case 'p':                        // -p priority
                  usPriority = atoi(argv[++iCount]);
                  break;




               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      } // End for loop

      if ((pszServer == NULL) || (*pszServer == '\0') ||
          (pszUser   == NULL) || (*pszUser   == '\0') ||
          (pszWksta  == NULL) || (*pszWksta  == '\0')  )
      {
         uRet = NetWkstaGetInfo(pszServer,   // Servername
                         10,                 // Level
                         NULL,               // Return buffer
                         0,                  // Size of buffer
                         &cbTotalAvail);     // Count of bytes available
         if ((uRet != NERR_BufTooSmall) && (uRet != ERROR_MORE_DATA))
         {
            printf("NetWkstaGetInfo returned %u\n", uRet);
            exit(1);
         }
         pBuf = (struct wksta_info_10 *) SafeMalloc(cbBuflen);
         uRet = NetWkstaGetInfo(pszServer,   // Servername
                         10,                 // Level
                         (char far *) pBuf,  // Return buffer
                         cbBuflen,           // Size of buffer
                         &cbTotalAvail);     // Count of bytes available
         if (uRet != NERR_Success)
         {
            printf("NetWkstaGetInfo returned %u\n", uRet);
            exit(1);
         }
      }
      if ((pszServer != NULL) && (*pszServer != '\0')) // Set up for
   semaphore
         strcpy (pszShare, pszServer);
      else
      {
         strcpy (pszShare, "\\\\");          //Insert leading backslashes
         FarStrcat((char far *)pszShare, pBuf->wki10_computername);
      }
      strcat (pszShare, "\\" );
      strcat (pszShare, pszQueue);
      if ((pszUser == NULL) || (*pszUser == '\0'))
         pszUser = pBuf->wki10_username;
      if ((pszWksta == NULL) || (*pszWksta == '\0'))
         pszWksta = pBuf->wki10_computername;
      // Create the semaphore that will be used to stop the active job.
      if ( (usRet = DosCreateSem (CSEM_PUBLIC, &hssmClose, SEMAPHORE
   )) != 0)
      {
         printf ("DosCreateSem returned %hu\n", usRet);
         exit(1);
      }
      while (TRUE)
      {
         DisplayPrompt();
         chAction = GetNextAction ();
         printf("\n");
         switch (chAction)
         {
            // Open the com port.
            case START_JOB:
               OpenPort (hssmClose, pszShare, SEMAPHORE);
               continue;

            // Close (has no effect if there is no active job).
            case PURGE_QUEUE:
               uRet = NetCharDevQPurge(pszServer, pszQueue);
               printf("NetCharDevQPurge returned %u\n", uRet);
               continue;

            //Kill the active job.
            case KILL_ACTIVE_JOB:
               uRet = NetCharDevControl(pszServer,
                                         pszDevice,
                                         CHARDEV_CLOSE);
               printf("NetCharDevControl returned %u\n", uRet);
               usRet = DosSemClear(hssmClose);
               printf("DosSemClear returned %hu\n", usRet);
               continue;

            // NetCharDevQPurgeSelf
            case PURGE_OWN_JOBS:
               StopInactiveJobs(pszServer, pszQueue, pszWksta);
               continue;

            // NetCharDevQGetInfo
            case VIEW_PRIORITY:
               ViewPriority (pszServer, pszQueue, pszUser);
               continue;

            // NetCharDevQSetInfo
            case CHANGE_PRIORITY:
               ChangePriority (pszServer, pszQueue, usPriority);
               continue;
            // NetCharDevQEnum
            case ENUM_QUEUES:
               EnumerateQueues (pszServer, pszUser);
               continue;

            // NetCharDevEnum
            case LIST_DEVICES:
               EnumerateDevices (pszServer);
               continue;

            // NetCharDevGetInfo
            case STATUS_DEVICE:
               GetDeviceInfo (pszServer, pszDevice);
               continue;

            // Close if currently using port or NetCharDevQPurgeSelf.
            case EXIT:
               StopInactiveJobs( pszServer, pszQueue, pszWksta);
               usRet = DosSemClear(hssmClose);
               printf("DosSemClear returned %hu\n", usRet);
               break;

            default:
               printf("Invalid option: select 1-%c\n", EXIT);
               continue;
         }
         break;
      }
      free (pBuf);
      exit(0);
   }


   // OpenPort spawns a child process that:
   //     -  Opens the com port (using the UNC name)
   //     -  Writes a test message to the port
   //     -  Waits on the \sem\chardev semaphore, then closes the port
   //
   // If the port is being used by another process, the DosOpen function
   // in the child process blocks until the port is freed.
   //
   // Note: You can always use the same semaphore because the DosOpen
   function
   // in the child process blocks if another process currently owns the
   port
   // (that is, only one process can wait on the semaphore at any one
   time).


   BOOL OpenPort (HSYSSEM hssmClose, char * pszShare, char * pszSem)
   {
      char achFailName[PATHLEN];
      RESULTCODES rescResults;
      char pszArgs[PATHLEN];
      char *pszNextArg;
      USHORT usRet;

       /*
        * Set the semaphore to cause the child process to wait after
   printing
        * the first line.
        */
      usRet = DosSemSet(hssmClose);
      printf("DosSemSet returned %hu\n", usRet);

       /*
        * Make up the argument list for the child process:
        *       usecom<NULL>sharename semaphore<NULL><NULL>
        * Make sure there are two null terminators in the argument list.
        */

      strnset (pszArgs, '\0', PATHLEN);

      strcpy (pszArgs, CHILD_PROCESS);
      pszNextArg = pszArgs + strlen(pszArgs) + 1;
      strcpy (pszNextArg, pszShare);
      strcat (pszNextArg, " ");
      strcat (pszNextArg, pszSem);

      usRet = DosExecPgm (achFailName,
                  PATHLEN,
                  EXEC_ASYNC,
                  pszArgs,
                  NULL,
                  &rescResults,
                  CHILD_PROCESS);

      printf ("DosExecPgm returned %hu\n", usRet);
      if (usRet)
         return FALSE;
      return TRUE;
   }

   //========================================================================
   // NetCharDevGetInfo
   //
   // This API finds the status of the ComShare device.
   //========================================================================

   BOOL GetDeviceInfo (char * pszServer, char * pszDev)
   {
      unsigned short cbTotalAvail;
      unsigned uRet;
      struct chardev_info_1 * pCharDevInfo;

       /*
        * The chardev_info_1 structure contains no variable-length data,
   so
        * there's no need to find out how much buffer space is required.
        */

      pCharDevInfo = SafeMalloc(sizeof (struct chardev_info_1));

      uRet = NetCharDevGetInfo(pszServer,               // Servername
                       pszDev,                          // Devicename
                       1,                               // Info level
                       (char far *)pCharDevInfo,        // Buffer
                       sizeof(struct chardev_info_1),   // Size of buffer

                       &cbTotalAvail);

      printf("NetCharDevGetInfo returned %u\n", uRet);

      if (uRet != NERR_Success)
         return FALSE;
      else
      {
         printf ("Status of device %s ",pCharDevInfo->ch1_dev);
         printf ("is %d ", pCharDevInfo->ch1_status);
         if (pCharDevInfo->ch1_status & CHARDEV_STAT_OPENED)
            printf ("(open");
         else
            printf ("(idle");
         if (pCharDevInfo->ch1_status & CHARDEV_STAT_ERROR)
            printf (" and in error");
         printf(")\n\n");
         if (pCharDevInfo->ch1_username[0] != '\0')
            printf ("Username is %s", pCharDevInfo->ch1_username);
         else
            printf ("No current users\n");
      }


      free(pCharDevInfo);
      return TRUE;
   }

   //========================================================================
   // NetCharDevEnum
   //
   // This API displays a list of character devices on the server.
   // Note: The attached devices are available only at info level 1.
   //========================================================================

   BOOL EnumerateDevices (char * pszServer)
   {
      unsigned short cEntriesRead;
      unsigned short cTotalEntries;
      unsigned short cbBuflen;
      unsigned short iCount;
      unsigned uRet;
      struct chardev_info_1 *pBuf, *pB;

      // First, a call to see what size buffer is needed.
      uRet = NetCharDevEnum(pszServer,           // Servername
                              1,                 // Info level
                              NULL,              // No buffer provided
                              0,                 // Size of buffer
                              &cEntriesRead,     // Count of entries
   read
                              &cTotalEntries);   // Count of entries
   available
      cbBuflen = (cTotalEntries + 1) * sizeof(struct chardev_info_1);

      pBuf = (struct chardev_info_1 *) SafeMalloc(cbBuflen);
      pB = pBuf;
      uRet = NetCharDevEnum(pszServer,          // Servername
                             1,                 // Info level
                             (char far *)pBuf,  // Data returned here
                             cbBuflen,          // Size of buffer, in
   bytes
                             &cEntriesRead,     // Count of entries read
                             &cTotalEntries);   // Count of entries available

      printf("NetCharDevEnum returned %u\n", uRet);
      if (uRet != NERR_Success)
      {
         free(pB);
         return FALSE;
      }
      if (cTotalEntries == 0)
         printf("There are no comm devices on this server\n");

      else
      {
         for (iCount = 0; iCount < cEntriesRead; iCount++)
         {
            printf("Device %s: ", pBuf->ch1_dev);
            printf("has status %d\n", pBuf->ch1_status);
            if (pBuf->ch1_status && CHARDEV_STAT_OPENED)
            {
               printf("Open %lu seconds ", pBuf->ch1_time);
               printf("by %s\n", pBuf->ch1_username);
            }
         pBuf++;
         }
      }
      free(pB);
      return TRUE;
   }

   //========================================================================
   // NetCharDevQEnum
   //
   // This API displays a list of character-device queues and the devices

   // they are attached to.
   // Note: The attached devices are available only at info level 1.
   //========================================================================


   BOOL EnumerateQueues (char * pszServer, char far * pszUser)
   {

      unsigned short cEntriesRead;
      unsigned short cTotalEntries;
      unsigned short cbBuflen;
      unsigned short iCount;
      unsigned uRet;
      struct chardevQ_info_1 * pQInfo;
      struct chardevQ_info_1 * pBuf;

      // First, a call to see what size buffer is needed.
      uRet = NetCharDevQEnum(pszServer,          // Servername
                              pszUser,           // Username
                              1,                 // Info level
                              NULL,              // No buffer provided
                              0,                 // Size of buffer
                              &cEntriesRead,     // Count of entries
   read
                              &cTotalEntries);   // Count of entries
   available

      cbBuflen = cTotalEntries * MAX_CHARDEVQ_INFO_1;

      pBuf = SafeMalloc(cbBuflen);          // Remember start of memory
   block
      pQInfo = pBuf;
      uRet = NetCharDevQEnum(pszServer,     // Servername
                        pszUser,            // Username
                        1,                  // Info level
                        (char far *)pQInfo, // Data returned here
                        cbBuflen,           // Size of buffer, in bytes
                        &cEntriesRead,      // Count of entries read
                        &cTotalEntries);    // Count of entries available


      printf("NetCharDevQEnum returned %u\n", uRet);
      if (uRet != NERR_Success)
         return FALSE;
      else
      {
         if (cTotalEntries == 0)
         {
            printf("There are no comm queues on this server\n");
         }
         else
         {
            for (iCount = 0; iCount < cEntriesRead; iCount++)
            {
               printf("\nQueue %s: ",pQInfo->cq1_dev );
               printf("has devices: %Fs\n", pQInfo->cq1_devs );
               printf("%u users, ", pQInfo->cq1_numusers );
               /*
                * If numahead = CHARDEVQ_NO_REQUESTS, user has no jobs

                * in the queue.
                */
               if (pQInfo->cq1_numahead == CHARDEVQ_NO_REQUESTS)
                  printf("user %s has no jobs\n", pszUser);
               else
                  printf("%d users ahead of %s\n",
                          pQInfo->cq1_numahead, pszUser);
            pQInfo++;
            }
         }
      }
      free(pBuf);
      return TRUE;
   }

   //========================================================================
   // NetCharDevQGetInfo
   //
   // This API views the queue priority.
   //========================================================================

   BOOL ViewPriority (char *pszServer, char *pszQ, char far *pszUser)
   {
      struct chardevQ_info_1 *pBuf;
      unsigned short cbTotalAvail;
      unsigned short cbBuflen = sizeof( struct chardevQ_info_1) + 256;
      unsigned uRet;

      pBuf = (struct chardevQ_info_1 *) SafeMalloc (cbBuflen);
      uRet = NetCharDevQGetInfo(pszServer,   // Servername
                        pszQ,                // Queuename
                        pszUser,             // Username
                        1,                   // Info level
                        (char far *)pBuf,    // Buffer
                        cbBuflen,            // Size of buffer
                        &cbTotalAvail);      // Count of bytes available
      printf("NetCharDevQGetInfo returned %u\n", uRet);

      if (uRet == NERR_Success)
      {
         printf ("Queue %s ", pBuf->cq1_dev);
         printf ("has priority %d\n", pBuf->cq1_priority);
         printf ("Devices = %s\n", pBuf->cq1_devs);
         printf ("Number of users in queue = %d\n", pBuf->cq1_numusers);
         printf ("Number ahead of %s ", pszUser);
         printf ("= %d\n", pBuf->cq1_numahead);
      }
      free(pBuf);
      return TRUE; }

   //========================================================================
   // NetCharDevQSetInfo
   //
   // This API changes the queue priority from the default (5).
   //========================================================================

   BOOL ChangePriority (char * pszSrv, char * pszQ, unsigned short usPrty
   )
   {

      unsigned uRet;


      /*
       * There are two ways to call NetCharDevQSetInfo.
       * If sParmNum == PARMNUM_ALL, you must pass it a whole structure.
       * Otherwise, you can set sParmNum to the element of the structure

       * you want to change. Only the latter method is shown here.
       */

      uRet = NetCharDevQSetInfo(pszSrv,              // Servername
                        pszQ,                        // Queuename
                        1,                           // Info level
                        (char far *)&usPrty,         // Buffer
                        sizeof (usPrty),             // Size of buffer

                        CHARDEVQ_PRIORITY_PARMNUM);  // Parameter code
   number
      printf("NetCharDevQSetInfo returned %u\n", uRet);

      if (uRet != NERR_Success)
         return FALSE;
      else
         printf ("Priority for queue changed to %d\n", usPrty);
      return TRUE;
   }

   //========================================================================
   // NetCharDevQPurgeSelf
   //
   // This API removes its own jobs from the queue. It removes only
   // jobs that have not started printing.
   //========================================================================

   BOOL StopInactiveJobs (char *pszServer, char *pszQ, char far *pszComputer)
   {
      unsigned uRet;
      uRet = NetCharDevQPurgeSelf (pszServer,     // Servername
                                    pszQ,         // Queuename
                                    pszComputer); // Workstation name

      printf("NetCharDevQPurgeSelf returned %u\n", uRet);
      switch (uRet)
      {
         case NERR_Success:
            break;
         case NERR_ItemNotFound:
            printf ("There are no jobs in the queue\n");
            break;
         default:
            return FALSE;
      }
      return TRUE;

   }

   void DisplayPrompt(void)
   {
      printf("\n\nCharacter Device Category API Examples\n\n");
      printf("%c. Start job: DosExecPgm DosOpen comm device\n",
                                                          START_JOB);
      printf("%c. Device status: NetCharDevGetInfo\n",
                                                          STATUS_DEVICE);
      printf("%c. List all devices: NetCharDevEnum\n",
                                                          LIST_DEVICES);
      printf("%c. List all queues: NetCharDevQEnum\n",
                                                          ENUM_QUEUES);
      printf("%c. View queue: NetCharDevQGetInfo\n",
                                                          VIEW_PRIORITY);
      printf("%c. Change priority: NetCharDevQSetInfo\n",
                                                          CHANGE_PRIORITY);
      printf("%c. Close device, kill job: NetCharDevControl\n",
                                                          KILL_ACTIVE_JOB);
      printf("%c. Stop all jobs: NetCharDevQPurgeSelf\n",
                                                          PURGE_OWN_JOBS);
      printf("%c. Purge queue: NetCharDevQPurge\n",
                                                          PURGE_QUEUE);
      printf("%c. Exit\n",
                                                          EXIT);
      printf("Enter selection:  ");
   }

   // Return the next character typed from the keyboard.
   char GetNextAction ()
   {
      return ((char)getche());
   }

   void Usage(char *pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-q queue]", pszString);
      fprintf(stderr, " [-u username]\n");
      fprintf(stderr, "\t[-w wksta] [-d device] [-p priority]\n");
      exit(1);
   }

   /*
      NETCHAR2.C -- a sample program demonstrating NetCharDev API functions.
                    This program should only be executed from NETCHAR1.C.

      This program attempts to open the comm device using the UNC name.
      Note: If the device has already been opened by another process,
      DosOpen blocks until the device is freed.

      Once the port is open, a sentence is written out and the process
   waits
      on a semaphore to be told to close the port.

         usage: netchar2 \\server\share semaphore

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define CALLING_PROGRAM  "netchar1"
   #define STRING1          "A test message\r\n"
   #define STRING1LEN       strlen(STRING1)
   #define STRING2          "Closing statement\r\n"
   #define STRING2LEN       strlen(STRING2)

   #define     INCL_BASE
   #include    <os2.h>        // MS OS/2 base header files

   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header file
   #include    <stdlib.h>
   #include    <string.h>

   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      HFILE   fh;
      USHORT  usAction;
      unsigned short usRet;
      USHORT   cbWritten;
      HSYSSEM  hssmClose;

      if (argc != 3)
         Usage(CALLING_PROGRAM);


      // Open the semaphore this thread waits for.
      if (DosOpenSem(&hssmClose, argv[2]) != 0)
         exit(1);

      /*
       * The first process to open gets a file handle immediately;
       * all subsequent processes are suspended until the device
       * is freed (that is, until the current owner closes the device).
       */
      usRet = DosOpen (argv[1],
                  &fh,
                  &usAction,
                  0L,   // No file length, since this is a com port
                  0,    // No action specified since we aren't creating
                  FILE_OPEN,
                  OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE,
                  0L    // Reserved
                );

      if (usRet != NERR_Success)
         exit(1);

      DosWrite(fh, STRING1, STRING1LEN, &cbWritten);

      // Wait to be told to close or for 30 seconds (whichever comes
   first).
      usRet = DosSemWait(hssmClose, 30000L);
      if (usRet != ERROR_SEM_TIMEOUT)
      {
         printf("\nQueue was forced closed, DosSemWait returned %hu\n",
                   usRet);
         exit(1);
      }

      DosWrite(fh, STRING2, STRING2LEN, &cbWritten);

      /*
       * Close the device using DosClose instead of NetCharDevControl.

       * The NetCharDevControl function is designed for administrators

       * when they need to force the device closed.
       */

      DosClose(fh);
      exit(0);
   }

   void Usage(char *pszString)
   {
      fprintf(stderr, "This program should not be called directly.\n");
      fprintf(stderr, "Usage: %s [-s \\\\server] [-q queue]", pszString);
      fprintf(stderr, " [-u username]\n");
      fprintf(stderr, "\t[-w wksta] [-d device] [-p priority]\n");
      exit(1);
   }





 Configuration Category

 Configuration API functions retrieve network configuration information from
 the LANMAN.INI file. When executed on the local computer, Configuration API
 functions require that the NETWKSTA device driver be installed. When
 executed on a remote server, they require that the local Workstation service
 be started.

 The Configuration category functions, datatypes, structures, and constants
 are defined in the NETCONS.H, NETERR.H, and CONFIG.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETCONFIG, and including the master header file,
 LAN.H. For more information about these definitions, see the "Example"
 section, later in this category.

 These are the Configuration API functions:


   þ   NetConfigGet2

   þ   NetConfigGetAll2



 Description

 NetConfigGet2 retrieves a single entry value from the LANMAN.INI file on the
 local computer or on a remote server.

 NetConfigGetAll2 retrieves the value of the entries for a given component
 from the LANMAN.INI file on the local computer or on a remote server.

 The LANMAN.INI file is an ASCII file that contains configuration information
 for LAN Manager services, as well as network configuration information for
 user-defined services and applications. It consists of component lines,
 entry lines, and comment lines, in the following format:


   þ   Component lines mark the start of a set of information, in this form:

       [component name]

   þ   Entry lines contain a parameter and a value, in this form:

       entry = value

       The entry value can consist of any text. Configuration API functions
       do not process the text, although they do remove leading and trailing
       spaces. Interpretation of the value is left to the caller.

       If an entry appears several times in a single component,
       NetConfigGetAll2 returns each instance; NetConfigGet2 returns only the
       first instance. Using the same entry name in different components does
       not affect the data returned by NetConfigGet2.

   þ   Comment lines are any blank lines or lines that have a semicolon (;)
       as the first nonblank character.


 For example, a LANMAN.INI [workstation] component might contain the
 following information:

   [workstation]
       ; define net_tools workstation
       computername = NET_TOOLS
       charcount = 16
       chartime = 250
       charwait = 3600
       domain = LAN

 The LANMAN.INI file contains default values for network parameters. These
 values are not necessarily the current values for those parameters. For
 example, in the preceding example, the computername component is set to
 NET_TOOLS, but the workstation does not necessarily have that name. A
 different name could be specified from the command line when the Workstation
 service is started. Use NetWkstaGetInfo to retrieve the current value of
 parameters in the [workstation] component; use NetServerGetInfo to retrieve
 the current values for the [server] component.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 LANMAN.INI file                   LAN Manager administrator's manual(s)


 NetConfigGet2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetConfigGet2 retrieves the value of a single specified entry for a
 particular component of the LANMAN.INI file on the local computer or on a
 remote server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege or accounts, comm, print, or server operator privilege is
 required to successfully execute NetConfigGet2 on a remote server.


 Syntax

   #define INCL_NETCONFIG
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetConfigGet2 (const char far *      pszServer,
                  const char far *      pszReserved,
                  const char far *      pszComponent,
                  const char far *      pszParameter,
                  const char far *      pbBuffer,
                  unsigned short        cbBuffer,
                  unsigned short far *  pcbParmlen
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetConfigGet2. A null pointer or null string specifies the
   local computer.

 pszReserved
   Reserved; must be a null pointer.

 pszComponent
   Points to an ASCIIZ string that specifies which LANMAN.INI component to
   search.

 pszParameter
   Points to an ASCIIZ string that specifies the entry whose value is to be
   returned.

 pbBuffer
   Points to the buffer where the value of the entry is to be returned.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbParmlen
   Points to an unsigned short integer in which the size of the entry value
   (in bytes) is returned. This count is valid only if NetConfigGet2 returns
   NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_FILE_NOT_FOUND              2       The file was not found.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_CfgCompNotFound              2146    The specified component in the
                                           LANMAN.INI file is not found.

 NERR_CfgParamNotFound             2147    The specified parameter in the
                                           LANMAN.INI file is not found.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetConfigGet2 returns the entry value of the specified LANMAN.INI component
 as an ASCIIZ string in the buffer pointed to by pbBuffer. This string
 consists of all text to the right of the equal sign (=) in the LANMAN.INI
 entry. NetConfigGet2 removes leading and trailing spaces, but performs no
 other processing on the text.

 For example, the LANMAN.INI entry

   "    sky  =  blue,1,long comment string    "

 is returned as the following string:

   "blue,1,long comment string"

 The value of cbBuffer must be at least 1 larger than the value returned in
 pcbParmlen; this is necessary to provide for the NUL at the end of the
 ASCIIZ string.

 NetConfigGet2 supersedes NetConfigGet (used in earlier versions of LAN
 Manager). These functions are the same except that NetConfigGet2 has the
 pszServer parameter, which enables it to be called remotely. For more
 information, see Appendix B, "Upgrading LAN Manager 1.0 Applications."

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 LANMAN.INI file                   LAN Manager administrator's manual(s)


 NetConfigGetAll2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetConfigGetAll2 retrieves all the configuration information for a given
 component in the LANMAN.INI file on a local or a remote computer.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege or account, comm, print, or server operator privilege is
 required to successfully execute NetConfigGetAll2 on a remote server.


 Syntax

   #define INCL_NETCONFIG
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetConfigGetAll2 (const char far *      pszServer,
                     const char far *      pszReserved,
                     const char far *      pszComponent,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcbReturned,
                     unsigned short far *  pcbTotalAvail
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetConfigGetAll2. A null pointer or null string specifies the
   local computer.

 pszReserved
   Reserved; must be a null pointer.

 pszComponent
   Points to an ASCIIZ string that specifies which LANMAN.INI component to
   search.

 pbBuffer
   Points to the buffer where the entry values are to be returned.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbReturned
   Points to an unsigned short integer in which the number of bytes returned
   in the buffer pointed to by pbBuffer is returned.

 pcbTotalAvail
   Points to an unsigned short integer in which the number of bytes of data
   available is returned. This count is valid only if NetConfigGetAll2
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_FILE_NOT_FOUND              2       The file was not found.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_CfgCompNotFound              2146    The specified component in the
                                           LANMAN.INI file is not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetConfigGetAll2 returns a set of concatenated ASCIIZ strings in the buffer
 pointed to by pbBuffer, representing configuration information for the
 specified component. Each string is terminated by a NUL, and the whole
 buffer is terminated by a null string. NetConfigGetAll2 removes leading and
 trailing spaces, but performs no other processing on the text. Information
 is returned in the form ENTRY=value. The entry name (left of the equal sign)
 is converted to uppercase.

 For example, the LANMAN.INI entry

   "   sky  =  blue, 1, long comment string   "
   "    ground  =  brown, 2"

 is returned as these two consecutive strings:

   "SKY=blue, 1, long comment string"
   "GROUND=brown, 2"

 NetConfigGetAll2 supersedes NetConfigGetAll (used in earlier versions of LAN
 Manager). These functions are the same except that NetConfigGetAll2 has the
 pszServer parameter, which enables it to be called remotely. For more
 information, see Appendix B, "Upgrading LAN Manager 1.0 Applications."

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 LANMAN.INI file                   LAN Manager administrator's manual(s)





 Configuration Category Example

   /*
      NETCNFG.C -- a sample program demonstrating NetConfig API functions.

      This program requires that you have admin privilege or any
      type of operator privilege on the specified server.

         usage:  netcnfg [-s \\server] [-p parameter] [-c component]

         where  \\server  = Name of the server. A servername must be
                            preceded by two backslashes (\\).
                parameter = Name of the LANMAN.INI parameter to get.
                component = Name of the component from which the
                            parameter is to be retrieved.

      API                  Used to...
      ================     ===========================================
      NetConfigGet2        Retrieve a parameter in the LANMAN.INI file
                           on the specified server
      NetConfigGetAll2     Retrieve complete component info from the
                           specified LANMAN.INI file

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETCONFIG
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   #define DEFAULT_COMPONENT  "Workstation"
   #define DEFAULT_PARAMETER  "Domain"
   #define SMALL_BUFF         64
   #define BIG_BUFF           4096

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *pszServer = "";                     // Servername
      char *pszComponent  = DEFAULT_COMPONENT;  // Component to list
      char *pszParameter  = DEFAULT_PARAMETER;  // Parameter within component
      char *pszBuffer, *p;                      // String pointers
      int            iCount;                    // Index counter
      unsigned short cbBuffer;                  // Count of bytes in
   buffer
      unsigned short cbParmlen;                 // Length of returned
   parameter
      unsigned short cbRead;                    // Count of bytes read
      unsigned short cbAvail;                   // Count of bytes available
      API_RET_TYPE   uReturnCode;               // API return code

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'c':                        // -c component
                  pszComponent = argv[++iCount];
                  break;
               case 'p':                        // -p parameter
                  pszParameter = argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetConfigGet2
   //
   //  This API retrieves a single entry from the LANMAN.INI file on
   a
   //  specified server. If no servername is given, the local LANMAN.INI
   //  file is used. When executed remotely, the user must have admin
   //  privilege or at least one operator privilege on the remote server.
   //========================================================================
      cbBuffer = SMALL_BUFF;
      pszBuffer = SafeMalloc(cbBuffer);

      uReturnCode = NetConfigGet2(
                              pszServer,     // Servername
                              NULL,          // Reserved; must be NULL
                              pszComponent,  // Component in LANMAN.INI
                              pszParameter,  // Parameter in component
                              pszBuffer,     // Pointer to return buffer
                              cbBuffer,      // Size of buffer
                              &cbParmlen);   // Length of returned parameter

      printf("NetConfigGet2 returned %u \n", uReturnCode);

      if (uReturnCode == NERR_Success)
         printf("   %s = %s\n\n", pszParameter, pszBuffer);
      else if (uReturnCode == NERR_BufTooSmall)
         printf("   %hu bytes were provided, but %hu bytes were needed\n\n",
               cbBuffer, cbParmlen);
      free(pszBuffer);

   //========================================================================
   //  NetConfigGetAll2
   //
   //  This API returns information for an entire LANMAN.INI component

   //  such as [networks] or [workstation]. The returned information
   is a
   //  sequence of null-terminated strings followed by a null string.
   //========================================================================

      cbBuffer = BIG_BUFF;
      pszBuffer = SafeMalloc(cbBuffer);

      uReturnCode = NetConfigGetAll2(
                              pszServer,     // Name of remote server
                              NULL,          // Reserved; must be NULL
                              pszComponent,  // Component of LANMAN.INI
                              pszBuffer,     // Pointer to return buffer
                              cbBuffer,      // Size of buffer
                              &cbRead,       // Count of bytes read
                              &cbAvail);     // Count of bytes available


   printf("NetConfigGetAll2 returned %u \n", uReturnCode);

      switch(uReturnCode)
      {
         case NERR_Success:                  // It worked
            p = pszBuffer;
            while (*p)                       // While not at null string
            {
               printf("   %s\n", p);         // Print string
               p += (strlen(p) + 1);         // Step past trailing NUL
            }
            break;
         case ERROR_BAD_NETPATH:
            printf("   Server %s not found.\n", pszServer);
            break;
         case NERR_InvalidAPI:
            printf("   The remote server %s does not support this API.\n",
                    pszServer);
            break;
         default:
            break;
      }
      free(pszBuffer);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-c component]" \
                      " [-p parameter]\n", pszProgram);
      exit(1);
   }





 Connection Category

 The Connection API function, NetConnectionEnum, lists server connections.
 When a remote server is specified, NetConnectionEnum requires that the
 Workstation service be started on the local computer and that the Server
 service be started on the specified server.

 The Connection category function, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETCONNECTION, and including the master header file,
 LAN.H. For more information about these definitions, see the "Example"
 section, later in this category.


 Description

 A computer accesses a shared resource on a server by means of a connection.
 A connection is a software link between a computer and a server, made by
 assigning a local or null devicename to the shared resource on the server.
 The NetUseAdd function establishes connections.

 NetConnectionEnum lists information about all connections to a server made
 by a specified computer, or about all connections made to a specified
 sharename.


 Data Structures

 NetConnectionEnum returns data at a detail level of 0 or 1, using the
 connection_info_0 and connection_info_1 data structures.


 Connection Information (level 0)

 The connection_info_0 data structure has this format:

   struct connection_info_0 {
       unsigned short  coni0_id;
   };

 where

 coni0_id
   Specifies the connection identification number.


 Connection Information (level 1)

 The connection_info_1 data structure has this format:

   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;
   };

 where

 coni1_id
   Specifies the connection identification number.

 coni1_type
   Specifies the type of connection made from the local computer to the
   shared resource. The SHARES.H header file defines these possible
   connections:

 Code            Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 STYPE_DISKTREE  0      Disk connection.
 STYPE_PRINTQ    1      Printer queue connection.
 STYPE_DEVICE    2      Communication-device connection.
 STYPE_IPC       3      Interprocess communication (IPC) connection.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 coni1_num_opens
   Specifies the number of resources (files, pipes, or devices) open as a
   result of the connection.

 coni1_num_users
   Specifies the number of connected users.

 coni1_time
   Specifies the number of seconds the connection has been established.

 coni1_username
   Points to an ASCIIZ string. On a server that has user-level security, the
   string contains the name of the user who established the connection. On a
   server that has share-level security, the string contains the name of the
   computer that established the connection.

 coni1_netname
   Points to an ASCIIZ string that contains the sharename or a computername.
   This value is the inverse of the NetConnectionEnum pszQualifier parameter:
   when pszQualifier is a sharename, coni1_netname is a computername; when
   pszQualifier is a computername, coni1_netname is a sharename.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Connecting to a shared resource   NetUseAdd
 on a server


 NetConnectionEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetConnectionEnum lists all connections made to a shared resource on the
 server or all connections established from a particular computer.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server, print, or comm operator privilege is required to
 successfully execute NetConnectionEnum on a remote server or on a computer
 that has local security enabled.


 Syntax

   #define INCL_NETCONNECTION
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetConnectionEnum (const char far *      pszServer,
                      const char far *      pszQualifier,
                      short                 sLevel,
                      char far *            pbBuffer,
                      unsigned short        cbBuffer,
                      unsigned short far *  pcEntriesRead,
                      unsigned short far *  pcTotalEntries
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetConnectionEnum. A null pointer or null string specifies the
   local computer.

 pszQualifier
   Points to an ASCIIZ string that specifies either a sharename or a
   computername. If pszQualifier is a sharename, NetConnectionEnum lists all
   connections made to that sharename. If pszQualifier is a computername,
   NetConnectionEnum lists all connections made from that computer to the
   server specified by pszServer. This parameter cannot be a null pointer or
   null string. When pszQualifier represents a computername, it must start
   with two backslash characters (\\).

 sLevel
   Specifies the level of detail (0 or 1) to be returned in the buffer
   pointed to by pbBuffer.

 pbBuffer
   Points to the buffer for data returned by NetConnectionEnum. On a
   successful return, the buffer contains connection_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the return buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer that specifies the number of entries
   in the return buffer pointed to by pbBuffer. This count is valid only if
   NetConnectionEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalEntries
   Points to an unsigned short integer that specifies the total number of
   entries available. This count is valid only if NetConnectionEnum returns
   NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NetNameNotFound              2310    The sharename does not exist.

 NERR_ClientNameNotFound           2312    The specified computer does not
                                           have a session with the server.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all available servers     NetServerEnum

 Listing sessions on a server      NetSessionEnum





 Connection Category Example

   /*
      NETCONS.C -- a sample program demonstrating NetConnectionEnum.

      This program requires that you have admin privilege on the specified
      server.

         usage:  netcons [-s \\server] [-r sharename | -w \\wkstaname]

         where  \\server    = Name of the server. A servername must
   be
                              preceded by two backslashes (\\).
                sharename   = Name of the shared resource as qualifier.
                \\wkstaname = Computername used as qualifier.

      API                   Used to...
      =================     ==========================================
      NetConnectionEnum     List connections to a server's shared
                            resources, or list connections established

                            from a particular computer

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.

   */

   #define     INCL_NETERRORS
   #define     INCL_NETCONNECTION
   #define     INCL_NETSHARE
   #include    <lan.h>                     // LAN Manager header files

   #include    <stdio.h>                   // C run-time header files
   #include    <stdlib.h>

   #include    "samples.h"                 // Internal routine header
   file

   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      char *pszServerName = "";     // Can be null; default to local
   machine
      char *pszQualifier = "C$";    // Cannot be null; default to shared
   drive
      unsigned uRet;                // API return code
      unsigned short  cbBuflen;     // Buffer length
      unsigned short  cEntriesRead; // Count of entries read
      unsigned short  cTotAvail;    // Count of entries available

      unsigned short  fSetQualifier = 0;  // Flag; set qualifier only
   once
      int             iCount;             // Index; loop counter
      struct connection_info_1 *pBuf1, *p1;

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServerName = argv[++iCount];
                  break;
               case 'w':                        // -w workstation
                  if (fSetQualifier == 1)
                     Usage(argv[0]);            // Exit program
                  fSetQualifier = 1;
                  pszQualifier = argv[++iCount];
                  break;
               case 'r':                        // -r sharename
                  if (fSetQualifier == 1)
                     Usage(argv[0]);            // Exit program
                  fSetQualifier = 1;
                  pszQualifier = argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);               // Exit program
            }
         }
         else
            Usage(argv[0]);
      }
      printf("\nConnection Category API Example\n\n");

      // Initial call to determine how large a return buffer is needed.

      uRet = NetConnectionEnum(pszServerName,   // Servername
                                pszQualifier,   // Qualifier
                                1,              // Reporting level (0
   or 1)
                                NULL,           // Return buffer
                                0,              // Size of target buffer
                                &cEntriesRead,  // Count of entries read
                                &cTotAvail);    // Count of entries available




      if ((uRet != NERR_Success) && (uRet != ERROR_MORE_DATA))
      {
         printf("NetConnectionEnum returned %u\n", uRet);
         exit(1);
      }

      if (cTotAvail == 0)
      {
         printf("No connections with %s\n", pszQualifier);
         exit(0);
      }

      // Each structure contains strings UNLEN+1 and NNLEN+1 long.
      cbBuflen = cTotAvail *
                  (sizeof (struct connection_info_1) + UNLEN + NNLEN
   + 2);
      pBuf1 = (struct connection_info_1 *) SafeMalloc(cbBuflen);
      p1 = pBuf1;         // Save start of memory block for cleanup

      uRet = NetConnectionEnum(pszServerName,     // Servername
                               pszQualifier,      // Qualifier
                               1,                 // Reporting level
   (0 or 1)
                               (char far *)pBuf1, // Target buffer for
   info
                               cbBuflen,          // Size of target buffer
                               &cEntriesRead,     // Count of entries
   read
                               &cTotAvail);       // Count of entries
   available

      printf("NetConnectionEnum returned %u \n", uRet);


      if (uRet != NERR_Success)
         exit(1);             // Exit if error occurred

      for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
      {
         printf("Connection id number %hu\n", pBuf1->coni1_id);
         printf(" connection type          :  %hu  ", pBuf1->coni1_type);
         switch (pBuf1->coni1_type)
         {
            case STYPE_DISKTREE:
               printf("Disk Connection\n");
               break;
            case STYPE_PRINTQ:
               printf("Printer Queue Connection\n");
               break;
            case STYPE_DEVICE:
               printf("Character Device Connection\n");
               break;

             case STYPE_IPC:
               printf("IPC Connection\n");
               break;
             default:
               printf("Unknown Connection Type\n");
               break;
         }
         printf(" open files on connection :  %hu\n",
 pBuf1->coni1_num_opens);
         printf(" users on connection      :  %hu\n",
 pBuf1->coni1_num_users);
         printf(" seconds since established:  %lu\n", pBuf1->coni1_time);

         /*
          * Print the name of the user or computer that made the connection.
          * If server has share-level security, the name is a username.
          * If server has user-level security, the name is a computername.
          */

         printf(" connection user name     :  %s\n", pBuf1->coni1_username);

         /*
          * Print the network name, the inverse of the qualifier.
          * If qualifier is a sharename, netname is a computername.
          * If qualifier is a computername, netname is a username.
          */

         printf(" connection network name  :  %s\n", pBuf1->coni1_netname);

         pBuf1++;                          // Increment the record pointer
      }
      printf("%hu out of %hu entries read\n", cEntriesRead, cTotAvail);

      free(p1);
      exit(0);
   }

   void Usage(char *pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server]", pszString);
      fprintf(stderr, " [-r sharename | -w \\\\wkstaname]\n");
      exit(1);
   }







 Domain Category

 Domain API functions retrieve information about a domain. They require that
 the Workstation service be started. NetLogonEnum also requires that the
 Netlogon service be started on the specified server.

 The Domain category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and ACCESS.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETDOMAIN, and including the master header file,
 LAN.H. For more information about these definitions,  see the "Example"
 section, later in this category.

 These are the Domain API functions:


   þ   NetGetDCName

   þ   NetLogonEnum



 Description

 NetGetDCName retrieves the name of the domain controller. NetLogonEnum
 retrieves information about the users who are logged on in a domain.


 Data Structures

 NetGetDCName returns the domain name in the form of an ASCIIZ string.
 NetLogonEnum uses the user_logon_info_X data structure, where X is 0 or 2,
 depending on the level of detail specified.


 Logon Information (Level 0)

 The user_logon_info_0 data structure has this format:

   struct user_logon_info_0 {
      char  usrlog0_eff_name[UNLEN+1];
      char  usrlog0_pad_1;
   };

 where

 usrlog0_eff_name
   Specifies the name of the user. The constant UNLEN is defined in the
   NETCONS.H header file.

 usrlog0_pad_1
   Aligns the next data structure element on a word boundary.


 Logon Information (Level 2)

 The user_logon_info_2 data structure has this format:

   struct user_logon_info_2 {
       char           usrlog2_eff_name[UNLEN+1];
       char           usrlog2_pad_1;
       char far *     usrlog2_computer;
       char far *     usrlog2_full_name;
       char far *     usrlog2_usrcomment;
       unsigned long  usrlog2_logon_time;
   };

 where

 usrlog2_eff_name
   Specifies the name of the user. The constant UNLEN is defined in the
   NETCONS.H header file.

 usrlog2_pad_1
   Aligns the next data structure element on a word boundary.

 usrlog2_computer
   Points to an ASCIIZ string that contains the name of the computer where
   the user logged on.

 usrlog2_full_name
   Points to an ASCIIZ string that contains the full name of the user.

 usrlog2_usrcomment
   Points to the ASCIIZ string that contains the user's comment.

 usrlog2_logon_time
   Specifies the time the user logged on to the network. This value is stored
   as the number of seconds elapsed since 00:00:00, January 1, 1970. A value
   of -1 indicates that the logon time is not available.


 NetGetDCName
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGetDCName returns the name of a domain controller for a specified domain.
 If no domain name or servername is supplied, NetGetDCName returns the name
 of the domain controller for the local workstation's primary domain.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 No special privilege level is required to successfully execute NetGetDCName.



 Syntax

   #define INCL_NETDOMAIN
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGetDCName (const char far *  pszServer,
                 const char far *  pszDomain,
                 char far *        pbBuffer,
                 unsigned short    cbBuffer
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGetDCName. A null pointer or null string specifies the local
   computer.

 pszDomain
   Points to an ASCIIZ string that contains the name of the domain. A null
   pointer or null string indicates that the name of the domain controller
   for the primary domain is to be returned.

 pbBuffer
   Points to the buffer in which to return the name of the domain controller.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                    Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success            0       The function encountered no errors.

 ERROR_ACCESS_DENIED     5       The user has insufficient privilege for
                                 this operation.

 ERROR_BAD_NETPATH       53      The network path was not found.

 NERR_NetNotStarted      2102    The LAN Manager NETWKSTA driver is not
 Code                    Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetNotStarted      2102    The LAN Manager NETWKSTA driver is not
                                 installed.

 NERR_BufTooSmall        2123    The supplied buffer is too small.

 NERR_WkstaNotStarted    2138    The Workstation service is not started.

 NERR_BadTransactConfig  2141    The server is not configured for this
                                 transaction: IPC$ is not shared.

 NERR_InvalidAPI         2142    The requested API is not supported on the
                                 remote server.

 NERR_InvalidComputer    2351    The specified computername is invalid.

 NERR_DCNotFound         2453    The domain controller for this domain was
                                 not found.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                    Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If the return code is NERR_Success, the buffer contains an ASCIIZ string
 that contains the name of the domain controller in UNC format, for example:


   \\SERVER

 NetGetDCName can require a large amount of network time and can affect the
 performance of applications that call it often. Because the domain
 controller of a domain can change, you should not assume that the domain
 controller remains unchanged for long periods. Applications that require the
 name of the domain controller should call NetGetDCName when necessary,
 unless performance tests indicate that these calls cause poor performance.
 You can assume only that the domain controller remains unchanged for short
 periods.


 NetLogonEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetLogonEnum supplies information about users who are logged on in a domain.



 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute NetLogonEnum.



 Syntax

   #define INCL_NETDOMAIN
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetLogonEnum (const char far *      pszServer,
                 short                 sLevel,
                 char far *            pbBuffer,
                 unsigned short        cbBuffer,
                 unsigned short far *  pcEntriesRead,
                 unsigned short far *  pcTotalAvail
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetLogonEnum. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail (0 or 2) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of user_logon_info_X data
   structures, where X is 0 or 2, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of
   users listed in the buffer is returned. This count is valid only if
   NetLogonEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of logon data structures available is returned. This count is valid only
   if NetLogonEnum returns NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.


 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_NetlogonNotStarted           2455    The Netlogon service is not
                                           running.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetLogonEnumcan return more than one entry for a particular username, if
 that user is logged on at more than one workstation.



 Domain Category Example

   /*
      NETDOM.C -- a sample program demonstrating the Domain API functions.

      This program requires that the Netlogon service be started on
      the specified server.

         usage:  netdom [-s \\server] [-d domain]

         where  \\server = Name of the server. A servername must
   be preceded
                           by two backslashes (\\).
                domain   = Name of the domain.

      API              Used to...
      ============     ================================================
      NetGetDCName     Find the domain controller for a given domain
      NetLogonEnum     Get details about users at the domain controller

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETDOMAIN
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>
   #include    <time.h>

   #include    "samples.h"    // Internal routine header file

   #define     BIG_BUFF       32768

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pszServer = "";            // Servername
      char *         pszDomain = "";            // Domain name
      char           pszDCName[UNCLEN+1];       // Name of domain controller
      int            iCount;                    // Index counter
      unsigned short cRead;                     // Count of entries read
      unsigned short cAvail;                    // Count of entries available
      unsigned short cbBuffer;                  // Size of buffer, in
   bytes
      API_RET_TYPE   uReturnCode;               // API return code
      struct user_logon_info_2 *pBuffer;        // Data buffer

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'd':                        // -d domain
                  pszDomain = argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetGetDCName
   //
   //  This API returns the name of the server that is the domain
   //  controller in the specified domain. If no domain name is given,
   //  the name of the primary domain controller is returned.
   //========================================================================

      cbBuffer = sizeof(pszDCName);
      uReturnCode = NetGetDCName(pszServer,     // Server; NULL means
   local
                                 pszDomain,     // Domain; NULL means
   primary
                                 pszDCName,     // Return buffer
                                 cbBuffer);     // Size of buffer

      printf("NetGetDCName returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
         printf("   the domain controller is %s\n", pszDCName);
      else if (uReturnCode == NERR_DCNotFound)
      {
         printf("   domain controller not found\n");
      }

   //========================================================================
   //  NetLogonEnum
   //
   //  This API lists the logon names, logon times, and machines the
   users
   //  logged on from.
   //
   //  Note: In the printf() statement, the computername is pointed to
   by
   //  a far pointer and so is formatted with %Fs. NetLogonEnum will
   NOT list
   //  all the users logged on in a domain. It lists only those users
   logged
   //  on to the specified server.
   //========================================================================

      cbBuffer = BIG_BUFF;                      // Can be up to 64K
      pBuffer = (struct user_logon_info_2 *) SafeMalloc(cbBuffer);

      uReturnCode = NetLogonEnum(pszDCName,     // Servername
                          2,                    // Level (0 or 2)
                          (char far *)pBuffer,  // Data returned here
                          cbBuffer,             // Size of supplied buffer
                          &cRead,               // Count of entries read
                          &cAvail);             // Count of entries available

      printf("NetLogonEnum for \"%s\" returned %u\n",
                     pszDCName, uReturnCode);

      if (uReturnCode == NERR_Success || uReturnCode == ERROR_MORE_DATA)
      {
         putenv("TZ=GMT0");         // Allow ctime() to report local
   time
         for (iCount = 0; iCount < (int) cRead; iCount++)
         {
            printf(" %15s on machine %-15Fs  Logon: %s",
                        pBuffer->usrlog2_eff_name,
                        pBuffer->usrlog2_computer,
                        ctime(&pBuffer->usrlog2_logon_time));
            pBuffer++;
         }
         printf("%hu out of %hu entries returned\n", cRead, cAvail);
      }
      free(pBuffer);
      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-d domain]\n", pszProgram);
      exit(1);
   }





 Error Logging Category

 Error Logging API functions control the error log. All Error Logging API
 functions require that the NETWKSTA device driver be installed.
 NetErrorLogWrite also requires that the Workstation service be started.

 The Error Logging category functions, datatypes, structures, and constants
 are defined in the NETCONS.H, NETERR.H, and ERRLOG.H header files. A source
 program  can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETERRORLOG, and including the master header file,
 LAN.H. For more information about these definitions, see the "Example"
 section, later in this category.

 These are the Error Logging API functions:


   þ   NetErrorLogClear

   þ   NetErrorLogRead

   þ   NetErrorLogWrite



 Description

 The error log is a file that stores error messages (in binary format). It
 contains information about LAN Manager software internal errors, MS OS/2 and
 MS-DOS internal errors, and network service errors.

 The default error log is NET.ERR in the LAN Manager LOGS directory. All
 Error Logging functions operate on this file.

 NetErrorLogWrite writes an entry to the error log; NetErrorLogRead reads
 entries from the error log; and NetErrorLogClear clears the error log and,
 optionally, saves the entries in a backup file.

 To set a maximum size for the error log, use one of these methods:


   þ   Use the net config command with the /maxerrorlog option. For more
       information, see your LAN Manager user's manual(s).

   þ   Set the maxerrorlog entry in the [workstation] section of the
       LANMAN.INI file. For a description of the LANMAN.INI file, see your
       LAN Manager administrator's manual(s).

   þ   Call the NetWkstaSetInfo function with the sParmNum parameter set to
       WKSTA_ERRLOGSZ_PARMNUM.



 Data Structure

 NetErrorLogRead and NetErrorLogWrite use the error_log data structure to
 read entries from and write entries to the error log. An entry consists of a
 fixed-length data structure. The data structure can be followed by ASCIIZ
 strings (el_text) that describe the error message, and a block of raw data
 (el_data) related to the cause of the error. Because of the variable lengths
 and structures of the el_data and el_text portions of the entry, only the
 fixed-length data structure is defined in the error_log data structure.

 The error log entry has the following format:

   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;
   };

   /*
    *   Variable-length data specific to the error. The
    *   data consists of message strings and raw data.
    *   The number of bytes of data is equivalent to:
    *   el_len - el_data_offset - sizeof(unsigned short);
    */

       char el_text[];     /* Error messages */
       char el_data[];     /* Raw data       */

       unsigned short el_len;

 where

 el_len
   Specifies the length of the error log entry (in bytes). The el_len element
   is included both at the beginning and at the end of the entry to enable
   both forward and backward scanning of the log.

 el_reserved
   Reserved; must be 0.

 el_time
   Specifies the time that the service or application specified by el_name
   submitted the error entry. The value is stored as the number of seconds
   elapsed since 00:00:00, January 1, 1970.

 el_error
   Specifies the error code for the error. You can use el_error to obtain an
   error message from the NET.MSG file.

 el_name
   Contains an ASCIIZ string that specifies the name of the network service
   or application that returned the error entry. The constant SNLEN is
   defined in the NETCONS.H header file.

 el_data_offset
   Specifies the byte offset from the beginning of the error log entry to the
   start of its variable-length portion (el_text).

 el_nstrings
   Specifies how many ASCIIZ strings the el_text portion of the entry
   contains.

 el_text
   Points to ASCIIZ strings that describe the error.

 el_data
   Points to the raw data associated with the error.


 Error Log Codes

 The ERRLOG.H header file defines a number of standard error codes that can
 be written to the error log. Applications can use these values or they can
 define their own.

 The defined codes allow string data and raw data to be inserted along with
 the error code. The string data is represented in the table by a number
 preceded by a percent sign (%). For example, %1 is the first string. The
 string entries go in the el_text element of the data buffer. The raw data
 goes in the el_data element of the data buffer. For more information, see
 the "Example" section, later in this category.

 The ERRLOG.H header file defines the code, values, and meanings for these
 LAN Manager error codes:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NELOG_Internal_Error              3100   The operation failed because a
                                          network software error occurred.

 NELOG_Resource_Shortage           3101   The system ran out of a resource
                                          controlled by the %1 option.

 NELOG_Unable_To_Lock_Segment      3102   The service failed to obtain a
                                          long-term lock on the  segment
                                          for NCBs. The error code is the
                                          data.

 NELOG_Unable_To_Unlock_Segment    3103   The service failed to release the
                                          long-term lock on the segment for
                                          NCBs. The error code is the data.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         NCBs. The error code is the data.


 NELOG_Uninstall_Service           3104   An error stopped service %1.
                                          The error code from
                                          NetServiceControl is the data.

 NELOG_Init_Exec_Fail              3105   Initialization failed because of
                                          an MS OS/2 exec failure on path
                                          %1. The MS OS/2 error code is the
                                          data.

 NELOG_Ncb_Error                   3106   An unexpected NCB was received.
                                          The NCB is the data.

 NELOG_Net_Not_Started             3107   The network is not started.

 NELOG_Ioctl_Error                 3108   A DosDevIOCtl or DosFSCtl call to
                                          NETWKSTA.SYS failed.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         NETWKSTA.SYS failed.
                                          The data shown is in this format:
                                          dword Approximate CS:IP of   call
                                          to IOCtl or FSCtl
                                          word Error code
                                          word IOCtl or FSCtl number

 NELOG_System_Semaphore            3109   Unable to create or open system
                                          semaphore %1. The error code is
                                          the data.

 NELOG_Init_OpenCreate_Err         3110   Initialization failed because of
                                          an open/create error on the file
                                          %1. The MS OS/2 error code is the
                                          data.

 NELOG_NetBios                     3111   An unexpected NetBIOS error
                                          occurred. The error code is the
                                          data.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         data.

 NELOG_SMB_Illegal                 3112   An illegal SMB was received. The
                                          SMB is the data.

 NELOG_Service_Fail                3113   Initialization failed because the
                                          requested service %1 could not be
                                          started.

 NELOG_Entries_Lost                3114   Some entries in the error log
                                          were lost because of a buffer
                                          overflow.

 NELOG_Init_Seg_Overflow           3120   Initialization parameters that
                                          control resource use other than
                                          network buffers are sized so that
                                          too much memory is needed.

 NELOG_Srv_No_Mem_Grow             3121   The server cannot increase the
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NELOG_Srv_No_Mem_Grow             3121   The server cannot increase the
                                          size of a memory segment.

 NELOG_Access_File_Bad             3122   Initialization failed because
                                          account file: %1 is either
                                          incorrect or not present.

 NELOG_Srvnet_Not_Started          3123   Initialization failed because
                                          network: %1 was not started.

 NELOG_Init_Chardev_Err            3124   The server failed to start.
                                          Either all three character device
                                          parameters must be 0 or all three
                                          must be nonzero.

 NELOG_Remote_API                  3125   A remote API request was halted
                                          due to the following invalid
                                          description string: %1.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NELOG_Ncb_TooManyErr              3126   The network %1 ran out of NCBs.
                                          You may need to increase NCBs for
                                          this network. The following
                                          information includes the number
                                          of NCBs submitted by the server
                                          when this error occurred:

 NELOG_Mailslot_err                3127   The server cannot create the %1
                                          mailslot needed to send the
                                          ReleaseMemory alert message. The
                                          error received is:

 NELOG_ReleaseMem_Alert            3128   The server failed to register for
                                          the RELEASEMEMORY alert, with
                                          recipient %1. The error code from
                                          NetAlertStart is the data.

 NELOG_AT_cannot_write             3129   The server cannot update the AT
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NELOG_AT_cannot_write             3129   The server cannot update the AT
                                          schedule file. The file is
                                          corrupt.

 NELOG_Cant_Make_Msg_File          3130   The server encountered an error.
                                          The error code is the data.

 NELOG_Exec_Netservr_NoMem         3131   Initialization failed because of
                                          an MS OS/2 exec failure on path
                                          %1. There is not enough memory to
                                          start the process. The MS OS/2
                                          error code is the data.

 NELOG_Server_Lock_Failure         3132   Long-term lock of server buffers
                                          failed. Check swap disk free
                                          space and reboot system to start
                                          server.

 NELOG_Msg_Shutdown                3140   The service has stopped due
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NELOG_Msg_Shutdown                3140   The service has stopped due
                                          to repeated consecutive
                                          occurrences of an NCB error. The
                                          last bad NCB follows in raw data.

 NELOG_Msg_Sem_Shutdown            3141   Shutdown has occurred due to a
                                          lock on the shared data segment.

 NELOG_Msg_Log_Err                 3150   A file system error occurred
                                          while opening or writing to the
                                          system message log file, %1.
                                          Message logging has been switched
                                          off due to the error. The error
                                          code is the data.

 NELOG_VIO_POPUP_ERR               3151   Unable to display message popup
                                          due to an MS OS/2 VIO call error.
                                          The error code is the data.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NELOG_Msg_Unexpected_SMB_Type     3152   An illegal SMB was received. The
                                          SMB is the data.

 NELOG_Wksta_Infoseg               3160   The workstation information
                                          segment is bigger than 64K bytes.
                                          The size follows, in dword
                                          format:

 NELOG_Wksta_Compname              3161   The workstation was unable to get
                                          the name/number of the
                                          computername.

 NELOG_Wksta_BiosThreadFailure     3162   The workstation could not
                                          initialize the async NetBIOS
                                          thread. The error code is the
                                          data.

 NELOG_Wksta_IniSeg                3163   The workstation could not open
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NELOG_Wksta_IniSeg                3163   The workstation could not open
                                          the initial shared segment. The
                                          error code is the data.

 NELOG_Wksta_HostTab_Full          3164   The workstation host table is
                                          full.

 NELOG_Wksta_Bad_Mailslot_SMB      3165   A bad mailslot SMB was received.
                                          The SMB is the data.

 NELOG_Wksta_UASInit               3166   The workstation encountered an
                                          error while trying to start the
                                          UAS. The error code is the data.

 NELOG_Wksta_SSIRelogon            3167   The workstation encountered an
                                          error while responding to an SSI
                                          revalidation request. The
                                          function code and the error codes
                                          are the data.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         are the data.

 NELOG_Build_Name                  3170   The Alerter service had a problem
                                          creating the list of alert
                                          recipients. The error code is %1.

 NELOG_Name_Expansion              3171   There was an error expanding %1
                                          as a groupname. Try splitting the
                                          group into two or more smaller
                                          groups.

 NELOG_Message_Send                3172   There was an error sending %2 the
                                          alert message - (%3). The error
                                          code is %1.

 NELOG_Mail_Slt_Err                3173   There was an error in creating or
                                          reading the alerter mailslot. The
                                          error code is %1.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NELOG_AT_cannot_read              3174   The server could not read the AT
                                          schedule file.

 NELOG_AT_sched_err                3175   The server found an invalid AT
                                          schedule record.

 NELOG_AT_schedule_file_created    3176   The server could not find an AT
                                          schedule file so it created one.

 NELOG_Srvnet_NB_Open              3177   The server could not access the
                                          %1 network with NetBiosOpen.

 NELOG_AT_Exec_Err                 3178   The AT command processor couldn't
                                          run %1.

 NELOG_Lazy_Write_Err              3180   WARNING:  Because of a lazy-write
                                          error, drive %1 now contains some
                                          corrupt data. The cache is
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         corrupt data. The cache is
                                          stopped.

 NELOG_HotFix                      3181   A defective sector on drive %1
                                          has been replaced (hotfixed). No
                                          data was lost. You should run
                                          CHKDSK soon to restore full
                                          performance and replenish the
                                          volume's spare sector pool. The
                                          hotfix occurred while processing
                                          a remote request.

 NELOG_HardErr_From_Server         3182   A disk error occurred on the HPFS
                                          volume in drive %1. The error
                                          occurred while processing a
                                          remote request.

 NELOG_LocalSecFail1               3183   The UAS database (NET.ACC) is
                                          corrupt. The local security
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         corrupt. The local security
                                          system is replacing the corrupted
                                          NET.ACC with the backup made at
                                          %1. Any updates to the UAS made
                                          after this time are lost.

 NELOG_LocalSecFail2               3184   The UAS database (NET.ACC) is
                                          missing. The local security
                                          system is restoring the backup
                                          database made at %1. Any updates
                                          to the UAS made after this time
                                          are lost.

 NELOG_LocalSecFail3               3185   Local security could not be
                                          started because the UAS database
                                          (NET.ACC) was missing or corrupt,
                                          and no usable backup database was
                                          present. THE SYSTEM IS NOT SECURE.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NELOG_LocalSecGeneralFail         3186   Local security could not be
                                          started because an error occurred
                                          during initialization. The error
                                          code returned is %1. THE SYSTEM
                                          IS NOT SECURE.

 NELOG_NetWkSta_Internal_Error     3190   A NetWksta internal error has
                                          occurred: %1.

 NELOG_NetWkSta_No_Resource        3191   The redirector is out of a
                                          resource: %1.

 NELOG_NetWkSta_SMB_Err            3192   An SMB error occurred on
                                          connection to %1. The SMB header
                                          is the data.

 NELOG_NetWkSta_VC_Err             3193   A virtual circuit error occurred
                                          on the session to %1. The NCB
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         on the session to %1. The NCB
                                          command and return code is the
                                          data.

 NELOG_NetWkSta_Stuck_VC_Err       3194   Hanging up a stuck session to %1.


 NELOG_NetWkSta_NCB_Err            3195   An NCB error occurred (%1). The
                                          NCB is the data.

 NELOG_NetWkSta_Write_Behind_Err   3196   A write operation to %1 failed.
                                          Data may have been lost.

 NELOG_NetWkSta_Reset_Err          3197   Reset of driver %1 failed to
                                          complete the NCB. The NCB is the
                                          data.

 NELOG_NetWkSta_Too_Many           3198   The amount of resource %1
                                          requested was more than the
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         requested was more than the
                                          maximum. The maximum amount was
                                          allocated.

 NELOG_Srv_Thread_Failure          3204   The server could not create a
                                          thread. The threads parameter in
                                          CONFIG.SYS should be increased.

 NELOG_Srv_Close_Failure           3205   The server could not close %1.
                                          The file is probably corrupt.

 NELOG_ReplUserCurDir              3206   The replicator cannot update
                                          directory %1. It has tree
                                          integrity and is the current
                                          directory for some process.

 NELOG_ReplCannotMasterDir         3207   The server cannot export
                                          directory %1 to client %2. It is
                                          exported from another server.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         exported from another server.

 NELOG_ReplUpdateError             3208   The replication server could not
                                          update directory %2 from the
                                          source on %3 due to error %1.

 NELOG_ReplLostMaster              3209   Master %1 did not send an update
                                          notice for directory %2 at the
                                          expected time.

 NELOG_NetlogonAuthDCFail          3210   Failed to authenticate with %2,
                                          the domain controller for domain
                                          %1.

 NELOG_ReplLogonFailed             3211   The replicator attempted to log
                                          on at %3 as %2 and failed.

 NELOG_ReplNetErr                  3212   Network error %1 occurred.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NELOG_ReplMaxFiles                3213   Replicator limit for files in a
                                          directory has been exceeded.

 NELOG_ReplMaxTreeDepth            3214   Replicator limit for tree depth
                                          has been exceeded.

 NELOG_ReplBadMsg                  3215   Unrecognized message received in
                                          mailslot.

 NELOG_ReplSysErr                  3216   System error %1 occurred.

 NELOG_ReplUserLoged               3217   Cannot log on. User is currently
                                          logged on and argument TRYUSER is
                                          set to NO.

 NELOG_ReplBadImport               3218   IMPORT path %1 cannot be found.

 NELOG_ReplBadExport               3219   EXPORT path %1 cannot be found.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NELOG_ReplBadExport               3219   EXPORT path %1 cannot be found.

 NELOG_ReplSignalFileErr           3220   Replicator failed to update
                                          signal file in directory %2 due
                                          to %1 system error.

 NELOG_DiskFT                      3221   Disk fault tolerance error %1.

 NELOG_ReplAccessDenied            3222   Replicator could not access %2 on
                                          %3 due to %1 system error.

 NELOG_NetlogonFailedPrimary       3223   The primary domain controller for
                                          domain %1 has apparently failed.

 NELOG_NetlogonPasswdSetFailed     3224   Error in changing this computer's
                                          password.

 NELOG_NetlogonTrackingError       3225   Error in updating the logon or
                                          logoff information for %1.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         logoff information for %1.

 NELOG_NetlogonSyncError           3226   Error in synchronizing with
                                          primary domain controller %1.

 NELOG_UPS_PowerOut                3230   A power failure was detected.

 NELOG_UPS_Shutdown                3231   The UPS service performed server
                                          shutdown.

 NELOG_UPS_CmdFileError            3232   The UPS service did not complete
                                          execution of the user-specified
                                          shutdown command file.

 NELOG_UPS_CannotOpenDriver        3233   The UPS driver could not be
                                          opened. The error code is the
                                          data.

 NELOG_Missing_Parameter           3250   Initialization failed because of
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NELOG_Missing_Parameter           3250   Initialization failed because of
                                          an invalid or missing  parameter
                                          in LANMAN.INI: %1.

 NELOG_Invalid_Config_Line         3251   Initialization failed because of
                                          an invalid line in the
                                          configuration file %1. The
                                          invalid line is the data.

 NELOG_Invalid_Config_File         3252   Initialization failed because of
                                          an error in the configuration
                                          file %1.

 NELOG_File_Changed                3253   The file %1 has been changed
                                          after initialization. The boot
                                          block loading was temporarily
                                          terminated.

 NELOG_Files_Dont_Fit              3254   The files do not fit the boot
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NELOG_Files_Dont_Fit              3254   The files do not fit the boot
                                          block configuration file %1.
                                          Change BASE and ORG definitions
                                          or the order of the files.

 NELOG_Wrong_DLL_Version           3255   Initialization failed because the
                                          dynamic-link library %1 returned
                                          a wrong version number.

 NELOG_Error_in_DLL                3256   There was an unrecoverable error
                                          in the dynamic-link library of
                                          the service.

 NELOG_System_Error                3257   The system returned an unexpected
                                          error code. The error code is the
                                          data.

 NELOG_FT_ErrLog_Too_Large         3258   The fault-tolerance error log,
                                          LANROOT\LOGS\FT.LOG, is more than
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         LANROOT\LOGS\FT.LOG, is more than
                                          64K.

 NELOG_FT_Update_In_Progress       3259   The fault-tolerance error log,
                                          LANROOT\LOGS\FT.LOG, had the
                                          update-in-progress bit set upon
                                          opening, which means that the
                                          system crashed while working on
                                          the error log.

 NELOG_OEM_Code                    3299   Generic error log entry for OEMs
                                          to use to log errors from OEM
                                          value-added services. The text
                                          for the entry is: %1 %2 %3 %4 %5
                                          %6 %7 %8 %9. (For more detail,
                                          see ERRLOG.H.)

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 NetErrorLogClear
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetErrorLogClear clears the error log and optionally saves the entries in a
 backup file. When executed locally, NetErrorLogClear requires that the
 NETWKSTA device driver be installed. When a servername parameter is
 supplied, NetErrorLogClear requires that the local Workstation service be
 started.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetErrorLogClear on a
 remote server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETERRORLOG
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetErrorLogClear (const char far *  pszServer,
                     const char far *  pszBackupFile,
                     char far *        pszReserved
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetErrorLogClear. A null pointer or null string specifies the
   local computer.

 pszBackupFile
   Points to an ASCIIZ string that assigns a name for an optional backup
   file. The calling application must have write permission for the path
   specified by pszBackupFile. The DosMove function must also be able to
   access the pathname. If the pathname is relative, it is assumed to be
   relative to the LAN Manager LOGS directory. A null pointer indicates not
   to back up the error log.

 pszReserved
   Reserved; must be a null pointer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 ERROR_FILENAME_EXCED_RANGE        206     The filename specified is
                                           invalid for the file system.
                                           This code is returned when
                                           checking a FAT disk partition
                                           only. It cannot be returned for
                                           an HPFS partition.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetErrorLogClear returns ERROR_SHARING_VIOLATION if the error log is
 currently opened by another process.


 NetErrorLogRead
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetErrorLogRead reads from the specified error log. When executed locally,
 NetErrorLogRead requires that the NETWKSTA device driver be installed. When
 a servername parameter is supplied, NetErrorLogRead requires that the local
 Workstation service be started.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute
 NetErrorLogRead.


 Syntax

   #define INCL_NETERRORLOG
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetErrorLogRead (const char far *      pszServer,
                    const char far *      pszReserved1
                    HLOG far *            phErrorLog,
                    unsigned long         ulOffset,
                    unsigned short far *  pusReserved2,
                    unsigned long         ulReserved3,
                    unsigned long         flOffset,
                    char far *            pbBuffer,
                    unsigned short        cbBuffer,
                    unsigned short far *  pcbReturned,
                    unsigned short far *  pcbTotalAvail
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetErrorLogRead. A null pointer or null string specifies the
   local computer.

 pszReserved1
   Reserved; must be a null pointer.

 phErrorLog
   Points to the error log handle. An application calling NetErrorLogRead for
   the first time must initialize the 128-bit error log handle as follows:

 Bits                             Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 127 (MSB) - 64                   0
 63 - 0 (LSB)                     1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   The most significant bit (MSB) is the leftmost bit. The least significant
   bit (LSB) is the rightmost bit. Thereafter, each call to NetErrorLogRead
   must be given the value for the handle returned by the previous call.

 ulOffset
   Specifies the record offset at which to begin reading. This parameter is
   ignored unless bit 1 of flOffset is set. If used, ulOffset is taken as an
   offset of the record number (not bytes) at which to begin reading. Note
   that the record offset parameter is zero-based from both directions,
   depending upon the direction it is read. If reading backward, record 0 is
   the last record in the log. If reading forward, record 0 is the first
   record in the log.

 pusReserved2
   Reserved; must be a null pointer.

 ulReserved3
   Reserved; must be 0.

 flOffset
   Specifies the open flags, bitmapped as follows:

 Bit(s)                            Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 If 0, the log is read forward. If 1, the
                                   log is read backward and records are
                                   returned in reverse chronological order.

 1                                 If 0, the read proceeds normally
                                   (sequentially). If 1, the read proceeds
                                   from the nth record from the start of
                                   the log, where n is the offset parameter.

 2-31                              Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 pbBuffer
   Points to the buffer for returned data.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbReturned
   Points to an unsigned short integer that specifies how many bytes were
   read into the buffer. This count is valid only if NetErrorLogRead returns
   NERR_Success or NERR_BufTooSmall.

 pcbTotalAvail
   Points to an unsigned short integer that specifies how many bytes were
   available to be read from the log. This count is valid only if
   NetErrorLogRead returns NERR_Success or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_LogFileChanged               2378    The log file has changed since
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_LogFileChanged               2378    The log file has changed since
                                           it was last read.

 NERR_LogFileCorrupt               2379    The log file is corrupt.

 NERR_InvalidLogSeek               2440    The log file does not contain
                                           the requested record number.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 To read the contents of an error log, an application calls NetErrorLogRead
 repeatedly until the function returns information (via the pcbTotalAvail
 parameter) that indicates there is no more data to be read. Each call to
 NetErrorLogRead returns a handle that must be provided to any subsequent
 call to NetErrorLogRead. This handle changes with each subsequent call. The
 handle is not a system file handle and should never be treated as such.

 Note that the error log can contain much more than 64K of data. If
 pcbTotalAvail is returned with a value of 0xFFFF, there may be 0xFFFF or
 more bytes of data available. The application should continue to read the
 log until the value returned in pcbTotalAvail is 0.

 NetErrorLogRead passes data back in the buffer only in whole records. The
 application never gets a partial record in the buffer. Use the value pointed
 to by pcbReturned to determine the end of valid data in the buffer.

 The error log is written with the newest records appended at the end. The
 flOffset parameter determines whether to read the log in forward or in
 reverse order.

 If the error log is partially read, and then the log is cleared or a new
 record written, a subsequent read with the handle returned from the first
 call to NetErrorLogRead will return an error. An application that finds that
 the error log has changed between calls can reread the changed log by
 reissuing the call with the error log handle initialized as if it were
 making the call for the first time.


 NetErrorLogWrite
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetErrorLogWrite writes an entry to the error log on the local computer. It
 requires that the Workstation service be started.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to successfully execute
 NetErrorLogWrite.


 Syntax

   #define INCL_NETERRORLOG
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetErrorLogWrite (char far *        pszReserved1,
                     unsigned short    usCode,
                     const char far *  pszComponent,
                     const char far *  pbBuffer,
                     unsigned short    cbBuffer,
                     const char far *  pszStrBuf
                     unsigned short    cStrBuf,
                     char far *        pszReserved2
                    );

 where

 pszReserved1
   Reserved; must be a null pointer.

 usCode
   Specifies the code of the error that occurred.

 pszComponent
   Points to an ASCIIZ string that specifies which component encountered the
   error.

 pbBuffer
   Points to the raw data associated with the error condition.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pszStrBuf
   Points to ASCIIZ strings that contain the error message.

 cStrBuf
   Specifies how many concatenated ASCIIZ strings are stored by pszStrBuf.

 pszReserved2
   Reserved; must be a null pointer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_NET_WRITE_FAULT             88      A network data fault occurred.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_LogOverflow                  2377    The log file is too big.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetErrorLogWrite internally calls the appropriate functions to open and
 close the error log.

 NetErrorLogWrite issues an error log alert (via NetAlertRaise) each time an
 entry is written to the error log. It also issues an admin alert by calling
 NetAlertRaise when the error log reaches 80% capacity and again when the log
 reaches 100% capacity. At 100% error log capacity, NetErrorLogWrite fails
 and returns NERR_LogOverflow. Applications should periodically clear the log
 of outdated information so that the log does not reach 100% capacity.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Alerts                            Alert Category





 Error Logging Category Example

   /*
      NETERR.C -- a sample program demonstrating NetErrorLog API functions.

      This program requires that you have admin privilege if a servername
      parameter is supplied.

         usage:  neterr [-s \\server] [-b backup]

         where  \\server = Name of the server. A servername must be preceded

                           by two backslashes (\\).
                backup   = Name of the backup file.

      API                  Used to...
      ================     ===========================================
      NetErrorLogClear     Back up the error log and then clear it
      NetErrorLogWrite     Write several entries into the error log
      NetErrorLogRead      Read the error log and display its contents

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETERRORS
   #define     INCL_NETERRORLOG
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>
   #include    <time.h>

   #include    "samples.h"    // Internal routine header file

   #define DEFAULT_BACKUP     "ERROR.BCK"

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char * pszServer = "";                    // Servername
      char * pszBackup = DEFAULT_BACKUP;        // Backup log file
      struct error_log *pBuffer;                // Pointer to data buffer
      struct error_log *pEntry;                 // Single entry in log
      int              iCount;                  // Index counter
      unsigned short   cbBuffer;                // Count of bytes in
   buffer
      unsigned short   cbRead;                  // Count of bytes read
      unsigned short   cbAvail;                 // Count of bytes available
      unsigned short   usDataByte;              // Raw data
      API_RET_TYPE     uReturnCode;             // API return code
      HLOG             hLogHandle;              // Error log handle
      time_t           tTime;

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'b':                        // -b backup file
                  pszBackup = argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetErrorLogClear
   //
   //  This API clears the error log for the specified server. A backup
   is
   //  kept in the file specified by pszBackup. If a null pointer is
   supplied,
   //  no backup is kept.
   //========================================================================

      uReturnCode = NetErrorLogClear(
                        pszServer,              // Servername
                        pszBackup,              // Backup file
                        NULL);                  // Reserved; must be
   NULL

      printf("NetErrorLogClear returned %u\n", uReturnCode);
      printf("   backup file = %s \n\n", pszBackup);



   //========================================================================
   //  NetErrorLogWrite
   //
   //  This API writes a few entries to the error log. These entries
   are
   //  some typical types of errors that may be encountered. The error
   //  codes are defined in the ERRLOG.H header file.
   //  Note: Because NetErrorLogWrite has no servername parameter, the
   entry
   //  written into the local error log.
   //========================================================================

      /*
       * Write an entry of type NELOG_Resource_Shortage that has
       * a single text error message and no raw data.
       */

      uReturnCode = NetErrorLogWrite(
                        NULL,                     // Reserved; must be
   NULL
                        NELOG_Resource_Shortage,  // Error code
                        argv[0],                  // Component in error
                        NULL,                     // Pointer to raw data
                        0,                        // Length of raw data
   buffer
                        "THREADS=",               // String data
                        1,                        // Number of error
   strings
                        NULL);                    // Reserved; must be
   NULL

      printf("NetErrorLogWrite for NELOG_Resource_Shortage returned %u\n",
                        uReturnCode);

      /*
       * Write an entry of type NELOG_Init_OpenCreate_Err that has
       * a single text error message and raw data associated with it.
       */

      usDataByte = 3;                              // Path not found
   error

      uReturnCode = NetErrorLogWrite(
                        NULL,                      // Reserved; must
   be NULL
                        NELOG_Init_OpenCreate_Err, // Error code
                        argv[0],                   // Component in error
                        (char far *)&usDataByte,   // Pointer to raw
   data
                        sizeof(unsigned short),    // Length of raw data
   buffer
                        "C:\\INIT\\STARTER.CMD",   // String data
                        1,                         // Number of error
   strings
                        NULL);                     // Reserved; must
   be NULL

      printf("NetErrorLogWrite for NELOG_Init_OpenCreate_Err returned
   %u\n",
                        uReturnCode);

      /*
       * Write an entry of type NELOG_Srv_No_Mem_Grow that has
       * no text error message and no raw data associated with it.
       */

      uReturnCode = NetErrorLogWrite(
                        NULL,                   // Reserved; must be
   NULL
                        NELOG_Srv_No_Mem_Grow,  // Error code
                        argv[0],                // Component in error
                        NULL,                   // Pointer to raw data
                        0,                      // Length of raw data
   buffer
                        NULL,                   // String data
                        0,                      // Number of error strings
                        NULL);                  // Reserved; must be
   NULL

      printf("NetErrorLogWrite for NELOG_Srv_No_Mem_Grow returned %u\n\n",
                        uReturnCode);

   //========================================================================
   //  NetErrorLogRead
   //
   //  This API reads and displays the error log for the specified server.
   //========================================================================

      /*
       * Allocate a small buffer space to demonstrate reading the error
   log
       * when the log is larger than the buffer allocated to store it.
   The
       * maximum allowable buffer is 64K. If the error log is larger
   than
       * the buffer specified, the API returns as many full records as
   it
       * can and the NERR_Success return code. Subsequent reads start
   from
       * the end of the last record read. To read the whole log, the
   reads
       * must continue until the bytes available counter is 0.
       */

      cbBuffer = 100;
      pBuffer = SafeMalloc(cbBuffer);           // Allocate memory for
   buffer

      /*
       * Set the log handle for reading from the start of the error log.
       * This handle gets modified by the API. Any subsequent reads
       * for unread data should use the returned handle.
       */

      hLogHandle.time = 0L;
      hLogHandle.last_flags = 0L;
      hLogHandle.offset = 0xFFFFFFFF;
      hLogHandle.last_flags = 0xFFFFFFFF;
      do {
         uReturnCode = NetErrorLogRead(
                           pszServer,           // Servername
                           NULL,                // Reserved; must be
   NULL
                           &hLogHandle,         // Error log handle
                           0L,                  // Start at record 0
                           NULL,                // Reserved; must be
   NULL
                           0L,                  // Reserved; must be
   0
                           0L,                  // Read the log forward
                           (char far *)pBuffer, // Data returned here
                           cbBuffer,            // Size of buffer, in
   bytes
                           &cbRead,             // Count of bytes read
                           &cbAvail);           // Count of bytes available

         printf("NetErrorLogRead returned %u \n", uReturnCode);

         if (uReturnCode == NERR_Success)
         {
            for ( pEntry = pBuffer;
                  pEntry < (struct error_log *)((char *)pBuffer + cbRead);
   )
            {
               tTime = (time_t) pEntry->el_time;

               printf("   Error %hu, from %s at %s",
                   pEntry->el_error, pEntry->el_name,
                   asctime( gmtime ((const time_t *) &tTime) ) );

               pEntry = (struct error_log *)((char *)pEntry +
 pEntry->el_len);
            }
            printf("Bytes Read = 0x%X\n", cbRead);

            // To read to whole log, keep reading until cbAvail is 0.

            if (cbAvail)
               printf("Data still unread.\n\n");
            else
               printf("All data read.\n\n");
         }
      } while ((uReturnCode == NERR_Success) && (cbAvail != 0));

      free(pBuffer);
      exit(0);
   }
   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-b backup]\n", pszProgram);
      exit(1);
   }







 File Category

 File API functions provide a way to monitor and close the file, device, and
 pipe resources open on a server. They require that the Workstation service
 be started and that the Server service be started on the specified server.

 The File category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETFILE, and including the master header file,
 LAN.H. For more information about these definitions,  see the "Example"
 section, later in this category.

 These are the File API functions:


   þ   NetFileClose2

   þ   NetFileEnum2

   þ   NetFileGetInfo2



 Description

 NetFileClose2 forces a server resource closed. This function can be used
 when a system error prevents normal closure (for example, when the DosClose
 function fails).

 NetFileEnum2 returns information about resources open on a server. A file
 can be opened one or more times by one or more applications. Each file
 opening is uniquely identified. NetFileEnum2 returns an entry for each file
 opening.

 NetFileGetInfo2 returns information about one particular opening of a
 resource.

 NetFileEnum2 and NetFileGetInfo2 can return the file identifier only, or
 they can return the file identifier and additional detailed data. Four
 levels and data structures are available. Levels 0 and 1 return short file
 identifiers. Levels 2 and 3 return long file identifiers.  Long file
 identifiers support the increased number of open files allowed on computers
 using the high-performance file system (HPFS). Levels 0 and 2 return only
 the iden- tification number that was assigned to the resource when it was
 opened. Levels 1 and 3 return the identification number, permissions, file
 locks, and the name of the user who opened the resource. You should use
 levels 2 and 3 to ensure that data is returned for all open resources.
 Levels 0 and 1 are provided only for compatibility with previous LAN Manager
 releases.

 NetFileEnum2 and NetFileGetInfo2 can return level 0 and level 1 data for
 only those resources that have file identifier values less than 65,536. Do
 not make assumptions about file identifiers; an open resource can have an
 identifier greater than 65,536 even if it is the only open resource.

 Levels 0 and 1 do not guarantee the return of all valid data. When level 0
 or level 1 is used, the value of the pcEntriesRemaining parameter returned
 by NetFileEnum2 reflects only the number of open files that have file
 identifier values less than 65,536.


 Data Structures

 The sLevel parameter of NetFileEnum2 and NetFileGetInfo2 specifies the level
 of information to be returned. Both functions return the file_info_X data
 structure, where X is 0, 1, 2, or 3, depending on the level of detail
 specified.


 Opened Resources (level 0)

 The file_info_0 data structure has this format:

   struct file_info_0 {
       unsigned short  fi0_id;
   };

 where

 fi0_id
   Specifies the identification number assigned to the resource when it is
   opened.


 Opened Resources (level 1)

 The file_info_1 data structure has this format:

   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;
   };

 where

 fi1_id
   Specifies the identification number assigned to the resource when it is
   opened.

 fi1_permissions
   Specifies the access permissions of the opening application. The bit mask
   of fi1_permissions is defined in the SHARES.H header file.

   The SHARES.H header file defines the following permissions:

 Code              Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PERM_FILE_READ    0x1       Permission to read a resource and, by default,
                             execute the resource.

 PERM_FILE_WRITE   0x2       Permission to write to a resource.

 PERM_FILE_CREATE  0x4       Permission to create a resource; data can be
                             written when creating the resource.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 fi1_num_locks
   Specifies how many file locks are on the file, device, or pipe.

 fi1_pathname
   Points to an ASCIIZ string that gives the pathname of the opened resource.

 fi1_username
   Points to an ASCIIZ string that specifies which user (on servers with
   user-level security) or which computername (on servers with share-level
   security) opened the resource.


 Opened Resources (level 2)

 The file_info_2 data structure has this format:

   struct file_info_2 {
       unsigned long  fi2_id;
   };

 where

 fi2_id
   Specifies the identification number assigned to the resource when it is
   opened.


 Opened Resources (level 3)

 The file_info_3 data structure has this format:

   struct file_info_3 {
       unsigned long   fi3_id;
       unsigned short  fi3_permissions;
       unsigned short  fi3_num_locks;
       char far *      fi3_pathname;
       char far *      fi3_username;
   };

 where

 fi3_id
   Specifies the identification number assigned to the resource when it is
   opened.

 fi3_permissions
   Specifies the access permissions of the opening application. The bit mask
   of fi3_permissions is defined in the SHARES.H header file. It has the same
   definition as the fi1_permissions element of the file_info_1 data
   structure. For more information, see the description of the file_info_1
   data structure, earlier in this section.

 fi3_num_locks
   Specifies how many file locks are on the file, device, or pipe.

 fi3_pathname
   Points to an ASCIIZ string that gives the pathname of the opened resource.

 fi3_username
   Points to an ASCIIZ string that specifies which user (on servers that have
   user-level security) or which computer (on servers that have share-level
   security) opened the resource.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Access permissions                Access Permissions Category


 NetFileClose2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetFileClose2 forces a resource to close. This function can be used when an
 error prevents closure by other means.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetFileClose2 on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETFILE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetFileClose2 (const char far *  pszServer,
                  unsigned long     ulFileId
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetFileClose2. A null pointer or null string specifies the
   local computer.

 ulFileId
   Specifies the identification number assigned to the resource when it is
   opened.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_FileIdNotFound               2314    There is no open file with this
                                           ID number.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Ordinarily, a call to the DosClose function closes a resource opened by a
 call to the DosOpen function. Use NetFileClose2 to force a resource to
 close.

 NetFileClose2 supersedes NetFileClose (used in earlier versions of LAN
 Manager). NetFileClose2 is the same as NetFileClose except that
 NetFileClose2 has an unsigned long ulFileId parameter instead of an unsigned
 short usFileId parameter. For more information, see Appendix B, "Upgrading
 LAN Manager 1.0 Applications."

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing open files, devices, or   NetFileEnum2
 pipes on a server

 Obtaining information about a     NetFileGetInfo2
 specified open resource


 NetFileEnum2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetFileEnum2 supplies information about some or all open files on a server,
 allowing the user to supply a key and get required information through
 repeated calls to the function.

 NetFileEnum2 is slightly different from other Enum functions. NetFileEnum2
 uses a file resume key data structure that allows the application to resume
 enumeration from where it left off. NetFileEnum2 does not require all data
 to fit in a single buffer returned from a single call.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetFileEnum2 on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETFILE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetFileEnum2 (const char far *      pszServer,
                 const char far *      pszBasePath,
                 const char far *      pszUserName,
                 short                 sLevel,
                 char far *            pbBuffer,
                 unsigned short        cbBuffer,
                 unsigned short far *  pcEntriesRead,
                 unsigned short far *  pcEntriesRemaining,
                 void far *            pResumeKey
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetFileEnum2. A null pointer or null string specifies the local
   computer.

 pszBasePath
   Points to the base pathname for enumeration. If not NULL, pszBasePath
   serves as a qualifier to the enumeration. The entries returned are limited
   to those that have names beginning with the qualifier string pointed to by
   pszBasePath. For example, the value C:\TMP enumerates only open files that
   have pathnames beginning with C:\TMP (such as C:\TMPFILE and
   C:\TMP\DOCUMENT). If pszBasePath is NULL, no base path qualifier is used.

 pszUserName
   Points to an ASCIIZ string that specifies the name of the user. If not
   NULL, pszUserName serves as a qualifier to the enumeration. The files
   returned are limited to those that have usernames matching the qualifier.
   If pszUserName is NULL, no username qualifier is used.

 sLevel
   Specifies the level of detail (0, 1, 2, or 3) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of file_info_X data structures,
   where X is 0, 1, 2, or 3, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of
   entries in the buffer is returned. This count is valid only if
   NetFileEnum2 returns NERR_Success or ERROR_MORE_DATA.

 pcEntriesRemaining
   Points to an unsigned short integer in which a count of the total number
   of entries is returned. This count is valid only if NetFileEnum2 returns
   NERR_Success or ERROR_MORE_DATA.

 pResumeKey
   Points to the file resume key structure, FRK. Using pResumeKey allows
   repeated calls to NetFileEnum2 to continue enumerating files when the
   return data from a preceding call did not fit within the return buffer
   supplied.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetFileEnum2 is different from other Enum functions. Other Enum functions
 supply only the fixed-length data if the buffer cannot hold the complete
 record; unlike other Enum functions, NetFileEnum2 supplies as many complete
 records as the buffer can hold.

 The application can use a resume key and make repeated calls to obtain the
 data. Rather than make repeated pairs of calls as with other Enum functions
 (the first to determine a buffer size, the second to obtain the data), an
 application can determine a representative buffer size, and then make
 repeated calls using this size. (If the application makes an initial call to
 NetFileEnum2 to determine the representative buffer size, the file resume
 key should be reinitialized for the first call that obtains actual data.)

 NetFileEnum2 allows the user to overcome the problem that arises when the
 information returned exceeds the size of the return buffer. To initialize
 pResumeKey, use the FRK_INIT macro supplied in the SHARES.H header file; the
 macro accepts an FRK structure as an argument. The following example shows
 an application code fragment:

   FRK f;

   FRK_INIT (f);
   NetFileEnum2 (..., &f, ...);

 If NetFileEnum2 is called with an initial pResumeKey value, and the buffer
 supplied is too small to return all the requested information, NetFileEnum2
 returns the ERROR_MORE_DATA error code and a pResumeKey value suitable for
 retrieving the remaining data.

 When called with a pResumeKey value from a previous call, NetFileEnum2
 resumes the enumeration at the place indicated by that value. The user must
 not attempt to set this key, other than to initialize it. Other
 user-supplied values for pResumeKey must have been returned by a preceding
 call to NetFileEnum2.

 On heavily loaded servers, the information returned by NetFileEnum2 can
 exceed the maximum allowed buffer size of 64K and generate ERROR_MORE_DATA
 return codes.

 The amount of data returned can be minimized by specifying the base path or
 username. If both the pszUserName and pszBasePath parameters are specified,
 only files that match both qualifying conditions are returned.

 NetFileEnum2 supports level 0, 1, 2, and 3 file_info_X data structures.

 NetFileEnum2 supersedes NetFileEnum (used in earlier versions of LAN
 Manager). NetFileEnum2 is the same as NetFileEnum except that NetFileEnum2
 includes the pResumeKey parameter. For more information, see Appendix B,
 "Upgrading LAN Manager 1.0 Applications."

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Closing open files, devices, or   NetFileClose2
 pipes

 Obtaining information about a     NetFileGetInfo2
 specified open resource


 NetFileGetInfo2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetFileGetInfo2 retrieves information about a particular opening of a server
 resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetFileGetInfo2 on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETFILE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetFileGetInfo2 (const char far *      pszServer,
                    unsigned long         ulFileId,
                    short                 sLevel,
                    char far *            pbBuffer,
                    unsigned short        cbBuffer,
                    unsigned short far *  pcbTotalAvail
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetFileGetInfo2. A null pointer or null string specifies the
   local computer.

 ulFileId
   Specifies the identification number assigned to the resource when it was
   opened.

 sLevel
   Specifies the level of detail (0, 1, 2, or 3) to be returned.

 pbBuffer
   Points to the buffer in which to store the return data. On a successful
   return, the buffer contains a sequence of file_info_X data structures,
   where X is 0, 1, 2, or 3, depending on the level of detail specified.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer that specifies how many bytes of
   information were available. This count is valid only if NetFileGetInfo2
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_FileIdNotFound               2314    There is no open file with this
                                           ID number.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetFileGetInfo2 supports level 0, 1, 2, and 3 file_info_X data structures.

 NetFileGetInfo2 supersedes NetFileGetInfo (used in earlier versions of LAN
 Manager). NetFileGetInfo2 is the same as NetFileGetInfo except that
 NetFileGetInfo2 has an unsigned long ulFileId parameter instead of an
 unsigned short usFileId parameter. For more information, see Appendix B,
 "Upgrading LAN Manager 1.0 Applications."

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Closing a file, device, or pipe   NetFileClose2

 Listing files, devices, or pipes  NetFileEnum2
 open on a server





 File Category Example

   /*
      NETFILE.C -- a sample program demonstrating NetFile API functions.

      This program requires that you have admin privilege on the specified
      server.

         usage:  netfile [-s \\server] [-b basepath] [-u username]

         where  \\server = Name of the server. A servername must be
                           preceded by two backslashes (\\).
                basepath = Enumerate only open files along this path.
                username = Enumerate only files opened by this user.

      API                 Used to...
      ===============     ================================================
      NetFileEnum2        List files in the base path opened by user
      NetFileGetInfo2     Get information available about each listed
   file
      NetFileClose2       Close specified files on the specified server

      This sample code is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.

   */

   #define     INCL_NETFILE
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      char *pszServerName = "";              // Required parameters for
   calls
      char far *pszBasePath = (char far *) NULL;
      char far *pszUserName = (char far *) NULL;
      API_RET_TYPE   uReturnCode;            // API return codes
      int            iCount;                 // Index counter

   unsigned short cbBuflen;               // Count of bytes
      unsigned short cEntriesRead;           // Entries read
      unsigned short cEntriesRemaining;      // Entries remaining to
   be read
      unsigned short cGetEntries = 0;        // Count of all enumerated
   IDs
      unsigned short cbTotalAvail;           // Count of bytes available
      unsigned short fTableAllocated = 0;    // Flag to build table of
   IDs
      struct file_info_3 *pBuf3, *p3;        // File IDs; use only level
   2,3
      FRK resumekey;   // File resume key, used when enum data > buffer
   size
      unsigned long *pulIds, *pulStartId;    // List of file IDs

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServerName = argv[++iCount];
                  break;
               case 'b':                        // -b base path
                  pszBasePath = (char far *)argv[++iCount];
                  break;
               case 'u':                        // -u username
                  pszUserName = (char far *)argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      } // End for loop

      printf("\nFile Category API Examples\n");
      if (pszServerName[0] != '\0')
         printf("Server = %s\n", pszServerName);
      if (pszBasePath != NULL)
         printf("Base path = %s\n", pszBasePath);
      if (pszUserName != NULL)
         printf("User name = %s\n", pszUserName);

   //========================================================================
   //  NetFileEnum2
   //
   //  This API lists all open files on the server below the specified
   given
   //  base path. If no base path is given, all open files are listed.
   //========================================================================
      cbBuflen = 256;      // Small size to demonstrate use of resume
   key
      pBuf3 = (struct file_info_3 *) SafeMalloc(cbBuflen);
      p3 = pBuf3;          // Save pointer for free() cleanup at end
      FRK_INIT(resumekey); // Must init file resume key; use SHARES.H
   macro

      do                   // Use resume key and loop until done
      {
         uReturnCode = NetFileEnum2(pszServerName,    // NULL means local
                                  pszBasePath,        // NULL means root
                                  pszUserName,        // NULL means all
   users
                                  3,                  // Level (0 through
   3)
                                  (char far *)pBuf3,  // Return buffer
                                  cbBuflen,           // Return buffer
   length
                                  &cEntriesRead,      // Count of entries
   read
                                  &cEntriesRemaining, // Entries not
   read
                                  &resumekey);        // Resume key

         printf("NetFileEnum2 returned %u\n", uReturnCode);
         if (uReturnCode == NERR_Success || uReturnCode == ERROR_MORE_DATA)
         {
            printf("   Entries read = %hu, Entries remaining = %hu\n",

                          cEntriesRead, cEntriesRemaining);
               // Save the file IDs.
            if (cEntriesRead > 0)
            {
               // Allocate memory for file ID table first time through
   only.
               if (fTableAllocated == 0)
               {
                  cGetEntries = cEntriesRead + cEntriesRemaining;
                  pulStartId = pulIds = (unsigned long *)
                             SafeMalloc(cGetEntries * sizeof(unsigned
   long));
                  fTableAllocated = 1;         // Assure allocate only
   once
               }

               // Print the file information.
               printf("   Id      Perms   Locks   User            Path\n");
               for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
               {
                  printf("   %-8lu%-8hu%-8hu%-16Fs%Fs\n", pBuf3->fi3_id,
                        pBuf3->fi3_permissions, pBuf3->fi3_num_locks,
                        pBuf3->fi3_username, pBuf3->fi3_pathname);

                  *pulIds = pBuf3->fi3_id;
                  pulIds++;
                  pBuf3++;
               } // End for loop
               pBuf3 = p3;   // Pointer was changed; restore to top of
   buffer
            } // End if cEntriesRead > 0
         } // End if successful call
      } while (uReturnCode == ERROR_MORE_DATA); // Use FRK until enum
   all
      free(p3);

   //========================================================================
   //  NetFileGetInfo2
   //
   //  This API retrieves all file IDs listed from the NetFileEnum2 call.
   //========================================================================

      if (cGetEntries != 0)
      {
         cbBuflen = 1024;
         pBuf3 = (struct file_info_3 *) SafeMalloc(cbBuflen);
         p3 = pBuf3;           // Save pointer for free() cleanup at
   end
         pulIds = pulStartId;  // Start at beginning of list
         printf("NetFileGetInfo2 results:\n");
         for (iCount = 0; iCount < (int) cGetEntries; iCount++)
         {
            uReturnCode = NetFileGetInfo2(
                                 pszServerName,      // NULL means local
                                 *pulIds,            // File ID from
   enum
                                 3,                  // Level (0 through
   3)
                                 (char far *)pBuf3,  // Return buffer
                                 cbBuflen,           // Return buffer
   length
                                 &cbTotalAvail);     // Entries not yet
   read

            if (uReturnCode)
               printf("NetFileGetInfo2 for file %lu returned %u\n",
                     *pulIds, uReturnCode);
            else
               printf("   File %lu: %-8hu%-8hu%-16Fs%Fs\n", *pulIds,
                     pBuf3->fi3_permissions, pBuf3->fi3_num_locks,
                     pBuf3->fi3_username, pBuf3->fi3_pathname);
            pulIds++;
         }
      }

   //========================================================================
   //  NetFileClose2
   //
   //  This API closes the specified open files on the specified server.
   //========================================================================

      if (cGetEntries != 0)
      {
         pulIds = pulStartId;
         for (iCount = 0; iCount < (int) cGetEntries; iCount++)
         {
            uReturnCode = NetFileClose2(pszServerName,    // NULL means
   local
                                 (unsigned long)*pulIds); // File ID
   from enum

            printf("NetFileClose2 for file %lu returned %u\n",
                           *pulIds, uReturnCode);
            pulIds++;
         }
         free(pulStartId);
      }

      free(p3);
      exit(0);
   }

   void Usage(char *pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-b basepath] "
                      "[-u username]\n", pszString);
      exit(1);
   }







 Group Category

 Group API functions control groups of users. The Group API functions require
 that the user account subsystem (UAS) be started. On most computers the UAS
 is started when the Workstation service is started, provided a valid user
 accounts database file exists. On computers using the high-performance file
 system 386 (HPFS386) with local security enabled, the UAS is started
 automatically as part of the boot process.

 The Group category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and ACCESS.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETGROUP, and including the master header file,
 LAN.H. For more information about these definitions,  see the "Example"
 section, later in this category.

 These are the Group API functions:


   þ   NetGroupAdd

   þ   NetGroupAddUser

   þ   NetGroupDel

   þ   NetGroupDelUser

   þ   NetGroupEnum

   þ   NetGroupGetInfo

   þ   NetGroupGetUsers

   þ   NetGroupSetInfo

   þ   NetGroupSetUsers



 Description

 A group is a set of users who share common permissions in the user accounts
 subsystem database. Group API functions create or delete groups, and review
 or adjust the membership of the groups. The group has a groupname that
 specifies the usernames of group members.

 An administrator can assign access permissions for all members of a group by
 supplying the groupname to NetAccessAdd instead of assigning each user an
 individual access permission record. For more information, see the Access
 Permissions category API functions.

 To create a group, an application calls NetGroupAdd, supplying a groupname.
 Initially, the group has no members. To assign members to the group, call
 NetGroupSetUsers. To add a user to an existing group, call NetGroupAddUser.
 To set general information about the group, call NetGroupSetInfo.


 NetGroupDelUser deletes a specified username from a group, and NetGroupDel
 disbands a group. NetGroupDel works whether or not the group has any
 members.

 Three Group category API functions retrieve information about the groups on
 a server: NetGroupEnum produces a list of all groups; NetGroupGetUsers lists
 all members of a specified group; and NetGroupGetInfo returns general
 information about the group.

 All Group API functions executed on a remote server (except
 NetGroupGetUsers) require that that server have user-level security.
 Attempting to execute one of these Group API functions on a remote server
 that has share-level security results in the return code
 ERROR_NOT_SUPPORTED.

 LAN Manager supports as many as 252 groups in addition to the special groups
 admins, guests, users, and local.

 Each user account automatically belongs to one of the special groups users,
 admins, or guests, according to the user's privilege level. Membership of
 these groups is indirectly controlled by the NetUserAdd, NetUserDel, and
 NetUserSetInfo functions. The local group has no members. For more
 information, see the User category API functions.

 Only NetGroupEnum and NetGroupGetUsers can operate on the special groups,
 but NetGroupEnum does not list the group local.


 Data Structures

 NetGroupAdd, NetGroupEnum, and NetGroupGetInfo use the group_info_0 data
 structure. These three functions and NetGroupSetInfo use the group_info_1
 data structure.

 NetGroupGetUsers and NetGroupSetUsers use the group_users_info_0 data
 structure.


 Group Information (level 0)

 The group_info_0 data structure has this format:

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

 where

 grpi0_name
   Contains an ASCIIZ string that specifies a groupname. The constant GNLEN
   is defined in the NETCONS.H header file.


 Group Information (level 1)

 The group_info_1 data structure has this format:

   struct group_info_1 {
       char       grpi1_name[GNLEN+1];
       char       grpi1_pad;
       char far * grpi1_comment;
   };

 where

 grpi1_name
   Contains an ASCIIZ string that specifies a groupname. The constant GNLEN
   is defined in the NETCONS.H header file.

 grpi1_pad
   Aligns the next data structure element on a word boundary.

 grpi1_comment
   Points to an ASCIIZ string that contains a remark for the group. This
   element can be a null string. The comment can have as many as
   MAXCOMMENTSZ+1 characters, as defined in the NETCONS.H header file.


 Group Membership Information (level 0)

 The group_users_info_0 data structure has this format:

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

 where

 grui0_name
   Contains an ASCIIZ string that specifies the name of a group member. The
   constant UNLEN is defined in the NETCONS.H header file.


 NetGroupAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupAdd creates a group account in the user accounts subsystem (UAS)
 database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupAdd on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupAdd (const char far *  pszServer,
                short             sLevel,
                char far *        pbBuffer,
                unsigned short    cbBuffer
               );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupAdd. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail (0 or 1) for the data to be set.

 pbBuffer
   Points to the buffer in which the data to be set is located. This buffer
   should contain a group_info_0 (level 0 call) or group_info_1 (level 1
   call) data structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_BadUsername                  2202    The username or groupname is
                                           invalid.

 NERR_GroupExists                  2223    The groupname already exists.

 NERR_UserExists                   2224    The user account already exists.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFNoRoom                    2228    The user accounts database is
                                           full.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetGroupAdd returns NERR_UserExists if the groupname specified is already
 being used as a username.

 NetGroupAdd supports level 0 and level 1 data structures. When adding a
 group account at level 0, the comment element is set to a null string
 because the group_info_0 data structure does not provide a comment element.


 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a single user to a group   NetGroupAddUser

 Assigning group permissions       NetAccessAdd

 Deleting a group account from a   NetGroupDel
 server

 Listing all groups on a server    NetGroupEnum

 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"

 Setting the list of all users in  NetGroupSetUsers
 a group


 NetGroupAddUser
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupAddUser adds a user to a group in the user accounts subsystem (UAS)
 database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupAddUser on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupAddUser (const char far *  pszServer,
                    char far *        pszGroupName,
                    char far *        pszUserName
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupAddUser. A null pointer or null string specifies the
   local computer.

 pszGroupName
   Points to an ASCIIZ string that specifies which group the user will join.

 pszUserName
   Points to an ASCIIZ string that specifies which user to add to the group.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_BadUsername                  2202    The username or groupname is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadUsername                  2202    The username or groupname is
                                           invalid.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_SpeGroupOp                   2234    This operation is not allowed on
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_SpeGroupOp                   2234    This operation is not allowed on
                                           this special group.

 NERR_UserInGroup                  2236    The user already belongs to this
                                           group.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If an attempt is made to add a user to the users, guests, admins, or local
 special groups, NetGroupAddUser returns NERR_SpeGroupOp.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Creating a new group              NetGroupAdd

 Defining group access             Access Permissions Category
 permissions

 Removing a user from a group      NetGroupDelUser

 Retrieving a list of group        NetGroupGetUsers
 members


 NetGroupDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupDel removes a group account from the user accounts subsystem (UAS)
 database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupDel on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupDel (const char far *  pszServer,
                char far *        pszGroupName
               );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupDel. A null pointer or null string specifies the local
   computer.

 pszGroupName
   Points to an ASCIIZ string that specifies which group to remove.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_NotPrimary                   2226    The specified server is not the
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_SpeGroupOp                   2234    This operation is not allowed on
                                           this special group.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 It is not necessary to remove all members from a group before deleting the
 group account. Deleting a group deletes it from the access control profiles,
 but does not delete the individual accounts of its members.

 If an attempt is made to delete one of the users, guests, admins, or local
 special groups, NetGroupDel returns NERR_SpeGroupOp.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a group to a server        NetGroupAdd

 Listing all groups on a server    NetGroupEnum

 Removing a user from a group      NetGroupDelUser


 NetGroupDelUser
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupDelUser removes a user from a particular group in the user accounts
 subsystem (UAS) database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupDelUser on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupDelUser (const char far *  pszServer,
                    char far *        pszGroupName,
                    char far *        pszUserName
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the remote server on
   which to execute NetGroupDelUser. A null pointer or null string specifies
   the local computer.

 pszGroupName
   Points to an ASCIIZ string that specifies the group from which to remove
   the user.

 pszUserName
   Points to an ASCIIZ string that specifies which user to remove from the
   group.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_SpeGroupOp                   2234    This operation is not allowed on
                                           this special group.

 NERR_UserNotInGroup               2237    The user is not a member of this
                                           group.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Removing a user from a group does not delete the user's account from the
 system.

 If an attempt is made to delete a user from the users, guests, admins, or
 local special groups, NetGroupDelUser returns NERR_SpeGroupOp.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a user to a group          NetGroupAddUser

 Deleting a group                  NetGroupDel


 NetGroupEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupEnum lists all group accounts in the user accounts subsystem (UAS)
 database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupEnum at level 1 on a remote server or on a computer that has
 local security enabled. No special privilege is required for level 0 calls.



 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupEnum (const char far *      pszServer,
                 short                 sLevel,
                 char far *            pbBuffer,
                 unsigned short        cbBuffer,
                 unsigned short far *  pcEntriesRead,
                 unsigned short far *  pcTotalAvail
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupEnum. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of group_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which the number of groups
   enumerated in the buffer pointed to by pbBuffer is returned. This count is
   valid only if NetGroupEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which the total number of groups is
   returned. This count is valid only if NetGroupEnum returns NERR_Success or
   ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetGroupEnum does not list the special group local.


 NetGroupGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupGetInfo gets group-related information.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupGetInfo at level 1 on a remote server or on a computer that
 has local security enabled. No special privilege is required for level 0
 calls.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupGetInfo (const char far *      pszServer,
                    char far *            pszGroupName,
                    short                 sLevel,
                    char far *            pbBuffer,
                    unsigned short        cbBuffer,
                    unsigned short far *  pcbTotalAvail
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupGetInfo. A null pointer or null string specifies the
   local computer.

 pszGroupName
   Points to an ASCIIZ string that contains the name of the group about which
   to get information.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a group_info_X data structure, where X is 0 or
   1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which the total number of bytes of
   information available is returned. This count is valid only if
   NetGroupGetInfo returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.


 NERR_SpeGroupOp                   2234    This operation is not allowed on
                                           this special group.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If an attempt is made to get information about the users, guests, admins, or
 local special groups, NetGroupGetInfo returns NERR_SpeGroupOp.


 NetGroupGetUsers
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupGetUsers returns a list of the members of a particular group in the
 user accounts subsystem (UAS) database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupGetUsers on a remote server or on a computer that has local
 security enabled, except when users request details about a group to which
 they belong. In this case, no special privilege is required.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupGetUsers (const char far *      pszServer,
                     const char far *      pszGroupName,
                     short                 sLevel,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcEntriesRead,
                     unsigned short far *  pcTotalAvail
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupGetUsers. A null pointer or null string specifies the
   local computer.

 pszGroupName
   Points to an ASCIIZ string that contains the name of the group whose
   members are to be listed.

 sLevel
   Specifies the level of detail requested; must be 0.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer pointed to by pbBuffer contains a sequence of
   group_users_info_0 data structures.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which the number of
   group_users_info_0 data structures in the buffer pointed to by pbBuffer is
   returned. This count is valid only if NetGroupGetUsers returns
   NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 pcTotalAvail
   Points to an unsigned short integer in which the total number of users in
   the group is returned. This count is valid only if NetGroupGetUsers
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetGroupGetUsers is the only function in the Group category that can operate
 on a remote server that has share-level security. All other Group category
 functions require the remote server to have user-level security.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all groups that contain   NetUserGetGroups
 a specific username

 Listing the names of groups on a  NetGroupEnum
 server


 NetGroupSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupSetInfo sets information for a given group in the user accounts
 subsystem (UAS) database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupSetInfo on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupSetInfo (const char far *  pszServer,
                    char far *        pszGroupName,
                    short             sLevel,
                    char far *        pbBuffer,
                    unsigned short    cbBuffer,
                    short             sParmNum
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupSetInfo. A null pointer or null string specifies the
   local computer.

 pszGroupName
   Points to an ASCIIZ string that contains the name of the group for which
   the information is to be set.

 sLevel
   Specifies the level of detail provided; must be 1.

 pbBuffer
   Points to the data to be set.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to reset all the group information or to change only a
   part of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a
   group_info_1 data structure, and the old group information is replaced by
   this new information. If sParmNum is any other defined value, only one
   element of the group information is changed, and pbBuffer must point to a
   valid value for that element.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The ACCESS.H header file
   defines these possible values for sParmNum:

 Code                  Value  Element of group_info_1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL           0      All elements.
 GRP1_PARMNUM_COMMENT  2      grpi1_comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_SpeGroupOp                   2234    This operation is not allowed on
                                           this special group.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If an attempt is made to set information for the users, guests, admins, or
 local special groups, NetGroupSetInfo returns NERR_SpeGroupOp.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"


 NetGroupSetUsers
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupSetUsers sets information about users who belong to a particular
 group.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetGroupSetUsers on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETGROUP
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetGroupSetUsers (const char far *  pszServer,
                     const char far *  pszGroupName,
                     short             sLevel,
                     char far *        pbBuffer,
                     unsigned short    cbBuffer,
                     unsigned short    cEntries
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetGroupSetUsers. A null pointer or null string specifies the
   local computer.

 pszGroupName
   Points to an ASCIIZ string that contains the name of the group to which
   the specified users belong.

 sLevel
   Specifies the level of detail supplied; must be 0.

 pbBuffer
   Points to the buffer in which the data to be set is stored. This data
   consists of a sequence of group_users_info_0 data structures.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 cEntries
   Specifies the number of group_users_info_0 data structures supplied in the
   buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFNoRoom                    2228    The user accounts database is
                                           full.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_SpeGroupOp                   2234    This operation is not allowed on
                                           this special group.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If an attempt is made to set a list of usernames for the users, guests,
 admins, or local special groups, NetGroupSetUsers returns NERR_SpeGroupOp.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"

 Setting a user's group            NetUserSetGroups
 membership





 Group Category Example

   /*
      NETGROUP.C -- a sample program demonstrating NetGroup API functions.

      This program requires that you have admin privilege or accounts
      operator privilege on the specified server.

         usage:  netgroup [-s \\server] [-g groupname] [-c comment]

         where  \\server  = Name of the server. A servername must be

                            preceded by two backslashes (\\).
                groupname = Name of the group to be added.
                comment   = Comment for the group to be added.

      API                  Used to...
      ================     =========================================
      NetGroupAdd          Add a new group
      NetGroupEnum         Display list of groups and group comments
      NetGroupSetInfo      Change a group's comment
      NetGroupGetInfo      Display a particular group's comment
      NetGroupSetUsers     Set the members of a group
      NetGroupAddUser      Add a new member to the group
      NetGroupDelUser      Delete a member from the group
      NetGroupGetUsers     List the members of a group
      NetGroupDel          Delete a group

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETGROUP
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   #define DEFAULT_GROUP      "TESTERS"
   #define DEFAULT_COMMENT    "Default comment for new group"
   #define NEW_COMMENT        "New group comment"
   #define TRIAL_USER1        "BRUCE"
   #define TRIAL_USER2        "LIZ"
   #define TRIAL_USER3        "JOHN"
   #define BIG_BUFF           32768

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pszServer = "";
      char *         pszNewGroup = DEFAULT_GROUP;
      char *         pszComment  = DEFAULT_COMMENT;
      char *         pszNewUser1 = TRIAL_USER1;
      char *         pszNewUser2 = TRIAL_USER2;
      char *         pszNewUser3 = TRIAL_USER3;
      char *         pbBuffer;               // Pointer to data buffer
      int            iArgv;                  // Index for arguments
      unsigned short iEntries;               // Index for entries read
      unsigned short cRead;                  // Count read
      unsigned short cAvail;                 // Count available
      unsigned short cbBuffer;               // Size of buffer, in bytes
      API_RET_TYPE   uReturnCode;            // API return code
      struct group_info_1 * pGroupInfo1;     // Pointer to group info
      struct group_users_info_0 * pGroupUsersInfo0;

      for (iArgv = 1; iArgv < argc; iArgv++)
      {
         if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/'))
         {
            switch (tolower(*(argv[iArgv]+1))) // Process switches
            {
               case 's':                       // -s servername
                  pszServer = argv[++iArgv];
                  break;
               case 'g':                       // -g groupname
                  pszNewGroup = argv[++iArgv];
                  break;
               case 'c':                       // -c comment
                  pszComment = argv[++iArgv];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetGroupAdd
   //
   //  This API adds a new group with info level 1.
   //========================================================================

      cbBuffer = sizeof(struct group_info_1);
      pGroupInfo1 = (struct group_info_1 *) SafeMalloc(cbBuffer);
      strcpy(pGroupInfo1->grpi1_name, pszNewGroup);
      pGroupInfo1->grpi1_comment = pszComment;

      uReturnCode = NetGroupAdd(
                        pszServer,              // Servername
                        1,                      // Info level
                        (char far *)pGroupInfo1,// Input buffer
                        cbBuffer);              // Size of buffer
      free(pGroupInfo1);

      printf("NetGroupAdd of group \"%s\" returned %u\n",
                 pszNewGroup, uReturnCode);

   //========================================================================
   //  NetGroupEnum
   //
   //  This API displays the list of current groupnames and group comments.
   //========================================================================

      cbBuffer = BIG_BUFF;                      // Can be up to 64K
      pbBuffer = SafeMalloc(cbBuffer);          // Data buffer

      uReturnCode = NetGroupEnum(
                        pszServer,              // Servername
                        1,                      // Info level
                        pbBuffer,               // Data returned here
                        cbBuffer,               // Size of buffer, in
   bytes
                        &cRead,                 // Count of entries read
                        &cAvail);               // Count of entries available

      printf("NetGroupEnum returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         pGroupInfo1 = (struct group_info_1 *) pbBuffer;
         for (iEntries = 0; iEntries < cRead; iEntries++)
         {
            printf("   %-24s - %Fs\n", pGroupInfo1->grpi1_name,
                      pGroupInfo1->grpi1_comment);
            pGroupInfo1++;
         }
         printf("%hu out of %hu entries returned\n", cRead, cAvail);
      }
      free(pbBuffer);

   //========================================================================
   //  NetGroupSetInfo
   //
   //  This API sets information for a group.
   //
   //  There are two ways to call NetGroupSetInfo. If sParmNum is set
   to
   //  PARMNUM_ALL, you must pass it a whole structure. Otherwise, you

   //  can set sParmNum to the structure element you want to change.
   The
   //  whole structure is used in this example to change the group comment.
   //========================================================================

      cbBuffer = sizeof(struct group_info_1) + MAXCOMMENTSZ + 1;
      pbBuffer = SafeMalloc(cbBuffer);          // Info buffer

      pGroupInfo1 = (struct group_info_1 *) pbBuffer;
      strcpy(pGroupInfo1->grpi1_name, pszNewGroup);

      /*
       * Data referenced by a pointer from within the fixed-length
       * portion of the data structure must be located outside the buffer
       * passed to the API or it will be ignored in remote NetGroupSetInfo

       * calls.
       */

      pGroupInfo1->grpi1_comment = NEW_COMMENT;

      uReturnCode = NetGroupSetInfo(
                        pszServer,              // Servername
                        pszNewGroup,            // Groupname
                        1,                      // Info level
                        pbBuffer,               // Data buffer
                        cbBuffer,               // Size of buffer, in
   bytes
                        PARMNUM_ALL);           // Parameter number code

      printf("NetGroupSetInfo returned %u\n", uReturnCode);
      printf("   Changing comment for group \"%s\" %s\n", pszNewGroup,
                        uReturnCode ? "failed" : "succeeded");

   //========================================================================
   //  NetGroupGetInfo
   //
   //  This API gets the information available about the new group.
   //========================================================================

      uReturnCode = NetGroupGetInfo(
                        pszServer,              // Servername
                        pszNewGroup,            // Groupname
                        1,                      // Info level
                        pbBuffer,               // Data buffer
                        cbBuffer,               // Size of buffer, in
   bytes
                        &cAvail);               // Count of bytes available

      printf("NetGroupGetInfo returned %u\n", uReturnCode);
      if (uReturnCode == NERR_Success)
      {
         printf("   %-24s - %Fs\n", pGroupInfo1->grpi1_name,
                        pGroupInfo1->grpi1_comment);
      }
      free(pbBuffer);

   //========================================================================
   //  NetGroupSetUsers
   //
   //  This API sets the list of users who belong to the new group.
   //========================================================================

      cbBuffer = sizeof(struct group_users_info_0) * 2;
      pbBuffer = SafeMalloc(cbBuffer);          // Info buffer

      pGroupUsersInfo0 = (struct group_users_info_0 *) pbBuffer;
      strcpy(pGroupUsersInfo0->grui0_name, pszNewUser1);
      pGroupUsersInfo0++;
      strcpy(pGroupUsersInfo0->grui0_name, pszNewUser2);

      uReturnCode = NetGroupSetUsers(
                        pszServer,              // Servername
                        pszNewGroup,            // Groupname
                        0,                      // Info level; must be
   0
                        pbBuffer,               // Data buffer
                        cbBuffer,               // Size of buffer, in
   bytes
                        2);                     // Entries

      printf("NetGroupSetUsers returned %u\n", uReturnCode);

   //========================================================================
   //  NetGroupAddUser
   //
   //  This API adds a user to the new group.
   //========================================================================

      uReturnCode = NetGroupAddUser(
                        pszServer,              // Servername
                        pszNewGroup,            // Groupname
                        pszNewUser3);           // Username to add

      printf("NetGroupAddUser for user \"%s\" returned %u\n",
                 pszNewUser3, uReturnCode);

   //========================================================================
   //  NetGroupDelUser
   //
   //  This API deletes a user from the new group.
   //========================================================================

      uReturnCode = NetGroupDelUser(
                        pszServer,              // Servername
                        pszNewGroup,            // Groupname
                        pszNewUser2);           // Username to delete

      printf("NetGroupDelUser for user \"%s\" returned %u\n",
                 pszNewUser2, uReturnCode);

   //========================================================================
   //  NetGroupGetUsers
   //
   //  This API lists the users who belong to the new group.
   //========================================================================

      uReturnCode = NetGroupGetUsers(
                        pszServer,              // Servername
                        pszNewGroup,            // Groupname
                        0,                      // Info level; must be
   0
                        pbBuffer,               // Buffer
                        cbBuffer,               // Size of buffer
                        &cRead,                 // Count of entries read
                        &cAvail);               // Count of entries available





      printf("NetGroupGetUsers returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         pGroupUsersInfo0 = (struct group_users_info_0 *) pbBuffer;
         for (iEntries = 0; iEntries < cRead; iEntries++)
         {
            printf("   %s\n", pGroupUsersInfo0->grui0_name);
            pGroupUsersInfo0++;
         }
      }
      free(pbBuffer);

   //========================================================================
   //  NetGroupDel
   //
   //  This API deletes the new group.
   //========================================================================

      uReturnCode = NetGroupDel(pszServer,      // Servername
                                pszNewGroup);   // Groupname to delete
      free(pGroupInfo1);

      printf("NetGroupDel of group \"%s\" returned %u\n",
                 pszNewGroup, uReturnCode);

      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server]"\
                      " [-g groupname] [-c comment]\n", pszProgram);
      exit(1);
   }





 Handle Category

 Handle API functions get and set information related to the specified
 character-device or named-pipe handle. They require that the Workstation
 service be started.

 The Handle category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and CHARDEV.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETHANDLE, and including the master header file,
 LAN.H. For more information about these definitions, see the "Example"
 section, later in this category.

 These are the Handle API functions:


   þ   NetHandleGetInfo

   þ   NetHandleSetInfo



 Description

 NetHandleGetInfo and NetHandleSetInfo allow an application to examine or
 change the communications parameters for character-device handles and
 named-pipe handles, provided that the handles refer to devices or pipes
 opened on a remote server.

 The adjustable parameters are based on the LANMAN.INI file entries for
 chartime and charcount, which determine the workstation data structure
 elements wkiX_chartime and wkiX_charcount, where X is the level of detail
 requested. These values specify when LAN Manager sends a packet of
 information over the network. Rather than writing single bytes to the
 network, LAN Manager saves the data in a buffer until chartime milliseconds
 have elapsed or until the buffer contains charcount characters.

 The handle_info_1 data structure elements hdli1_chartime and hdli1_charcount
 take their initial values from the workstation data structure elements
 wkiX_chartime and wkiX_charcount. The Handle API functions allow these
 values to be inspected and modified on a handle-by-handle basis.

 NetHandleGetInfo can also be used to identify the user of a named pipe,
 provided that the pipe has been opened from a remote server.

 Handle API functions can be called only locally (there is no servername
 parameter).


 Data Structures

 The handle_info_1 data structure is used with both NetHandleGetInfo  and
 NetHandleSetInfo. The handle_info_2 data structure is used only with
 NetHandleGetInfo.


 Handle Information (level 1)

 The handle_info_1 data structure has this format:

   struct handle_info_1 {
       unsigned long   hdli1_chartime;
       unsigned short  hdli1_charcount;
   };

 where

 hdli1_chartime
   Specifies the amount of time (in milliseconds) that the workstation
   collects data to send to a character device or named pipe.

 hdli1_charcount
   Specifies the number of characters (in bytes) that the workstation stores
   before it sends data to a character device or named pipe.


 Handle Information (level 2)

 The handle_info_2 data structure has this format:

   struct handle_info_2 {
       char far *   hdli2_username;
   };

 where

 hdli2_username
   Points to the name of the user who has opened a named pipe. This username
   is available only for a handle on the serving side of a valid named pipe
   that has been opened by a remote computer. If the named pipe has been
   opened locally, the call to NetHandleGetInfo returns
   ERROR_INVALID_PARAMETER.


 NetHandleGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetHandleGetInfo retrieves handle-specific information for character-device
 and named-pipe handles.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only, levels 1 and 2

   þ   MS OS/2 version 1.1, local only, level 1 only

   þ   MS-DOS, local only, level 1 with remote named pipes only



 Privilege Level

 Access privilege is determined by the access restrictions to the named pipe
 or character device being accessed.


 Syntax

   #define INCL_NETHANDLE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetHandleGetInfo (unsigned short        hHandle,
                     short                 sLevel,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcbTotalAvail
                    );

 where

 hHandle
   Identifies a communication-device queue or a named pipe.

 sLevel
   Specifies the level of detail (1 or 2) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a handle_info_1 data structure (level 1 call)
   or a handle_info_2 data structure (level 2 call).

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetHandleGetInfo returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          started.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetHandleGetInfo can be called at level 1 only if the value of hHandle is a
 valid handle to a named pipe or character device that exists on a remote
 server.

 NetHandleGetInfo can be called at level 2 only if the value of hHandle is a
 handle to the server side of a valid named pipe opened on a remote computer.
 If the named pipe has been opened locally or if the handle is not for a
 named pipe, NetHandleGetInfo returns ERROR_INVALID_PARAMETER.


 NetHandleSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetHandleSetInfo sets handle-specific information for character-device and
 named-pipe handles.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only, level 1 only

   þ   MS OS/2 version 1.1, local only, level 1 only

   þ   MS-DOS, local only, level 1 with remote named pipes only



 Privilege Level

 Access privilege is determined by the access restrictions to the named pipe
 or character device being accessed.


 Syntax

   #define INCL_NETHANDLE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetHandleSetInfo (unsigned short  hHandle,
                     short           sLevel,
                     char far *      pbBuffer,
                     unsigned short  cbBuffer,
                     unsigned short  sParmNum
                    );

 where

 hHandle
   Identifies a communication-device queue or a named pipe.

 sLevel
   Specifies the level of detail provided; must be 1.

 pbBuffer
   Points to the data to be set.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to reset all handle information or to change only a part
   of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a handle_info_1
   data structure, and the previous handle information is replaced by this
   new information. If sParmNum is any other defined value, only one element
   of the handle information  is changed, and pbBuffer must point to a valid
   value for that element.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The CHARDEV.H header file
   defines these possible values for sParmNum:

 Code                   Value  Element of handle_info_1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL            0      All elements.
 HANDLE_SET_CHAR_TIME   1      hdli1_chartime
 HANDLE_SET_CHAR_COUNT  2      hdli1_charcount
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ







 Handle Category Example

   /*
      NETHAND1.C -- a sample program demonstrating NetHandle API functions
                    for the server side of named pipes.

      This program must be run on a computer that has the Server service
      running. It is to be used in conjunction with the program NETHAND2
      running on a workstation.

         usage:  nethand1 [-p pipename] [-m message]

         where  pipename = Name of the pipe to create.
                message  = Message to be sent through the pipe.

      Run NETHAND1 on the server to create a named pipe, then run
      NETHAND2 on a workstation to connect to that named pipe.

      API                  Used to...
      ================     ==========================================
      NetHandleGetInfo     Get the name of the user of the named pipe

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_BASE
   #define     INCL_DOSNMPIPES
   #include    <os2.h>        // MS OS/2 base header files

   #define     INCL_NETERRORS
   #define     INCL_NETHANDLE
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>
   #include    <chardev.h>
   #include    <io.h>

   #define PIPENAMELEN        128
   #define BUFFLEN            128
   #define PIPE_BUFFSIZE      2048
   #define DEFAULT_MESSAGE    "Message from server"
   #define DEFAULT_PIPE       "handtest"
   #define OPENMODE            NP_ACCESS_DUPLEX
   #define PIPEMODE            NP_READMODE_BYTE | NP_TYPE_BYTE | NP_WAIT
   | \
                               NP_UNLIMITED_INSTANCES

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char * pszMessage  = DEFAULT_MESSAGE;  // Message to send down
   pipe
      char * pszPipeName = DEFAULT_PIPE;     // Supplied pipename
      char   achBuffer[BUFFLEN];             // Data buffer
      char   achFullPipe[PIPENAMELEN];       // Full name of pipe to
   open
      int    iArgv;                          // Index for arguments
      unsigned short hPipe;                  // Handle to named pipe
      unsigned short cbAvail;                // Bytes available from
   GetInfo
      unsigned short usReturnCode;           // MS OS/2 return code
      API_RET_TYPE uReturnCode;              // LAN Manager API return
   code
      struct handle_info_2 * pHandleInfo2;

      for (iArgv = 1; iArgv < argc; iArgv++)
      {
         if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/'))
         {
            switch (tolower(*(argv[iArgv]+1))) // Process switches
            {
               case 'p':                       // -p pipename
                  pszPipeName = argv[++iArgv];
                  break;
               case 'm':                       // -m message
                  pszMessage = argv[++iArgv];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

      strcpy(achFullPipe, "\\PIPE\\");       // Set up named pipe
      strcat(achFullPipe, pszPipeName);






      printf("Creating Named Pipe %s\n", achFullPipe);

      if (usReturnCode = DosMakeNmPipe(
                            achFullPipe,     // Name of pipe to open
                            &hPipe,          // Handle to opened pipe
                            OPENMODE,        // Full duplex
                            PIPEMODE,        // Unlimited opens, blocked
   mode
                            PIPE_BUFFSIZE,   // Outgoing buffer size
                            PIPE_BUFFSIZE,   // Incoming buffer size
                            0L))             // Time-out value
      {
         printf( "DosMakeNmPipe failed (error %hu).\n", usReturnCode
   );
         exit(1);
      }

      printf("Waiting for Connect to Pipe... \n" );

      if (usReturnCode = DosConnectNmPipe(hPipe))
      {
         printf("DosConnectNmPipe failed (error %hu).\n", usReturnCode);
         exit(1);
      }

      printf("Waiting for message from pipe... \n" );

      if (read( hPipe, achBuffer, BUFFLEN ) == -1)
      {
         printf("   Read message failed (error %d)\n", errno);
         exit(1);
      }
      else
      {
         printf("   \"%s\"\n", achBuffer);
      }

      /*
       * Write message to the named pipe. Make sure that the message
       * length specified includes the terminating NUL.
       */

      printf("Writing message \"%s\" \n", pszMessage );

      if (write(hPipe, pszMessage, strlen(pszMessage) + 1) == -1)
      {
         printf("   Write message failed (error %d)\n", errno);
         exit(1);
      }

   //========================================================================
   //  NetHandleGetInfo
   //
   //  This API gets the name of the user who is connected to the named
   pipe.
   //  It can be called only at level 2 on the server end of a handle.
   //========================================================================

      uReturnCode = NetHandleGetInfo(
                        hPipe,               // Handle to named pipe
                        2,                   // Level 2
                        achBuffer,           // Data returned here
                        BUFFLEN,             // Size of buffer, in bytes
                        (unsigned short far *) &cbAvail);

      printf("NetHandleGetInfo returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         pHandleInfo2 = (struct handle_info_2 *) achBuffer;
         printf("   User of the named pipe is %Fs\n",
                                   pHandleInfo2->hdli2_username );
      }

      do                                     // Wait for disconnect
      {
      } while (DosConnectNmPipe(hPipe) == 0 );

      if ((usReturnCode = DosDisConnectNmPipe(hPipe)) == 0)
         printf("Pipe disconnected. \n");
      else
      {
         printf("DosDisConnectNmPipe failed (error %hu).\n", usReturnCode);
         exit(1);
      }
      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-p pipename] [-m message] \n", pszProgram);
      exit(1);
   }

   /*
      NETHAND2.C -- a sample program demonstrating NetHandle API functions
                    for the workstation side of named pipes.

      This program must be run on a computer that has the Workstation
   service
      running. It is to be used in conjunction with the program NETHAND1
      running on a server.

         usage: nethand2 -s \\server [-p pipename] [-m message]

         where  \\server = Name of the server. A servername
                           must be preceded by two backslashes (\\).
                pipename = Name of the pipe to connect to.
                message  = Message to be sent through the pipe.

      Run NETHAND1 on the server to create a named pipe, then run
      NETHAND2 on a workstation to connect to that named pipe.

      API                  Used to...
      ================     ================================================
      NetHandleGetInfo     Get the values for charcount and chartime
      NetHandleSetInfo     Set the value for charcount to half the original

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */


   #define     INCL_NETERRORS
   #define     INCL_NETHANDLE
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>
   #include    <chardev.h>
   #include    <fcntl.h>
   #include    <sys\types.h>
   #include    <sys\stat.h>
   #include    <share.h>
   #include    <io.h>

   #define PIPENAMELEN        128
   #define BUFFLEN            128
   #define DEFAULT_MESSAGE    "Message from workstation"
   #define DEFAULT_PIPE       "handtest"

   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char * pszServer   = NULL;
      char * pszMessage  = DEFAULT_MESSAGE;  // Message to send down
   pipe
      char * pszPipeName = DEFAULT_PIPE;     // Supplied pipename
      char   achFullPipe[PIPENAMELEN];       // Full name of pipe
      char   achBuffer[BUFFLEN];             // Data buffer
      int    iArgv;                          // Index for arguments
      unsigned short hPipe;                  // Handle to named pipe
      unsigned short cbAvail;                // Bytes available from
   GetInfo
      unsigned short cbCharCount;            // Pipe charcount
      API_RET_TYPE uReturnCode;              // LAN Manager API return
   code
      struct handle_info_1 HandleInfo1;

      for (iArgv = 1; iArgv < argc; iArgv++)
      {
         if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/'))
         {
            switch (tolower(*(argv[iArgv]+1))) // Process switches
            {
               case 's':                       // -s servername
                  pszServer = argv[++iArgv];
                  break;
               case 'p':                       // -p pipename
                  pszPipeName = argv[++iArgv];
                  break;
               case 'm':                       // -m message
                  pszMessage = argv[++iArgv];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

      if (pszServer == NULL)                 // Must specify a servername
      {
         Usage(argv[0]);
      }




                                             // Set up full name of pipe
      strcpy(achFullPipe, pszServer);
      strcat(achFullPipe, "\\PIPE\\");
      strcat(achFullPipe, pszPipeName);

      printf("Opening named pipe %s\n", achFullPipe);
      if ((hPipe = sopen(achFullPipe, O_BINARY | O_RDWR, SH_DENYNO))==  -1)
      {
         printf( "   Open of pipe failed (error %d).\n", errno );
         exit(1);
      }


   // NetHandleGetInfo
   //
   //  This API gets the values for chartime and charcount for the named
   pipe.
   //  These values will be the same as the default values for the
 workstation
   //  as listed in the LANMAN.INI file (unless explicitly altered).
   This API
   //  can be called only at level 1 on the workstation end of a
 serial-device
   //  handle.

      uReturnCode = NetHandleGetInfo(
                        hPipe,                    // Handle to named
   pipe
                        1,                        // Level 1
                        (char far *)&HandleInfo1, // Data returned here
                        sizeof(struct handle_info_1),
                        (unsigned short far *) &cbAvail);

      printf("NetHandleGetInfo returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         cbCharCount = HandleInfo1.hdli1_charcount;
         printf("   Chartime  = %ld\n", HandleInfo1.hdli1_chartime);
         printf("   CharCount = %hu\n", cbCharCount);
      }

   //========================================================================
   //  NetHandleSetInfo
   //
   //  This API sets the value for charcount to half the default value.
   //  There are two ways to call NetHandleSetInfo: If sParmNum is set
   to
   //  PARMNUM_ALL, you must pass a whole structure. Otherwise, you can

   //  set sParmNum to the element of the structure you want to change
   and
   //  pass a pointer to the value. The second method is shown here.
   //========================================================================
      cbCharCount /= 2;
      printf("Setting the charcount to %hu\n", cbCharCount);

      uReturnCode = NetHandleSetInfo(
                        hPipe,                    // Handle to named
   pipe
                        1,                        // Level; must be 1
                        (char far *)&cbCharCount, // Data to be set
                        sizeof(unsigned short),   // Size of buffer
                        HANDLE_SET_CHAR_COUNT);   // Set the charcount
   only

      printf("NetHandleSetInfo returned %u\n", uReturnCode);

                                                  // Verify the values
   set
      uReturnCode = NetHandleGetInfo(
                        hPipe,                    // Handle to named
   pipe
                        1,                        // Level 1
                        (char far *)&HandleInfo1, // Data returned here
                        sizeof(struct handle_info_1),
                        (unsigned short far *) &cbAvail);

      printf("NetHandleGetInfo returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         printf("   Chartime  = %lu\n", HandleInfo1.hdli1_chartime);
         printf("   CharCount = %hu\n", HandleInfo1.hdli1_charcount);
      }

   /*
       * Write a message to the named pipe. Make sure that the
       * message length specified includes the terminating NUL.
       */

      printf("Writing \"%s\" to pipe... \n", pszMessage);

      if (write(hPipe, pszMessage, strlen(pszMessage) + 1) == -1)
      {
         printf("   Write message failed (error %d)\n", errno);
         exit(1);
      }

   printf("Waiting for message from pipe... \n" );

      if (read(hPipe, achBuffer, BUFFLEN) == -1)
      {
         printf("   Read message failed (error %d)\n", errno);
         exit(1);
      }
      printf("    \"%s\"\n", achBuffer);

      printf("Closing pipe...\n");           // Close the pipe
      if (close(hPipe))
      {
         printf("   Close handle failed (error %d)\n", errno);
         exit(1);
      }
      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s -s \\\\server [-p pipename] [-m message]
   \n",
                 pszProgram);
      exit(1);
   }









 Mailslot Category

 Mailslot API functions provide one-way interprocess communication (IPC).
 They require that the NETWKSTA device driver be installed and, when trying
 to access remote resources, that the Workstation service be started.

 The Mailslot category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and MAILSLOT.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETMAILSLOT, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Mailslot API functions:


   þ   DosDeleteMailslot

   þ   DosMailslotInfo

   þ   DosMakeMailslot

   þ   DosPeekMailslot

   þ   DosReadMailslot

   þ   DosWriteMailslot



 Description

 An application can use LAN Manager mailslots to send data to local or remote
 applications on the network. Mailslot API functions manage mailslots and
 mailslot messages.

 DosMakeMailslot creates a mailslot and returns its handle. DosPeekMailslot
 reads the highest-priority, most current message without removing it from
 the mailslot. DosReadMailslot reads the highest-priority, most current
 message, and then removes it from the mailslot. DosWriteMailslot writes a
 message to a mailslot. Applications can write messages to any mailslot on
 any computer or in any domain on the network. The message can be any form of
 dataÄit need not be an ASCIIZ string. DosMailslotInfo retrieves information
 about a particular mailslot. DosDeleteMailslot removes a mailslot,
 discarding all unread messages.

 There are two classes of mailslot message delivery: first-class and
 second-class. First-class messages are successfully delivered or the sender
 is notified with the appropriate error return code. If a mailslot is full
 when a first-class message arrives, DosWriteMailslot waits until a message
 is read and removed from the mailslot (using DosReadMailslot) or until the
 delivery time-out expires (controlled by the cTimeout parameter in
 DosWriteMailslot). First-class messages can be used only with mailslots on
 the local computer and remote servers.

 Successful delivery of second-class messages is not guaranteed. There is no
 way to determine whether a message arrived successfully. The simpler
 delivery system tends to make second-class messages faster than first-class
 messages. Second-class messages can be sent to any remote computer, not just
 to remote servers, and can be sent to multiple computers simultaneously.

 Each message is assigned a priority from 0 (lowest priority) through 9
 (highest priority) using the DosWriteMailslot usPriority parameter. Messages
 are stored in the mailslot sorted first by priority, then by time of
 arrival. High-priority messages are placed ahead of previously stored
 messages that have the same or lower priority. Since MS OS/2 is a
 multitasking operating system, this scheme cannot be guaranteed at any
 instant (messages could be received but not yet sorted).


 DosPeekMailslot and DosReadMailslot read the oldest message of highest
 priority. Since new messages can be placed ahead of others, a message read
 by DosReadMailslot might not be the same one read earlier by
 DosPeekMailslot.

 DosMailslotInfo retrieves information about a mailslot, such as its maximum
 size, the maximum size of messages it can accept, the priority and size of
 the next message, and the total number of messages waiting to be read.

 To write data to a mailslot on a remote computer, the name of the mailslot
 must include a computername. This enables multiple remote computers to use
 the same mailslot name locally but to use different names on the network
 (the computername must be unique).

 An application can write the same message to all computers in a domain that
 have a mailslot with a particular name. In this case, only second-class
 delivery is supported. Specifying an asterisk (*) as the computername when
 calling DosWriteMailslot sends the same message to the named mailslot on
 every computer in the sender's primary domain. Use this mailslot format:

 \\*\mailslot\mailslotname

 Specifying a domain name for the computername when calling DosWriteMailslot
 sends the same message to the named mailslot on every computer in the
 specified domain. Use this mailslot format:

 \\domainname\mailslot\mailslotname

 Workstations can receive only second-class messages, with as many as 400
 bytes per message. Servers can receive first-class or second-class messages
 of any size.

 Mailslots can be read or deleted only by the process that created them.
 Mailslots created by a process are deleted when that process ends.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Interprocess communication (IPC)  Appendix F, "Network Considerations for
                                   Named Pipes"


 DosDeleteMailslot
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosDeleteMailslot deletes a mailslot, discarding all messages whether or not
 they have been read.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege level is required to successfully execute
 DosDeleteMailslot.


 Syntax

   #define INCL_NETMAILSLOT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   DosDeleteMailslot (unsigned  hMailslot);

 where

 hMailslot
   Specifies a handle for the mailslot to be deleted. The handle must have
   been returned by a previous call to DosMakeMailslot.

 Return Codes

 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.

 ERROR_INVALID_HANDLE  6       The handle specified is invalid.

 NERR_NetNotStarted    2102    The LAN Manager NETWKSTA driver is not
                               installed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Remarks

 Mailslots are generally deleted as the last step in a program's execution. A
 mailslot can be deleted only by the application that created it.


 DosMailslotInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosMailslotInfo retrieves information about a particular mailslot.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege level is required to successfully execute
 DosMailslotInfo.


 Syntax

   #define INCL_NETMAILSLOT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   DosMailslotInfo (unsigned              hMailslot,
                    unsigned short far *  pcbMessageSize,
                    unsigned short far *  pcbMailslotSize,
                    unsigned short far *  pcbNextSize,
                    unsigned short far *  pusNextPriority,
                    unsigned short far *  pcMessages
                   );

 where

 hMailslot
   Specifies a handle for the mailslot about which information is requested.
   The handle must have been returned by a previous call to DosMakeMailslot.

 pcbMessageSize
   Points to an unsigned short integer in which the maximum message size (in
   bytes) that the mailslot can accept is returned.

 pcbMailslotSize
   Points to an unsigned short integer in which the size (in bytes) of the
   mailslot is returned.

 pcbNextSize
   Points to an unsigned short integer in which the size (in bytes) of the
   next message in the mailslot is returned. If this value is 0, no message
   is available.

 pusNextPriority
   Points to an unsigned short integer in which the priority (0 through 9) of
   the next message in the mailslot is returned.

 pcMessages
   Points to an unsigned short integer in which a count of the messages in
   the mailslot is returned.

 Return Codes

 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.

 ERROR_INVALID_HANDLE  6       The handle specified is invalid.

 ERROR_BROKEN_PIPE     109     The pipe has been closed or the pipe is not
                               being read.

 NERR_NetNotStarted    2102    The LAN Manager NETWKSTA driver is not
                               installed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Remarks

 DosMailslotInfo can be used before DosReadMailslot or DosPeekMailslot to
 determine the buffer size needed to read the next message. This may fail,
 because a higher-priority message can arrive after the DosMailslotInfo call
 and before the identified message is read.

 If the mailslot is deleted while being queried by DosMailslotInfo, the error
 code ERROR_BROKEN_PIPE is returned.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Creating (and obtaining the       DosMakeMailslot
 handle for) a mailslot

 Retrieving the most current       DosReadMailslot
 message in a mailslot

 Writing a message to a mailslot   DosWriteMailslot


 DosMakeMailslot
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosMakeMailslot creates a mailslot on a local computer and returns a handle
 to that mailslot. The other Mailslot API functions can then use this handle.


 The mailslot name supplied to the function should be in the format

 \mailslot\mailslotname

 where mailslotname is a unique set of characters that distinguish the
 mailslot from other mailslots on the computer (for example,
 \mailslot\test\slot1).


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege level is required to successfully execute
 DosMakeMailslot.


 Syntax

   #define INCL_NETMAILSLOT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   DosMakeMailslot (const char far *  pszName,
                    unsigned short    cbMessageSize,
                    unsigned short    cbMailslotSize,
                    unsigned far *    phMailslot
                   );

 where

 pszName
   Points to an ASCIIZ string that contains the name of the mailslot.

 cbMessageSize
   Specifies the maximum message size (in bytes) that the mailslot can
   accept. Mailslots can accept messages that have as many as 65,475 bytes.

 cbMailslotSize
   Specifies the size (in bytes) of the mailslot. This parameter must be 0,
   or it must be equal to or exceed cbMessageSize. If this value is 0,
   DosMakeMailslot sets a value based on cbMessageSize.

 phMailslot
   Points to an unsigned integer that is the returned handle for the
   mailslot. This handle must be used for all subsequent operations on the
   mailslot.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_ALREADY_EXISTS              183     A loader error occurred.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Mailslot names must be unique; no two mailslots on any one computer can have
 the same name. An attempt to create a mailslot with the name of a mailslot
 that already exists results in ERROR_ALREADY_EXISTS being returned.

 You cannot pass mailslot handles to other processes using the DosExecPgm
 function, but mailslot handles can be shared among threads in a single
 process. Multiple threads can use the handle to read or write data to the
 mailslot.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Deleting a mailslot               DosDeleteMailslot

 Retrieving information about a    DosMailslotInfo
 mailslot


 DosPeekMailslot
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPeekMailslot reads the highest-priority, most current message in a
 mailslot without removing it.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege level is required to successfully execute
 DosPeekMailslot.


 Syntax

   #define INCL_NETMAILSLOT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   DosPeekMailslot (unsigned              hMailslot,
                    char far *            pbBuffer,
                    unsigned short far *  pcbReturned,
                    unsigned short far *  pcbNextSize,
                    unsigned short far *  pusNextPriority
                   );

 where

 hMailslot
   Specifies the handle of the mailslot to be read. The handle must have been
   returned by a previous call to DosMakeMailslot.

 pbBuffer
   Points to the buffer in which to store the returned message. The buffer
   should be as large as the cbMessageSize parameter passed to
   DosMakeMailslot.

 pcbReturned
   Points to an unsigned short integer in which the size (in bytes) of the
   new message is returned. If no message is available, pcbReturned is 0.

 pcbNextSize
   Points to an unsigned short integer in which the size (in bytes) of the
   next message in the mailslot is returned. If the mailslot does not contain
   another message, pcbNextSize is 0.

 pusNextPriority
   Points to an unsigned short integer in which the priority (0 through 9) of
   the next message in the mailslot is returned. This value is valid only if
   pcbNextSize is not 0.

 Return Codes

 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.

 ERROR_INVALID_HANDLE  6       The handle specified is invalid.

 ERROR_BROKEN_PIPE     109     The pipe has been closed or the pipe is not
                               being read.

 NERR_NetNotStarted    2102    The LAN Manager NETWKSTA driver is not
                               installed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Remarks

 There is no guarantee that a message read by calling DosPeekMailslot will be
 the same message read by a subsequent call to DosReadMailslot. A
 higher-priority message can arrive between the two calls.

 If the mailslot is deleted while being queried by DosPeekMailslot, the error
 code ERROR_BROKEN_PIPE is returned.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Creating a mailslot               DosMakeMailslot

 Reading and removing a message    DosReadMailslot

 Writing a message to a mailslot   DosWriteMailslot


 DosReadMailslot
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosReadMailslot reads and then removes the highest-priority, most current
 message in a mailslot.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege level is required to successfully execute
 DosReadMailslot.


 Syntax

   #define INCL_NETMAILSLOT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   DosReadMailslot (unsigned              hMailslot,
                    char far *            pbBuffer,
                    unsigned short far *  pcbReturned,
                    unsigned short far *  pcbNextSize,
                    unsigned short far *  pusNextPriority,
                    long                  cTimeout
                   );

 where

 hMailslot
   Specifies the handle of the mailslot to be read. The handle must have been
   returned by a previous call to DosMakeMailslot.

 pbBuffer
   Points to the buffer in which to store the returned message. The buffer
   should be as large as the cbMessageSize parameter passed to
   DosMakeMailslot.

 pcbReturned
   Points to an unsigned short integer in which the size (in bytes) of the
   new message is returned. If no message is available, pcbReturned is 0.

 pcbNextSize
   Points to an unsigned short integer in which the size (in bytes) of the
   next message in the mailslot is returned. If the mailslot does not contain
   another message, pcbNextSize is 0.

 pusNextPriority
   Points to an unsigned short integer in which the priority (0 through 9) of
   the next message in the mailslot is returned. This value is valid only if
   pcbNextSize is not 0.

 cTimeout
   Specifies how many milliseconds to wait if a message is not available
   immediately. If this value is 0, DosReadMailslot does not wait; if it is
   MAILSLOT_NO_TIMEOUT, DosReadMailslot waits indefinitely.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.

 ERROR_INVALID_HANDLE  6       The handle specified is invalid.

 ERROR_INTERUPT        95      The system call was interrupted.

 ERROR_BROKEN_PIPE     109     The pipe has been closed or the pipe is not
                               being read.

 ERROR_SEM_TIMEOUT     121     A time-out occurred from the Semaphore API
                               functions.

 NERR_NetNotStarted    2102    The LAN Manager NETWKSTA driver is not
                               installed.

 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If the mailslot is deleted while being queried by DosReadMailslot, the error
 code ERROR_BROKEN_PIPE is returned.

 If no message is waiting to be read, and none arrives within the period
 specified by cTimeout, DosReadMailslot returns ERROR_SEM_TIMEOUT.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Creating a mailslot               DosMakeMailslot

 Reading a message without         DosPeekMailslot
 removing it

 Writing a message to a mailslot   DosWriteMailslot


 DosWriteMailslot
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosWriteMailslot writes a message to a particular mailslot.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege level is required to successfully execute
 DosWriteMailslot.


 Syntax

   #define INCL_NETMAILSLOT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   DosWriteMailslot (const char far *  pszName,
                     const char far *  pbBuffer,
                     unsigned short    cbBuffer,
                     unsigned short    usPriority,
                     unsigned short    usClass,
                     long              cTimeout
                    );

 where

 pszName
   Points to an ASCIIZ string that contains the name of the mailslot where
   the message is to be written.

 pbBuffer
   Points to the data to write to the mailslot. If the data to be written is
   an ASCIIZ string, the NUL terminator must be included in the count of
   bytes to send.

 cbBuffer
   Specifies the number of bytes of data to be written to the mailslot.

 usPriority
   Assigns a priority (0 through 9) to the message. High-priority messages
   are generally placed ahead of previously stored messages that have lower
   priority.

 usClass
   Specifies the class of mail service to be provided. A value of 1 specifies
   first-class service; 2 specifies second-class service.

 cTimeout
   Specifies the number of milliseconds to wait for space to become available
   in the mailslot for this message. If this value is 0, DosWriteMailslot
   does not wait; if it is MAILSLOT_NO_TIMEOUT, DosWriteMailslot waits
   indefinitely.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_INVALID_FUNCTION            1       The function is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_BUSY                54      The network is busy.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INTERUPT                    95      The system call was interrupted.

 ERROR_BROKEN_PIPE                 109     The pipe has been closed or the
                                           pipe is not being read.

 ERROR_SEM_TIMEOUT                 121     A time-out occurred from the
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_SEM_TIMEOUT                 121     A time-out occurred from the
                                           Semaphore API functions.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosWriteMailslot accepts mailslot names in both a local and a remote format,
 as follows:

 Format                                  Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 \mailslot\mailslotname                  Local mailslot.
 \\computername\mailslot\mailslotname    Remote mailslot.
 \\domainname\mailslot\mailslotname      Mailslot on another domain.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 To send a message to all computers in the primary domain that have a local
 mailslot with a particular name, an application should pass the pszName
 parameter (\\*\mailslot\mailslotname) and the usClass parameter 2 to
 DosWriteMailslot.

 Second-class messages have as many as 400 bytes when written to remote
 workstations or entire domains; they can be any size when written to local
 computers or remote servers.

 When DosWriteMailslot is called with the workstation not started and the
 name of a mailslot on a remote computer supplied, DosWriteMailslot returns
 the error code ERROR_INVALID_FUNCTION.

 If the mailslot is deleted while being used by DosWriteMailslot,
 ERROR_BROKEN_PIPE is returned.

 If a first-class message is being sent, but it is not read within the period
 specified by cTimeout, DosWriteMailslot returns ERROR_SEM_TIMEOUT.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Creating a mailslot               DosMakeMailslot

 Reading a message                 DosReadMailslot





 Mailslot Category Example

   /*
      NETMAIL.C -- a sample program demonstrating Mailslot API functions.

      This program requires no special privilege.
        usage:  netmail  [-m mailslot] [-s size] [-t text] [-c class]
                         [-p priority] [-i iterations]
        where  mailslot   = Name of mailslot to be used.
               size       = Maximum message size for mailslot.
               text       = Text of message sent to mailslot.
               class      = Class of message sent to mailslot (1 or 2).
               priority   = Priority of message sent to mailslot (0 to
   9).
               iterations = Number of times to send the message.

      API                  Used to...
      =================    ==================================================
      DosMakeMailslot      Make a mailslot on the local computer
      DosWriteMailslot     Write a message to the created mailslot
      DosMailslotInfo      Get information about the mailslot and print
   it
      DosPeekMailslot      Read the most current message without removing
   it
      DosReadMailslot      Read and then remove the most current message
      DosDeleteMailslot    Delete the created mailslot

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETERRORS
   #define     INCL_NETMAILSLOT
   #include    <lan.h>             // LAN Manager header files

   #include    <stdio.h>           // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"         // Internal routine header file

   #define     DEFAULT_MAILSLOT    "\\mailslot\\testname"
   #define     DEFAULT_MESSAGE     "message sent to mailslot"
   #define     DEFAULT_MSGSIZE     1024       // Max. message size
   #define     DEFAULT_CLASS       1          // First class
   #define     DEFAULT_PRIORITY    0          // Lowest priority
   #define     DEFAULT_ITERATIONS  1          // Send message once
   void Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pszMailslot = DEFAULT_MAILSLOT;   // Mailslot to
   use
      char *         pszMessage  = DEFAULT_MESSAGE;    // Message to
   be sent
      char *         pbBuffer;                // Pointer to data buffer
      int            iCount;                  // Index counter
      int            cIterations = DEFAULT_ITERATIONS; // Iteration counter
      unsigned       hMailslot;               // Handle to mailslot
      unsigned short cbBuffer;                // Size of data buffer

      unsigned short cbMessageSize = DEFAULT_MSGSIZE;
      unsigned short cbMailslotSize, cMessages;
      unsigned short cbReturned, cbNextSize, usNextPriority;
      unsigned short usPriority = DEFAULT_PRIORITY;
      unsigned short usClass = DEFAULT_CLASS;
      API_RET_TYPE   uReturnCode;             // API return code

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 'm':                        // -m mailslot name
                  pszMailslot = argv[++iCount];
                  break;
               case 's':                        // -s max. message size
                  cbMessageSize = atoi(argv[++iCount]);
                  break;
               case 't':                        // -t text
                  pszMessage = argv[++iCount];
                  break;
               case 'p':                        // -p priority
                  usPriority = atoi(argv[++iCount]);
                  break;
               case 'c':                        // -c class
                  usClass = atoi(argv[++iCount]);
                  break;
               case 'i':                        // -i iterations
                  cIterations = atoi(argv[++iCount]);
                  break;
               case 'h':
               default:

   Usage(argv[0]);
            }
         }

   else
            Usage(argv[0]);
      }

   //========================================================================
   // DosMakeMailslot
   //
   // This API creates a mailslot on the local computer. The mailslot

   // size is set to 0, indicating to the API to choose a value based

   // on the size of the message buffer.
   //========================================================================

      uReturnCode = DosMakeMailslot (
                           pszMailslot,       // Mailslot name
                           cbMessageSize,     // Max. message size
                           0,                 // Size of mailslot
                           &hMailslot);       // Handle to mailslot

      printf("DosMakeMailslot of \"%s\" returned %u \n",
                 pszMailslot, uReturnCode);

      if (uReturnCode != NERR_Success)
         exit(1);

   //========================================================================
   // DosWriteMailslot
   //
   // This API writes cIterations messages to the mailslot just created.
   // If the message being written to the mailslot is an ASCIIZ string,
   // the specified length must include the NUL terminator.
   //========================================================================

      for (iCount = 1; iCount <= cIterations; iCount++)
      {
         uReturnCode = DosWriteMailslot(
                           pszMailslot,       // Mailslot name
                           pszMessage,        // Message to write to
   mailslot
                           strlen(pszMessage)+1,  // Length; allow for
   NUL
                           usPriority,            // Message priority
                           usClass,               // Message class
                           0L);                   // Immediate time-out
         printf("DosWriteMailslot #%d returned %u \n",
                     iCount, uReturnCode);
      }

   //========================================================================
   // DosMailslotInfo
   //
   // This API gets information about the mailslot and then prints it.
   //========================================================================

      uReturnCode = DosMailslotInfo(
                           hMailslot,         // Handle to mailslot
                           &cbMessageSize,    // Max. message size accepted
                           &cbMailslotSize,   // Size of mailslot
                           &cbNextSize,       // Size of next message
                           &usNextPriority,   // Priority of next message
                           &cMessages);       // Count of messages in
   mailslot

      printf("DosMailslotInfo returned %u \n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         printf("   Message buffer size : %hu \n", cbMessageSize);
         printf("   Mailslot size       : %hu \n", cbMailslotSize);
         printf("   Size of next message: %hu \n", cbNextSize);
         if (cbNextSize)
            printf("   Priority of next msg: %hu\n", usNextPriority);
         printf("   Number of messages  : %hu \n", cMessages);
      }

   //========================================================================
   // DosPeekMailslot
   //
   // This API reads the most current message without removing it.
   //========================================================================

      /*
       *  Allocate a data buffer large enough for the next message.
       *  Use the default buffer size, just in case a message of higher
       *  priority is received between the DosMailslotInfo call and
       *  the DosPeekMailslot call.
       */

      cbBuffer = cbMessageSize;               // Default buffer size
      pbBuffer = SafeMalloc(cbBuffer);

   uReturnCode = DosPeekMailslot(
                           hMailslot,         // Handle to mailslot
                           pbBuffer,          // Buffer for returned
   message
                           &cbReturned,       // Size of returned message
                           &cbNextSize,       // Size of next message
                           &usNextPriority);  // Priority of next message

      printf("DosPeekMailslot returned %u \n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         printf("   Message received    : \"%s\" \n", pbBuffer);
         printf("   Size of message read: %hu bytes\n", cbReturned);
         printf("   Size of next message: %hu bytes\n", cbNextSize);
         if (cbNextSize)
            printf("   Priority of next msg: %hu\n", usNextPriority);
      }

   //========================================================================
   // DosReadMailslot
   //
   // Read and delete the most current message.
   //========================================================================

      uReturnCode = DosReadMailslot(
                           hMailslot,         // Handle to mailslot
                           pbBuffer,          // Buffer for returned
   message
                           &cbReturned,       // Size of returned message
                           &cbNextSize,       // Size of next message
                           &usNextPriority,   // Priority of next message
                           0L);               // Time-out value; don't
   wait

      printf("DosReadMailslot returned %u \n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         printf("   Message received    : \"%s\" \n", pbBuffer);
         printf("   Size of message read: %hu bytes\n", cbReturned);
         printf("   Size of next message: %hu bytes\n", cbNextSize);
         if (cbNextSize)
            printf("   Priority of next msg: %hu\n", usNextPriority);
      }
      free (pbBuffer);

   //========================================================================
   // DosDeleteMailslot
   //
   // This API deletes the created mailslot.
   //========================================================================

      uReturnCode = DosDeleteMailslot(hMailslot);

      printf("DosDeleteMailslot of \"%s\" returned %u \n",
                 pszMailslot, uReturnCode);

      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage:  %s [-m mailslot] [-s size] [-t text] "
         "[-c class]\n\t\t[-p priority] [-i iterations]\n", pszProgram);
      exit(1);
   }







 Message Category

 Message API functions send and receive messages, and manipulate message
 aliases.

 All Message API functions require that the local computer be running the
 Workstation service. All Message functions except NetMessageBufferSend and
 NetMessageFileSend require that the computer where the function is to be
 executed be running the Messenger service. NetMessageBufferSend and
 NetMessageFileSend require only the Messenger service to be running on the
 computer that receives the message.

 The Message category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and MESSAGE.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETMESSAGE, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Message API functions:


   þ   NetMessageBufferSend

   þ   NetMessageFileSend

   þ   NetMessageLogFileGet

   þ   NetMessageLogFileSet

   þ   NetMessageNameAdd

   þ   NetMessageNameDel

   þ   NetMessageNameEnum

   þ   NetMessageNameFwd

   þ   NetMessageNameGetInfo

   þ   NetMessageNameUnFwd



 Description

 A message is any file or buffer of data sent to a user or application on the
 network. To receive a message, a user or application must register a message
 alias in a computer's table of message names. This can be done by using
 NetMessageNameAdd.

 A message name table contains a list of registered message aliases (users
 and applications) permitted to receive messages and a list of aliases to
 which a message can be forwarded.

 The aliases registered in the message name table are case sensitive. An
 alias added using the LAN Manager command-line or full-screen interface is
 added in uppercase. If an alias is added using NetMessageNameAdd, the case
 is unaltered. To send a message, the alias specified must match exactly the
 alias that is registered.

 NetMessageNameDel deletes a specific message alias from the message name
 table. NetMessageNameEnum lists all the aliases stored in the message name
 table. NetMessageNameGetInfo retrieves information about a particular
 message alias in the message name table.

 To send a message, an application can call either NetMessageFileSend or
 NetMessageBufferSend. NetMessageFileSend sends a file; NetMessageBufferSend
 sends a buffer of information.

 Applications can also send broadcast messages to all users in a domain or to
 all computers on a network by using NetMessageFileSend or
 NetMessageBufferSend.

 All messages sent to an alias on a particular computer can be forwarded to
 another alias on a different computer by using NetMessageNameFwd. Forwarded
 messages can be received only by the forwarded alias. They are not received
 by the alias that forwards them. NetMessageNameUnFwd ends message forwarding
 for a specified alias.

 Users can receive messages in one of two ways (or both at the same time):


   þ   The message is logged in a message log.

   þ   The message is displayed in a popup. To receive a popup message, the
       Netpopup service must be installed.


 NetMessageLogFileSet enables or disables message logging and specifies the
 name of the message log file. If message logging is enabled, all messages
 received are logged. The log file is in ASCII format.

 NetMessageLogFileGet returns the name of the message log file for a
 workstation or server and specifies whether or not message logging is
 enabled. The default message log file is LANMAN\LOGS\MESSAGES.LOG. The
 LANMAN directory is set during installation; the default is C:\LANMAN.

 The message log file contains messages in the following format:


   þ   A header specifying who sent the message, who received the message,
       and the time and date the message was received

   þ   A blank line

   þ   The contents of the message

   þ   A blank line

   þ   A line containing four asterisks (****)

   þ   A blank line


 The following example shows the contents of a message log file containing
 two messages:

   Message from JOHN to BRUCE on October 01, 1990, 14:05:20

   Hello, this is a BUFFER test message.

   ****

   Message from BRUCE to JOHN on October 01, 1990, 14:11:48

   Hello, this is a FILE test message.

   ****

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE
 A process must open the message log in read-only/deny-none mode; otherwise,
 the Messenger service fails when trying to log incoming messages.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 MS-DOS Considerations

 By default, LAN Manager for MS-DOS accepts only two names, the name of the
 workstation and the name of the user in the message name table. To define
 more names, change the value of the nummsgnames entry in the [messenger]
 section of the LANMAN.INI file.

 MS OS/2 LAN Manager accepts up to 14 aliases in the message name table,
 although this may be limited to a smaller value by the network hardware
 being used.


 Data Structures

 NetMessageNameEnum and NetMessageNameGetInfo use the msg_info_X data
 structure, where X is 0 or 1, depending on the level of detail requested.


 Message Information (level 0)

 The msg_info_0 data structure has this format:

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

 where

 msgi0_name
   Contains an ASCIIZ string that specifies the alias to which the message is
   to be sent. The constant CNLEN is defined in the NETCONS.H header file.


 Message Information (level 1)

 The msg_info_1 data structure has this format:

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

 where

 msgi1_name
   Contains an ASCIIZ string that specifies the alias to which the message is
   to be sent. The constant CNLEN is defined in the NETCONS.H header file.

 msgi1_forward_flag
   Specifies whether to send messages to a message alias on the local
   computer or to forward them to a message alias on a remote computer. The
   MESSAGE.H header file defines these possible values:

 Code                    Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 MSGNAME_NOT_FORWARDED   0x00   Name is not forwarded.
 MSGNAME_FORWARDED_TO    0x04   Name is forwarded to a remote computer.
 MSGNAME_FORWARDED_FROM  0x10   Name is forwarded from a remote computer.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 msgi1_pad1
   Aligns the next data structure element on a word boundary.

 msgi1_forward
   Contains an ASCIIZ string that specifies the alias to which the message
   will be sent if forwarding is enabled. The constant CNLEN is defined in
   the NETCONS.H header file.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 LANMAN.INI file                   LAN Manager administrator's manual(s)

 Starting services, the Messenger  Appendix C, "Creating LAN Manager
 service                           Services"


 NetMessageBufferSend
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageBufferSend sends a buffer of information to a registered message
 alias.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege or accounts, comm, print, or server operator privilege is
 required to successfully execute NetMessageBufferSend on a remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageBufferSend (const char far *  pszServer,
                         char far *        pszRecipient,
                         char far *        pbBuffer,
                         unsigned short    cbBuffer
                        );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageBufferSend. A null pointer or null string specifies
   the local computer.

 pszRecipient
   Points to an ASCIIZ string that contains the registered message alias to
   receive the message buffer. To broadcast a message to all workstations on
   the network, pszRecipient should point to an asterisk (*). To broadcast to
   all members of a domain, pszRecipient should point to the domain name,
   which should be terminated with an asterisk.

 pbBuffer
   Points to the message buffer to be sent.

 cbBuffer
   Specifies the size (in bytes) of the message contained in the buffer
   pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_REM_NOT_LIST                51      The remote computer is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_REM_NOT_LIST                51      The remote computer is not
                                           listening.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_NoNetworkResource            2105    The network hardware could not
                                           access the resources it needed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NoComputerName               2270    A computername has not been
                                           configured.

 NERR_NameNotFound                 2273    The message alias cannot be
                                           located.

 NERR_PausedRemote                 2281    The message was sent, but the
                                           recipient has paused the
                                           Messenger service, so the
                                           message cannot be received.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BadReceive                   2282    The remote workstation was
                                           unable to receive the message.
                                           The Workstation or Messenger
                                           service may not be running on
                                           that workstation, it may have
                                           been receiving another message
                                           when this message arrived, or
                                           its message buffer may be too
                                           small.

 NERR_NotLocalName                 2285    The message alias is not on the
                                           local computer.

 NERR_TruncatedBroadcast           2289    The broadcast message is too
                                           long. Only the first 128
                                           characters of the message were
                                           sent.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Broadcast messages (pszRecipient points to * or domainname*) can have as
 many as 128 bytes; delivery is not guaranteed. Other messages can have as
 many as 62K, provided they do not exceed the maximum receivable message size
 for the computer that receives them. The maximum receivable size is set by
 the sizmessbuf entry in the [messenger] section of the LANMAN.INI file. The
 sizmessbuf entry cannot define a value larger than 62K. (The default value
 is 4K on a computer with MS OS/2, and 256 bytes on an MS-DOS workstation.)

 The total size of sizmessbuf can be divided among different messages if
 messages arrive at the same time, reducing the actual size of any one
 message that can be received. For more information about the LANMAN.INI
 file, see your LAN Manager administrator's manual(s).

 NetMessageBufferSend requires that the Messenger service be started on the
 computer where the message is to be received, but it need not be started on
 the computer that sends the message.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a message alias            NetMessageNameAdd

 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"

 Sending a message file            NetMessageFileSend

 Setting the LANMAN.INI            LAN Manager administrator's manual(s)
 sizmessbuf entry for a server


 NetMessageFileSend
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageFileSend sends a file to a registered message alias.

 It is recommended that you not use NetMessageFileSend because it is unlikely
 to be supported in future releases of LAN Manager. NetMessageBufferSend can
 be used as an alternative.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege or accounts, comm, print, or server operator privilege is
 required to successfully execute NetMessageFileSend on a remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageFileSend (const char far *  pszServer,
                       char far *        pszRecipient,
                       char far *        pszFileSpec
                      );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageFileSend. A null pointer or null string specifies the
   local computer.

 pszRecipient
   Points to an ASCIIZ string that contains the registered message alias to
   receive the message file. To broadcast a message to all workstations on
   the network, pszRecipient should point to an asterisk (*). To broadcast to
   all members of a domain, this parameter should point to the domain name,
   which should be terminated with an asterisk.

 pszFileSpec
   Points to an ASCIIZ string that contains the pathname of the file to send.
   This pathname must be specified relative to the computer specified by
   pszServer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_FILE_NOT_FOUND              2       The file was not found.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_REM_NOT_LIST                51      The remote computer is not
                                           listening.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_OPEN_FAILED                 110     An open or write operation
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_OPEN_FAILED                 110     An open or write operation
                                           failed.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_NoNetworkResource            2105    The network hardware could not
                                           access the resources it needed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          shared.

 NERR_NoComputerName               2270    A computername has not been
                                           configured.

 NERR_NameNotFound                 2273    The message alias cannot be
                                           located.

 NERR_PausedRemote                 2281    The message was sent, but the
                                           recipient has paused the
                                           Messenger service, so the
                                           message cannot be received.

 NERR_BadReceive                   2282    The remote workstation was
                                           unable to receive the message.
                                           The Workstation or Messenger
                                           service may not be running on
                                           that workstation, it may have
                                           been receiving another message
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          been receiving another message
                                           when this message arrived, or
                                           its message buffer may be too
                                           small.

 NERR_NotLocalName                 2285    The message alias is not on the
                                           local computer.

 NERR_TruncatedBroadcast           2289    The broadcast message is too
                                           long. Only the first 128
                                           characters of the message were
                                           sent.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Broadcast messages (pszRecipient points to * or domainname*) can have as
 many as 128 bytes; delivery is not guaranteed. Other messages can have as
 many as 62K, provided they do not exceed the maximum receivable message size
 for the computer that receives them. The maximum receivable size is set with
 the sizmessbuf entry in the [messenger] section of the LANMAN.INI file. The
 sizmessbuf entry cannot define a value larger than 62K. (The default value
 is 4K on a computer with MS OS/2, and 256 bytes on an MS-DOS workstation.)

 The total size of sizmessbuf can be divided among different messages if
 messages arrive at the same time, reducing the actual size of any one
 message that can be received. For more information about the LANMAN.INI
 file, see your Microsoft LAN Manager administrator's manual(s).

 NetMessageFileSend requires that the Messenger service be started on the
 computer where the message is to be received, but it need not be started on
 the computer that sends the message.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a message alias            NetMessageNameAdd

 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"

 Sending a buffer of information   NetMessageBufferSend

 Setting the LANMAN.INI            LAN Manager administrator's manual(s)
 sizmessbuf entry for a server


 NetMessageLogFileGet
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageLogFileGet retrieves the name of the message log and the current
 logging status (on or off). NetMessageLogFileGet requires that the Messenger
 service be started.

 It is recommended that you not use NetMessageLogFileGet because it is
 unlikely to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetMessageLogFileGet on
 a remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageLogFileGet (const char far *  pszServer,
                         char far *        pbBuffer,
                         unsigned short    cbBuffer,
                         short far *       pfsEnabled
                        );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageLogFileGet. A null pointer or null string specifies
   the local computer.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains the pathname of the message log file.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pfsEnabled
   Points to a short integer in which the status of message logging is
   returned. If pfsEnabled is 1, message logging is enabled. If it is 0,
   message logging is not enabled.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"

 Modifying the name and status of  NetMessageLogFileSet
 the message log


 NetMessageLogFileSet
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageLogFileSet specifies the name of a file in which to log messages
 received by registered message aliases, and enables or disables logging.
 NetMessageLogFileSet requires that the Messenger service be started.

 It is recommended that you not use NetMessageLogFileSet because it is
 unlikely to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetMessageLogFileSet on
 a remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageLogFileSet (const char far *  pszServer,
                         char far *        pszFileSpec,
                         short             pfsEnabled
                        );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageLogFileSet. A null pointer or null string specifies
   the local computer.

 pszFileSpec
   Points to an ASCIIZ string that contains the pathname of the file or
   device (LPT: or COM:) where the messages are logged.

   If pszFileSpec is passed as a null pointer, the name of the current
   message log file does not change. If pszFileSpec points to a null string,
   no message file is used; in this case, pfsEnabled must be 0.

   If pszFileSpec points to a relative path, the path must be relative to the
   LAN Manager LOGS directory. All other pathnames must be fully qualified.
   If a filename extension is not provided, the file extension .LOG is
   appended.

 pfsEnabled
   Points to a short integer that specifies whether logging is enabled. If
   pfsEnabled is 0, message logging is disabled. If it is 1, message logging
   is enabled.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RedirectedPath               2117    The operation is invalid for a
                                           redirected resource. The
                                           devicename specified is assigned
                                           to a shared resource.

 NERR_WkstaNotStarted              2138    The Workstation service is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 NERR_InvalidDevice                2294    The devicename is invalid.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"

 Retrieving the name and status    NetMessageLogFileGet
 of the message log


 NetMessageNameAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageNameAdd registers a message alias in the message name table.
 NetMessageNameAdd requires that the Messenger service be started.

 It is recommended that you not use NetMessageNameAdd because it is unlikely
 to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetMessageNameAdd on a
 remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageNameAdd (const char far *  pszServer,
                      const char far *  pszMessageName,
                      short             fsFwdAction
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageNameAdd. A null pointer or null string specifies the
   local computer.

 pszMessageName
   Points to an ASCIIZ string that contains a message alias to add to the
   message name table. The message alias can have as many as CNLEN+1 bytes,
   including the terminating NUL character. The constant CNLEN is defined in
   the NETCONS.H header file.

 fsFwdAction
   Specifies the action to take if the message alias pointed to by
   pszMessageName is already forwarded. If fsFwdAction is 0, an error is
   returned. If it is any other value, the name is added to the message name
   table.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_REM_NOT_LIST                51      The remote computer is not
                                           listening.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_NoNetworkResource            2105    The network hardware could not
                                           access the resources it needed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_AlreadyForwarded             2274    Messages for this alias are
                                           already being forwarded to
                                           another alias.

 NERR_AddForwarded                 2275    Messages for this alias are
                                           being forwarded to another
                                           computer.

 NERR_AlreadyExists                2276    The message alias already exists
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_AlreadyExists                2276    The message alias already exists
                                           on this computer.

 NERR_TooManyNames                 2277    The maximum number of message
                                           aliases has been exceeded.

 NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 NERR_DuplicateName                2297    The name specified is already in
                                           use as a message alias on the
                                           network.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Deleting a message alias          NetMessageNameDel

 Forwarding messages               NetMessageNameFwd

 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"


 NetMessageNameDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageNameDel deletes a message alias from the table of message aliases
 on a computer. NetMessageNameDel requires that the Messenger service be
 started.

 It is recommended that you not use NetMessageNameDel because it is unlikely
 to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetMessageNameDel on a
 remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageNameDel (const char far *  pszServer,
                      const char far *  pszMessageName,
                      short             fsFwdAction
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageNameDel. A null pointer or null string specifies the
   local computer.

 pszMessageName
   Points to an ASCIIZ string that contains the message alias to be removed.

 fsFwdAction
   Specifies what action to take if the messages for the message alias
   pointed to by pszMessageName are being forwarded to another message alias.
   If fsFwdAction is 0, an error is returned. If it is any other value, the
   message alias is deleted from the message name table.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_REM_NOT_LIST                51      The remote computer is not
                                           listening.

 ERROR_BAD_NETPATH                 53      The network path was not found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NameNotFound                 2273    The message alias cannot be
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NameNotFound                 2273    The message alias cannot be
                                           located.

 NERR_DelComputerName              2278    A message alias that is also a
                                           computername cannot be deleted.

 NERR_NameInUse                    2283    The message alias is currently
                                           in use. Try again later.

 NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 NERR_NotLocalName                 2285    The message alias is not on the
                                           local computer.

 NERR_DeleteLater                  2298    The message alias will be
                                           deleted later.

 NERR_IncompleteDel                2299    The message alias was not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_IncompleteDel                2299    The message alias was not
                                           successfully deleted from all
                                           networks.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a message alias            NetMessageNameAdd

 Listing all message aliases       NetMessageNameEnum

 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"


 NetMessageNameEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageNameEnum lists the message aliases that will receive messages on a
 specified computer. NetMessageNameEnum requires that the Messenger service
 be started.

 It is recommended that you not use NetMessageNameEnum because it is unlikely
 to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetMessageNameEnum on a
 remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageNameEnum (const char far *      pszServer,
                       short                 sLevel,
                       char far *            pbBuffer,
                       unsigned short        cbBuffer,
                       unsigned short far *  pcEntriesRead,
                       unsigned short far *  pcTotalAvail
                      );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageNameEnum. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of msg_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the message
   aliases enumerated in the buffer is returned. This count is valid only if
   NetMessageNameEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of message aliases is returned. This count is valid only if
   NetMessageNameEnum returns NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a message alias            NetMessageNameAdd

 Deleting a message alias          NetMessageNameDel

 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"

 Retrieving information about a    NetMessageNameGetInfo
 particular message alias


 NetMessageNameFwd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageNameFwd modifies the message name table to forward messages
 addressed to one alias on to another alias. The original recipient of the
 message does not receive the message. NetMessageNameFwd requires that the
 Messenger service be started.

 It is recommended that you not use NetMessageNameFwd because it is unlikely
 to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetMessageNameFwd on a
 remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageNameFwd (const char far *  pszServer,
                      const char far *  pszMessageName,
                      const char far *  pszForwardName,
                      short             fsDelFwdName
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageNameFwd. A null pointer or null string specifies the
   local computer.

 pszMessageName
   Points to an ASCIIZ string that contains the alias to which the messages
   are originally sent.

 pszForwardName
   Points to an ASCIIZ string that contains the alias to which messages are
   forwarded. The message aliases can have as many as CNLEN+1 bytes,
   including the terminating  NUL character. The constant CNLEN is defined in
   the NETCONS.H header file.

 fsDelFwdName
   Specifies the action to take if the alias pointed to by pszMessageName
   already forwards messages to another alias. If fsDelFwdName is 0, an error
   is returned. If it is any other value, any previous forwarded alias is
   deleted.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_REM_NOT_LIST                51      The remote computer is not
                                           listening.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_NoNetworkResource            2105    The network hardware could not
                                           access the resources it needed.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NameNotFound                 2273    The message alias cannot be
                                           located.

 NERR_AlreadyForwarded             2274    Messages for this alias are
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_AlreadyForwarded             2274    Messages for this alias are
                                           already being forwarded to
                                           another alias.

 NERR_AlreadyExists                2276    The message alias already exists
                                           on this computer.

 NERR_TooManyNames                 2277    The maximum number of message
                                           aliases has been exceeded.

 NERR_LocalForward                 2279    Messages cannot be forwarded
                                           back to the same workstation.

 NERR_NameInUse                    2283    The message alias is currently
                                           in use. Try again later.

 NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_NotLocalName                 2285    The message alias is not on the
                                           local computer.

 NERR_RemoteFull                   2287    The message alias table on the
                                           remote workstation is full.

 NERR_DuplicateName                2297    The name specified is already in
                                           use as a message alias on the
                                           network.

 NERR_DeleteLater                  2298    The message alias will be
                                           deleted later.

 NERR_MultipleNets                 2300    This operation is not supported
                                           on a computer that is on
                                           multiple networks.

 NERR_InvalidComputer              2351    The specified computername is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all message aliases       NetMessageNameEnum

 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"

 Setting the LANMAN.INI            LAN Manager administrator's manual(s)
 sizmessbuf entry for a server

 Stopping the forwarding of        NetMessageNameUnFwd
 messages


 NetMessageNameGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageNameGetInfo retrieves information about a particular message alias
 in the message name table. NetMessageNameGetInfo requires that the Messenger
 service be started.

 It is recommended that you not use NetMessageNameGetInfo because it is
 unlikely to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetMessageNameGetInfo on
 a remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageNameGetInfo (const char far *      pszServer,
                          const char far *      pszMessageName,
                          short                 sLevel,
                          char far *            pbBuffer,
                          unsigned short        cbBuffer,
                          unsigned short far *  pcbTotalAvail
                         );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetMessageNameGetInfo. A null pointer or null string specifies
   the local computer.

 pszMessageName
   Points to an ASCIIZ string that contains the message alias of interest.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a msg_info_X data structure, where X is 0 or
   1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetMessageNameGetInfo returns NERR_Success or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 NERR_NotLocalName                 2285    The message alias is not on the
                                           local computer.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all message aliases       NetMessageNameEnum

 Messenger Service                 Appendix C, "Creating LAN Manager
                                   Services"


 NetMessageNameUnFwd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetMessageNameUnFwd stops the forwarding of messages from one message alias
 to another. NetMessageNameUnFwd requires that the Messenger service be
 started.

 It is recommended that you not use NetMessageNameUnFwd because it is
 unlikely to be supported in future releases of LAN Manager.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetMessageNameUnFwd on a
 remote server.


 Syntax

   #define INCL_NETMESSAGE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetMessageNameUnFwd (const char far *  pszServer,
                        const char far *  pszMessageName
                       );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of a server on which to
   execute NetMessageNameUnFwd. A null pointer or null string specifies the
   local computer.

 pszMessageName
   Points to an ASCIIZ string that contains the alias whose message
   forwarding is to be canceled.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_REM_NOT_LIST                51      The remote computer is not
                                           listening.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NameNotFound                 2273    The message alias cannot be
                                           located.

 NERR_NameInUse                    2283    The message alias is currently
                                           in use. Try again later.

 NERR_MsgNotStarted                2284    The Messenger service has not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_MsgNotStarted                2284    The Messenger service has not
                                           been started.

 NERR_NotLocalName                 2285    The message alias is not on the
                                           local computer.

 NERR_NameNotForwarded             2288    Messages for this alias are not
                                           being forwarded.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Forwarding messages to another    NetMessageNameFwd
 alias

 Messenger service                 Appendix C, "Creating LAN Manager
                                   Services"





 Message Category Example

   /*
       NETMSG.C -- a sample program demonstrating NetMessageBufferSend.

       This program requires that the Messenger service be running on
       the specified server, and that you have admin privileges or
       accounts, server, print, or comm operator privilege on that server.

       usage:  netmsg [-s \\server] [-r recipient] [-m message]

       where  \\server  = Name of the server. A servername must be
                          preceded by two backslashes (\\).
              recipient = Name of the message recipient.
              message   = Message to be sent.

       Note: When supplying a username as the name of the recipient,
   the name
       is case-sensitive. If the name has been added from the command
   line
       or from the full-screen interface, it will be uppercase. If the
       name has been added using NetMessageNameAdd, the case will be

       unaltered.

       API                      Used to...
       ====================     ==========================================
       NetMessageBufferSend     Send a buffer (message) of information
   to
                                a registered message alias

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define   INCL_NETERRORS
   #define   INCL_NETMESSAGE
   #define   INCL_NETWKSTA
   #include  <lan.h>          // LAN Manager header files

   #include  <stdio.h>        // C run-time header files
   #include  <stdlib.h>
   #include  <string.h>

   #include  "samples.h"      // Internal routine header file

   #define DEFAULT_MESSAGE    "Hi there!"
   #define TRUE               1
   #define FALSE              0

   void Usage (char * pszProgram);
   void main(int argc, char * argv[])
   {
      char * pszServer = NULL;                // NULL means local machine
      char * pszRecipient;                    // Message recipient
      char * pszMessage = DEFAULT_MESSAGE;    // Message to send
      char * pbBuffer;                        // Data buffer
      char   achDomain[DNLEN + 1];            // Domain, allow for *
   at end
      int    iCount;                          // Index counter
      short  fRecipient = FALSE;              // Flag if recipient specified
      unsigned short cbAvail;                 // Count of bytes available
      struct wksta_info_10 * pWksta10;        // Pointer to workstation
   info
      API_RET_TYPE uReturnCode;               // API return code

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1)))   // Process switches
            {
               case 's':                          // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'r':                          // -r recipient
                  pszRecipient = argv[++iCount];
                  fRecipient = TRUE;
                  break;
               case 'm':                          // -m message
                  pszMessage = argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }


   //  NetMessageBufferSend
   //
   //  This API sends a message to another user/computer. If no message

   //  recipient is specified, this example calls NetWkstaGetInfo to
   determine
   //  the primary domain for the workstation, then sends a broadcast
   message
   //  to all computers in that domain. First, NetWkstaGetInfo is called

   //  with a NULL buffer to determine the amount of data available,
   then
   //  NetWkstaGetInfo is called again with the returned buffer size.

      if (fRecipient == FALSE)
      {
         uReturnCode = NetWkstaGetInfo(
                           pszServer,         // Servername
                           10,                // Level of detail
                           NULL,              // Data buffer
                           0,                 // Size of buffer
                           &cbAvail);         // Count of bytes available

         if (uReturnCode != NERR_BufTooSmall)
         {
           printf("NetWkstaGetInfo for \"%s\" failed with %u\n",
                   pszServer, uReturnCode);
           exit(1);
         }

         // Allocate a data buffer large enough for workstation information.
         pbBuffer = SafeMalloc(cbAvail);

         uReturnCode = NetWkstaGetInfo(
                           pszServer,         // Servername
                           10,                // Level of detail
                           pbBuffer,          // Data buffer
                           cbAvail,           // Size of buffer
                           &cbAvail);         // Count of bytes available

         if (uReturnCode != NERR_Success)
         {
           printf("NetWkstaGetInfo for \"%s\" failed with %u\n",
                   pszServer, uReturnCode);
           exit(1);
         }



   // Add * to domain name so that the message is broadcast.

         pWksta10 = (struct wksta_info_10 *) pbBuffer;
         FarStrcpy((char far *)achDomain, pWksta10->wki10_logon_domain);
         strcat(achDomain, "*");
         pszRecipient = achDomain;
      }

      uReturnCode = NetMessageBufferSend(
                           pszServer,            // Servername
                           pszRecipient,         // Message recipient
                           pszMessage,           // Message to send
                           strlen(pszMessage));  // Length of message

      printf("NetMessageBufferSend returned %u\n", uReturnCode);
      printf("   Sending message to \"%s\"\n", pszRecipient);
      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-r recipient]"
                      " [-m message]\n", pszProgram);
      exit(1);
   }







 Print Destination Category

 Print Destination API functions control printers that receive spooled print
 jobs. When executed locally, Print Destination functions do not require that
 the NETWKSTA device driver be installed. When a servername is supplied, they
 require that the Workstation service be started.

 The Print Destination category functions, datatypes, structures, and
 constants are defined in the PMSPL.H header file. A source program can
 access error codes by defining the constant INCL_NETERRORS and including the
 LAN.H header file. For an example, see the "Example" section, later in this
 category.

 These are the Print Destination API functions:


   þ   DosPrintDestAdd

   þ   DosPrintDestControl

   þ   DosPrintDestDel

   þ   DosPrintDestEnum

   þ   DosPrintDestGetInfo

   þ   DosPrintDestSetInfo



 Description

 A print destination is a print device that can be associated with a printer
 queue. Print jobs submitted to a printer queue are directed to the print
 destination for the queue. A print destination can be physically connected
 to the computer, or it can be a redirected device that is physically
 connected to another computer. The Print Destination API functions allow
 operations on these printers and on the job they are currently printing.

 DosPrintDestAdd establishes a print destination on the specified computer.
 DosPrintDestDel deletes a print destination from the specified computer.

 DosPrintDestControl pauses or continues the print destination. If a job is
 currently printing, this function also affects that job.

 DosPrintDestEnum lists all print destinations on a computer.
 DosPrintDestGetInfo provides information about a particular print
 destination. DosPrintDestSetInfo can change the parameter values for a print
 destination.

 The Print Destination data structures and the Print Destination API
 functions use MS OS/2 conventions for names and type definitions. The
 OS2DEF.H header file defines these types:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 MS OS/2 Type Definition           C-Language Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 CHAR                              char
 PBYTE                             unsigned char far *
 PSZ                               unsigned char far *
 PUSHORT                           unsigned short *
 SPLENTRY                          pascal far
 SPLERR                            unsigned
 USHORT                            unsigned short
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Data Structures

 Level 0 and level 1 data structures are provided for compatibility with
 existing LAN Manager 1.0 applications. LAN Manager 2.0 applications should
 use level 2 and level 3 data structures.

 One of the important enhancements of LAN Manager 2.0 is the ability to treat
 a print destination as a virtual device, independent of a printer queue or a
 specific logical address.

 To illustrate this change, consider the definition of print destination
 names. The LAN Manager 1.0-compatible names must be names of logical
 addresses, such as LPT1, LPT2, or COM1. The new level 2 and level 3 data
 structures allow the use of more general names for print destinations.

 The API functions also demonstrate this enhancement. DosPrintDestGetInfo and
 DosPrintDestEnum return level 0 and level 1 data only if print destinations
 are associated with a printer queue. At level 2 and level 3, these functions
 return data for all print destinations.

 Existing LAN Manager 1.0 applications (that use the level 0 and level 1
 Print Destination data structures) can be compiled and linked using the 1.0
 header file NETSPOOL.H and the 1.0-compatible libraries NETSPOOL.LIB and
 NETSPOOL.DLL.

 Applications designed to run with both MS OS/2 1.1 and MS OS/2 1.2 should
 use the new level 0 and level 1 data structure names, include the PMSPL.H
 header file, and link with the NETSPOOL libraries.

 Applications designed to run only with MS OS/2 1.2 should use the PMSPL.LIB
 and PMSPL.DLL libraries. The PMSPL libraries provide faster performance than
 the corresponding functions in the NETSPOOL library.

 Applications that run only with MS OS/2 1.2 can be built from existing
 applications by changing the data structure and element names. The
 prdest_info data structure and element names can be changed to the
 corresponding PRDINFO data structure and element names. There is a
 one-to-one mapping from the prdest_info elements to the PRDINFO elements, as
 shown in the following table:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 LAN Manager 1.0                     LAN Manager 2.0
 prdest_info Element                 PRDINFO Element
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 prdest_name                         szName

 prdest_username                     szUserName

 prdest_jobid                        uJobId

 prdest_status                       fsStatus

 prdest_status_string                pszStatus

 prdest_time                         time

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 DosPrintDestAdd and DosPrintDestSetInfo accept the level 3 data structure
 PRDINFO3.

 DosPrintDestEnum and DosPrintDestGetInfo accept levels 0, 1, 2, and 3. These
 functions accept or return the logical address at level 0, the PRDINFO data
 structure at level 1, the printer name at level 2, and the PRDINFO3 data
 structure at level 3. New applications should use levels 2 and 3 only.

 DosPrintDestControl and DosPrintDestDel do not use these data structures.
 The required data is defined within the API function definition.


 Print Destination Name (level 0)

 At level 0, data is returned in this format:

   CHAR szName[PDLEN+1];

 where

 szName
   Specifies an ASCIIZ string that contains the name of a print destination.
   The constant PDLEN is defined in the PMSPL.H header file.


 Print Destination Information (level 1)

 The PRDINFO data structure has this format:

   typedef struct _PRDINFO {
       CHAR    szName[PDLEN+1];
       CHAR    szUserName[UNLEN+1];
       USHORT  uJobId;
       USHORT  fsStatus;
       PSZ     pszStatus;
       USHORT  time;
   } PRDINFO;

 where

 szName
   Specifies an ASCIIZ string that contains the name of the print
   destination. The constant PDLEN is defined in the PMSPL.H header file.

 szUserName
   Specifies an ASCIIZ string that contains the name of the user who
   submitted a print job. This component is valid only during printing. A
   null string indicates that the job was submitted from the local computer.
   The constant UNLEN is defined in the PMSPL.H header file.

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the current print job. If no job is printing, uJobId is 0.

 fsStatus
   Contains a short integer that specifies the status of the print
   destination. The bits of fsStatus are defined in PMSPL.H.

   Bits 0-1 have the code PRD_STATUS_MASK and the value 0x0003. This bit mask
   isolates the print destination status, as follows:

 Bits  Code        Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0-1   PRD_ACTIVE  0      The print job is processing.
 0-1   PRD_PAUSED  1      The print job is paused.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   Bits 2-11 indicate the print job and print destination status. Bits 2-11
   can be isolated using the constants PRJ_DEVSTATUS and PRD_DEVSTATUS, which
   have the value 0x0FFC. Bit 15 signals whether an alert indicated that the
   print job was deleted. These are the meanings for individual bits:

ÖÚÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 2    PRJ_COMPLETE     0x0004  If 1, the print job is complete.

 3    PRJ_INTERV       0x0008  If 1, intervention is required.

 4    PRJ_ERROR        0x0010  If 1, an error occurred (pszStatus can
                               contain a comment explaining the error).

 5    PRJ_DESTOFFLINE  0x0020  If 1, the print destination is offline.

 6    PRJ_DESTPAUSED   0x0040  If 1, the print destination is paused.

 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 7    PRJ_NOTIFY       0x0080  If 1, an alert is raised.

 8    PRJ_DESTNOPAPER  0x0100  If 1, the print destination is out of paper.

 9    PRJ_DESTFORMCHG  0x0200  If 1, the printer is waiting for a form
                               change.

 10   PRJ_DESTCRTCHG   0x0400  If 1, the printer is waiting for a cartridge
                               change.

 11   PRJ_DESTPENCHG   0x0800  If 1, the printer is waiting for a pen
                               change.

 15   PRJ_DELETED      0x8000  If 1, an alert indicates the print job was
                               deleted.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 pszStatus
   Points to an ASCIIZ string that contains a comment about the print
   destination error status, posted by the print destination's print
   processor. This element contains valid data only while the job is printing
   and an error occurs.

 time
   Contains an unsigned short integer that specifies the number of minutes
   the current job has been printing. This value is valid only while the job
   is printing.


 Print Destination Information (level 2)

 At level 2, the pszPrinterName element of the PRDINFO3 data structure is
 returned in this format:

   PSZ pszPrinterName;

 where

 pszPrinterName
   Points to an ASCIIZ string that specifies the name of a print destination.
   The name can contain blanks. The string can have as many as CCHMAXPATHCOMP
   bytes, as defined in the MS OS/2 header file BSEDOS.H.


 Print Destination Information (level 3)

 The PRDINFO3 data structure has this format:

   typedef struct _PRDINFO3 {
       PSZ     pszPrinterName;
       PSZ     pszUserName;
       PSZ     pszLogAddr;
       USHORT  uJobId;
       USHORT  fsStatus;
       PSZ     pszStatus;
       PSZ     pszComment;
       PSZ     pszDrivers;
       USHORT  time;
       USHORT  pad1;
   } PRDINFO3;

 where

 pszPrinterName
   Points to an ASCIIZ string that specifies the name of the printer. The
   name can contain blanks. The string can have as many as CCHMAXPATHCOMP
   bytes, as defined in the MS OS/2 header file BSEDOS.H.

 pszUserName
   Points to an ASCIIZ string that specifies the name of the user who
   submitted the currently active print job. This variable is valid only
   during printing. A null string or null pointer indicates the job was
   submitted from the local computer.

 pszLogAddr
   Points to an ASCIIZ string that specifies the name of the logical address
   where this printer prints, such as LPT1. If the printer is not connected
   to a logical address, pszLogAddr is a null pointer.

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of a job currently being printed. If no job is printing, uJobId is
   0.

 fsStatus
   Contains a short integer that specifies the status of the print
   destination. The bits of fsStatus are identical to the fsStatus element of
   the PRDINFO data structure. For a full description, see the preceding
   section.

 pszStatus
   Points to an ASCIIZ string that contains a comment about the print
   destination error status, posted by the print destination's print
   processor. This value is valid only while the job is printing and an error
   occurs.

 pszComment
   Points to an ASCIIZ string that contains a printer description.

 pszDrivers
   Points to an ASCIIZ string that contains a list of drivers that are
   supported by this printer (the drivernames are separated by commas). If
   the devicename contains blanks, the name should be enclosed in quotation
   marks (" "). Each driver can consist of a drivername and a devicename
   separated by a period (.) For example:

   IBM 4201, "PSCRIPT. Apple Laserwriter"

   indicates that this printer supports two drivers.

 time
   Contains an unsigned short integer that specifies the number of minutes
   the current job has been printing. This value is valid only during
   printing.

 pad1
   Aligns the next data structure element on a word boundary.


 DosPrintDestAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintDestAdd adds a print destination to the specified computer.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote and levels 0 and 1 only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintDestAdd on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintDestAdd (PSZ     pszServer,
                    USHORT  uLevel,
                    PBYTE   pbBuf,
                    USHORT  cbBuf
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of a server on which to
   execute DosPrintDestAdd. A null pointer or null string specifies the local
   computer.

 uLevel
   Specifies the level of detail requested; must be 3.

 pbBuf
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains records of the PRDINFO3 data structure.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_REQ_NOT_ACCEP               71      The network request cannot be
                                           accepted at this time. There may
                                           be a lack of resources on the
                                           specified server or the local
                                           workstation.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_DestExists                   2153    The print destination already
                                           exists.

 NERR_DestNoRoom                   2157    The server does not have enough
                                           memory available to add another
                                           printer.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_DestInvalidState             2162    This operation cannot be
                                           performed on the print
                                           destination in its current state.

 NERR_SpoolNoMemory                2165    A spooler memory allocation
                                           failure occurred.

 NERR_DriverNotFound               2166    The device driver specified has
                                           not been installed on the
                                           computer.

 NERR_BadDev                       2341    The devicename is invalid
                                           because it does not represent a
                                           physical device, or because the
                                           device hardware is faulty.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosPrintDestAdd creates a new print destination to the specified computer.
 The printer is set to print at the logical address specified by the
 pszLogAddr element of the PRDINFO3 data structure. If pszLogAddr is a null
 pointer or null string, the print destination is created but not connected
 to any logical address. This means that printing cannot occur on that
 printer or from any printer queue connected only to that printer.

 A print destination can be successfully added on an MS OS/2 1.2 workstation
 even if the workstation is not connected to a printer.

 All device drivers specified for the printer must be installed before
 calling DosPrintDestAdd.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Changing the connection between   DosPrintDestSetInfo
 a printer and a port


 DosPrintDestControl
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintDestControl pauses or continues printing on the specified print
 destination. If a job is currently printing on that destination, its status
 is changed along with that of the print destination. This function can also
 cancel or restart a job that is printing on the specified destination.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote and levels 0 and 1 only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintDestControl on a remote server or on a computer that has
 local security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintDestControl (PSZ     pszServer,
                        PSZ     pszDestName,
                        USHORT  uControl
                       );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintDestControl. A null pointer or null string specifies
   the local computer.

 pszDestName
   Points to an ASCIIZ string that contains the name of the print
   destination.

 uControl
   Contains an unsigned short integer that specifies the operation to be
   performed. The PMSPL.H header file defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code         Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PRD_DELETE   0      Delete the current print job.
 PRD_PAUSE    1      Pause printing.
 PRD_CONT     2      Continue the paused print job.
 PRD_RESTART  3      Restart the print job.
 Ä            4-255  Reserved.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_DestNotFound                 2152    The print destination was not
                                           found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          found.

 NERR_DestIdle                     2158    The print destination is idle
                                           and cannot accept control
                                           operations.

 NERR_DestInvalidOp                2159    The print destination request
                                           contains an invalid control
                                           function.

 NERR_ProcNoRespond                2160    The print processor is not
                                           responding.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 While paused, a print destination cannot accept new print jobs.

 To maintain compatibility with LAN Manager 1.0 applications,
 DosPrintDestControl uses logical addresses to refer to the destination
 printer.

 If the print destination is idle when the application attempts to restart or
 delete a print job (that is, the uControl parameter has the value PRD_DELETE
 or PRD_RESTART), DosPrintDestControl returns the error code NERR_DestIdle.
 These operations can succeed only if a job is printing.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the print destinations    DosPrintDestEnum
 on a computer

 Retrieving the status of the      DosPrintJobGetInfo
 current print job spooled to a
 printer


 DosPrintDestDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintDestDel deletes a print destination from a computer.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote and levels 0 and 1 only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintDestDel on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintDestDel (PSZ pszServer,
                    PSZ pszPrinterName
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintDestDel. A null pointer or null string specifies the
   local computer.

 pszPrinterName
   Points to the name of the printer to be deleted. The printer name should
   be a general name as defined in the level 2 and level 3 data structures,
   rather than a logical address as defined in the level 0 and level 1 data
   structures.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          shared.

 NERR_DestNotFound                 2152    The print destination was not
                                           found.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_DestInvalidState             2162    This operation cannot be
                                           performed on the print
                                           destination in its current state.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If the print destination is currently printing a job, DosPrintDestDel
 returns the error code NERR_DestInvalidState.


 DosPrintDestEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintDestEnum lists all print destinations on a computer and gives status
 information about the print destinations.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote and levels 0 and 1 only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute
 DosPrintDestEnum.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintDestEnum (PSZ      pszServer,
                     USHORT   uLevel,
                     PBYTE    pbBuf,
                     USHORT   cbBuf,
                     PUSHORT  pcReturned,
                     PUSHORT  pcTotal
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintDestEnum. A null pointer or null string specifies the
   local computer.

 uLevel
   Specifies the level of detail (0, 1, 2, or 3) requested.

 pbBuf
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a PRDINFOX data structure, where X is 0, 1, 2,
   or 3, depending on the level of detail requested.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 pcReturned
   Points to an unsigned short integer that indicates the number of entries
   returned in the buffer pointed to by pbBuf. This count is valid only if
   DosPrintDestEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotal
   Points to an unsigned short integer that indicates how many entries were
   available. This count is valid only if DosPrintDestEnum returns
   NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success           0       The function encountered no errors.

 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_BAD_NETPATH      53      The network path was not found.

 ERROR_INVALID_LEVEL    124     The level for information retrieval or
                                setting is invalid.

 ERROR_MORE_DATA        234     Additional data is available.

 NERR_RemoteOnly        2106    This operation can be performed only on a
                                server.

 NERR_DestNotFound      2152    The print destination was not found.

 NERR_SpoolerNotLoaded  2161    The spooler is not started.

 NERR_InvalidComputer   2351    The specified computername is invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 At levels 0 and 1, DosPrintDestEnum returns print destination names only if
 they are associated with printer queues. At levels 2 and 3, DosPrintDestEnum
 returns all print destinations.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Pausing or continuing printing    DosPrintDestControl
 on a particular print
 destination

 Retrieving the status of a        DosPrintDestGetInfo
 particular print destination


 DosPrintDestGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintDestGetInfo retrieves information about a print destination on a
 computer.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote and levels 0 and 1 only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute
 DosPrintDestGetInfo.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintDestGetInfo (PSZ      pszServer,
                        PSZ      pszName,
                        USHORT   uLevel,
                        PBYTE    pbBuf,
                        USHORT   cbBuf,
                        PUSHORT  pcbNeeded
                       );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintDestGetInfo. A null pointer or null string specifies
   the local computer.

 pszName
   Points to an ASCIIZ string that contains the name of the specific print
   destination.

 uLevel
   Specifies the level of detail (0, 1, 2, or 3) requested.  The level
   parameter works in conjunction with pszName and pbBuf, as follows:

 uLevel  pszName          Data returned in pbBuf
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0       Logical address  pszLogAddr element of PRDINFO3
                          data structure.

 1       Logical address  PRDINFO data structure.

 2       Printer name     Pointer to a printer name.

 3       Printer name     PRDINFO3 data structure.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 pbBuf
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains the data structure that corresponds to the
   uLevel and pszName parameters, as described in the preceding table.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 pcbNeeded
   Points to an unsigned short integer that specifies the number of bytes of
   information available. This count is valid only if DosPrintDestGetInfo
   returns NERR_Success,  ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success           0       The function encountered no errors.

 ERROR_BAD_NETPATH      53      The network path was not found.

 ERROR_INVALID_LEVEL    124     The level for information retrieval or
                                setting is invalid.

 ERROR_MORE_DATA        234     Additional data is available.

 NERR_RemoteOnly        2106    This operation can be performed only on a
                                server.

 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BufTooSmall       2123    The supplied buffer is too small.

 NERR_DestNotFound      2152    The print destination was not found.

 NERR_SpoolerNotLoaded  2161    The spooler is not started.

 NERR_InvalidComputer   2351    The specified computername is invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 At levels 0 and 1, DosPrintDestGetInfo returns print destination names only
 if they are associated with printer queues. At levels 2 and 3,
 DosPrintDestGetInfo returns all print destinations.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the print destinations    DosPrintDestEnum
 on a computer

 Pausing or continuing printing    DosPrintDestControl
 on a particular print
 destination


 DosPrintDestSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintDestSetInfo modifies the configuration of a print destination.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote and levels 0 and 1 only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintDestSetInfo on a remote server or on a computer that has
 local security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintDestSetInfo (PSZ     pszServer,
                        PSZ     pszName,
                        USHORT  uLevel,
                        PBYTE   pbBuf,
                        USHORT  cbBuf,
                        USHORT  uParmNum
                       );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintDestSetInfo. A null pointer or null string specifies
   the local computer.

 pszName
   Points to an ASCIIZ string that contains the name of the printer or
   parallel port.

 uLevel
   Specifies the level of detail; must be 3.

 pbBuf
   Points to the data to be set.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 uParmNum
   Specifies whether to set one or all elements of the entire PRDINFO3 data
   structure. If uParmNum is PARMNUM_ALL, the entire structure is set, and
   pbBuf must point to a PRDINFO3 data structure. If uParmNum is any other
   defined value, only one element of the print destination information is
   changed, and pbBuf must point to a valid value for that element.

   Not all elements can be set. Only those that have a specific PARMNUM
   constant value defined can be set. The PMSPL.H and NETCONS.H header files
   define these possible values for sParmNum:

 Code                 Value  Element of PRDINFO3
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL          0      All elements.
 PRD_LOGADDR_PARMNUM  3      pszLogAddr
 PRD_COMMENT_PARMNUM  7      pszComment
 PRD_DRIVERS_PARMNUM  8      pszDrivers
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_DestNotFound                 2152    The print destination was not
                                           found.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_SpoolNoMemory                2165    A spooler memory allocation
                                           failure occurred.

 NERR_DriverNotFound               2166    The device driver specified has
                                           not been installed on the
                                           computer.

 NERR_BadDev                       2341    The devicename is invalid
                                           because it does not represent a
                                           physical device, or because the
                                           device hardware is faulty.

 NERR_InvalidComputer              2351    The specified computername is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosPrintDestSetInfocan be used to disconnect a printer from a port by
 supplying a null string for the pszLogAddrelement of the PRDINFO3data
 structure.



 Print Destination Category Example

   /*
      NETPRD.C -- a program demonstrating the DosPrintDest API functions.

      Admin or print operator privilege is required to successfully
      execute the Print Destination API functions on a remote server.

      This program calls DosPrintDestAdd to add a printer to the specified
      server, then manipulates that printer using DosPrintDestControl.
      DosPrintDestGetInfo displays status information about the printer.
      DosPrintDestSetInfo is called to disconnect the printer from the
      computer. DosPrintDestEnum lists all printers on the computer.
      DosPrintDestDel then deletes the print destination.

      usage:  netprd [-s \\server] [-p printername] [-a address]
                     [-l level] [-o operation] [-d driver] [-f flag]
      where  \\server    = Name of the server. A servername must be preceded
                           by two backslashes (\\).
             printername = Name of the printer.
             address     = Logical address, such as LPT1.
             level       = Level of detail.
             operation   = Integer code for DosPrintDestControl.
             driver      = Name of the print driver.
             flag        = Flag whether to delete the printer (0 or 1).

      API                     Used to...
      ===================     ===============================================
      DosPrintDestAdd         Add a new print destination
      DosPrintDestControl     Control the status of the printer
      DosPrintDestGetInfo     Get specific information about a single
   printer
      DosPrintDestSetInfo     Set specific information for a single printer
      DosPrintDestEnum        List all printers available
      DosPrintDestDel         Delete the print destination

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define  INCL_BASE
   #include <os2.h>           // MS OS/2 base header files
   #include <pmspl.h>         // Print definitions

   #define  INCL_NETERRORS
   #include <lan.h>           // LAN Manager header files

   #include <stdio.h>         // C run-time header files
   #include <stdlib.h>
   #include <string.h>

   #include "samples.h"       // Internal routine header file

   #define  NEWPORTNAME       "LPT1"
   #define  NEWPRINTERNAME    "PrntDestTest"
   #define  NEWDRIVER         "IBM4201"
   #define  DEFAULT_BUF_SIZE  512
   #define  MAX_BUFFER_SIZE   65535
   #define  MAX_PDEST         10     // Limit for this program only

   void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries);
   void Usage(char *pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pbBuffer;            // Return data
      char *         pszServer = "";      // Server; default to local
   computer
      char *         szNull = "";         // Null string
      char far *     pszPrinterName = NEWPRINTERNAME;
      char far *     pszLogAddr = NEWPORTNAME;
      char far *     pszDriver = NEWDRIVER;
      int            iCount;              // Index counter
      PRDINFO3       prd3;                // Level 3 data structure
      short          sLevel = 3;          // Level of detail
      unsigned       uRet;                // Return code
      unsigned short fDone;               // Flag successful call
      unsigned short fDelete = TRUE;      // Delete flag
      unsigned short cEntriesRead;        // Count of entries read
      unsigned short cTotal;              // Count of entries available
      unsigned short cbBuffer = 0;        // Count of bytes in data buffer
      unsigned short cbBufferNeeded = 0;  // Bytes needed for GetInfo
   call
      unsigned short uControl = PRD_CONT; // DosPrintDestControl operation

   for (iCount = 1; iCount < argc; iCount++) // Get cmd-line
   switches
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'l':                        // -l level
                  sLevel = atoi(argv[++iCount]);
                  break;
               case 'p':                        // -p printername
                  pszPrinterName = argv[++iCount];
                  break;
               case 'd':                        // -d drivername
                  pszDriver = argv[++iCount];
                  break;
               case 'f':                        // -f flag deletion
                  fDelete = atoi(argv[++iCount]);
                  break;
               case 'a':                        // -a address
                  pszLogAddr = argv[++iCount];
                  break;
               case 'o':                        // -o operation
                  uControl = atoi(argv[++iCount]);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }
      printf("\nPrint Destination Category API Examples\n");

   //=======================================================================
   //  DosPrintDestAdd
   //
   //  This API adds the specified printer to the specified server.
   //=======================================================================

      memset(&prd3, 0, sizeof(PRDINFO3));       // Initialize memory

      prd3.pszPrinterName = pszPrinterName;     // Set names
      prd3.pszLogAddr = pszLogAddr;
      prd3.pszDrivers = pszDriver;

      uRet = DosPrintDestAdd(pszServer,         // Servername
                     3,                         // Level; must be 3
                     (char far *)&prd3,         // New printer struct
                     sizeof(PRDINFO3));         // Size of buffer

      printf("DosPrintDestAdd returned %u\n", uRet);
      if (uRet == NERR_Success)
      {
         printf("   %Fs added to ", prd3.pszPrinterName);
         if ((pszServer == NULL) || (*pszServer == '\0'))
            printf("the local computer\n");
         else
            printf("   %s\n", pszServer);
         printf("   Printer port set to %Fs\n", prd3.pszLogAddr);
      }

   //=======================================================================
   //  DosPrintDestControl
   //
   //  This API controls a printer destination. It can delete, pause,

   //  continue, or restart the printer. If a job is printing at the

   //  time the API is executed, that print job receives the new printer

   //  status. The print destination name must be a logical address.
   //=======================================================================

      uRet = DosPrintDestControl(pszServer,     // Computername
                     pszLogAddr,                // Print destination
   name
                     uControl);                 // Operation

      printf("DosPrintDestControl returned %u\n", uRet);

   //=======================================================================
   //  DosPrintDestGetInfo
   //
   //  This API returns information about the specified print destination.
   //=======================================================================

   // Call with zero-length buffer, expect NERR_BufTooSmall.

      uRet = DosPrintDestGetInfo(pszServer,     // Servername
                     pszPrinterName,            // Printername
                     sLevel,                    // Call level
                     NULL,                      // Data buffer
                     0,                         // Size of buffer
                     &cbBufferNeeded);          // Returns required size

      if (uRet == NERR_BufTooSmall)
      {
         cbBuffer = cbBufferNeeded;
         pbBuffer = SafeMalloc(cbBuffer);    // SafeMalloc() is in SAMPLES.C

         uRet = DosPrintDestGetInfo(pszServer,  // Servername
                     pszPrinterName,            // Printername
                     sLevel,                    // Call level
                     pbBuffer,                  // Data buffer
                     cbBuffer,                  // Size of buffer
                     &cbBufferNeeded);          // Size required

         printf("DosPrintDestGetInfo returned %u\n", uRet);
         if (uRet == NERR_Success)
            DisplayInfo(sLevel, pbBuffer, 1);   // Display buffer
         free(pbBuffer);
      }
      else
         printf("DosPrintDestGetInfo returned %u\n", uRet);

   //=======================================================================
   //  DosPrintDestSetInfo
   //
   //  This API allows control over print destination settings.
   //  It must be called using level 3 (PRDINFO3).
   //
   //  In this example, a single element is set to the desired value.
   //  A program can also set all elements by setting the parameter number
   //  code to PARMNUM_ALL. Setting the logical address to a null string
   //  disconnects this printer from the computer.
   //=======================================================================

   uRet = DosPrintDestSetInfo(pszServer,     // Servername
                     pszPrinterName,            // Printername
                     3,                         // Level; must be 3
                     (char far *)szNull,        // Data
                     sizeof(szNull),            // Size of buffer
                     PRD_LOGADDR_PARMNUM);      // Parameter number code

      printf("DosPrintDestSetInfo returned %u", uRet);
      if (uRet)
         printf(": Disconnect failed");
      printf("\n");

   //========================================================================
   //  DosPrintDestEnum
   //
   //  This API lists all printers connected to the specified server.
   //  Allocate a buffer for the returned data. If the buffer is too
   small,
   //  try again with a bigger buffer, and keep trying until the buffer
   //  is large enough or until it cannot be made any larger.
   //========================================================================

      cbBuffer = DEFAULT_BUF_SIZE;
      pbBuffer = SafeMalloc(cbBuffer); // SafeMalloc() is in SAMPLES.C
      do
      {
          uRet = DosPrintDestEnum (pszServer,   // Servername
                     sLevel,                    // Call level
                     pbBuffer,                  // Buffer for info
                     cbBuffer,                  // Size of buffer
                     &cEntriesRead,             // Count of entries read
                     &cTotal);                  // Count of entries available

          if (uRet == ERROR_MORE_DATA)
          {
             free(pbBuffer);                    // Buffer too small
             if (cbBuffer == MAX_BUFFER_SIZE)
             {
                printf("Exceeded buffer size\n");
                exit(1);
             }
             else if (cbBuffer > (MAX_BUFFER_SIZE/2))
                cbBuffer = MAX_BUFFER_SIZE;
             else
                cbBuffer += cbBuffer;           // Allocate larger buffer
             pbBuffer = SafeMalloc(cbBuffer);
             fDone = FALSE;
          }
          else
             fDone = TRUE;
      } while (fDone == FALSE);  // Loop until buffer big enough or call
   fails

      printf("DosPrintDestEnum returned %u\n", uRet);
      printf("   Entries read = %hu out of %hu\n", cEntriesRead, cTotal);

      if (uRet == NERR_Success)
         DisplayInfo(sLevel, pbBuffer, cEntriesRead);
      free(pbBuffer);

   //========================================================================
   //  DosPrintDestDel
   //
   //  This API deletes the print destination.
   //========================================================================

      if (fDelete == TRUE)
      {
         uRet = DosPrintDestDel(pszServer,       // Servername
                                pszPrinterName); // Printername
         printf("DosPrintDestDel returned %u\n", uRet);
      }
      exit(0);
   }  // End of main

   //=======================================================================
   //  DisplayInfo
   //
   //  Displays the print destination information obtained by
   //  DosPrintDestGetInfo or DosPrintDestEnum.
   //=======================================================================

   void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries)
   {
      char *         pprd0Info;   // Level 0 data
      PPRDINFO       pprd1Info;   // Pointer to level 1 structure
      PSZ *          pprd2Info;   // Array of pointers
      PPRDINFO3      pprd3Info;   // Pointer to level 3 structure
      unsigned short iCount;      // Index counter

      pprd0Info = (char *) pbBuffer;
      pprd1Info = (PPRDINFO) pbBuffer;
      pprd2Info = (PSZ *) pbBuffer;
      pprd3Info = (PPRDINFO3) pbBuffer;

   for (iCount = 0; iCount < cEntries; iCount++)
      {
         switch (sLevel)
         {
            case 0:
               printf("   Printer Name:  %s\n", pprd0Info);
               pprd0Info += (strlen(pprd0Info) + 1);
               break;
            case 1:
               printf("   Printer Name:  %s\n", pprd1Info->szName);
               printf("   User Name   :  %s\n", pprd1Info->szUserName);
               printf("   Job Id      :  %hu\n", pprd1Info->uJobId);
               if (pprd1Info->uJobId)  // Data valid only while job prints
               {
                  printf("   Job Status  :  0x%hx\n", pprd1Info->fsStatus);
                  printf("   Status Text :  %Fs\n", pprd1Info->pszStatus);
                  printf("   Time        :  %hu\n", pprd1Info->time);
               }
               pprd1Info++;
               break;
            case 2:
               printf("   Printer Name:  %Fs\n", *pprd2Info++);
               break;
            case 3:
               printf("   Printer Name:  %Fs\n", pprd3Info->pszPrinterName);
               printf("   Logical Addr:  %Fs\n", pprd3Info->pszLogAddr);
               printf("   Drivers     :  %Fs\n", pprd3Info->pszDrivers);
               printf("   Comment     :  %Fs\n", pprd3Info->pszComment);
               printf("   Job Id      :  %hu\n", pprd3Info->uJobId);
               if (pprd3Info->uJobId)
               {
                  printf("   User Name   :  %Fs\n", pprd3Info->pszUserName);
                  printf("   Job Status  :  0x%hx\n", pprd3Info->fsStatus);
                  printf("   Status Text :  %Fs\n", pprd3Info->pszStatus);
                  printf("   Print time  :  %hu\n", pprd3Info->time);
               }
               pprd3Info++;
               break;
            default:
               break;
         } // End switch sLevel
      } // End for loop
   }  // End function

   //=======================================================================
   //  Usage
   //
   //  Display possible command-line switches for this sample program.
   //=======================================================================

   void Usage(char *pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-l level]", pszProgram);
      fprintf(stderr, " [-d driver]\n\t[-p printer] [-f flag delete]");
      fprintf(stderr, " [-a address] [-o operation]\n");
      exit(1);
   }





 Print Job Category

 Print Job API functions control the print jobs in a printer queue. When
 executed locally, Print Job functions do not require that the NETWKSTA
 device driver be installed. When a servername is supplied, they require that
 the Workstation service be started.

 The Print Job category functions, datatypes, structures, and constants are
 defined in the PMSPL.H header file. A source program can access these
 definitions by including the PMSPL.H header file. A source program can
 access error codes by defining the constant INCL_NETERRORS and including the
 LAN.H header file. For more information, see the "Example" section, later in
 this category.

 These are the Print Job API functions:


   þ   DosPrintJobContinue

   þ   DosPrintJobDel

   þ   DosPrintJobEnum

   þ   DosPrintJobGetId

   þ   DosPrintJobGetInfo

   þ   DosPrintJobPause

   þ   DosPrintJobSetInfo



 Description

 A print job is a file submitted to a printer queue for printing. The Print
 Job API functions control individual jobs within printer queues, and can
 change the position of a print job in the queue, pause a print job, or
 delete it from the queue.

 DosPrintJobGetId returns the identification number of the spooling job. The
 print spooler assigns an identification number when the job is queued.

 DosPrintJobEnum lists the print jobs in a particular printer queue.
 DosPrintJobGetInfo retrieves information about a particular print job.
 DosPrintJobSetInfo sets parameters related to the print job, such as its
 priority.

 DosPrintJobPause pauses a print job. DosPrintJobContinue allows a paused
 print job to continue.

 DosPrintJobDel removes a print job from a printer queue.

 The Print Job data structures and the Print Job API functions use MS OS/2
 conventions for names and type definitions. The OS2DEF.H header file defines
 these types:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 MS OS/2 Type Definition           C-Language Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 CHAR                              char
 HFILE                             unsigned short
 PBYTE                             unsigned char far *
 PSZ                               unsigned char far *
 PUSHORT                           unsigned short *
 SPLENTRY                          pascal far
 SPLERR                            unsigned
 USHORT                            unsigned short
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 MS OS/2 Type Definition           C-Language Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Data Structures

 Level 0 and level 1 data structures are provided for compatibility with
 existing LAN Manager 1.0 applications. LAN Manager 2.0 applications should
 use level 0, 2, and 3 data structures.

 Existing LAN Manager 1.0 applications (that use the level 0 and level 1
 Print Job data structures) can be compiled and linked using the 1.0 header
 file NETSPOOL.H and the 1.0-compatible libraries NETSPOOL.LIB and
 NETSPOOL.DLL.

 Applications designed to run with both MS OS/2 1.1 and MS OS/2 1.2 should
 use the new level 0 and level 1 data structure names, include the PMSPL.H
 header file, and link with the NETSPOOL libraries.

 Applications that are designed to run only with MS OS/2 1.2 should use the
 PMSPL.LIB and PMSPL.DLL libraries. The PMSPL library functions provide
 better performance than the corresponding functions in the NETSPOOL library.


 Applications that run only with MS OS/2 1.2 can be built from existing
 applications. These applications can be upgraded by changing the data
 structure and element names. References to the prjob_info data structure and
 element names can be changed to the PRJINFO data structure and element
 names. There is one-to-one mapping from the prjob_info elements to the
 PRJINFO elements, as shown in the following table:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 LAN Manager 1.0                    LAN Manager 2.0
 prjob_info Element                 PRJINFO Element
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 prjob_id                           uJobId

 prjob_username                     szUserName

 prjob_pad_1                        pad_1
 LAN Manager 1.0                    LAN Manager 2.0
 prjob_info Element                 PRJINFO Element
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
prjob_pad_1                        pad_1

 prjob_notifyname                   szNotifyName

 prjob_datatype                     szDataType

 prjob_parms                        pszParms

 prjob_position                     uPosition

 prjob_status                       fsStatus

 prjob_status_string                pszStatus

 prjob_submitted                    ulSubmitted

 prjob_size                         ulSize

 LAN Manager 1.0                    LAN Manager 2.0
 prjob_info Element                 PRJINFO Element
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 prjob_comment                      pszComment

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 The new data structures are supported when they are directed to servers that
 run LAN Manager 1.0 software (down-level servers). New elements are given
 default values or values that indicate the element is not available, such as
 NULL.

 DosPrintJobSetInfo uses the level 1 data structure PRJINFO and the level 3
 data structure PRJINFO3. DosPrintJobEnum uses levels 0, 1, and 2.
 DosPrintJobGetInfo uses levels 0, 1, 2, and 3.

 DosPrintJobGetId returns the PRIDINFO data structure.


 Print Job Identification Number (level 0)

 At level 0, data is returned in this format:

   USHORT  uJobId;

 where

 uJobId
   Contains an unsigned short integer that specifies the identification
   number assigned to the print job when it was queued. The identification
   number is unique on a particular computer. A combination of the
   computername and uJobId is sufficient to uniquely identify a particular
   print job.


 Print Job Information (level 1)

 The PRJINFO data structure has this format:

   typedef struct _PRJINFO {
       USHORT  uJobId;
       CHAR    szUserName[UNLEN+1];
       CHAR    pad_1;
       CHAR    szNotifyName[CNLEN+1];
       CHAR    szDataType[DTLEN+1];
       PSZ     pszParms;
       USHORT  uPosition;
       USHORT  fsStatus;
       PSZ     pszStatus;
       ULONG   ulSubmitted;
       ULONG   ulSize;
       PSZ     pszComment;
   } PRJINFO;

 where

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job. The identification number is assigned by the
   print spooler.

 szUserName
   Contains an ASCIIZ string that specifies which user submitted the print
   job. The constant UNLEN is defined in the PMSPL.H header file. A null
   string indicates that the job was submitted from the local computer and
   the user did not log on.

 pad_1
   Aligns the next data structure element on a word boundary.

 szNotifyName
   Contains an ASCIIZ string that specifies the message alias that receives
   alert messages relating to the print job. The constant CNLEN is defined in
   the PMSPL.H header file. A null string is used for jobs submitted from the
   local computer.

 szDataType
   Contains an ASCIIZ string that specifies the datatype for the print job.
   This element corresponds to the pszDataType element of the MS OS/2
   DEVOPENSTRUC data structure that was supplied when the job was created.
   The DEVOPENSTRUC data structure is defined in the OS2DEV.H header file.
   The constant DTLEN is defined in the PMSPL.H header file.

 pszParms
   Points to an ASCIIZ string that contains a parameter string to pass to the
   spooler. The parameter string has this format:

   parm1=value1 parm2=value2 ...

   Note that a single space separates the parameter and value pairs.

 uPosition
   Contains an unsigned short integer that specifies the position of the
   print job in the printer queue. If uPosition is 1, the print job prints
   next.

 fsStatus
   Contains an unsigned short integer used as a status flag. Possible values
   are defined in the PMSPL.H header file.

   Bits 0-1 have the code PRJ_QSTATUS and the value 0x0003. This bit mask
   isolates the print job queued status bits, as follows:

 Bits  Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0-1   PRJ_QS_QUEUED    0      Print job is queued.

 0-1   PRJ_QS_PAUSED    1      Print job is paused.

 0-1   PRJ_QS_SPOOLING  2      Print job is spooling.

 0-1   PRJ_QS_PRINTING  3      Print job is printing
                               (bits 2-11 are valid).

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


   Bits 2-11 indicate the print job status. Bits 2-11 can be isolated using
   the constant PRJ_DEVSTATUS, which has the value 0x0FFC. Bit 15 signals
   whether an alert indicated that the print job was deleted. These are the
   meanings for individual bits:

ÖÚÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 2    PRJ_COMPLETE     0x0004  If 1, the print job is complete.

 3    PRJ_INTERV       0x0008  If 1, intervention is required.

 4    PRJ_ERROR        0x0010  If 1, an error occurred (pszStatus can
                               contain a comment explaining the error).

 5    PRJ_DESTOFFLINE  0x0020  If 1, the print destination is offline.

 6    PRJ_DESTPAUSED   0x0040  If 1, the print destination is paused.

 7    PRJ_NOTIFY       0x0080  If 1, an alert is raised.

 8    PRJ_DESTNOPAPER  0x0100  If 1, the print destination is out of paper.

 9    PRJ_DESTFORMCHG  0x0200  If 1, the printer is waiting for a form
                               change.

 10   PRJ_DESTCRTCHG   0x0400  If 1, the printer is waiting for a cartridge
 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
10   PRJ_DESTCRTCHG   0x0400  If 1, the printer is waiting for a cartridge
                               change.

 11   PRJ_DESTPENCHG   0x0800  If 1, the printer is waiting for a pen
                               change.

 15   PRJ_DELETED      0x8000  If 1, an alert indicates the job was deleted.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 pszStatus
   Points to an ASCIIZ string that contains a comment about the status of the
   print job posted by the queue's print processor. A null pointer or null
   string indicates that no information was posted. This element contains
   valid data only while the job is printing and an error occurs.

 ulSubmitted
   Contains an unsigned long integer that specifies the time the user
   submitted the print job. The time is stored in seconds elapsed since
   00:00:00, January 1, 1970.

 ulSize
   Contains an unsigned long integer that specifies the size (in bytes) of
   the print job.

 pszComment
   Points to an ASCIIZ string that contains a comment about the print job.
   This string can have as many as MAXCOMMENTSZ bytes. The constant
   MAXCOMMENTSZ is defined in the PMSPL.H header file.


 Print Job Information (level 2)

 The PRJINFO2 data structure has this format:

   typedef struct _PRJINFO2 {
       USHORT  uJobId;
       USHORT  uPriority;
       PSZ     pszUserName;
       USHORT  uPosition;
       USHORT  fsStatus;
       ULONG   ulSubmitted;
       ULONG   ulSize;
       PSZ     pszComment;
       PSZ     pszDocument;
   } PRJINFO2;

 where

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job. The identification number is assigned by the
   print spooler.

 uPriority
   Contains an unsigned short integer that specifies the priority of the
   print job. The range is 1 (lowest priority) through 99 (highest priority).
   If the constant PRJ_NO_PRIORITY is used, a default job priority is
   computed based on the queue priority. The default job priority is defined
   as follows:

   default job priority = 100 - (10 * queue priority)

   The constant PRJ_NO_PRIORITY is defined in the PMSPL.H header file. The
   job priority determines the order of jobs in the queue. If multiple queues
   print to the same printer, the spooler compares the priorities of the jobs
   at the front of the queues and schedules the job with the highest priority
   first. If job priorities are equal, the oldest job is scheduled.

 pszUserName
   Points to an ASCIIZ string that specifies the name of the user who
   submitted the print job.

 uPosition through pszComment
   Are the same as the corresponding elements of the PRJINFO data structure.
   For a complete description, see the preceding section.

 pszDocument
   Points to an ASCIIZ string that contains the document name of the print
   job. This string can have as many as CCHMAXPATH bytes. The constant
   CCHMAXPATH is defined in the MS OS/2 header file BSEDOS.H.


 Print Job Information (level 3)

 The PRJINFO3 data structure has this format:

   typedef struct _PRJINFO3 {
       USHORT     uJobId;
       USHORT     uPriority;
       PSZ        pszUserName;
       USHORT     uPosition;
       USHORT     fsStatus;
       ULONG      ulSubmitted;
       ULONG      ulSize;
       PSZ        pszComment;
       PSZ        pszDocument;
       PSZ        pszNotifyName;
       PSZ        pszDataType;
       PSZ        pszParms;
       PSZ        pszStatus;
       PSZ        pszQueue;
       PSZ        pszQProcName;
       PSZ        pszQProcParms;
       PSZ        pszDriverName;
       PDRIVDATA  pDriverData;
       PSZ        pszPrinterName;
   } PRJINFO3;

 where

 uJobId through pszDocument
   Are the same as the corresponding elements of the PRJINFO2 data structure.
   For a complete description, see the preceding section.

 pszNotifyName
   Points to an ASCIIZ string that contains the message alias that receives
   alert messages related to the print job. A null string indicates the job
   was submitted from the local computer.

 pszDataType
   Points to an ASCIIZ string that contains the datatype for the print job.
   This field corresponds to the pszDataType field of the MS OS/2
   DEVOPENSTRUC data structure supplied when the job was created. The
   DEVOPENSTRUC data structure is defined in the OS2DEV.H header file.

 pszParms
   Points to an ASCIIZ string that contains a parameter string to pass to the
   printer queue processor. The parameter string has this format:

   parms=value

 pszStatus
   Points to an ASCIIZ string that contains a comment about the status of the
   print job posted by the queue's print processor. A null pointer or null
   string indicates that no information was posted. This element contains
   valid data only while the job is printing and an error occurs.

 pszQueue
   Points to an ASCIIZ string that contains the name of the printer queue
   that contains the print job.

 pszQProcName
   Points to an ASCIIZ string that contains the name of the queue print
   processor.

 pszQProcParms
   Points to an ASCIIZ string that contains parameters passed to the queue
   print processor. The parameter string has the following format:

   parm1=value1 parm2=value2 ...

   Note that a single space separates the parameter and value pairs. An
   example  parameter, CPY=n, specifies that n copies of the document will be
   printed.

 pszDriverName
   Points to an ASCIIZ string that contains the name of the printer device
   driver.

 pDriverData
   Points to the MS OS/2 DRIVDATA data structure for the default driver. This
   data is specific to the device driver and is used only if pszDriverName is
   not null. The MS OS/2 DRIVDATA data structure is defined in the OS2DEF.H
   header file.

 pszPrinterName
   Points to an ASCIIZ string that contains the name of the printer on which
   the job is printing. If the job is not printing, pszPrinterName contains a
   null string or a null pointer.


 Print Job Identification Number

 DosPrintJobGetId returns the PRIDINFO data structure:

   typedef struct _PRIDINFO {
       USHORT  uJobId;
       CHAR    szServer[CNLEN+1];
       CHAR    szQName[QNLEN+1];
       CHAR    pad_1;
   } PRIDINFO;

 where

 uJobId
   Contains an unsigned short integer that specifies the identification
   number assigned to the print job when it was queued. The identification
   number is unique on a particular computer. A combination of the
   computername and uJobId is sufficient to uniquely identify a particular
   print job.

 szServer
   Specifies an ASCIIZ string that contains the name of the computer handling
   the print job. The constant CNLEN is defined in the PMSPL.H header file.
   If the name has more than CNLEN bytes, a null string is returned.

 szQName
   Specifies an ASCIIZ string that contains the name of the printer queue for
   the job. The constant QNLEN is defined in the PMSPL.H header file. If the
   name has more than QNLEN bytes, a null string is returned.

 pad_1
   Aligns the next data structure element on a word boundary.


 DosPrintJobContinue
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintJobContinue allows a paused print job to resume printing.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintJobContinue on a remote server or on a computer that has
 local security enabled, except when users are continuing their own jobs. In
 this case, no special privilege is required.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintJobContinue (PSZ     pszServer,
                        USHORT  uJobId
                       );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintJobContinue. A null pointer or null string specifies
   the local computer.

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_JobNotFound                  2151    No print job matches the print
                                           job identification number typed.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_JobInvalidState              2164    This operation cannot be
                                           performed on the print job in
                                           its current state.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          its current state.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosPrintJobContinue cannot continue a job that is already printing. Use
 DosPrintDestControl instead.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Obtaining the identification      DosPrintJobGetId
 number of a print job

 Pausing a print job               DosPrintJobPause

 Retrieving information about a    DosPrintJobGetInfo
 particular print job


 DosPrintJobDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintJobDel deletes a print job from a printer queue.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintJobDel on a remote server or on a computer that has local
 security enabled, except when users are deleting their own jobs. In this
 case, no special privilege is required.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintJobDel (PSZ     pszServer,
                   USHORT  uJobId
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintJobDel. A null pointer or null string specifies the
   local computer.

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_JobNotFound                  2151    No print job matches the print
                                           job identification number typed.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          job identification number typed.

 NERR_ProcNoRespond                2160    The print processor is not
                                           responding.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the print jobs in a       DosPrintJobEnum
 printer queue

 Obtaining the identification      DosPrintJobGetId
 number of a print job




 DosPrintJobEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintJobEnum lists print jobs in the specified printer queue.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute
 DosPrintJobEnum.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintJobEnum (PSZ      pszServer,
                    PSZ      pszQueueName,
                    USHORT   uLevel,
                    PBYTE    pbBuf,
                    USHORT   cbBuf,
                    PUSHORT  pcReturned,
                    PUSHORT  pcTotal
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintJobEnum. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that specifies which printer queue to monitor.

 uLevel
   Specifies the level of detail (0, 1, or 2) requested.

 pbBuf
   Points to the buffer in which to store the returned data.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 pcReturned
   Points to an unsigned short integer that specifies the number of entries
   returned to pbBuf. This count is valid only if DosPrintJobEnum returns
   NERR_Success or ERROR_MORE_DATA.

 pcTotal
   Points to an unsigned short integer that specifies the number of entries
   available. This count is valid only if DosPrintJobEnum returns
   NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                   Value   Meaning
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success           0       The function encountered no errors.

 ERROR_BAD_NETPATH      53      The network path was not found.

 ERROR_INVALID_LEVEL    124     The level for information retrieval or
                                setting is invalid.

 ERROR_MORE_DATA        234     Additional data is available.

 NERR_QNotFound         2150    The queue name specified is invalid.

 NERR_SpoolerNotLoaded  2161    The spooler is not started.

 NERR_InvalidComputer   2351    The specified computername is invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Level 0 and level 1 calls are compatible with existing LAN Manager 1.0
 applications. Note that for LAN Manager 2.0 three new print destination
 status bits (9, 10, and 11) are added to the fsStatus element of the PRJINFO
 data structure. Existing applications that do not examine these new status
 bits may not accurately report the status.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Modifying instructions for a      DosPrintJobSetInfo
 submitted print job

 Retrieving information about a    DosPrintJobGetInfo
 particular print job


 DosPrintJobGetId
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintJobGetId retrieves information about a remote print job.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only with handle to remote queue name

   þ   MS OS/2 version 1.1, local only with handle to remote queue name

   þ   MS-DOS, local only with handle to remote queue name



 Privilege Level

 DosPrintJobGetId is a handle-based function. If you have privilege to open
 the file to get the handle, you do not need special privilege to call
 DosPrintJobGetId.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintJobGetId (HFILE      hFile,
                     PPRIDINFO  pInfo,
                     USHORT     cbInfo
                    );

 where

 hFile
   Specifies the handle of a redirected print device.

 pInfo
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains the PRIDINFO data structure.

 cbInfo
   Specifies the size (in bytes) of the data returned in the buffer pointed
   to by pInfo.


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success           0       The function encountered no errors.

 ERROR_ACCESS_DENIED    5       The user has insufficient privilege for
                                this operation.

 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_HANDLE   6       The handle specified is invalid.

 ERROR_NOT_SUPPORTED    50      This network request is not supported.

 NERR_DevNotRedirected  2107    The devicename is not assigned to a shared
                                resource.

 NERR_BufTooSmall       2123    The supplied buffer is too small.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosPrintJobGetId is handle-based. The handle must be a valid handle to a
 remote spooled queue. The handle cannot be a handle to a local job.

 If LAN Manager is not installed, DosPrintJobGetId returns
 ERROR_NOT_SUPPORTED.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the print jobs in a       DosPrintJobEnum
 printer queue

 Modifying the instructions for a  DosPrintJobSetInfo
 submitted print job

 Retrieving information about a    DosPrintJobGetInfo
 particular print job


 DosPrintJobGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintJobGetInfo retrieves information about a particular print job.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege is required to successfully execute DosPrintJobGetInfo.



 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintJobGetInfo (PSZ      pszServer,
                       USHORT   uJobId,
                       USHORT   uLevel,
                       PBYTE    pbBuf,
                       USHORT   cbBuf,
                       PUSHORT  pcbNeeded
                      );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintJobGetInfo. A null pointer or null string specifies the
   local computer.

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job.

 uLevel
   Specifies the level of detail (0, 1, 2, or 3) requested.

 pbBuf
   Points to the buffer in which data is returned.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 pcbNeeded
   Points to an unsigned short integer that specifies the number of bytes of
   information available. This count is valid only if DosPrintJobGetInfo
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success           0       The function encountered no errors.

 ERROR_BAD_NETPATH      53      The network path was not found.

 ERROR_INVALID_LEVEL    124     The level for information retrieval or
                                setting is invalid.

 ERROR_MORE_DATA        234     Additional data is available.

 NERR_RemoteOnly        2106    This operation can be performed only on a
                                server.

 NERR_BufTooSmall       2123    The supplied buffer is too small.

 NERR_JobNotFound       2151    No print job matches the print job
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_JobNotFound       2151    No print job matches the print job
                                identification number typed.

 NERR_SpoolerNotLoaded  2161    The spooler is not started.

 NERR_InvalidComputer   2351    The specified computername is invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the print jobs in a       DosPrintJobEnum
 printer queue

 Modifying the instructions for a  DosPrintJobSetInfo
 submitted print job

 Obtaining the identification      DosPrintJobGetId
 number of a print job


 DosPrintJobPause
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintJobPause pauses a print job in a printer queue.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintJobPause on a remote server or on a computer that has local
 security enabled, except when users are pausing their own jobs. In this
 case, no special privilege is required.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintJobPause (PSZ     pszServer,
                     USHORT  uJobId
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintJobPause. A null pointer or null string specifies the
   local computer.

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_JobNotFound                  2151    No print job matches the print
                                           job identification number typed.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          job identification number typed.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_JobInvalidState              2164    This operation cannot be
                                           performed on the print job in
                                           its current state.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosPrintJobPause cannot pause a job that is already printing. Use
 DosPrintDestControl instead. If the print job is printing when the
 application calls DosPrintJobPause, the error code NERR_JobInvalidState is
 returned.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Continuing a paused print job     DosPrintJobContinue

 Obtaining the identification      DosPrintJobGetId
 number of a print job

 Retrieving information about a    DosPrintJobGetInfo
 particular print job


 DosPrintJobSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintJobSetInfo modifies the instructions for a submitted print job.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintJobSetInfo on a remote server or on a computer that has
 local security enabled, except when users are setting information for their
 own job. In this case, the only restriction is that users cannot move their
 jobs forward in the queue.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintJobSetInfo (PSZ     pszServer,
                       USHORT  uJobId,
                       USHORT  uLevel,
                       PSZ     pbBuf,
                       USHORT  cbBuf,
                       USHORT  uParmNum
                      );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintJobSetInfo. A null pointer or null string specifies the
   local computer.

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job.

 uLevel
   Specifies the level of detail (1 or 3) provided.

 pbBuf
   Points to a buffer that contains the data to be set.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 uParmNum
   Specifies whether to set one or all elements of the print job data
   structure. If uParmNum is PARMNUM_ALL, pbBuf must point to the print job
   data structure that corresponds to the uLevel parameter (level 1 indicates
   PRJINFO, level 3 indicates PRJINFO3). If uParmNum is any other defined
   value, only one element of the print job information is changed, and pbBuf
   must point to a valid value for that element.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The PMSPL.H and NETCONS.H
   header files define these possible values for uParmNum:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
                                Element of PRJINFO and PRJINFO3
 Code                    Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL             0      All elements.

 PRJ_NOTIFYNAME_PARMNUM  3      szNotifyName or pszNotifyName

 PRJ_DATATYPE_PARMNUM    4      szDataType or pszDataType

 PRJ_PARMS_PARMNUM       5      pszParms
                                Element of PRJINFO and PRJINFO3
 Code                    Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
PRJ_PARMS_PARMNUM       5      pszParms

 PRJ_POSITION_PARMNUM    6      uPosition

 PRJ_COMMENT_PARMNUM     11     pszComment

 PRJ_DOCUMENT_PARMNUM    12     pszDocument (level 3 only)

 PRJ_PRIORITY_PARMNUM    14     uPriority (level 3 only)

 PRJ_PROCPARMS_PARMNUM   16     pszQProcParms (level 3 only)

 PRJ_DRIVERDATA_PARMNUM  18     pDriverData (level 3 only)

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   The uPosition element can have the following values:

 Value                             Position Change
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 No change.

 1                                 Moves to first place.

 n > 1                             Assumes position n in queue. If n is
                                   greater than the number of jobs in the
                                   queue, the job moves to the end of the
                                   queue.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_JobNotFound                  2151    No print job matches the print
                                           job identification number typed.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_JobInvalidState              2164    This operation cannot be
                                           performed on the print job in
                                           its current state.

 NERR_SpoolNoMemory                2165    A spooler memory allocation
                                           failure occurred.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_DriverNotFound               2166    The device driver specified has
                                           not been installed on the
                                           computer.

 NERR_ProcNotFound                 2168    The print processor has not been
                                           installed on the server.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Jobs created locally have no username, and can be operated upon by any user
 on the local computer. Admin privilege or printer operator privilege is
 required to operate on the job from a remote computer.

 The job position or job priority can be changed to allow a particular print
 job to print before other jobs in the queue. Applications or users without
 admin or print operator privilege can only move their own job backward in a
 printer queue and set the priority to a lower value. Without admin or print
 operator privilege, applications or users can improve the relative position
 of their job in the queue by changing all their other jobs in the queue to
 lower position or priority values. They cannot increase the job priority.

 When a new data structure is directed to a server running an earlier version
 of LAN Manager (a down-level server), the following parameter number codes
 are not supported: PRJ_PRIORITY_PARMNUM, PRJ_PROCPARMS_PARMNUM, and
 PRJ_DRIVERDATA_PARMNUM. The function returns ERROR_NOT_SUPPORTED for these
 codes. If the entire structure is passed, these unsupported entries are
 ignored.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the print jobs in a       DosPrintJobEnum
 printer queue

 Retrieving information about a    DosPrintJobGetInfo
 particular print job





 Print Job Category Example

   /*
      NETPRJ.C -- a program demonstrating the DosPrintJob API functions.

      Admin or print operator privilege is required to successfully
      execute the Print Job API functions on a remote server.

      DosPrintJobGetId is called to demonstrate that a Print Job ID can
      be returned for those applications that use Open to access a printer.
      This print job ID can then be used as an input parameter for the
   other
      Print Job API functions.

      This program calls DosPrintJobEnum to list all jobs in the specified
      queue. If the user did not select a job ID from the command
      line, the program selects the first job ID returned by the Enum
      function as the target job ID used in all other calls.

      DosPrintJobPause is called to pause the job, DosPrintJobSetInfo
      changes the job's position in the printer queue, DosPrintJobGetInfo
      displays the new settings, DosPrintJobContinue releases the paused
      job, and DosPrintJobDel deletes the job.

      Usage:  netprj [-s \\server] [-q queue] [-l level] [-n nth position]
                     [-f flag] [-j jobid]
      where  \\server     = Name of the server. A servername must be
                            preceded by two backslashes (\\).
             queue        = Name of the printer queue.
             level        = Level of detail.
             nth position = Job's new position in the queue.
             flag         = Flag to delete the job; 0 = no, 1 = yes.
             jobid        = ID of the target job for all function calls.

      API                     Used to...
      ===================     ===========================================
      DosPrintJobGetId        Get info about the print job (using handle)
      DosPrintJobEnum         List all print jobs in the specified queue
      DosPrintJobPause        Pause a print job in a printer queue
      DosPrintJobSetInfo      Set one or all print job parameters
      DosPrintJobGetInfo      Get info about the print job (using job
   ID)
      DosPrintJobContinue     Continue a paused print job
      DosPrintJobDel          Delete a print job from the queue

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */
   #define  INCL_BASE
   #include <os2.h>             // MS OS/2 base header files
   #include <pmspl.h>           // Print definitions

   #define  INCL_NETERRORS
   #include <lan.h>             // LAN Manager header files

   #include <fcntl.h>           // File-related defines
   #include <io.h>              // File-related functions
   #include <malloc.h>          // Memory allocation functions
   #include <share.h>           // File-related defines
   #include <stdio.h>           // C run-time header files
   #include <stdlib.h>
   #include <string.h>
   #include <time.h>

   #include "samples.h"         // SafeMalloc(), FarStrcpy(), etc.

   #define  DEFAULT_POS           1
   #define  DEFAULT_BUFFER_SIZE   512
   #define  MAX_BUFFER_SIZE       32768
   #define  DEFAULT_QUEUE         "PRINTQ"

   void DisplayInfo(USHORT uLevel, PBYTE pbBuffer, USHORT cEntries);
   void Usage(PSZ pszString);

   void main(int argc, char *argv[])
   {
      CHAR    szPath[2+CNLEN+1+UNLEN+1];     // Allow for slashes and
   NUL
      HFILE   hFile;                         // File handle
      INT     iCount;                        // Index, loop counter
      PBYTE   pbBuffer;                      // Pointer to return data
      PSZ     pszServerName = "";            // Default to local computer
      PSZ     pszQueueName = DEFAULT_QUEUE;  // Queuename
      SPLERR  uRet;                          // Return code
      USHORT  uLevel = 2;                    // Level of detail
      USHORT  fDone;                         // Flag successful call
      USHORT  fDelete = TRUE;                // Flag whether to delete
   or not
      USHORT  cEntriesRead;                  // Entries in buffer
      USHORT  cEntriesTotal;                 // Entries available
      USHORT  cbBuffer = 0;                  // Count of bytes in buffer
      USHORT  cbBufferNeeded = 0;            // Count of bytes available
      USHORT  uNewPosition = DEFAULT_POS;    // New position in queue;
   1 = top
      USHORT  uJobId = 0;                    // Print job ID number
      PPRIDINFO pprid;                       // DosPrintJobGetId data

   for (iCount = 1; iCount < argc; iCount++) // Get cmd-line
   switches
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':   // -s servername
                  pszServerName = argv[++iCount];
                  break;
               case 'q':   // -q queuename
                  pszQueueName = argv[++iCount];
                  break;
               case 'l':   // -l level
                  uLevel = atoi(argv[++iCount]);
                  break;
               case 'n':   // -n nth position in queue
                  uNewPosition = atoi(argv[++iCount]);
                  break;
               case 'f':   // -f flag for delete
                  fDelete = atoi(argv[++iCount]);
                  break;
               case 'j':
                  uJobId = atoi(argv[++iCount]);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      } // End for loop
      printf("\nPrint Job Category API Examples\n");

   //========================================================================
   //  DosPrintJobGetId
   //
   //  This API returns a job ID to allow existing applications that

   //  write directly to a remote server printer queue to use Print Job

   //  API functions. The input parameter is a handle to the remote
   //  printer queue.
   //========================================================================

   if ((pszServerName != NULL) && (*pszServerName != '\0'))
   // Remote only
      {
         FarStrcpy((PSZ)szPath, pszServerName);  // Servername
         strcat(szPath, "\\");                   // Slash precedes sharename
         FarStrcat((PSZ)szPath, pszQueueName);   // Queuename

         //  Open the file on the remote queue to obtain the handle.
         hFile = sopen(szPath,     // Remote printer queue: \\server\queue
                       O_RDONLY,   // Open read-only
                       SH_DENYNO); // Share deny-none

         if (hFile == -1)
            printf("sopen failed opening %s\n", szPath);
         else
         {
            printf("sopen succeeded opening %s\n", szPath);
            /*
             * If sopen succeeded, prepare to call DosPrintJobGetId:
               Allocate a buffer for the return data.
             */
            if ((pprid = (PPRIDINFO)_fmalloc(sizeof(PRIDINFO))) == NULL)
               exit(1);

            uRet = DosPrintJobGetId(hFile,   // Handle to printer queue
                          pprid,             // Pointer to return buffer
                          sizeof(PRIDINFO)); // Size of return buffer
            printf("DosPrintJobGetId returned %u\n", uRet);
            if (uRet == NERR_Success)
            {
               printf("Job ID   : %hu\n", pprid->uJobId);
               printf("Server   : %Fs\n",  pprid->szServer);
               printf("Queue    : %Fs\n",  pprid->szQName);
               /*
                * If an application prints using the handle,
                * DosPrintJobGetId can provide the job ID needed
                * to use the other Print Job API functions.
                */
               }
            _ffree((PVOID)pprid);
            close(hFile);       // Close handle
         }  // End successful sopen
      } // End if remote server

   //=======================================================================
   //  DosPrintJobEnum
   //
   //  This API lists all print jobs in the specified printer queue.
   //=======================================================================

      cbBuffer = DEFAULT_BUFFER_SIZE;
      if ((pbBuffer = (PBYTE)_fmalloc(cbBuffer)) == NULL)
      {
         printf("Cannot allocate buffer\n");
         exit(1);
      }

      do   // Call API function until buffer big enough or call fails
      {
         uRet = DosPrintJobEnum ( pszServerName, // Servername
                              pszQueueName,      // Queuename
                              uLevel,            // Call level
                              pbBuffer,          // Buffer for info
                              cbBuffer,          // Size of buffer
                              &cEntriesRead,     // Count of entries
   read
                              &cEntriesTotal);   // Count of entries
   available
         printf("DosPrintJobEnum returned %u\n", uRet);
         if ((uRet == NERR_BufTooSmall) || (uRet == ERROR_MORE_DATA))
         {
            // Allocate a buffer twice as large, up to the maximum size.
            _ffree((PVOID)pbBuffer);  // Buffer too small to hold data
            if (cbBuffer >= MAX_BUFFER_SIZE)
               exit(1);
            else if (cbBuffer > (MAX_BUFFER_SIZE/2))
               cbBuffer = MAX_BUFFER_SIZE;
            else
               cbBuffer += cbBuffer; // Allocate a larger one and try
   again
            if ((pbBuffer = (PBYTE)_fmalloc(cbBuffer)) == NULL)
               exit(1);
            fDone = FALSE;
         }
         else
            fDone = TRUE;
      } while (fDone == FALSE); // Loop until buffer big enough or call
   fails

   if (uRet == NERR_Success)
      {
         printf("DosPrintJobEnum read %hu ", cEntriesRead);
         printf(" out of %hu entries\n", cEntriesTotal);
         DisplayInfo(uLevel, pbBuffer, cEntriesRead);

   if ((uJobId == 0) && (cEntriesRead > 0))  // If data in
   the buffer
         {
            uJobId = *((USHORT FAR *)pbBuffer); // uJobId first, all
   levels
            printf(" Job ID for other functions = %hu\n", uJobId);
         }
      }
      _ffree((PVOID)pbBuffer);

   //=======================================================================
   //  DosPrintJobPause
   //
   //  This API pauses the specified print job.
   //=======================================================================

      uRet = DosPrintJobPause(pszServerName,  // Servername
                              uJobId);        // Job ID
      printf("DosPrintJobPause returned %u\n", uRet);

   //=======================================================================
   //  DosPrintJobSetInfo
   //
   //  This API allows control over one or all print job settings.
   //  In this example, a single element is set to the desired value
   //  (but a valid detail level [1 or 3] must still be provided).
   //=======================================================================

      uRet = DosPrintJobSetInfo(pszServerName,  // Servername
                          uJobId,               // Job ID
                          1,                    // Call level
                          (PBYTE)&uNewPosition, // Data to be set
                          sizeof(USHORT),       // Size of buffer
                          PRJ_POSITION_PARMNUM);// Set job position in
   queue
      printf("DosPrintJobSetInfo returned %u\n", uRet);

   //=======================================================================
   //  DosPrintJobGetInfo
   //
   //  This API returns information about one specific print job.
   //=======================================================================

      /*
       * Call with zero-length buffer, expect NERR_BufTooSmall.
       * Make a second call with the buffer of the required size.
       */

      uRet = DosPrintJobGetInfo(pszServerName,   // Servername
                            uJobId,              // Job ID
                            uLevel,              // Call level
                            NULL,                // Buffer for info
                            0,                   // Size of buffer
                            &cbBufferNeeded);    // Size required

      if (uRet == NERR_BufTooSmall)
      {
         cbBuffer = cbBufferNeeded;
         if ((pbBuffer = (PBYTE)_fmalloc(cbBuffer)) == NULL)
            exit(1);

         uRet = DosPrintJobGetInfo(pszServerName,// Servername
                               uJobId,           // Job ID
                               uLevel,           // Call level
                               pbBuffer,         // Buffer for info
                               cbBuffer,         // Size of buffer
                               &cbBufferNeeded); // Size required
      }
      printf("DosPrintJobGetInfo returned %u\n", uRet);
      if (uRet == NERR_Success)
         DisplayInfo(uLevel, pbBuffer, 1);  // Show results of GetInfo
      _ffree((PVOID)pbBuffer);

   //=======================================================================
   //  DosPrintJobContinue
   //
   //  This API allows a paused print job to continue.
   //=======================================================================

      uRet = DosPrintJobContinue(pszServerName,  // Servername
                                 uJobId);        // Job ID
      printf("DosPrintJobContinue returned %u\n", uRet);

   //=======================================================================
   //  DosPrintJobDel
   //
   //  This API deletes the print job. This sample program allows the
   user
   //  to specify a command-line flag that determines whether to delete

   //  the job or not.
   //=======================================================================

   if (fDelete == TRUE)
      {
         uRet = DosPrintJobDel(pszServerName, // Servername
                               uJobId);       // Job ID
         printf("DosPrintJobDel returned %u\n", uRet);
      }
      exit(0);
   }  // End of main

   //=======================================================================
   //  DisplayInfo
   //
   //  Display selected print job information obtained by
   //  DosPrintJobGetInfo or DosPrintJobEnum. DosPrintJobGetInfo allows

   //  levels 0, 1, 2, or 3. DosPrintJobEnum allows levels 0, 1, or 2.
   //=======================================================================

   void DisplayInfo(USHORT uLevel, PBYTE pbBuffer, USHORT cEntries)
   {
      PUSHORT   pprj0Info;  // Pointer to level 0 data structure
      PPRJINFO  pprj1Info;  // Pointer to level 1 data structure
      PPRJINFO2 pprj2Info;  // Pointer to level 2 data structure
      PPRJINFO3 pprj3Info;  // Pointer to level 3 data structure
      USHORT    iCount;     // Index, loop counter
      time_t    time;       // Convert job submission time

      pprj0Info = (PUSHORT) pbBuffer;    // Initialize pointers
      pprj1Info = (PPRJINFO) pbBuffer;
      pprj2Info = (PPRJINFO2) pbBuffer;
      pprj3Info = (PPRJINFO3) pbBuffer;

      for (iCount = 1; iCount <= cEntries; iCount++)
      {
         printf("\n");
         switch (uLevel)
         {
            case 0:
               printf("Job ID      :  %hu\n", *pprj0Info++);
               break;
            case 1:                     // Level 1 data in buffer
               printf("Job ID      :  %hu\n", pprj1Info->uJobId);
               printf("User Name   :  %Fs\n", pprj1Info->szUserName);
               printf("Position    :  %hu\n", pprj1Info->uPosition);
               printf("Job Status  :  0x%hx\n", pprj1Info->fsStatus);
               pprj1Info++;
               break;
            case 2:                     // Level 2 data in buffer
               printf("Job ID      : %hu\n", pprj2Info->uJobId);
               printf("Priority    : %hu\n", pprj2Info->uPriority);
               printf("User Name   : %Fs\n", pprj2Info->pszUserName);
               putenv("TZ=GMT0");   // Print time given in local time
               time = (time_t) pprj2Info->ulSubmitted;
               printf("Submitted   : %s", ctime(&time));
               printf("Job size    : %lu\n", pprj2Info->ulSize);
               pprj2Info++;
               break;

            case 3:                     // Level 3 data in buffer
               printf("Job ID      : %hu\n", pprj3Info->uJobId);
               printf("Priority    : %hu\n", pprj3Info->uPriority);
               printf("User Name   : %Fs\n", pprj3Info->pszUserName);
               printf("Queue       : %Fs\n", pprj3Info->pszQueue);
               printf("Printer Name: %Fs\n", pprj3Info->pszPrinterName);
               pprj3Info++;
               break;

            default:                    // Undefined level
               break;
         } // End switch uLevel
      } // End for loop
   }  // End function

   //=======================================================================
   //  Usage
   //
   //  Display possible command-line switches for this sample program.
   //=======================================================================

   void Usage(PSZ pszString)
   {
      fprintf(stderr, "Usage: %Fs [-s \\\\server] [-l level]", pszString);
      fprintf(stderr, " [-q queuename]\n\t[-j jobid] [-f flag delete]\n");
      exit(1);
   }







 Printer Queue Category

 Printer Queue API functions control the printer queues on a server. When
 executed locally, they do not require that the NETWKSTA device driver be
 installed. When a servername is supplied, they require that the Workstation
 service be started.

 The Printer Queue category functions, datatypes, structures, and constants
 are defined in the PMSPL.H header file. A source program can access these
 definitions by including the PMSPL.H header file. A source program can
 access error codes by defining the constant INCL_NETERRORS and including the
 LAN.H header file. For more information, see the "Example" section, later in
 this category.

 These are the Printer Queue API functions:


   þ   DosPrintQAdd

   þ   DosPrintQContinue

   þ   DosPrintQDel

   þ   DosPrintQEnum

   þ   DosPrintQGetInfo

   þ   DosPrintQPause

   þ   DosPrintQPurge

   þ   DosPrintQSetInfo



 Description

 A printer queue is an ordered list of print jobs on a computer. A single
 computer can have multiple printer queues. When a print job is submitted to
 a printer queue, the spooler directs the print job to a print processor for
 processing before printing. The print spooler continuously examines the
 printer queues. The action taken depends on the following:


   þ   Printer queue priority (in relation to other printer queues)

   þ   Time of day during which the printer queue accepts jobs

   þ   Print destination(s) available to the printer queue

   þ   Print processor, driver, and driver data defaults for jobs added to
       the queue


 DosPrintQAdd creates a printer queue on the specified server. DosPrintQDel
 deletes a printer queue.

 DosPrintQPause pauses the operation of a printer queue and suspends
 scheduling of all print jobs but the current job. A paused queue continues
 to accept new jobs. DosPrintQContinue resumes processing of print jobs in a
 paused printer queue. Print jobs can be submitted to a paused queue, but
 jobs are not spooled to a print destination or print processor until the
 printer queue resumes processing. DosPrintQPurge  removes all pending jobs
 in a printer queue, leaving only currently printing jobs.

 The DosPrintQEnum API function lists information about all printer queues on
 a server. The DosPrintQGetInfo API function retrieves information about a
 particular printer queue. The DosPrintQSetInfo API function allows you to
 change parameter settings for a particular printer queue.

 The Printer Queue data structures and the Printer Queue API functions use MS
 OS/2 conventions for names and type definitions. The OS2DEF.H header file
 defines these types:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 MS OS/2 Type Definition           C-Language Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 CHAR                              char
 PBYTE                             unsigned char far *
 PSZ                               unsigned char far *
 PUSHORT                           unsigned short *
 SPLENTRY                          pascal far
 SPLERR                            unsigned
 USHORT                            unsigned short
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Data Structures

 Level 0, level 1, and level 2 data structures are provided for compatibility
 with existing LAN Manager 1.0 applications. LAN Manager 2.0 applications
 should use level 3, level 4, and level 5 data structures.

 Existing LAN Manager 1.0 applications (that use the level 0, 1, and 2 data
 structures) can be compiled and linked using the 1.0 header file NETSPOOL.H
 and the 1.0-compatible libraries NETSPOOL.LIB and NETSPOOL.DLL.

 Applications designed to run with both MS OS/2 1.1 and MS OS/2 1.2 should
 use the new level 3, level 4, and level 5 data structure names, include the
 PMSPL.H header file, and link with the NETSPOOL libraries.

 Applications that are designed to run only with MS OS/2 1.2 should use the
 PMSPL.LIB and PMSPL.DLL libraries. The PMSPL library functions provide
 better performance than the corresponding functions in the NETSPOOL library.


 Applications that run only with MS OS/2 1.2 can be built from existing
 applications. These applications can be upgraded by changing the data
 structure and element names. References to the prq_info data structure and
 element names can be changed to the PRQINFO data structure and element
 names. The prq_processor element of the prq_info data structure must be
 changed. This element contains a path to a .EXE file; the corresponding
 pszPrProc element of the PRQINFO data structure contains a queue processor
 name.

 There is one-to-one mapping from the size and type of the prq_info elements
 to the PRQINFO elements, as shown in the following table:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 LAN Manager 1.0                  LAN Manager 2.0
 prq_info Element                 PRQINFO Element
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 prq_name                         szName

 prq_pad1                         pad_1

 prq_priority                     uPriority

 prq_starttime                    uStarttime

 prq_untiltime                    uUntiltime
 LAN Manager 1.0                  LAN Manager 2.0
 prq_info Element                 PRQINFO Element
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
prq_untiltime                    uUntiltime

 prq_separator                    pszSepFile

 prq_processor                    pszPrProc

 prq_destinations                 pszDestinations

 prq_parms                        pszParms

 prq_comment                      pszComment

 prq_status                       fsStatus

 prq_jobcount                     cJobs

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 LAN Manager 1.0                  LAN Manager 2.0
 prq_info Element                 PRQINFO Element
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 The new data structures are supported when they are directed to servers that
 run LAN Manager 1.0 software (down-level servers). New elements are given
 default values or values that indicate the element is not available, such as
 NULL.

 DosPrintQAdd and DosPrintQSetInfo use the level 1 data structure PRQINFO or
 the level 3 data structure PRQINFO3.

 DosPrintQEnum and DosPrintQGetInfo use levels 0, 1, 2, 3, 4, and 5.


 Printer Queue Name (level 0)

 At level 0, data is returned in this format:

   CHAR szName[QNLEN+1];

 where

 szName
   Contains an ASCIIZ string that specifies the name of a printer queue. The
   constant QNLEN is defined in the PMSPL.H header file.


 Printer Queue Information (level 1)

 The PRQINFO data structure has this format:

   typedef struct _PRQINFO {
       CHAR    szName[QNLEN+1];
       CHAR    pad_1;
       USHORT  uPriority;
       USHORT  uStarttime;
       USHORT  uUntiltime;
       PSZ     pszSepFile;
       PSZ     pszPrProc;
       PSZ     pszDestinations;
       PSZ     pszParms;
       PSZ     pszComment;
       USHORT  fsStatus;
       USHORT  cJobs;
   } PRQINFO;

 where

 szName
   Contains an ASCIIZ string that specifies the name of the printer queue.
   The constant QNLEN is defined in the PMSPL.H header file.

 pad_1
   Aligns the next data structure element on a word boundary.

 uPriority
   Contains an unsigned short integer that specifies the printer queue
   priority, ranging from 1 (highest) through 9 (lowest). When two or more
   printer queues submit print jobs to the same destination, jobs in printer
   queues with higher priorities are processed before those in lower-priority
   queues.

   The printer queue priority is used to determine the default print job
   priority. The default job priority is used when no priority is specified
   for the job or when the specified job priority is higher than the default
   job priority. For more information, see the Print Job category API
   functions.

 uStarttime
   Contains an unsigned short integer that specifies the time of day a
   printer queue becomes active and can start sending print jobs to print
   destinations. This value represents the number of minutes since 00:00
   (midnight). For example, a value of 60 indicates that the printer queue
   becomes active at 1:00 A.M.

 uUntiltime
   Contains an unsigned short integer that specifies the time of day a
   printer queue becomes inactive and stops sending print jobs to print
   destinations. This value  represents the number of minutes since 00:00
   (midnight). For example, a value of 1020 (60 minutes * 17 hours) indicates
   that the printer queue becomes inactive at 5:00 P.M.

 pszSepFile
   Points to an ASCIIZ string that contains the pathname of a separator page
   file. A relative pathname is relative to the current spool directory. The
   separator page file contains formatting information for the page(s) that
   separates print jobs. Separator pages are printed only by some print
   processors, such as LMPRINT; PMPRINT does not print them.

 pszPrProc
   Points to an ASCIIZ string that contains the name of the print processor.
   A null pointer or null string indicates the default queue processor.

 pszDestinations
   Points to an ASCIIZ string that contains a list of print destinations for
   this queue (the concatenated print destinations are separated by spaces).
   The specified print destinations process the print jobs in this printer
   queue. Print jobs submitted to the queue are sent to the first available
   destination in the list.

 pszParms
   Points to an ASCIIZ string that contains parameters required by printer
   queues. The parameter string has the following format:

   parm1=value1 parm2=value2 ...

   Note that a single space separates the parameter and value pairs.

 pszComment
   Points to an ASCIIZ string that contains a comment about the printer
   queue.

 fsStatus
   Contains an unsigned short integer that specifies the status of a printer
   queue. Possible values are defined in the PMSPL.H header file. The
   PRQ_STATUS_MASK code has a value of 3 and specifies the status of the
   printer queue, as follows:

 Code         Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PRQ_ACTIVE   0      Active.
 PRQ_PAUSE    1      Paused.
 PRQ_ERROR    2      Error occurred.
 PRQ_PENDING  3      Deletion pending.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 cJobs
   Contains an unsigned short integer that specifies the number of print jobs
   currently in the queue.


 Printer Queue and Job Information (level 2)

 Level 2 indicates that the return data consists of the Printer Queue data
 structure PRQINFO followed by a Print Job data structure PRJINFO for every
 job in the queue. For a full description of the Printer Queue data structure
 PRQINFO, see the preceding section.

 The Print Job data structure PRJINFO has this format:

   typedef struct _PRJINFO {
       USHORT  uJobId;
       CHAR    szUserName[UNLEN+1];
       CHAR    pad_1;
       CHAR    szNotifyName[CNLEN+1];
       CHAR    szDataType[DTLEN+1];
       PSZ     pszParms;
       USHORT  uPosition;
       USHORT  fsStatus;
       PSZ     pszStatus;
       ULONG   ulSubmitted;
       ULONG   ulSize;
       PSZ     pszComment;
   } PRJINFO;

 where

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job. The identification number is assigned by the
   print spooler.

 szUserName
   Specifies an ASCIIZ string that contains the name of the user who
   submitted the print job. The constant UNLEN is defined in the PMSPL.H
   header file. A null string indicates that the job was submitted from the
   local computer.

 pad_1
   Aligns the next data structure element on a word boundary.

 szNotifyName
   Contains an ASCIIZ string that specifies the message alias that receives
   alert messages relating to the print job. A null string indicates that the
   job was submitted from the local computer. The constant CNLEN is defined
   in the PMSPL.H header file.

 szDataType
   Contains an ASCIIZ string that specifies the datatype for the print job.
   This element corresponds to the pszDataType element of the MS OS/2
   DEVOPENSTRUC data structure supplied when the job was created.
   DEVOPENSTRUC is defined in the OS2DEV.H header file. The constant DTLEN is
   defined in the PMSPL.H header file.

 pszParms
   Points to an ASCIIZ string that contains a parameter string to pass to the
   printer queue processor. The parameter string has this format:

   parms=value

 uPosition
   Contains an unsigned short integer that specifies the position of the
   print job in the printer queue. If uPosition is 1, the print job prints
   next.

 fsStatus
   Contains an unsigned short integer used as a status flag. Possible values
   are defined in the PMSPL.H header file.

   Bits 0-1 have the code PRJ_QSTATUS and the value 0x0003. This bit mask
   isolates the print job queued status bits, as follows:

 Bits  Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0-1   PRJ_QS_QUEUED    0      Print job is queued.

 0-1   PRJ_QS_PAUSED    1      Print job is paused.

 0-1   PRJ_QS_SPOOLING  2      Print job is spooling.

 0-1   PRJ_QS_PRINTING  3      Print job is printing
                               (bits 2-11 are valid).

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


   Bits 2-11 indicate the print job status. Bits 2-11 can be isolated using
   the constant PRJ_DEVSTATUS, which has the value 0x0FFC. Bit 15 signals
   whether an alert indicated the print job was deleted. These are the
   meanings for individual bits:

ÖÚÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 2    PRJ_COMPLETE     0x0004  If 1, the job is complete.

 3    PRJ_INTERV       0x0008  If 1, intervention is required.

 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 4    PRJ_ERROR        0x0010  If 1, an error occurred (pszStatus can
                               contain a comment explaining the error).

 5    PRJ_DESTOFFLINE  0x0020  If 1, the print destination is offline.

 6    PRJ_DESTPAUSED   0x0040  If 1, the print destination is paused.

 7    PRJ_NOTIFY       0x0080  If 1, an alert is raised.

 8    PRJ_DESTNOPAPER  0x0100  If 1, the print destination is out of paper.

 9    PRJ_DESTFORMCHG  0x0200  If 1, the printer is waiting for a form
                               change.

 10   PRJ_DESTCRTCHG   0x0400  If 1, the printer is waiting for a cartridge
                               change.

 11   PRJ_DESTPENCHG   0x0800  If 1, the printer is waiting for a pen
 Bit  Code             Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
11   PRJ_DESTPENCHG   0x0800  If 1, the printer is waiting for a pen
                               change.

 15   PRJ_DELETED      0x8000  If 1, an alert indicates the print job was
                               deleted.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 pszStatus
   Points to an ASCIIZ string that contains a comment about the status of the
   print job posted by the queue's print processor. A null pointer or null
   string indicates that no information was posted.

 ulSubmitted
   Contains an unsigned long integer that specifies the time the user
   submitted the print job. The time is given as the number of seconds
   elapsed since 00:00:00, January 1, 1970.

 ulSize
   Contains an unsigned long integer that specifies the size (in bytes) of
   the print job.

 pszComment
   Points to an ASCIIZ string that contains a comment about the print job. It
   can have as many as MAXCOMMENTSZ bytes, as defined in the PMSPL.H header
   file.


 Printer Queue Information (level 3)

 The PRQINFO3 data structure has this format:

   typedef struct _PRQINFO3 {
       PSZ        pszName;
       USHORT     uPriority;
       USHORT     uStarttime;
       USHORT     uUntiltime;
       USHORT     pad1;
       PSZ        pszSepFile;
       PSZ        pszPrProc;
       PSZ        pszParms;
       PSZ        pszComment;
       USHORT     fsStatus;
       USHORT     cJobs;
       PSZ        pszPrinters;
       PSZ        pszDriverName;
       PDRIVDATA  pDriverData;
   } PRQINFO3;

 where

 pszName
   Points to an ASCIIZ string that contains the name of the printer queue.
   The queuename can have as many as CCHMAXPATHCOMP bytes, as defined in the
   MS OS/2 header file BSEDOS.H.

 uPriority through cJobs
   Are the same as the corresponding elements of the PRQINFO data structure.
   For a complete description, see "Printer Queue Information (level 1),"
   earlier in this category.

 pszPrinters
   Points to an ASCIIZ string that contains a list of printers that can print
   from the printer queue. These names reference printers that already exist.
   If a null pointer or null string is supplied, the queue is created but is
   not connected to any printers. Printernames in the list are separated by
   commas (,). If the printername contains spaces, the name should be
   enclosed in double quotation marks (" ").

 pszDriverName
   Points to an ASCIIZ string that contains the default device driver for the
   queue. The device driver must already have been installed. The default
   device driver is used to create a print job when only a queuename is
   specified. If a null pointer or null string is supplied, pDriverData is
   not used.

 pDriverData
   Points to the device driver data for the default driver. This data is
   specific to the device driver, and it is used only if pszDriverName is not
   a null pointer or null string.


 Printer Queue Information (level 4)

 Level 4 indicates that the return data consists of the Printer Queue data
 structure(s) PRQINFO3 followed by a Print Job data structure PRJINFO2 for
 each job in the queue.

 For a full description of the Printer Queue data structure PRQINFO3, see the
 preceding section.

 The Print Job data structure PRJINFO2 has this format:

   typedef struct _PRJINFO2 {
       USHORT  uJobId;
       USHORT  uPriority;
       PSZ     pszUserName;
       USHORT  uPosition;
       USHORT  fsStatus;
       ULONG   ulSubmitted;
       ULONG   ulSize;
       PSZ     pszComment;
       PSZ     pszDocument;
   } PRJINFO2;

 where

 uJobId
   Contains an unsigned short integer that specifies the identification
   number of the print job. The identification number is assigned by the
   print spooler.

 uPriority
   Contains an unsigned short integer that specifies the priority of the
   print job, ranging from 1 (lowest priority) through 99 (highest priority).
   The constant PRJ_NO_PRIORITY should be used to get the default job
   priority based on the queue priority. The constant PRJ_NO_PRIORITY is
   defined in the PMSPL.H header file.

   The job priority determines the order of jobs in the queue. If multiple
   queues print to the same printer, the jobs at the front of the queues are
   examined. The job with the highest priority is scheduled. If the job
   priorities are equal, the oldest job is scheduled.

 pszUserName
   Points to an ASCIIZ string that contains the name of the user who
   submitted the print job.

 uPosition through pszComment
   Are the same as the corresponding elements of the PRJINFO data structure.
   For a complete description, see "Printer Queue and Job Information (level
   2)," earlier in this category.

 pszDocument
   Points to an ASCIIZ string that contains the document name of the print
   job. The document name can have as many as CCHMAXPATH bytes, as defined in
   the MS OS/2 header file BSEDOS.H.


 Printer Queue Information (level 5)

 At level 5, data is returned in this format:

   PSZ  pszName;

 where

 pszName
   Points to an ASCIIZ string that specifies the name of the printer queue.
   The queuename can have as many as CCHMAXPATHCOMP bytes, as defined in the
   MS OS/2 header file BSEDOS.H.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Controlling a print destination   Print Destination Category

 Controlling print jobs            Print Job Category


 DosPrintQAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQAdd creates a printer queue on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintQAdd on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQAdd (PSZ     pszServer,
                 USHORT  uLevel,
                 PBYTE   pbBuf,
                 USHORT  cbBuf
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of a server on which to
   execute DosPrintQAdd. A null pointer or null string specifies the local
   computer.

 uLevel
   Specifies the level of detail (1 or 3) provided in the buffer pointed to
   by pbBuf. Level 1 is provided for compatibility with existing LAN Manager
   1.0 applications and should not be used in new applications. Only level 3
   should be used in new applications.

 pbBuf
   Points to the buffer that contains data for the printer queue to be added.
   The buffer should contain a PRQINFO or PRQINFO3 data structure,
   corresponding to the level specified by uLevel.

 cbBuf
   Specifies the size (in bytes) of the data buffer pointed to by pbBuf.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_RedirectedPath               2117    The operation is invalid for a
                                           redirected resource. The
                                           devicename specified is assigned
                                           to a shared resource.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_DestNotFound                 2152    The print destination was not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_DestNotFound                 2152    The print destination was not
                                           found.

 NERR_QExists                      2154    A printer queue with this name
                                           already exists.

 NERR_QNoRoom                      2155    The server does not have enough
                                           memory available to add another
                                           printer queue.

 NERR_DestNoRoom                   2157    The server does not have enough
                                           memory available to add another
                                           printer.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_DestInvalidState             2162    This operation cannot be
                                           performed on the print
                                           destination in its current state.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          destination in its current state.

 NERR_SpoolNoMemory                2165    A spooler memory allocation
                                           failure occurred.

 NERR_DriverNotFound               2166    The device driver specified has
                                           not been installed on the
                                           computer.

 NERR_DataTypeInvalid              2167    The datatype is not supported by
                                           the queue's print processor.

 NERR_ProcNotFound                 2168    The print processor has not been
                                           installed on the server.

 NERR_BadDev                       2341    The devicename is invalid
                                           because it does not represent a
                                           physical device, or because the
                                           device hardware is faulty.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          device hardware is faulty.

 NERR_CommDevInUse                 2343    The device is already used with
                                           a communication-device queue. It
                                           cannot be used with both
                                           communication-device queues and
                                           printer queues.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 The PRQINFO data structure is provided only for compatibility with existing
 LAN Manager 1.0 applications. All new applications should use the PRQINFO3
 data structure.

 If the specified queuename is already in use on the server, DosPrintQAdd
 fails unless the queue is marked for pending deletion. In this case, the
 queue is not deleted and the parameters provided in DosPrintQAdd are used to
 set the values of the queue configuration. (The queuename is specified by
 the szName element of the PRQINFO data structure or by the pszName element
 of the PRQINFO3 data structure.)

 If the queuename exceeds the maximum legal length, ERROR_INVALID_PARAMETER
 is returned. The maximum legal length depends on the installed file system.


 A queue can be added successfully even if it is not connected to a printer.
 A queue can be added successfully on an MS OS/2 1.2 workstation.

 Applications that use the level 3 data structure PRQINFO3 can specify that
 the queue should use the default pDriverData value by supplying a null
 pointer for the pDriverData parameter; a new pszDriverName element will be
 supplied.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Changing the parameters of a      DosPrintQSetInfo
 printer queue

 Deleting a printer queue          DosPrintQDel

 Listing a server's printer        DosPrintQEnum
 queues

 Retrieving information about a    DosPrintQGetInfo
 printer queue


 DosPrintQContinue
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQContinue allows a paused printer queue to resume printing.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintQContinue on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQContinue (PSZ  pszServer,
                      PSZ  pszQueueName
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of a server on which to
   execute DosPrintQContinue. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that contains the name of the printer queue.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_QNotFound                    2150    The queuename specified is
                                           invalid.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_QInvalidState                2163    This operation cannot be
                                           performed on the printer queue
                                           in its current state.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosPrintQContinue reenables a printer queue that has been paused by a call
 to DosPrintQPause or disabled by an error. DosPrintQContinue does not affect
 an active printer queue.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing a server's printer        DosPrintQEnum
 queues

 Pausing a printer queue           DosPrintQPause

 Retrieving information about a    DosPrintQGetInfo
 printer queue




 DosPrintQDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQDel deletes a printer queue from a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintQDel on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQDel (PSZ  pszServer,
                 PSZ  pszQueueName
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintQDel. A null pointer or null string specifies the local
   computer.

 pszQueueName
   Points to an ASCIIZ string that specifies which printer queue to delete.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_QNotFound                    2150    The queuename specified is
                                           invalid.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_QInvalidState                2163    This operation cannot be
                                           performed on the printer queue
                                           in its current state.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If print jobs remain to be processed in a printer queue, DosPrintQDel marks
 the printer queue as "pending delete" so it cannot accept new jobs, and
 deletes the queue when all jobs have been printed.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Canceling all print jobs in a     DosPrintQPurge
 printer queue

 Establishing a printer queue      DosPrintQAdd

 Listing a server's printer        DosPrintQEnum
 queues

 Retrieving information about a    DosPrintQGetInfo
 printer queue


 DosPrintQEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQEnum lists all printer queues on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute
 DosPrintQEnum.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQEnum (PSZ      pszServer,
                  USHORT   uLevel,
                  PSZ      pbBuf,
                  USHORT   cbBuf,
                  PUSHORT  pcReturned,
                  PUSHORT  pcTotal
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintQEnum. A null pointer or null string specifies the
   local computer.

 uLevel
   Specifies the level of detail (0, 1, 2, 3, 4, or 5) requested.

 pbBuf
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of data structures corresponding to
   the level of detail requested.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 pcReturned
   Points to an unsigned short integer that specifies the number of entries
   returned in the buffer pointed to by pbBuf. This count is valid only if
   DosPrintQEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotal
   Points to an unsigned short integer that specifies the total number of
   entries available. This count is valid only if DosPrintQEnum returns
   NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success           0       The function encountered no errors.

 ERROR_BAD_NETPATH      53      The network path was not found.

 ERROR_INVALID_LEVEL    124     The level for information retrieval or
                                setting is invalid.

 ERROR_MORE_DATA        234     Additional data is available.

 NERR_NetNotStarted     2102    The LAN Manager NETWKSTA driver is not
                                installed.

 NERR_RemoteOnly        2106    This operation can be performed only on a
 Code                   Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_RemoteOnly        2106    This operation can be performed only on a
                                server.

 NERR_SpoolerNotLoaded  2161    The spooler is not started.

 NERR_InvalidComputer   2351    The specified computername is invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Levels 0, 1, and 2 are provided only for compatibility with existing LAN
 Manager 1.0 applications and should not be used in new applications. All new
 applications should use levels 3, 4, and 5.

 Levels 0, 1, and 2 return queuenames only if the number of bytes in the
 queuename is less than or equal to QNLEN. (The constant QNLEN is defined in
 the PMSPL.H header file.) At levels 0, 1, and 2, the values of pcReturned
 and pcTotal are set to the count of queues with short names. At levels 3, 4,
 and 5, all queuenames are returned, and the values pcReturned and pcTotal
 represent the count of all queues.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Retrieving information about a    DosPrintQGetInfo
 printer queue


 DosPrintQGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQGetInfo retrieves information about a particular printer queue on a
 server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute
 DosPrintQGetInfo.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQGetInfo (PSZ      pszServer,
                     PSZ      pszQueueName,
                     USHORT   uLevel,
                     PSZ      pbBuf,
                     USHORT   cbBuf,
                     PUSHORT  pcbNeeded
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintQGetInfo. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that contains the name of the printer queue.

 uLevel
   Specifies the level of detail (0, 1, 2, 3, 4, or 5) requested.

 pbBuf
   Points to the buffer in which to store the return data. On a successful
   return, the buffer contains a sequence of data structures corresponding to
   the level of detail requested.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 pcbNeeded
   Points to an unsigned short integer that specifies the number of bytes of
   information available. This count is valid only if DosPrintQGetInfo
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_FILENAME_EXCED_RANGE        206     The filename specified is
                                           invalid for the file system.
                                           This code is returned when
                                           checking a FAT disk partition
                                           only. It cannot be returned for
                                           an HPFS partition.

 ERROR_MORE_DATA                   234     Additional data is available.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_QNotFound                    2150    The queuename specified is
                                           invalid.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Levels 0, 1, and 2 are provided for compatibility with existing LAN Manager
 1.0 applications and should not be used in new applications. All new
 applications should use levels 3, 4, and 5.

 Levels 0, 1, and 2 return queuenames only if the number of bytes in the
 queuename is less than or equal to QNLEN. (The constant QNLEN is defined in
 the PMSPL.H header file.) At levels 0, 1, and 2, the values of pcReturned
 and pcTotal are set to the count of queues with short names. At levels 3, 4,
 and 5, all queuenames are returned, and the values pcReturned and pcTotal
 represent the count of all queues.

 When a new data structure is directed to a server that runs an earlier
 version of LAN Manager (a down-level server), the elements uPriority,
 pszPrProc, and pszPrinters are given default values. The element pszPrProc
 points to the string "LM10," pszPrinters points to a list of port names
 separated by commas, and uPriority has the value PRJ_NO_PRIORITY.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Finding out a print job's         DosPrintJobGetInfo
 position in a queue

 Listing a server's printer        DosPrintQEnum
 queues

 Modifying the configuration of a  DosPrintQSetInfo
 printer queue


 DosPrintQPause
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQPause pauses the operation of a printer queue, suspending
 processing of all print jobs except the current job. A paused queue accepts
 new jobs.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintQPause on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQPause (PSZ  pszServer,
                   PSZ  pszQueueName
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintQPause. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that specifies which printer queue to pause.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_QNotFound                    2150    The queuename specified is
                                           invalid.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Pausing a printer queue suspends processing of all print jobs in the queue
 except the job that is printing. A paused queue can accept submitted print
 jobs, but it holds them in the queue until a call to DosPrintQContinue
 allows the queue to resume printing.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Continuing a paused printer       DosPrintQContinue
 queue

 Finding out the position of a     DosPrintJobGetInfo
 print job in a printer queue

 Retrieving information about a    DosPrintQGetInfo
 printer queue


 DosPrintQPurge
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQPurge removes all pending jobs in a printer queue, leaving only
 currently printing jobs.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintQPurge on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQPurge (PSZ  pszServer,
                   PSZ  pszQueueName
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintQPurge. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that specifies which printer queue to purge.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_QNotFound                    2150    The queuename specified is
                                           invalid.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 DosPrintQPurge does not affect a print job already sent to a print
 destination.

 If a printer queue is pending deletion when DosPrintQPurge is called, the
 purge clears the way for the printer queue to be deleted at the end of the
 current printing.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing a server's printer        DosPrintQEnum
 queues

 Listing the print jobs in a       DosPrintQGetInfo
 printer queue

 Retrieving information about a    DosPrintQGetInfo
 printer queue


 DosPrintQSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 DosPrintQSetInfo modifies the configuration of a printer queue.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or print operator privilege is required to successfully
 execute DosPrintQSetInfo on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_BASE
   #include <os2.h>

   #include <pmspl.h>

   #define INCL_NETERRORS
   #include <lan.h>

   SPLERR SPLENTRY
   DosPrintQSetInfo (PSZ     pszServer,
                     PSZ     pszQueueName,
                     USHORT  uLevel,
                     PSZ     pbBuf,
                     USHORT  cbBuf,
                     USHORT  uParmNum
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute DosPrintQSetInfo. A null pointer or null string specifies the
   local computer.

 pszQueueName
   Points to an ASCIIZ string that specifies which printer queue is to be
   modified.

 uLevel
   Contains an unsigned short integer that specifies the level of detail (1
   or 3) provided.

 pbBuf
   Points to the provided data structure or component.

 cbBuf
   Specifies the size (in bytes) of the buffer pointed to by pbBuf.

 uParmNum
   Specifies whether to set all printer queue information or to set only a
   part of it. If uParmNum is PARMNUM_ALL, pbBuf must point to a PRQINFO or
   PRQINFO3 data structure. If uParmNum is any other defined value, only one
   element of the printer queue information is changed, and  pbBuf must point
   to a valid value for that element.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The PMSPL.H header file defines
   these possible values for uParmNum:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
                                  Element of PRQINFO and PRQINFO3
 Code                      Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL               0      All elements.

 PRQ_PRIORITY_PARMNUM      2      uPriority

 PRQ_STARTTIME_PARMNUM     3      uStarttime

 PRQ_UNTILTIME_PARMNUM     4      uUntiltime

 PRQ_SEPARATOR_PARMNUM     5      pszSepFile

 PRQ_PROCESSOR_PARMNUM     6      pszPrProc

 PRQ_DESTINATIONS_PARMNUM  7      pszDestinations (level 1 only)

 PRQ_PARMS_PARMNUM         8      pszParms
                                  Element of PRQINFO and PRQINFO3
 Code                      Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
PRQ_PARMS_PARMNUM         8      pszParms

 PRQ_COMMENT_PARMNUM       9      pszComment

 PRQ_PRINTERS_PARMNUM      12     pszPrinters (level 3 only)

 PRQ_DRIVERNAME_PARMNUM    13     pszDriverName (level 3 only)

 PRQ_DRIVERDATA_PARMNUM    14     pDriverData (level 3 only)

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.



 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_RedirectedPath               2117    The operation is invalid for a
                                           redirected resource. The
                                           devicename specified is assigned
                                           to a shared resource.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_QNotFound                    2150    The queuename specified is
                                           invalid.

 NERR_DestNotFound                 2152    The print destination was not
                                           found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          found.

 NERR_DestNoRoom                   2157    The server does not have enough
                                           memory available to add another
                                           printer.

 NERR_SpoolerNotLoaded             2161    The spooler is not started.

 NERR_DestInvalidState             2162    This operation cannot be
                                           performed on the print
                                           destination in its current state.

 NERR_SpoolNoMemory                2165    A spooler memory allocation
                                           failure occurred.

 NERR_DriverNotFound               2166    The device driver specified has
                                           not been installed on the
                                           computer.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_DataTypeInvalid              2167    The datatype is not supported by
                                           the queue's print processor.

 NERR_ProcNotFound                 2168    The print processor has not been
                                           installed on the server.

 NERR_BadDev                       2341    The devicename is invalid
                                           because it does not represent a
                                           physical device, or because the
                                           device hardware is faulty.


 NERR_CommDevInUse                 2343    The device is already used with
                                           a communication-device queue. It
                                           cannot be used with both
                                           communication-device queues and
                                           printer queues.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 The PRQINFO data structure is provided only for compatibility with existing
 LAN Manager 1.0 applications. All new applications should use the PRQINFO3
 data structure.

 If the uPriority element of the PRQINFO3 data structure is set to
 PRQ_NO_PRIORITY, the queue priority is not changed.

 If a null pointer is provided for the pDriverData element of the PRQINFO3
 data structure, the spooler provides the default driver data.

 When a new data structure is directed to a server that is running an earlier
 version of LAN Manager (a down-level server), the PRQ_DRIVERNAME_PARMNUM and
 PRQ_DRIVERDATA_PARMNUM parameter number codes are not supported. The
 function returns ERROR_NOT_SUPPORTED for these codes. If the entire
 structure is passed, these unsupported entries are ignored. The code
 PRQ_PRINTERS_PARMNUM is interpreted as PRQ_DESTINATIONS_PARMNUM, and commas
 that are used as delimiters are replaced by blanks.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Establishing a printer queue      DosPrintQAdd

 Listing the printer queues on a   DosPrintQEnum
 server

 Retrieving a print job's          DosPrintJobGetId
 identification number

 Retrieving the configuration of   DosPrintQGetInfo
 a printer queue





 Printer Queue Category Example

   /*
      NETPRQ.C -- a program demonstrating the DosPrintQ API functions.

      This sample program demonstrates how to add a printer queue using

      DosPrintQAdd, then pauses the queue using DosPrintQPause and calls
      DosPrintQGetInfo to display its status. The queue priority is
      modified using DosPrintQSetInfo, and the new priority is displayed
      using DosPrintQEnum. DosPrintQPurge is called to purge all jobs
      from the queue, and then DosPrintQContinue allows the paused printer
      queue to continue. DosPrintQDel deletes the printer queue.

      usage:  netprj [-s \\server] [-l level] [-p priority] [-q queue]
                     [-f flag] [-c comment]
      where  \\server = Name of the server. A servername must be preceded

                        by two backslashes (\\).
             level    = Level of detail.
             priority = Priority of the queue.
             queue    = Name of the printer queue.
             flag     = Flag to delete the queue; 0 = no, 1 = yes.
             comment  = Queue's comment (enclose in quotes).

       API                     Used to...
       =================       ============================================
       DosPrintQAdd            Add a new printer queue
       DosPrintQContinue       Continue a paused printer queue
       DosPrintQDel            Delete the printer queue
       DosPrintQEnum           List all printer queues available
       DosPrintQGetInfo        Get specific info on a single printer
   queue
       DosPrintQPause          Pause the printer queue
       DosPrintQPurge          Delete all jobs from the printer queue
       DosPrintQSetInfo        Set specific info for a single printer
   queue

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define  INCL_BASE
   #include <os2.h>            // MS OS/2 base header files
   #include <pmspl.h>          // Print definitions

   #define  INCL_NETERRORS
   #include <lan.h>            // LAN Manager header files

   #include <stdio.h>          // C run-time header files
   #include <stdlib.h>
   #include <string.h>
   #include "samples.h"        // Internal routine header file

   #define DEFAULT_BUFFER_SIZE  1024
   #define MAX_BUFFER_SIZE      32768
   #define DEFAULT_PRIORITY     9
   #define NEW_PRIORITY         1
   #define NEWCOMMENT           "Print q built by example program"
   #define NEWQUEUENAME         "PRINTQ0"

   void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries);
   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      char *          pbBuffer;            // Buffer for return data
      char *          pszServer = "";      // Default to local computer
      char far *      pszQueueName = NEWQUEUENAME;
      char far *      pszComment = NEWCOMMENT;
      int             iCount;              // Index, loop counter
      PRQINFO3        prq3;                // Level 3 data structure
      short           sLevel = 3;          // Level of detail
      unsigned        uRet;                // Return code
      unsigned short  fDone;               // Flag successful call
      unsigned short  fDelete = TRUE;      // Delete queue flag
      unsigned short  cEntriesRead;        // Count of entries read
      unsigned short  cEntriesTotal;       // Count of entries available

      unsigned short  cbBuffer = 0;        // Count of bytes read
      unsigned short  cbBufferNeeded = 0;  // Count of bytes needed
      unsigned short  uPriority = NEW_PRIORITY;// Used to set queue

      for (iCount = 1; iCount < argc; iCount++) // Get command-line switches
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'p':                        // -p priority
                  uPriority = atoi(argv[++iCount]);
                  break;
               case 'l':                        // -l level
                  sLevel = atoi(argv[++iCount]);
                  break;
               case 'q':                        // -q queuename
                  pszQueueName = argv[++iCount];
                  break;
               case 'c':                        // -c comment
                  pszComment = argv[++iCount];
                  break;
               case 'f':                        // -f flag deletion
                  fDelete = atoi(argv[++iCount]);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      } // End for loop
      printf("\nPrint Queue Category API Examples\n");

   //========================================================================
   //  DosPrintQAdd
   //
   //  This API adds a printer queue to the specified server.
   //========================================================================

      memset(&prq3, 0, sizeof(PRQINFO3));       // Initialize memory
   to zeros
      prq3.pszName = pszQueueName;              // Set names
      prq3.uPriority = DEFAULT_PRIORITY;
      prq3.pszComment = pszComment;

      uRet = DosPrintQAdd(pszServer,            // Servername
                          3,                    // Level
                          (char far *)&prq3,    // New printer structure
                          sizeof(PRQINFO3));    // Size of buffer
      printf("DosPrintQAdd returned %u\n", uRet);
      if (uRet == NERR_Success)
      {
         printf("%Fs added to ", prq3.pszName);
         if ((pszServer == NULL) || (*pszServer == '\0'))
            printf("the local computer\n");
         else
            printf("%s\n", pszServer);
         printf("Priority set to %hu\n", prq3.uPriority);
      }

   //========================================================================
   //  DosPrintQPause
   //
   //  This API pauses the specified printer queue.
   //========================================================================

      uRet = DosPrintQPause(pszServer,          // Servername
                            pszQueueName);      // Queuename
      printf("DosPrintQPause returned %u\n", uRet);

   //========================================================================
   //  DosPrintQGetInfo
   //
   //  This API returns information about a specific printer queue.
   //========================================================================

      // Call with zero-length buffer, expect NERR_BufTooSmall
      uRet = DosPrintQGetInfo(pszServer,         // Servername
                                pszQueueName,    // Queuename
                                sLevel,          // Call level
                                NULL,            // Buffer for info
                                0,               // Size of buffer
                                &cbBufferNeeded);// Required size
      if (uRet == NERR_BufTooSmall)
      {
         cbBuffer = cbBufferNeeded;
         pbBuffer = SafeMalloc(cbBuffer);  // SafeMalloc() in samples.c
         uRet = DosPrintQGetInfo(pszServer,      // Servername
                              pszQueueName,      // Queuename
                              sLevel,            // Call level
                              pbBuffer,          // Buffer for info
                              cbBuffer,          // Size of buffer
                              &cbBufferNeeded);  // Required size
         printf("DosPrintQGetInfo returned %u\n", uRet);
         if (uRet == NERR_Success)
            DisplayInfo(sLevel, pbBuffer, 1);    // Show return data
         free(pbBuffer);
      }
      else
         printf("DosPrintQGetInfo returned %u\n", uRet);

   //========================================================================
   //  DosPrintQSetInfo
   //
   //  This API controls print destination settings. DosPrintQSetInfo
   must
   //  be called using level 1 or level 3. In this example, a single

   //  element is set to the desired value. A program can also set all

   //  elements by setting the parameter number code to PARMNUM_ALL.
   //========================================================================

      prq3.uPriority = uPriority;               // Disconnect using SetInfo
      uRet = DosPrintQSetInfo(pszServer,        // Servername
                  pszQueueName,                 // Queuename
                  3,                            // Call level
                  (char far *)&(prq3.uPriority),// Data to set
                  sizeof(USHORT),               // Size of buffer
                  PRQ_PRIORITY_PARMNUM);        // Parameter number code
      printf("DosPrintQSetInfo returned %u\n", uRet);

   //========================================================================
   //  DosPrintQEnum
   //
   //  This API lists all printers connected to the specified server.
   //========================================================================

      cbBuffer = DEFAULT_BUFFER_SIZE;
      pbBuffer = SafeMalloc(cbBuffer); // SafeMalloc() is in samples.c
      do  // Until buffer is big enough to succeed
      {
         uRet = DosPrintQEnum (pszServer,      // Servername
                               sLevel,         // Call level
                               pbBuffer,       // Buffer for info
                               cbBuffer,       // Size of buffer
                               &cEntriesRead,  // Count of entries read
                               &cEntriesTotal);// Count of entries available
         if (uRet == ERROR_MORE_DATA)
         {
            free(pbBuffer);   // Buffer too small to hold data
            if (cbBuffer >= MAX_BUFFER_SIZE)
               exit(1);
            else if (cbBuffer > (MAX_BUFFER_SIZE/2))
               cbBuffer = MAX_BUFFER_SIZE;
            else
               cbBuffer += cbBuffer; // Allocate a larger one and try
   again
            pbBuffer = SafeMalloc(cbBuffer);  // SafeMalloc() in samples.c
               fDone = FALSE;
         }

   else
            fDone = TRUE;
      } while (fDone == FALSE); // Loop until buf big enough or call
   fails
      printf("DosPrintQEnum returned %u\n", uRet);
      if (uRet == NERR_Success)
      {
         printf("DosPrintQEnum read %hu ", cEntriesRead);
         printf(" out of %hu entries\n", cEntriesTotal);
         DisplayInfo(sLevel, pbBuffer, cEntriesRead);
      }
      free(pbBuffer);

   //=====================================================================
   //  DosPrintQPurge
   //
   //  This API deletes all jobs from the printer queue.
   //=====================================================================

      uRet = DosPrintQPurge(pszServer,          // Servername
                             pszQueueName);     // Queuename
      printf("DosPrintQPurge returned %u\n", uRet);

   //=====================================================================
   //  DosPrintQContinue
   //
   //  This API allows a paused printer queue to continue.
   //=====================================================================

      uRet = DosPrintQContinue(pszServer,      // Servername
                               pszQueueName);  // Queuename
      printf("DosPrintQContinue returned %u\n", uRet);

   //=====================================================================
   //  DosPrintQDel
   //
   //  This API deletes the printer queue. This sample program allows
   //  a command-line switch that prevents deletion of the queue.
   //=====================================================================

      if (fDelete == TRUE)
      {
         uRet = DosPrintQDel(pszServer,         // Servername
                             pszQueueName);     // Queuename
         printf("DosPrintQDel returned %u\n", uRet);
      }
      exit(0);
   }  // End of main

   //=====================================================================
   //  DisplayInfo
   //
   //  Displays printer queue information obtained by DosPrintQGetInfo
   or
   //  DosPrintQEnum.
   //
   //  Level 0:  Queuename
   //  Level 1:  PRQINFO data structure
   //  Level 2:  PRQINFO followed by PRJINFO for each job
   //  Level 3:  PRQINFO3 data structure
   //  Level 4:  PRQINFO3 followed by PRJINFO2 for each job
   //  Level 5:  Far pointer to queuename
   //=====================================================================

   void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries)
   {
      char *     pprq0;  // Level 0 data
      PPRQINFO   pprq1;  // Pointer to queue data provided at levels
   1, 2
      PPRJINFO   pprj1;  // Pointer to job data provided at level 2
      PPRJINFO2  pprj2;  // Pointer to job data provided at level 3
      PPRQINFO3  pprq3;  // Pointer to queue data provided at levels
   3, 4
      char far * far * pprq5;  // Pointer to level 5 data
      unsigned short iCount, iJobs, cJobs;  // Loop counters

      pprq0 = (char *) pbBuffer;            // Initialize pointers
      pprq1 = (PPRQINFO) pbBuffer;
      pprq3 = (PPRQINFO3) pbBuffer;
      pprq5 = (char far * far *) pbBuffer;

      for (iCount = 1; iCount <= cEntries; iCount++)
      {
         printf("\n");
         switch (sLevel)
         {
            case 0:                         // Level 0 data
               printf("Queue Name  :  %s\n", pprq0);
               pprq0 += (QNLEN + 1);
               break;

            case 1:                         // Level 1 data
               printf("Queue Name  :  %s\n", pprq1->szName);
               printf("Priority    :  %hu\n", pprq1->uPriority);
               printf("Comment     :  %Fs\n", pprq1->pszComment);
               printf("Jobs        :  %hu\n", pprq1->cJobs);
               printf("Queue Status:  0x%hx\n", pprq1->fsStatus);
               pprq1++;
               break;

            case 2:                         // Level 2 data
               printf("Queue Name  :  %s\n", pprq1->szName);
               printf("Priority    :  %hu\n", pprq1->uPriority);
               printf("Comment     :  %Fs\n", pprq1->pszComment);
               cJobs = pprq1->cJobs;
               printf("Jobs        :  %hu\n", cJobs);
               printf("Queue Status:  0x%hx\n", pprq1->fsStatus);
               pprq1++;
               pprj1 = (PPRJINFO) pprq1;
               for (iJobs = 0; iJobs < cJobs; iJobs++)
               {
                  printf("\n");
                  printf("  Job Id      :  %hu\n", pprj1->uJobId);
                  printf("  User Name   :  %s\n", pprj1->szUserName);
                  printf("  Position    :  %hu\n", pprj1->uPosition);
                  pprj1++;
               }
               pprq1 = (PPRQINFO) pprj1;
               break;

            case 3:                       // Level 3 data
               printf("Queue Name  :  %Fs\n", pprq3->pszName);
               printf("Priority    :  %hu\n", pprq3->uPriority);
               printf("Comment     :  %Fs\n", pprq3->pszComment);
               printf("Jobs        :  %hu\n", pprq3->cJobs);
               printf("Queue Status:  0x%hx\n", pprq3->fsStatus);
               pprq3++;
               break;

            case 4:                       // Level 4 data
               printf("Printer Name:  %s\n", pprq3->pszName);
               printf("Priority    :  %hu\n", pprq3->uPriority);
               printf("Comment     :  %Fs\n", pprq3->pszComment);
               cJobs = pprq3->cJobs;
               printf("Jobs        :  %hu\n", cJobs);
               printf("Queue Status:  0x%hx\n", pprq3->fsStatus);
               pprq3++;                   // Skip queue data
               pprj2 = (PPRJINFO2)pprq3;  // Examine job data
               for (iJobs = 0; iJobs < cJobs; iJobs++)

   {
                  printf("\n");
                  printf("  Job Id      :  %hu\n", pprj2->uJobId);
                  printf("  User Name   :  %Fs\n", pprj2->pszUserName);
                  printf("  Priority    :  %hu\n", pprj2->uPriority);
                  printf("  Document    :  %Fs\n", pprj2->pszDocument);
                  pprj2++;   // Bump to look at next print job structure
               }

   pprq3 = (PPRQINFO3) pprj2; // If next element, it
   is queue
               break;

            case 5:                       // Level 5 data
               printf("Queue Name  :  %Fs\n", *pprq5);
               pprq5++;
               break;
            default:                      // Undefined level
               break;
         } // End switch sLevel
      } // End for loop
   }  // End function

   //=====================================================================
   //  Usage
   //
   //  Display possible command-line switches for this sample program.
   //=====================================================================

   void Usage(char *pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-l level]", pszString);
      fprintf(stderr, " [-p priority]\n\t[-q queuename] [-f flag delete]");
      fprintf(stderr, " [-c comment for queue]\n");
      exit(1);
   }









 Remote Utility Category

 Remote Utility API functions enable applications to copy and move remote
 files, execute a program remotely, and access the time-of-day information on
 a remote server. They require that the Workstation service be running on the
 local computer.

 The Remote Utility category functions, datatypes, structures, and constants
 are defined in the NETCONS.H, NETERR.H, and REMUTIL.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETREMUTIL, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Remote Utility API functions:


   þ   NetRemoteCopy

   þ   NetRemoteExec

   þ   NetRemoteMove

   þ   NetRemoteTOD



 Description

 NetRemoteCopy copies files on remote servers without copying the files
 physically to and from the local workstation.

 NetRemoteMove moves files or directories from one location to another on a
 remote server, without physically moving the data if the source and
 destination are on the same drive. If the source and destination are on
 different drives, the move takes place directly from source to destination,
 without moving the data to and from the local workstation.

 For both NetRemoteCopy and NetRemoteMove, the source and destination must be
 on the same server.

 NetRemoteExec executes a program on a remote server. It is similar to the
 DosExecPgm function, but NetRemoteExec is executed on a remote network
 server. For information about DosExecPgm, see your MS OS/2 programming
 manual(s).

 NetRemoteTOD returns time-of-day information from a remote server.


 Data Structures

 NetRemoteCopy returns a copy_info data structure. NetRemoteMove returns a
 move_info data structure. NetRemoteTOD returns a time_of_day_info data
 structure. NetRemoteExec does not use a data structure.


 File Copy Information

 The copy_info data structure has this format:

   struct copy_info {
       unsigned short  ci_num_copied;
       char            ci_err_buf[1];
   };

 where

 ci_num_copied
   Specifies the number of files copied.

 ci_err_buf
   Contains a variable-length ASCIIZ string that specifies error information
   about the file copy operation.


 File Move Information

 The move_info data structure has this format:

   struct move_info {
       unsigned short  mi_num_moved;
       char            mi_err_buf[1];
   };

 where

 mi_num_moved
   Specifies the number of files moved.

 mi_err_buf
   Contains a variable-length ASCIIZ string that specifies error information
   about the move operation.


 Time-of-Day Information

 The time_of_day_info data structure has this format:

   struct time_of_day_info {
       unsigned long   tod_elapsedt;
       unsigned long   tod_msecs;
       unsigned char   tod_hours;
       unsigned char   tod_mins;
       unsigned char   tod_secs;
       unsigned char   tod_hunds;
       unsigned short  tod_timezone;
       unsigned short  tod_tinterval;
       unsigned char   tod_day;
       unsigned char   tod_month;
       unsigned short  tod_year;
       unsigned char   tod_weekday;
   };

 where

 tod_elapsedt
   Specifies the number of seconds elapsed since 00:00:00, January 1, 1970.

 tod_msecs
   Specifies the number of milliseconds from an arbitrary starting point
   (system reset). Typically, tod_msecs is read twice, once at the start of a
   process and again at the end, then subtracting one value from the other to
   determine how long that process took.

 tod_hours
   Specifies the current hour (0-23).

 tod_mins
   Specifies the current minute (0-59).

 tod_secs
   Specifies the current second (0-59).

 tod_hunds
   Specifies the current hundredth second (0.01 second) (0-99).

 tod_timezone
   Specifies the time zone of the server. This value is calculated (in
   minutes) from Greenwich Mean Time (GMT). For time zones west of Greenwich,
   the value is positive; for time zones east of Greenwich, the value is
   negative. A value of -1 indicates that the time zone is undefined.

 tod_tinterval
   Specifies the time interval for each tick of the clock. Each integral
   integer represents one ten-thousandth second (0.0001 second).

 tod_day
   Specifies the day of the month (1-31).

 tod_month
   Specifies the month of the year (1-12).

 tod_year
   Specifies the year.

 tod_weekday
   Specifies the day of the week (0-6, where 0 is Sunday, 1 is Monday, and so
   on).


 NetRemoteCopy
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetRemoteCopy copies one or more files from one location to another on a
 remote server. The source and destination for the file copy operation must
 be on the same server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only. The function can operate on remote
       files by using universal naming convention (UNC) paths or redirected
       drives.

   þ   MS OS/2 version 1.1, local only. The function can operate on remote
       files by using UNC paths or redirected drives.

   þ   MS-DOS, local only. The function can operate on remote files by using
       UNC paths or redirected drives.



 Privilege Level

 The execution privilege level for NetRemoteCopy depends on the access
 restrictions of the file(s) being accessed.


 Syntax

   #define INCL_NETREMUTIL
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetRemoteCopy (const char far *  pszSourcePath,
                  const char far *  pszDestPath,
                  const char far *  pszSourcePasswd,
                  const char far *  pszDestPasswd,
                  unsigned short    fsOpen,
                  unsigned short    fsCopy,
                  char far *        pbBuffer,
                  unsigned short    cbBuffer
                 );

 where

 pszSourcePath
   Points to an ASCIIZ string that contains the pathname of the file(s) to be
   copied. This value can be expressed in UNC format or with a redirected
   drive letter.

 pszDestPath
   Points to an ASCIIZ string that contains the name of the path where the
   file specified by pszSourcePath is to be copied. When a wildcard is used
   for pszSourcePath, pszDestPath must be a directory. This value can be
   expressed in UNC format or with a redirected drive letter.

 pszSourcePasswd
   Points to an ASCIIZ string that contains the password needed to access the
   path specified by pszSourcePath. A null pointer indicates a password is
   not required.

 pszDestPasswd
   Points to an ASCIIZ string that contains the password needed to access the
   path specified by pszDestPath. A null pointer indicates a password is not
   required.

 fsOpen
   Specifies how to open pszDestPath. The REMUTIL.H header file defines these
   possible values:

 Bit(s)                            Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0-1                               Used if pszDestPath exists. If 0, the
                                   open operation fails. If 1, the file is
                                   appended. If 2, the file is overwritten.

 2-3                               Reserved; must be 0.

 4                                 Used if pszDestPath does not exist. If 0,
                                   the open operation fails. If 1, the file
                                   is created.

 5-15                              Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 fsCopy
   Specifies how the file copy operation is done. The REMUTIL.H header file
   defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code          Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 MUST_BE_FILE  0x1       If 1, pszDestPath must be a file.

 MUST_BE_DIR   0x2       If 1, pszDestPath must be a directory.

 ASCII_DEST    0x4       If 0, pszDestPath is opened in binary mode. If 1,
                         pszDestPath is opened in text mode.
 Code          Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                        pszDestPath is opened in text mode.

 ASCII_SOURCE  0x8       If 0, pszSourcePath is opened in binary mode. If 1,
                         pszSourcePath is opened in text mode.

 VERIFY        0x10      If 1, all write operations are verified.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   Note that the fsCopy parameter must not be set to both MUST_BE_FILE and
   MUST_BE_DIR at the same time.

 pbBuffer
   Points to the buffer in which to store the returned copy_info data
   structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_FILE_NOT_FOUND              2       The file was not found.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NO_MORE_FILES               18      No more files are available.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_FILE_EXISTS                 80      The file already exists.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_NO_PROC_SLOTS               89      No process slots are available.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          started.

 NERR_BadSource                    2381    The source path is invalid.

 NERR_BadDest                      2382    The destination pathname does
                                           not exist.

 NERR_DifferentServers             2383    The source and destination paths
                                           are on different servers.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 With NetRemoteCopy, both of the following cases are valid:


   þ   The source and destination are both files. The source file is copied
       to the destination file, subject to fsOpen and fsCopy limitations.

   þ   The source is a file or wildcard and the destination is a directory.
       The source file(s) is copied to the destination directory, subject to
       fsOpen and fsCopy limitations.


 If the remote server runs out of resources while processing the request,
 NetRemoteCopy returns ERROR_NO_PROC_SLOTS. Any files already transferred are
 not removed from the specified destination.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Moving remote files between       NetRemoteMove
 servers

 Passwords for shared resources    Share Category

 User passwords                    User Category


 NetRemoteExec
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetRemoteExec enables a remote server to execute a program located on that
 remote server. It is a network extension of the DosExecPgm function. The
 executed program runs on the computer connected to the caller's current
 drive. If the caller's current drive is on a remote server, the child
 process executes on that server. If the caller's current drive is a local
 drive, the child process executes locally.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only. The function can operate on remote
       files by using redirected drives.

   þ   MS OS/2 version 1.1, local only. The function can operate on remote
       files by using redirected drives.

   þ   MS-DOS not supported.



 Privilege Level

 The execution privilege level for NetRemoteExec depends on the access
 restrictions of the file(s) being accessed.


 Syntax

   #define INCL_NETREMUTIL
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetRemoteExec (char far *        pszReserved1,
                  char far *        pszFailName,
                  unsigned          cbFailName,
                  unsigned          fAsync,
                  const char far *  pszArgs,
                  const char far *  pszEnvs,
                  char far *        pReturnCodes,
                  const char far *  pszPgmName,
                  char far *        pszReserved2,
                  unsigned short    fsRemoteExec
                 );

 where

 pszReserved1
   Reserved pointer; must be -1.

 pszFailName
   Points to a buffer into which a name is copied if NetRemoteExec cannot
   successfully load and start the specified program. The name is that of the
   object that failed, such as a dynamic-link library.

 cbFailName
   Specifies the size (in bytes) of the buffer pointed to by pszFailName.

 fAsync
   Specifies the asynchronous and trace flags. The MS OS/2 BSEDOS.H header
   file defines these possible values:

 Code              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 EXEC_SYNC         0      Synchronous process.
 EXEC_ASYNC        1      Asynchronous process without result code.
 EXEC_ASYNCRESULT  2      Asynchronous process with result code.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 pszArgs
   Points to a set of ASCIIZ strings that contain the arguments of the
   program to be executed. For programs to run with MS-DOS or MS OS/2,
   pszArgs should point to a string containing the program name, a NUL
   character, the program parameters (separated by spaces), and terminated by
   two NUL characters.

 pszEnvs
   Points to a set of ASCIIZ strings that specify environment variables and
   their current values. The set must be terminated by two NUL characters.
   The environment variable strings have this form:

   variable=value

 pReturnCodes
   Points to an MS OS/2 data structure (RESULTCODES) that contains the return
   codes that result from the file execution. This is the same data structure
   used with the DosExecPgm function.

 pszPgmName
   Points to an ASCIIZ string that contains the name and optional extension
   of the file to  be executed. This name must not contain any path
   separators or a drive letter. The location of the program is determined by
   the runpath parameter set in the [netrun] section of the LANMAN.INI file
   on the remote server.

 pszReserved2
   Reserved pointer; must be 0.

 fsRemoteExec
   Specifies the remote executable flags that control program execution. The
   REMUTIL.H header file defines the possible values, as follows.

   The REM_PIPE_MODE code has the value 1. This bit mask isolates the mode
   for standard input, as follows:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 REM_PIPE_MODE_MSG                 0           Message mode pipe for
                                               standard input.

 REM_PIPE_MODE_CHAR                1           Character mode pipe for
                                               standard input.

   The REM_WAIT_MODE code has the value 2. This bit mask
 isolates the wait mode for the process, as follows:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 REM_WAIT_MODE_PROCESS             0           The DosCwait function waits
                                               for the child process to
                                               finish before returning.

 REM_WAIT_MODE_TREE                2           The DosCwait function waits
                                               for all spawned processes to
                                               finish before returning.

   The REM_SIGL_MODE code has the value 4. This bit mask
 isolates the mode for remote signals, as follows:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 REM_SIGL_MODE_MAP                 0           Map SIGINTR and SIGBREAK to
                                               SIGKILL when sending remote
                                               standard signals.

 REM_SIGL_MODE_RAW                 4           Send signals as received.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_FILE_NOT_FOUND              2       The file was not found.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_RunSrvPaused                 2385    The server is paused and cannot
                                           run a program or command.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          run a program or command.

 NERR_ErrCommRunSrv                2389    An error occurred when
                                           communicating with a run server.

 NERR_ErrorExecingGhost            2391    An error occurred when starting
                                           a background process.

 NERR_ShareNotFound                2392    The shared resource was not
                                           found.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetRemoteExec requires that the LAN Manager Netrun service be running on the
 remote server. If this service is not running, NetRemoteExec returns
 ERROR_PATH_NOT_FOUND. If the Netrun service is running but the specified
 executable cannot be found on the run path, NetRemoteExec returns
 ERROR_FILE_NOT_FOUND.

 A process executed remotely inherits the following handles from the calling
 process:

 Handle               Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                    Standard input (stdin).
 1                    Standard output (stdout).
 2                    Standard error (stderr).
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 When NetRemoteExec initiates an asynchronous process, the process
 identification (PID) returned to the first word of pReturnCodes is a valid
 local PID that represents the remote program. The PID can be used with any
 MS OS/2 function that accepts a PID as a parameter, such as DosFlagProcess
 (to send signals to the remote process), DosCWait (to wait for the remote
 process to exit), and DosKillProcess (to terminate the process).

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 DosFlagProcess, DosCWait,         MSOS/2 programming manual(s)
 DosKillProcess

 Executing a program               DosExecPgm, in MSOS/2 programming
                                   manual(s)

 Listing the resources on a        NetShareEnum
 server

 Listing the servers on the        NetServerAdminCommand
 network

 Netrun service                    LAN Manager administrator's manual(s)


 NetRemoteMove
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetRemoteMove moves one or more files from one location to another on a
 remote server. The source and destination pathnames must be on the same
 server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only. The function can operate on remote
       files by using UNC paths or redirected drives.

   þ   MS OS/2 version 1.1, local only. The function can operate on remote
       files by using UNC paths or redirected drives.

   þ   MS-DOS, local only. The function can operate on remote files by using
       UNC paths or redirected drives.



 Privilege Level

 The execution privilege level for NetRemoteMove depends on the access
 restrictions of the file being moved.


 Syntax

   #define INCL_NETREMUTIL
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetRemoteMove (const char far *  pszSourcePath,
                  const char far *  pszDestPath,
                  const char far *  pszSourcePasswd,
                  const char far *  pszDestPasswd,
                  unsigned short    fsOpen,
                  unsigned short    fsMove,
                  char far *        pbBuffer,
                  unsigned short    cbBuffer
                 );

 where

 pszSourcePath
   Points to an ASCIIZ string that contains the pathname of the file to be
   moved. Wildcards are acceptable.

 pszDestPath
   Points to an ASCIIZ string that contains the name of the path where the
   file specified by pszSourcePath is to be moved. If pszSourcePath is a
   wildcard, pszDestPath must be a directory.

 pszSourcePasswd
   Points to an ASCIIZ string that contains the password for the path
   specified by pszSourcePath. A null pointer means a password is not
   required.

 pszDestPasswd
   Points to an ASCIIZ string that contains the password for the path
   specified by pszDestPath. A null pointer means a password is not required.

 fsOpen
   Specifies how to open pszDestPath. The REMUTIL.H header file defines these
   possible values:

 Bit(s)                            Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0-1                               Use if pszDestPath exists. If 0, the
                                   open fails. If 1, the file is appended.
                                   If 2, the file is overwritten.

 2-3                               Reserved; must be 0.

 4                                 Use if pszDestPath does not exist. If 0,
                                   the open fails. If 1, the file is
                                   created.

 5-15                              Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 fsMove
   Specifies control for the file move. The REMUTIL.H header file defines
   these possible values:

 Code          Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 MUST_BE_FILE  0x1       If 1, pszDestPath must be a file.
 MUST_BE_DIR   0x2       If 1, pszDestPath must be a directory.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   Note that the fsMove parameter must not be set to both MUST_BE_FILE and
   MUST_BE_DIR at the same time.

 pbBuffer
   Points to the buffer in which to store the returned move_info data
   structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_FILE_NOT_FOUND              2       The file was not found.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NO_MORE_FILES               18      No more files are available.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_FILE_EXISTS                 80      The file already exists.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_NO_PROC_SLOTS               89      No process slots are available.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadSource                    2381    The source path is invalid.

 NERR_BadDest                      2382    The destination pathname does
                                           not exist.

 NERR_DifferentServers             2383    The source and destination paths
                                           are on different servers.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If the source and destination files are in the same directory, NetRemoteMove
 renames the source file. If they are in different directories, NetRemoteMove
 modifies the directory table accordingly. When the source and destination
 are on different drives, NetRemoteMove moves pszSourcePath to pszDestPath
 and then deletes pszSourcePath.

 With NetRemoteMove, both of the following cases are valid:


   þ   The source and destination are both files. The source file is copied
       to the destination file, subject to fsOpen and fsMove limitations.

   þ   The source is a file or wildcard and the destination is a directory.
       The source file(s) is copied to the destination directory, subject to
       fsOpen and fsMove limitations.


 If the remote server runs out of resources while processing the request,
 NetRemoteMove returns ERROR_NO_PROC_SLOTS. Any files already transferred are
 not removed from the specified destination.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Copying a file from one network   NetRemoteCopy
 location to another


 NetRemoteTOD
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetRemoteTOD returns a server's time of day.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 No special privilege level is required to successfully execute NetRemoteTOD.



 Syntax

   #define INCL_NETREMUTIL
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetRemoteTOD (const char far *  pszServer,
                 char far *        pbBuffer,
                 unsigned short    cbBuffer
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetRemoteTOD. A null pointer or null string specifies the local
   computer.

 pbBuffer
   Points to the buffer in which to store the returned time_of_day_info data
   structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.
 ERROR_BAD_NETPATH     53      The network path was not found.
 NERR_BufTooSmall      2123    The supplied buffer is too small.
 NERR_WkstaNotStarted  2138    The Workstation service is not started.
 NERR_InvalidComputer  2351    The specified computername is invalid.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ






 Remote Utility Category Example

   /*
      NETREM.C -- sample program demonstrating NetRemote API functions.

      This program executes the NetRemote APIs with the supplied parameters.
      To execute NetRemoteCopy: supply the parameters starting with -c.
      To execute NetRemoteMove: supply the parameters starting with -m.
      To execute NetRemoteExec: supply the parameters starting with -e.
      To execute NetRemoteTOD:  supply a servername with a -ts switch.
      The source and destination for NetRemoteCopy and NetRemoteMove
      can be specified using either a UNC path or a redirected drive
      letter. NetRemoteExec is carried out on the computer connected
      to the current drive. NetRemoteTOD gets the current time from the

      specified server.

      usage:

       netrem [-cs copy source] [-cd copy dest] [-cf copy flag] [-co
   copy open]
              [-ms move source] [-md move dest] [-mf move flag] [-mo
   move open]
              [-ep executable] [-ea arguments] [-ts \\server]

       where  copy source = Complete path of the source file or directory
                            for NetRemoteCopy.
              copy dest   = Complete path of the destination file or
                            directory for NetRemoteCopy.
              copy flag   = Copy flag for NetRemoteCopy.
              copy open   = Open flag for NetRemoteCopy.
              move source = Complete path of the source file or directory
                            for NetRemoteMove.
              move dest   = Complete path of the destination file or
                            directory for NetRemoteMove.
              move flag   = Move flag for NetRemoteMove.
              move open   = Open flag for NetRemoteMove.
              executable  = Name of the program for NetRemoteExec.
              arguments   = Argument string for NetRemoteExec.
              \\server    = Name of the server for NetRemoteTOD.
                            A servername must be preceded by two
                            backslashes (\\).

   API               Used to...
      =============     =====================================================
      NetRemoteCopy     Copy a file or directory on a remote server to
                        another file or directory on a remote server
      NetRemoteMove     Move a file or directory on a remote server to
   a
                        new file or directory on a remote server
      NetRemoteExec     Execute a program
      NetRemoteTOD      Obtain time of day from a remote server

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETERRORS
   #define     INCL_NETREMUTIL
   #include    <lan.h>          // LAN Manager header files

   #include    <stdio.h>        // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   // Define mnemonic bit masks for the functions to execute.
   #define DO_NONE              0
   #define DO_COPY              0x01
   #define DO_MOVE              0x02
   #define DO_EXEC              0x04
   #define DO_TOD               0x08

   // Define mnemonic bit masks for copy and move flag words.
   #define REM_OPEN_APPEND      0x01     // If dest exists, append
   #define REM_OPEN_OVERWRITE   0x02     // If dest exists, overwrite
   #define REM_OPEN_CREATE      0x10     // If dest does not exist, create

   #define REM_ASYNCRESULT      0x02     // Equivalent of EXEC_ASYNCRESULT
   #define ARG_LEN              128
   #define OBJ_LEN              64

   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      char   fToDo = DO_NONE;              // NetRemote API to perform
      char   achReturnCodes[OBJ_LEN];      // NetRemoteExec MS OS/2 ret
   codes
      char   achObjectName[OBJ_LEN];       // NetRemoteExec object name
      char   achArgs[ARG_LEN];             // NetRemoteExec argument
   string
      char   achEnvs[ARG_LEN];             // NetRemoteExec environment
   string
      char * pszCopySrc = NULL;            // Can be file or directory
      char * pszCopyDest = NULL;           // Can be file or directory
      char * pszMoveSrc = NULL;            // Can be file or directory
      char * pszMoveDest = NULL;           // Can be file or directory
      char * pszPgmName = NULL;            // Program to be executed
      char * pszArgs;                      // Arguments for program
      char * pszServer = NULL;             // Time servername
      unsigned short fsCopy = 0;           // Copy flag
      unsigned short fsMove = 0;           // Move flag
      unsigned short fsCopyOpen = REM_OPEN_OVERWRITE | REM_OPEN_CREATE;
      unsigned short fsMoveOpen = REM_OPEN_OVERWRITE | REM_OPEN_CREATE;
      int            iCount;               // Index counter
      struct copy_info CopyBuf;            // Return data from NetRemoteCopy
      struct move_info MoveBuf;            // Return data from NetRemoteMove
      struct time_of_day_info TimeBuf;     // Time-of-day struct in REMUTIL.H
      API_RET_TYPE uRet;                   // Return code from API calls

      for (iCount = 1; iCount < argc; iCount++) // Get command-line switches
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 'c':                        // -c copy
                  fToDo |= DO_COPY;
                  switch (tolower(*(argv[iCount]+2)))
                  {
                     case 's':                  // -cs copy source
                        pszCopySrc = argv[++iCount];
                        break;
                     case 'd':                  // -cd copy destination
                        pszCopyDest = argv[++iCount];
                        break;
                     case 'f':                  // -cf copy flag
                        fsCopy = atoi(argv[++iCount]);
                        break;
                     case 'o':                  // -co copy open flag
                        fsCopyOpen = atoi(argv[++iCount]);
                        break;
                     default:
                        Usage(argv[0]);         // Display usage and
   exit
                  }
                  break;
               case 'm':                        // -m move
                  fToDo |= DO_MOVE;
                  switch (tolower(*(argv[iCount]+2)))

   {
                     case 's':                  // -ms move source
                        pszMoveSrc = argv[++iCount];
                        break;
                     case 'd':                  // -md move destination
                        pszMoveDest = argv[++iCount];
                        break;
                     case 'f':                  // -mf move flag
                        fsMove = atoi(argv[++iCount]);
                        break;
                     case 'o':                  // -mo move open flag
                        fsMoveOpen = atoi(argv[++iCount]);
                        break;
                     default:
                        Usage(argv[0]);         // Display usage and
   exit
                  }
                  break;
               case 'e':                        // -e exec
                  fToDo |= DO_EXEC;
                  switch (tolower(*(argv[iCount]+2)))
                  {
                     case 'p':                  // -ep exec executable
   program
                        pszPgmName = argv[++iCount];
                        achArgs[0] = '\0'; // Set double NUL terminator
                        achArgs[1] = '\0';
                        achEnvs[0] = '\0'; // Set double NUL terminator
                        achEnvs[1] = '\0';
                        break;
                     case 'a':                  // -ea exec argument
   string
                        pszArgs = achArgs;
                        strcpy(pszArgs, pszPgmName);      // Program
   name
                        pszArgs += strlen(pszArgs) + 1;   // NUL terminator
                        strcpy(pszArgs, argv[++iCount]);  // Argument
   string
                        pszArgs += strlen(pszArgs) + 1;   // NUL terminator
                        *pszArgs = '\0';                  // Extra NUL
                        break;
                     default:
                        Usage(argv[0]);         // Display usage and
   exit
                  }
                  break;
               case 't':                        // -t time of day
                  fToDo |= DO_TOD;
                  if (tolower(*(argv[iCount]+2)) == 's')
                     pszServer = argv[++iCount];// -ts servername
                  else
                     Usage(argv[0]);            // Display usage and
   exit
                  break;

   case 'h':
               default:
                  Usage(argv[0]);               // Display usage and
   exit
            }
         }
         else
            Usage(argv[0]);                     // Display usage and
   exit
      }

      if (fToDo == DO_NONE)
      {
         printf("No operation specified.\n");
         Usage(argv[0]);                        // Display usage and
   exit
      }

   //========================================================================
   //  NetRemoteCopy
   //
   //  This API copies a file or directory on the specified server.
   //  The source is copied to the destination according to the flags.

   //  Information about the operation is returned in the CopyBuf structure.
   //========================================================================

      if (fToDo & DO_COPY)
      {
         uRet = NetRemoteCopy(pszCopySrc,   // Source path
                  pszCopyDest,              // Destination path
                  NULL,                     // No password for source
   path
                  NULL,                     // No password for dest path
                  fsCopyOpen,               // Open flags
                  fsCopy,                   // Copy flags
                  (char far *)&CopyBuf,     // Return data
                  sizeof(struct copy_info));// Return data size, in bytes

         printf("NetRemoteCopy returned %u\n", uRet);
         if (uRet == NERR_Success)
         {
             printf("   Copied %s to %s\n",pszCopySrc, pszCopyDest);
             printf("   Files copied = %hu\n", CopyBuf.ci_num_copied);
         }
      }

   //========================================================================
   //  NetRemoteMove
   //
   //  This API moves a file on the remote server. The source file is
   renamed
   //  to the name specified by the destination file. After the operation,
   //  only one file exists, and its name is the destination filename.
   //========================================================================

      if (fToDo & DO_MOVE)
      {
         uRet = NetRemoteMove(pszMoveSrc,    // Source path
                  pszMoveDest,               // Destination path
                  NULL,                      // No password for source
   path
                  NULL,                      // No password for dest
   path
                  fsMoveOpen,                // Open flags
                  fsMove,                    // Move flags
                  (char far *) &MoveBuf,     // Return data
                  sizeof(struct move_info)); // Return data size, in
   bytes

         printf("NetRemoteMove returned %u\n",uRet);
         if (uRet == NERR_Success)
         {
             printf("   Moved %s to %s\n", pszMoveSrc, pszMoveDest);
             printf("   Number of files moved = %hu\n",MoveBuf.mi_num_moved);
         }
      }

   //========================================================================
   //  NetRemoteExec
   //
   //  This API executes the specified file on the computer connected

   //  to the current drive. If the current drive is connected to a
   //  remote server, the file is executed on that server. If the current

   //  drive is local, the file is executed locally. When NETREM.EXE
   reads
   //  the arguments for the NetRemoteExec call, it adds the name of
   the
   //  program to be executed to the front of that program's argument
   string.
   //========================================================================

      if (fToDo & DO_EXEC)
      {
         uRet = NetRemoteExec((char far *)-1L, // Reserved; must be -1
                  achObjectName,               // Contains data if error
                  OBJ_LEN,                     // Length of error data
   buffer
                  REM_ASYNCRESULT,             // Asynchronous with result
   code
                  achArgs,                     // Argument strings
                  achEnvs,                     // Environment strings
                  achReturnCodes,              // DosExecPgm return codes
                  pszPgmName,                  // Program to execute
                  NULL,                        // Reserved; must be NULL
                  0);                          // Remote exec flags

         if (uRet == NERR_Success)
             printf("\nNetRemoteExec executed %s\n", pszPgmName);
         else
         {
             printf("\nNetRemoteExec returned error %u\n", uRet);
             if (achObjectName[0] != '\0')
                printf("   Error buffer = %s\n", achObjectName);
         }
      }

   //=======================================================================
   //  NetRemoteTOD
   //
   //  This API obtains the time of day from the specified server.
   //  The time-of-day structure is defined in the REMUTIL.H header file.
   //=======================================================================

      if (fToDo & DO_TOD)
      {
         uRet = NetRemoteTOD(pszServer,            // Servername
                 (char far *) &TimeBuf,            // Data returned here
                 sizeof(struct time_of_day_info)); // Size of buffer

         printf("NetRemoteTOD returned %u\n", uRet);
         if (uRet == NERR_Success)                 // Call completed
   OK
         {
             printf("   Time ");
             if ((pszServer != NULL) && (*pszServer != '\0'))
                printf("on server %s = ",pszServer);
             printf("%02u:%02u:%02u ", TimeBuf.tod_hours,
                                       TimeBuf.tod_mins,
                                       TimeBuf.tod_secs);
             printf("%02u/%02u/%u \n", TimeBuf.tod_month,
                                       TimeBuf.tod_day,
                                       TimeBuf.tod_year);
         }
      }
      exit(0);
   }

   void Usage(char * pszString)
   {
      printf("Usage: %s [-cs copy source] [-cd copy dest] [-cf copy flag]"
             " [-co copy open]\n\t   [-ms move source] [-md move dest]"
             " [-mf move flag] [-mo move open]\n\t   [-ep executable]"
             " [-ea arguments]\n\t   [-ts \\\\server for TOD]\n",
             pszString);
      exit(1);
   }





 Server Category

 Server API functions perform administrative tasks on a local or remote
 server. They require that the Workstation service be started.
 NetServerAdminCommand, NetServerGetInfo, and NetServerSetInfo also require
 that the Server service be started on the specified server.

 The Server category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and SERVER.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETSERVER, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Server API functions:


   þ   NetServerAdminCommand

   þ   NetServerDiskEnum

   þ   NetServerEnum2

   þ   NetServerGetInfo

   þ   NetServerSetInfo



 Description

 Any user or application with admin privilege on a local or remote server can
 perform administrative tasks on that server to control its operation, user
 access, and resource sharing. You can examine and modify low-level
 parameters that affect a server's operation by calling NetServerGetInfo and
 NetServerSetInfo. The parameters, elements of the server_info_X data
 structures (where X is 0, 1, 2, or 3, depending on the level of detail
 requested), take their default values from the [server] section of the
 LANMAN.INI file.

 Another way to change a server's operation is by using the LAN Manager net
 command. An application can call the NetServerAdminCommand function to
 execute a LAN Manager net command on a server. For a list of net commands
 (such as net use, net share, and net access), see your LAN Manager
 administrator's manual(s).

 NetServerEnum2 lists all visible servers of specific types in the specified
 domains. Visible servers are those servers that have not set the svX_hidden
 element of the server_info_X data structure, where X is 2 or 3.

 NetServerDiskEnum lists the local drives on the specified server.

 With MS-DOS, most Server category API functions can be executed only on a
 remote server. NetServerDiskEnum and NetServerEnum2 can be executed on
 either a local workstation or a remote server, but all other Server category
 API functions executed on a local workstation return the NERR_RemoteOnly
 error code.


 Data Structures

 NetServerGetInfo uses the server_info_X data structure, where X is 0, 1, 2,
 or 3, to return server configuration information.

 NetServerSetInfo allows the user to change server parameters in the
 server_info_X data structure, where X is 1, 2, or 3.

 NetServerEnum2 lists server information using the server_info_X data
 structure, where X is 0 or 1.

 NetServerDiskEnum returns a list of all disk drives on a server. The data is
 returned in the form of consecutive ASCIIZ strings. Each disk drive name
 string is terminated by a NUL character. The next disk drive name string
 starts in the byte immediately following  the terminating NUL. Level 0 must
 be specified.


 Server Information (level 0)

 The server_info_0 data structure has this format:

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

 where

 sv0_name
   Specifies an ASCIIZ string that contains the name of a server. The
   constant CNLEN is defined in the NETCONS.H header file.


 Server Information (level 1)

 The server_info_1 data structure has this format:

   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;
   };

 where

 sv1_name
   Contains an ASCIIZ string that specifies the name of a server. The
   constant CNLEN is defined in the NETCONS.H header file.

 sv1_version_major
   The least significant nibble (rightmost nibble) specifies the major
   release version number of LAN Manager. The most significant nibble
   (leftmost nibble) specifies server type. The bits have the following
   values:

 Code                Value  Bits  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 MAJOR_VERSION_MASK  0x0F   0-3   Major version number.
 Ä                   0x10   4-7   Unlimited server.
 Ä                   0x10   4-7   Limited server.
 Ä                   0x20   4-7   Peer server.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   The mask MAJOR_VERSION_MASK, defined in the SERVER.H header file, should
   be used to ensure correct results.

 sv1_version_minor
   Specifies the minor release version number of LAN Manager.

 sv1_type
   Specifies the type of software the computer is running. The SERVER.H
   header file defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                    Bit Mask    Type of Software
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SV_TYPE_WORKSTATION     0x00000001  Workstation.
 SV_TYPE_SERVER          0x00000002  Server.
 SV_TYPE_SQLSERVER       0x00000004  SQL server.
 SV_TYPE_DOMAIN_CTRL     0x00000008  Primary domain controller.
 SV_TYPE_DOMAIN_BAKCTRL  0x00000010  Backup domain controller.
 SV_TYPE_TIME_SOURCE     0x00000020  Time server.
 SV_TYPE_AFP             0x00000040  Apple(R) File Protocol (AFP) service.
 Code                    Bit Mask    Type of Software
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
SV_TYPE_AFP             0x00000040  Apple(R) File Protocol (AFP) service.
 SV_TYPE_NOVELL          0x00000080  Novell(R) service.
 SV_TYPE_ALL             0xFFFFFFFF  All types of servers.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 sv1_comment
   Points to an ASCIIZ string that contains a comment describing the server.
   The comment can be a null string or a null pointer.


 Server Information (level 2)

 The server_info_2 data structure has this format:

   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;
   };

 where

 sv2_name through sv2_comment
   Are the same as the corresponding elements in the server_info_1 data
   structure. For a complete description, see the preceding section.

 sv2_ulist_mtime
   Specifies the time when the user list (for a server that has user-level
   security) was last modified. This value is stored as the number of seconds
   elapsed since 00:00:00, January 1, 1970.

 sv2_glist_mtime
   Specifies the time when the group list (for a server that has user-level
   security) was last modified. This value is stored as the number of seconds
   elapsed since 00:00:00, January 1, 1970.

 sv2_alist_mtime
   Specifies the time when the access control list (for a server that has
   user-level security) was last modified. This value is stored as the number
   of seconds elapsed since 00:00:00, January 1, 1970.

 sv2_users
   Specifies how many users are allowed on the server.

 sv2_disc
   Specifies the time (in minutes) when the session is automatically
   disconnected. A session is disconnected if it is idle longer than the time
   specified by sv2_disc. If sv2_disc is SV_NODISC, the autodisconnect
   feature is not enabled.

 sv2_alerts
   Points to an ASCIIZ string that contains the usernames listed in the
   server's alert table. The usernames are separated by spaces.

 sv2_security
   Specifies the security type of the server. The SERVER.H header file
   defines these possible values:

 Code              Value  Type of Security
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SV_SHARESECURITY  0      Share-level.
 SV_USERSECURITY   1      User-level.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 sv2_auditing
   Specifies whether auditing is enabled on the server. If sv_auditing is 0,
   auditing is disabled. If it is any other defined value, the server audits
   LAN Manager activities. For more information about auditing, see the
   Auditing category API functions.

 sv2_numadmin
   Specifies how many users with admin privilege can administer the server at
   the same time.

 sv2_lanmask
   Indicates the network device drivers active on this server. Each bit
   corresponds to an entry in the [networks] section of the LANMAN. INI file.
   If sv2_lanmask is 0, the network device driver is not active. If it is 1,
   the network device driver is active.

 sv2_hidden
   Specifies whether the server is visible to other computers in the same
   network domain. The SERVER.H header file defines these possible values:

 Code        Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SV_VISIBLE  0      Server is visible.
 SV_HIDDEN   1      Server is hidden (not visible).
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 sv2_announce
   Specifies the network announce rate (in seconds). This value and the value
   of sv2_anndelta determine how often the server is announced to other
   computers on the network.

 sv2_anndelta
   Specifies the delta, or change, of the announce rate (in milliseconds).
   This value specifies how much the announce rate can vary from the time
   specified in sv2_announce. The delta value allows randomly varied announce
   rates. For example, if sv2_announce has the value 10, and sv2_anndelta has
   the value 1, the announce rate can vary from 9.999 seconds to 10.001
   seconds.

 sv2_guestacct
   Specifies an ASCIIZ string that contains the name of the reserved guests
   account on a server. The constant UNLEN is defined in the NETCONS.H header
   file.

 sv2_pad1
   Aligns the next data structure element on a word boundary.

 sv2_userpath
   Points to an ASCIIZ string that contains the pathname to user directories.

 sv2_chdevs
   Specifies how many communication devices can be shared on the server at
   any one time.

 sv2_chdevq
   Specifies how many communication-device queues can be defined on the
   server at any one time.

 sv2_chdevjobs
   Specifies how many communication device jobs can be pending on a server.

 sv2_connections
   Specifies how many connections to sharenames are allowed on a server.

 sv2_shares
   Specifies how many sharenames can be defined on the server at any one
   time.

 sv2_openfiles
   Specifies how many files can be open at any one time on the server.

 sv2_sessopens
   Specifies how many files can be open per session.

 sv2_sessvcs
   Specifies how many virtual circuits are allowed for each client process.

 sv2_sessreqs
   Specifies how many simultaneous requests a client process can make.

 sv2_opensearch
   Specifies how many searches can be open at any one time.

 sv2_activelocks
   Specifies how many file locks can be active at any one time.

 sv2_numreqbuf
   Specifies how many server buffers are provided.

 sv2_sizreqbuf
   Specifies the size (in bytes) of each server buffer.

 sv2_numbigbuf
   Specifies how many 64K server buffers are provided.

 sv2_numfiletasks
   Specifies how many server processes can perform file I/O simultaneously.

 sv2_alertsched
   Specifies the alert interval (in minutes) for notifying an administrator
   of a network event.

 sv2_erroralert
   Specifies how many entries can be written to the error log during a
   sv2_alertsched interval before an administrator is notified.

 sv2_logonalert
   Specifies how many invalid logon attempts can be made before an
   administrator is notified.

 sv2_accessalert
   Specifies how many invalid file accesses can be made before an
   administrator is notified.

 sv2_diskalert
   Specifies at what point (the number of kilobytes of free disk space) an
   administrator should be notified that available space on a disk is low.

 sv2_netioalert
   Specifies the network I/O error ratio (in tenths of a percent) to allow
   before an administrator is notified.

 sv2_maxauditsz
   Specifies the maximum audit file size (in kilobytes).

 sv2_srvheuristics
   Points to an ASCIIZ string of flags used to control a server's operations
   and optimize server performance. The server heuristics are 20 digits that
   configure how a server processes network requests. Digits read from left
   (0) to right (19). For a complete description of these digits, see
   Appendix G, "Workstation and Server Heuristics."


 Server Information (level 3)

 The server_info_3 data structure has this format:

   struct server_info_3 {
       char            sv3_name[CNLEN+1];
       unsigned char   sv3_version_major;
       unsigned char   sv3_version_minor;
       unsigned long   sv3_type;
       char far *      sv3_comment;
       unsigned long   sv3_ulist_mtime;
       unsigned long   sv3_glist_mtime;
       unsigned long   sv3_alist_mtime;
       unsigned short  sv3_users;
       unsigned short  sv3_disc;
       char far *      sv3_alerts;
       unsigned short  sv3_security;
       unsigned short  sv3_auditing;
       unsigned short  sv3_numadmin;
       unsigned short  sv3_lanmask;
       unsigned short  sv3_hidden;
       unsigned short  sv3_announce;
       unsigned short  sv3_anndelta;
       char            sv3_guestacct[UNLEN + 1];
       unsigned char   sv3_pad1;
       char far *      sv3_userpath;
       unsigned short  sv3_chdevs;
       unsigned short  sv3_chdevq;
       unsigned short  sv3_chdevjobs;
       unsigned short  sv3_connections;
       unsigned short  sv3_shares;
       unsigned short  sv3_openfiles;
       unsigned short  sv3_sessopens;
       unsigned short  sv3_sessvcs;
       unsigned short  sv3_sessreqs;
       unsigned short  sv3_opensearch;
       unsigned short  sv3_activelocks;
       unsigned short  sv3_numreqbuf;
       unsigned short  sv3_sizreqbuf;
       unsigned short  sv3_numbigbuf;
       unsigned short  sv3_numfiletasks;
       unsigned short  sv3_alertsched;
       unsigned short  sv3_erroralert;
       unsigned short  sv3_logonalert;
       unsigned short  sv3_accessalert;
       unsigned short  sv3_diskalert;
       unsigned short  sv3_netioalert;
       unsigned short  sv3_maxauditsz;
       char far *      sv3_srvheuristics;
       unsigned long   sv3_auditedevents;
       unsigned short  sv3_autoprofile;
       char far *      sv3_autopath;
   };

 where

 sv3_name through sv3_srvheuristics
   Are the same as the corresponding elements of the server_info_2 data
   structure. For a complete description, see the preceding section.

 sv3_auditedevents
   Specifies the audit event control mask. Bits 18 through 31 are reserved.
   Bits 0 through 16 have the following meaning:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Event Name     Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 service        0x0001    Disable auditing of service state changes.

 goodsesslogon  0x0006    Disable auditing of successful session logon
                          requests.

 badsesslogon   0x0018    Disable auditing of failed session logon requests.
 Event Name     Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
badsesslogon   0x0018    Disable auditing of failed session logon requests.

 sesslogon      0x001E    Disable auditing of all session logon/logoff
                          attempts.

 goodnetlogon   0x0060    Disable auditing of successful network logon
                          requests.

 badnetlogon    0x0180    Disable auditing of failed network logon requests.

 netlogon       0x01E0    Disable auditing of all network logon/logoff
                          attempts.

 logon          0x01FE    Disable auditing of all logon/logoff attempts
                          (network and session). This mask produces the
                          same effect as goodnetlogon/badnetlogon and
                          goodsesslogon/badsesslogon masks.

 gooduse        0x0600    Disable auditing of successful requests to use a
 Event Name     Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
gooduse        0x0600    Disable auditing of successful requests to use a
                          shared resource.

 baduse         0x0800    Disable auditing of failed attempts to access a
                          shared resource.

 use            0x1E00    Disable auditing of all access requests to a
                          shared resource regardless of gooduse or baduse
                          masks. This mask produces the same effect as both
                          the gooduse/baduse masks.

 userlist       0x2000    Disable auditing of changes to the user/domain
                          account database.

 permissions    0x4000    Disable auditing of changes to the access control
                          list (ACL) database.

 resource       0x8000    Disable auditing of resource access as defined by
                          the per-resource auditing options, specified in
 Event Name     Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                         the per-resource auditing options, specified in
                          the ACL.

 logonlimit     0x10000   Disable auditing of logon limit violations.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 sv3_autoprofile
   Controls how the server acts on the profile. The SERVER.H header file
   defines these possible values:

 Code                   Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SW_AUTOPROF_LOAD_MASK  0x1    Server loads the profile.
 SW_AUTOPROF_SAVE_MASK  0x2    Server saves the profile.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   Both flags can be set simultaneously.

 sv3_autopath
   Points to the pathname for the profile.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Domains                           LAN Manager administrator's manual(s)

 Remote administration of net      LAN Manager administrator's manual(s)
 commands


 NetServerAdminCommand
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServerAdminCommand executes a command on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetServerAdminCommand on
 a remote server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETSERVER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServerAdminCommand (const char far *      pszServer,
                          const char far *      pszCommand,
                          short far *           psResult,
                          char far *            pbBuffer,
                          unsigned short        cbBuffer,
                          unsigned short far *  pcbReturned,
                          unsigned short far *  pcbTotalAvail
                         );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServerAdminCommand. A null pointer or null string specifies
   the local computer.

 pszCommand
   Points to an ASCIIZ string that contains the command string to execute on
   the specified server.

 psResult
   Points to the returned exit code of the command executed on the specified
   server.

 pbBuffer
   Points to a buffer in which a string that contains the output returned by
   the command executed on the specified server is returned.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcbReturned
   Points to an unsigned short integer that specifies the number of bytes
   returned in the buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer that specifies the number of bytes of
   return information available.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 ERROR_FILENAME_EXCED_RANGE        206     The filename specified is
                                           invalid for the file system.
                                           This code is returned when
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          This code is returned when
                                           checking a FAT disk partition
                                           only. It cannot be returned for
                                           an HPFS partition.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_NoRoom                       2119    The server could not access
                                           enough of a resource, such as
                                           memory, to complete the task.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          memory, to complete the task.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ExecFailure                  2315    A failure occurred when
                                           executing a remote
                                           administration command, probably
                                           because of a problem with the
                                           server's operating system
                                           configuration.

 NERR_TmpFile                      2316    A failure occurred when opening
                                           a remote temporary file.

 NERR_TooMuchData                  2317    The data returned from a remote
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_TooMuchData                  2317    The data returned from a remote
                                           administration command was
                                           truncated to 64K.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetServerAdminCommand is a remote form of the C-library system function.

 The command string pointed to by pszCommand can contain multiple commands
 linked by the following characters, as recognized by the operating system
 command shell:

 & && | || ;

 If multiple commands are specified, only the output of the last command is
 returned in the buffer pointed to by pbBuffer.

 If executed remotely, NetServerAdminCommand sets the server environment as
 follows:


   þ   The default drive and directory is LANMAN\NETPROG.

   þ   The PATH environment variable is set to no path.


 If executed locally, NetServerAdminCommand uses the following:


   þ   Current drive and directory of the caller.

   þ   Server's default PATH variable.


 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Executing a program on a remote   NetRemoteExec
 server

 Listing available servers         NetServerEnum2


 NetServerDiskEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServerDiskEnum retrieves a list of disk drives on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetServerDiskEnum on a remote computer. No special privilege is
 required for local calls.


 Syntax

   #define INCL_NETSERVER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServerDiskEnum (const char far *      pszServer,
                      short                 sLevel,
                      char far *            pbBuffer,
                      unsigned short        cbBuffer,
                      unsigned short far *  pcEntriesRead,
                      unsigned short far *  pcTotalAvail
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServerDiskEnum. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail requested; must be 0.

 pbBuffer
   Points to consecutive ASCIIZ strings that specify the returned list of
   disk drive names. Each disk drive name string is terminated by the
   character NUL. The next disk drive name string, if defined, starts in the
   byte immediately following the terminating NUL. The list is terminated by
   a null string.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of disk
   drive name strings enumerated in the buffer is returned. This count is
   valid only if NetServerDiskEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of disk drive names available is returned. This count is valid only if
   NetServerDiskEnum returns NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetServerDiskEnum returns a list of local drive names for the specified
 server. The drive names in the list are consecutive strings, each containing
 a drive letter, a colon (:), and the character NUL that terminates the
 ASCIIZ string. For example, NetServerDiskEnum returns the following
 consecutive strings for a server with two floppy drives (A and B), one hard
 drive (C), and one RAM drive (E):

   A:\0B:\0C:\0E:\0\0

 NetServerDiskEnum works locally even if the server has not been started.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing a server's shared         NetShareEnum
 resources

 Listing available servers         NetServerEnum2


 NetServerEnum2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServerEnum2 lists all servers of the specified type(s) that are visible
 in the specified domain(s). For example, an application can call
 NetServerEnum2 to list all domain controllers only or all SQL servers only.



 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, local and remote



 Privilege Level

 No special privilege level is required to successfully execute
 NetServerEnum2.


 Syntax

   #define INCL_NETSERVER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServerEnum2 (const char far *      pszServer,
                   short                 sLevel,
                   char far *            pbBuffer,
                   unsigned short        cbBuffer,
                   unsigned short far *  pcEntriesRead,
                   unsigned short far *  pcTotalAvail,
                   unsigned long         flServerType,
                   char far *            pszDomain
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServerEnum2. A null pointer or string specifies the local
   computer.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of server_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of
   servers enumerated in the buffer is returned. This count is valid only if
   NetServerEnum2 returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of available entries is returned. This count is valid only if
   NetServerEnum2 returns NERR_Success or ERROR_MORE_DATA.

 flServerType
   Specifies the type(s) of servers to enumerate. The flServerType parameter
   is tested against the svX_type element of each entry. Entries that match
   at least one of the specified bits are included in the entries returned in
   the buffer and in the counts returned in pcEntriesRead and pcTotalAvail.

   The SERVER.H header file defines these flag bits:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                    Bit Mask    Type of Software
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SV_TYPE_WORKSTATION     0x00000001  Workstation.
 SV_TYPE_SERVER          0x00000002  Server.
 SV_TYPE_SQLSERVER       0x00000004  SQL server.
 SV_TYPE_DOMAIN_CTRL     0x00000008  Domain controller.
 Code                    Bit Mask    Type of Software
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
SV_TYPE_DOMAIN_CTRL     0x00000008  Domain controller.
 SV_TYPE_DOMAIN_BAKCTRL  0x00000010  Backup domain controller.
 SV_TYPE_TIME_SOURCE     0x00000020  Time server.
 SV_TYPE_AFP             0x00000040  Apple File Protocol (AFP) service.
 SV_TYPE_NOVELL          0x00000080  Novell service.
 SV_TYPE_ALL             0xFFFFFFFF  All types of servers.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 pszDomain
   Points to an ASCIIZ string that contains the name of the domain in which
   to enumerate servers of the specified type(s). The specified domain must
   be the primary domain, the logon domain, or a domain listed as one of the
   other domains for the computer specified by pszServer. (The domain name
   must appear in the wkiX_langroup, wkiX_logon_domain, or wkiX_oth_domains
   element of the wksta_info_X workstation data structure, where X is the
   level of detail specified.) If the domain does not meet these conditions,
   NetServerEnum2 returns NERR_NotLocalDomain.

   If pszDomain is a null string or a null pointer, servers are enumerated
   for the primary domain, logon domain, and other domains.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BrowserNotStarted            2139    The mailslots entry of the
                                           workstation's LANMAN.INI file is
                                           incorrect.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_BrowserTableIncomplete       2319    The information in the list of
                                           servers may be incorrect.

 NERR_NotLocalDomain               2320    The computer is not active in
                                           this domain.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          this domain.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If SV_TYPE_NOVELL or SV_TYPE_AFP is specified in the flServerType parameter,
 all servers running a service called "NOVELL" or "AFP," respectively, will
 be listed.

 If the workstation has been started with the mailslots = no entry in the
 LANMAN.INI file, NetServerEnum2 returns the NERR_BrowserNotStarted error
 code.

 NetServerEnum2 supersedes NetServerEnum (used in earlier versions of LAN
 Manager). These functions are the same except that NetServerEnum2 includes
 the flServerType and pszDomain parameters, which specify the type of server
 and the domain in which to enumerate that type of server. For more
 information, see Appendix B, "Upgrading LAN Manager 1.0 Applications."


 NetServerGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServerGetInfo retrieves information about the specified server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts, comm, print, or server operator privilege is
 required to successfully execute NetServerGetInfo at levels 2 or 3 on a
 remote server or on a computer that has local security enabled. No special
 privilege is required for level 0 or level 1 calls.


 Syntax

   #define INCL_NETSERVER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServerGetInfo (const char far *      pszServer,
                     short                 sLevel,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcbTotalAvail
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServerGetInfo. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0, 1, 2, or 3) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a server_info_X data structure, where X is 0,
   1, 2, or 3, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetServerGetInfo returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Configuring a server              NetServerSetInfo


 NetServerSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServerSetInfo sets a server's operating parameters; it can set them
 individually or collectively.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetServerSetInfo on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETSERVER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServerSetInfo (const char far *  pszServer,
                     short             sLevel,
                     const char far *  pbBuffer,
                     unsigned short    cbBuffer,
                     short             sParmNum
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServerSetInfo. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (1, 2, or 3) provided in the buffer pointed
   to by pbBuffer.

 pbBuffer
   Points to the data to be set.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to set all the server information or to change only a
   part of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a
   server_info_X data structure (where X is 1, 2, or 3, depending on the
   level of detail being set). If sParmNum is any other defined value, only
   one element of the server information is changed, and pbBuffer must point
   to a valid value for that element.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The SERVER.H header file
   defines these possible values for sParmNum:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                    Value  Element of server_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL             0      All elements.
 SV_COMMENT_PARMNUM      5      svX_comment
 SV_DISC_PARMNUM         10     svX_disc
 SV_ALERTS_PARMNUM       11     svX_alerts
 SV_HIDDEN_PARMNUM       16     svX_hidden
 SV_ANNOUNCE_PARMNUM     17     svX_announce
 SV_ANNDELTA_PARMNUM     18     svX_anndelta
 SV_ALERTSCHED_PARMNUM   37     svX_alertsched
 SV_ERRORALERT_PARMNUM   38     svX_erroralert
 SV_LOGONALERT_PARMNUM   39     svX_logonalert
 Code                    Value  Element of server_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
SV_LOGONALERT_PARMNUM   39     svX_logonalert
 SV_ACCESSALERT_PARMNUM  40     svX_accessalert
 SV_DISKALERT_PARMNUM    41     svX_diskalert
 SV_NETIOALERT_PARMNUM   42     svX_netioalert
 SV_MAXAUDITSZ_PARMNUM   43     svX_maxauditsz
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_NoRoom                       2119    The server could not access
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NoRoom                       2119    The server could not access
                                           enough of a resource, such as
                                           memory, to complete the task.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"

 Retrieving information about the  NetServerGetInfo
 configuration of a server





 Server Category Example

   /*
      NETSERV.C -- a sample program demonstrating NetServer API functions.

         usage:  netserv  [-s \\servername] [-c comment] [-l level]
                          [-t type] [-a admin command] [-d domain]
         where  \\server = Name of the server. A servername must be preceded
                           by two backslashes (\\).
                comment  = New comment for the server.
                level    = Level of detail to be provided/supplied.
                type     = Types of servers to enumerate.
                admin command = Command line for remote admin.
                domain   = List of domains to count.

      API                       Used to...
      =====================     ============================================
      NetServerGetInfo          Return information about the server
                                configuration
      NetServerSetInfo          Change the configuration of the server
      NetServerEnum2            List the servers visible on the network
      NetServerDiskEnum         List the disk drives on the server
      NetServerAdminCommand     Execute a sequence of commands on the
   server

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define  INCL_BASE
   #include <os2.h>                        // MS OS/2 base header files

   #define  INCL_NETERRORS
   #define  INCL_NETSERVER
   #include <lan.h>                        // LAN Manager header files

   #include <stdio.h>                      // C run-time header files
   #include <stdlib.h>
   #include <string.h>
   #include <malloc.h>

   #include "samples.h"                    // Internal routine header
   file

   #define A_CMD_STRING       "c: & cd \\ & dir"
   #define A_COMMENT          "This is a new comment"
   #define BIG_BUFFER_SIZE    32768

   void Usage(char *pszString);
   void main(int argc, char * argv[])
   {
      char * pszServer = "";             // NULL or null string = local
      char * pbBuffer;                   // Pointer to data buffer
      char * pszDisk;                    // Return string NetServerDiskEnum
      char * pszComment = A_COMMENT;     // New comment string
      char * pszCommand = A_CMD_STRING;  // Cmd for NetServerAdminCommand
      char far * pszDomain = NULL;       // Input to NetServerEnum2
      int iCount;                        // Index and loop counter
      short sLevel = 0;                  // Level of detail requested
      API_RET_TYPE uReturnCode;          // API return code
      unsigned short usRemoteRetCode;    // Return code of remote command
      unsigned short cbBuffer;           // Size of buffer, in bytes
      unsigned short cEntriesRead;       // Count of records returned
      unsigned short cTotalEntries;      // Count of records available

      unsigned short cbReturned;         // Count of bytes returned
      unsigned short cbTotalAvail;       // Count of bytes available

      unsigned long flServerType = SV_TYPE_SERVER;  // List of servers

      struct server_info_0 *pServer0;    // Pointer to level 0 structure
      struct server_info_1 *pServer1;    // Pointer to level 1 structure
      struct server_info_2 *pServer2;    // Pointer to level 2 structure
      struct server_info_3 *pServer3;    // Pointer to level 3 structure

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'a':                        // -a admin command
                  pszCommand = argv[++iCount];
                  break;
               case 'c':                        // -c comment
                  pszComment = argv[++iCount];
                  break;
               case 'l':                        // -l level
                  sLevel = (short)(atoi(argv[++iCount]));
                  break;
               case 'd':                        // -d domain
                  pszDomain = argv[++iCount];
                  break;

   case 't':                        // -t type
                  flServerType = (unsigned long)(atoi(argv[++iCount]));
                  break;
               default:
                  Usage(argv[0]);
               }
            }
         else
            Usage(argv[0]);
      } // End for loop

   //========================================================================
   //  NetServerGetInfo
   //
   //  This API returns information about the server's configuration

   //  components. The returned data reflects the current configuration,

   //  including any modifications made by calls to NetServerSetInfo.

   //  The results returned by this API will not necessarily match the
   //  contents of the LANMAN.INI file; use NetConfigGet2 to get the
   //  default values stored in the LANMAN.INI file.
   //========================================================================

     /*
      *  The structure returned by NetServerGetInfo is a combination
      *  of data elements and pointers to variable-size elements within
   the
      *  returned data. Because of this, the size of the data buffer
   passed
      *  to the API must be larger than the size of the structure. The
   extra
      *  space is needed for variable-length strings such as comment
   elements.
      *  The first call is used to determine how large a buffer is needed;
      *  the second call is used to obtain the data.
      */

      uReturnCode = NetServerGetInfo(pszServer, // Servername
                  sLevel,                       // Reporting level (0,1,2,3)
                  NULL,                         // Target buffer for
   info
                  0,                            // Size of target buffer
                  &cbTotalAvail);               // Total info available
      cbBuffer = cbTotalAvail;
      pbBuffer = SafeMalloc(cbBuffer);

      uReturnCode = NetServerGetInfo(pszServer, // Servername
                  sLevel,                       // Reporting level (0,1,2,3)
                  pbBuffer,                     // Target buffer for
   info
                  cbBuffer,                     // Size of target buffer
                  &cbTotalAvail);               // Total amount of info
      printf("NetServerGetInfo returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         switch (sLevel)
         {
            case 3:
               pServer3 = (struct server_info_3 *) pbBuffer;
               printf("   Audited events : 0x%lX\n",
                          pServer3->sv3_auditedevents);
            case 2:
               pServer2 = (struct server_info_2 *) pbBuffer;
               printf("   Heuristics     : %Fs\n",
                          pServer2->sv2_srvheuristics);
            case 1:
               pServer1 = (struct server_info_1 *) pbBuffer;
               printf("   Major version #: %hu\n",
                          pServer1->sv1_version_major & MAJOR_VERSION_MASK);
               printf("   Type           : 0x%X\n", pServer1->sv1_type);
               printf("   Comment        : %Fs\n", pServer1->sv1_comment);
            case 0:
               pServer0 = (struct server_info_0 *) pbBuffer;
               printf("   Computer Name  : %s\n", pServer0->sv0_name);
               break;
            default:
               printf("   Level %hu is not supported\n", sLevel);
               break;
         }
      }
      free(pbBuffer);

   //========================================================================
   //  NetServerSetInfo
   //
   //  This API function sets configuration components for the specified

   //  server. Note that the function does not change default configuration

   //  parameters in the LANMAN.INI file.
   //
   //  All SetInfo API functions can be called in two ways: to set all
   //  parameters, or to set a single parameter. To set all parameters,
   //  call NetServerGetInfo to obtain the current values of all
   //  parameters, modify the components to change, and then call
   //  NetServerSetInfo. To set one parameter, set the buffer pointer

   //  to point to the new value for that parameter, and then call
   //  NetServerSetInfo using the corresponding sParmNum value. In this

   //  example, NetServerSetInfo sets the server's comment field.
   //========================================================================

   uReturnCode = NetServerSetInfo(pszServer,    // Servername
                              sLevel,              // Level of detail
   (0,1)
                              pszComment,          // Pointer to input
   data
                              strlen(pszComment)+1,// String length +
   NUL
                              SV_COMMENT_PARMNUM); // Change comment
   only

      printf("NetServerSetInfo returned %u\n", uReturnCode);
      printf("   Set comment to \"%s\" ", pszComment);
      printf(" %s\n", uReturnCode ? "failed" : "succeeded");

   //========================================================================
   //  NetServerEnum2
   //
   //  This API lists all servers visible on the network in the given
   domain.
   //  In this example, the domain argument is NULL, indicating to list

   //  servers in the workstation's domain, its logon domain, and its
   other
   //  domains.
   //========================================================================

      cbBuffer = BIG_BUFFER_SIZE;                // Can be up to 64K
      pbBuffer = SafeMalloc(cbBuffer);           // Allocate space for
   buffer

      uReturnCode = NetServerEnum2(pszServer,    // Servername
                                  sLevel,        // Reporting level (0,1)
                                  pbBuffer,      // Buffer containing
   data
                                  cbBuffer,      // Size of buffer, in
   bytes
                                  &cEntriesRead, // Entries in buffer
                                  &cTotalEntries,// Count of entries
   available
                                  flServerType,  // Type(s) to enumerate
                                  pszDomain);    // Server's domain(s)

      printf("NetServerEnum2 returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         pServer0 = (struct server_info_0 *) pbBuffer;
         pServer1 = (struct server_info_1 *) pbBuffer;
         pServer2 = (struct server_info_2 *) pbBuffer;
         pServer3 = (struct server_info_3 *) pbBuffer;

   for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
         {
            switch (sLevel)
            {
               case 0:
                  printf("   Computer Name : %s\n", pServer0->sv0_name);
                  pServer0++;
                  break;
               case 1:
                  printf("   Computer Name : %s\n", pServer1->sv1_name);
                  printf("   Type          : 0x%X\n", pServer1->sv1_type);
                  pServer1++;
                  break;
               case 2:
                  printf("  Computer Name : %s\n", pServer2->sv2_name);
                  printf("  Type          : 0x%X\n", pServer2->sv2_type);
                  pServer2++;
                  break;
               case 3:
                  printf("  Computer Name : %s\n", pServer3->sv3_name);
                  printf("  Type          : 0x%X\n", pServer3->sv3_type);
                  pServer3++;
                  break;
               default:
                  break;
            } // End switch (sLevel)
         } // End for loop
         printf("%hu entries returned out of ", cEntriesRead);
         printf("%hu available\n", cTotalEntries);
      } // End if successful return

   //========================================================================
   //  NetServerDiskEnum
   //
   //  This API lists all the local disk drives for the specified server,

   //  including hard disk drives, floppy disk drives, and RAM drives.
   //========================================================================

      uReturnCode = NetServerDiskEnum(pszServer,  // Servername
                                 0,               // Level; must be 0
                                 pbBuffer,        // Results buffer
                                 cbBuffer,        // Size of buffer,
   in bytes
                                 &cEntriesRead,   // Count of entries
   read
                                 &cTotalEntries); // Count of entries
   available

      printf("NetServerDiskEnum returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)        // Print returned info
      {
         pszDisk = pbBuffer;
         printf("   Disk drives on server %s : \n", pszServer);
         for (iCount = 0; iCount < (int) cEntriesRead; iCount++)

   {
            printf("   %s\n", pszDisk);
            pszDisk += (strlen(pszDisk) + 1); // Skip NUL, get next string
         }
         printf("%hu entries returned out of ", cEntriesRead);
         printf("%hu available\n", cTotalEntries);
      }

   //========================================================================
   //  NetServerAdminCommand
   //
   //  This API executes a sequence of commands on the specified server.
   //  The default command string, "c: & cd \\ & dir", changes the current
   //  drive to the C: drive, changes the directory to the root C:\,
   //  and performs a list directory DIR command. The results returned
   //  in the buffer are displayed.
   //========================================================================

      if ((pszServer != NULL) && (pszServer[0] != '\0'))
         printf("On server %s", pszServer);
      else
         printf("On local computer");
      printf(" execute command string \"%s\"\n", pszCommand);

      uReturnCode = NetServerAdminCommand(pszServer, // Servername
                                 pszCommand,         // Commands to execute
                                 &usRemoteRetCode,   // Ret code of last
   cmd
                                 pbBuffer,           // Results buffer
                                 cbBuffer,           // Size of buffer
                                 &cbReturned,        // Count of bytes
   returned
                                 &cbTotalAvail);     // Count of bytes
   avail

   printf("NetServerAdminCommand returned %u\n", uReturnCode);
      if (uReturnCode == NERR_Success)               // Print returned
   info
      {
         printf("Return code of last command : %hu\n", usRemoteRetCode);

         printf("%hu out of %hu bytes returned\n", cbReturned, cbTotalAvail);
         printf("Buffer contents:\n");
         for (iCount = 0; iCount < (int) cbReturned; iCount++)
            printf("%c", *((char *)pbBuffer++) );
      }

      free(pbBuffer);
      exit(0);
      }


   //  Usage
   //
   //  Display possible command-line switches for this example.

   void Usage(char *pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server]", pszString);
      fprintf(stderr, " [-c comment] [-l level]\n [-t type]");
      fprintf(stderr, " [-a admin command] [-d domain(s)]\n");
      exit(1);
   }







 Session Category

 Session API functions control network sessions established between
 workstations and servers. They require that the Server service be started on
 the specified server.

 The Session category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETSESSION, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Session API functions:


   þ   NetSessionDel

   þ   NetSessionEnum

   þ   NetSessionGetInfo



 Description

 A session is a link between a workstation and a server. It is established
 the first time a workstation makes a connection with a shared resource on
 the server. Until the session ends, all further connections between the
 workstation and the server are part of this same session.

 To end a session, an application on the server end of a connection calls
 NetSessionDel. This deletes all current connections between the workstation
 and the server.

 NetSessionEnum returns information about all sessions established for a
 server. NetSessionGetInfo returns information about a particular session.


 Data Structures

 NetSessionEnum and NetSessionGetInfo return session_info_X data structures,
 where X is 0, 1, 2, or 10, depending on the level of data requested.


 Session Information (level 0)

 The session_info_0 data structure has this format:

   struct session_info_0 {
       char far *  sesi0_cname;
   };

 where

 sesi0_cname
   Points to an ASCIIZ string that contains the computername of the
   workstation that established the session.


 Session Information (level 1)

 The session_info_1 data structure has this format:

   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;
   };

 where

 sesi1_cname
   Points to an ASCIIZ string that contains the computername of the
   workstation that established the session.

 sesi1_username
   Points to an ASCIIZ string that contains the name of the user who
   established the session.

 sesi1_num_conns
   Specifies how many connections have been made during the session.

 sesi1_num_opens
   Specifies how many files, devices, and pipes have been opened during the
   session.

 sesi1_num_users
   Specifies how many users have made connections via the session.

 sesi1_time
   Specifies how long (in seconds) a session has been active.

 sesi1_idle_time
   Specifies how long (in seconds) a session has been idle.

 sesi1_user_flags
   Specifies how the user established the session. The SHARES.H header file
   defines this bit mask for sesi1_user_flags:

 Code               Bit  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SESS_GUEST         1    User specified by sesi1_username established the
                         session using a guest account.

 SESS_NOENCRYPTION  2    User specified by sesi1_username established the
                         session without using password encryption.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Session Information (level 2)

 The session_info_2 data structure has this format:

   struct session_info_2 {
       char far *      sesi2_cname;
       char far *      sesi2_username;
       unsigned short  sesi2_num_conns;
       unsigned short  sesi2_num_opens;
       unsigned short  sesi2_num_users;
       unsigned long   sesi2_time;
       unsigned long   sesi2_idle_time;
       unsigned long   sesi2_user_flags;
       char far *      sesi2_cltype_name;
   };

 where

 sesi2_cname through sesi2_user_flags
   Are the same as the corresponding elements of the session_info_1 data
   structure. For a complete description, see the preceding section.

 sesi2_cltype_name
   Points to an ASCIIZ string that specifies the type of client that
   established the session. These are the defined types for LAN Manager
   servers:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Name                              Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 DOWN LEVEL                        Old clients (for example, Microsoft
                                   Networks, PC LAN, XENIX(R)).

 DOS LM                            LAN Manager 1.0 for MS-DOS clients
 Name                              Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
DOS LM                            LAN Manager 1.0 for MS-DOS clients
                                   (Basic and Enhanced) and LAN Manager 2.0
                                   for MS-DOS Basic clients.

 DOS LM 2.0                        LAN Manager 2.0 for MS-DOS Enhanced
                                   clients.

 OS/2 LM 1.0                       LAN Manager 1.0 for MS OS/2 clients, or
                                   LAN Manager 2.0 for MS OS/2 with MS OS/2
                                   1.1.

 OS/2 LM 2.0                       LAN Manager 2.0 for MS OS/2 clients.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Session Information (level 10)

 The session_info_10 data structure has this format:

   struct session_info_10 {
       char far *     sesi10_cname;
       char far *     sesi10_username;
       unsigned long  sesi10_time;
       unsigned long  sesi10_idle_time;
   };

 where

 sesi10_cname through sesi10_idle_time
   Are the same as the corresponding elements of the session_info_1 data
   structure. For a complete description, see "Session Information (level
   1)," earlier in this category.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Guest accounts                    User Category


 NetSessionDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetSessionDel ends a session between a server and a workstation.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetSessionDel on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETSESSION
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetSessionDel (const char far *  pszServer,
                  const char far *  pszClientName,
                  short             sReserved
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetSessionDel. A null pointer or null string specifies the
   local server.

 pszClientName
   Points to an ASCIIZ string that contains the remote name of the computer
   whose session is being discontinued. The name must be preceded by two
   backslashes (for example, \\client).

 sReserved
   Reserved; must be 0.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ClientNameNotFound           2312    The specified computer does not
                                           have a session with the server.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_NoSuchServer                 2460    The server ID does not specify a
                                           valid server.

 NERR_NoSuchSession                2461    The session ID does not specify
                                           a valid session.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          a valid session.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 When NetSessionDel ends a session, it disconnects all connections
 established via the session and closes any files that were opened via the
 session. Data can be lost if any process on the workstation is communicating
 with the server when NetSessionDel is called.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Retrieving the status of a        NetSessionGetInfo
 server session


 NetSessionEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetSessionEnum provides information about all current sessions.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetSessionEnum at level 1 or level 2 on a remote server or on a
 computer that has local security enabled. No special privilege is required
 for level 0 or level 10 calls.


 Syntax

   #define INCL_NETSESSION
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetSessionEnum (const char far *      pszServer,
                   short                 sLevel,
                   char far *            pbBuffer,
                   unsigned short        cbBuffer,
                   unsigned short far *  pcEntriesRead,
                   unsigned short far *  pcTotalAvail
                  );

 where

 pszServer
   Points to an ASCIIZ string that specifies the name of the server on which
   to execute NetSessionEnum. A null pointer or null string specifies the
   local server.

 sLevel
   Specifies the level of detail (0, 1, 2, or 10) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of session_info_X data structures,
   where X is 0, 1, 2, or 10, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of
   sessions enumerated in the buffer is returned. This count is valid only if
   NetSessionEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of sessions is returned. This count is valid only if NetSessionEnum
   returns NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Deleting a session                NetSessionDel

 Listing information about a       NetConnectionEnum
 session between a particular
 workstation and server

 Retrieving information about a    NetSessionGetInfo
 session between a particular
 server and workstation.


 NetSessionGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetSessionGetInfo retrieves information about a session established between
 a particular server and workstation.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetSessionGetInfo at level 1 or level 2 on a remote server or on a
 computer that has local security enabled. No special privilege is required
 for level 0 or level 10 calls.


 Syntax

   #define INCL_NETSESSION
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetSessionGetInfo (const char far *      pszServer,
                      const char far *      pszClientName,
                      short                 sLevel,
                      char far *            pbBuffer,
                      unsigned short        cbBuffer,
                      unsigned short far *  pcbTotalAvail
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetSessionGetInfo. A null pointer or null string specifies the
   local server.

 pszClientName
   Points to an ASCIIZ string that contains the name of the computer whose
   session is to be monitored. The name must be preceded by two backslashes
   (for example, \\client).

 sLevel
   Specifies the level of detail (0, 1, 2, or 10) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a session_info_X data structure, where X is 0,
   1, 2, or 10, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetSessionGetInfo returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ClientNameNotFound           2312    The specified computer does not
                                           have a session with the server.

 NERR_InvalidComputer              2351    The specified computername is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Deleting a session                NetSessionDel

 Listing all sessions redirected   NetSessionEnum
 to a resource

 Listing information about a       NetConnectionEnum
 session between a particular
 workstation and server





 Session Category Example

   /*
      NETSESS.C -- a sample program demonstrating NetSession API functions.

      This program requires that you have admin privilege or server
      operator privilege on the specified server.

         usage:  netsess [-s \\server] [-w \\workstation]

         where  \\server      = Name of the server. A servername must
   be
                                preceded by two backslashes (\\).
                \\workstation = Name of the client machine to check.

      API                   Used to...
      =================     ================================================
      NetSessionEnum        Display list of workstations connected to
   server
      NetSessionGetInfo     Check that a particular workstation is connected
      NetSessionDel         Delete a session for a particular workstation

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_BASE
   #include    <os2.h>        // MS OS/2 base header files

   #define     INCL_NETERRORS
   #define     INCL_NETSESSION
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   #define     STRINGLEN 256
   #define     NETWKSTAGETINFOSIZE 1048

   // Function prototypes
   void Usage  (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pszServer = "";            // Servername
      char *         pszClientName = "";        // Workstation name
      char *         pbBuffer;                  // Pointer to data buffer
      int            iCount;                    // Index counter
      unsigned short cbBuffer;                  // Size of data buffer
      unsigned short cEntriesRead;              // Count of entries read
      unsigned short cTotalAvail;               // Count of entries available
      API_RET_TYPE   uReturnCode;               // API return code
      struct session_info_2 *  pSessInfo2;      // Session info; level
   2
      struct session_info_10 * pSessInfo10;     // Session info; level
   10

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'w':                        // -w workstation name
                  pszClientName = argv[++iCount];
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetSessionEnum
   //
   //  This API lists the workstations connected to the server.
   //  Calculate the buffer size needed by determining the number
   //  of sessions and multiplying this value by the size needed
   //  to store the data for one session.
   //========================================================================

   // Supply a zero-length buffer and get back the number of
   sessions.

      uReturnCode = NetSessionEnum(pszServer,     // "" or NULL means
   local
                                  10,             // Level (0,1,2,10)
                                  NULL,           // Return buffer
                                  0,              // Size of return buffer
                                  &cEntriesRead,  // Count of entries
   read
                                  &cTotalAvail);  // Count of total available
      if (uReturnCode != NERR_Success && uReturnCode != ERROR_MORE_DATA)
         printf("NetSessionEnum returned %u\n", uReturnCode);
      else
      {
         printf("There are %hu session(s)\n", cTotalAvail);
         if (cTotalAvail != 0 )
         {
            cbBuffer = cTotalAvail * (sizeof (struct session_info_10)
   +
                            CNLEN+1+              // Space for sesi10_cname
                            CNLEN+1);             // Space for
 sesi10_username
            pbBuffer = SafeMalloc(cbBuffer);

            // Buffer is large enough unless new sessions have been created.

            uReturnCode = NetSessionEnum(pszServer, // "" or NULL means
   local
                                   10,              // Level (0,1,2,10)
                                   pbBuffer,        // Return buffer
                                   cbBuffer,        // Size of return
   buffer
                                   &cEntriesRead,   // Count of entries
   read
                                   &cTotalAvail);   // Count of total
   available

            // Display information returned by the Enum call.

            if (uReturnCode == NERR_Success || uReturnCode ==
 ERROR_MORE_DATA)
            {
               pSessInfo10 = (struct session_info_10 *) pbBuffer;
               for (iCount = 0; iCount++ < (int) cEntriesRead; pSessInfo10++)
                  printf("   \"%Fs\"\n", pSessInfo10->sesi10_cname);
            // May be NULL if uReturnCode != NERR_Success.
            }
            else
               printf("NetSessionEnum returned %u\n", uReturnCode);

            free(pbBuffer);
         }
      }

   //========================================================================
   //  NetSessionGetInfo
   //
   //  This API displays information about sessions at level 2 (maximum

   //  information). Call NetSessionGetInfo with a zero-length buffer
   to
   //  determine the size of buffer required, and then call it again
   with
   //  the correct buffer size.
   //========================================================================

   uReturnCode = NetSessionGetInfo(pszServer,  // "" or NULL
   means local
                                   pszClientName, // Client to get info
   on
                                   2,             // Level (0,1,2,10)
                                   NULL,          // Return buffer
                                   0,             // Size of return buffer
                                   &cbBuffer);    // Count of bytes available

      if (uReturnCode != NERR_BufTooSmall)
         printf("NetSessionGetInfo with 0 byte buffer returned %u\n",
                uReturnCode);
      else
      {
         pbBuffer = SafeMalloc(cbBuffer);

         uReturnCode = NetSessionGetInfo(pszServer, // "" or NULL means
   local
                                   pszClientName,   // Client to get
   info on
                                   2,               // Level (0,1,2,10)
                                   pbBuffer,        // Return buffer
                                   cbBuffer,        // Size of return
   buffer
                                   &cTotalAvail);   // Count of bytes
   available

         printf("\nNetSessionGetInfo with %hu byte buffer returned %u\n\n",
                    cTotalAvail, uReturnCode);

   if (uReturnCode == NERR_Success )
         {
            pSessInfo2 = (struct session_info_2 *) pbBuffer;
            printf ("  Computer name :  %Fs\n", pSessInfo2->sesi2_cname);
            printf ("  User name     :  %Fs\n", pSessInfo2->sesi2_username);
            printf ("  # Connections :  %hu\n", pSessInfo2->sesi2_num_conns);
            printf ("  # Opens       :  %hu\n", pSessInfo2->sesi2_num_opens);
            printf ("  # Users       :  %hu\n", pSessInfo2->sesi2_num_users);
            printf ("  Seconds active:  %lu\n", pSessInfo2->sesi2_time);
            printf ("  Seconds idle  :  %lu\n", pSessInfo2->sesi2_idle_time);
            printf ("  User flags    :  %lu\n",
 pSessInfo2->sesi2_user_flags);
            printf ("  Client version:  %Fs\n",
 pSessInfo2->sesi2_cltype_name);
         }
         free(pbBuffer);
      }

   //========================================================================
   //  NetSessionDel
   //
   //  This API deletes the session with the specified workstation.
   //========================================================================

   uReturnCode = NetSessionDel(pszServer,      // "" or NULL
   means local
                                  pszClientName,  // Clientname
                                  0);             // Reserved; must be
   0

      printf("NetSessionDel returned %u\n", uReturnCode );

      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-w \\\\workstation]\n",
                 pszProgram);
      exit(1);
   }





 Share Category

 Share API functions control shared resources. They require that the
 Workstation service be started, and that the Server service be started on
 the specified server.

 The Share category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETSHARE, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the Share API functions:


   þ   NetShareAdd

   þ   NetShareCheck

   þ   NetShareDel

   þ   NetShareEnum

   þ   NetShareGetInfo

   þ   NetShareSetInfo



 Description

 A shared resource is a local resource on a server (for example, a disk
 directory, print device, or named pipe) that can be accessed by users and
 applications on the network.

 NetShareAdd allows a user or application to share a resource of a specific
 type using the specified sharename.

 On a server that has share-level security, NetShareAdd also assigns a
 password and permissions to the shared resource. A user or application can
 access the shared resource only by supplying the correct password.

 On a server that has user-level security, NetShareAdd requires only the
 sharename and local devicename to share the resource. A user or application
 must have an account on the server to access the resource. For information
 about accounts on servers that have user-level security, see the User
 category API functions. For information about assigning permissions in
 user-level security, see the Access Permissions category API functions.

 LAN Manager defines three types of special sharenames for interprocess
 communication (IPC) and remote administration of the server:


   þ   IPC$, reserved for interprocess communication

   þ   ADMIN$, reserved for remote administration

   þ   A$, B$, C$ (and other local disk names followed by a dollar sign),
       assigned to local disk devices



 Data Structures

 The Share API functions use the share_info_X data structures, where X is 0,
 1, or 2, depending on the level of detail specified by the sLevel parameter.


 NetShareEnum and NetShareGetInfo return data at levels 0, 1, and 2.
 NetShareSetInfo supports data supplied at levels 1 and 2. NetShareAdd
 supports data supplied at level 2.


 Share Information (level 0)

 The share_info_0 data structure has this format:

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

 where

 shi0_netname
   Contains an ASCIIZ string that specifies the sharename of a resource. The
   constant NNLEN is defined in the NETCONS.H header file.


 Share Information (level 1)

 The share_info_1 data structure has this format:

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

 where

 shi1_netname
   Contains an ASCIIZ string that specifies the sharename of the resource.
   The constant NNLEN is defined in the NETCONS.H header file.

 shi1_pad1
   Aligns the next data structure element on a word boundary.

 shi1_type
   Contains an integer that specifies the type of shared resource. The
   SHARES.H header file defines these possible values:

 Code            Value  Share Type
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 STYPE_DISKTREE  0      Disk directory tree.
 STYPE_PRINTQ    1      Printer queue.
 STYPE_DEVICE    2      Communication device.
 STYPE_IPC       3      Interprocess communication (IPC).
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 shi1_remark
   Points to an ASCIIZ string that contains a comment about the shared
   resource. The remark element must be set to NULL when NetShareAdd is
   called to add the ADMIN$ or IPC$ sharenames; the remark is supplied by
   NetShareAdd.


 Share Information (level 2)

 The share_info_2 data structure has this format:

   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;
   };

 where

 shi2_netname through shi2_remark
   Are the same as the corresponding elements of the share_info_1 data
   structure. For a complete description, see the preceding section.

 shi2_permissions
   Specifies the permissions for the shared resource on a server that has
   share-level security. This element is ignored on servers with user-level
   security. For servers that have share-level security, the ACCESS.H header
   file defines the bit mask for shi2_permissions:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code           Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code           Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ACCESS_READ    0x01      Permission to read data from a resource and, by
                          default, to execute the resource.

 ACCESS_WRITE   0x02      Permission to write data to the resource.

 ACCESS_CREATE  0x04      Permission to create an instance of the resource
                          (such as a file); data can be written to the
                          resource as the resource is created.

 ACCESS_EXEC    0x08      Permission to execute the resource.

 ACCESS_DELETE  0x10      Permission to delete the resource.

 ACCESS_ATRIB   0x20      Permission to modify the resource's attributes
                          (such as the date and time when a file was last
                          modified).

 ACCESS_PERM    0x40      Permission to modify the permissions (read, write,
                          create, execute, and delete) assigned to a
 Code           Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                         create, execute, and delete) assigned to a
                          resource for a user or application.

 ACCESS_ALL     0x7F      Permission to read, write, create, execute, and
                          delete data from a resource, and to modify
                          attributes and permissions.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 shi2_max_uses
   Specifies the maximum number of concurrent connections that the shared
   resource can accommodate. If shi2_max_uses is -1, the connections are
   unlimited.

 shi2_current_uses
   Specifies the number of connections to the resource.

 shi2_path
   Points to an ASCIIZ string that contains the local pathname of the shared
   resource. For disks, shi2_path is the path being shared. For printer
   queues, shi2_path is the name of the printer queue being shared. For
   communication-device queues, shi2_path is a string of one or more
   communication-device names. In this case, the devicenames are separated by
   spaces (for example, COM1 COM2 COM6). For ADMIN$ or IPC$ resources,
   shi2_path must be a null pointer.

 shi2_passwd
   Specifies the sharename's password for a server that has share-level
   security. For a server that has user-level security, shi2_passwd is NULL
   and is ignored. The constant SHPWLEN is defined in the NETCONS.H header
   file.

 shi2_pad2
   Aligns the next data structure element on a word boundary.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 ADMIN$ and IPC$ resources         Chapter 1, "Overview of the LAN Manager
                                   API"

 User accounts                     User Category


 NetShareAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetShareAdd shares a server resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm, print, or server operator privilege is required to
 successfully execute NetShareAdd on a remote server or on a computer that
 has local security enabled. The print operator can add only printer queues.
 The comm operator can add only communication-device queues.


 Syntax

   #define INCL_NETSHARE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetShareAdd (const char far *  pszServer,
                short             sLevel,
                const char far *  pbBuffer,
                unsigned short    cbBuffer
               );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetShareAdd. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail provided; must be 2.

 pbBuffer
   Points to the buffer that contains the share_info_2 data structure
   provided.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_NAME                123     The character or file system
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_FILENAME_EXCED_RANGE        206     The filename specified is
                                           invalid for the file system.
                                           This code is returned when
                                           checking a FAT disk partition
                                           only. It cannot be returned for
                                           an HPFS partition.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_UnknownServer                2103    The server was not found.

 NERR_ServerNotStarted             2114    The Server service is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_UnknownDevDir                2116    The device or directory does not
                                           exist.

 NERR_RedirectedPath               2117    The operation is invalid for a
                                           redirected resource. The
                                           devicename specified is assigned
                                           to a shared resource.

 NERR_DuplicateShare               2118    The sharename is already in use
                                           on this server.

 NERR_NoRoom                       2119    The server could not access
                                           enough of a resource, such as
                                           memory, to complete the task.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_QNotFound                    2150    The queuename specified is
                                           invalid.

 NERR_DeviceShareConflict          2318    Requests cannot be routed from
                                           both a printer queue and a
                                           communication-device queue to
                                           the same device.

 NERR_BadDevString                 2340    The list of devices is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BadDev                       2341    The devicename is invalid
                                           because it does not represent a
                                           physical device, or because the
                                           device hardware is faulty.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetShareAdd requires a level 2 data structure (share_info_2). Depending on
 the type of shared resource specified by the shi2_type element of the
 share_info_2 data structure, you can specify other elements in the data
 structure, as follows:

 Code            Value  Element Requirements
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 STYPE_DISKTREE  0      The shi2_path element must specify a file system
                        pathname, or it must be NULL for ADMIN$.

 STYPE_PRINTQ    1      The shi2_netname element must specify the name of
                        an existing printer queue.

 STYPE_DEVICE    2      The shi2_path element must be passed as a null
                        pointer, or it must point to a list of
                        communication devices (the devicenames must be
                        separated by spaces).

 STYPE_IPC       3      The shi2_netname element must specify an IPC$
                        resource, and shi2_path must point to a null string.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 NetShareAdd ignores the value specified in the shi2_current_uses element of
 share_info_2.

 If there is a conflict between the server_info_X element svX_numadmin and
 the share_info_2 element shi2_max_uses for the sharename ADMIN$, LAN Manager
 gives priority to the shi2_max_uses value. For more information, see your
 LAN Manager administrator's manual(s).

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the resources that can    NetShareEnum
 be shared on a server

 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"

 Removing a list of resources      NetShareDel
 that can be shared


 NetShareCheck
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetShareCheck checks whether or not a server is sharing a device.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege level is required to successfully execute
 NetShareCheck.


 Syntax

   #define INCL_NETSHARE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetShareCheck (const char far *      pszServer,
                  const char far *      pszDeviceName,
                  unsigned short far *  pusType
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetShareCheck. A null pointer or null string specifies the
   local computer.

 pszDeviceName
   Points to an ASCIIZ string that contains the name of the character device,
   print destination, or disk to check.

 pusType
   Points to an unsigned short integer that contains the returned data. The
   returned value specifies the type of the shared device specified by
   pszDeviceName. The SHARES.H header file defines these possible values:

 Code            Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 STYPE_DISKTREE  0      Disk directory tree.
 STYPE_PRINTQ    1      Printer queue.
 STYPE_DEVICE    2      Communication device.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NetNameNotFound              2310    The sharename does not exist.

 NERR_DeviceNotShared              2311    The device is not shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 The returned pusType value is valid only if NetShareCheck returns
 NERR_Success. If the device is not shared, NERR_DeviceNotShared is returned.


 NetShareCheck returns successfully if a specified device is in the routing
 list of a printer queue or a communication-device queue.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Reconfiguring a server resource   NetShareSetInfo
 that can be shared

 Retrieving the status of a        NetShareGetInfo
 shared resource


 NetShareDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetShareDel deletes a sharename from a server's list of shared resources,
 disconnecting all connections to the shared resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm, print, or server operator privilege is required to
 successfully execute NetShareDel on a remote server or on a computer that
 has local security enabled. The print operator can delete only printer
 queues. The comm operator can delete only communication-device queues.


 Syntax

   #define INCL_NETSHARE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetShareDel (const char far *  pszServer,
                const char far *  pszNetName,
                unsigned short    usReserved
               );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetShareDel. A null pointer or null string specifies the local
   computer.

 pszNetName
   Points to an ASCIIZ string that contains the sharename to be deleted.

 usReserved
   Reserved; must be 0.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NetNameNotFound              2310    The sharename does not exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Adding a share on a server        NetShareAdd

 Listing all connections to a      NetConnectionEnum
 shared resource

 Listing the resources on a        NetShareEnum
 server that can be shared


 NetShareEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetShareEnum retrieves information about each shared resource on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm, print, or server operator privilege is required to
 successfully execute NetShareEnum at level 2 on a remote server or on a
 computer that has local security enabled. No special privilege is required
 for level 0 or level 1 calls.


 Syntax

   #define INCL_NETSHARE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetShareEnum (const char far *      pszServer,
                 short                 sLevel,
                 char far *            pbBuffer,
                 unsigned short        cbBuffer,
                 unsigned short far *  pcEntriesRead,
                 unsigned short far *  pcTotalAvail
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetShareEnum. A null pointer or null string specifies the local
   server.

 sLevel
   Specifies the level of detail (0, 1, or 2) returned.

 pbBuffer
   Points to the buffer in which to store the return data. On a successful
   return, the buffer contains a sequence of share_info_X data structures,
   where X is 0, 1, or 2, depending on the level of detail specified.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of
   shared resources enumerated in the buffer is returned. This count is valid
   only if NetShareEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of shared resources is returned. This count is valid only if NetShareEnum
   returns NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Retrieving information about a    NetShareGetInfo
 particular shared resource


 NetShareGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetShareGetInfo retrieves information about a particular shared resource on
 a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm, print, or server operator privilege is required to
 successfully execute NetShareGetInfo at level 2 on a remote server or on a
 computer that has local security enabled. No special privilege is required
 for level 0 or level 1 calls.


 Syntax

   #define INCL_NETSHARE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetShareGetInfo (const char far *      pszServer,
                    const char far *      pszNetName,
                    short                 sLevel,
                    char far *            pbBuffer,
                    unsigned short        cbBuffer,
                    unsigned short far *  pcbTotalAvail
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetShareGetInfo. A null pointer or null string specifies the
   local computer.

 pszNetName
   Points to an ASCIIZ string that contains the name of the shared resource.

 sLevel
   Specifies the level of detail (0, 1, or 2) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a share_info_X data structure, where X is 0,
   1, or 2, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetShareGetInfo returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          this transaction: IPC$ is not
                                           shared.

 NERR_NetNameNotFound              2310    The sharename does not exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Reconfiguring a shareable server  NetShareSetInfo
 resource


 NetShareSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetShareSetInfo sets the parameters of a shared resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or comm, print, or server operator privilege is required to
 successfully execute NetShareSetInfo on a remote server or on a computer
 that has local security enabled. The print operator can set information only
 about printer queues. The comm operator can set information only about
 communication-device queues.


 Syntax

   #define INCL_NETSHARE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetShareSetInfo (const char far *  pszServer,
                    const char far *  pszNetName,
                    short             sLevel,
                    const char far *  pbBuffer,
                    unsigned short    cbBuffer,
                    short             sParmNum
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetShareSetInfo. A null pointer or null string specifies the
   local computer.

 pszNetName
   Points to an ASCIIZ string that contains the sharename of the resource to
   be set.

 sLevel
   Specifies the level of detail (1 or 2) provided.

 pbBuffer
   Points to the data to be set.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to set all share information or to change only a part of
   it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a share_info_X data
   structure, where X is 1 or 2, depending on the level of detail provided.
   If sParmNum is any other defined value, only one element of the share
   information is changed, and pbBuffer must point to a valid value for that
   element.

   Not all fields can be set. Only those fields that have a specific PARMNUM
   constant value defined can be set. The SHARES.H header files define these
   possible values for sParmNum and the associated elements that must be
   supplied in the data buffer:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                     Value  Element of share_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL              0      All elements.
 SHI_REMARK_PARMNUM       4      shiX_remark
 SHI_PERMISSIONS_PARMNUM  5      shi2_permissions
 SHI_MAX_USES_PARMNUM     6      shi2_max_uses
 SHI_PASSWD_PARMNUM       9      shi2_passwd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                     Value  Element of share_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_NetNameNotFound              2310    The sharename does not exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If there is a conflict between the server_info_X element svX_numadmin and
 the share_info_2 element shi2_max_uses for the sharename ADMIN$, LAN Manager
 gives priority to the shi2_max_uses value. For more information, see your
 LAN Manager administrator's manual(s).

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Retrieving the status of a        NetShareGetInfo
 server resource that can be
 shared





 Share Category Example

   /*
      NETSHARE.C -- a sample program demonstrating NetShare API functions.

      This program requires that you have admin privilege or server
      operator privilege on the specified server.

         usage:  netshare [-s \\server] [-r sharename] [-p path]
                          [-d devicename] [-l level] [-t type] [-c comment]
         where  \\server   = Name of the server. A servername must be
                             preceded by two backslashes (\\).
                sharename  = Name of the shared resource.
                path       = Share path for directory tree shares.
                devicename = Name of the device, such as LPT1, COM1,
   or C:
                level      = Level of detail; 0, 1, or 2.
                type       = Type of share; Directory=0, Printer Queue=1,
                                Comm device=2, IPC=3.
                comment    = Remark to be added to the share.

      API                 Used to...
      ===============     =================================================
      NetShareAdd         Add a shared resource
      NetShareGetInfo     Get the details of the shared resource just
   added
      NetShareSetInfo     Change the maximum users of the share
      NetShareDel         Delete the above share
      NetShareCheck       Check to see if the device has been shared
      NetShareEnum        Display the list of current shares

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETERRORS
   #define     INCL_NETSHARE
   #include    <lan.h>            // LAN Manager header files

   #include    <stdio.h>          // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"        // Internal routine header file

   #define BIG_BUFFER_SIZE   32768
   #define A_SHAREPATH       "A:\\"
   #define A_SHARENAME       "FLOPPY"
   #define A_SHAREREMARK     "shared floppy drive"
   #define CHECK_RESOURCE    "LPT1"
   #define MAX_USERS         8

   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      char * pszServer = NULL;                // Default to local server
      char * pbBuffer;                        // Return data buffer
      char * pszResShare = A_SHAREPATH;       // Share path
      char * pszResCheck = CHECK_RESOURCE;    // Device for NetShareCheck

      char * pszNetName = A_SHARENAME;        // Name for the shared
   resource
      char * pszRemark = A_SHAREREMARK;       // Default share comment
      int    iCount;                          // Index and loop counter
      unsigned short usMaxUses;               // For SetInfo call
      unsigned short cEntriesRead;            // Count of entries read
      unsigned short cTotalAvail;             // Count of entries available
      unsigned short cbBuffer;                // Size of buffer, in bytes
      unsigned short cbTotalAvail;            // Total available data
      unsigned short sLevel = 1;              // Level of detail
      unsigned short usType = STYPE_DISKTREE; // Share type for NetShareAdd
      API_RET_TYPE   uReturnCode;             // API return code
      struct share_info_0 *pBuf0;             // Pointer to returned
   data
      struct share_info_1 *pBuf1;             // Level 1 data
      struct share_info_2 *pBuf2;             // Level 2 data

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'r':                        // -r sharename
                  pszNetName = argv[++iCount];
                  break;
               case 'l':                        // -l level
                  sLevel = (short)(atoi(argv[++iCount]));
                  break;
               case 'd':                        // -d devicename
                  pszResCheck = argv[++iCount];
                  break;

   case 't':                        // -t share type
                  usType = (unsigned short)(atoi(argv[++iCount]));
                  break;
               case 'c':                        // -c comment for share
                  pszRemark = argv[++iCount];
                  break;
               case 'p':                        // -p pathname for share
                  pszResShare = argv[++iCount];
                  break;
               default:
                  Usage(argv[0]);
               }
            }
         else
            Usage(argv[0]);
      } // End for loop

   //========================================================================
   //  NetShareAdd
   //
   //  This API adds a shared resource. The default is to share the
   //  A:\ drive using the sharename FLOPPY. The API must be called at

   //  level 2. The logged-on user must have admin privilege or server
   //  operator privilege, and the Server service must be started for
   //  this call to succeed.
   //========================================================================

      cbBuffer = sizeof(struct share_info_2);
      pbBuffer = SafeMalloc(cbBuffer);            // Allocate buffer
      pBuf2 = (struct share_info_2 *)pbBuffer;    // Start of memory
   block

      strcpy(pBuf2->shi2_netname, pszNetName);    // Sharename
      pBuf2->shi2_path = pszResShare;             // Local pathname
      pBuf2->shi2_type = usType;                  // Share type
      pBuf2->shi2_passwd[0] = '\0';               // No password
      pBuf2->shi2_remark = pszRemark;             // Share remark
      pBuf2->shi2_permissions = ACCESS_PERM;      // Admin privilege
      pBuf2->shi2_max_uses = MAX_USERS;           // Max. users of share

      uReturnCode = NetShareAdd(pszServer,        // Servername
                                2,                // Info level; must
   be 2
                                pbBuffer,         // Data structure
                                cbBuffer);        // Size of buffer,
   in bytes

   printf("NetShareAdd returned %u\n", uReturnCode);
      switch (uReturnCode)
      {
         case NERR_DuplicateShare:
            printf("Resource %s is already shared\n\n", pszResShare);
            break;
         case NERR_ServerNotStarted:
            printf("The server is not started\n\n");
            exit(1);
            break;
         default:
            break;
      }
      free(pbBuffer);

   //========================================================================
   //  NetShareGetInfo
   //
   //  This API gets and displays information about the sharename just
   added.
   //========================================================================

      cbBuffer = BIG_BUFFER_SIZE;                 // Large enough buffer
      pbBuffer = SafeMalloc(cbBuffer);            // Allocate buffer

      uReturnCode = NetShareGetInfo(pszServer,    // Servername
                          pszNetName,             // Device to get info
   about
                          sLevel,                 // Info level
                          pbBuffer,               // Data returned here
                          cbBuffer,               // Size of buffer,
   in bytes
                          &cbTotalAvail);         // Bytes of data available

      printf("NetShareGetInfo of %s ", pszNetName);
      printf(" returned %u\n", uReturnCode);
      if (uReturnCode == NERR_Success)
      {
         switch (sLevel)
         {
            case 2:                               // Use level 2 structure
               pBuf2 = (struct share_info_2 *) pbBuffer;
               printf("   Permissions : 0x%x\n", pBuf2->shi2_permissions);
               printf("   Max. users  : %hu\n", pBuf2->shi2_max_uses);
               printf("   Curr. users : %hu\n", pBuf2->shi2_current_uses);
               printf("   Path        : %Fs\n", pBuf2->shi2_path);
            case 1:                               // Use level 1 structure
               pBuf1 = (struct share_info_1 *) pbBuffer;
               printf("   Type        : %hu\n", pBuf1->shi1_type);
               printf("   Remark      : %Fs\n", pBuf1->shi1_remark);
            case 0:                               // Use level 0 structure
               pBuf0 = (struct share_info_0 *) pbBuffer;
               printf("   Resource    : %s\n", pBuf0->shi0_netname);
               break;
            default:
               break;
         }
      }


   //  NetShareSetInfo
   //
   //  This API changes the maximum number of users allowed by the share

   //  to unlimited. There are two ways to call NetShareSetInfo. If
   //  sParmNum == PARMNUM_ALL, you must set the whole structure. Otherwise,

   //  you can set sParmNum to the element of the structure you want
   to
   //  change. This example sets only the "max uses" parameter by setting
   //  sParmNum to SHI_MAX_USES_PARMNUM.

      usMaxUses = SHI_USES_UNLIMITED;

      uReturnCode = NetShareSetInfo(pszServer,    // Servername
                          pszNetName,             // Device to set info
   on
                          2,                      // Info level
                          (char far *)&usMaxUses, // Data buffer address
                          sizeof(usMaxUses),      // Size of buffer,
   in bytes
                          SHI_MAX_USES_PARMNUM);  // Parameter to set

      printf("NetShareSetInfo of max. users returned %u\n", uReturnCode);

   //========================================================================
   //  NetShareDel
   //
   //  This API deletes the sharename established by the previous
   //  NetShareAdd call.
   //========================================================================

      uReturnCode = NetShareDel(pszServer,        // Servername
                                pszNetName,       // Sharename to be
   deleted
                                0);               // Reserved; must be
   0

      printf("NetShareDel of %s returned %u\n", pszNetName, uReturnCode);

   //========================================================================
   //  NetShareCheck
   //
   //  This API checks to see if the device is being shared.
   //========================================================================

      uReturnCode = NetShareCheck(pszServer,      // Servername
                                  pszResCheck,    // Device to check
                                  &usType);       // Return share type

      printf("NetShareCheck of %s returned %u\n", pszResCheck, uReturnCode);
      switch (uReturnCode)
      {
         case NERR_Success:
            printf("   Resource %s is shared as type %hu\n",
                       pszResCheck, usType);
            break;
         case NERR_DeviceNotShared:
            printf("   Resource %s is not shared\n", pszResCheck);
            break;
         default:
            break;
      }

   //========================================================================
   //  NetShareEnum
   //
   //  This API displays the current sharenames.
   //========================================================================

      uReturnCode = NetShareEnum(pszServer,      // Servername
                               sLevel,           // Info level
                               pbBuffer,         // Data returned here
                               cbBuffer,         // Size of buffer, in
   bytes
                               &cEntriesRead,    // Count of entries
   read
                               &cTotalAvail);    // Count of entries
   available

      printf("NetShareEnum returned %u \n", uReturnCode);

   if (uReturnCode == NERR_Success)
      {
         pBuf0 = (struct share_info_0 *) pbBuffer;
         pBuf1 = (struct share_info_1 *) pbBuffer;
         pBuf2 = (struct share_info_2 *) pbBuffer;
         for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
         {
            switch (sLevel)
            {
               case 0:
                  printf("   %s\n", pBuf0->shi0_netname);
                  pBuf0++;
                  break;
               case 1:
                  printf("   %s\n", pBuf1->shi1_netname);
                  printf("      remark: %Fs\n", pBuf1->shi1_remark);
                  pBuf1++;
                  break;
               case 2:
                  printf("%s\n", pBuf2->shi2_netname);
                  printf("      remark: %Fs\n", pBuf1->shi1_remark);
                  printf("      path: %Fs\n\n", pBuf2->shi2_path);
                  pBuf2++;
                  break;
            }
         }
         printf("Entries read: %hu out of %hu \n", cEntriesRead,
 cTotalAvail);
      }

      free(pbBuffer);
      exit(0);
   }

   //========================================================================
   //  Usage
   //
   //  Display possible command-line switches for this example.
   //========================================================================

   void Usage(char *pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server]", pszString);
      fprintf(stderr, " [-r sharename] [-l level]\n\t\t[-d devicename]");
      fprintf(stderr, " [-t type] [-c comment] [-p path]\n");
      exit(1);
   }







 Statistics Category

 The Statistics API function, NetStatisticsGet2, retrieves and clears the
 operating statistics for workstations and servers. It requires that the
 Workstation service be started and, if server statistics are required, that
 the Server service be started.

 The Statistics category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and NETSTATS.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETSTATS, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.


 Description

 LAN Manager accumulates a set of operating statistics for workstations and
 servers from the time that the Workstation or Server service is started.
 NetStatisticsGet2 is called to get, and optionally clear, those statistics.



 Data Structures

 NetStatisticsGet2 returns a stat_workstation_0 data structure when
 workstation statistics are requested; it returns a stat_server_0 data
 structure when server statistics are requested.


 Workstation Statistics

 The stat_workstation_0 data structure has this format:

   struct stat_workstation_0 {
       unsigned long stw0_start;
       unsigned long stw0_numNCB_r;
       unsigned long stw0_numNCB_s;
       unsigned long stw0_numNCB_a;
       unsigned long stw0_fiNCB_r;
       unsigned long stw0_fiNCB_s;
       unsigned long stw0_fiNCB_a;
       unsigned long stw0_fcNCB_r;
       unsigned long stw0_fcNCB_s;
       unsigned long stw0_fcNCB_a;
       unsigned long stw0_sesstart;
       unsigned long stw0_sessfailcon;
       unsigned long stw0_sessbroke;
       unsigned long stw0_uses;
       unsigned long stw0_usefail;
       unsigned long stw0_autorec;
       unsigned long stw0_bytessent_r_hi;
       unsigned long stw0_bytessent_r_lo;
       unsigned long stw0_bytesrcvd_r_hi;
       unsigned long stw0_bytesrcvd_r_lo;
       unsigned long stw0_bytessent_s_hi;
       unsigned long stw0_bytessent_s_lo;
       unsigned long stw0_bytesrcvd_s_hi;
       unsigned long stw0_bytesrcvd_s_lo;
       unsigned long stw0_bytessent_a_hi;
       unsigned long stw0_bytessent_a_lo;
       unsigned long stw0_bytesrcvd_a_hi;
       unsigned long stw0_bytesrcvd_a_lo;
       unsigned long stw0_reqbufneed;
       unsigned long stw0_bigbufneed;
   };

 where

 stw0_start
   Specifies the time statistics collection started. This element also
   indicates when the statistics were last cleared. The value is stored as
   the number of seconds elapsed since 00:00:00, January 1, 1970. To
   calculate the length of time that statistics have been collected, subtract
   this value from the present time.

 stw0_numNCB
   These three elements indicate the total number of network control blocks
   (NCBs) issued from each source (the counts include failed NCBs). To
   calculate the total number of successful NCBs, subtract the number of
   failed NCBs from stw0_numNCB. These numbers are held in the stw0_fiNCB and
   stw0_fcNCB elements, and are explained in the stw0_fiNCB and stw0_fcNCB
   descriptions following this list.

     stw0_numNCB_r
       Specifies the total number of NCBs issued by the redirector.

     stw0_numNCB_s
       Specifies the total number of NCBs issued by the server.

     stw0_numNCB_a
       Specifies the total number of NCBs issued by applications.

 stw0_fiNCB
   These three elements indicate the number of NCBs that failed for any
   reason when they were issued. These NCBs are included in the "total
   issued" count specified by stw0_numNCB.

     stw0_fiNCB_r
       Specifies the number of NCBs that failed when issued by the
       redirector.

     stw0_fiNCB_s
       Specifies the number of NCBs that failed when issued by the server.

     stw0_fiNCB_a
       Specifies the number of NCBs that failed when issued by applications.

 stw0_fcNCB
   These three elements indicate the number of NCBs that failed after issue,
   at or before completion. These NCBs are also included in the "total
   issued" count specified by stw0_numNCB.

     stw0_fcNCB_r
       Specifies the number of NCBs that were issued by the redirector and
       that failed before completion.

     stw0_fcNCB_s
       Specifies the number of NCBs that were issued by the server and that
       failed before completion.

     stw0_fcNCB_a
       Specifies the number of NCBs that were issued by applications and that
       failed before completion.

 stw0_sesstart
   Specifies the number of workstation sessions started.

 stw0_sessfailcon
   Specifies the number of workstation sessions that failed to connect, not
   counting those that failed due to "name not found."

 stw0_sessbroke
   Specifies the number of workstation sessions that failed after the session
   was established.

 stw0_uses
   Specifies the number of workstation uses.

 stw0_usefail
   Specifies the number of workstation use failures. This is a count of the
   times the tree connections failed, when a server is found but the
   resources are not found.

 stw0_autorec
   Specifies the number of workstation autoconnections.

 The following 12 elements form six quad-words that contain very large
 counters. (A quad-word is a data area twice as large as a double word.) The
 high double word (dword) of each is the value divided by 2
 sup 32; the low dword is the value modulo 2 sup 32. The counter value equals
 (high dword * 2 sup 32) + (low dword).

 These elements count total bytes in all NCBs sent and received for all
 categories.

 Note the following for all the NCB-related and byte-count counters:


   þ   Elements with the suffix _r are NCBs issued by the redirector as part
       of the typical process of maintaining remote network connections.

   þ   Elements with the suffix _s are server-related, sent by the redirector
       on behalf of the server to maintain shared resource connections.

   þ   Elements with the suffix _a are application-generated NCBs.
       Applications can generate these elements by calling NetBiosSubmit,
       using second-class mailslots, sending and receiving server
       announcements, and so on.

       stw0_bytessent_r_hi
   Specifies the number of workstation bytes sent to the network (high
   dword).

       stw0_bytessent_r_lo
   Specifies the number of workstation bytes sent to the network (low dword).

       stw0_bytesrcvd_r_hi
   Specifies the number of workstation bytes received from the network (high
   dword).

       stw0_bytesrcvd_r_lo
   Specifies the number of workstation bytes received from the network (low
   dword).

       stw0_bytessent_s_hi
   Specifies the number of server bytes sent to the network (high dword).

       stw0_bytessent_s_lo
   Specifies the number of server bytes sent to the network (low dword).

       stw0_bytesrcvd_s_hi
   Specifies the number of workstation bytes received from the network (high
   dword).

       stw0_bytesrcvd_s_lo
   Specifies the number of workstation bytes received from the network (low
   dword).

       stw0_bytessent_a_hi
   Specifies the number of application bytes sent to the network (high
   dword).

       stw0_bytessent_a_lo
   Specifies the number of application bytes sent to the network (low dword).

       stw0_bytesrcvd_a_hi
   Specifies the number of application bytes received from the network (high
   dword).

       stw0_bytesrcvd_a_lo
   Specifies the number of application bytes received from the network (low
   dword).

       stw0_reqbufneed
   Specifies the number of times the workstation required a request buffer
   but failed to allocate one. This element indicates that the workstation
   parameters may need adjustment.

       stw0_bigbufneed
   Specifies the number of times the workstation required a big buffer but
   failed to allocate one. This element indicates that the workstation
   parameters may need adjustment.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE
 A value of STATS_NO_VALUE for any element means that information is not
 available. A value of STATS_OVERFLOW means that the element has overflowed.
 The NETSTATS.H header file defines these
 constants.ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Server Statistics

 The stat_server_0 data structure has this format:

   struct stat_server_0 {
       unsigned long sts0_start;
       unsigned long sts0_fopens;
       unsigned long sts0_devopens;
       unsigned long sts0_jobsqueued;
       unsigned long sts0_sopens;
       unsigned long sts0_stimedout;
       unsigned long sts0_serrorout;
       unsigned long sts0_pwerrors;
       unsigned long sts0_permerrors;
       unsigned long sts0_syserrors;
       unsigned long sts0_bytessent_low;
       unsigned long sts0_bytessent_high;
       unsigned long sts0_bytesrcvd_low;
       unsigned long sts0_bytesrcvd_high;
       unsigned long sts0_avresponse;
       unsigned long sts0_reqbufneed;
       unsigned long sts0_bigbufneed;
   };

 where

 sts0_start
   Specifies the time statistics collection started. This element also
   indicates when the statistics were last cleared. The value is stored as
   the number of seconds elapsed since 00:00:00, January 1, 1970. To
   calculate the length of time that statistics have been collected, subtract
   this value from the present time.

 sts0_fopens
   Specifies the number of server file opens. This includes opens of named
   pipes.

 sts0_devopens
   Specifies the number of server device opens.

 sts0_jobsqueued
   Specifies the number of server print jobs spooled.

 sts0_sopens
   Specifies the number of times the server session started.

 sts0_stimedout
   Specifies the number of times the server session automatically
   disconnected.

 sts0_serrorout
   Specifies the number of times the server sessions failed with an error.

 sts0_pwerrors
   Specifies the number of server password violations.

 sts0_permerrors
   Specifies the number of server access permission errors.

 sts0_syserrors
   Specifies the number of server system errors.

 The following four elements form two quad-words, which contain very large
 counters. (A quad-word is a data area twice as large as a double word.) The
 high dword of each is the value divided by 2 sup 32; the low dword is the
 value modulo 2 sup 32. The counter value equals (high dword * 2 sup 32) +
 (low dword).

 sts0_bytessent_low
   Specifies the number of server bytes sent to the network (low dword).

 sts0_bytessent_high
   Specifies the number of server bytes sent to the network (high dword).

 sts0_bytesrcvd_low
   Specifies the number of server bytes received from the network (low
   dword).

 sts0_bytesrcvd_high
   Specifies the number of server bytes received from the network (high
   dword).

 sts0_avresponse
   Specifies the average server response time (in milliseconds).

 sts0_reqbufneed
   Specifies the number of times the server required a request buffer but
   failed to allocate one. This value indicates that the server parameters
   may need adjustment.

 sts0_bigbufneed
   Specifies the number of times the server required a big buffer but failed
   to allocate one. This value indicates that the server parameters may need
   adjustment.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 A value of STATS_NO_VALUE for any element means that information is not
 available. A value of STATS_OVERFLOW means that the element has overflowed.
 The NETSTATS.H header file defines these constants.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 NetStatisticsGet2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetStatisticsGet2 retrieves, and optionally clears, operating statistics for
 a service. Currently, only the Workstation and Server services are
 supported.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetStatisticsGet2 on a remote server. A non-admin class user cannot
 use this function to clear statistics on a computer that has local security
 enabled.


 Syntax

   #define INCL_NETSTATS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetStatisticsGet2 (const char far *      pszServer,
                      const char far *      pszService,
                      unsigned long         ulReserved,
                      short                 sLevel,
                      unsigned long         flOptions,
                      char far *            pbBuffer,
                      unsigned short        cbBuffer,
                      unsigned short far *  pcbTotalAvail
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetStatisticsGet2. A null pointer or null string specifies the
   local computer.

 pszService
   Points to an ASCIIZ string that contains the name of the service about
   which to get the statistics. Only the values SERVER and WORKSTATION are
   currently allowed. If another name is used, NetStatisticsGet2 returns
   ERROR_NOT_SUPPORTED.

 ulReserved
   Reserved; must be 0.

 sLevel
   Specifies the level of detail requested; must be 0.

 flOptions
   Specifies the options flags. The NETSTATS.H header file defines these
   possible values:

 Bit(s)  Bit Mask  Code          Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0       0x1       STATSOPT_CLR  Clear statistics.
 1-31                            Reserved; must be 0.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   The option to clear the statistics allows automatic get and clear
   operations. This allows an application compiling cumulative numbers to
   ensure that no data is missed in the time between the get operation and
   the clear operation.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a stat_workstation_0 data structure if
   pszService is WORKSTATION; it contains a stat_server_0 data structure if
   pszService is SERVER.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. The count is valid only if
   NetStatisticsGet2 returns NERR_Success or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_ServiceNotInstalled          2184    The service is not running.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ServiceNotInstalled          2184    The service is not running.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If server statistics are requested and the server is not running,
 NetStatisticsGet2 returns NERR_ServiceNotInstalled.

 NetStatisticsGet2supersedes NetStatisticsClearand NetStatisticsGet(used in
 earlier versions of LAN Manager). For more information, see Appendix B,
 "Upgrading LAN Manager 1.0 Applications."



 Statistics Category Example

   /*
      NETSTATS.C -- a sample program demonstrating NetStatisticsGet2.

      This program requires that you have admin privilege or server
      operator privilege on the specified server if a servername
      parameter is supplied.

      usage:  netstats [-s \\server] [-v service] [-clear]

      where  \\server = Name of the server. A servername must be preceded
                        by two backslashes (\\).
             service  = Name of the service.
             clear    = Flag to specify to clear the statistics.

      API                   Used to...
      =================     ===============================================
      NetStatisticsGet2     Get, and optionally clear, operating statistics
                            for a service.

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETERRORS
   #define     INCL_NETSTATS
   #include    <lan.h>             // LAN Manager header files

   #include    <stdio.h>           // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>
   #include    <time.h>

   #include    "samples.h"         // Internal routine header file

   #define     DEFAULT_SERVICE     "WORKSTATION"

   void usage (char * pszProgram);

   void main(int argc, char * argv[])
   {
      char * pszServer = "";                 // Servername
      char * pszService = DEFAULT_SERVICE;   // Service on which to get
   stats
      char * pbBuffer;                       // Pointer to data buffer
      int    iCount;                         // Index for arguments
      API_RET_TYPE   uReturnCode;            // API return code
      unsigned short cbBuffer;               // Size of buffer
      unsigned short cbTotalAvail;           // Count of bytes available
      unsigned long  flClear = 0;            // 0 = leave stats; 1 =
   clear
      struct stat_server_0 * pStatServ0;     // Server statistics
      struct stat_workstation_0 * pStatWksta0;  // Workstation statistics

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1)))     // Process switches
            {
               case 's':                            // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'v':                            // -v service
                  pszService = argv[++iCount];
                  break;
               case 'c':                            // -clear
                  flClear = STATSOPT_CLR;
                  iCount++;
                  break;
               case 'h':
               default:
                  usage(argv[0]);
            }
         }
         else
            usage(argv[0]);
      }

   //========================================================================
   //  NetStatisticsGet2
   //
   //  This API gets, and optionally clears, operating statistics for
   a
   //  service. Only the Server and Workstation services are supported.
   //  Note: To calculate the local starting time of the statistics,
   //  the environment variable TZ should be set to GMT0.
   //========================================================================

      // Allocate a data buffer large enough for the statistics.
      if (strcmpi(pszService, "SERVER"))
         cbBuffer = sizeof(struct stat_workstation_0);
      else
         cbBuffer = sizeof(struct stat_server_0);

      pbBuffer = SafeMalloc(cbBuffer);

      uReturnCode = NetStatisticsGet2(
                              pszServer,        // Servername
                              pszService,       // Name of service to
   report
                              0L,               // Reserved; must be
   0L
                              0,                // Level; must be 0
                              flClear,          // Options flag
                              pbBuffer,         // Information buffer
                              cbBuffer,         // Size of information
   buffer
                              &cbTotalAvail);   // Count of bytes available

      printf("NetStatisticsGet2 returned %u\n", uReturnCode);

   switch (uReturnCode)
      {
         case NERR_Success:
            putenv("TZ=GMT0");          // Allow ctime() to report local
   time
            if (strcmpi(pszService, "SERVER"))   // Check if not SERVER
            {
               pStatWksta0 = (struct stat_workstation_0 *) pbBuffer;
               printf("   Starting time of statistics        : %s",
                       ctime((const time_t *)&(pStatWksta0->stw0_start)));
               printf("   Workstation bytes sent (high DWORD): %lu\n",
                       pStatWksta0->stw0_bytessent_r_hi);
               printf("   Workstation bytes sent (low DWORD) : %lu\n",
                       pStatWksta0->stw0_bytessent_r_lo);
            }
            else                                // Must be SERVER
            {
               pStatServ0 = (struct stat_server_0 *) pbBuffer;
               printf("   starting time of statistics   : %s",
                       ctime((const time_t *)&(pStatServ0->sts0_start)));
               printf("   server bytes sent (high DWORD): %lu\n",
                       pStatServ0->sts0_bytessent_high);
               printf("   server bytes sent (low DWORD) : %lu\n",
                       pStatServ0->sts0_bytessent_low);
            }
            printf("%hu bytes of data available\n", cbTotalAvail);
            break;

         case NERR_BadTransactConfig:
            printf("   NetStatisticsGet2 requires the server to share
   IPC$\n");

         case ERROR_NOT_SUPPORTED:
            printf("   Service name must be SERVER or WORKSTATION\n");
            break;

         default:
            break;
      }
      free (pbBuffer);
   }

   void usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-v service] [-clear]\n",
                      pszProgram);
      exit(1);
   }





 Service Category

 Service API functions control network services. All except NetServiceInstall
 require the Workstation service to be started. NetServiceInstall can install
 the Workstation service, and the Workstation service must be started before
 NetServiceInstall can install any other service.

 The Service category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and SERVICE.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETSERVICE, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category, and Appendix C, "Creating LAN Manager Services."

 These are the Service API functions:


   þ   NetServiceControl

   þ   NetServiceEnum

   þ   NetServiceGetInfo

   þ   NetServiceInstall

   þ   NetServiceStatus



 Description

 A service is an application that an administrator can control using the LAN
 Manager interfaces.

 Services allow administrators to control applications on the network and
 maintain the integrity of users' data. On a typical network, applications
 are shared by many users. If an administrator terminates an application
 running on a server, a user who has not finished working with that
 application can lose important data. When an application is implemented as a
 service, LAN Manager checks the status before changing the state of the
 service.

 LAN Manager provides several standard services, such as the Workstation,
 Server, and Messenger services. For a complete description of these and
 other available services, see your LAN Manager administrator's manual(s).

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 The IBM(R) LAN Server and IBM EE LAN Requester use the service name
 "requester" instead of "Workstation."

 The LAN Manager spooler is no longer implemented as a service. Applications
 that attempt to control the spooler using the Service API functions will not
 operate properly.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 A service can be installed (started) using the Service API functions. At
 installation time, the service defines whether it can be stopped
 (uninstalled), paused, and continued.

 NetServiceControl controls the operations of network services, and it can
 provide time hints to controlling applications. NetServiceEnum retrieves
 information about all installed services. NetServiceGetInfo retrieves
 information about a particular installed service. NetServiceInstall installs
 a network service. NetServiceStatus sets status and code information for a
 network service.


 Time Hints for Starting and Stopping a Service

 LAN Manager is designed to allow timing information about services that take
 a long time to start or to stop. An application can use this information to
 determine how long to wait for the service or to provide timing information
 to the user. This information is contained in the svcs_code and svcs_text
 elements of the service_status data structure.

 Services (and applications that start or stop services) can use timing
 information to communicate during start and stop operations. Any service
 that has a significant initialization or shutdown task (two or more seconds)
 should use this method.

 The control-completion-pending (CCP) code is defined as part of the
 svcs_code element of the service_status data structure and the svciX_code
 elements of the server_info_X data structures, where X is 0, 1, or 2,
 depending on the level of detail specified. The CCP code consists of three
 fields: checkpoint, wait time, and hint bit. Constants relating to the CCP
 codes are defined in the SERVICE.H header file.

 A service should frequently call NetServiceStatus to update the checkpoint
 portion of the CCP code. An application can then monitor the checkpoint
 value to determine whether the service is still running. (The service's
 calls to NetServiceStatus to update the CCP code should be in the main code
 path, not in a timer-triggered thread that might live on even if the current
 operation halts due to error.)

 If the service is not using CCP codes, you should set the CCP code fields to
 0 while the service status element (svcs_status) has the value
 SERVICE_INSTALL_PENDING or SERVICE_UNINSTALL_PENDING. Unused bits should
 also be set to 0 to ensure compatibility with future versions.

 With LAN Manager 1.0, svcs_code was used only to indicate the status of
 service installation. The codes have been extended in LAN Manager 2.0 to
 indicate the status of service installation and shutdown.

 LAN Manager 1.0 constant names such as SERVICE_IP_CHKPT_NUM suggested that
 the codes represented install pending (IP) codes. LAN Manager 2.0 constant
 names such as SERVICE_CCP_CHKPT_NUM suggest that the codes represent CCP
 codes. The new names indicate that these codes cover not only installation,
 but also shutdown. The IP and CCP constants have the same values. All new
 applications should use the CCP constants.


 Service Names

 Many of the service category API functions require a service name. The
 SERVICE.H header file defines these names for the standard LAN Manager
 services:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                    ASCIIZ String  Service
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_WORKSTATION     WORKSTATION    Workstation.

 SERVICE_SERVER          SERVER         Server.
 Code                    ASCIIZ String  Service
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
SERVICE_SERVER          SERVER         Server.

 SERVICE_MESSENGER       MESSENGER      Messenger.

 SERVICE_NETRUN          NETRUN         Netrun.

 SERVICE_SPOOLER         SPOOLER        Spooler.

 SERVICE_ALERTER         ALERTER        Alerter.

 SERVICE_NETLOGON        NETLOGON       Netlogon.

 SERVICE_NETPOPUP        NETPOPUP       Netpopup.

 SERVICE_SQLSERVER       SQLSERVER      SQL Server.

 SERVICE_REPL            REPLICATOR     Replicator.

 SERVICE_RIPL            REMOTEBOOT     Remoteboot.
 Code                    ASCIIZ String  Service
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
SERVICE_RIPL            REMOTEBOOT     Remoteboot.

 SERVICE_TIMESOURCE      TIMESOURCE     Timesource.

 SERVICE_AFP             AFP            Apple File Protocol (AFP) service.

 SERVICE_UPS             UPS            UPS.

 SERVICE_DOS_ENCRYPTION  ENCRYPT        Encryption service for MS-DOS LAN
                                        Manager.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 If you write your own service, you should define a name for the service that
 does not match any of the names listed in this table. For more information
 about writing your own services, see Appendix C, "Creating LAN Manager
 Services."


 Data Structures

 NetServiceStatus uses the service_status data structure.

 All other Service API functions use the service_info_X data structures,
 where X is 0, 1, or 2. NetServiceEnum and NetServiceGetInfo return
 information at three levels of detail (0, 1, or 2). NetServiceControl and
 NetServiceInstall use the level 2 data structure only.


 Service Status

 The service_status data structure has this format:

   struct service_status {
       unsigned short  svcs_status;
       unsigned long   svcs_code;
       unsigned short  svcs_pid;
       char            svcs_text[STXTLEN+1];
   };

 where

 svcs_status
   Specifies the status of the service. The status element is composed of
   several subfields. The SERVICE.H header file defines these possible
   values:

ÖÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Bit(s)  Code                         Bit Mask  Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0-1     SERVICE_INSTALL_STATE        0x03      General status of the
                                                service.

 2-3     SERVICE_PAUSE_STATE          0x0C      Paused/active status.

 4       Ä                            Ä         Service can or cannot be
                                                installed.

 5       Ä                            Ä         Service can or cannot be
 Bit(s)  Code                         Bit Mask  Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
5       Ä                            Ä         Service can or cannot be
                                                paused.

 6-7     Ä                            Ä         Reserved.

 8-10    SERVICE_REDIR_PAUSED         0x0700    Redirection paused/active.

 11-15   Ä                            Ä         Reserved.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   Bits 0-1 have these values:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_UNINSTALLED               0x00        Service is uninstalled.

 SERVICE_INSTALL_PENDING           0x01        Service install is pending.

 SERVICE_UNINSTALL_PENDING         0x02        Service uninstall is pending.

 SERVICE_INSTALLED                 0x03        Service is installed.

   Bits 2-3 have these values:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_ACTIVE                    0x00        Service is active.

 SERVICE_CONTINUE_PENDING          0x04        Service continue is pending.

 SERVICE_PAUSE_PENDING             0x08        Service pause is pending.

 SERVICE_PAUSED                    0x0C        Service is paused.

   Bit 4 has these values:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_NOT_UNINSTALLABLE         0x00        Service cannot be removed.

 SERVICE_UNINSTALLABLE             0x10        Service can be removed.

   Bit 5 has these values:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_NOT_PAUSABLE              0x00        Service cannot be paused.

 SERVICE_PAUSABLE                  0x20        Service can be paused.

   Bits 8-10 have these values:

 Code                              Value       Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_REDIR_DISK_PAUSED         0x100       Redirector for disks is
                                               paused.

 SERVICE_REDIR_PRINT_PAUSED        0x200       Redirector for spooled
                                               devices is paused.

 SERVICE_REDIR_COMM_PAUSED         0x400       Redirector for communication
                                               devices is paused.

 svcs_code
   Specifies a code that indicates the service status. For stopped
 services (when svcs_status has the value SERVICE_UNINSTALLED),
 the most significant word
 of svcs_code defines the primary error code. When svcs_status
 has the value SERVICE_INSTALL_PENDING or SERVICE_UNINSTALL_PENDING,
 the least significant word defines a secondary error code, or hint
 and checkpoint information.

   The SERVICE.H header file defines these high-word values of
 svcs_code:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                    Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_UIC_NORMAL      0      Normal.
 Code                    Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_UIC_NORMAL      0      Normal.

 SERVICE_UIC_BADPARMVAL  3051   A bad parameter value was specified.

 SERVICE_UIC_MISSPARM    3052   A parameter is missing.

 SERVICE_UIC_UNKPARM     3053   An unknown parameter was specified.

 SERVICE_UIC_RESOURCE    3054   The resource is insufficient.

 SERVICE_UIC_CONFIG      3055   Configuration is faulty.

 SERVICE_UIC_SYSTEM      3056   An MS-DOS or MS OS/2 error occurred.

 SERVICE_UIC_INTERNAL    3057   An internal error occurred.

 SERVICE_UIC_AMBIGPARM   3058   An ambiguous parameter name was given.

 SERVICE_UIC_DUPPARM     3059   A duplicate parameter exists.
 Code                    Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
SERVICE_UIC_DUPPARM     3059   A duplicate parameter exists.

 SERVICE_UIC_KILL        3060   The service was terminated by
                                NetServiceControl when it did not respond.

 SERVICE_UIC_EXEC        3061   The service program file could not be
                                executed.

 SERVICE_UIC_SUBSERV     3062   The subservice failed to install.

 SERVICE_UIC_CONFLPARM   3063   There is a conflict in the value or use of
                                these parameters.

 SERVICE_UIC_FILE        3064   There is a problem with the file.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   When the least significant word is used as a modifier for
 the error code, these are the low-word values of svcs_code:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_UIC_M_NULL                0      Normal.

 SERVICE_UIC_M_MEMORY              3070   There is insufficient memory.

 SERVICE_UIC_M_DISK                3071   There is insufficient disk space.

 SERVICE_UIC_M_THREADS             3072   Unable to create thread.

 SERVICE_UIC_M_PROCESSES           3073   Unable to create process.

 SERVICE_UIC_M_SECURITY            3074   A security failure occurred.

 SERVICE_UIC_M_LANROOT             3075   There is a bad or missing default
                                          path.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 SERVICE_UIC_M_REDIR               3076   Network software is not installed.

 SERVICE_UIC_M_SERVER              3077   Server software is not installed.

 SERVICE_UIC_M_SEC_FILE_ERR        3078   The server could not access the
                                          UAS database.

 SERVICE_UIC_M_FILES               3079   This action requires user-level
                                          security.

 SERVICE_UIC_M_LOGS                3080   The log directory is invalid.

 SERVICE_UIC_M_LANGROUP            3081   The LAN group specified could not
                                          be used.

 SERVICE_UIC_M_MSGNAME             3082   The computername is being used as
                                          a message alias on another
                                          computer.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         computer.

 SERVICE_UIC_M_ANNOUNCE            3083   The workstation failed to
                                          announce the servername.

 SERVICE_UIC_M_UAS                 3084   The user accounts system is not
                                          configured properly.

 SERVICE_UIC_M_SERVER_SEC_ERR      3085   The server is not running with
                                          user-level security.

 SERVICE_UIC_M_WKSTA               3087   The workstation is not configured
                                          properly.

 SERVICE_UIC_M_ERRLOG              3088   View your error log for details.

 SERVICE_UIC_M_FILE_UW             3089   Unable to write to this file.

 SERVICE_UIC_M_ADDPAK              3090   The addpak file is corrupt.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
SERVICE_UIC_M_ADDPAK              3090   The addpak file is corrupt.
                                          Delete the file and reapply all
                                          addpaks.

 SERVICE_UIC_M_LAZY                3091   The server with HPFS386 cannot be
                                          started because CACHE.EXE is not
                                          running.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   For services in the states SERVICE_INSTALL_PENDING
 or SERVICE_UNINSTALL_PENDING (startup or shutdown), SERVICE.H
 defines the following values for the least significant word of svcs_code:

 Bit(s)  Code                         Bit Mask  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0-7     SERVICE_CCP_CHKPT_NUM,       0x0FF     Checkpoint number.
         SERVICE_IP_CHKPT_NUM

 8-15    SERVICE_CCP_WAIT_TIME,       0x0FF00   Time to wait (in tenths of
         SERVICE_IP_WAIT_TIME                   a second) for install or
                                                uninstall.

 16      SERVICE_CCP_QUERY_HINT,      0x10000   If 1, a hint is given.
         SERVICE_IP_QUERY_HINT

 17-32   Ä                            Ä         Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


   Bits 8-15 specify the time to wait, the expected time
 (in tenths of a second) to complete the current start or stop operation
 .

   The checkpoint number should be incremented each time the
 service calls NetServiceStatus.

   The hint bit informs the application controlling the service
 that the time and count information are valid.

   If the hint bit is set to 1, the svcs_text element
 can contain an ASCIIZ string that provides information about the current
 state of the service. The service can use a null string (provide no
 information). It is up to the controlling application to make use
 of the text field. A value of 1 for the hint bit indicates that the
 text is suitable for the user to see.

 svcs_pid
   Specifies the program identification number (PID) of a service.

 svcs_text
   Contains an ASCIIZ string if the service is stopped or a null
 string if the service is running. In this case, svcs_text can
 contain a parameter string related to the CCP
 code contained in the svcs_code element. The constant STXTLEN
 is defined in the NETCONS.H header file.


 Service Information (level 0)

 The service_info_0 data structure has this format:

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

 where

 svci0_name
   Specifies an ASCIIZ string that contains the name of the network service.
   The constant SNLEN is defined in the NETCONS.H header file.


 Service Information (level 1)

 The service_info_1 data structure has this format:

   struct service_info_1 {
       char           svci1_name[SNLEN+1];
       unsigned short svci1_status;
       unsigned long  svci1_code;
       unsigned short svci1_pid;
   };

 where

 svci1_name
   Contains an ASCIIZ string that specifies which network service to monitor.
   The constant SNLEN is defined in the NETCONS.H header file.

 svci1_status through svci1_pid
   Are the same as the corresponding elements of the service_status data
   structure. For a complete description, see "Service Status," earlier in
   this category.


 Service Information (level 2)

 The service_info_2 data structure has the following format:

   struct service_info_2 {
       char            svci2_name[SNLEN+1];
       unsigned short  svci2_status;
       unsigned long   svci2_code;
       unsigned short  svci2_pid;
       char            svci2_text[STXTLEN+1];
   };

 where

 svci2_name
   Contains an ASCIIZ string that specifies the name of the network service.
   The constant SNLEN is defined in the NETCONS.H header file.

 svci2_status through svci2_text
   Are the same as the corresponding elements of the service_status data
   structure. For a complete description, see "Service Status," earlier in
   this category.


 NetServiceControl
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServiceControl controls the operations of network services.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetServiceControl on a remote server, unless the opcode is
 SERVICE_CTRL_INTERROGATE. In this case, no special privilege is required.


 Syntax

   #define INCL_NETSERVICE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServiceControl (const char far *  pszServer,
                      const char far *  pszService,
                      unsigned char     fbOpCode,
                      unsigned char     fbArg,
                      char far *        pbBuffer,
                      unsigned short    cbBuffer
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServiceControl. A null pointer or null string specifies the
   local computer.

 pszService
   Points to an ASCIIZ string that contains the name of the network service
   being controlled.

 fbOpCode
   Specifies a value that indicates the action to perform on the service. The
   SERVICE.H header file defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                      Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_CTRL_INTERROGATE  0      Query the service status.
 SERVICE_CTRL_PAUSE        1      Pause the service.
 SERVICE_CTRL_CONTINUE     2      Continue the service.
 SERVICE_CTRL_UNINSTALL    3      Uninstall the service.
                           4-255  Reserved; must be 0.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 fbArg
   Specifies which service-specific operation to perform. This parameter is
   used when fbOpCode has the value SERVICE_CTRL_PAUSE or
   SERVICE_CTRL_CONTINUE. The SERVICE.H header file defines these possible
   values:

 Code                      Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_CTRL_REDIR_DISK   0x1    Disk resource.
 SERVICE_CTRL_REDIR_PRINT  0x2    Print resource.
 SERVICE_CTRL_REDIR_COMM   0x4    Communication resource.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 pbBuffer
   Points to the buffer that contains the return data. On a successful
   return, the buffer contains a service_info_2 data structure.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ServiceTableLocked           2180    The service does not respond to
                                           control actions.

 NERR_ServiceNotInstalled          2184    The service is not running.

 NERR_ServiceCtlTimeout            2186    The service does not respond to
                                           the control function.

 NERR_ServiceCtlBusy               2187    The service control is not
                                           currently responding to requests.
                                           Another program may be
                                           controlling the service or there
                                           may be a software problem.

 NERR_ServiceNotCtrl               2189    The service is not currently
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ServiceNotCtrl               2189    The service is not currently
                                           accepting requests. If the
                                           service is starting, it cannot
                                           process requests until it is
                                           fully started.

 NERR_ServiceKillProc              2190    The service was not running
                                           properly and would not respond
                                           to a command. The service was
                                           terminated.

 NERR_ServiceCtlNotValid           2191    The command is invalid for this
                                           service, or the service cannot
                                           accept the command right now.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If the operation specified by fbOpCode takes a long time to complete,
 NetServiceControl can return intermediate status and code values. For
 long-running operations, an application should issue successive calls to
 NetServiceControl to verify that the operation has finished.

 NetServiceControl acts on services that are started. If a service state is
 SERVICE_UNINSTALLED, SERVICE_UNINSTALL_PENDING, or SERVICE_INSTALL_PENDING,
 NetServiceControl returns the NERR_ServiceCtlNotValid error code. There is
 one exception: an application can pass the fbOpCode parameter with the value


 SERVICE_CTRL_INTERROGATE to query the last known state of a stopped service
 (SERVICE_UNINSTALLED). If a service has never been installed,
 NetServiceControl returns the NERR_ServiceNotInstalled error code.

 NetServiceControl can only pause and continue services running with MS-DOS.
 It cannot stop these services.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the services installed    NetServiceEnum
 on a server

 Updating status and code          NetServiceStatus
 information for a service


 NetServiceEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServiceEnum retrieves information about all started (installed) services,
 including paused services.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 No special privilege level is required to successfully execute
 NetServiceEnum.


 Syntax

   #define INCL_NETSERVICE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServiceEnum (const char far *      pszServer,
                   short                 sLevel,
                   char far *            pbBuffer,
                   unsigned short        cbBuffer,
                   unsigned short far *  pcEntriesRead,
                   unsigned short far *  pcTotalAvail
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServiceEnum. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0, 1, or 2) requested.

 pbBuffer
   Points to the buffer in which the data is returned. The buffer contains
   records of the service_info_X data structure, where X is 0, 1, or 2,
   depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer that specifies the number of entries
   returned in the buffer pointed to by pbBuffer. This count is valid only if
   NetServiceEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer that specifies the number of entries
   available. This count is valid only if NetServiceEnum returns NERR_Success
   or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ServiceTableLocked           2180    The service does not respond to
                                           control actions.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 NetServiceGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServiceGetInfo retrieves information about a particular started
 (installed) service.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 No special privilege level is required to successfully execute
 NetServiceGetInfo.


 Syntax

   #define INCL_NETSERVICE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServiceGetInfo (const char far *      pszServer,
                      const char far *      pszService,
                      short                 sLevel,
                      char far *            pbBuffer,
                      unsigned short        cbBuffer,
                      unsigned short far *  pcbTotalAvail
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetServiceGetInfo. A null pointer or null string specifies the
   local computer.

 pszService
   Points to an ASCIIZ string that contains the name of the network service
   for which information is being requested.

 sLevel
   Specifies the level of detail (0, 1, or 2) requested.

 pbBuffer
   Points to the buffer in which data will be returned. The buffer contains
   the service_info_X data structure, where X is 0, 1, or 2, depending on the
   level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer that specifies the number of bytes of
   information available. This count is valid only if NetServiceGetInfo
   returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ServiceTableLocked           2180    The service does not respond to
                                           control actions.

 NERR_ServiceNotInstalled          2184    The service is not running.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetServiceGetInfo returns NERR_Success for services that are not started
 (SERVICE_UNINSTALLED).

 NetServiceGetInfo is similar to NetServiceControl when NetServiceControl
 takes as its opcode SERVICE_CTRL_INTERROGATE. However, NetServiceGetInfo
 does not actively query the service; it only reads the status last posted by
 the service.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Controlling the operations of a   NetServiceControl
 network service


 NetServiceInstall
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServiceInstall starts a network service.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or server operator privilege is required to successfully
 execute NetServiceInstall on a remote server.


 Syntax

   #define INCL_NETSERVICE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServiceInstall (const char far *  pszServer,
                      const char far *  pszService,
                      const char far *  pszCmdArgs,
                      char far *        pbBuffer,
                      unsigned short    cbBuffer
                     );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetService Install. A null pointer or null string specifies the
   local computer.

 pszService
   Points to an ASCIIZ string that specifies which network service to
   install.

 pszCmdArgs
   Points to an ASCIIZ string that contains the command-line arguments for
   the service. This parameter can be a null pointer, or it can point to a
   series of ASCIIZ string parameters terminated by a NUL character, as shown
   here:

   param:value\0 param\0 param=value\0 \0

   These parameters are merged with [services] section parameters from the
   LANMAN.INI file and passed to the service program. The pszCmdArgs
   parameters take precedence over the parameters supplied in the LANMAN.INI
   file.

 pbBuffer
   Points to an ASCIIZ string that contains the return data. On a successful
   return, the buffer contains a service_info_2 data structure.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_LanmanIniError               2131    The LANMAN.INI file is missing
                                           or contains invalid information.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_LineTooLong                  2149    A line in the LANMAN.INI file is
                                           too long.

 NERR_ServiceTableLocked           2180    The service does not respond to
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ServiceTableLocked           2180    The service does not respond to
                                           control actions.

 NERR_ServiceTableFull             2181    Another service cannot be
                                           started because the maximum
                                           number of services specified in
                                           the LANMAN.INI file has been
                                           reached.

 NERR_ServiceInstalled             2182    The requested service is already
                                           running.

 NERR_ServiceEntryLocked           2183    The service does not respond to
                                           control actions.

 NERR_BadServiceName               2185    The service name is invalid.

 NERR_ServiceCtlTimeout            2186    The service does not respond to
                                           the control function.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          the control function.

 NERR_ServiceCtlBusy               2187    The service control is not
                                           currently responding to requests.
                                           Another program may be
                                           controlling the service or there
                                           may be a software problem.

 NERR_BadServiceProgName           2188    The LANMAN.INI file has
                                           associated a service with a
                                           nonexistent program file.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Service names are found in the LANMAN.INI file. NetServiceInstall matches
 the executable filenames of the service to a corresponding entry in the
 [services] section of the LANMAN.INI file. Any relative file pathname is
 assumed to be relative to the LAN Manager root directory (for example,
 C:\LANMAN\).

 If using a 386(tm) computer with HPFS, and if the caller has admin
 privilege, the NetServiceInstall function starts the service as a privileged
 service not subject to access control list (ACL) restrictions. This provides
 compatibility with earlier versions of LAN Manager. Services started using
 the run command in the CONFIG.SYS file are also started as privileged. These
 services effectively become part of the privileged operating system and the
 administrator must be confident of their reliability.

 Descendant processes inherit the privilege of the parent process or the
 privilege of the logged-on user.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Controlling network services      NetServiceControl

 Listing available servers         NetServerEnum2


 NetServiceStatus
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetServiceStatus allows a service to make its status information available
 to other services and applications.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to successfully execute
 NetServiceStatus.


 Syntax

   #define INCL_NETSERVICE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetServiceStatus (const char far *  pbBuffer,
                     unsigned short    cbBuffer
                    );

 where

 pbBuffer
   Points to the buffer that contains the service_status data structure
   provided for the service.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_ServiceTableLocked           2180    The service does not respond to
                                           control actions.

 NERR_ServiceNotInstalled          2184    The service is not running.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Applications implemented as services can call NetServiceStatus to update LAN
 Manager status and code tables. A service should call NetServiceStatus when
 its status changes.

 If an application not installed as a service (that is, it is not installed
 by a call to NetServiceInstall) calls NetServiceStatus, the
 NERR_ServiceNotInstalled error code is returned.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Controlling the operation of a    NetServiceControl
 network service





 Service Category Example

   /*
      NETSVC.C -- a sample program demonstrating NetService API functions.

      This program requires that you have admin privilege on the specified
      server.

      usage:  netsvc [-s \\server] [-v servicename] [-l level]

      where  \\server    = Name of the server. A servername must be preceded
                           by two backslashes (\\).
             servicename = Name of the service.
             level       = Level of detail requested.

      API                   Used to...
      =================     ================================================
      NetServiceInstall     Install the specified service
      NetServiceControl     Check progress of installation and uninstall
   the
                            specified service
      NetServiceEnum        List services and their status

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_BASE
   #include    <os2.h>        // MS OS/2 base header files

   #define     INCL_NETERRORS
   #define     INCL_NETSERVICE
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <conio.h>
   #include    <stdlib.h>

   #include    "samples.h"    // Internal routine header file

   #define A_SERVICE          SERVICE_TIMESOURCE  // Default servicename
   #define DEFAULT_WAITTIME   150          // 0.1 seconds; 150 = 1.5
   sec
   #define MAX_POLLS          5            // Max. checks (5*1.5 sec
   = 20 sec)
   #define WAIT_MULT          10

   void InstallService (char *pszServer, char *pszService);
   void UninstallService (char *pszServer, char *pszService);
   void Usage(char * pszString);

   void main(int argc, char *argv[])
   {
      char *                 pszServer = "";  // Default to local machine
      char *                 pszService = A_SERVICE; // Servicename
      char *                 pbBuffer;        // Buffer for return data
      unsigned short         cEntriesRead;    // Count of entries in
   buffer
      unsigned short         cTotalEntries;   // Count available
      unsigned short         cbBuffer;        // Size of buffer, in bytes
      int                    iCount;          // Index and loop counter
      short                  sLevel =  0;     // Level of detail
      API_RET_TYPE           uRet;            // API function return
   code
      struct service_info_0 *pSvc0;           // Service info; level
   0
      struct service_info_1 *pSvc1;           // Service info; level
   1
      struct service_info_2 *pSvc2;           // Service info; level
   2

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'v':                        // -v servicename
                  pszService = argv[++iCount];
                  break;
               case 'l':                        // -l level
                  sLevel = (short)(atoi(argv[++iCount]));
                  break;
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      } // End for loop

   //======================================================================
   //  NetServiceInstall and NetServiceControl
   //
   //  The NetServiceInstall API installs a service. Reassure the user

   //  that installation is proceeding by using NetServiceControl.
   //======================================================================
      InstallService(pszServer, pszService);

   //====================================================================
   //  NetServiceEnum
   //
   //  This API displays a list of installed services.
   //====================================================================

      // First, a call to see what size buffer is needed.
      uRet = NetServiceEnum(pszServer,      // Servername
                           sLevel,          // Info level
                           NULL,            // Pointer to buffer
                           0,               // Size of buffer
                           &cEntriesRead,   // Count of entries read
                           &cTotalEntries); // Count of entries available

      // Allocate enough for level 2; big enough for all other levels.
      cbBuffer = cTotalEntries * sizeof (struct service_info_2);
      pbBuffer = SafeMalloc(cbBuffer);
      pSvc0 = (struct service_info_0 *) pbBuffer;     // If sLevel ==
   0
      pSvc1 = (struct service_info_1 *) pbBuffer;     // If sLevel ==
   1
      pSvc2 = (struct service_info_2 *) pbBuffer;     // If sLevel ==
   2

      uRet = NetServiceEnum(pszServer,   // Servername
                        sLevel,          // Info level
                        pbBuffer,        // Data returned here
                        cbBuffer,        // Size of buffer, in bytes
                        &cEntriesRead,   // Count of entries read
                        &cTotalEntries); // Count of entries available

      printf("NetServiceEnum returned %u\n", uRet);
      if (uRet == NERR_Success)
      {
         printf("Services installed");
         if ((pszServer == NULL) || (*pszServer == '\0'))
             printf(" on local server:\n");
         else
             printf(" on server %s:\n", pszServer);
         for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
         {
            switch (sLevel)
            {
               case 0:
                  printf("   %s\n", pSvc0->svci0_name);
                  pSvc0++;
                  break;
               case 1:
                  printf("Service:  %s\n", pSvc1->svci1_name);
                  printf("   Status :  0x%hX\n", pSvc1->svci1_status);
                  printf("   Code   :  0x%lX\n", pSvc1->svci1_code);
                  pSvc1++;
                  break;
               case 2:
                  printf("Service:  %s\n", pSvc2->svci2_name);
                  printf("   Status :  0x%hX\n", pSvc2->svci2_status);
                  printf("   Code   :  0x%lX\n", pSvc2->svci2_code);
                  printf("   Text   :  %s\n", pSvc2->svci2_text);
                  pSvc2++;
                  break;
               default:
                  break;
            } // End switch
         } // End for loop
      } // End if successful return

   //====================================================================
   //  NetServiceControl
   //
   //  This API uninstalls the service.
   //====================================================================

      UninstallService(pszServer, pszService);
      free(pbBuffer);
      exit(0);
   }

   //====================================================================
   //  NetServiceInstall
   //
   //  This API installs the service. Reassure the user that installation
   //  is proceeding by using NetServiceControl.
   //====================================================================

   void InstallService (char *pszServer, char *pszService)
   {
      int                   iCount = 0;
      unsigned short        usOldCheck = 0;
      unsigned short        usNewCheck = 0;
      unsigned long         ulWaitTime;
      unsigned              uRet;
      struct service_info_2 StatBuf;

      uRet = NetServiceInstall(pszServer,   // Servername
                     pszService,            // Servicename
                     NULL,                  // No command-line args
                     (char far *) &StatBuf, // Level 2 return buffer
                     sizeof(StatBuf));      // Size of return buffer
      printf("NetServiceInstall %s returned %u\n", pszService, uRet);
      switch (uRet)
      {
         case NERR_Success:
            break;
         /*
          * NERR_BadServiceName and ERROR_FILE_NOT_FOUND can be caused
          * by the absence of the service entry in the LANMAN.INI file
          * or when the entry points to a directory that does not contain
          * the executable service program.
          */
         case NERR_BadServiceName:
         case ERROR_FILE_NOT_FOUND:
            printf("\n%s could not be installed\n", pszService);
            return;

         default:
            return;
      }

      do  // Poll every few seconds.
      {
         uRet = NetServiceControl(pszServer, // Servername
                   pszService,               // Servicename
                   SERVICE_CTRL_INTERROGATE, // Opcode
                   0,                        // Service-specific args
                   (char far * ) &StatBuf,   // Return buffer
                   sizeof(StatBuf) );        // Size of return buffer

         switch (StatBuf.svci2_status & SERVICE_INSTALL_STATE)
         {
            case SERVICE_INSTALLED:
               printf ("\n%s successfully installed\n", pszService);
               return;

            case SERVICE_INSTALL_PENDING:
               printf(".");
               break;

            default:
               printf ("\nService %s failed to install\n", pszService);
               printf ("NetServiceControl returned status %d\n",
                  StatBuf.svci2_status & SERVICE_INSTALL_STATE);
               break;
         }

   /*
          * Check the service timing hints. As long as the hints are
   being
          * changed, assume that the service is still alive.
          */
         if (StatBuf.svci2_code & SERVICE_CCP_QUERY_HINT)
         {
            usNewCheck = (unsigned)
               (StatBuf.svci2_code & SERVICE_CCP_CHKPT_NUM);
            if (usNewCheck != usOldCheck)   // Hints are being changed
            {
               iCount = 0;
               usOldCheck = usNewCheck;
            }
         }

         // Get wait time from data structure.

         ulWaitTime = (long) WAIT_MULT * ( ( StatBuf.svci2_code
                             &  SERVICE_IP_WAIT_TIME )
                             >> SERVICE_IP_WAITTIME_SHIFT);

         // Provide a default wait time if the service doesn't give one.

         if (ulWaitTime == 0)
            ulWaitTime = DEFAULT_WAITTIME;

         // If we've gone maximum amount of time without an update, fail.

         if (((unsigned long)iCount) >= (MAX_POLLS * ulWaitTime))
         {
            printf("\n%s failed to install. ", pszService);
            printf("The service did not report an error.\n");
            break;
         }
         /*
          * DosSleep works only with MS OS/2 or if the application is
   bound.
          * Change to a for() loop to run as a pure MS-DOS application.
          */
         DosSleep(ulWaitTime);
         iCount++;

      } while ((StatBuf.svci2_status & SERVICE_INSTALL_STATE)
                 == SERVICE_INSTALL_PENDING );

      // Successful installation returns true from the switch statement.
      return;
   }

   //====================================================================
   //  NetServiceControl
   //
   //  This API uninstalls the service.
   //====================================================================

   void UninstallService (char *pszServer, char *pszService)
   {
      int                   iCount = 0;
      unsigned              uRet;
      unsigned long         ulWaitTime;
      struct service_info_2 StatBuf;

      uRet = NetServiceControl (pszServer,    // Servername
                     pszService,              // Servicename
                     SERVICE_CTRL_UNINSTALL,  // Opcode
                     0,                       // Service-specific args
                     (char far *) &StatBuf,   // Return buffer
                     sizeof(StatBuf));        // Size of return buffer
      printf("NetServiceControl %s returned %u\n", pszService, uRet);

      do // Poll every few seconds.
      {
         uRet = NetServiceControl(pszServer,
                   pszService,
                   SERVICE_CTRL_INTERROGATE,
                   0,
                   (char far * ) &StatBuf,
                   sizeof(StatBuf));

         switch (StatBuf.svci2_status & SERVICE_INSTALL_STATE)
         {
            case SERVICE_UNINSTALLED:
               printf ("\nService %s successfully stopped\n", pszService);
               return;
            case SERVICE_UNINSTALL_PENDING:  // Keep waiting
               break;
            default:
               printf ("\nService %s failed to stop\n", pszService);
               printf ("NetServiceControl returned status %d\n",
                          StatBuf.svci2_status & SERVICE_INSTALL_STATE);
               break;
         }

   // Get wait time from data structure.

         ulWaitTime = (long) WAIT_MULT * ( ( StatBuf.svci2_code
                                &  SERVICE_IP_WAIT_TIME )
                                >> SERVICE_IP_WAITTIME_SHIFT);

         // Provide a default wait time if the service doesn't give one.

         if (ulWaitTime == 0)
            ulWaitTime = DEFAULT_WAITTIME;

         // If service is not stopped after 20 polls, fail.
         if (((unsigned long)iCount) >= (MAX_POLLS * ulWaitTime))
         {
            printf( "\n%s failed to stop: ", pszService);
            printf(" The service did not report an error.\n");
            break;
         }

         printf (".");     // Display to let user know program is active.
         /*
          * DosSleep works only with MS OS/2 or if the application is
   bound.
          * Change to a for() loop to run as a pure MS-DOS application.
          */
         DosSleep( ulWaitTime );
         iCount++;

      } while ((StatBuf.svci2_status & SERVICE_INSTALL_STATE)
             == SERVICE_UNINSTALL_PENDING);

      // Successful installation returns from the switch statement.
      return; }

   //=================================================================
   //  Usage
   //
   //  Display possible command-line switches for this example.
   //=================================================================

   void Usage(char * pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-v servicename]",
 pszString);
      fprintf(stderr, " [-l level]\n");
      exit(1);
   }









 Use Category

 Use API functions examine or control connections (uses) between workstations
 and servers. They require that the Workstation service be running on the
 local computer. Any user can call these API functions locally, but admin
 privilege is required to call them on a remote server.

 The Use category functions, datatypes, structures, and constants are defined
 in the NETCONS.H, NETERR.H, and USE.H header files. A source program can
 access these definitions by defining the constants INCL_NETERRORS and
 INCL_NETUSE, and including the master header file, LAN.H. For more
 information, see the "Example" section, later in this category.

 These are the Use API functions:


   þ   NetUseAdd

   þ   NetUseDel

   þ   NetUseEnum

   þ   NetUseGetInfo



 Description

 Connections are distinguished from sessions: a session is established the
 first time a workstation makes a connection to a shared resource on the
 server; all further connections between the workstation and the server are
 part of this same session until the session ends.

 Two types of connections can be made: devicename connections (which can only
 be explicit) and universal-naming convention (UNC) connections (which can be
 explicit or implicit).

 NetUseAdd creates a devicename connection or an explicit UNC connection.
 Implicit UNC connections are made by the MS-DOS or MS OS/2 function
 responsible for the connection.

 NetUseAdd establishes an explicit connection between the local computer and
 a resource shared on a server by redirecting a local devicename to the
 sharename of a remote server resource (\\servername\sharename). Once a
 devicename connection is made, users or applications can use the remote
 resource by specifying the local devicename.

 To establish an implicit UNC connection, an application passes the sharename
 of a resource to any function that accepts UNC pathnames (for example, the
 DosOpen function). The function accepts the UNC name and makes a connection
 to the specified sharename. All further requests on this connection require
 the full sharename.

 NetUseDel ends a connection to a shared resource. NetUseEnum enumerates all
 current connections between the local computer and resources on remote
 servers. NetUseGetInfo returns information about a connection to a shared
 resource.

 To understand how these types of connections work, consider the following
 examples:


   þ   Explicit devicename connection.

       Assume that an application redirected the local devicename D: to the
       remote sharename \\DEVELOPMENT\SRCDRV by calling NetUseAdd, as
       follows:

       strcpy (pbBuffer->ui1_local, "D:"); pbBuffer->ui1_remote =
       "\\\\DEVELOPMENT\\SRCDRV"; pbBuffer->ui1_password = pszPassword;
       pbBuffer->ui1_asg_type = USE_DISKDEV; usReturnCode = NetUseAdd (NULL,
       1, pbBuffer, cbBuffer);

       To access files on this resource, an application need only specify the
       redirected devicename and the name of the file, as shown:

       usReturnCode = DosOpen ("D:\\READ.ME", ...);

   þ   Explicit UNC connection.

       Assume that an application redirected a null devicename to the remote
       resource \\DEVELOPMENT\SRCDRV by calling NetUseAdd, as follows:

       pbBuffer-ui1_local = '\0'; pbBuffer-ui1_remote =
       "\\\\DEVELOPMENT\\SRCDRV"; pbBuffer-ui1_password = pszPassword;
       pbBuffer->ui1_asg_type = USE_DISKDEV; usReturnCode = NetUseAdd (NULL,
       1, pbBuffer, cbBuffer);

       To open the READ.ME file on the resource \\DEVELOPMENT\SRCDRV, an
       application can specify just the name of the resource with the
       following command:

       usReturnCode = DosOpen ("\\\\DEVELOPMENT\\SRCDRV\\READ.ME", ...);

       Note that this does not create a new connection to the resource.

   þ   Implicit UNC connection.

       An implicit connection is made by calling a function that accepts UNC
       pathnames and passing the remote sharename as part of a parameter. For
       example, the following call to DosOpen establishes an implicit UNC
       connection to the remote resource \\DEVELOPMENT\SRCDRV and opens
       FILE.1:

       usReturnCode = DosOpen ("\\\\DEVELOPMENT\\SRCDRV\\FILE.1", ...);

       This creates a new connection to the resource.



 Data Structures

 NetUseEnum and NetUseGetInfo use use_info_X data structures, where X is 0 or
 1. NetUseAdd uses only the use_info_1 data structure.


 Use Information (level 0)

 The use_info_0 data structure has this format:

   struct use_info_0 {
       char       ui0_local[DEVLEN+1];
       char       ui0_pad_1;
       char far * ui0_remote;
   };

 where

 ui0_local
   Specifies an ASCIIZ string that contains the local devicename (for
   example, E:, LPT1:, or COM1:) being redirected to the shared resource. The
   constant DEVLEN is defined in the NETCONS.H header file.

 ui0_pad_1
   Aligns the next data structure element on a word boundary.

 ui0_remote
   Points to an ASCIIZ string that specifies the sharename of the remote
   resource being accessed. The string is in the form \\servername\sharename.


 Use Information (level 1)

 The use_info_1 data structure has this format:

   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;
   };

 where

 ui1_local through ui1_remote
   Are the same as the corresponding elements in the use_info_0  data
   structure. For a complete description, see the preceding section.

 ui1_password
   Points to an ASCIIZ string that contains the password needed to establish
   a session between a specific workstation and server. This element is used
   only by NetUseAdd.

 ui1_status
   Specifies the status of the connection. This element is not used by
   NetUseAdd. The USE.H header file defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code          Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USE_OK        0      Connection is valid.
 USE_PAUSED    1      Paused by local workstation.
 USE_SESSLOST  2      Disconnected.
 USE_DISCONN   2      Error occurred (same as USE_SESSLOST).
 USE_NETERR    3      Network error occurred.
 USE_CONN      4      Connection is being made.
 USE_RECONN    5      Reconnecting.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 ui1_asg_type
   Specifies the type of remote resource being accessed. The USE.H header
   file defines these types of resources:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code          Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USE_WILDCARD  -1     Matches the type of the server's shared resources.
                      Wildcards can be used only with NetUseAdd, and only
 Code          Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                     Wildcards can be used only with NetUseAdd, and only
                      when ui1_local is a null string.

 USE_DISKDEV   0      Disk device.

 USE_SPOOLDEV  1      Spooled printer.

 USE_CHARDEV   2      Communication device.

 USE_IPC       3      Interprocess communication (IPC).

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



   The ui1_asg_type element can be set to USE_WILDCARD only for connections
   without a local devicename. A connection that maps a local device to the
   resource must use one of the other four values.

 ui1_refcount
   Specifies how many files, directories, and other processes are open on the
   remote resource. This element is not used by NetUseAdd.

 ui1_usecount
   Specifies how many explicit connections (redirection without a local
   devicename) or implicit UNC connections (redirection without a local
   devicename) are established with the resource.

   If both an explicit and an implicit connection exist between a workstation
   and a server resource, the server ui1_usecount is 1 and the workstation
   ui1_usecount is 2. This element is not used by NetUseAdd.


 NetUseAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUseAdd establishes a connection between a local or null devicename and a
 shared resource by redirecting the local or null (UNC) devicename to the
 shared resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetUseAdd on a remote
 server.


 Syntax

   #define INCL_NETUSE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUseAdd (const char far *  pszServer,
              short             sLevel,
              const char far *  pbBuffer,
              unsigned short    cbBuffer
             );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUseAdd. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail provided; must be 1.

 pbBuffer
   Points to the buffer in which the data to be set is located. The buffer
   should contain a use_info_1 data structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_BAD_DEV_TYPE                66      The network resource type is not
                                           correct.

 ERROR_BAD_NET_NAME                67      The network name was not found.

 ERROR_ALREADY_ASSIGNED            85      The network drive is already
                                           redirected.

 ERROR_INVALID_PASSWORD            86      The password specified is
                                           invalid.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_BadAsgType                   2251    The asg_type is invalid.

 NERR_DeviceIsShared               2252    The device is currently being
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 NERR_LocalDrive                   2405    The drive letter is in use
                                           locally and cannot be used for a
                                           shared resource.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 A local devicename can be redirected to only one shared resource at a time.
 To establish a new direction for a redirected device, an application must
 first delete the existing connection by calling NetUseDel.

 A communication or serial device can be redirected even if it is already
 open. Redirecting the device has no effect on the device handle if it is
 already open, but subsequent openings return a handle to the remote device
 where the local device was redirected.

 If the resource is on a server that has user-level security, and if the
 logon password is not acceptable, you must supply a password the first time
 you make a UNC connection between a local or null devicename and a remote
 resource. Further connections to the same server do not require a password,
 because the password is associated with the same session. If the server has
 share-level security, all connections require a password.

 Whether a server has user-level or share-level security, the password needed
 to access a shared resource can be provided in three ways:


   þ   By a string that specifies the password

   þ   By a null pointer that specifies for LAN Manager to use the same
       password given at logon time

   þ   By a null string that indicates no password is provided


 Special care should be taken with this because with most compilers, when
 near pointers are cast to far pointers, they are assigned the segment
 address of the current data segment. A near null pointer is cast to DS:0x00,
 which is a null string, not a null pointer. For more information, see
 Chapter 1, "Overview of the LAN Manager API."

 NetUseAdd ignores the ui1_status, ui1_refcount, and ui1_usecount elements of
 the use_info_1 data structure.

 If NetUseAdd is called to establish a UNC connection, and a connection
 already exists, the ui1_usecount element of the use_info_1 data structure is
 incremented and the function succeeds, returning NERR_Success.

 If the ui1_asg_type element is set to a different type from the actual type
 of the remote resource, or if the element is set to USE_WILDCARD when the
 ui1_local field is not a null string, the function returns
 ERROR_INVALID_PARAMETER.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Add function calls                Add functions in Chapter 1, "Overview of
                                   the LAN Manager API"

 Disconnecting a device from a     NetUseDel
 shared resource

 Listing all devices redirected    NetUseEnum
 to a shared resource


 NetUseDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUseDel ends a connection to a shared resource.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetUseDel on a remote
 server.


 Syntax

   #define INCL_NETUSE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUseDel (const char far *  pszServer,
              const char far *  pszUseName,
              unsigned short    usForce
             );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUseDel. A null pointer or null string specifies the local
   computer.

 pszUseName
   Points to an ASCIIZ string that specifies the connection to be deleted.
   The connection can be specified as the name of the local redirected device
   or as the UNC sharename of the remote resource.

 usForce
   Specifies the level of force of the disconnection. This acts differently
   for UNC connections than for explicit device or drive connections. The
   USE.H header file defines these possible values for UNC connections:

 Code               Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USE_NOFORCE        0      Decrement the UNC reference count. Disconnect if
                           the connection count is 0,
                           but fail the disconnection if there is any
                           file, directory, or drive open across the
                           connection. Disconnect if the connection
                           is dormant.

 USE_FORCE          1      Remove all UNC connections. Disconnect if the
                           connection count is 0, but fail the
                           disconnection if there is any file, directory,
                           or drive open across the connection. Disconnect
                           if the connection is dormant.

 USE_LOTS_OF_FORCE  2      Remove all UNC connections. Disconnect if the
                           connection count is 0. Force closed any file,
                           directory, or drive open across the connection.
                           Terminate any activity on the connection.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


   The USE.H header file defines these possible values for explicit device or
   drive connections:

 Code               Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USE_NOFORCE        0      Decrement the device reference count. Disconnect
                           if the connection count is 0,
                           but fail the disconnection if there is any
                           file, directory, or drive open across the
                           connection. Disconnect if the connection
                           is dormant.

 USE_FORCE          1      Same as USE_NOFORCE.

 USE_LOTS_OF_FORCE  2      Decrement the device reference count. Disconnect
                           if the connection count is 0. Force closed any
                           file, directory, or drive open across the
                           connection. Terminate any activity on the
                           connection.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_INVALID_DRIVE               15      The drive specified is invalid.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_BAD_DEV_TYPE                66      The network resource type is not
                                           correct.

 ERROR_BAD_NET_NAME                67      The network name was not found.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          shared.

 NERR_UseNotFound                  2250    This network connection does not
                                           exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_OpenFiles                    2401    There are open files or requests
                                           pending on this connection.

 NERR_DevInUse                     2404    The drive specified is the
                                           current drive of an MS OS/2
                                           session.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 The workstation has only one connection to a shared resource on a server, no
 matter how many connections are specified. All uses, both device and UNC,
 are maintained on the one connection. A count of the number and type of
 references to that connection is kept. Any operation that uses the
 connection is maintained until all references to the connection are deleted.


 For example, a workstation could have the drives X: and Y: redirected to the
 same shared resource. This would be one connection with a usage count of 2.
 If a file has been opened     on each remote drive, both file handles remain
 valid even if one of the drives is deleted. Because the other redirected
 drive is still attached, the connection still exists. Attempting to delete
 the last drive will fail, except at force level USE_LOTS_OF_FORCE, because
 there are still two open files on the connection. When both files are
 closed, the final drive can be deleted by a call with force level
 USE_NOFORCE or USE_FORCE.


 NetUseEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUseEnum lists all current connections between the local computer and
 resources on remote servers.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetUseEnum on a remote
 server.


 Syntax

   #define INCL_NETUSE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUseEnum (const char far *      pszServer,
               short                 sLevel,
               char far *            pbBuffer,
               unsigned short        cbBuffer,
               unsigned short far *  pcEntriesRead,
               unsigned short far *  pcTotalAvail
              );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUseEnum. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of use_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of
   connections enumerated in the buffer is returned. This count is valid only
   if NetUseEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of connections is returned. This count is valid only if NetUseEnum returns
   NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing the shared resources on   NetShareEnum
 a server

 Retrieving the status of a local  NetUseGetInfo
 devicename


 NetUseGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUseGetInfo retrieves information about a connection to a shared resource.



 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege is required to successfully execute NetUseGetInfo on a
 remote server.


 Syntax

   #define INCL_NETUSE
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUseGetInfo (const char far *      pszServer,
                  const char far *      pszUseName,
                  short                 sLevel,
                  char far *            pbBuffer,
                  unsigned short        cbBuffer,
                  unsigned short far *  pcbTotalAvail
                 );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUseGetInfo. A null pointer or null string specifies the
   local computer.

 pszUseName
   Points to an ASCIIZ string that specifies which connection is to be
   detailed. The connection can be specified as the name of the local
   redirected device or as the UNC sharename of the remote resource.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a use_info_X data structure, where X is 0 or
   1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetUserGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_UseNotFound                  2250    This network connection does not
                                           exist.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetUseGetInfo returns the ui1_password element as a null string so that
 users or applications cannot determine the password of another user or
 application.

 If pszUseName specifies the UNC sharename of the remote resource, the
 uiX_local element (where X is the level of detail requested) of the returned
 data structure is left blank, even if there is a local drive redirected to
 the specified sharename.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all connections to a      NetUseEnum
 shared resource

 Listing the shared resources on   NetShareEnum
 a server





 Use Category Example

   /*
      NETUSE.C -- a sample program demonstrating NetUse API functions.

      This program requires that you have admin privilege on the
      specified server if a servername parameter is supplied.

         usage:  netuse [-s \\server] [-d device] [-r resource]
                        [-p password] [-a share type]
         where  \\server   = Name of the server. A servername must be
                             preceded by two backslashes (\\).
                device     = Device to be redirected.
                resource   = Name of the remote shared resource.
                password   = Password for the remote shared resource.
                share type = Type of remote resource for ui1_asg_type
   field.

      API               Used to...
      =============     ==================================================
      NetUseAdd         Connect a local device to a remote shared resource
      NetUseEnum        Enumerate all current connections
      NetUseGetInfo     Get information about the new connection
      NetUseDel         Delete the new connection

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETERRORS
   #define     INCL_NETUSE
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   #define  DEFAULT_DEVICE    "X:"     // Device or drive to be redirected
   #define  DEFAULT_RESOURCE  ""       // Remote shared resource to connect
   #define  DEFAULT_ASG_TYPE  0        // Remote shared res is a disk
   device
   #define  LARGE_BUFFER      32768    // Buffer size for Enum call

   void Usage  (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pszServer = "";            // Servername
      char *         pszDevice  = DEFAULT_DEVICE;    // Device to redirect
      char *         pszResource = DEFAULT_RESOURCE; // Remote shared
   resource
      char *         pszUseName;                // Connected to remote
   resource
      char *         pbBuffer;                  // Pointer to data buffer
      char far *     pszPassword = NULL;        // NULL so use logon
   password
      int            iCount;                    // Index counter
      short          sAsgType = DEFAULT_ASG_TYPE;    // Type of remote
   resource
      unsigned short cbBuffer;                  // Size of data buffer
      unsigned short cEntriesRead;              // Count of entries read
      unsigned short cTotalAvail;               // Count of entries available
      API_RET_TYPE   uReturnCode;               // API return code
      struct use_info_0 * pUseInfo0;            // Pointer to Use info;
   level 0
      struct use_info_1 * pUseInfo1;            // Pointer to Use info;
   level 1

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1)))   // Process switches
            {
               case 's':                          // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'd':                          // -d device
                  pszDevice = argv[++iCount];
                  break;
               case 'r':                          // -r resource
                  pszResource = argv[++iCount];
                  break;
               case 'p':                          // -p password
                  pszPassword = (char far *) argv[++iCount];
                  break;
               case 'a':                          // -a share type
                  sAsgType = atoi(argv[++iCount]);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetUseAdd
   //
   //  This API establishes a connection between the specified local
   device
   //  and a remote shared resource. It can establish connections to

   //  directories, spooled devices, or communication devices.
   //
   //  Note: The pszPassword parameter was declared far so that the default
   //  password could be set to a null pointer (0x00:0x00). This means
   that
   //  the logon password is used. A near variable can cause a different
   //  result. Most compilers would convert the pointer to DS:0x00, which
   is
   //  a null string, indicating that no password is provided. This can
   cause
   //  the function to return ERROR_ACCESS_DENIED.
   //========================================================================

      cbBuffer = sizeof(struct use_info_1);       // Allocate data buffer
      pUseInfo1 = (struct use_info_1 *) SafeMalloc(cbBuffer);

      strcpy(pUseInfo1->ui1_local, pszDevice);    // Local devicename
      pUseInfo1->ui1_remote = pszResource;        // Remote sharename
      pUseInfo1->ui1_password = pszPassword;      // Password for share
      pUseInfo1->ui1_asg_type = sAsgType;         // Type of shared resource

      uReturnCode = NetUseAdd(pszServer,          // "" or NULL means
   local
                              1,                  // Level; must be 1
                              (char far *)pUseInfo1, // Pointer to data
   buffer
                              cbBuffer);          // Size of data buffer

      printf("NetUseAdd returned %u \n", uReturnCode);
      free(pUseInfo1);

   //========================================================================
   //  NetUseEnum
   //
   //  This API lists the connections between the local device and the

   //  remote resource.
   //========================================================================

      cbBuffer = LARGE_BUFFER;
      pbBuffer = SafeMalloc(cbBuffer);            // Allocate large buffer

      uReturnCode = NetUseEnum(pszServer,         // "" or NULL means
   local
                               0,                 // Level (0 or 1)
                               pbBuffer,          // Return buffer
                               cbBuffer,          // Size of return buffer
                               &cEntriesRead,     // Count of entries
   read
                               &cTotalAvail);     // Count of total available
      printf("\nNetUseEnum returned %u \n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         pUseInfo0 = (struct use_info_0 *) pbBuffer;
         printf("\nDevice\tRemote resource\n");
         for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
         {
            printf("%-8s%Fs\n", pUseInfo0->ui0_local, pUseInfo0->ui0_remote);
            pUseInfo0++;
         }
      }
      free(pbBuffer);


   //  NetUseGetInfo
   //
   //  This API returns information about a specific connection. The
   name of
   //  the shared device or the local device can be used. It returns
   both
   //  fixed-length and variable-length data. The size of the buffer
   passed to
   //  the API function must be larger than the size of the structure.
   The
   //  extra space is needed for variable-length strings, such as the
   name of
   //  the remote shared device. If you call NetUseGetInfo the first
   time with
   //  a zero-length buffer, the API function returns the needed buffer
   size.

      // If the devicename is null, use the name of the remote shared
   device.
      if (pszDevice[0] == '\0')
         pszUseName = pszResource;
      else
         pszUseName = pszDevice;

      uReturnCode = NetUseGetInfo(pszServer,      // "" or NULL means
   local
                                  pszUseName,     // Devicename or sharename
                                  1,              // Level (0 or 1)
                                  NULL,           // Return buffer
                                  0,              // Size of return buffer
                                  &cbBuffer);     // Count of bytes available

      if (uReturnCode != NERR_BufTooSmall)
         printf("\nNetUseGetInfo with zero buffer returned %u\n",
 uReturnCode);
      else

   {
         pbBuffer = SafeMalloc(cbBuffer);

   uReturnCode = NetUseGetInfo(pszServer,   // "" or NULL
   means local
                                   pszUseName,    // Devicename or sharename
                                   1,             // Level (0 or 1)
                                   pbBuffer,      // Return buffer
                                   cbBuffer,      // Size of return buffer
                                   &cTotalAvail); // Count of bytes available

         printf("\nNetUseGetInfo with %hu byte buffer returned %u\n",
                    cTotalAvail, uReturnCode);

         if (uReturnCode == NERR_Success)        // Display results
         {
            pUseInfo1 = (struct use_info_1 *) pbBuffer;
            printf("   Local device   : %s\n",  pUseInfo1->ui1_local);
            printf("   Remote device  : %Fs\n", pUseInfo1->ui1_remote);
            printf("   Status         : %hu\n", pUseInfo1->ui1_status);
            printf("   Remote type    : %hu\n", pUseInfo1->ui1_asg_type);
            printf("   Open resources : %hu\n", pUseInfo1->ui1_refcount);
            printf("   Use count      : %hu\n", pUseInfo1->ui1_usecount);
         }
         free(pbBuffer);
      }

   //========================================================================
   //  NetUseDel
   //
   //  This API deletes the connection added by the previous NetUseAdd
   call.
   //  The USE_FORCE flag indicates not to close the connection if there
   //  are files open. The USE_LOTS_OF_FORCE flag forces the connection

   //  to be deleted regardless and can cause data to be lost.
   //======================================================================

      uReturnCode = NetUseDel(pszServer,          // "" or NULL means
   local
                              pszUseName,         // Devicename or sharename
                              USE_FORCE);         // Type of disconnection

      printf("\nNetUseDel of %s returned %u \n", pszUseName, uReturnCode);
      exit(0);
   }

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-d device]"\
                      " [-r resource] [-p password]\n", pszProgram);
      exit(1);
   }







 User Category

 User API functions control a user's account in the user account subsystem
 (UAS) database.

 The User API functions require that the UAS be started. The UAS is started
 automatically as part of the boot process on computers with the
 high-performance file system 386 (HPFS386) with local security enabled. On
 computers that do not have HPFS386, or on HPFS computers without local
 security, the UAS is started when the Workstation service is started,
 provided a valid user accounts database file exists.

 The User category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, and ACCESS.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETUSER, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 category.

 These are the User API functions:


   þ   NetUserAdd

   þ   NetUserDel

   þ   NetUserEnum

   þ   NetUserGetGroups

   þ   NetUserGetInfo

   þ   NetUserModalsGet

   þ   NetUserModalsSet

   þ   NetUserPasswordSet

   þ   NetUserSetGroups

   þ   NetUserSetInfo

   þ   NetUserValidate2



 Description

 Each user or application that accesses resources must have an account in the
 UAS database. The UAS uses this user account to verify that the user or
 application has permission to connect to a resource. For a description of
 the information stored in the user account, see the section "User Account
 Information (level 2)," later in this category. To set up a user account,
 call NetUserAdd.

 When a user or an application requests access to a shared resource on a
 server, LAN Manager checks for an appropriate account. NetUserValidate2
 checks for a valid account with a particular username and password
 combination. NetUserGetInfo retrieves full account details.

 LAN Manager then checks the user's privilege level. If the user has admin
 privilege, the request to access a resource is immediately accepted.
 Otherwise, processing continues. (Admin privilege allows the broadest access
 to the domain, giving the user permission to execute all administrative
 functions, and allowing complete access to all available resources.)

 If the user does not have admin privilege, LAN Manager checks the resource's
 access permissions to see if the user has the proper permissions to use that
 particular resource. For more information about permissions, see the Access
 Permissions category API functions.

 Each time NetUserAdd establishes an account, LAN Manager automatically adds
 the username to one of the special groups admins, users, or guests. The
 group to which the username is added depends on the new user's level of
 privilege. Users automatically inherit all access permissions assigned to
 the special group to which they are added.

 NetUserEnum can be used to list all user accounts on a server.

 An application can change a user's privilege level by calling
 NetUserSetInfo. It can also change the user's resource access privileges by
 modifying that user's groups (for more information, see the Group category
 API functions). Individually assigned user privileges take precedence over
 group privileges. An application can verify the groups to which a user
 belongs by calling NetUserGetGroups, which returns a list of groupnames. To
 find out how to change individual access permission settings, see the Access
 Permissions category API functions.

 When a user account is no longer needed, use NetUserDel to delete the
 account from the server. Once the account is removed, the user can no longer
 access the server, except by using the guest account.

 Because the user's password is confidential, it is not returned by
 NetUserEnum or NetUserGetInfo; instead, a string of space characters
 (blanks) is substituted for any password requested. The password is
 initially assigned when NetUserAdd is called. NetUserSetInfo sets the
 password and other elements of a user account. Users or applications can use
 NetUserPasswordSet to change a password (they must supply the current
 password).

 NetUserModalsGet and NetUserModalsSet examine and modify the modal settings
 for accounts in the UAS database (modal settings are global parameters that
 affect every account in the database, for example, the minimum allowable
 password length). All modal settings can be altered by calling
 NetUserModalsSet. Most of the modals can also be altered by using the net
 accounts command. For more information, see your LAN Manager administrator's
 manual(s).

 All User API functions executed on a remote server (except NetUserModalsGet
 and NetUserModalsSet) require that the server have user-level security.
 Attempting to execute one of the User API functions on a remote server that
 has share-level security causes ERROR_NOT_SUPPORTED to be returned.


 Data Structures

 NetUserGetInfo can be called at levels 0, 1, 2, 10, and 11; it returns a
 user_info_X data structure, where X is the level specified. The user_info_X
 data structures at levels 10 and 11 are supplied so non-admin users can get
 user information.

 NetUserSetInfo can be called at levels 1 and 2 to set individual user
 information. It uses the user_info_X data structure, where X is 1 or 2.

 NetUserModalsGet and NetUserModalsSet can be called at levels 1 and 2. They
 use the user_modals_info_X data structure, where X is the level number, to
 specify the modal information for all accounts in the UAS database.

 NetUserGetGroups and NetUserSetGroups use the group_info_0 data structure to
 retrieve and modify the list of groups to which a user belongs.

 NetUserValidate2 uses a user_logon_req_1 data structure as input. It returns
 a user_logon_info_1 data structure when successful.


 User Account Information (level 0)

 The user_info_0 data structure has this format:

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

 where

 usri0_name
   Specifies the name of the user whose account will be altered. The constant
   UNLEN is defined in the NETCONS.H header file.


 User Account Information (level 1)

 The user_info_1 data structure has this format:

   struct user_info_1 {
       char            usri1_name[UNLEN+1];
       char            usri1_pad_1;
       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;
   };

 where

 usri1_name
   Specifies the name of the user whose account will be accessed. The
   constant UNLEN is defined in the NETCONS.H header file.

 usri1_pad_1
   Aligns the next data structure element on a word boundary.

 usri1_password
   Specifies the password of the user specified by usri1_name. The password
   length can contain as many as PWLEN bytes, as defined in the NETCONS.H
   header file. To maintain password security, NetUserEnum and NetUserGetInfo
   return a string of space characters (blanks).

   To allow room for the encrypted version of the password to be transmitted
   over the network, the usri1_password element is longer than PWLEN bytes.
   When setting the user's password, check its length against PWLEN, not
   against ENCRYPTED_PWLEN.

 usri1_password_age
   Specifies how many seconds have elapsed since usri1_password was last
   changed. NetUserAdd and NetUserSetInfo calls ignore this element.

 usri1_priv
   Specifies the level of privilege assigned to the user specified by
   usri1_name. The ACCESS.H header file defines these possible values:

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USER_PRIV_GUEST  0      Guest privilege.
 USER_PRIV_USER   1      User privilege.
 USER_PRIV_ADMIN  2      Admin privilege.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 usri1_home_dir
   Points to an ASCIIZ string that contains the pathname of the home
   directory of the user specified by usri1_name. This value can be a null
   string, a local absolute path, or a UNC path. It can have as many as
   PATHLEN characters, as defined in the NETCONS.H. header file.

 usri1_comment
   Points to an ASCIIZ string that contains a comment. This field can be a
   null string, or it can have as many as MAXCOMMENTSZ characters before the
   terminating NUL. The constant MAXCOMMENTSZ is defined in the NETCONS.H
   header file.

 usri1_flags
   Specifies an unsigned short integer that contains bits that determine
   several features. The ACCESS.H header file defines these possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Bit(s)  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 UF_SCRIPT                         0       If 1, the logon script is
                                           executed. Must be 1 for LAN
                                           Manager 2.0.

 Code                              Bit(s)  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 UF_ACCOUNTDISABLE                 1       If 1, the user's account is
                                           disabled.

 UF_DELETE_PROHIBITED              2       If 1, deleting is prohibited.

 UF_HOMEDIR_REQUIRED               3       If 1, the home directory is
                                           required.

 Ä                                 4       Reserved; must be 0.

 UF_PASSWORD_NOTREQD               5       If 1, no password is required.

 UF_PASSWORD_CANT_CHANGE           6       If 1, the user cannot change the
                                           password.

 Ä                                 7-15    Reserved; must be 0.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Bit(s)  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 usri1_script_path
   Points to an ASCIIZ string that specifies the path for the user's logon
   script file. The script file can be a .CMD file (MS OS/2), a .EXE file (MS
   OS/2 and MS-DOS), a .BAT file (MS-DOS), or a .PRO file (LAN Manager
   profile), or it can have no extension. Files with no extension are assumed
   to be .CMD or .BAT files.

   The script path must be specified relative to the Netlogon service SCRIPTS
   path. It can have as many as PATHLEN characters before the terminating
   NUL. The constant PATHLEN is defined in the NETCONS.H header file. A null
   string indicates no logon script exists.


 User Account Information (level 2)

 The user_info_2 data structure has this format:

   struct user_info_2 {
       char                 usri2_name[UNLEN+1];
       char                 usri2_pad_1;
       char                 usri2_password[ENCRYPTED_PWLEN];
       long                 usri2_password_age;
       unsigned short       usri2_priv;
       char far *           usri2_home_dir;
       char far *           usri2_comment;
       unsigned short       usri2_flags;
       char far *           usri2_script_path;
       unsigned long        usri2_auth_flags;
       char far *           usri2_full_name;
       char far *           usri2_usr_comment;
       char far *           usri2_parms;
       char far *           usri2_workstations;
       long                 usri2_last_logon;
       long                 usri2_last_logoff;
       long                 usri2_acct_expires;
       unsigned long        usri2_max_storage;
       unsigned short       usri2_units_per_week;
       unsigned char far *  usri2_logon_hours;
       unsigned short       usri2_bad_pw_count;
       unsigned short       usri2_num_logons;
       char far *           usri2_logon_server;
       unsigned short       usri2_country_code;
       unsigned short       usri2_code_page;
   };

 where

 usri2_name through usri2_script_path
   Are the same as the corresponding elements of the user_info_1 data
   structure. For a complete description, see the preceding section.

 usri2_auth_flags
   Specifies an unsigned long integer that contains bits that specify the
   user's operator privileges. The ACCESS.H header file defines these
   possible values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code            Bit(s)  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AF_OP_PRINT     0       If 1, print operator privilege is enabled.
 AF_OP_COMM      1       If 1, comm operator privilege is enabled.
 AF_OP_SERVER    2       If 1, server operator privilege is enabled.
 AF_OP_ACCOUNTS  3       If 1, accounts operator privilege is enabled.
 Ä               4-31    Reserved; must be 0.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 usri2_full_name
   Points to an ASCIIZ string that contains the full name of the user. This
   value can be a null string, or it can have as many as MAXCOMMENTSZ
   characters before the terminating NUL. The constant MAXCOMMENTSZ is
   defined in the NETCONS.H header file.

 usri2_usr_comment
   Points to an ASCIIZ string that contains a user comment. This value can be
   a null string, or it can have as many as MAXCOMMENTSZ characters before
   the terminating NUL. The constant MAXCOMMENTSZ is defined in the NETCONS.H
   header file.

 usri2_parms
   Points to an ASCIIZ string that is set aside for use by applications. It
   can have as many as MAXCOMMENTSZ characters before the terminating NUL.
   The constant MAXCOMMENTSZ is defined in the NETCONS.H header file. LAN
   Manager does not use this element.

 usri2_workstations
   Points to an ASCIIZ string that contains the names of workstations from
   which the user can log on. As many as eight workstations can be specified;
   the names must be separated by commas (,). A null string indicates that
   there is no restriction. To disable logons from all workstations to this
   account, set the UF_ACCOUNTDISABLE bit in the usriX_flags element.

 usri2_last_logon
   Specifies when the last logon occurred. This value is stored as the number
   of seconds elapsed since 00:00:00, January 1, 1970. This element is
   ignored in NetUserAdd and NetUserSetInfo calls.

 usri2_last_logoff
   Specifies when the last logoff occurred. This value is stored as the
   number of seconds elapsed since 00:00:00, January 1, 1970. A value of 0
   means that the last logoff time is unknown. This element is ignored in
   NetUserAdd and NetUserSetInfo calls.

 usri2_acct_expires
   Specifies when the account will expire. This value is stored as the number
   of seconds elapsed since 00:00:00, January 1, 1970. A value of
   TIMEQ_FOREVER, as defined in the ACCESS.H header file, indicates that the
   account never expires.

 usri2_max_storage
   Specifies the maximum amount of disk space the user can use. A value of
   USER_MAXSTORAGE_UNLIMITED, as defined in the ACCESS.H header file,
   indicates that there is no restriction.

 usri2_units_per_week
   Specifies the number of equal-length time units into which the week is
   divided in order to compute the length of the bit string in
   usri2_logon_hours. This value must be UNITS_PER_WEEK for LAN Manager 2.0.
   This element is ignored in NetUserAdd and NetUserSetInfo calls.

 usri2_logon_hours
   Points to a 21-byte (168 bits) bit string that specifies the times during
   which the user can log on. Each bit represents a unique hour in the week.
   The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit
   1, word 0) is Sunday, 1:00 to 1:59; and so on. A null pointer in this
   element for NetUserAdd calls means that there is no time restriction. A
   null pointer in this element for NetUserSetInfo calls means that no change
   is to be made.

 usri2_bad_pw_count
   Specifies the number of attempts to log on to this account using an
   incorrect password. A value of 0xFFFFFFFF indicates that the value is
   unknown. This element is ignored in NetUserAdd and NetUserSetInfo calls.

 usri2_num_logons
   Counts the number of successful attempts to log on to this account. A
   value of 0xFFFFFFFF indicates that the value is unknown. This element is
   ignored in NetUserAdd and NetUserSetInfo calls.

 usri2_logon_server
   Points to an ASCIIZ string that contains the name of the server to which
   logon requests are sent. Servernames should be preceded by two backslashes
   (\\). A servername of an asterisk (\\*) indicates that the logon request
   can be handled by any logon server. A null string indicates that requests
   are sent to the domain controller.

 usri2_country_code
   Specifies the MS OS/2 country code for the user's language of choice.

 usri2_code_page
   Specifies the MS OS/2 code page for the user's language of choice.


 User Account Information (level 10)

 The user_info_10 data structure has this format:

   struct user_info_10 {
       char        usri10_name[UNLEN+1];
       char        usri10_pad_1;
       char far *  usri10_comment;
       char far *  usri10_usr_comment;
       char far *  usri10_full_name;
   };

 where

 usri10_name through usri10_full_name
   Are the same as the corresponding elements of the user_info_2 data
   structure. For a complete description, see the preceding section.


 User Account Information (level 11)

 The user_info_11 data structure has this format:

   struct user_info_11 {
       char                 usri11_name[UNLEN+1];
       char                 usri11_pad_1;
       char far *           usri11_comment;
       char far *           usri11_usr_comment;
       char far *           usri11_full_name;
       unsigned short       usri11_priv;
       unsigned long        usri11_auth_flags;
       long                 usri11_password_age;
       char far *           usri11_home_dir;
       char far *           usri11_parms;
       long                 usri11_last_logon;
       long                 usri11_last_logoff;
       unsigned short       usri11_bad_pw_count;
       unsigned short       usri11_num_logons;
       char far *           usri11_logon_server;
       unsigned short       usri11_country_code;
       char far *           usri11_workstations;
       unsigned long        usri11_max_storage;
       unsigned short       usri11_units_per_week;
       unsigned char far *  usri11_logon_hours;
       unsigned short       usri11_code_page;
   };

 where

 usri11_name through usri11_code_page
   Are the same as the corresponding elements of the user_info_2 and
   user_info_10 data structures. For a complete description, see "User
   Account Information (level 2)," earlier in this category.


 User Modals Information (level 0)

 The user_modals_info_0 data structure has this format:

   struct user_modals_info_0 {
       unsigned short  usrmod0_min_passwd_len;
       unsigned long   usrmod0_max_passwd_age;
       unsigned long   usrmod0_min_passwd_age;
       unsigned long   usrmod0_force_logoff;
       unsigned short  usrmod0_password_hist_len;
       unsigned short  usrmod0_reserved1;
   };

 where

 usrmod0_min_passwd_len
   Specifies the minimum allowable password length. Valid values for this
   element are 0 through PWLEN, as defined in the NETCONS.H header file.

 usrmod0_max_passwd_age
   Specifies the maximum allowable password age (in seconds). A value of
   TIMEQ_FOREVER, as defined in the ACCESS.H header file, indicates that the
   password never expires. The minimum valid value for this element is
   ONE_DAY, as defined in the ACCESS.H header file. The value specified must
   be greater than or equal to the value for usrmod0_min_passwd_age.

 usrmod0_min_passwd_age
   Specifies the minimum elapsed time (in seconds) between when the password
   was last changed and when it can be changed again. A value of 0 indicates
   that no delay is required between password updates. The value specified
   must be less than or equal to the value for usrmod0_max_passwd_age.

 usrmod0_force_logoff
   Specifies the amount of time (in seconds) between the end of the valid
   logon time and the time when the user is forced off the network. A value
   of TIMEQ_FOREVER, as defined in the ACCESS.H header file, indicates that
   the user is never forced off. A value of 0 indicates that the user will be
   forced off immediately when the valid logon time expires.

 usrmod0_password_hist_len
   Specifies the length of password history maintained. A new password cannot
   match any of the previous usrmod0_password_hist_len passwords. Valid
   values for this element are 0 through DEF_MAX_PWHIST, as defined in the
   ACCESS.H header file.

 usrmod0_reserved1
   Reserved; must be 0.


 User Modals Information (level 1)

 The user_modals_info_1 data structure has this format:

   struct user_modals_info_1 {
       unsigned short  usrmod1_role;
       char far *      usrmod1_primary;
   };

 where

 usrmod1_role
   Specifies the role of the logon server. The ACCESS.H header file defines
   these possible values:

 Code                 Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 UAS_ROLE_STANDALONE  0      Logon server is a standalone.
 UAS_ROLE_MEMBER      1      Logon server is a member.
 UAS_ROLE_BACKUP      2      Logon server is a backup.
 UAS_ROLE_PRIMARY     3      Logon server is a domain controller.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   If the Netlogon service is not being used, the usrmod1_role element should
   be set to UAS_ROLE_STANDALONE. For more information about the Netlogon
   service, see your LAN Manager administrator's manual(s).

 usrmod1_primary
   Specifies the name of the domain controller where the primary copy of the
   UAS database file is stored.


 Group Membership Information (level 0)

 The group_info_0 data structure has this format:

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

 where

 grpi0_name
   Specifies the group to which a user belongs. The constant GNLEN is defined
   in the NETCONS.H header file.


 User Validation Information (level 1)

 A pointer to a user_logon_req_1 data structure is passed to
 NetUserValidate2. The user_logon_req_1 data structure has this format:

   struct user_logon_req_1 {
       char        usrreq1_name[UNLEN+1];
       char        usrreq1_pad_1;
       char        usrreq1_password[SESSION_PWLEN];
       char far *  usrreq1_workstation;
   };

 where

 usrreq1_name
   Specifies the name of the user whose account is queried. The constant
   UNLEN is defined in the NETCONS.H header file.

 usrreq1_pad_1
   Aligns the next data structure element on a word boundary.

 usrreq1_password
   Specifies the password of the user specified by usrreq1_name. The password
   can have as many as PWLEN non-NUL bytes, and must be followed by a
   terminating NUL character. The array is SESSION_PWLEN bytes long to allow
   for password encryption. The constants PWLEN and SESSION_PWLEN are defined
   in the NETCONS.H header file.

 usrreq1_workstation
   Points to an ASCIIZ string that contains the name of the workstation for
   which the user is requesting validation. A null string indicates the local
   workstation; a null pointer indicates to ignore the workstation.


 Logon Information (level 1)

 NetUserValidate2 returns a user_logon_info_1 structure. The
 user_logon_info_1 data structure has this format:

   struct user_logon_info_1 {
       unsigned short  usrlog1_code;
       char            usrlog1_eff_name[UNLEN+1];
       char            usrlog1_pad_1;
       unsigned short  usrlog1_priv;
       unsigned long   usrlog1_auth_flags;
       unsigned short  usrlog1_num_logons;
       unsigned short  usrlog1_bad_pw_count;
       unsigned long   usrlog1_last_logon;
       unsigned long   usrlog1_last_logoff;
       unsigned long   usrlog1_logoff_time;
       unsigned long   usrlog1_kickoff_time;
       long            usrlog1_password_age;
       unsigned long   usrlog1_pw_can_change;
       unsigned long   usrlog1_pw_must_change;
       char far *      usrlog1_computer;
       char far *      usrlog1_domain;
       char far *      usrlog1_script_path;
       unsigned long   usrlog1_reserved1;
   };

 where

 usrlog1_code
   Specifies the logon code used in conjunction with the code returned by the
   API function. For a list of the specific values, see the "Return Codes"
   section of the NetUserValidate2 description.

 usrlog1_eff_name
   Specifies the name of the account to which the user was logged on. The
   constant UNLEN is defined in the NETCONS.H header file.

 usrlog1_pad_1
   Aligns the next data structure element on a word boundary.

 usrlog1_priv
   Specifies the user's privilege level. The ACCESS.H header file defines
   these possible values:

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USER_PRIV_GUEST  0      Guest privilege.
 USER_PRIV_USER   1      User privilege.
 USER_PRIV_ADMIN  2      Admin privilege.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 usrlog1_auth_flags
   Specifies a bitmap of account operator privileges. The ACCESS.H header
   file defines these bits:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code            Bit(s)  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AF_OP_PRINT     0       Print operator.
 AF_OP_COMM      1       Comm operator.
 AF_OP_SERVER    2       Server operator.
 AF_OP_ACCOUNTS  3       Accounts operator.
 Ä               4-31    Reserved.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 usrlog1_num_logons
   Specifies the number of times this user is logged on. A value of -1 means
   the number of logons is unknown.

 usrlog1_bad_pw_count
   Specifies the number of attempts to log on to this account using an
   incorrect password since the last successful logon.

 usrlog1_last_logon
   Specifies the time the user last logged on. This value is stored as the
   number of seconds elapsed since 00:00:00, January 1, 1970.

 usrlog1_last_logoff
   Specifies the time the user last logged off. This value is stored as the
   number of seconds elapsed since 00:00:00, January 1, 1970. A value of 0
   means that the last logoff time is unknown.

 usrlog1_logoff_time
   Specifies the time the user should log off. This value is stored as the
   number of seconds elapsed since 00:00:00, January 1, 1970. A value of
   USER_NO_LOGOFF means the user never has to log off. The constant
   USER_NO_LOGOFF is defined in the ACCESS.H header file.

 usrlog1_kickoff_time
   Specifies the time the user will be logged off by the system. This value
   is stored as the number of seconds elapsed since 00:00:00, January 1,
   1970. A value of USER_NO_LOGOFF means the user will not be logged off by
   the system. The constant USER_NO_LOGOFF is defined in the ACCESS.H header
   file.

 usrlog1_password_age
   Specifies how many seconds have elapsed since the user password was last
   changed.

 usrlog1_pw_can_change
   Specifies the time when the user is allowed to change the password. This
   value is stored as the number of seconds elapsed since 00:00:00, January
   1, 1970. A value of TIMEQ_FOREVER means the user can never change the
   password. The constant TIMEQ_FOREVER is defined in the ACCESS.H header
   file.

 usrlog1_pw_must_change
   Specifies the time when the user must change the password. This value is
   stored as the number of seconds elapsed since 00:00:00, January 1, 1970.

 usrlog1_computer
   Specifies which server validated the user's logon.

 usrlog1_domain
   Specifies in which domain the user is logged on.

 usrlog1_script_path
   Specifies the relative path to the user logon script.

 usrlog1_reserved1
   Reserved; the value is undefined. This element should not be used.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Access permissions for a shared   Access Permissions Category and Share
 resource                          Category

 Logon scripts                     LAN Manager administrator's manual(s)

 Netlogon service                  LAN Manager administrator's manual(s)


 NetUserAdd
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserAdd establishes an account for a user and assigns a password and a
 privilege level.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserAdd on a remote server or on a computer that has local
 security enabled. Admin privilege is required to add an admin privilege
 account.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserAdd (const char far *  pszServer,
               short             sLevel,
               char far *        pbBuffer,
               unsigned short    cbBuffer
              );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserAdd. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail (1 or 2) provided.

 pbBuffer
   Points to the buffer that contains the data to be added. The buffer should
   contain a user_info_1 (level 1 call) or a user_info_2 (level 2 call) data
   structure. This buffer must be able to be both read and written to, even
   though NetUserAdd does not change the contents.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PASSWORD            86      The password specified is
                                           invalid.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_BadUsername                  2202    The username or groupname is
                                           invalid.

 NERR_GroupExists                  2223    The groupname already exists.

 NERR_UserExists                   2224    The user account already exists.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_UserExists                   2224    The user account already exists.

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFNoRoom                    2228    The user accounts database is
                                           full.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_PasswordTooShort             2245    The password is too short.

 NERR_InvalidDatabase              2247    The user accounts database file,
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetUserAdd supports level 1 and level 2 data structures. Level 1 calls
 initialize the additional fields in the user_info_2 data structure to their
 default values. Subsequent NetUserSetInfo calls can change these values.
 These are the default values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Element                           Default Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 usri2_auth_flags                  None (0).

 usri2_full_name                   usri1_name

 usri2_usr_comment                 None (null string).

 usri2_parms                       None (null string).

 usri2_workstations                All (null string).

 usri2_acct_expires                Never (TIMEQ_FOREVER).

 usri2_max_storage                 Unlimited (USER_MAXSTORAGE_UNLIMITED).

 usri2_logon_hours                 Logon allowed at any time (each element
 Element                           Default Value
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
usri2_logon_hours                 Logon allowed at any time (each element
                                   0xFF;
                                   all bits set to 1).

 usri2_logon_server                Domain controller (null string).

 usri2_country_code                Current country_code on the server.

 usri2_code_page                   0

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Assigning access permissions      Access Permissions Category

 Logon scripts                     LAN Manager administrator's manual(s)

 Modifying a user's group          Group Category
 memberships


 NetUserDel
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserDel removes an account from the user accounts database, ending access
 to all resources in the system for that user or application.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserDel on a remote server or on a computer that has local
 security enabled. Admin privilege is required to delete an admin privilege
 account.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserDel (const char far *  pszServer,
               char far *        pszUserName
              );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserDel. A null pointer or null string specifies the local
   computer.

 pszUserName
   Points to an ASCIIZ string that specifies which user account to delete.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          shared.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_UserLogon                    2231    The user currently has a session
                                           with the server.

 NERR_InvalidDatabase              2247    The user accounts database file,
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_LastAdmin                    2452    The operation is not allowed on
                                           the last account with admin
                                           privilege.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Deleting an account also deletes all references to that account in all
 resource access control lists (ACLs) on the server.

 If the account being deleted is the last admin account in the database,
 NetUserDel fails and returns NERR_LastAdmin.


 NetUserEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserEnum returns information about all user accounts on a server.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserEnum at level 1 or level 2 on a remote server or on a
 computer that has local security enabled. No special privilege is required
 for level 0 or level 10 calls.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserEnum (const char far *      pszServer,
                short                 sLevel,
                char far *            pbBuffer,
                unsigned short        cbBuffer,
                unsigned short far *  pcEntriesRead,
                unsigned short far *  pcTotalAvail
               );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserEnum. A null pointer or null string specifies the local
   computer.

 sLevel
   Specifies the level of detail (0, 1, 2, or 10) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of user_info_X data structures,
   where X is 0, 1, 2, or 10, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of the number of
   users enumerated in the buffer is returned. This count is valid only if
   NetUserEnum returns NERR_Success or ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of users is returned. This count is valid only if NetUserEnum returns
   NERR_Success or ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 To maintain password security, the usriX_password element returned in each
 data structure contains a string of space characters (blanks).


 NetUserGetGroups
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserGetGroups lists all groups in the user account subsystem (UAS)
 database to which a particular user belongs.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is needed to successfully
 execute NetUserGetGroups on a remote server or on a computer that has local
 security enabled, except when users request details about their own
 accounts.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserGetGroups (const char far *      pszServer,
                     const char far *      pszUserName,
                     short                 sLevel,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcEntriesRead,
                     unsigned short far *  pcTotalAvail
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserGetGroups. A null pointer or null string specifies the
   local computer.

 pszUserName
   Points to an ASCIIZ string that contains the username to search for in
   each group.

 sLevel
   Specifies the level of detail requested; must be 0.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of group_info_0 data structures.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer in which a count of group_info_0 data
   structures in the buffer is returned. This count is valid only if
   NetUserGetGroups returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 pcTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of groups to which the user belongs is returned. This count is valid only
   if NetUserGetGroups returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_UserNotFound                 2221    The username was not found.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_UserNotFound                 2221    The username was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.



 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Similar to an Enum function, NetUserGetGroups returns a sequence of
 group_info_0 data structures, specifying the names of all groups to which
 the user belongs.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all users in a group      NetGroupGetUsers


 NetUserGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserGetInfo retrieves information about a particular account on a server.



 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserGetInfo at levels 1, 2, or 11 on a remote server or on a
 computer that has local security enabled. No special privilege is required
 for level 0 or level 10 calls, or for level 11 calls when users request
 details about their own accounts.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserGetInfo (const char far *      pszServer,
                   char far *            pszUserName,
                   short                 sLevel,
                   char far *            pbBuffer,
                   unsigned short        cbBuffer,
                   unsigned short far *  pcbTotalAvail
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserGetInfo. A null pointer or null string specifies the
   local computer.

 pszUserName
   Points to an ASCIIZ string that contains the username about which to get
   account information.

 sLevel
   Specifies the level of detail (0, 1, 2, 10, or 11) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a user_info_X data structure, where X is 0, 1,
   2, 10, or 11, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetUserGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.


 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 To maintain password security, the usriX_password element of the data
 structure is always returned as a string of space characters (blanks).


 NetUserModalsGet
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserModalsGet gets global information for all users and groups in the
 user account subsystem (UAS) database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserModalsGet at level 1 on a remote server or on a computer that
 has local security enabled. No special privilege is required for level 0
 calls.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserModalsGet (const char far *      pszServer,
                     short                 sLevel,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcbTotalAvail
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserModalsGet. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a user_modals_info_X data structure, where X
   is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetUserModalsGet returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetUserModalsGet can be called even when the UAS is not active, provided
 that a valid NET.ACC file exists.


 NetUserModalsSet
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserModalsSet sets global information for all users and groups in the
 user account subsystem (UAS) database.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserModalsSet on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserModalsSet (const char far *  pszServer,
                     short             sLevel,
                     char far *        pbBuffer,
                     unsigned short    cbBuffer,
                     short             sParmNum
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserModalsSet. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0 or 1) provided.

 pbBuffer
   Points to the data to be set.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to reset all the information or to change only a part of
   it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a
   user_modals_info_0 (level 0 call) or user_modals_info_1 (level 1 call)
   data structure. If sParmNum is any other defined value, only one element
   of the modal information is changed, and pbBuffer must point to a valid
   value for that element.

   The ACCESS.H header file defines these possible values for sParmNum and
   the associated elements that must be supplied in the data buffer:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                     Value  Element of modals_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMUM_ALL               0      All elements.
 MODAL0_PARMNUM_MIN_LEN   1      usrmod0_min_passwd_len
 MODAL0_PARMNUM_MAX_AGE   2      usrmod0_max_passwd_age
 MODAL0_PARMNUM_MIN_AGE   3      usrmod0_min_passwd_age
 MODAL0_PARMNUM_FORCEOFF  4      usrmod0_force_logoff
 MODAL0_PARMNUM_HISTLEN   5      usrmod0_passwd_hist_len
 MODAL1_PARMNUM_ROLE      1      usrmod1_role
 MODAL1_PARMNUM_PRIMARY   2      usrmod1_primary
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidAPI                   2142    The requested API is not
                                           supported on the remote server.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_InvalidUASOp                 2451    The operation is not allowed
                                           while the Netlogon service is
                                           running.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetUserModalsSet can be called even when the UAS is not active, provided
 that a valid NET.ACC file exists.

 The Netlogon service must not be running when calling NetUserModalsSet at
 level 1.


 NetUserPasswordSet
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserPasswordSet changes the password stored in a user's account. It
 changes the old password only if it matches the user's current password and
 if the new password is not the same as any of the previous passwords
 specified in the usrmod0_password_hist_len element of the user_modals_info_0
 data stucture.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 No special privilege is required to successfully execute NetUserPasswordSet.



 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserPasswordSet (const char far *  pszServer,
                       char far *        pszUserName,
                       char far *        pszOldPassword,
                       char far *        pszNewPassword
                      );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserPasswordSet. A null pointer or null string specifies the
   local computer.

 pszUserName
   Points to an ASCIIZ string that contains the name of the user whose
   password is to be changed.

 pszOldPassword
   Points to an ASCIIZ string that specifies the user's current password.

 pszNewPassword
   Points to an ASCIIZ string that specifies a new password for the user. The
   password can have as many as PWLEN characters. The constant PWLEN is
   defined in the NETCONS.H header file.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_INVALID_PASSWORD            86      The password specified is
                                           invalid.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_BadPassword                  2203    The password is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_UserNotFound                 2221    The username was not found.

 NERR_NotPrimary                   2226    The specified server is not the
                                           primary domain controller, so
                                           its UAS database cannot be
                                           updated.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFNoRoom                    2228    The user accounts database is
                                           full.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_AccountExpired               2239    The user account has expired.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_PasswordCantChange           2243    The user's password cannot be
                                           changed.

 NERR_PasswordHistConflict         2244    The password cannot be used now.

 NERR_PasswordTooShort             2245    The password is too short.

 NERR_PasswordTooRecent            2246    The password is too recent to be
                                           changed.



 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Passwords entered using API functions are case-sensitive; passwords entered
 from the command-line or full-screen interface are capitalized.

 An administrator who needs to change a user's password but does not know the
 old password should use NetUserSetInfo instead of NetUserPasswordSet.

 If NetUserPasswordSet is used to set the "default" password on the domain
 controller of a single system image (SSI) domain, the new password will be
 replicated throughout the domain.

 When NetUserPasswordSet is used remotely, and the user's password has
 expired but the user could otherwise log on, the server allows the call to
 succeed.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Setting a password                NetUserSetInfo

 Verifying the password for a      NetUserValidate2
 username


 NetUserSetGroups
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserSetGroups sets the groups to which a specified user belongs.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserSetGroups on a remote server or on a computer that has local
 security enabled.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserSetGroups (const char far *  pszServer,
                     const char far *  pszUserName,
                     short             sLevel,
                     char far *        pbBuffer,
                     unsigned short    cbBuffer,
                     unsigned short    cEntries
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserSetGroups. A null pointer or null string specifies the
   local computer.

 pszUserName
   Points to an ASCIIZ string that contains the name of the user for which to
   set groups.

 sLevel
   Specifies the level of detail provided; must be 0.

 pbBuffer
   Points to the buffer in which the data to be set is stored. This data
   consists of a sequence of group_info_0 data structures.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 cEntries
   Specifies the number of group_info_0 data structures supplied in the
   buffer pointed to by pbBuffer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_NAME                123     The character or file system
                                           name is invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_ACFNotFound                  2219    LAN Manager could not find the
                                           user accounts database file,
                                           NET.ACC. This file should be in
                                           the ACCOUNTS subdirectory of the
                                           LANMAN directory.

 NERR_GroupNotFound                2220    The groupname was not found.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFNoRoom                    2228    The user accounts database is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ACFNoRoom                    2228    The user accounts database is
                                           full.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_CanNotGrowSegment            2233    The user accounts database has
                                           reached its size limit. Nothing
                                           can be added to it.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If pbBuffer is set to a null pointer and cbBuffer is set to 0, the only
 group membership for the user can be to one of the special groups admins,
 users, or guests.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Setting group membership          NetGroupSetUsers


 NetUserSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserSetInfo modifies a user's account.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege or accounts operator privilege is required to successfully
 execute NetUserSetInfo on a remote server or on a computer that has local
 security enabled, except when users are setting details for their own
 accounts.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserSetInfo (const char far *  pszServer,
                   char far *        pszUserName,
                   short             sLevel,
                   char far *        pbBuffer,
                   unsigned short    cbBuffer,
                   short             sParmNum
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetUserSetInfo. A null pointer or null string specifies the
   local computer.

 pszUserName
   Points to an ASCIIZ string that specifies which user account to modify.

 sLevel
   Specifies the level of detail (1 or 2) provided.

 pbBuffer
   Points to the data to be set. If the user's password is being set, a
   read/write buffer must be supplied even though NetUserSetInfo does not
   change the contents of the buffer.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to reset all the user information or to change only a
   part of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a
   user_info_X data structure (where X is the level of detail specified). If
   sParmNum is set to any other defined value, only one element of the user
   information is changed, and pbBuffer must point to a valid value for that
   element.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The ACCESS.H header file
   defines the following possible values for sParmNum:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                  Value  Element of user_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL           0      All elements.
 PARMNUM_PASSWD        3      usriX_password
 PARMNUM_PRIV          5      usriX_priv
 PARMNUM_DIR           6      usriX_home_dir
 PARMNUM_COMMENT       7      usriX_comment
 PARMNUM_USER_FLAGS    8      usriX_flags
 PARMNUM_SCRIPT_PATH   9      usriX_script_path
 PARMNUM_AUTH_FLAGS    10     usri2_auth_flags
 Code                  Value  Element of user_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
PARMNUM_AUTH_FLAGS    10     usri2_auth_flags
 PARMNUM_FULL_NAME     11     usri2_full_name
 PARMNUM_USR_COMMENT   12     usri2_usr_comment
 PARMNUM_PARMS         13     usri2_parms
 PARMNUM_WORKSTATIONS  14     usri2_workstations
 PARMNUM_ACCT_EXPIRES  17     usri2_acct_expires
 PARMNUM_MAX_STORAGE   18     usri2_max_storage
 PARMNUM_LOGON_HOURS   20     usri2_logon_hours
 PARMNUM_LOGON_SERVER  23     usri2_logon_server
 PARMNUM_COUNTRY_CODE  24     usri2_country_code
 PARMNUM_CODE_PAGE     25     usri2_code_page
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_BadPassword                  2203    The password is invalid.

 NERR_UserNotFound                 2221    The username was not found.

 NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          not active. This database must
                                           be active for the command to run.

 NERR_SpeGroupOp                   2234    This operation is not allowed on
                                           this special group.

 NERR_PasswordTooShort             2245    The password is too short.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 NERR_LastAdmin                    2452    The operation is not allowed on
                                           the last account with admin
                                           privilege.

 NERR_CanNotGrowUASFile            2456    The user accounts database
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_CanNotGrowUASFile            2456    The user accounts database
                                           cannot be enlarged because the
                                           server's hard disk is full.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Only applications or users with admin privilege can change a user's password
 by calling NetUserSetInfo. Applications or users who know the current
 password can change the password by calling NetUserPasswordSet.

 When an administrator calls NetUserSetInfo, the only restriction applied is
 that the new password length must be consistent with system modals.

 Users with admin privilege can set any modifiable element. All users can set
 the usri2_usr_comment, usri2_parms, and usri2_country_code elements of the
 user_info_2 data structure for their own accounts. To do this, the user must
 use the sParmNum parameter and cannot pass the whole structure.

 If sParmNum is set to PARMNUM_ALL and the password is to be left unchanged,
 the usriX_password element of the user_info_X data structure (where X is 1
 or 2) must be set to NULL_USERSETINFO_PASSWD.

 An accounts operator cannot set details for an admin class account, give an
 existing account admin privilege, or change the operator privilege of any
 account.

 If attempting to change the privilege level or disable the last account with
 admin privilege in the database, NetUserSetInfo fails and returns
 NERR_LastAdmin.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"


 NetUserValidate2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserValidate2 validates a user's account, validates the user's password,
 and verifies whether the user can log on based on the user's logon
 restrictions.

 If the username and password combination is not correct, NetUserValidate2
 delays for approximately three seconds before returning ERROR_ACCESS_DENIED.



 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1 not supported

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to successfully execute
 NetUserValidate2.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserValidate2 (char far *            pszReserved1,
                     short                 sLevel,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short        usReserved2,
                     unsigned short far *  pcbTotalAvail
                    );

 where

 pszReserved1
   Reserved; must be a null pointer.

 sLevel
   Specifies the level of detail provided; must be 1.

 pbBuffer
   When making the call, pbBuffer points to the data to be validated. A
   user_logon_req_1 data structure that contains the username, password, and
   workstation name to be validated should be passed to the function.

   After the call, pbBuffer points to the returned data. On a successful
   return, the buffer contains a user_logon_info_1 data structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 usReserved2
   Reserved; must be 0.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetUserValidate2 returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success          0       The function encountered no errors.

 ERROR_ACCESS_DENIED   5       The user has insufficient privilege for this
                               operation.
 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                              operation.

 ERROR_INVALID_LEVEL   124     The level for information retrieval or
                               setting is invalid.

 ERROR_MORE_DATA       234     Additional data is available.

 NERR_BufTooSmall      2123    The supplied buffer is too small.

 NERR_ACFNotLoaded     2227    The user accounts database is not active.
                               This database must be active for the command
                               to run.

 NERR_ACFFileIOFail    2229    A disk I/O failure occurred.

 NERR_InvalidDatabase  2247    The user accounts database file, NET.ACC, is
                               corrupted.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                  Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 An application should examine both the NetUserValidate2 return code and the
 usrlog1_code element of the user_logon_info_1 data structure. Both codes are
 needed to determine the validity of the user's account.

 The usrlog1_code element of the user_logon_info_1 data structure can have
 the following values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0      The function encountered no
                                          errors.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         errors.

 ERROR_ACCESS_DENIED               5      The user has insufficient
                                          privilege for this operation.

 NERR_InvalidWorkstation           2240   The user is not allowed to log on
                                          from this workstation.

 NERR_InvalidLogonHours            2241   The user is not allowed to log on
                                          at this time.

 NERR_PasswordExpired              2242   The user's password has expired.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 The rest of the user_logon_info_1 data structure is valid only when
 usrlog1_code is returned as NERR_Success or ERROR_MORE_DATA.

 The usrlog1_bad_pw_count element is incremented if the password fails to
 match it. A successful match resets this element to 0.

 NetUserValidate2supersedes NetUserValidate(used in earlier versions of LAN
 Manager). For more information, see Appendix B, "Upgrading LAN Manager 1.0
 Applications."



 User Category Example

   /*
      NETUSER.C -- a sample program demonstrating NetUser API functions.

      This program requires that you have admin or accounts operator
      privilege on the specified server.

      usage:  netuser [-s \\server] [-u username] [-p password]
                      [-c comment] [-l privilege level]
      where  \\server = Name of the server. A servername must be
   preceded
                        by two backslashes (\\).
             username = Name of the user.
             password = Password for the user.
             comment  = Comment string for the user.
             privilege level = Privilege level for the user
                               (0=Guest, 1=User, 2=Admin).

      API                    Used to...
      ==================     ============================================
      NetUserAdd             Add a new user with a level 1 call
      NetUserEnum            List users and user comments
      NetUserGetInfo         Display user details
      NetUserSetInfo         Disable, then re-enable the account
      NetUserPasswordSet     Change the new user's password
      NetUserSetGroups       Set the groups to which a user belongs
      NetUserGetGroups       Get the groups to which a user belongs
      NetUserDel             Delete the new user
      NetUserModalsGet       Get current modals for users in database
      NetUserModalsSet       Increment the password history length by
   one

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETUSER
   #define     INCL_NETGROUP
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <search.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file
   #define  DEFAULT_NEWUSER       "BRUCE"
   #define  DEFAULT_PASSWORD      "PASSWORD"
   #define  DEFAULT_NEW_PASSWORD  "NEWPASS"
   #define  DEFAULT_PRIVILEGE     1          // 0=Guest, 1=User, 2=Admin
   #define  DEFAULT_COMMENT       "New user"
   #define  DEFAULT_NEWGROUP      "TESTERS"
   #define  NUM_GROUPS            10         // For NetUserGetGroups
   buffer
   #define  LARGE_BUFFER          32768      // Buffer size for Enum
   call


   int  Compare(struct user_info_2 *arg1, struct user_info_2 *arg2);
   void Usage  (char * pszProgram);

   void main(int argc, char *argv[])
   {
      char *         pszServer   = NULL;             // Servername
      char *         pszNewUser  = DEFAULT_NEWUSER;  // Name of new user
      char *         pszPassword = DEFAULT_PASSWORD; // Password for
   new user
      char *         pszComment  = DEFAULT_COMMENT;  // Comment for new
   user
      char *         pszNewGroup = DEFAULT_NEWGROUP; // Name of new group
      char *         pbBuffer;                       // Pointer to data
   buffer
      int            iCount;                         // Index counter
      unsigned short cbBuffer;                       // Size of data
   buffer
      unsigned short cEntriesRead;                   // Count of entries
   read
      unsigned short cTotalAvail;                    // Entries available
      unsigned short usPrivLevel = DEFAULT_PRIVILEGE;// New user privilege
      unsigned short fsFlags;                        // User flags
      unsigned short usHistLen;                      // Password history

      API_RET_TYPE   uReturnCode;                    // API return code
      struct user_info_1 * pUserInfo1;               // User info; level
   1
      struct user_info_2 * pUserInfo2;               // User info; level
   2
      struct group_info_0 * pGroupInfo0;             // Group info; level
   0
      struct user_modals_info_0 * pUserModals0;      // Modals info;
   level 0

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'u':                        // -u username
                  pszNewUser = argv[++iCount];
                  break;

   case 'p':                        // -p password
                  pszPassword = argv[++iCount];
                  break;
               case 'c':                        // -c comment
                  pszComment = argv[++iCount];
                  break;
               case 'l':                        // -l privilege level
                  usPrivLevel = atoi(argv[++iCount]);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetUserAdd
   //
   //  This API adds a new user at info level 1. Note comments carefully.
   //========================================================================

      cbBuffer = sizeof(struct user_info_1);
      pUserInfo1 = (struct user_info_1 *) SafeMalloc(cbBuffer);

      /*
       * Copy the fixed-length strings into the data buffer.
       * The password and username must be uppercase or the user will

       * not be able to log on through the net command or through the

       * full-screen user interface. The password is encrypted before

       * being sent to the server.
       */
      strcpy(pUserInfo1->usri1_name, pszNewUser);
      strcpy(pUserInfo1->usri1_password, pszPassword);

      pUserInfo1->usri1_priv        = usPrivLevel;
      pUserInfo1->usri1_home_dir    = "";
      pUserInfo1->usri1_comment     = pszComment;
      pUserInfo1->usri1_script_path = "";
      pUserInfo1->usri1_flags       = UF_SCRIPT;
      /*
       * At least UF_SCRIPT must be included here. If usriX_flags is
       * left as 0, NetUserAdd returns ERROR_INVALID_PARAMETER.
       */

      uReturnCode = NetUserAdd(pszServer,         // Servername
                          1,                      // Info level (1 or
   2)
                          (char far *)pUserInfo1, // Input buffer
                          cbBuffer);              // Size of buffer

      printf("NetUserAdd of %s returned %u\n", pszNewUser, uReturnCode);
      free(pUserInfo1);

   //========================================================================
   //  NetUserEnum
   //
   //  This API lists usernames and comments and sorts the names
   //  alphabetically before displaying them.
   //========================================================================

      cbBuffer = LARGE_BUFFER;                // Can be up to 64K
      pbBuffer = SafeMalloc(cbBuffer);        // Allocate data buffer

      uReturnCode = NetUserEnum(pszServer,    // Servername
                          1,                  // Info level (0,1,2,10)
                          pbBuffer,           // Data returned here
                          cbBuffer,           // Size of buffer, in bytes
                          &cEntriesRead,      // Count of entries read
                          &cTotalAvail);      // Count of entries available

      printf("NetUserEnum returned %u\n", uReturnCode);

      switch (uReturnCode) {
         case NERR_Success:
            pUserInfo1 = (struct user_info_1 *) pbBuffer;
            qsort(pbBuffer, cEntriesRead, sizeof(struct user_info_1),
   Compare);
            for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
            {
               printf("   %-24s (%Fs)\n", pUserInfo1->usri1_name,
                                         pUserInfo1->usri1_comment);
               pUserInfo1++;
            }
            break;
         case ERROR_MORE_DATA:
            printf("   Entries read = %hu,  Entries available = %hu \n",
                         cEntriesRead, cTotalAvail);
            break;
      }
      free(pbBuffer);

   //========================================================================
   //  NetUserGetInfo
   //
   //  This API prints details about the new user. First, call NetUserGetInfo
   //  with a zero-length buffer to determine the size of the buffer
   needed.
   //========================================================================

      uReturnCode = NetUserGetInfo(pszServer,     // Servername
                          pszNewUser,             // Username
                          2,                      // Level (0,1,2,10,11)
                          NULL,                   // Data buffer
                          0,                      // Size of data buffer

                          &cbBuffer);             // Buffer size required
      pbBuffer = SafeMalloc(cbBuffer);
      printf("NetUserGetInfo with NULL buffer returned %u\n", uReturnCode);

      uReturnCode = NetUserGetInfo(pszServer,     // Servername
                          pszNewUser,             // Username
                          2,                      // Level (0,1,2,10,11)
                          pbBuffer,               // Data buffer
                          cbBuffer,               // Size of data buffer

                          &cTotalAvail);          // Count of bytes available

      printf("NetUserGetInfo with %hu byte buffer returned %u\n",
                              cbBuffer, uReturnCode);
      pUserInfo2 = (struct user_info_2 *) pbBuffer;

      if (uReturnCode == NERR_Success)
      {
         printf("   User Name    = %s \n", pUserInfo2->usri2_name);
         printf("   Privilege    = %hu \n", pUserInfo2->usri2_priv);
         printf("   Comment      = %s \n", pUserInfo2->usri2_comment);
         printf("   Full name    = %s \n", pUserInfo2->usri2_full_name);
         printf("   Workstations = %s \n", pUserInfo2->usri2_workstations);
         printf("   Logon server = %s \n", pUserInfo2->usri2_logon_server);
      }

   //========================================================================
   //  NetUserSetInfo
   //
   //  There are two ways to call NetUserSetInfo. If sParmNum is PARMNUM_ALL,
   //  you must pass a whole user_info_X structure. Otherwise, you can
   set
   //  sParmNum to the element of the structure you want to change. Both
   ways
   //  are shown here.
   //========================================================================

   // Disable the account by setting the UF_ACCOUNTDISABLE bit
   to 1.
      pUserInfo2->usri2_flags |= UF_ACCOUNTDISABLE;

      strcpy(pUserInfo2->usri2_password, NULL_USERSETINFO_PASSWD);
      /*
       * This previous step is important. When you get a structure from
       * NetUserGetInfo, it does not contain the password. If you want
       * to send that same structure back to NetUserSetInfo (using
       * sParmNum=PARMNUM_ALL), you must set usriX_password to
       * NULL_USERSETINFO_PASSWD to indicate that you want the old password
       * left unchanged.
       */
      cbBuffer = sizeof(struct user_info_2);
      uReturnCode = NetUserSetInfo(pszServer,     // Servername
                          pszNewUser,             // Username
                          2,                      // Info level (1 or
   2)
                          (char far *)pUserInfo2, // Data buffer
                          cbBuffer,               // Size of buffer
                          PARMNUM_ALL);           // Parameter number
   code

      printf("NetUserSetInfo with sParmNum = %d returned %u\n",
                  PARMNUM_ALL, uReturnCode);

      /*
       * The following is a more typical use of NetUserSetInfo when you
   only
       * want to change one element in the structure. The example enables
       * an account by setting the UF_ACCOUNTDISABLE bit to 0.
       */

      fsFlags = pUserInfo2->usri2_flags & ~UF_ACCOUNTDISABLE;

      uReturnCode = NetUserSetInfo(pszServer,     // Servername
                          pszNewUser,             // Username
                          2,                      // Info level (1 or
   2)
                          (char far *) &fsFlags,  // Data buffer
                          sizeof(fsFlags),        // Size of buffer
                          PARMNUM_USER_FLAGS);    // Parameter number
   code

      printf("NetUserSetInfo with sParmNum = %d returned %u\n",
                  PARMNUM_USER_FLAGS, uReturnCode);
      free(pbBuffer);

   //========================================================================
   //  NetUserPasswordSet
   //
   //  This API changes a user's password. It allows users to change
   their
   //  own password if they know their old one. An administrator would

   //  typically use NetUserSetInfo, which does not require knowledge
   of
   //  the old password.
   //========================================================================

      uReturnCode = NetUserPasswordSet(pszServer, // Servername
                          pszNewUser,             // Username
                          pszPassword,            // Old password
                          DEFAULT_NEW_PASSWORD);  // New password

      printf("NetUserPasswordSet returned %u\n", uReturnCode);

   //========================================================================
   //  NetUserSetGroups
   //
   //  This API creates a new group and then sets this as the group to
   which
   //  the new user belongs.
   //========================================================================

      cbBuffer = sizeof(struct group_info_0);
      pGroupInfo0 = (struct group_info_0 *) SafeMalloc(cbBuffer);
      strcpy(pGroupInfo0->grpi0_name, pszNewGroup);

      uReturnCode = NetGroupAdd(pszServer,        // Servername
                          0,                      // Info level (0 or
   1)
                          (char far *)pGroupInfo0,// Input buffer
                          cbBuffer);              // Size of buffer

      printf("NetGroupAdd of group \"%s\" returned %u\n",
                 pszNewGroup, uReturnCode);

      uReturnCode = NetUserSetGroups(pszServer,   // Servername
                          pszNewUser,             // Username
                          0,                      // Info level; must
   be 0
                          (char far *)pGroupInfo0,// Input buffer
                          cbBuffer,               // Size of buffer
                          1);                     // Number of groups
   to set
      free(pGroupInfo0);

      printf("NetUserSetGroups for user \"%s\" returned %u\n",
                 pszNewUser, uReturnCode);

   //======================================================================
   //  NetUserGetGroups
   //
   //  This API lists the groups to which the new user belongs.
   //======================================================================

      // Allocate enough space for up to NUM_GROUPS groupnames.
      cbBuffer = sizeof(struct group_info_0) * NUM_GROUPS;
      pbBuffer = SafeMalloc(cbBuffer);

      uReturnCode = NetUserGetGroups(pszServer, // Servername
                          pszNewUser,           // Username
                          0,                    // Level; must be 0
                          pbBuffer,             // Return buffer
                          cbBuffer,             // Size of buffer
                          &cEntriesRead,        // Count of groups read
                          &cTotalAvail);        // Count of groups available

      printf("NetUserGetGroups returned %u\n", uReturnCode);

      if (uReturnCode == NERR_Success)
      {
         pGroupInfo0 = (struct group_info_0 *) pbBuffer;
         for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
         {
            printf("   %s\n", pGroupInfo0->grpi0_name);
            pGroupInfo0++;
         }
      }
      free(pbBuffer);

   //========================================================================
   //  NetUserDel
   //
   //  This API deletes the new user added at the start of this program
   and
   //  deletes the new group that was added to demonstrate NetUserSetGroups.
   //========================================================================

      uReturnCode = NetUserDel(pszServer,         // Servername
                               pszNewUser);       // Username

      printf("NetUserDel of user \"%s\" returned %u\n",
                 pszNewUser, uReturnCode);

   uReturnCode = NetGroupDel(pszServer,        // Servername
                                pszNewGroup);     // Groupname

      printf("NetGroupDel of group \"%s\" returned %u\n",
                 pszNewGroup, uReturnCode);

   //========================================================================
   //  NetUserModalsGet
   //
   //  This API gets modal information for all users in the user account

   //  subsystem.
   //========================================================================

      cbBuffer = sizeof(struct user_modals_info_0);
      pUserModals0 = (struct user_modals_info_0 *) SafeMalloc(cbBuffer);

      uReturnCode = NetUserModalsGet(pszServer,   // Servername
                          0,                      // Info level (0 or
   1)
                          (char far *)pUserModals0, // Return buffer
                          cbBuffer,               // Size of buffer
                          &cTotalAvail);          // Count of bytes available

      printf("NetUserModalsGet returned %u\n", uReturnCode);
      if (uReturnCode == NERR_Success)
      {
         printf("   Min. password length         = %hu\n",
                           pUserModals0->usrmod0_min_passwd_len);
         if (pUserModals0->usrmod0_max_passwd_age == TIMEQ_FOREVER)
            printf("   Max. password age (days)     = UNLIMITED\n");
         else
            printf("   Max. password age (days)     = %lu\n",
                           pUserModals0->usrmod0_max_passwd_age / (ONE_DAY));
         printf("   Min. password age (days)     = %lu\n",
                           pUserModals0->usrmod0_min_passwd_age / (ONE_DAY));
         if (pUserModals0->usrmod0_force_logoff == USER_NO_LOGOFF)
            printf("   Forced logoff time           = NEVER\n");
         else
            printf("   Forced logoff time (minutes) = %lu\n",
                           pUserModals0->usrmod0_force_logoff / 60);
         printf("   Password history             = %hu\n",
                           pUserModals0->usrmod0_password_hist_len);
      }

   //========================================================================
   //  NetUserModalsSet
   //
   //  There are two ways to call NetUserModalsSet. If sParmNum is
   //  PARMNUM_ALL, you must pass in a whole user_modals_info_X structure.
   //  Otherwise, you can set sParmNum to the element of the structure

   //  to change. In this example, the password history length is incremented


   //  using MODAL0_PARMNUM_HISTLEN as the value of sParmNum.
   //========================================================================

      if (pUserModals0->usrmod0_password_hist_len == DEF_MAX_PWHIST)
         usHistLen = 0;
      else
         usHistLen = pUserModals0->usrmod0_password_hist_len + 1;

      uReturnCode = NetUserModalsSet(pszServer,   // Servername
                          0,                      // Info level (0 or
   1)
                          (char far *)&usHistLen, // Input buffer
                          sizeof(usHistLen),      // Size of buffer
                          MODAL0_PARMNUM_HISTLEN);// Parameter number
   code

      printf("NetUserModalsSet returned %u\n", uReturnCode);
      free(pUserModals0);

      exit(0);
   }

   // Compare function used by quicksort.
   int Compare(struct user_info_2 *arg1, struct user_info_2 *arg2)
   {
      return(stricmp(arg1->usri2_name, arg2->usri2_name));
   };

   void Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage:  %s [-s \\\\server] [-u username] "\
                      "[-p password] [-c comment]\n\t\t"\
                      "[-l privilege level] \n", pszProgram);
      exit(1);
   }









 Workstation Category

 Workstation API functions control the operation of workstations. They
 require that the Workstation service be started.

 The Workstation category functions, datatypes, structures, and constants are
 defined in the NETCONS.H, NETERR.H, ACCESS.H, and WKSTA.H header files. A
 source program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETWKSTA, and including the master header file,
 LAN.H. For more information about these definitions, see the "Example"
 section, later in this category.

 These are the Workstation API functions:


   þ   NetWkstaGetInfo

   þ   NetWkstaSetInfo

   þ   NetWkstaSetUID2



 Description

 NetWkstaSetUID2 logs a user on to or off from a workstation and executes a
 logon script for a specific user.

 NetWkstaSetInfo configures a workstation. NetWkstaGetInfo returns
 information about the configuration of a workstation.


 Data Structures

 NetWkstaGetInfo uses wksta_info_X data structures, where X is 0, 1, or 10,
 depending on the level of detail requested. NetWkstaSetInfo uses
 wksta_info_X data structures, where  X is 0 or 1, depending on the level of
 detail specified.

 NetWkstaSetUID2 uses the user_logon_info_1 and user_logoff_info_1 data
 stuctures. The pszUserName input parameter determines whether
 NetWkstaSetUID2 performs a logon or a logoff operation, and selects the data
 structure provided in the return buffer. A null string or null pointer value
 for pszUserName indicates a logoff operation; any other value indicates a
 logon operation.

 MS-DOS does not support the following wksta_info_X data structure elements,
 where X is 0 or 1, depending on the level of detail requested:
 wkiX_maxthreads, wkiX_maxwrkcache, wkiX_sesstimeout, wkiX_sizerror,
 wkiX_numalerts, wkiX_errlogsz, wkiX_printbuftime, wkiX_logon_server.


 Workstation Information (level 0)

 The wksta_info_0 data structure has this format:

   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_reserved_6;
       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;
   };

 where

 wki0_reserved_1 and wki0_reserved_2
   Reserved; must be 0.

 wki0_root
   Points to an ASCIIZ string that contains the path to the computer's LANMAN
   directory.

 wki0_computername
   Points to an ASCIIZ string that contains the computername of the
   workstation.

 wki0_username
   Points to an ASCIIZ string that contains the name of the user who is
   logged on to the specified workstation.

 wki0_langroup
   Points to an ASCIIZ string that contains the name of the domain to which
   the workstation belongs.

 wki0_ver_major
   Specifies the LAN Manager major version number.

 wki0_ver_minor
   Specifies the LAN Manager minor version number.

 wki0_reserved_3
   Reserved; must be 0.

 wki0_charwait
   Specifies the number of seconds the workstation waits for a
   character-device resource to become available.

 wki0_chartime
   Specifies how many milliseconds the workstation collects data before
   sending the data to a character-device resource. The workstation waits the
   specified time or collects the number of characters specified by
   wki0_charcount, whichever comes first.

 wki0_charcount
   Specifies how many bytes of information the workstation collects before
   sending the data to a character-device resource. The workstation collects
   the specified number of bytes or waits the time specified by
   wki0_chartime, whichever comes first.

 wki0_reserved_4 and wki0_reserved_5
   Reserved; must be 0.

 wki0_keepconn
   Specifies how many seconds to maintain an inactive connection from the
   workstation to a resource on a server.

 wki0_keepsearch
   Specifies how many seconds an inactive search continues.

 wki0_maxthreads
   Specifies how many threads the workstation can dedicate to the network.
   (This element is not supported with MS-DOS.)

 wki0_maxcmds
   Specifies how many simultaneous network device driver commands can be sent
   to the network.

 wki0_reserved_6
   Reserved; must be 0.

 wki0_numworkbuf
   Specifies how many internal buffers the workstation has.

 wki0_sizworkbuf
   Specifies the size (in bytes) of each internal buffer.

 wki0_maxwrkcache
   Specifies the maximum size (in bytes) of an internal cache buffer. (This
   element is not supported with MS-DOS.)

 wki0_sesstimeout
   Specifies the number of seconds to wait before disconnecting an inactive
   session between a workstation and a server. (This element is not supported
   with MS-DOS.)

 wki0_sizerror
   Specifies the size (in bytes) of an internal error buffer. (This element
   is not supported with MS-DOS.)

 wki0_numalerts
   Specifies the maximum number of clients that can receive alert messages.
   (This element is not supported with MS-DOS.)

   Each mailslot or semaphore registered by NetAlertStart is a different
   client; the Alerter service registers at least three clients when it
   starts. For more information about alerts, see the Alert category API
   functions.

 wki0_numservices
   Specifies how many services can be started on the workstation at one time.
   For more information about services, see the Service category API
   functions.

 wki0_errlogsz
   Specifies the maximum size (in kilobytes) of the workstation's error log.
   (This element is not supported with MS-DOS.)

 wki0_printbuftime
   Specifies the number of seconds to wait before closing inactive print jobs
   submitted from the MS OS/2 DOS-compatibility-mode window. (This element is
   not supported with MS-DOS.)

 wki0_numcharbuf
   Specifies how many character pipe buffers and device buffers the
   workstation can have.

 wki0_sizcharbuf
   Specifies the maximum size (in bytes) of a character pipe buffer and a
   device buffer.

 wki0_logon_server
   Points to an ASCIIZ string that contains the name of the logon server that
   validated the user logon. (This element is not supported with MS-DOS.)

   A null string indicates that the user logon was not validated by any
   server. For more information about logging on and logging off, see your
   LAN Manager administrator's manual(s).

 wki0_wrkheuristics
   Points to an ASCIIZ string that contains flags used to control a
   workstation's operation. Digits are read from left (0) to right (54). For
   a complete description of heuristics, see Appendix G, "Workstation and
   Server Heuristics."

 wki0_mailslots
   Specifies whether mailslots are allowed. If wki0_mailslots is 0, mailslots
   are not supported on this computer and the Netlogon service will not
   start.


 Workstation Information (level 1)

 The wksta_info_1 data structure includes the elements of the wksta_info_0
 data structure. For more information, see the previous section.
 NetWkstaGetInfo and NetWkstaSetInfo use the wksta_info_1 data structure.

 The wksta_info_1 data structure has this format:

   struct wksta_info_1 {
       unsigned short  wki1_reserved_1;
       unsigned long   wki1_reserved_2;
       char far *      wki1_root;
       char far *      wki1_computername;
       char far *      wki1_username;
       char far *      wki1_langroup;
       unsigned char   wki1_ver_major;
       unsigned char   wki1_ver_minor;
       unsigned long   wki1_reserved_3;
       unsigned short  wki1_charwait;
       unsigned long   wki1_chartime;
       unsigned short  wki1_charcount;
       unsigned short  wki1_reserved_4;
       unsigned short  wki1_reserved_5;
       unsigned short  wki1_keepconn;
       unsigned short  wki1_keepsearch;
       unsigned short  wki1_maxthreads;
       unsigned short  wki1_maxcmds;
       unsigned short  wki1_reserved_6;
       unsigned short  wki1_numworkbuf;
       unsigned short  wki1_sizworkbuf;
       unsigned short  wki1_maxwrkcache;
       unsigned short  wki1_sesstimeout;
       unsigned short  wki1_sizerror;
       unsigned short  wki1_numalerts;
       unsigned short  wki1_numservices;
       unsigned short  wki1_errlogsz;
       unsigned short  wki1_printbuftime;
       unsigned short  wki1_numcharbuf;
       unsigned short  wki1_sizcharbuf;
       char far *      wki1_logon_server;
       char far *      wki1_wrkheuristics;
       unsigned short  wki1_mailslots;
       char far *      wki1_logon_domain;
       char far *      wki1_oth_domains;
       unsigned short  wki1_numdgrambuf;
   };

 where

 wki1_reserved_1 through wki1_mailslots
   Are the same as the corresponding elements of the wksta_info_0 data
   structure. For a complete description, see the preceding section.

 wki1_logon_domain
   Points to an ASCIIZ string that contains the name of the domain in which
   the user is logged on. When no user is logged on, a null string is
   returned.

 wki1_oth_domains
   Points to an ASCIIZ string that lists all domains in which the computer is
   enlisted. Names of domains are separated by spaces. This element can be
   set by using NetWkstaSetInfo. (This element is not supported with MS-DOS.)

 wki1_numdgrambuf
   Specifies the number of buffers to allocate for receiving datagrams. For
   more information, see your LAN Manager administrator's manual(s).


 Workstation Information (level 10)

 The wksta_info_10 data structure is provided for users who do not have admin
 privilege, but who need certain information about a workstation. The
 wksta_info_10 data structure can be used with NetWkstaGetInfo.

 The wksta_info_10 data structure has this format:

   struct wksta_info_10 {
       char far *      wki10_computername;
       char far *      wki10_username;
       char far *      wki10_langroup;
       unsigned char   wki10_ver_major;
       unsigned char   wki10_ver_minor;
       char far *      wki10_logon_domain;
       char far *      wki10_oth_domains;
   };

 where

 wki10_computername through wki10_oth_domains

   Are the same as the corresponding elements in the wksta_info_0 and
   wksta_info_1 structures. For more information, see the preceding section.


 Logon Information (level 1)

 The user_logon_info_1 and user_logoff_info_1 data structures are returned by
 the NetWkstaSetUID2 API function.

 The user_logon_info_1 data structure has this format:

   struct user_logon_info_1 {
       unsigned short usrlog1_code;
       char           usrlog1_eff_name[UNLEN+1];
       char           usrlog1_pad_1;
       unsigned short usrlog1_priv;
       unsigned long  usrlog1_auth_flags;
       unsigned short usrlog1_num_logons;
       unsigned short usrlog1_bad_pw_count;
       unsigned long  usrlog1_last_logon;
       unsigned long  usrlog1_last_logoff;
       unsigned long  usrlog1_logoff_time;
       unsigned long  usrlog1_kickoff_time;
       long           usrlog1_password_age;
       unsigned long  usrlog1_pw_can_change;
       unsigned long  usrlog1_pw_must_change;
       char far *     usrlog1_computer;
       char far *     usrlog1_domain;
       char far *     usrlog1_script_path;
       unsigned long  usrlog1_reserved1;
   };

 where

 usrlog1_code
   Specifies the logon code used in conjunction with the code returned by
   NetWkstaSetUID2. For a list of the specific values, see the "Return Codes"
   section of the NetWkstaSetUID2 description.

 usrlog1_eff_name
   Specifies the account to which the user was logged on. The constant UNLEN
   is defined in the NETCONS.H header file.

 usrlog1_pad_1
   Aligns the next data structure element on a word boundary.

 usrlog1_priv
   Specifies the user's privilege level. The ACCESS.H header file defines
   these possible values:

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USER_PRIV_GUEST  0      Guest privilege.
 USER_PRIV_USER   1      User privilege.
 USER_PRIV_ADMIN  2      Admin privilege.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 usrlog1_auth_flags
   Specifies the account operator privileges. The ACCESS.H header file
   defines these possible values:

 Code            Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AF_OP_PRINT     0      Print operator.
 AF_OP_COMM      1      Comm operator.
 AF_OP_SERVER    2      Server operator.
 AF_OP_ACCOUNTS  3      Accounts operator.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 usrlog1_num_logons
   Specifies the number of times this user is logged on. A value of -1 means
   the number of logons is unknown.

 usrlog1_bad_pw_count
   Specifies the number of incorrect passwords entered since the last
   successful logon.

 usrlog1_last_logon
   Specifies the time when the user last logged on. This value is stored as
   the number of seconds elapsed since 00:00:00, January 1, 1970.

 usrlog1_last_logoff
   Specifies the time when the user last logged off. This value is stored as
   the number of seconds elapsed since 00:00:00, January 1, 1970. A value of
   0 means that the last logoff time is unknown.

 usrlog1_logoff_time
   Specifies the time when the user should log off. This value is stored as
   the number of seconds elapsed since 00:00:00, January 1, 1970. A value of
   -1 means the user never has to log off.

 usrlog1_kickoff_time
   Specifies the time when the user will be logged off by the system. This
   value is stored as the number of seconds elapsed since 00:00:00, January
   1, 1970. A value of -1 means the system will not log off the user.

 usrlog1_password_age
   Specifies the time (in seconds) since the user password was changed.

 usrlog1_pw_can_change
   Specifies the time when the user is allowed to change the password. This
   value is stored as the number of seconds elapsed since 00:00:00, January
   1, 1970. A value of -1 means the user can never change the password.

 usrlog1_pw_must_change
   Specifies the time when the user must change the password. This value is
   stored as the number of seconds elapsed since 00:00:00, January 1, 1970.

 usrlog1_computer
   Specifies the computer where the user is logged on.

 usrlog1_domain
   Specifies the domain in which the user is logged on.

 usrlog1_script_path
   Specifies the relative path to the user logon script.

 usrlog1_reserved1
   Reserved; the value is undefined. This element should not be used.


 Logoff Information (level 1)

 The user_logoff_info_1 data structure has this format:

   struct user_logoff_info_1 {
       unsigned short  usrlogf1_code;
       unsigned long   usrlogf1_duration;
       unsigned short  usrlogf1_num_logons;
   };

 where

 usrlogf1_code
   Specifies the logoff code used in conjunction with the value returned by
   NetWkstaSetUID2. For a list of specific values, see the "Return Codes"
   section of the NetWkstaSetUID2 description.

 usrlogf1_duration
   Specifies the number of seconds elapsed since the user logged on.

 usrlogf1_num_logons
   Specifies the number of times this user is logged on. A value of -1 means
   the number of logons is unknown.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Configuring workstations          LAN Manager administrator's manual(s)

 Domains                           LAN Manager administrator's manual(s)

 Elements of wksta_info_0 data     Appendix G, "Workstation and Server
 structure                         Heuristics"

 LANMAN.INI file                   LAN Manager installation manual(s)


 NetWkstaGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetWkstaGetInfo returns information about the configuration elements for a
 workstation.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote



 Privilege Level

 Admin privilege or accounts, comm, print, or server operator privilege is
 required to successfully execute NetWkstaGetInfo at level 0 or level 1 on a
 remote server or on a computer that has local security enabled. No special
 privilege is required for level 10 calls.


 Syntax

   #define INCL_NETWKSTA
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetWkstaGetInfo (const char far *      pszServer,
                    short                 sLevel,
                    char far *            pbBuffer,
                    unsigned short        cbBuffer,
                    unsigned short far *  pcbTotalAvail
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetWkstaGetInfo. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail to be supplied in the return buffer. Level
   0, 1, or 10 can be used on the local computer. Only level 10 can be used
   on a remote server.

 pbBuffer
   Points to the buffer in which data is returned. On a successful return,
   the buffer contains the wksta_info_X data structure, where X is 0, 1, or
   10, depending on the level of detail specified.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer in which the number of bytes of
   information available is returned. This count is valid only if
   NetWkstaGetInfo returns NERR_Success, ERROR_MORE_DATA, or
   NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Modifying the configuration of    NetWkstaSetInfo
 the local workstation


 NetWkstaSetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetWkstaSetInfo configures a workstation.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, local and remote.



 Privilege Level

 Admin privilege is required to successfully execute NetWkstaSetInfo on a
 remote server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETWKSTA
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetWkstaSetInfo (const char far *  pszServer,
                    short             sLevel,
                    char far *        pbBuffer,
                    unsigned short    cbBuffer,
                    short             sParmNum
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetWkstaSetInfo. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0 or 1) of the data structure provided in
   the buffer.

 pbBuffer
   Points to the buffer that contains the wksta_info_X data structure
   elements (where X is the level of detail specified). If sParmNum is
   PARMNUM_ALL, pbBuffer should point  to the appropriate wksta_info_X data
   structure. If sParmNum contains the code for a single element, pbBuffer
   should point to the single element to be set.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 sParmNum
   Specifies whether to change all elements or a single element of the
   wksta_info_X data structure (where X is 0, 1, or 10, depending on the
   level of detail specified). If sParmNum is PARMNUM_ALL, pbBuffer must
   point to the wksta_info_X data structure. If, sParmNum is any other
   defined value, only one element is changed and sParmNum must point to the
   single element to change.

   Not all elements can be set. Only those elements that have a specific
   PARMNUM constant value defined can be set. The WKSTA.H and NETCONS.H
   header files define these possible values for sParmNum:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                         Value  Element of wksta_info_X
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PARMNUM_ALL                  0      All elements.
 WKSTA_CHARWAIT_PARMNUM       10     wkiX_charwait
 WKSTA_CHARTIME_PARMNUM       11     wkiX_chartime
 WKSTA_CHARCOUNT_PARMNUM      12     wkiX_charcount
 WKSTA_ERRLOGSZ_PARMNUM       27     wkiX_errlogsz
 WKSTA_PRINTBUFTIME_PARMNUM   28     wkiX_printbuftime
 WKSTA_WRKHEURISTICS_PARMNUM  32     wkiX_wrkheuristics
 WKSTA_OTHDOMAINS_PARMNUM     35     wki1_oth_domains
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_NetworkError                 2136    A general failure occurred in
                                           the network hardware.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_TooManyNames                 2277    The maximum number of message
                                           aliases has been exceeded.

 NERR_DuplicateName                2297    The name specified is already in
                                           use as a message alias on the
                                           network.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          network.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetWkstaSetInfo does not change values in the LANMAN.INI file. Values set by
 previous calls to NetWkstaSetInfo can be overwritten when workstation
 parameters are reset. When the Workstation service is stopped and restarted,
 parameters are reset to the default values specified in the LANMAN.INI file
 unless overwritten by command-line parameters.

 Domain names in the wki1_oth_domains element of the wksta_info_1 data
 structure are separated by spaces. An empty list is legal. A null pointer
 means to leave the field unmodified. The wki1_oth_domains element cannot be
 set with MS-DOS. When setting this element, NetWkstaSetInfo rejects the
 request if the name list was invalid or if a name could not be added to one
 or more of the network adapters managed by LAN Manager.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Remote calls                      Chapter 1, "Overview of the LAN Manager
                                   API"

 Retrieving the configuration of   NetWkstaGetInfo
 the local workstation


 NetWkstaSetUID2
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetWkstaSetUID2 logs a user on to or off from the network, and runs a logon
 script.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege is required to successfully execute NetWkstaSetUID2.
 Remote calls are not supported.


 Syntax

   #define INCL_NETWKSTA
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetWkstaSetUID2 (char far *            pszReserved,
                    char far *            pszDomain,
                    char far *            pszUserName,
                    char far *            pszPassword,
                    char far *            pszParms,
                    unsigned short        usLogoffForce,
                    short                 sLevel,
                    char far *            pbBuffer,
                    unsigned short        cbBuffer,
                    unsigned short far *  pcTotalAvail
                   );

 where

 pszReserved
   Reserved; must be NULL.

 pszDomain
   Points to an ASCIIZ string that contains the name of the domain in which
   to log on. A null string or null pointer specifies that the primary domain
   is used. The domain name is used only during a logon operation.

 pszUserName
   Points to an ASCIIZ string that specifies the username. The pszUserName
   parameter determines whether a logon or logoff operation is performed. A
   null pointer or null string indicates a logoff operation. A non-null value
   indicates that NetWkstaSetUID2 should log on the specified user.

 pszPassword
   Points to an ASCIIZ string that contains the logon password for the
   username pointed to by pszUserName. The value of pszPassword becomes the
   default password for the workstation and is used whenever the workstation
   attempts to access a remote resource.

 pszParms
   Reserved; must be set to a null string (" ").

 usLogoffForce
   Specifies how to proceed with the logoff operation when the user has
   connections to redirected resources. The usLogoffForce parameter is used
   when NetWkstaSetUID2 performs a logoff operation (when a null pointer or
   null string is supplied for the pszUserName parameter). The WKSTA.H header
   file defines these possible values:

 Code                 Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 WKSTA_NOFORCE        0      Log off the user if the user has no
                             connections to redirected resources. Do not
                             log off if the user has connections.

 WKSTA_FORCE          1      Log off the user with connections to
                             redirected resources. Do not log off if the
                             user has pending activities on redirected
                             resources, or if the user uses the resource as
                             the current drive.

 WKSTA_LOTS_OF_FORCE  2      Log off the user with connections or pending
                             activities on redirected resources. Do not log
                             off if a user process uses the resource as the
                             current drive.

 WKSTA_MAX_FORCE      3      Log off the user under any conditions.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 sLevel
   Specifies the level of detail of the data structure provided in the
   buffer; must be 1.

 pbBuffer
   Points to the buffer in which to store the return data. On a successful
   return after a logon operation, the buffer contains a user_logon_info_1
   data structure. On a successful return after a logoff operation, the
   buffer contains a user_logoff_info_1 data structure. (The pszUserName
   parameter determines whether the logon or logoff operation is performed.)


 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcTotalAvail
   Points to an unsigned short integer that specifies the number of bytes of
   data available.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_INVALID_FUNCTION            1       The function is invalid.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_AlreadyLoggedOn              2200    A user is already logged on at
                                           this workstation.

 NERR_NotLoggedOn                  2201    The user must log on to the
                                           network before performing this
                                           operation.

 NERR_BadUsername                  2202    The username or groupname is
                                           invalid.

 NERR_BadPassword                  2203    The password is invalid.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadPassword                  2203    The password is invalid.

 NERR_UnableToAddName_W            2204    Warning: The logon processor did
                                           not add the message alias.

 NERR_UnableToAddName_F            2205    Failure: The logon processor did
                                           not add the message alias.

 NERR_UnableToDelName_W            2206    Warning: The logoff processor
                                           did not delete the message alias.

 NERR_UnableToDelName_F            2207    Failure: The logoff processor
                                           did not delete the message alias.

 NERR_StandaloneLogon              2214    The logon was not validated by a
                                           logon server. The computer will
                                           be logged on as STANDALONE.

 NERR_ActiveConns                  2402    Active connections still exist.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ActiveConns                  2402    Active connections still exist.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 For a logon operation, an application should examine both the
 NetWkstaSetUID2 return code and the usrlog1_code element of the
 user_logon_info_1 data structure.

 For a logoff operation, an application should examine both the
 NetWkstaSetUID2 return code and the usrlogf1_code element of the
 user_logoff_info_1 data structure. Both codes are needed to determine the
 valid elements of the data structure.

 The usrlog1_code element of the user_logon_info_1 data structure can have
 these values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0      The function encountered no
                                          errors.

 ERROR_ACCESS_DENIED               5      The user has insufficient
                                          privilege for this operation.

 NERR_LogonScriptError             2212   An error occurred while loading
                                          or running the logon script.

 NERR_StandaloneLogon              2214   The logon was not validated by a
                                          logon server. The computer will
                                          be logged on as STANDALONE.

 NERR_NonValidatedLogon            2217   The logon server is running an
                                          earlier version of LAN Manager
                                          and cannot validate the logon.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         and cannot validate the logon.

 NERR_InvalidWorkstation           2240   The user is not allowed to log on
                                          from this workstation.

 NERR_InvalidLogonHours            2241   The user is not allowed to log on
                                          at this time.

 NERR_PasswordExpired              2242   The user's password has expired.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 The following table defines the valid elements of the user_logon_info_1 data
 structure based on the values of the NetWkstaSetUID2 return code and the
 usrlog1_code element:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 NetWkstaSetUID2 Return   usrlog1_code Element of  Valid Elements of
 Code                     user_logon_info_1        user_logon_info_1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success             NERR_Success             All.

 NERR_Success             NERR_StandaloneLogon     None.

 NERR_UnableToAddName_W   NERR_Success             All.

 NERR_UnableToAddName_W   NERR_NonValidatedLogon   computer, script_path

 ERROR_ACCESS_DENIED      NERR_PasswordExpired     None.

 ERROR_ACCESS_DENIED      NERR_InvalidWorkstation  None.

 ERROR_ACCESS_DENIED      NERR_InvalidLogonHours   None.

 ERROR_ACCESS_DENIED      NERR_LogonScriptError    None.

 ERROR_ACCESS_DENIED      ERROR_ACCESS_DENIED      None.

 NetWkstaSetUID2 Return   usrlog1_code Element of  Valid Elements of
 Code                     user_logon_info_1        user_logon_info_1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 All other errors         None; the code is        None.
                          meaningless

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 ERROR_ACCESS_DENIED applies when the account is disabled, the account has
 expired, there is no account, or if the password does not match.

 The following table defines the valid fields in the user_logoff_info_1 data
 structure based on the values of the NetWkstaSetUID2 return code and the
 usrlogf1_code element:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 NetWkstaSetUID2 Return   usrlogf1_code  Element   Valid Elements of
 Code                     of user_logoff_info_1    user_logoff_info_1
 NetWkstaSetUID2 Return   usrlogf1_code  Element   Valid Elements of
 Code                     of user_logoff_info_1    user_logoff_info_1
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success             NERR_Success             All.

 NERR_Success             NERR_StandaloneLogon     None.

 NERR_UnableToDelName_W   NERR_Success             All.

 NERR_UnableToDelName_W   NERR_NonValidatedLogon   None.

 All other errors         None; the code is        None.
                          meaningless

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Domains                           LAN Manager administrator's manual(s)





 Workstation Category Example

   /*
      NETWKSTA.C -- a sample program demonstrating NetWksta API functions.

      This program requires that you have admin privilege on the
      specified server.

      usage:  netwksta [-s \\server] [-l level] [-d domain] [-u username]
                       [-p password] [-f logoff force]
      where  \\server     = Name of the server. A servername must be

                            preceded by two backslashes (\\).
             level        = Level of detail to be provided/supplied.
             domain       = Logon domain.
             username     = Name of the logon user.
             password     = Password for the logon user.
             logoff force = Level of logoff force.

      API                 Used to...
      ===============     ==============================================
      NetWkstaGetInfo     Return information about the configuration
                          components for a workstation.
      NetWkstaSetInfo     Change configuration of currently executing
                          workstation. This example doubles the values
                          for charcount and chartime each time it is
   run.
      NetWkstaSetUID2     Log on or log off the user.

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define  INCL_BASE
   #include <os2.h>            // MS OS/2 base header files

   #define  INCL_NETWKSTA
   #define  INCL_NETERRORS
   #include <lan.h>            // LAN Manager header files

   #include <stdio.h>          // C run-time header files
   #include <stdlib.h>
   #include <string.h>

   #include "samples.h"        // Internal routine header files

   //  Define function prototypes.
   void ProcessLogonCode(struct user_logon_info_1 *p1);
   void ProcessLogoffCode(struct user_logoff_info_1 *p1);
   void ProcessAccessDenied(struct user_logon_info_1 *p1);
   void Usage(char * pszString);

   void main(int argc, char * argv[])
   {
      char * pbBuffer;                     // Pointer to data buffer
      char * pszDomainName = "";           // Default to local machine
      char * pszServer = "";               // Default to local machine
      char * pszUserName = "";             // Default to null username
      char * pszPassword = "";             // Default to null password
      int    iCount;                       // Index counter
      short  sLevel = 0;                   // Level of info in pbBuffer
      unsigned short cbBuflen;             // Count of bytes
      unsigned short cbTotalAvail;         // Count of bytes available
      unsigned short usLogoffForce = 0;    // Level of force for logoff
      API_RET_TYPE   uRetCode;             // API return code
      struct wksta_info_0 *p0;             // Workstation info; level
   0
      struct wksta_info_1 *p1;             // Workstation info; level
   1
      struct wksta_info_10 *p10;           // Workstation info; level
   10

      for (iCount = 1; iCount < argc; iCount++) // Get command-line switches
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 'd':                        // -d domain name
                  pszDomainName = argv[++iCount];
                  break;
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'u':                        // -u username
                  pszUserName = argv[++iCount];
                  break;
               case 'p':                        // -p password
                  pszPassword = argv[++iCount];
                  break;
               case 'l':                        // -l level
                  sLevel = atoi(argv[++iCount]);
                  break;
               case 'f':                        // -f logoff force
                  usLogoffForce = atoi(argv[++iCount]);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }
      printf("\nWorkstation Category API Examples\n");

   //========================================================================
   //  NetWkstaGetInfo
   //
   //  This API returns information about the workstation configuration.
   //  The data reflects all changes made by NetWkstaSetInfo, but may
   //  not be the same as the default values as set in the LANMAN.INI
   file.
   //  For LANMAN.INI parameter values, use NetConfigGet2.
   //========================================================================

   /*
    * NetWkstaGetInfo returns both fixed-length and variable-length data.
    * The size of the data buffer passed to the API function must be

    * larger than the size of the structure. The extra space is needed
    * for variable-length strings, such as computername and username.

    * Call NetWkstaGetInfo the first time with a zero-length buffer,

    * and the API function returns the buffer size needed.
    */
      uRetCode = NetWkstaGetInfo(pszServer,    // Servername
                              sLevel,          // Reporting level (0,1,10)
                              NULL,            // Target buffer for info
                              0,               // Size of target buffer
                              &cbBuflen);      // Count of bytes available

      if (uRetCode == NERR_BufTooSmall)
         pbBuffer = SafeMalloc(cbBuflen);
      else
      {
         printf("NetWkstaGetInfo returned %u\n", uRetCode);
         exit(1);
      }

      uRetCode = NetWkstaGetInfo(pszServer,    // Servername
                              sLevel,          // Reporting level (0,1,10)
                              pbBuffer,        // Target buffer for info
                              cbBuflen,        // Size of target buffer
                              &cbTotalAvail);  // Total info, in bytes

      printf("NetWkstaGetInfo returned %u\n", uRetCode);
      if (uRetCode != NERR_Success)
         exit(1);

      if ((sLevel == 0) || (sLevel == 1))  // Display common elements
      {
         p0 = (struct wksta_info_0 *) pbBuffer;
         printf("    Computer Name   : %Fs\n", p0->wki0_computername);
         printf("    User Name       : %Fs\n", p0->wki0_username);
         printf("    Lan Group       : %Fs\n", p0->wki0_langroup);
         printf("    Logon Server    : %Fs\n", p0->wki0_logon_server);
         printf("    Char Time       : %lu\n", p0->wki0_chartime);
         printf("    Char Count      : %hu\n", p0->wki0_charcount);
      }
      if (sLevel == 1)
      {
         p1 = (struct wksta_info_1 *) pbBuffer;
         printf("    Logon Domain    : %s\n", p1->wki1_logon_domain);
         printf("    Other Domains   : %s\n", p1->wki1_oth_domains);
         printf("    Datagram Buffers: %hu\n", p1->wki1_numdgrambuf);
      }
      if (sLevel == 10)
      {
         p10 = (struct wksta_info_10 *) pbBuffer;
         printf("    Computer Name   : %Fs\n", p10->wki10_computername);
         printf("    User Name       : %Fs\n", p10->wki10_username);
         printf("    Logon Domain    : %s\n", p10->wki10_logon_domain);
         printf("    Other Domains   : %s\n", p10->wki10_oth_domains);
      }

   //========================================================================
   //  NetWkstaSetInfo
   //
   //  This API sets configuration components for the specified LAN Manager
   //  workstation. This API does not modify the LANMAN.INI file. The
   call
   //  to NetWkstaSetInfo can reset all parameters or only one parameter.

   //  To reset all parameters, first call NetWkstaGetInfo, modify the

   //  desired components, then use NetWkstaSetInfo. If you want to change

   //  only one parameter, supply the variable that will change, and
   then
   //  call NetWkstaSetInfo with the corresponding parameter number code.
   //========================================================================

      // Previous call to NetWkstaGetInfo assures valid data in structure.


      p0 = (struct wksta_info_0 *) pbBuffer;

   //  Double the chartime and charcount values.
      p0->wki0_chartime *= 2;
      p0->wki0_charcount *= 2;

      uRetCode = NetWkstaSetInfo(pszServer,    // Servername
                            sLevel,            // Reporting level
                            pbBuffer,          // Source buffer for info
                            cbBuflen,          // Size of source buffer
                            PARMNUM_ALL);      // Parameter number code

      printf("NetWkstaSetInfo returned %u\n", uRetCode);

      if (uRetCode == NERR_Success)
      {
         printf("    Char Time set to  : %lu\n", p0->wki0_chartime);
         printf("    Char Count set to : %hu\n", p0->wki0_charcount);
      }
      free(pbBuffer);

   //========================================================================
   //  NetWkstaSetUID2
   //
   //  This API logs a user on to or off from the network. The username

   //  parameter determines which operation to perform; a null username

   //  indicates a logoff operation, a non-null username indicates a
   logon
   //  operation.
   //========================================================================

      // Make an initial call to determine the required return buffer
   size.

      uRetCode = NetWkstaSetUID2(NULL,   // Reserved; must be NULL
                       NULL,             // Domain to log on to
                       NULL,             // User to log on or null=log
   off
                       NULL,             // User password if logon
                       "",               // Reserved; must be null string
                       0,                // Logoff force
                       1,                // Level; must be 1
                       NULL,             // Logon data returned
                       0,                // Size of data area, in bytes
                       &cbTotalAvail);   // Count of total bytes available

      cbBuflen = cbTotalAvail;
      pbBuffer = SafeMalloc(cbBuflen);

      uRetCode = NetWkstaSetUID2(NULL,   // Reserved; must be NULL
                       pszDomainName,    // Domain to log on to
                       pszUserName,      // User to log on or null=log
   off
                       pszPassword,      // User password if logon
                       "",               // Reserved; must be null string
                       usLogoffForce,    // Logoff force
                       1,                // Level; must be 1
                       pbBuffer,         // Logon data returned
                       cbBuflen,         // Size of data area, in bytes
                       &cbTotalAvail);   // Count of total bytes available
      printf("NetWkstaSetUID2 returned %u\n", uRetCode);

      if ((*pszUserName == '\0') || (pszUserName == NULL))
      {
         printf("Log off using logoff code %hu\n", usLogoffForce);
         switch (uRetCode)
         {
            case NERR_NotLoggedOn:
               printf("Not logged on\n");
               break;
            case NERR_Success:
            case NERR_UnableToDelName_W:
               ProcessLogoffCode((struct user_logoff_info_1 *) pbBuffer);
               break;
            default:
               break;
         }
      }
      else  // Non-null username indicates a logon operation.
      {
         printf("Log user %s (password %s)",pszUserName, pszPassword);
         if ((*pszDomainName == '\0') || (pszDomainName == NULL))
            printf(" on the workstation's primary domain\n");
         else
            printf(" on domain %s\n", pszDomainName);

         switch (uRetCode)
         {
            case NERR_Success:
            case NERR_UnableToAddName_W:
               ProcessLogonCode((struct user_logon_info_1 *) pbBuffer);
               break;
            case NERR_StandaloneLogon:
               printf("No logon server specified, logged on STANDALONE\n");
               break;
            case NERR_BadUsername:
            case NERR_BadPassword:
               printf("Invalid username or password\n");
               break;

   case NERR_AlreadyLoggedOn:
            case NERR_NotLoggedOn:
               printf("Did not logon user \n");
               break;
            case ERROR_ACCESS_DENIED:
               ProcessAccessDenied((struct user_logon_info_1 *) pbBuffer);
               break;
            default:
               break;
         }
      }
      free(pbBuffer);
   }

   //========================================================================
   //  Applications that call NetWkstaSetUID2 need to examine two different

   //  return code variables to determine whether structure elements
   in the
   //  return buffer contain valid data.
   //
   //  This example program first examines the return code returned by
   the
   //  function, and then calls the functions ProcessLogoffCode,
   //  ProcessLogonCode, and ProcessAccessDenied to examine the return
   code
   //  within the user_logon_info_1 or user_logoff_info_1 data structures.
   //
   //  The combination of values of the function return code and the
   code
   //  present in the return buffer determines which structure elements
   //  contain valid data.
   //
   //  ProcessLogoffCode examines the usrlogf1_code element of the
   //  user_logoff_info_1 data structure when NetWkstaSetUID2, called
   with a
   //  null username, returns NERR_Success or NERR_UnableToDelName_W.
   //========================================================================

   void ProcessLogoffCode(struct user_logoff_info_1 *p1)
   {
      printf("Logoff code = %hu\n", p1->usrlogf1_code);

      switch (p1->usrlogf1_code)
      {
         case NERR_Success:            // All elements valid
            printf("Duration of logon: %lu\n", p1->usrlogf1_duration);
            printf("%hu other logons\n", p1->usrlogf1_num_logons);
            break;
         case NERR_NonValidatedLogon:  // No other valid elements in
   p1
            printf("Non validated logon\n");
            break;

   case NERR_StandaloneLogon:
            printf("Standalone logon\n");
            break;
         default:
            printf("No valid fields\n");
            break;
      }
      return;
   }

   //========================================================================
   // For calls to NetWkstaSetUID2, two different return code variables

   // are needed to determine whether structure elements in the return
   // buffer contain valid data. ProcessLogonCode examines the
   // usrlog1_code element of the user_logon_info_1 data structure when

   // NetWkstaSetUID2, called with a non-null username, returns NERR_Success

   // or NERR_UnableToAddName_W.
   //========================================================================

   void ProcessLogonCode(struct user_logon_info_1 *p1)
   {
      printf("Logon code = %hu\n", p1->usrlog1_code);
      switch (p1->usrlog1_code)
      {
         case NERR_Success:            // All codes valid
            printf("User %s", p1->usrlog1_eff_name);
            printf(" has privilege level %hu\n", p1->usrlog1_priv);
            break;
         case NERR_NonValidatedLogon:  // Computer, script valid
            printf("Used logon script %s", p1->usrlog1_script_path);
            printf(" on %s\n", p1->usrlog1_computer);
            break;
         case NERR_StandaloneLogon:
            printf("Standalone logon\n");
            break;
         default:
            printf("No valid fields\n");
            break;
      }
      return;
   }

   //========================================================================
   //  For calls to NetWkstaSetUID2, two different return code variables

   //  are needed to determine whether structure elements in the return

   //  buffer contain valid data.

   //  ProcessAccessDenied examines the usrlog1_code element of the
   //  user_logon_info_1 data structure when NetWkstaSetUID2, called
   with a
   //  non-null username, returns the return code value ERROR_ACCESS_DENIED.
   //========================================================================

   void ProcessAccessDenied(struct user_logon_info_1 *p1)
   {
      printf("Logon code = %hu\n", p1->usrlog1_code);
      switch (p1->usrlog1_code)
      {
         case NERR_PasswordExpired:
            printf("Password expired\n");
            break;
         case NERR_InvalidWorkstation:
            printf("Invalid workstation\n");
            break;
         case NERR_InvalidLogonHours:
            printf("Invalid logon hours\n");
            break;
         case NERR_LogonScriptError:
            printf("Logon script error\n");
            break;
         case ERROR_ACCESS_DENIED:
            printf("Access denied\n");
            break;
         default:
            printf("No valid fields\n");
            break;
      }
      return;
   }

   void Usage(char * pszString)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] [-d domain]", pszString);
      fprintf(stderr, " [-l level]\n\t[-u username] [-p password]");
      fprintf(stderr, " [-f logoff force]\n");
      exit(1);
   }








 Appendix A  Return Codes
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 This appendix lists the return codes for Microsoft LAN Manager API
 functions. The first section presents a table that groups the return codes
 by class. The second section lists (in ascending order) the return codes,
 values, and meanings as defined in the BSEERR.H and NETERR.H header files.


 Return Codes by Class

 To help you quickly identify the general cause of an error, Microsoft LAN
 Manager error codes are organized as related classes of errors defined
 within specific ranges of numbers. For example, an error code in the range
 2100 through 2144 is a general network error. An error code in the range
 2180 through 2199 is a Service category API error.

 The following table is designed as a quick reference. It lists the ranges of
 error code values, the classes of errors within the ranges, and the header
 file in which the errors are defined. For specific information about each
 error message, see the second section, "LAN Manager and MS OS/2 Return
 Codes."

ÖÚÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Value      Class                           Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0          Success                         NETERR.H

 1-249      MS OS/2 or Redirector           BSEERR.H and
                                            NETERR.H

 2100-2144  General network error           NETERR.H

 2145-2149  Configuration                   NETERR.H

 2150-2179  Spooler                         NETERR.H

 2180-2199  Service                         NETERR.H

 2200-2218  Workstation and Logon           NETERR.H

 2219-2249  Access, User, and Group         NETERR.H

 Value      Class                           Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 2250-2269  Use                             NETERR.H

 2270-2309  Message Server                  NETERR.H

 2310-2329  Server                          NETERR.H

 2330-2349  Character Device                NETERR.H

 2350-2369  Input/Output                    NETERR.H

 2370-2376  Profile                         NETERR.H

 2377-2379  Audit and Error Log             NETERR.H

 2380-2399  Remote                          NETERR.H

 2400-2429  Workstation                     NETERR.H

 Value      Class                           Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 2430-2439  Alerter                         NETERR.H

 2440-2443  Audit and Error Log             NETERR.H

 2450-2459  User Accounts Subsystem (UAS)   NETERR.H
            and Logon

 2460-2469  Server Integration              NETERR.H

 2480-2484  Uninterruptable Power Supply    NETERR.H
            (UPS)

 2500-2519  Remoteboot                      NETERR.H

 2525-2534  FTADMIN                         NETERR.H

 2999       Last error in NERR range        NETERR.H

 Value      Class                           Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 LAN Manager and MS OS/2 Return Codes

 When a LAN Manager API function is successful, or when it encounters a LAN
 Manager or MS OS/2 error, the function returns one of the following codes.
 The return codes are listed here in ascending order, by value. Only the most
 commonly encountered MS OS/2 error codes are listed here. For a complete
 list of MS OS/2 error codes, see your MS OS/2 programming manual(s).

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0      The function encountered no
                                          errors.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         errors.

 ERROR_INVALID_FUNCTION            1      The function is invalid.

 ERROR_FILE_NOT_FOUND              2      The file was not found.

 ERROR_PATH_NOT_FOUND              3      The path was not found.

 ERROR_TOO_MANY_OPEN_FILES         4      The maximum number of
                                          open files was exceeded.

 ERROR_ACCESS_DENIED               5      The user has insufficient
                                          privilege for this operation.

 ERROR_INVALID_HANDLE              6      The handle specified is invalid.

 ERROR_ARENA_TRASHED               7      The MS-DOS memory arena was
                                          destroyed by an invalid memory
                                          access operation.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         access operation.

 ERROR_NOT_ENOUGH_MEMORY           8      Insufficient memory is available.

 ERROR_INVALID_BLOCK               9      The memory block is not part of a
                                          valid arena header.

 ERROR_BAD_ENVIRONMENT             10     The environment is invalid.

 ERROR_BAD_FORMAT                  11     The format is invalid.

 ERROR_INVALID_ACCESS              12     The access specified is invalid.

 ERROR_INVALID_DATA                13     The data specified is invalid.

 ERROR_INVALID_DRIVE               15     The drive specified is invalid.

 ERROR_CURRENT_DIRECTORY           16     The current directory specified
                                          is invalid.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         is invalid.

 ERROR_NOT_SAME_DEVICE             17     Cannot rename a file from one
                                          volume to another.

 ERROR_NO_MORE_FILES               18     No more files are available.

 ERROR_WRITE_PROTECT               19     Write protection is enabled.

 ERROR_BAD_UNIT                    20     The device driver command
                                          specified an illegal unit.

 ERROR_NOT_READY                   21     The drive is not ready.

 ERROR_BAD_COMMAND                 22     The command specified is invalid.

 ERROR_CRC                         23     A cyclic redundancy check failed
                                          while getting data from the disk.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_BAD_LENGTH                  24     The length specified is invalid.

 ERROR_SEEK                        25     The seek operation specified is
                                          invalid.

 ERROR_NOT_DOS_DISK                26     This is not an MS-DOS or MS OS/2
                                          formatted disk.

 ERROR_SECTOR_NOT_FOUND            27     The sector was not found.

 ERROR_OUT_OF_PAPER                28     The printer is out of paper.

 ERROR_WRITE_FAULT                 29     An error was encountered while
                                          writing data.

 ERROR_READ_FAULT                  30     An error was encountered while
                                          reading data.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_GEN_FAILURE                 31     General failure was encountered.

 ERROR_SHARING_VIOLATION           32     A sharing violation occurred.

 ERROR_LOCK_VIOLATION              33     A file lock violation occurred.

 ERROR_WRONG_DISK                  34     The wrong disk was specified.

 ERROR_FCB_UNAVAILABLE             35     The FCB specified could not be
                                          regenerated.

 ERROR_SHARING_BUFFER_EXCEEDED     36     More file record locks were
                                          applied to a file than the
                                          sharing code allows.

 ERROR_NOT_SUPPORTED               50     This network request is not
                                          supported.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_REM_NOT_LIST                51     The remote computer is not
                                          listening.

 ERROR_DUP_NAME                    52     A duplicate name exists on
                                          the network.

 ERROR_BAD_NETPATH                 53     The network path was not found.

 ERROR_NETWORK_BUSY                54     The network is busy.

 ERROR_DEV_NOT_EXIST               55     This device does not exist on the
                                          network.

 ERROR_TOO_MANY_CMDS               56     The NetBIOS command limit was
                                          reached.

 ERROR_ADAP_HDW_ERR                57     A network adapter hardware error
                                          occurred.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         occurred.

 ERROR_BAD_NET_RESP                58     The network responded incorrectly.

 ERROR_UNEXP_NET_ERR               59     An unexpected network error
                                          occurred.

 ERROR_BAD_REM_ADAP                60     The remote adapter is not
                                          compatible with the local adapter.

 ERROR_PRINTQ_FULL                 61     The printer queue is full.

 ERROR_NO_SPOOL_SPACE              62     Space is not available on the
                                          server to store the file waiting
                                          to be printed.

 ERROR_PRINT_CANCELLED             63     The requested print file has been
                                          canceled.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_NETNAME_DELETED             64     The network name was deleted.

 ERROR_NETWORK_ACCESS_DENIED       65     Network access is denied.

 ERROR_BAD_DEV_TYPE                66     The network resource type is not
                                          correct.

 ERROR_BAD_NET_NAME                67     The network name was not found.

 ERROR_TOO_MANY_NAMES              68     The name limit for the local
                                          computer network adapter card was
                                          exceeded.

 ERROR_TOO_MANY_SESS               69     The NetBIOS session limit was
                                          exceeded.

 ERROR_SHARING_PAUSED              70     File sharing is temporarily
                                          paused.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         paused.

 ERROR_REQ_NOT_ACCEP               71     The network request cannot be
                                          accepted at this time. There may
                                          be a lack of resources on the
                                          specified server or on the local
                                          workstation.

 ERROR_REDIR_PAUSED                72     Print or disk redirection is
                                          temporarily paused.

 ERROR_FILE_EXISTS                 80     The file already exists.

 ERROR_DUP_FCB                     81     Too many network redirections
                                          occurred.

 ERROR_CANNOT_MAKE                 82     The file cannot be created.

 ERROR_FAIL_I24                    83     The user replied "Fail" to a hard
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_FAIL_I24                    83     The user replied "Fail" to a hard
                                          error popup in MS-DOS.

 ERROR_OUT_OF_STRUCTURES           84     There are too many network
                                          redirections.

 ERROR_ALREADY_ASSIGNED            85     The network drive is already
                                          redirected.

 ERROR_INVALID_PASSWORD            86     The password specified is invalid.

 ERROR_INVALID_PARAMETER           87     The parameter specified is
                                          invalid.

 ERROR_NET_WRITE_FAULT             88     A network data fault occurred.

 ERROR_NO_PROC_SLOTS               89     No process slots are available.

 ERR_TSTOVFL                       91     A Timer service table overflow
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERR_TSTOVFL                       91     A Timer service table overflow
                                          occurred.

 ERR_TSTDUP                        92     A Timer service table duplicate
                                          exists.

 ERROR_NO_ITEMS                    93     There were no items on which to
                                          operate.

 ERROR_INTERRUPT                   95     The system call was interrupted.

 ERROR_TOO_MANY_SEMAPHORES         100    Too many semaphores were
                                          requested.

 ERROR_EXCL_SEM_ALREADY_OWNED      101    An exclusive semaphore is already
                                          owned.

 ERROR_SEM_IS_SET                  102    An error occurred while setting
                                          the semaphore.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         the semaphore.

 ERROR_TOO_MANY_SEM_REQUESTS       103    Too many semaphore requests were
                                          specified.

 ERROR_INVALID_AT_INTERRUPT_TIME   104    A device helper request, illegal
                                          at interrupt time, was issued at
                                          interrupt time.

 ERROR_SEM_OWNER_DIED              105    The process that owned the
                                          semaphore terminated.

 ERROR_SEM_USER_LIMIT              106    Too many processes have this
                                          semaphore.

 ERROR_DISK_CHANGE                 107    Insert disk B into drive A.

 ERROR_DRIVE_LOCKED                108    The drive was locked by another
                                          process.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         process.

 ERROR_BROKEN_PIPE                 109    The pipe has been closed or the
                                          pipe is not being read.

 ERROR_OPEN_FAILED                 110    An open or create operation
                                          failed.

 ERROR_BUFFER_OVERFLOW             111    The buffer passed to the system
                                          call is too small to hold the
                                          return data.

 ERROR_DISK_FULL                   112    There is not enough space on the
                                          disk.

 ERROR_NO_MORE_SEARCH_HANDLES      113    Cannot allocate another search
                                          structure and handle.

 ERROR_INVALID_TARGET_HANDLE       114    The target handle in DosDupHandle
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_INVALID_TARGET_HANDLE       114    The target handle in DosDupHandle
                                          is invalid.

 ERROR_PROTECTION_VIOLATION        115    The user virtual address is
                                          invalid.

 ERROR_VIOKBD_REQUEST              116    The keyboard request is invalid.

 ERROR_INVALID_CATEGORY            117    The category for DosDevIOCtl is
                                          not defined.

 ERROR_INVALID_VERIFY_SWITCH       118    An invalid value was passed for
                                          the verify flag.

 ERROR_BAD_DRIVER_LEVEL            119    DosDevIOCtl cannot find a level 4
                                          driver.

 ERROR_SEM_TIMEOUT                 121    A time-out occurred from the
                                          Semaphore API functions.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         Semaphore API functions.

 ERROR_INSUFFICIENT_BUFFER         122    The input buffer is too small.

 ERROR_INVALID_NAME                123    The character or file system name
                                          is invalid.

 ERROR_INVALID_LEVEL               124    The level for information
                                          retrieval or setting is invalid.

 ERROR_NO_VOLUME_LABEL             125    No volume label was given with
                                          the DosQFSInfo function.

 ERROR_MOD_NOT_FOUND               126    The specified tracepoint object
                                          does not exist.

 ERROR_PROC_NOT_FOUND              127    The specified procedure was not
                                          found.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_WAIT_NO_CHILDREN            128    DosCwait found no child processes.

 ERROR_CHILD_NOT_COMPLETE          129    DosCwait child processes have not
                                          yet ended.

 ERROR_DIRECT_ACCESS_HANDLE        130    The handle operation is invalid
                                          for direct disk access handles.

 ERROR_NEGATIVE_SEEK               131    The application tried to seek
                                          with a negative offset.

 ERROR_SEEK_ON_DEVICE              132    The application tried to seek on
                                          a device or a pipe.

 ERROR_IS_JOIN_TARGET              133    A join command error occurred.

 ERROR_IS_JOINED                   134    A join command error occurred.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_IS_SUBSTED                  135    A substitute command error
                                          occurred.

 ERROR_NOT_JOINED                  136    A join command error occurred.

 ERROR_NOT_SUBSTED                 137    A substitute command error
                                          occurred.

 ERROR_JOIN_TO_JOIN                138    A join command error occurred.

 ERROR_SUBST_TO_SUBST              139    A substitute command error
                                          occurred.

 ERROR_JOIN_TO_SUBST               140    A join or substitute command
                                          error occurred.

 ERROR_SUBST_TO_JOIN               141    A join or substitute command
                                          error occurred.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         error occurred.

 ERROR_BUSY_DRIVE                  142    The drive is busy.

 ERROR_SAME_DRIVE                  143    The same drive was specified.

 ERROR_DIR_NOT_ROOT                144    The directory provided is not the
                                          root of the drive.

 ERROR_DIR_NOT_EMPTY               145    The directory is not empty.

 ERROR_IS_SUBST_PATH               146    A substitute command error
                                          occurred.

 ERROR_IS_JOIN_PATH                147    A join command error occurred.

 ERROR_PATH_BUSY                   148    The path is busy.

 ERROR_IS_SUBST_TARGET             149    A substitute command error
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_IS_SUBST_TARGET             149    A substitute command error
                                          occurred.

 ERROR_SYSTEM_TRACE                150    A system trace error occurred.

 ERROR_INVALID_EVENT_COUNT         151    DosMuxSemWait errors occurred.

 ERROR_TOO_MANY_MUXWAITERS         152    Too many mutual waits occurred.

 ERROR_INVALID_LIST_FORMAT         153    The list format is invalid.

 ERROR_LABEL_TOO_LONG              154    The label is too long.

 ERROR_TOO_MANY_TCBS               155    Too many threads have been
                                          created.

 ERROR_SIGNAL_REFUSED              156    The signal was refused.

 ERROR_DISCARDED                   157    The segment has been discarded.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_DISCARDED                   157    The segment has been discarded.

 ERROR_NOT_LOCKED                  158    The segment is not locked.

 ERROR_BAD_THREADID_ADDR           159    The thread ID or address is
                                          invalid.

 ERROR_BAD_ARGUMENTS               160    The arguments specified are
                                          invalid.

 ERROR_BAD_PATHNAME                161    The pathname is invalid.

 ERROR_SIGNAL_PENDING              162    A loader error occurred.

 ERROR_UNCERTAIN_MEDIA             163    A loader error occurred.

 ERROR_MAX_THRDS_REACHED           164    A loader error occurred.

 ERROR_MONITORS_NOT_SUPPORTED      165    A loader error occurred.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_MONITORS_NOT_SUPPORTED      165    A loader error occurred.

 ERROR_INVALID_SEGMENT_NUMBER      180    A loader error occurred.

 ERROR_INVALID_CALLGATE            181    A loader error occurred.

 ERROR_INVALID_ORDINAL             182    A loader error occurred.

 ERROR_ALREADY_EXISTS              183    A loader error occurred.

 ERROR_NO_CHILD_PROCESS            184    A loader error occurred.

 ERROR_CHILD_ALIVE_NOWAIT          185    A loader error occurred.

 ERROR_INVALID_FLAG_NUMBER         186    A loader error occurred.

 ERROR_SEM_NOT_FOUND               187    A loader error occurred.

 ERROR_INVALID_STARTING_CODESEG    188    A loader error occurred.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_INVALID_STARTING_CODESEG    188    A loader error occurred.

 ERROR_INVALID_STACKSEG            189    A loader error occurred.

 ERROR_INVALID_MODULETYPE          190    A loader error occurred.

 ERROR_INVALID_EXE_SIGNATURE       191    A loader error occurred.

 ERROR_EXE_MARKED_INVALID          192    A loader error occurred.

 ERROR_BAD_EXE_FORMAT              193    A loader error occurred.

 ERROR_ITERATED_DATA_EXCEEDS_64k   194    A loader error occurred.

 ERROR_INVALID_MINALLOCSIZE        195    A loader error occurred.

 ERROR_DYNLINK_FROM_INVALID_RING   196    A loader error occurred.

 ERROR_IOPL_NOT_ENABLED            197    A loader error occurred.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_IOPL_NOT_ENABLED            197    A loader error occurred.

 ERROR_INVALID_SEGDPL              198    A loader error occurred.

 ERROR_AUTODATASEG_EXCEEDS_64k     199    A loader error occurred.

 ERROR_RING2SEG_MUST_BE_MOVABLE    200    A loader error occurred.

 ERROR_RELOC_CHAIN_XEEDS_SEGLIM    201    A loader error occurred.

 ERROR_INFLOOP_IN_RELOC_CHAIN      202    A loader error occurred.

 ERROR_ENVVAR_NOT_FOUND            203    An environment variable error
                                          occurred.

 ERROR_NOT_CURRENT_CTRY            204    A country code error occurred.

 ERROR_FILENAME_EXCED_RANGE        206    The filename specified is invalid
                                          for the file system.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         for the file system.
                                          This code is returned when
                                          checking a FAT disk partition
                                          only. It cannot be returned for
                                          an HPFS partition.

 ERROR_META_EXPANSION_TOO_LONG     208    Expanding the wildcard (*)
                                          resulted in a path that is too
                                          long.

 ERROR_INVALID_SIGNAL_NUMBER       209    An invalid signal number was
                                          passed.

 ERROR_BAD_PIPE                    230    This is a nonexistent pipe or an
                                          invalid operation.

 ERROR_PIPE_BUSY                   231    The specified pipe is busy.

 ERROR_NO_DATA                     232    There is no data to be read on a
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_NO_DATA                     232    There is no data to be read on a
                                          nonblocking read.

 ERROR_PIPE_NOT_CONNECTED          233    The server disconnected the pipe.

 ERROR_MORE_DATA                   234    Additional data is available.

 ERROR_VC_DISCONNECTED             240    The session was canceled.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 LAN Manager and MS OS/2 Return Codes (continued)

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_NetNotStarted                2102   The LAN Manager NETWKSTA driver
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_NetNotStarted                2102   The LAN Manager NETWKSTA driver
                                          is not installed.

 NERR_UnknownServer                2103   The server was not found.

 NERR_ShareMem                     2104   An internal error occurred; the
                                          network cannot access a shared
                                          memory segment.

 NERR_NoNetworkResource            2105   The network hardware could not
                                          access the resources it needed.

 NERR_RemoteOnly                   2106   This operation can be performed
                                          only on a server.

 NERR_DevNotRedirected             2107   The devicename is not assigned to
                                          a shared resource.

 NERR_ServerNotStarted             2114   The Server service is not started.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ServerNotStarted             2114   The Server service is not started.

 NERR_ItemNotFound                 2115   The queue is empty.

 NERR_UnknownDevDir                2116   The device or directory does not
                                          exist.

 NERR_RedirectedPath               2117   The operation is invalid for
                                          a redirected resource. The
                                          devicename specified is assigned
                                          to a shared resource.

 NERR_DuplicateShare               2118   The sharename is already in use
                                          on this server.

 NERR_NoRoom                       2119   The server could not access
                                          enough of a resource, such as
                                          memory, to complete the task.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_TooManyItems                 2121   The list of items in the command
                                          is too long, or
                                          the user is trying to share
                                          a second printer queue or
                                          communication-device
                                          queue on a workstation
                                          running Peer service.

 NERR_InvalidMaxUsers              2122   Peer service supports only two
                                          simultaneous users.

 NERR_BufTooSmall                  2123   The supplied buffer is too small.

 NERR_RemoteErr                    2127   A remote API error occurred.

 NERR_LanmanIniError               2131   The LANMAN.INI file is missing or
                                          contains invalid information.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_OS2IoctlError                2134   An internal error occurred in the
                                          NETWKSTA.SYS driver.

 NERR_NetworkError                 2136   A general failure occurred in the
                                          network hardware.

 NERR_WkstaNotStarted              2138   The Workstation service is not
                                          started.

 NERR_BrowserNotStarted            2139   The mailslots entry of the
                                          workstation's LANMAN.INI file is
                                          incorrect.

 NERR_InternalError                2140   An internal LAN Manager error
                                          occurred.

 NERR_BadTransactConfig            2141   The server is not configured for
                                          this transaction: IPC$ is not
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         this transaction: IPC$ is not
                                          shared.

 NERR_InvalidAPI                   2142   The requested API is not
                                          supported on the remote server.

 NERR_BadEventName                 2143   The event name is invalid.

 NERR_CfgCompNotFound              2146   The specified component in the
                                          LANMAN.INI file is not found.

 NERR_CfgParamNotFound             2147   The specified parameter in the
                                          LANMAN.INI file is not found.

 NERR_LineTooLong                  2149   A line in the LANMAN.INI file is
                                          too long.

 NERR_QNotFound                    2150   The queuename specified is
                                          invalid.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         invalid.

 NERR_JobNotFound                  2151   No print job matches the print
                                          job identification number typed.

 NERR_DestNotFound                 2152   The print destination was not
                                          found.

 NERR_DestExists                   2153   The print destination already
                                          exists.

 NERR_QExists                      2154   A printer queue with this name
                                          already exists.

 NERR_QNoRoom                      2155   The server does not have enough
                                          memory available
                                          to add another printer queue.

 NERR_JobNoRoom                    2156   The server does not have enough
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_JobNoRoom                    2156   The server does not have enough
                                          memory available
                                          to add another print job.

 NERR_DestNoRoom                   2157   The server does not have enough
                                          memory available
                                          to add another printer.

 NERR_DestIdle                     2158   The print destination is idle and
                                          cannot accept control operations.

 NERR_DestInvalidOp                2159   The print destination request
                                          contains an invalid control
                                          function.

 NERR_ProcNoRespond                2160   The print processor is not
                                          responding.

 NERR_SpoolerNotLoaded             2161   The spooler is not started.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_SpoolerNotLoaded             2161   The spooler is not started.

 NERR_DestInvalidState             2162   This operation cannot be
                                          performed on the print
                                          destination in its current state.

 NERR_QInvalidState                2163   This operation cannot be
                                          performed on the printer queue in
                                          its current state.

 NERR_JobInvalidState              2164   This operation cannot be
                                          performed on the print job in its
                                          current state.

 NERR_SpoolNoMemory                2165   A spooler memory allocation
                                          failure occurred.

 NERR_DriverNotFound               2166   The device driver specified
                                          has not been installed on the
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         has not been installed on the
                                          computer.

 NERR_DataTypeInvalid              2167   The datatype is not supported by
                                          the queue's print processor.

 NERR_ProcNotFound                 2168   The print processor has not been
                                          installed on the server.

 NERR_ServiceTableLocked           2180   The service does not respond to
                                          control actions.

 NERR_ServiceTableFull             2181   Another service cannot be started
                                          because the maximum number of
                                          services specified
                                          in the LANMAN.INI file has been
                                          reached.

 NERR_ServiceInstalled             2182   The requested service is already
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ServiceInstalled             2182   The requested service is already
                                          running.

 NERR_ServiceEntryLocked           2183   The service does not respond to
                                          control actions.

 NERR_ServiceNotInstalled          2184   The service is not running.

 NERR_BadServiceName               2185   The service name is invalid.

 NERR_ServiceCtlTimeout            2186   The service does not respond to
                                          the control function.

 NERR_ServiceCtlBusy               2187   The service control is not
                                          currently responding to requests.
                                          Another program
                                          may be controlling the service
                                          or there may be a software
                                          problem.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         problem.

 NERR_BadServiceProgName           2188   The LANMAN.INI file has
                                          associated a service with a
                                          nonexistent program file.

 NERR_ServiceNotCtrl               2189   The service is not currently
                                          accepting requests. If the
                                          service is starting, it cannot
                                          process requests until it is
                                          fully started.

 NERR_ServiceKillProc              2190   The service was not running
                                          properly and would not respond to
                                          a command. The service was
                                          terminated.

 NERR_ServiceCtlNotValid           2191   The command is invalid for this
                                          service, or the service cannot
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         service, or the service cannot
                                          accept the command right now.

 NERR_AlreadyLoggedOn              2200   A user is already logged on at
                                          this workstation.

 NERR_NotLoggedOn                  2201   The user must log on to the
                                          network before performing this
                                          operation.

 NERR_BadUsername                  2202   The username or groupname is
                                          invalid.

 NERR_BadPassword                  2203   The password is invalid.

 NERR_UnableToAddName_W            2204   Warning: The logon processor did
                                          not add the message alias.

 NERR_UnableToAddName_F            2205   Failure: The logon processor did
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_UnableToAddName_F            2205   Failure: The logon processor did
                                          not add the message alias.

 NERR_UnableToDelName_W            2206   Warning: The logoff processor did
                                          not delete the message alias.

 NERR_UnableToDelName_F            2207   Failure: The logoff processor did
                                          not delete the message alias.

 NERR_LogonsPaused                 2209   The Netlogon service is paused.

 NERR_LogonServerConflict          2210   The Netlogon service cannot be
                                          started on this server because a
                                          server in this domain with an
                                          earlier version of LAN Manager is
                                          running the Netlogon service.

 NERR_LogonNoUserPath              2211   The userpath entry in the
                                          server's LANMAN.INI file does not
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         server's LANMAN.INI file does not
                                          list a valid directory.

 NERR_LogonScriptError             2212   An error occurred while loading
                                          or running the logon script.

 NERR_StandaloneLogon              2214   The logon was not validated
                                          by a logon server. The
                                          computer will be logged on
                                          as STANDALONE.

 NERR_LogonServerNotFound          2215   No domain controller is
                                          responding to the command.

 NERR_LogonDomainExists            2216   A logon domain already exists for
                                          this workstation.

 NERR_NonValidatedLogon            2217   The logon server is running an
                                          earlier version of LAN Manager
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         earlier version of LAN Manager
                                          and cannot validate the logon.

 NERR_ACFNotFound                  2219   LAN Manager could not find the
                                          user accounts database
                                          file, NET.ACC. This file should
                                          be in the ACCOUNTS subdirectory
                                          of the LANMAN directory.

 NERR_GroupNotFound                2220   The groupname was not found.

 NERR_UserNotFound                 2221   The username was not found.

 NERR_ResourceNotFound             2222   The resource name was not found.

 NERR_GroupExists                  2223   The groupname already exists.

 NERR_UserExists                   2224   The user account already exists.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_ResourceExists               2225   The resource access record
                                          already exists.

 NERR_NotPrimary                   2226   The specified server is not the
                                          primary domain controller, so its
                                          UAS database cannot be updated.

 NERR_ACFNotLoaded                 2227   The user accounts database is not
                                          active. This database must be
                                          active for the command
                                          to run.

 NERR_ACFNoRoom                    2228   The user accounts database
                                          is full.

 NERR_ACFFileIOFail                2229   A disk I/O failure occurred.

 NERR_ACFTooManyLists              2230   Each resource can have no more
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ACFTooManyLists              2230   Each resource can have no more
                                          than 64 access records defined.

 NERR_UserLogon                    2231   The user currently has a session
                                          with the server.

 NERR_ACFNoParent                  2232   No permissions have been assigned
                                          for the parent directory.

 NERR_CanNotGrowSegment            2233   The user accounts database has
                                          reached its size limit. Nothing
                                          can be added to it.

 NERR_SpeGroupOp                   2234   This operation is not allowed on
                                          this special group.

 NERR_NotInCache                   2235   The user is not cached in the UAS
                                          session cache.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_UserInGroup                  2236   The user already belongs to this
                                          group.

 NERR_UserNotInGroup               2237   The user is not a member of this
                                          group.

 NERR_AccountUndefined             2238   The user account is undefined.

 NERR_AccountExpired               2239   The user account has expired.

 NERR_InvalidWorkstation           2240   The user is not allowed to log on
                                          from this workstation.

 NERR_InvalidLogonHours            2241   The user is not allowed to log on
                                          at this time.

 NERR_PasswordExpired              2242   The user's password has expired.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_PasswordCantChange           2243   The user's password cannot be
                                          changed.

 NERR_PasswordHistConflict         2244   The password cannot be used now.

 NERR_PasswordTooShort             2245   The password is too short.

 NERR_PasswordTooRecent            2246   The password is too recent to be
                                          changed.

 NERR_InvalidDatabase              2247   The user accounts database file,
                                          NET.ACC, is corrupted.

 NERR_DatabaseUpToDate             2248   A server requested an update
                                          of the user accounts database,
                                          even though no update was
                                          required.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_SyncRequired                 2249   The local server's user accounts
                                          database is completely out of
                                          synchro- nization with that of
                                          the primary domain controller,
                                          so a complete synchroni-
                                          zation is needed.

 NERR_UseNotFound                  2250   This network connnection does not
                                          exist.

 NERR_BadAsgType                   2251   The asg_type is invalid.

 NERR_DeviceIsShared               2252   The device is currently being
                                          shared.

 NERR_NoComputerName               2270   A computername has not been
                                          configured.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_MsgAlreadyStarted            2271   The Messenger service is already
                                          running.

 NERR_MsgInitFailed                2272   The Messenger service failed to
                                          start.

 NERR_NameNotFound                 2273   The message alias cannot be
                                          located.

 NERR_AlreadyForwarded             2274   Messages for this alias are
                                          already being forwarded to
                                          another alias.

 NERR_AddForwarded                 2275   Message for this alias are being
                                          forwarded to another computer.

 NERR_AlreadyExists                2276   The message alias already exists
                                          on this computer.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         on this computer.

 NERR_TooManyNames                 2277   The maximum number of message
                                          aliases has been exceeded.

 NERR_DelComputerName              2278   A message alias that is also a
                                          computername cannot be deleted.

 NERR_LocalForward                 2279   Messages cannot be forwarded back
                                          to the same workstation.

 NERR_GrpMsgProcessor              2280   An error occurred when the
                                          workstation was receiving or
                                          processing a domain-wide message.

 NERR_PausedRemote                 2281   The message was sent, but
                                          the recipient has paused the
                                          Messenger service, so the message
                                          cannot be received.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         cannot be received.

 NERR_BadReceive                   2282   The remote workstation was unable
                                          to receive the message. The
                                          Workstation or Messenger service
                                          may not be running
                                          on that workstation, it may
                                          have been receiving another
                                          message when this message arrived,
                                          or its message buffer may be too
                                          small.

 NERR_NameInUse                    2283   The message alias is currently in
                                          use. Try again later.

 NERR_MsgNotStarted                2284   The Messenger service has not
                                          been started.

 NERR_NotLocalName                 2285   The message alias is not on the
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NotLocalName                 2285   The message alias is not on the
                                          local computer.

 NERR_NoForwardName                2286   The message alias no longer
                                          exists on the workstation that
                                          was receiving its forwarded
                                          messages. The alias may
                                          have been deleted at the
                                          workstation, or the workstation
                                          may have been restarted.

 NERR_RemoteFull                   2287   The message alias table on the
                                          remote workstation is full.

 NERR_NameNotForwarded             2288   Messages for this alias are not
                                          being forwarded.

 NERR_TruncatedBroadcast           2289   The broadcast message is
                                          too long. Only the first
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         too long. Only the first
                                          128 characters of the
                                          message were sent.

 NERR_InvalidDevice                2294   The devicename is invalid.

 NERR_WriteFault                   2295   A write fault occurred when
                                          writing to the message log file.

 NERR_DuplicateName                2297   The name specified is already in
                                          use as a message alias on the
                                          network.

 NERR_DeleteLater                  2298   The message alias will be deleted
                                          later.

 NERR_IncompleteDel                2299   The message alias was not
                                          successfully deleted from all
                                          networks.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         networks.

 NERR_MultipleNets                 2300   This operation is not supported
                                          on a computer that is on multiple
                                          networks.

 NERR_NetNameNotFound              2310   The sharename does not exist.

 NERR_DeviceNotShared              2311   The device is not shared.

 NERR_ClientNameNotFound           2312   The specified computer does not
                                          have a session with the server.

 NERR_FileIdNotFound               2314   There is no open file with this
                                          ID number.

 NERR_ExecFailure                  2315   A failure occurred when executing
                                          a remote administration command,
                                          probably because of a problem
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         probably because of a problem
                                          with the server's operating
                                          system configuration.

 NERR_TmpFile                      2316   A failure occurred when opening a
                                          remote temporary file.

 NERR_TooMuchData                  2317   The data returned from a remote
                                          administration command was
                                          truncated to 64K.

 NERR_DeviceShareConflict          2318   Requests cannot be routed from
                                          both a printer queue and a
                                          communication-device queue to the
                                          same device.

 NERR_BrowserTableIncomplete       2319   The information in the list of
                                          servers may be incorrect.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_NotLocalDomain               2320   The computer is not active in
                                          this domain.

 NERR_DevInvalidOpCode             2331   The operation is invalid for this
                                          device.

 NERR_DevNotFound                  2332   This device cannot be shared.

 NERR_DevNotOpen                   2333   The device is not open.

 NERR_BadQueueDevString            2334   The devicename list is invalid.

 NERR_BadQueuePriority             2335   The queue priority is invalid.

 NERR_NoCommDevs                   2337   There are no shared communication
                                          devices.

 NERR_QueueNotFound                2338   The sharename does not exist.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_QueueNotFound                2338   The sharename does not exist.

 NERR_BadDevString                 2340   The list of devices is invalid.

 NERR_BadDev                       2341   The devicename is invalid because
                                          it does not represent a physical
                                          device, or because the device
                                          hardware is faulty.

 NERR_InUseBySpooler               2342   The device is already used with a
                                          printer queue. It cannot be used
                                          with both printer queues and
                                          communication-device queues.

 NERR_CommDevInUse                 2343   The device is already used
                                          with a communication-device queue.
                                          It cannot be used with both
                                          communication-device queues and
                                          printer queues.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         printer queues.

 NERR_InvalidComputer              2351   The specified computername is
                                          invalid.

 NERR_MaxLenExceeded               2354   The string and prefix specified
                                          are too long.

 NERR_BadComponent                 2356   The path component is invalid.

 NERR_CantType                     2357   Cannot determine the type of
                                          input.

 NERR_TooManyEntries               2362   The buffer for types is too small.

 NERR_ProfileFileTooBig            2370   The profile is too large. Profile
                                          files cannot exceed 64K.

 NERR_ProfileOffset                2371   The start offset is out of range.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ProfileOffset                2371   The start offset is out of range.

 NERR_ProfileCleanup               2372   Loading the profile failed
                                          because one or more connections
                                          between the computer and other
                                          network computers are active. LAN
                                          Manager cannot delete current
                                          connections to network resources.

 NERR_ProfileUnknownCmd            2373   The system was unable to parse
                                          the command line in
                                          this file.

 NERR_ProfileLoadErr               2374   An error occurred while loading
                                          the profile file.

 NERR_ProfileSaveErr               2375   Errors occurred while saving the
                                          profile file. The profile was
                                          partially saved.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         partially saved.

 NERR_LogOverflow                  2377   The log file is too big.

 NERR_LogFileChanged               2378   The log file has changed since it
                                          was last read.

 NERR_LogFileCorrupt               2379   The log file is corrupt.

 NERR_SourceIsDir                  2380   The source path specified is a
                                          directory name, which is not
                                          allowed.

 NERR_BadSource                    2381   The source path is invalid.

 NERR_BadDest                      2382   The destination pathname does not
                                          exist.

 NERR_DifferentServers             2383   The source and destination paths
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_DifferentServers             2383   The source and destination paths
                                          are on different servers.

 NERR_RunSrvPaused                 2385   The server is paused and cannot
                                          run a program or command.

 NERR_ErrCommRunSrv                2389   An error occurred when
                                          communicating with a run server.

 NERR_ErrorExecingGhost            2391   An error occurred when starting a
                                          background process.

 NERR_ShareNotFound                2392   The shared resource was not found.

 NERR_InvalidLana                  2400   The LAN adapter number in the
                                          LANMAN.INI file is incorrect.

 NERR_OpenFiles                    2401   There are open files or requests
                                          pending on this connection.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         pending on this connection.

 NERR_ActiveConns                  2402   Active connections still exist.

 NERR_BadPasswordCore              2403   The sharename or password is
                                          invalid.

 NERR_DevInUse                     2404   The drive specified is the
                                          current drive of an MS OS/2
                                          session.

 NERR_LocalDrive                   2405   The drive letter is in use
                                          locally and cannot be used for a
                                          shared resource.

 NERR_AlertExists                  2430   A program requested to be
                                          notified by the alerter of an
                                          event for which it is already
                                          receiving notifications.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         receiving notifications.

 NERR_TooManyAlerts                2431   The number of alert notifications
                                          requested exceeded the number
                                          specified by the numalerts entry
                                          in the LANMAN.INI file.

 NERR_NoSuchAlert                  2432   An invalid or nonexistent
                                          alertname was raised.

 NERR_BadRecipient                 2433   The alert recipient is invalid.

 NERR_AcctLimitExceeded            2434   The user has stayed logged on
                                          past the logon hour limit.

 NERR_InvalidLogSeek               2440   The log file does not contain the
                                          requested record number.

 NERR_BadUasConfig                 2450   The user accounts database is not
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadUasConfig                 2450   The user accounts database is not
                                          configured correctly.

 NERR_InvalidUASOp                 2451   The operation is not allowed
                                          while the Netlogon service is
                                          running.

 NERR_LastAdmin                    2452   The operation is not allowed on
                                          the last account with admin
                                          privilege.

 NERR_DCNotFound                   2453   The domain controller for this
                                          domain was not found.

 NERR_LogonTrackingError           2454   The logon server cannot update
                                          the logon or logoff information
                                          for this user.

 NERR_NetlogonNotStarted           2455   The Netlogon service is not
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_NetlogonNotStarted           2455   The Netlogon service is not
                                          running.

 NERR_CanNotGrowUASFile            2456   The user accounts database cannot
                                          be enlarged because the server's
                                          hard disk is full.

 NERR_NoSuchServer                 2460   The server ID does not specify a
                                          valid server.

 NERR_NoSuchSession                2461   The session ID does not specify a
                                          valid session.

 NERR_NoSuchConnection             2462   The connection ID does not
                                          specify a valid connection.

 NERR_TooManyServers               2463   There is no space for another
                                          entry in the table of available
                                          servers.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         servers.

 NERR_TooManySessions              2464   The server has reached the
                                          maximum number of sessions it
                                          supports.

 NERR_TooManyConnections           2465   The server has reached the
                                          maximum number of connections it
                                          supports.

 NERR_TooManyFiles                 2466   The server cannot open more files
                                          because it has reached its
                                          maximum number.

 NERR_NoAlternateServers           2467   The server has no alternate
                                          servers registered.

 NERR_UPSDriverNotStarted          2480   The UPS service could not access
                                          the UPS driver (UPSDRV.OS2). The
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         the UPS driver (UPSDRV.OS2). The
                                          UPS driver may not be configured
                                          properly.

 NERR_BadDosRetCode                2500   The program below returned an
                                          MS-DOS error code:

 NERR_ProgNeedsExtraMem            2501   The program below needs more
                                          memory:

 NERR_BadDosFunction               2502   The program below called an
                                          unsupported MS-DOS function:

 NERR_RemoteBootFailed             2503   The workstation failed to boot.

 NERR_BadFileCheckSum              2504   The file below is corrupt.

 NERR_NoRplBootSystem              2505   No loader is specified in the
                                          boot-block definition file.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         boot-block definition file.

 NERR_RplLoadrNetBiosErr           2506   NetBIOS returned an error: The
                                          NCB and SMB are dumped above.

 NERR_RplLoadrDiskErr              2507   A disk I/O error occurred.

 NERR_ImageParamErr                2508   Image parameter substitution
                                          failed.

 NERR_TooManyImageParams           2509   Too many image parameters cross
                                          disk sector boundaries.

 NERR_NonDosFloppyUsed             2510   The image was not generated from
                                          an MS-DOS diskette formatted with
                                          /s.

 NERR_RplBootRestart               2511   Remoteboot will be restarted
                                          later.
 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                         later.

 NERR_RplSrvrCallFailed            2512   The call to the Remoteboot server
                                          failed.

 NERR_CantConnectRplSrvr           2513   Cannot connect the work- station
                                          to the Remoteboot server.

 NERR_CantOpenImageFile            2514   Cannot open an image file on the
                                          Remoteboot server.

 NERR_CallingRplSrvr               2515   Connecting to the Remoteboot
                                          server...

 NERR_StartingRplBoot              2516   Connecting to the Remoteboot
                                          server...

 NERR_RplBootServiceTerm           2517   The Remoteboot service stopped.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RplBootStartFailed           2518   The Remoteboot service could not
                                          be started.

 NERR_RPL_CONNECTED                2519   A second connection to a
                                          Remoteboot resource is not
                                          allowed.

 NERR_FTNotInstalled               2525   The fault-tolerance device driver,
                                          DISKFT.SYS, is not installed.

 NERR_FTMONITNotRunning            2526   FTMONIT is not running.

 NERR_FTDiskNotLocked              2527   FTADMIN could not lock the drive
                                          to perform the requested task.

 NERR_FTDiskNotAvailable           2528   Another process running on this
                                          computer has locked the drive.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_FTUnableToStart              2529   The verifier/correcter cannot be
                                          started.

 NERR_FTNotInProgress              2530   The verifier/correcter cannot be
                                          terminated because it is not
                                          started.

 NERR_FTUnableToAbort              2531   The verifier/correcter cannot be
                                          canceled.

 NERR_FTUnabletoChange             2532   The disk cannot be locked/
                                          unlocked.

 NERR_FTInvalidErrHandle           2533   The error handle is not
                                          recognized.

 NERR_FTDriveNotMirrored           2534   The drive is not mirrored.

 Code                              Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 MAX_NERR                          2999   This is the last error in NERR
                                          range.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ








 Appendix B  Upgrading LAN Manager 1.0 Applications
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 This appendix lists the LAN Manager 1.0 and LAN Manager 2.0 API functions,
 and describes changes from 1.0 to 2.0.

 The first part of this appendix provides a table of all API functions
 available with LAN Manager 1.0 and LAN Manager 2.0, noting functions that
 have changed since 1.0 and those that are likely to not be supported in
 future releases.

 The second part of this appendix lists LAN Manager 1.0 API functions that
 have been superseded by LAN Manager 2.0 API functions. It compares these LAN
 Manager 1.0 API functions with the LAN Manager 2.0 functions that supersede
 them. The LAN Manager superseded functions are still supported in this
 release, but they may not be supported in future releases. Details of the
 1.0 functions are provided here only for programmers who need to support
 existing applications, or who want to upgrade existing applications to use
 the new functionality available. It is recommended that you use the new
 functions for all new code.

 The final part of this appendix provides comprehensive details about those
 LAN Manager 1.0 functions that are very different from their LAN Manager 2.0
 counterparts.


 Table of API Changes

 This table lists the LAN Manager 1.0 and 2.0 API functions. It details which
 version(s) of LAN Manager supports the functions, and describes changes in
 functionality in LAN Manager 2.0 compared to LAN Manager 1.0. If there is no
 difference in functionality between the two versions, "No change" is noted
 in the "Comment" column.

 Only a brief description is provided for functions noted as "2.0 only." For
 full details about any LAN Manager 2.0-only function, see the description
 for that particular function in Chapter 2, "API Function Descriptions."

 When an API function is described as being "Obsolescent," this means it is
 supported by LAN Manager 2.0 but may not be supported by future releases. In
 most cases there is a new function that can be used instead of the old one.
 If a replacement function exists, it is noted in the "Comment" column.

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Access Permissions Category

 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAccessAdd                     1.0, 2.0  No longer requires the Server
                                            service.

 NetAccessCheck                   1.0, 2.0  No longer requires the Server
                                            service.

 NetAccessDel                     1.0, 2.0  No longer requires the Server
                                            service.

 NetAccessEnum                    1.0, 2.0  Obsolescent.

 NetAccessGetInfo                 1.0, 2.0  No longer requires the Server
                                            service.

 NetAccessGetUserPerms            2.0 only  Gets access permissions for a
                                            specific resource.

 NetAccessSetInfo                 1.0, 2.0  No longer requires the Server
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NetAccessSetInfo                 1.0, 2.0  No longer requires the Server
                                            service.

 Alert Category

 NetAlertRaise                    1.0, 2.0  No change.

 NetAlertStart                    1.0, 2.0  No change.

 NetAlertStop                     1.0, 2.0  No change.

 Audit Category

 NetAuditClear                    1.0, 2.0  No change.

 NetAuditOpen                     1.0, 2.0  Obsolescent; use NetAuditRead
                                            to read the audit log.

 NetAuditRead                     2.0 only  Reads the audit log;
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NetAuditRead                     2.0 only  Reads the audit log;
                                            independent of the internal
                                            format of the log.

 NetAuditWrite                    1.0, 2.0  No change.

 Character Device Category

 NetCharDevControl                1.0, 2.0  Comm operator privilege added.

 NetCharDevEnum                   1.0, 2.0  No change.

 NetCharDevGetInfo                1.0, 2.0  No change.

 NetCharDevQEnum                  1.0, 2.0  No change.

 Character Device Category (
 continued)

 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetCharDevQGetInfo               1.0, 2.0  No change.

 NetCharDevQPurge                 1.0, 2.0  Comm operator privilege added.

 NetCharDevQPurgeSelf             1.0, 2.0  Comm operator privilege added.

 NetCharDevQSetInfo               1.0, 2.0  Comm operator privilege added.

 Configuration Category

 NetConfigGet                     1.0, 2.0  Obsolescent; use NetConfigGet2.


 NetConfigGetAll                  1.0, 2.0  Obsolescent; use
                                            NetConfigGetAll2.

 NetConfigGet2                    2.0 only  Remotable version of
                                            NetConfigGet; supports all
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                           NetConfigGet; supports all
                                            operator privileges.

 NetConfigGetAll2                 2.0 only  Remotable version of
                                            NetConfigGetAll; supports all
                                            operator privileges.

 Connection Category

 NetConnectionEnum                1.0, 2.0  Comm, print, and server
                                            operator privileges added.

 Domain Category

 NetGetDCName                     2.0 only  Gets the name of the domain
                                            controller.

 NetLogonEnum                     2.0 only  Gets information about the
                                            users currently logged on.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                           users currently logged on.

 Error Logging Category

 NetErrorLogClear                 1.0, 2.0  No change.

 NetErrorLogOpen                  1.0, 2.0  Obsolescent; use
                                            NetErrorLogRead to read the
                                            error log.

 NetErrorLogRead                  2.0 only  Reads the error log;
                                            independent of the internal
                                            format of the log.

 NetErrorLogWrite                 1.0, 2.0  No change.



 File Category
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
File Category

 NetFileClose                     1.0, 2.0  Obsolescent; use NetFileClose2.


 NetFileClose2                    2.0 only  Supports long file IDs and
                                            server operator privilege.

 NetFileEnum                      1.0, 2.0  Obsolescent; use NetFileEnum2.

 NetFileEnum2                     2.0 only  Supports long file IDs and
                                            server operator privilege.

 NetFileGetInfo                   1.0, 2.0  Obsolescent; use
                                            NetFileGetInfo2.

 NetFileGetInfo2                  2.0 only  Supports long file IDs and
                                            server operator privilege.

 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Group Category

 NetGroupAdd                      1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege and level 1 added.

 NetGroupAddUser                  1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege added.

 NetGroupDel                      1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege added.

 NetGroupDelUser                  1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege added.

 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetGroupEnum                     1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege and level 1 added.

 NetGroupGetInfo                  2.0 only  Gets group-related information.


 NetGroupGetUsers                 1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege and ability to list
                                            own groups added.

 NetGroupSetInfo                  2.0 only  Sets group information.

 NetGroupSetUsers                 2.0 only  Sets users for the specified
                                            group.

 Handle Category
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Handle Category

 NetHandleGetInfo                 2.0 only  Gets handle-specific
                                            information.

 NetHandleSetInfo                 2.0 only  Sets handle-specific
                                            information.



 Mailslot Category

 DosDeleteMailslot                1.0, 2.0  No change.

 DosMailslotInfo                  1.0, 2.0  No change.

 DosMakeMailslot                  1.0, 2.0  No change.

 DosPeekMailslot                  1.0, 2.0  No change.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
DosPeekMailslot                  1.0, 2.0  No change.

 DosReadMailslot                  1.0, 2.0  No change.

 DosWriteMailslot                 1.0, 2.0  Support for domains added.

 Message Category

 NetMessageBufferSend             1.0, 2.0  Support for all operator
                                            privileges and support for
                                            domains added.

 NetMessageFileSend               1.0, 2.0  Obsolescent.

 NetMessageLogFileGet             1.0, 2.0  Obsolescent.

 NetMessageLogFileSet             1.0, 2.0  Obsolescent.

 NetMessageNameAdd                1.0, 2.0  Obsolescent.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NetMessageNameAdd                1.0, 2.0  Obsolescent.

 NetMessageNameDel                1.0, 2.0  Obsolescent.

 NetMessageNameEnum               1.0, 2.0  Obsolescent.

 NetMessageNameFwd                1.0, 2.0  Obsolescent.

 NetMessageNameGetInfo            1.0, 2.0  Obsolescent.

 NetMessageNameUnFwd              1.0, 2.0  Obsolescent.

 Named Pipes Category

 DosBufReset                      1.0 only  Now in MS OS/2.

 DosCallNmPipe                    1.0 only  Now in MS OS/2.

 DosClose                         1.0 only  Now in MS OS/2.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
DosClose                         1.0 only  Now in MS OS/2.

 DosConnectNmPipe                 1.0 only  Now in MS OS/2.

 DosDisconnectNmPipe              1.0 only  Now in MS OS/2.

 DosDupHandle                     1.0 only  Now in MS OS/2.

 DosMakeNmPipe                    1.0 only  Now in MS OS/2.

 DosOpen                          1.0 only  Now in MS OS/2.

 DosPeekNmPipe                    1.0 only  Now in MS OS/2.

 DosQFHandState                   1.0 only  Now in MS OS/2.

 Named Pipes Category (continued)

 DosQHandType                     1.0 only  Now in MS OS/2.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
DosQHandType                     1.0 only  Now in MS OS/2.

 DosQNmpHandState                 1.0 only  Now in MS OS/2.

 DosQNmPipeInfo                   1.0 only  Now in MS OS/2.

 DosQNmPipeSemState               1.0 only  Now in MS OS/2.

 NetBIOS Category

 NetBiosClose                     1.0, 2.0  No change.

 NetBiosEnum                      1.0, 2.0  No change.

 NetBiosGetInfo                   1.0, 2.0  No change.

 NetBiosOpen                      1.0, 2.0  No change.

 NetBiosSubmit                    1.0, 2.0  No change.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NetBiosSubmit                    1.0, 2.0  No change.

 NetSpecialSMB                    1.0 only  No longer supported.

 Print Destination Category

 DosPrintDestAdd                  2.0 only  Adds a print destination.

 DosPrintDestControl              1.0, 2.0  Print operator privilege added.


 DosPrintDestDel                  2.0 only  Deletes a print destination.

 DosPrintDestEnum                 1.0, 2.0  Print operator privilege and
                                            levels 2
                                            and 3 added.

 DosPrintDestGetInfo              1.0, 2.0  Print operator privilege and
                                            levels 2
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                           levels 2
                                            and 3 added.

 DosPrintDestSetInfo              2.0 only  Modifies configuration of print
                                            destination.

 DosPrintDestStatus               1.0 only  No longer supported.

 Print Job Category

 DosPrintJobContinue              1.0, 2.0  Print operator privilege added.


 DosPrintJobDel                   1.0, 2.0  Print operator privilege added.


 DosPrintJobEnum                  1.0, 2.0  Levels 2 and 3 added.

 DosPrintJobGetId                 1.0, 2.0  No change.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
DosPrintJobGetId                 1.0, 2.0  No change.

 DosPrintJobGetInfo               1.0, 2.0  Levels 2 and 3 added.

 Print Job Category (continued)

 DosPrintJobPause                 1.0, 2.0  Print operator privilege added.


 DosPrintJobSetInfo               1.0, 2.0  Print operator privilege and
                                            level 3 added.

 Printer Queue Category

 DosPrintQAdd                     1.0, 2.0  Print operator privilege and
                                            level 3
                                            added.

 DosPrintQContinue                1.0, 2.0  Print operator privilege added.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
DosPrintQContinue                1.0, 2.0  Print operator privilege added.


 DosPrintQDel                     1.0, 2.0  Print operator privilege added.


 DosPrintQEnum                    1.0, 2.0  Levels 3, 4, and 5 added.

 DosPrintQGetInfo                 1.0, 2.0  Levels 3, 4, and 5 added.

 DosPrintQPause                   1.0, 2.0  Print operator privilege added.


 DosPrintQPurge                   1.0, 2.0  Print operator privilege added.


 DosPrintQSetInfo                 1.0, 2.0  Print operator privilege and
                                            level 3
                                            added.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                           added.

 Profile Category

 NetProfileLoad                   1.0, 2.0  Obsolescent; not documented.

 NetProfileSave                   1.0, 2.0  Obsolescent; not documented.

 Remote Utility Category

 NetRemoteCopy                    1.0, 2.0  No change.

 NetRemoteExec                    1.0, 2.0  No change.

 NetRemoteMove                    1.0, 2.0  No change.

 NetRemoteTOD                     1.0, 2.0  No change.

 Server Category
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Server Category

 NetServerAdminCommand            1.0, 2.0  No change.

 NetServerDiskEnum                1.0, 2.0  No longer requires the Server
                                            service; server operator
                                            privilege added.

 NetServerEnum                    1.0, 2.0  Obsolescent; use NetServerEnum2.



 Server Category
 (continued)

 NetServerEnum2                   2.0 only  Enumerates servers of specified
                                            types in specified domains.

 NetServerGetInfo                 1.0, 2.0  Support for all operator
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NetServerGetInfo                 1.0, 2.0  Support for all operator
                                            privileges and level 3 added.

 NetServerSetInfo                 1.0, 2.0  Server operator privilege and
                                            level 3 added.

 Service Category

 NetServiceControl                1.0, 2.0  Admin-only restriction removed;
                                            server operator privilege added.


 NetServiceEnum                   1.0, 2.0  Admin-only restriction removed.


 NetServiceGetInfo                1.0, 2.0  Admin-only restriction removed.


 NetServiceInstall                1.0, 2.0  Server operator privilege added.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NetServiceInstall                1.0, 2.0  Server operator privilege added.


 NetServiceStatus                 1.0, 2.0  Admin-only restriction removed.


 Session Category

 NetSessionDel                    1.0, 2.0  Server operator privilege added.


 NetSessionEnum                   1.0, 2.0  Admin-only restriction removed;
                                            server operator privilege and
                                            levels 2 and 10 added.

 NetSessionGetInfo                1.0, 2.0  Admin-only restriction removed;
                                            server operator privilege and
                                            levels 2 and 10 added.

 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Share Category

 NetShareAdd                      1.0, 2.0  Server, print, and comm
                                            operator privileges added.

 NetShareCheck                    1.0, 2.0  No change.

 NetShareDel                      1.0, 2.0  Server, print, and comm
                                            operator privileges added.

 NetShareEnum                     1.0, 2.0  Server, print, and comm
                                            operator privileges added.

 Share Category
 (continued)

 NetShareGetInfo                  1.0, 2.0  Server, print, and comm
                                            operator privileges added.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                           operator privileges added.

 NetShareSetInfo                  1.0, 2.0  Server, print, and comm
                                            operator privileges added.

 Statistics Category

 NetStatisticsClear               1.0, 2.0  Obsolescent; use
                                            NetStatisticsGet2.

 NetStatisticsGet                 1.0, 2.0  Obsolescent; use
                                            NetStatisticsGet2.

 NetStatisticsGet2                2.0 only  Separates Workstation and
                                            Server service statistics;
                                            allows clearing and reading in
                                            one operation.

 Use Category
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Use Category

 NetUseAdd                        1.0, 2.0  No change.

 NetUseDel                        1.0, 2.0  No change.

 NetUseEnum                       1.0, 2.0  No change.

 NetUseGetInfo                    1.0, 2.0  No change.

 User Category

 NetUserAdd                       1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege and level 2 added.

 NetUserDel                       1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege added.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                           privilege added.

 NetUserEnum                      1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege and levels 2 and 10
                                            added.

 NetUserGetGroups                 1.0, 2.0  No longer requires the Server
                                            service; admin-only restriction
                                            removed; accounts operator
                                            privilege added.

 NetUserGetInfo                   1.0, 2.0  No longer requires the Server
                                            service; admin-only restriction
                                            removed; accounts operator
                                            privilege and levels 2, 10, and
                                            11 added.

 User Category
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
User Category
 (continued)

 NetUserModalsGet                 2.0 only  Gets global information for all
                                            users.

 NetUserModalsSet                 2.0 only  Sets global information for all
                                            users.

 NetUserPasswordSet               1.0, 2.0  No longer requires the Server
                                            service.

 NetUserSetGroups                 2.0 only  Sets group membership for a
                                            user.

 NetUserSetInfo                   1.0, 2.0  No longer requires the Server
                                            service; accounts operator
                                            privilege and level 2 added.

 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserValidate                  1.0, 2.0  Obsolescent; use
                                            NetUserValidate2.

 NetUserValidate2                 2.0 only  Supports enhanced logon
                                            security features.

 Workstation Category

 NetWkstaAnnounce                 1.0 only  No longer supported.

 NetWkstaGetInfo                  1.0, 2.0  Admin-only restriction removed;
                                            support for all operator
                                            privileges and levels 1 and 10
                                            added.

 NetWkstaInit                     1.0 only  Internal; no longer supported.

 NetWkstaLogoff                   1.0 only  Internal; no longer supported.
 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NetWkstaLogoff                   1.0 only  Internal; no longer supported.

 NetWkstaLogon                    1.0 only  Internal; no longer supported.

 NetWkstaReInit                   1.0 only  Internal; no longer supported.

 NetWkstaReLogon                  1.0 only  Internal; no longer supported.

 NetWkstaSetInfo                  1.0, 2.0  Level 1 added.

 NetWkstaSetUID                   1.0, 2.0  Obsolescent; use
                                            NetWkstaSetUID2.

 NetWkstaSetUID2                  2.0 only  Provides more information on
                                            the logon/logoff operation;
                                            supports logoff force level.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Function                         Version   Comment
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Superseded API Functions

 The LAN Manager 1.0 API functions described here have been superseded by LAN
 Manager 2.0 API functions. This section gives brief details of the new
 functionality available in the LAN Manager 2.0 functions. For a complete
 description of the new functions, see Chapter 2, "API Function
 Descriptions."

 In most cases the new functions are similar to their LAN Manager 1.0
 counterparts, but have increased functionality. The new versions of these
 functions often have the same name as the earlier version, but with a "2"
 appended to their names. In a few cases, the functions have been superseded
 by functions that provide a better method of achieving the same result.

 These functions have been superseded by LAN Manager 2.0 functions:

 NetAuditOpen
   Superseded by NetAuditRead, which opens, reads, and closes the audit log
   file, allowing applications to access audit log files without regard for
   filenames, location, or internal format, which might change in the future.
   NetAuditOpen is described in more detail later in this appendix.

 NetConfigGet and NetConfigGetAll
   Superseded by NetConfigGet2 and NetConfigGetAll2, which have two
   additional parameters (pszServer and pszReserved). The new functions can
   be executed on a remote server.

 NetErrorLogOpen
   Superseded by NetErrorLogRead, which opens, reads, and closes the error
   log file, allowing applications to access error log files without regard
   for filenames, location, or internal format, which might change in the
   future. NetErrorLogOpen is described in more detail later in this
   appendix.

 NetFileClose and NetFileGetInfo
   Superseded by NetFileClose2 and NetFileGetInfo2, which use an unsigned
   long file ID parameter instead of an unsigned short file ID. File IDs are
   not sequential. The new functions can access file IDs greater than 64K,
   necessary for machines using the high-performance file system (HPFS).

 NetFileEnum
   Superseded by NetFileEnum2, which has a pResumeKey parameter that enables
   it to return more file information than will fit into the data buffer in
   one call.

 NetServerEnum
   Superseded by NetServerEnum2, which has two new parameters (flServerType
   and pszDomain). These parameters specify the type of server and the domain
   to which the enumerated servers must belong.

 NetStatisticsClear and NetStatisticsGet
   Superseded by NetStatisticsGet2, which provides all the functionality
   available in the earlier version functions, but in a more flexible form.
   NetStatisticsClear and NetStatisticsGet are described in more detail later
   in this appendix.

 NetUserValidate
   Superseded by NetUserValidate2, which supports LAN Manager 2.0 enhanced
   logon security features. NetUserValidate is described in more detail later
   in this appendix.

 NetWkstaSetUID
   Superseded by NetWkstaSetUID2, which provides data structures for logon
   and logoff information. NetWkstaSetUID is described in more detail later
   in this appendix.


 Superseded Function Descriptions

 The following section contains reference pages for the LAN Manager 1.0
 functions that have been superseded by LAN Manager 2.0 functions.


 NetAuditOpen
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetAuditOpen opens and returns a file handle to a server's audit log file.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 NetAuditOpen is superseded in LAN Manager 2.0; use NetAuditRead for new
 applications that must read the audit log.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, remote only

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetAuditOpen on a remote
 server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETAUDIT
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetAuditOpen (const char far *  pszServer,
                 unsigned far *    phAuditLog,
                 char far *        pszReserved
                );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetAuditOpen. A null pointer or null string specifies the local
   computer.

 phAuditLog
   Points to the returned file handle for the audit log.

 pszReserved
   Reserved; must be a null pointer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_OPEN_FAILED                 110     An open or create operation
                                           failed.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Clearing the audit log            NetAuditClear

 Reading an entry from the audit   NetAuditRead
 log

 Writing an entry to the audit     NetAuditWrite
 log


 NetErrorLogOpen
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetErrorLogOpen opens and returns a file handle to a computer's error log
 file.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 NetErrorLogOpen is superseded in LAN Manager 2.0; use NetErrorLogRead for
 new applications that must read the error log.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetErrorLogOpen on a
 remote server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETERRORLOG
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetErrorLogOpen (const char far *  pszServer,
                    unsigned far *    phErrorLog,
                    char far *        pszReserved
                   );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetErrorLogOpen. A null pointer or null string specifies the
   local computer.

 phErrorLog
   Points to the returned file handle for the error log.

 pszReserved
   Reserved; must be a null pointer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_PATH_NOT_FOUND              3       The path was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_SHARING_VIOLATION           32      A sharing violation occurred.

 ERROR_NOT_SUPPORTED               50      This network request is not
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 ERROR_OPEN_FAILED                 110     An open or create operation
                                           failed.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_RemoteOnly                   2106    This operation can be performed
                                           only on a server.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Clearing the error log            NetErrorLogClear

 Reading an entry from the error   NetErrorLogRead
 log

 Writing an entry to the error     NetErrorLogWrite
 log


 NetStatisticsClear
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetStatisticsClear clears the operating statistics for a workstation or
 server, resetting all numeric and time statistics to 0 (including those
 NetStatisticsGet cannot retrieve).

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 NetStatisticsClear is superseded in LAN Manager 2.0; use NetStatisticsGet2
 for new applications.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetStatisticsClear on a
 remote server or on a computer that has local security enabled.


 Syntax

   #define INCL_NETSTATS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetStatisticsClear (const char far *  pszServer);

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetStatisticsClear. A null pointer or null string specifies the
   local computer.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_ServerNotStarted             2114    The Server service is not
                                           started.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Clearing statistics for a         NetStatisticsGet2
 service

 Retrieving statistics for a       NetStatisticsGet2
 service


 NetStatisticsGet
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetStatisticsGet retrieves a computer's operating statistics.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 NetStatisticsGet is superseded in LAN Manager 2.0; use NetStatisticsGet2 for
 new applications.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local and remote

   þ   MS OS/2 version 1.1, local and remote

   þ   MS-DOS, remote only



 Privilege Level

 Admin privilege is required to successfully execute NetStatisticsGet on a
 remote server.


 Syntax

   #define INCL_NETSTATS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetStatisticsGet (const char far *      pszServer,
                     char far *            pbBuffer,
                     unsigned short        cbBuffer,
                     unsigned short far *  pcbReturned,
                     unsigned short far *  pcbTotalAvail
                    );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetStatisticsGet. A null pointer or null string specifies the
   local computer.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a statistics_info_0 data structure.

 cbBuffer
   Specifies the size (in bytes) of the data buffer pointed to by pbBuffer.

 pcbReturned
   Points to an unsigned short integer in which a count of the number of
   bytes of information read into the buffer is returned. This count is valid
   only if NetStatisticsGet returns NERR_Success or NERR_BufTooSmall.

 pcbTotalAvail
   Points to an unsigned short integer in which a count of the total number
   of bytes of information available is returned. This count is valid only if
   NetStatisticsGet returns NERR_Success or NERR_BufTooSmall.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          started.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetStatisticsGet returns the following data structure:

   struct statistics_info_0 {
       unsigned long  st0_start;
       unsigned long  st0_wknumNCBs;
       unsigned long  st0_wkfiNCBs;
       unsigned long  st0_wkfcNCBs;
       unsigned long  st0_wksesstart;
       unsigned long  st0_wksessfail;
       unsigned long  st0_wkuses;
       unsigned long  st0_wkusefail;
       unsigned long  st0_wkautorec;
       unsigned long  st0_rdrnumNCBs;
       unsigned long  st0_svrnumNCBs;
       unsigned long  st0_usrnumNCBs;
       unsigned long  st0_reserved4;
       unsigned long  st0_reserved5;
       unsigned long  st0_reserved6;
       unsigned long  st0_reserved7;
       unsigned long  st0_reserved8;
       unsigned long  st0_svfopens;
       unsigned long  st0_svdevopens;
       unsigned long  st0_svjobsqueued;
       unsigned long  st0_svsopens;
       unsigned long  st0_svstimedout;
       unsigned long  st0_svserrorout;
       unsigned long  st0_svpwerrors;
       unsigned long  st0_svpermerrors;
       unsigned long  st0_svsyserrors;
       unsigned long  st0_svbytessent;
       unsigned long  st0_svbytesrcvd;
       unsigned long  st0_svavresponse;
   };

 where

 st0_start
   Specifies the time when statistics collection started and when the
   statistics were last cleared. The value is stored as the number of seconds
   elapsed since 00:00:00, January 1, 1970. To calculate the length of time
   that statistics have been collected, subtract this value from the present
   time.

 st0_wknumNCBs
   Specifies the total number of network control blocks (NCBs) issued on the
   workstation.

 st0_wkfiNCBs
   Specifies the number of submitted NCBs that failed for any reason.

 st0_wkfcNCBs
   Specifies the number of NCBs that failed after being issued, at or before
   completion.

 st0_wksesstart
   Specifies the number of workstation sessions that were started.

 st0_wksessfail
   Specifies the number of workstation sessions that failed.

 st0_wkuses
   Specifies the number of workstation connections that were started.

 st0_wkusefail
   Specifies the number of workstation connections that failed.

 st0_wkautorec
   Specifies the number of times the workstation automatically reconnected.

 st0_rdrnumNCBs
   Specifies the number of redirector NCBs issued.

 st0_srvnumNCBs
   Specifies the number of server NCBs issued.

 st0_usrnumNCBs
   Specifies the number of user NCBs issued.

 st0_reserved4 through st0_reserved8
   Reserved; must be unsigned long integers with a value of -1.

 st0_svfopens
   Specifies the number of files opened on the server.

 st0_svdevopens
   Specifies the number of communication devices opened on the server.

 st0_svjobsqueued
   Specifies the number of print jobs spooled on the server.

 st0_svsopens
   Specifies the number of sessions started on the server.

 st0_svstimedout
   Specifies the number of sessions disconnected automatically due to
   time-out on the server.

 st0_svserrorout
   Specifies the number of sessions disconnected due to an error on the
   server.

 st0_svpwerrors
   Specifies the number of password violations the server encountered.

 st0_svpermerrors
   Specifies the number of access permission errors the server encountered.

 st0_svsyserrors
   Specifies the number of system errors the server encountered.

 st0_svbytessent
   Specifies the number of bytes sent to the network from the server.

 st0_svbytesrcvd
   Specifies the number of bytes received from the network.

 st0_svavresponse
   Specifies the average response time (in milliseconds).

 For any of these parameters, a returned value of STATS_NO_VALUE means the
 statistic is not currently available. A return value of STATS_OVERFLOW
 indicates overflow.

 NetStatisticsGet returns as much of the statistics_info_0 data structure as
 the data buffer can hold. If more data is available, NetStatisticsGet
 returns the ERROR_MORE_DATA return code. Only complete dwords are returned.


 If an application calls NetStatisticsGet on a computer with only the
 Workstation service operating, NetStatisticsGet returns only data structure
 elements relevant to workstations. Elements beyond the value returned to the
 st0_reserved8 element are invalid, causing STATS_NO_VALUE to be returned.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Clearing statistics for a         NetStatisticsGet2
 service

 Dwords                            Statistics Category

 Retrieving statistics for a       NetStatisticsGet2
 service


 NetUserValidate
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetUserValidate verifies that there is an account with a particular username
 and password in the system. It does not check logon restrictions.

 If the account name and password combination is not correct, NetUserValidate
 delays for approximately three seconds before returning ERROR_ACCESS_DENIED.


 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 NetUserValidate is superseded in LAN Manager 2.0; use NetUserValidate2 for
 new applications.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1 not supported

   þ   MS-DOS not supported



 Privilege Level

 No special privilege level is required to execute NetUserValidate.


 Syntax

   #define INCL_NETUSER
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetUserValidate (char far *            pszReserved,
                    char far *            pszUserName,
                    char far *            pszPassword,
                    unsigned short far *  pusPrivilege
                   );

 where

 pszReserved
   Reserved; must be NULL.

 pszUserName
   Points to an ASCIIZ string that contains the name of the user whose
   account is to be verified.

 pszPassword
   Points to an ASCIIZ string that contains the password to be verified.

 pusPrivilege
   Points to an unsigned short integer in which the user's privilege is
   returned. The ACCESS.H header file defines these possible values:

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 USER_PRIV_GUEST  0      Guest privilege.
 USER_PRIV_USER   1      User privilege.
 USER_PRIV_ADMIN  2      Admin privilege.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_ACFNotLoaded                 2227    The user accounts database is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_ACFNotLoaded                 2227    The user accounts database is
                                           not active. This database must
                                           be active for the command to run.

 NERR_ACFFileIOFail                2229    A disk I/O failure occurred.

 NERR_InvalidDatabase              2247    The user accounts database file,
                                           NET.ACC, is corrupted.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 If the password is valid and the account is active, NetUserValidate returns
 the user's privilege level. If the password is not valid, the password is
 compared to the password of the guest user account (if the server is running
 with the guest account configured). If these match, the API returns
 USER_PRIV_GUEST privilege.

 If the guest user account has a null password, any password will match. If
 the specified user account has a null password, any value in the password
 field will match.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Guest account                     User Category

 Validating a user account and     NetUserValidate2
 checking logon restrictions


 NetWkstaSetUID
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetWkstaSetUID logs a user on to or off from the network, or changes a
 user's password.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 NetWkstaSetUID is superseded in LAN Manager 2.0; use NetWkstaSetUID2 for new
 applications.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS, local only



 Privilege Level

 No special privilege is required to successfully execute NetWkstaSetUID.


 Syntax

   #define INCL_NETWKSTA
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetWkstaSetUID (const char far *  pszReserved,
                   const char far *  pszUserName,
                   const char far *  pszPassword,
                   const char far *  pszParms,
                   unsigned short    fsLogOff
                  );

 where

 pszReserved
   Reserved; must be 0.

 pszUserName
   Points to an ASCIIZ string that contains the username. The pszUserName
   parameter determines whether a logon or logoff operation is performed. A
   null pointer or null string indicates a logoff operation. A non-null value
   indicates a logon operation.

 pszPassword
   Points to an ASCIIZ string that contains the logon password for the
   username pointed to by pszUserName. The value of pszPassword becomes the
   default password for the workstation and is used whenever the workstation
   attempts to access a remote resource.

 pszParms
   Reserved; must be set to a null string (" ").

 fsLogOff
   Specifies how to proceed with the logoff operation when another user is
   currently logged on. The WKSTA.H header file defines these possible
   values:

 Code                 Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 WKSTA_NOFORCE        0      NetWkstaSetUID fails.

 WKSTA_FORCE          1      Do not log off the current user if
                             the user has pending activities on redirected
                             resources or is using the resource as the
                             current drive.

 WKSTA_LOTS_OF_FORCE  2      Do not log off the current user if a user
                             process uses the resource as the current drive.

 WKSTA_MAX_FORCE      3      Log off the current user under any conditions.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_INVALID_FUNCTION            1       The function is invalid.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_WkstaNotStarted              2138    The Workstation service is not
                                           started.

 NERR_BadUsername                  2202    The username or groupname is
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NERR_BadUsername                  2202    The username or groupname is
                                           invalid.

 NERR_BadPassword                  2203    The password is invalid.

 NERR_UnableToAddName_W            2204    Warning: The logon processor did
                                           not add the message alias.

 NERR_UnableToAddName_F            2205    Failure: The logon processor did
                                           not add the message alias.

 NERR_UnableToDelName_W            2206    Warning: The logoff processor
                                           did not delete the message alias.

 NERR_UnableToDelName_F            2207    Failure: The logoff processor
                                           did not delete the message alias.

 NERR_StandaloneLogon              2214    The logon was not validated by a
                                           logon server. The computer will
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                          logon server. The computer will
                                           be logged on as STANDALONE.

 NERR_ActiveConns                  2402    Active connections still exist.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Logging on and off                NetWkstaSetUID2






 Appendix C  Creating LAN Manager Services
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 When an application is written as a service, a LAN Manager administrator has
 a standard, safe way to control the application. A LAN Manager service is an
 MS OS/2 application running in the background and controlled by the
 administrator through LAN Manager. A service guarantees data integrity
 because LAN Manager queries the status of the service before attempting any
 operation that might alter the status. A service also provides smooth
 integration with network management and operations.

 For example, think of an administrator who manages a medical database system
 that serves a number of clients. These clients enter and retrieve data for
 their patients through the system. At some point, the administrator decides
 that the server in the system must be shut down for maintenance. After
 logging off all users, the administrator decides to stop all network
 activity to prevent any new logons. What happens if the database application
 is in the middle of a critical update? If the application is written as a
 service, LAN Manager queries the service and informs the administrator of
 its status, allowing the necessary procedures to finish before shutting
 down.

 The Alerter, Messenger, Netlogon, Netpopup, Netrun, Peer, Remoteboot,
 Replicator, Server, Timesource, UPS, and Workstation services represent
 important subsystems of the network system. These services all have admin
 privilege on the local computer. Any application written as a service has
 this privilege.

 Services have these requirements:


   þ   The service's executable file must be listed in the [services] section
       of the LANMAN.INI file.

   þ   The service must not call screen or keyboard functions; this can be
       done indirectly by calling a popup function (for example, the MS OS/2
       VioPopUp function).

   þ   So that other applications can respond correctly to any change, the
       service must dynamically notify LAN Manager about a change in its
       status by calling the NetServiceStatus function.

   þ   The service must respond to signals sent by the NetServiceControl
       function by changing its current state of operation. Other
       applications use NetServiceControl to manipulate the service.



 A Simple Service

 To illustrate the requirements for writing a service, this appendix contains
 a simple example service that waits for an alert from a client program and
 then displays a popup window when the alert is received. For more
 information about alerts, see the Alert category API functions in Chapter 2,
 "API Function Descriptions."

 Fragments from the example service are used throughout this appendix. The
 service is listed in its entirety, with the companion program, at the end of
 this appendix. The example service must be compiled as a multithread
 program. For information about how to compile and link the example service,
 see the comments at the top of the program, and see Appendix D, "Building
 the Sample Programs."

 Once built, the example service can be started by adding an entry to the
 LANMAN.INI file and using the net start command or the NetServiceInstall
 function. Running the companion program when the service is started causes
 the service to display a popup message. For more information about
 installing and starting LAN Manager services, see your LAN Manager
 administrator's manual(s).


 How a Service Works

 Any MS OS/2 application that does not use Presentation Manager can run as a
 service. To convert an application into a service, you must add start-up
 code and a signal handler. The start-up code processes command-line and
 LANMAN.INI parameters, installs the signal handler, and starts the
 application. A service's start-up code should do the following:


   1.  Call the NetServiceStatus function with the SERVICE_INSTALL_PENDING
       opcode to notify applications that the service is not yet ready for
       use.

   2.  Verify any command-line parameters passed to the service by the
       calling process.

   3.  Start a signal handler to interpret opcodes passed by requesting
       applications.

   4.  Start the application code, possibly as another thread.

   5.  Call the NetServiceStatus function with the SERVICE_INSTALLED opcode
       to notify LAN Manager that installation is complete.


 One of the start-up code's functions is to install a signal handler. The
 signal handler makes the service a safe application. The signal handler
 processes requests that can drastically change the state of the service, and
 it provides information on demand about the status of a service. A service's
 signal handler should do the following:


   1.  Determine what request is being made.

   2.  Process that request.


 The remainder of this appendix describes the start-up code and signal
 handler in detail.


 Installing a Service

 A service can be started by a user through the command-line or full-screen
 interface, or it can be started by an application using NetServiceInstall.

 Before an application can start the service, a service's executable file
 must be listed in the [services] section of the LANMAN.INI file. For
 example, before the example service can be started, the following line
 should exist in the [services] section of the computer's LANMAN.INI file:

   popalrt = services\service.exe

 The name on the left of the equal sign (=) is the name LAN Manager uses to
 refer to the service. The name (in this case, popalrt) given to the net
 start command or to NetServiceInstall must match this name. The path on the
 right of the equal sign must specify the location of the service's
 executable file. This can be specified as a full path or as a path relative
 to the LAN Manager root directory.

 Both NetServiceInstall and the user interfaces use the MS OS/2 DosExecPgm
 function to execute the service in detached mode. This prevents handles from
 being passed to child processes and prevents screen and keyboard-oriented
 calls except through popup functions. This also means that a service
 inherits the environment of its parent process.


 Reporting Installation Status

 The NetServiceStatus function uses the service_status data structure. This
 structure contains an element for the status word, an error code (if there
 is an error), the process identification number of the service, and a text
 string. For a complete description of each element in the service_status
 data structure, see the Service category in Chapter 2, "API Function
 Descriptions."

 The following sections discuss some of the things you should consider when
 using the service_status data structure.


 Using the Status Bit Masks

 A service should report three kinds of information in the svcs_status
 element: the service's ability to uninstall, its ability to pause, and its
 current status. A service's ability to uninstall and to pause are static
 properties of the service; its current status is dynamic. The following
 example shows how the svcs_status information is used:

   ssStatus.svcs_status = SERVICE_INSTALL_PENDING |
                          SERVICE_NOT_UNINSTALLABLE |
                          SERVICE_NOT_PAUSABLE;
   ssStatus.svcs_code = SERVICE_UIC_NORMAL;

   uReturnCode = NetServiceStatus((char far *) &ssStatus, sizeof(ssStatus));

 Initially, the service combines the SERVICE_INSTALL_PENDING,
 SERVICE_NOT_PAUSABLE, and SERVICE_NOT_UNINSTALLABLE bit masks in the
 svcs_status element. Later, when the service completes installation, it uses
 the SERVICE_INSTALLED bit mask. If it is uninstallable, it also uses
 SERVICE_UNINSTALLABLE; if it can be paused, it uses SERVICE_PAUSABLE. Note
 that a service can report itself as uninstallable and pausable only after it
 is installed.

 A pausable service must also use SERVICE_PAUSED when it pauses. Similarly,
 an uninstallable service must use SERVICE_UNINSTALL_PENDING and
 SERVICE_UNINSTALLED when it uninstalls.

 The example service places SERVICE_UIC_NORMAL in the svcs_code element of
 the service_status data structure because the service is only reporting a
 change in state. If it were reporting an error, the service would place an
 error code in this element.

 When reporting errors, a service can also send text to NetServiceStatus with
 the svcs_text element of the service_status data structure. When the service
 is not reporting an error, this element should be set to a null pointer.


 Reporting the ID of the Main Process

 The example service uses the MS OS/2 DosGetPID function to place the process
 identification number of its main process in a global variable, as shown in
 the following example:

   uReturnCode = DosGetPID(&pidInfo);
   if (uReturnCode != NERR_Success)
   {
      sprintf(szErrBuffer, MSGERRGETPID, uReturnCode);
      ErrOut(uReturnCode, szErrBuffer);
   }
   ssStatus.svcs_pid = pidInfo.pid;

 After this point, whenever the service calls NetServiceStatus, it simply
 places the value in the svcs_pid element of the service_status data
 structure.

 This step is unnecessary if signal handler responsibilities will not be
 passed to another process. In this case, a process ID value of 0 can be
 used.


 Disabling Standard Input and Output

 Since a service runs in detached mode, it cannot access standard input and
 output data. For this reason, it is a good idea to map STDIN, STDOUT, and
 STDERR to the null device so that the application code calling these handles
 does not generate errors. Simply closing the standard handles is not
 effective. If the standard handles are closed and a spawned process opens a
 file, one of the standard handles is assigned to that file, and data
 intended for the file is sent to the standard devices instead. The following
 example shows how to map the standard handles to the null device:

   // Open the null device.
   uReturnCode = DosOpen("NUL",        // Name of device
                          &hFileNul,   // Handle
                          &usAction,   // Action taken
                          0L,          // File size
                          FILE_NORMAL, // File attribute
                          FILE_OPEN,   // Open action
                                       // Open mode
                          OPEN_ACCESS_READWRITE|OPEN_SHARE_DENYNONE,
                          0L);         // Reserved
   if (uReturnCode != NERR_Success)
   {
     sprintf(szErrBuffer, MSGERRDOSOPEN, uReturnCode);
     ErrOut(uReturnCode, szErrBuffer);
   }

   // Reroute stdin, stderr, and stderr to NUL.
   for (hNewHandle=0; hNewHandle < 3; hNewHandle++)
   {
       /*
        * Skip the duplicating operation if the handle already
        * points to NUL.
        */
       if (hFileNul != hNewHandle)
           DosDupHandle(hFileNul, &hNewHandle);
   }

 The example service uses the MS OS/2 DosDupHandle and DosOpen functions to
 save each handle and then map each standard handle to the null device. The
 example service also uses the MS OS/2 DosError function to disable hardware
 error popup messages.

 For more information about the DosDupHandle, DosError, and DosOpen
 functions, see your MS OS/2 programming manual(s).


 Parsing Service Parameters

 NetServiceInstall and the user interfaces pass LANMAN.INI parameters to the
 service in argv (argc contains the number of argv elements). The user
 interfaces add command-line or screen-selected parameters to argv;
 NetServiceInstall adds the contents of its cmdargs parameter to argv. For
 example, if the following command line is entered,

   net start popalrt /DECAF:yes

 and the following entry exists in the LANMAN.INI file,

   [popalrt]
       DECAF = yes

 the service code would receive one element of argv set to the string
 DECAF=yes.

 A service's start-up code should process parameters passed to the service.
 The following code from the example service provides a simple example of
 parameter parsing. A more elaborate parsing mechanism would be needed to
 handle multiple parameters.

   for (iCount = 1; iCount < argc; iCount++)
   {
      if (strnicmp(argv[iCount], pszDecaf, strlen(pszDecaf)) == 0)
      {   // Copy the string after equal sign.
         strcpy(szParmValue, argv[iCount]+strlen(pszDecaf)+1);
      }
      else
      {
         ssStatus.svcs_code |= SERVICE_UIC_AMBIGPARM;
         uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                        sizeof(ssStatus));
         sprintf(szErrBuffer, INVALIDPARAM, argv[iCount]);
         ErrOut(0, szErrBuffer);
      }
   }


 Reporting Errors

 If the parameters used when starting the service are invalid, the service
 should call the NetServiceStatus function with the svcs_status element of
 the service_status data structure set to SERVICE_UNINSTALLED. It should also
 place an error code describing the problem in the svcs_code element of the
 service_status data structure. To provide error information to the user, the
 service can record the error in an error log by calling the NetErrorLogWrite
 function, as shown in the following example:

   void ErrOut(unsigned short usErrCode, char far * psErrStr)
   {
      NetErrorLogWrite(NULL,                 // Reserved; must be NULL
                       usErrCode,            // Error code
                       DEFAULTCOMPONENTNAME, // Component name
                       NULL,                 // Pointer to raw data buffer
                       0,                    // Length of raw data buffer
                       psErrStr,             // String data
                       1,                    // Number of error strings
                       NULL);                // Reserved; must be NULL

      /*
       * If signal handler is installed, notify LAN Manager that
       * the service is exiting.
       */
      if (fSigStarted)
          ExitHandler();

 After reporting the errors, the service stops executing.


 Installing the Signal Handler

 Once the parameters are verified, the service should install a signal
 handler using the MS OS/2 DosSetSigHandler function. At the request of other
 applications, LAN Manager can uninstall, pause, continue, or query a
 service. Since these requests affect the status of the service, they are
 sent to the service as system signals. A service should use DosSetSigHandler
 to trap these signals. The following example shows how the example service
 does this:

   uReturnCode = DosSetSigHandler(SignalHandler,
                                  &pnPrevHandler,
                                  &pfPrevAction,
                                  SIGA_ACCEPT,
                                  SERVICE_RCV_SIG_FLAG);

   if (uReturnCode != NERR_Success)
   {
      sprintf(szErrBuffer, MSGERRCNTRLCSIGNAL, uReturnCode);
      ErrOut(uReturnCode, szErrBuffer);
   }

 In this example, the service uses the MS OS/2 DosSetSigHandler function to
 identify which signals it will reject, which signals it will ignore, and
 which signals it will accept. Signals that should not be sent to the example
 service are marked with SIGA_ERROR; signals that the example service ignores
 are marked with SIGA_IGNORE.

 The example service uses the SIGA_ACCEPT code to identify the SignalHandler
 function as the signal handler function. The SIGA_ACCEPT code also tells MS
 OS/2 that the service accepts signals from the flag identified by
 SERVICE_RCV_SIG_FLAG. The SERVICE_RCV_SIG_FLAG flag contains the name of the
 process flag LAN Manager uses for service signals. For more information
 about DosSetSigHandler and its codes, see your MS OS/2 programming
 manual(s).


 Spawning the Application Thread

 It is recommended that all services to be run with MS OS/2 have at least two
 threads: one thread to run the signal handler and one thread to run the main
 body of the application code. With two threads, signals can receive prompt
 attention, and the application code is not interrupted in untimely ways due
 to signals. The example service spawns an application thread, as shown in
 the following example:

   pbStack = (PBYTE) SafeMalloc(DEFAULT_STACK_SIZE);
   tThreadTid = _beginthread(AlertHandler,
                             pbStack,
                             DEFAULT_STACK_SIZE,
                             NULL);

   if (tThreadTid == -1)
   {
      sprintf(szErrBuffer, MSGERRBEGINTHREAD, tThreadTid);
      ErrOut(0, szErrBuffer);
   }

 In this example, the service uses the _beginthread function to spawn its
 application thread. The SafeMalloc function is described in Appendix D,
 "Building the Sample Programs."

 If the service spawns an application thread that requires some
 initialization time, it should wait for a semaphore to be cleared by the
 application thread before proceeding. The application thread should clear
 this semaphore after completing its initialization. (The example service
 does not do this because the application thread does not take a significant
 amount of time to initialize.)

 If a service includes more than one process, the process that the DosExecPgm
 function initially executes (referred to as the main service process) is the
 only process that receives the standard signals. The main service process is
 also the only one that can issue calls to the NetServiceStatus function.

 A service can transfer the responsibilities of the main service process to
 another process by setting the svcs_pid element of the service_status data
 structure to the process ID of the main service process candidate.

 For more information about DosCreateThread, DosExecPgm, and semaphores, see
 your MS OS/2 programming manual(s).


 Using Checkpoints

 NetServiceStatus provides a "checkpoint" ability for services that take a
 long time (more than a few seconds) to install or uninstall. The example
 service does not use this feature because it does not take a significant
 amount of time to install. If you start a service from the command line that
 uses checkpoint information, a message like this is displayed on the screen
 (where POPALRT is the name of the service that is starting):

   The POPALRT service is starting...

 A service sends checkpoint information by calling NetServiceStatus
 periodically during installation or uninstallation. When a service uses
 checkpoints, the service_status data structure elements must be set as
 follows:


   þ   The svcs_status element must be set to SERVICE_INSTALL_PENDING or
       SERVICE_UNINSTALL_PENDING.

   þ   The most significant word of the svcs_code element must be set to 0.

   þ   The upper eight bits of the least significant word of the svcs_code
       element must contain the approximate time the application takes to
       install, in tenths of a second (0.1 second).

   þ   The lower eight bits of the least significant word of the svcs_code
       element must contain a checkpoint number.


 A checkpoint number is simply an unsigned short integer that a service
 increments once before each checkpoint call to NetServiceStatus.

 A service uses the SERVICE_UIC_CODE macro to set the proper bits in the
 status word. The service then combines this value with the
 SERVICE_INSTALL_PENDING bit mask to form the whole argument before calling
 NetServiceStatus.

 For more information about using checkpoints, see the Service category in
 Chapter 2, "API Function Descriptions."


 Completing Installation

 Once the application thread is initialized, the service should call
 NetServiceStatus with the SERVICE_INSTALLED opcode to notify other
 applications that it is ready for use. The example service does this, as
 shown here:

   ssStatus.svcs_status = SERVICE_INSTALLED |
                          SERVICE_UNINSTALLABLE |
                          SERVICE_PAUSABLE;
   ssStatus.svcs_code = SERVICE_UIC_NORMAL;

   uReturnCode = NetServiceStatus((char far *) &ssStatus, sizeof(ssStatus));

 In addition to reporting itself as installed, the service changes its state
 to uninstallable and pausable. This prevents a second copy of the service
 from being installed, yet allows the current copy to be paused. Services
 that are uninstallable should set the SERVICE_NOT_UNINSTALLABLE status bit.


 At this point, the example service has two threads running. One thread waits
 for a dummy semaphore in an endless loop, as shown in the following example:


   uReturnCode = DosSemSet(&hSem);  // Set the semaphore

   if (uReturnCode != NERR_Success)
   {
      sprintf(szErrBuffer, MSGERRDOSSEMSET, uReturnCode);
      ErrOut(uReturnCode, szErrBuffer);
   }

   /*
    * The main thread waits on the RAM semaphore, but it is
    * interrupted whenever a signal comes. Loop over
    * DosSemWait if interrupted by a signal.
    */

   do {
      uReturnCode = DosSemWait(&hSem, SEM_INDEFINITE_WAIT);
      if (uReturnCode != ERROR_INTERRUPT)
      {
         sprintf(szErrBuffer, MSGERRDOSSEMWAIT, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }
   } while (uReturnCode == ERROR_INTERRUPT);

 The thread waiting for the dummy semaphore is interrupted when signals come
 to the signal handler. The second thread runs the main application code.

 Although it is possible to have the main thread simply execute an endless
 loop without waiting for a semaphore, or to have it sleep indefinitely, both
 of these methods use more CPU time than waiting for a dummy semaphore.
 Waiting for a dummy semaphore takes almost no resources at all, so it is the
 most efficient way to occupy the main thread when a signal is not being
 processed.


 Handling Signals

 When the system sends a status-changing request to the service, the main
 thread is interrupted and control goes to the signal handler. A service's
 signal handler function should always expect two unsigned short arguments:
 an opcode that describes the request and a number that identifies the
 process flag the signal was raised on.

 LAN Manager services can ignore the second argument since all LAN Manager
 service request signals are sent using the same process flag. For more
 information about system process flags, see your MS OS/2 programming
 manual(s).

 The signal handler should examine the first opcode to determine which
 request is being made. These are the four standard requests that LAN Manager
 sends to services:

 Code                              Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 SERVICE_CTRL_UNINSTALL            The service is requested to uninstall
                                   itself and terminate.

 SERVICE_CTRL_PAUSE                The service application is requested to
                                   suspend execution until it receives a
                                   SERVICE_CTRL_CONTINUE request.

 SERVICE_CTRL_CONTINUE             The service application is requested to
                                   resume execution after having been
                                   paused by a SERVICE_CTRL_PAUSE request.

 SERVICE_CTRL_INTERROGATE          LAN Manager requests information about
                                   the current status of the service.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 A service does not have to limit itself to processing only the four standard
 requests. Any value can be passed to the service as a request opcode. For
 example, a service could have a "delay" option (it could be told to pause
 for a certain amount of time and then restart on its own). To use this
 option, an application would send a special request opcode, perhaps
 SERVICE_CTRL_DELAY. The service would then check for this special opcode and
 process it accordingly.

 When a service does not recognize an opcode (the opcode is invalid), it
 should process the opcode as if it were SERVICE_CTRL_INTERROGATE.

 The signal handler for the sample service, shown in the following example,
 reads the opcode and performs various functions depending on the request
 being made:

   void far pascal SignalHandler(unsigned short usSigArg,
                                 unsigned short usSigNum)
   {
      unsigned uReturnCode;
      unsigned char fOpCode;
                                              // Compute the function
   code
      fOpCode = (unsigned char) (usSigArg & 0xFF);

      switch (fOpCode)                        // Do the function
      {
         case SERVICE_CTRL_UNINSTALL:         // Uninstall; end the service
            ExitHandler();
            DosExit(EXIT_PROCESS, 0);         // Stop this process
            break;

   case SERVICE_CTRL_PAUSE:             // Pause service
            DosSemSet(&hSemPause);            // Pause AlertHandler
            ssStatus.svcs_status = SERVICE_INSTALLED |
                                   SERVICE_PAUSED |
                                   SERVICE_UNINSTALLABLE|
                                   SERVICE_PAUSABLE;
            ssStatus.svcs_code = SERVICE_UIC_NORMAL;
            uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                           sizeof(ssStatus));
            break;
         case SERVICE_CTRL_CONTINUE:          // Continue service
            DosSemClear(&hSemPause);          // Continue AlertHandler
            ssStatus.svcs_status = SERVICE_INSTALLED |
                                   SERVICE_ACTIVE |
                                   SERVICE_UNINSTALLABLE|
                                   SERVICE_PAUSABLE;
            ssStatus.svcs_code = SERVICE_UIC_NORMAL;
            uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                           sizeof(ssStatus));
            break;
         case SERVICE_CTRL_INTERROGATE:       // Give service status
         default:
            uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                           sizeof(ssStatus));
            break;
      }

   /*
       * Reenable signal handling. This signal handler will accept the

       * next signal raised on usSigNum.
       */
      uReturnCode = DosSetSigHandler(0,
                             0,
                             0,
                             SIGA_ACKNOWLEDGE,
                             usSigNum);
      return;
   }

 In this example, the signal handler strips all but the lower eight bits from
 the opcode, then performs the appropriate action. The following sections
 describe the various actions that a service signal handler performs.

 After processing the request, the example service reenables itself by
 calling DosSetSigHandler again and passing 0 for all parameters except the
 action and signal number parameters. For more information about
 DosSetSigHandler, see your MS OS/2 programming manual(s).


 Pausing and Continuing a Service

 If the svcs_status element of the service_status data structure is set to
 the constant SERVICE_NOT_PAUSABLE, the service cannot be paused and
 SERVICE_CTRL_PAUSE is an invalid request. If the service can be paused and
 the signal handler receives a SERVICE_CTRL_PAUSE request, it requests the
 application thread to suspend itself, waits on a semaphore that the
 application clears when it is ready, and calls NetServiceStatus with the
 SERVICE_PAUSED code.

 When the signal handler receives a SERVICE_CTRL_CONTINUE request, it
 requests the application thread to continue. When the application thread is
 ready, the signal handler calls NetServiceStatus with the SERVICE_ACTIVE
 code, as shown in the preceding code sample.


 Querying a Service

 If the signal handler receives a SERVICE_CTRL_INTERROGATE request, it
 updates the service_status data structure and calls NetServiceStatus with
 the current information. The example service simply calls NetServiceStatus
 with the current service_status data structure, as shown in the preceding
 code sample.


 Uninstalling a Service

 If the svcs_status element of the service_status data structure is set to
 the constant SERVICE_NOT_UNINSTALLABLE, the service cannot be removed and
 the code SERVICE_CTRL_UNINSTALL is an invalid request. The following example
 shows how to process a valid uninstall request:

   void ExitHandler()
   {
      API_RET_TYPE uReturnCode;

      //Notify LAN Manager that the service will uninstall.
      ssStatus.svcs_status = SERVICE_UNINSTALL_PENDING |
                             SERVICE_UNINSTALLABLE |
                             SERVICE_NOT_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      uReturnCode = NetServiceStatus((char far *) &ssStatus,
 sizeof(ssStatus));

   // Exit processing would go here.

   /*
       * If the service has registered to receive alerts, deregister
   and
       * remove the alert semaphore or mailslot.
       */

   if (fAlertRegistered)
      {
         NetAlertStop(COFFEE_ALERT, ALERT_MAILBOX);
         DosDeleteMailslot(hMailSlot);
      }

      // Notify LAN Manager that the service is uninstalled.
      ssStatus.svcs_status = SERVICE_UNINSTALLED |
                             SERVICE_UNINSTALLABLE |
                             SERVICE_NOT_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      NetServiceStatus((char far *) &ssStatus, sizeof(ssStatus));
      return;
   }

 If the service is uninstallable and the signal handler receives a
 SERVICE_CTRL_UNINSTALL request, it calls NetServiceStatus with the
 SERVICE_UNINSTALL_PENDING code. A service should also request that the
 application thread finish its tasks and wait on a semaphore to be cleared by
 the application thread when it is finished. The example service does not do
 this because its application thread does not require any shutdown time.

 The signal handler then restores the standard handles (STDIN, STDOUT, and
 STDERR), calls NetServiceStatus with the SERVICE_UNINSTALLED code, and
 terminates the service.

 When uninstalling, a service can use checkpoints in combination with the
 opcode SERVICE_UNINSTALL_PENDING. Note that SERVICE_CTRL_UNINSTALL is the
 only request that the signal handler can process while the service is being
 installed (when the svcs_status element is set to SERVICE_INSTALL_PENDING).
 Any other request is invalid when the service is in this state.

 For information about other LAN Manager services and the functions used to
 control services, see the Service category in Chapter 2, "API Function
 Descriptions."





 Example Service

 The following is the complete code listing of the service used for the
 examples in this appendix. The service's companion program, ALERT.C, is also
 listed.

 The service and ALERT.C use alerts to communicate. For more information
 about alerts, see the Alert category in Chapter 2, "API Function
 Descriptions."

   /*   SERVICE.C - A sample service program that can be run with
   LAN Manager.


      Compile Instructions:
         This is a multithread application and should be compiled
         accordingly. Here are sample command-line sequences for
         Microsoft C compilers:

      Microsoft C 5.1:
         CL /c /AL SAMPLES.C
         LIB SAMPLES -+SAMPLES;
         CL /c /AL /I \PMTK\INCLUDE /I \C510\INCLUDE\MT SERVICE.C
         LINK /NOD /NOI SERVICE,,,LLIBCMT+DOSCALLS+LAN+SAMPLES;

         The directories after the /I switches on the compile line
         (\PMTK\INCLUDE and \C510\INCLUDE\MT) represent the MS OS/2
         Presentation Manager include file directory and the Microsoft

         C 5.1 multithread include directory, respectively. Substitute

         the correct pathnames for your Presentation Manager and
         multithread include directories.

      Microsoft C 6.0:
         CL /c /AL SAMPLES.C
         LIB SAMPLES -+SAMPLES;
         CL /c /AL /MT SERVICE.C
         LINK /NOD /NOI SERVICE,,,LLIBCMT+OS2+LAN+SAMPLES;

      Note that with both Microsoft C 5.1 and Microsoft C 6.0 you must
      build SAMPLES.LIB as a large model program first.

      Usage:
            a) Put following line in LANMAN.INI in [services] section
               service = <path of SERVICE.EXE>\SERVICE.EXE
            b) Optionally, put following section in LANMAN.INI
                  [services]
                      decaf = yes

   c) Start the service
                  NET START SERVICE
               or
                  NET START SERVICE /DECAF:YES

      API                   Used to...
      =================     ================================================
      NetServiceStatus      Notify LAN Manager about the current
                            status of service
      DosMakeMailslot       Make a mailslot to receive alert messages
      DosReadMailslot       Read alert messages coming in a mailslot
      DosDeleteMailslot     Delete a mailslot
      NetAlertStart         Register a mailslot to receive an alert message
      NetAlertStop          Cancel receiving alert messages
      NetErrorLogWrite      Write error message to LAN Manager error
   log


      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_KBD
   #define     INCL_VIO
   #define     INCL_DOSSIGNALS
   #define     INCL_DOSPROCESS
   #define     INCL_DOSSEMAPHORES
   #define     INCL_DOSFILEMGR
   #define     INCL_DOSERRORS
   #include    <os2.h>        // MS OS/2 header files

   #define     INCL_NETMAILSLOT
   #define     INCL_NETSERVICE
   #define     INCL_NETALERT
   #define     INCL_NETERRORS
   #define     INCL_NETERRORLOG
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>
   #include    <process.h>
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   // 4K for API calls and space for the service
   #define DEFAULT_STACK_SIZE      (4096+512)
   #define DEFAULTCOMPONENTNAME    "SERVICE"
   #define COFFEE_ALERT            "COFFEE_ALERT"
   #define ALERT_TYPE_MESSAGE      "Coffee is ready! Come and Get it!"
   #define ALERT_MAILBOX           "\\MAILSLOT\\ALERT"
   #define MESSAGE_SIZE            (sizeof(struct std_alert) + \
                                   sizeof(struct user_other_info))
   #define MAILSLOT_SIZE           (10 * MESSAGE_SIZE)
   #define WAIT_FOR_ALERT_TIME     ALERT_LONG_WAIT
   #define DEFAULT_PARAMETER       "DECAF"

   #define INVALIDPARAM        "Invalid Parameter %s"
   #define MSGERRCNTRLCSIGNAL  "Error in Setting CTL-C Handler %d"
   #define MSGERRCNTRLBSIGNAL  "Error in Setting CTL-BREAK Handler %d"
   #define MSGERRKILLPSIGNAL   "Error in Setting KILLPROCESS Handler
   %d"
   #define MSGERRFLAGASIGNAL   "Error in Setting Flag A Handler %d"
   #define MSGERRFLAGBSIGNAL   "Error in Setting Flag B Handler %d"
   #define MSGERRFLAGCSIGNAL   "Error in Setting Flag C Handler %d"
   #define MSGERRSRVSSIGNAL    "Error in Setting Service Handler %d"
   #define MSGERRDOSSEMSET     "Error in DosSemSet %d"
   #define MSGERRDOSSEMWAIT    "Error in DosSemWait %d"
   #define MSGERRBEGINTHREAD   "Error in Spawning Thread tid: %d"
   #define MSGERRMAKEMAIL      "Error in DosMailSlot %d"
   #define MSGERRREADMAIL      "Error in DosReadMailslot %d"
   #define MSGERRALERTSTOP     "Error in NetAlertStop %d"
   #define MSGERRALERTSTART    "Error in NetAlertStart %d"
   #define MSGERRSEMWAIT       "Error in DosSemWait %d"
   #define MSGERRGETPID        "Error in DosGetPID %d"
   #define MSGERRDOSOPEN       "Error in DosOpen %d"

   PFNSIGHANDLER pnPrevHandler;       // Previous handle address
   unsigned short pfPrevAction;       // Previous action flag
   int  fSigStarted;                  // Flag: TRUE if signal handler
   started
   struct service_status ssStatus;    // Service status structure

   PBYTE  pbStack;                    // Address of top of stack
   TID tThreadTid;                    // TID of Alert handler thread

   unsigned long hSemPause = 0;       // RAM semaphore for pausing
 AlertHandler
   char  szErrBuffer[80];             // Buffer used to report errors
   int   fAlertRegistered = FALSE;    // TRUE if alert registered
   unsigned  hMailSlot;               // Mailslot handle

   // Function declarations
   void far AlertHandler(void *arg);
   void ErrOut(unsigned short, char far *);
   void ExitHandler(void);
   void far pascal SignalHandler(unsigned short, unsigned short);

   void main(int argc, char *argv[])
   {
      int iCount;                    // Index for parsing argv
      unsigned uReturnCode;          // Return code
      char  szErrBuffer[80];         // Buffer used to report errors
      unsigned short usAction;       // Action taken by DosOpen
      unsigned long hSem = 0;        // Dummy semaphore; wait forever
      PIDINFO pidInfo;               // Get PID of main process
      char    szParmValue[80];       // Buffer for value of parameter
      char *  pszDecaf = DEFAULT_PARAMETER;  // DECAF parameter
      HFILE   hFileNul;              // Handle for NULL device
      HFILE   hNewHandle;            // Temporary handle
      fSigStarted  = FALSE;          // Signal handler not started
                                     // Set up service status for param
   error
      ssStatus.svcs_status = SERVICE_UNINSTALLED |
                             SERVICE_UNINSTALLABLE;
      ssStatus.svcs_code = SERVICE_UIC_M_ERRLOG;    // Look at error
   log

   /*
       * Parse the service parameters passed by LAN Manager.
       * The parameters passed in argv can be from LANMAN.INI
       * if they are defined in LANMAN.INI. For example:
       *    [services]
       *         DECAF = yes
       * Or, they can be from the command line. For example:
       *    "net start service /DECAF:yes"
       * Both ways of setting parameters get passed through to the
       * service as DECAF = yes.
       */

   for (iCount = 1; iCount < argc; iCount++)
      {
         if (strnicmp(argv[iCount], pszDecaf, strlen(pszDecaf)) == 0)
         {  // Copy the string after equal sign.
            strcpy(szParmValue, argv[iCount]+strlen(pszDecaf)+1);
         }
         else
         {
            ssStatus.svcs_code |= SERVICE_UIC_AMBIGPARM;
            uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                           sizeof(ssStatus));
            sprintf(szErrBuffer, INVALIDPARAM, argv[iCount]);
            ErrOut(0, szErrBuffer);
         }
      }

   /*
       * Get the process ID of the main process to be used in
       * subsequent NetServiceStatus calls.
       */

      uReturnCode = DosGetPID( &pidInfo);

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRGETPID, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }
      ssStatus.svcs_pid = pidInfo.pid;

      /*
       * Notify LAN Manager that the service is installing. At this time,

       * the service cannot be paused or uninstalled because signal handler

       * has not been installed.
       */

      ssStatus.svcs_status = SERVICE_INSTALL_PENDING |
                             SERVICE_NOT_UNINSTALLABLE |
                             SERVICE_NOT_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      uReturnCode = NetServiceStatus((char far *) &ssStatus,
 sizeof(ssStatus));

   /*
       * Install the signal handler. Ignore CTRL-C, BREAK, and KILL
       * signals and let LAN Manager take care of them. The signal
       * handler will be raised when SERVICE_RCV_SIG_FLAG is raised
       * (SERVICE_RCV_SIG_FLAG is the same as SIG_PFLG_A).
       */

      uReturnCode = DosSetSigHandler(SignalHandler,
                                     &pnPrevHandler,
                                     &pfPrevAction,
                                     SIGA_ACCEPT,
                                     SERVICE_RCV_SIG_FLAG);

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRCNTRLCSIGNAL, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

   /*
       * Signal handler has been installed. Service can now be
       * paused or uninstalled.
       */

      fSigStarted = TRUE;
      ssStatus.svcs_status = SERVICE_INSTALL_PENDING |
                             SERVICE_UNINSTALLABLE |
                             SERVICE_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      uReturnCode = NetServiceStatus((char far *)&ssStatus,
 sizeof(ssStatus));

      uReturnCode = DosSetSigHandler(NULL,      // Ignore CTRL-C
                                     &pnPrevHandler,
                                     &pfPrevAction,
                                     SIGA_IGNORE,
                                     SIG_CTRLC);

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRCNTRLCSIGNAL, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

   uReturnCode = DosSetSigHandler(NULL,      // Ignore BREAK
   signal
                                     &pnPrevHandler,
                                     &pfPrevAction,
                                     SIGA_IGNORE,
                                     SIG_CTRLBREAK);

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRCNTRLBSIGNAL, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

      uReturnCode = DosSetSigHandler(NULL,      // Ignore KILL signal
                                     &pnPrevHandler,
                                     &pfPrevAction,
                                     SIGA_IGNORE,
                                     SIG_KILLPROCESS);

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRKILLPSIGNAL, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

      uReturnCode = DosSetSigHandler(NULL, // Flag B should cause error
                                     &pnPrevHandler,
                                     &pfPrevAction,
                                     SIGA_ERROR,
                                     SIG_PFLG_B);

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRFLAGBSIGNAL, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

      uReturnCode = DosSetSigHandler(NULL, // Flag C should cause error
                                     &pnPrevHandler,
                                     &pfPrevAction,
                                     SIGA_ERROR,
                                     SIG_PFLG_C);

   if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRFLAGCSIGNAL, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }


   /*
       * Close stdin, stdout, and stderr handles so that
       * they cannot be used from this service. Redirect
       * stdin, stdout, stderr to NULL device.
       */

       // Open the null device.
       uReturnCode = DosOpen("NUL",        // Name of device
                              &hFileNul,   // Handle
                              &usAction,   // Action taken
                              0L,          // File size
                              FILE_NORMAL, // File attribute
                              FILE_OPEN,   // Open action
                                           // Open mode
                              OPEN_ACCESS_READWRITE|OPEN_SHARE_DENYNONE,
                              0L);         // Reserved
       if (uReturnCode != NERR_Success)
       {
         sprintf(szErrBuffer, MSGERRDOSOPEN, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
       }

       // Reroute stdin, stderr, and stderr to NUL.
       for (hNewHandle=0; hNewHandle < 3; hNewHandle++)
       {
           /*
            * Skip the duplicating operation if the handle already
            * points to NUL.
            */
           if (hFileNul != hNewHandle)
               DosDupHandle(hFileNul, &hNewHandle);
       }

       // Extra handle to NUL not needed anymore.
       if (hFileNul > 2)
           DosClose(hFileNul);

   // Spawn the application thread.

      pbStack = (PBYTE) SafeMalloc(DEFAULT_STACK_SIZE);
      tThreadTid = _beginthread(AlertHandler,
                                pbStack,
                                DEFAULT_STACK_SIZE,
                                NULL);

      if (tThreadTid == -1)
      {
         sprintf(szErrBuffer, MSGERRBEGINTHREAD, tThreadTid);
         ErrOut(0, szErrBuffer);
      }

      // Notify LAN Manager that the service is installed.

      ssStatus.svcs_status = SERVICE_INSTALLED |
                             SERVICE_UNINSTALLABLE |
                             SERVICE_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      uReturnCode = NetServiceStatus((char far *) &ssStatus,
 sizeof(ssStatus));

   /*
       * Wait on dummy semaphore. This thread will wait forever on the
       * dummy semaphore.
       */

      uReturnCode = DosSemSet(&hSem);  // Set the semaphore

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRDOSSEMSET, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

      /*
       * The main thread waits on the RAM semaphore, but it is
       * interrupted whenever a signal comes. Loop over DosSemWait
       * if interrupted by a signal.
       */

   do {
         uReturnCode = DosSemWait(&hSem, SEM_INDEFINITE_WAIT);
         if (uReturnCode != ERROR_INTERRUPT)
         {
            sprintf(szErrBuffer,MSGERRDOSSEMWAIT, uReturnCode);
            ErrOut(uReturnCode, szErrBuffer);
         }
      } while (uReturnCode == ERROR_INTERRUPT);
   }

   //=======================================================================
   //  ErrOut
   //
   //  This routine is called whenever an error that needs to
   //  be reported occurs. It writes a text message in the error log
   //  and then calls the ExitHandler routine to stop the service.
   //=======================================================================

   void ErrOut(unsigned short usErrCode, char far * psErrStr)
   {
      NetErrorLogWrite(NULL,                // Reserved; must be NULL
                       usErrCode,           // Error code
                       MYSERVICENAME,       // Component name
                       NULL,                // Pointer to raw data buffer
                       0,                   // Length of raw data buffer
                       psErrStr,            // String data
                       1,                   // Number of error strings
                       NULL);               // Reserved; must be NULL

      /*
       * If signal handler is installed, notify LAN Manager
       * that the service is exiting.
       */

      if (fSigStarted)
          ExitHandler();

      _endthread();                         // End AlertHandler

      DosExit(EXIT_PROCESS, 0);
   }

   //=======================================================================
   //  SignalHandler
   //
   //  The signal handling routine gets control when the system sends
   a
   //  status-changing request to the service. The routine should always

   //  expect these arguments:
   //     usSigArg = Opcode that describes the request
   //     usSigNum = Number that identifies the process flag
   //                on which the signal was raised
   //=======================================================================

   void far pascal SignalHandler(unsigned short usSigArg,
                                 unsigned short usSigNum)
   {
      unsigned uReturnCode;
      unsigned char fOpCode;
                                              // Compute the function
   code
      fOpCode = (unsigned char) (usSigArg & 0xFF);

      switch (fOpCode)                        // Do the function
      {
         case SERVICE_CTRL_UNINSTALL:         // Uninstall; end the service
            ExitHandler();
            DosExit(EXIT_PROCESS, 0);         // Stop this process
            break;
         case SERVICE_CTRL_PAUSE:             // Pause service
            DosSemSet(&hSemPause);            // Pause AlertHandler
            ssStatus.svcs_status = SERVICE_INSTALLED |
                                   SERVICE_PAUSED |
                                   SERVICE_UNINSTALLABLE|
                                   SERVICE_PAUSABLE;
            ssStatus.svcs_code = SERVICE_UIC_NORMAL;
            uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                           sizeof(ssStatus));
            break;
         case SERVICE_CTRL_CONTINUE:          // Continue service
            DosSemClear(&hSemPause);          // Continue AlertHandler
            ssStatus.svcs_status = SERVICE_INSTALLED |
                                   SERVICE_ACTIVE |
                                   SERVICE_UNINSTALLABLE|
                                   SERVICE_PAUSABLE;
            ssStatus.svcs_code = SERVICE_UIC_NORMAL;
            uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                           sizeof(ssStatus));
            break;

   case SERVICE_CTRL_INTERROGATE:       // Give service status
         default:
            uReturnCode = NetServiceStatus((char far *) &ssStatus,
                                           sizeof(ssStatus));
            break;
      }

   /*
       * Reenable signal handling. This signal handler accepts the next

       * signal raised on usSigNum.
       */
      uReturnCode = DosSetSigHandler(0,
                             0,
                             0,
                             SIGA_ACKNOWLEDGE,
                             usSigNum);
      return;
   }

   //=======================================================================
   //  ExitHandler
   //
   //  This routine should perform any exit processing tasks and
   //  then inform LAN Manager that the service is uninstalled.
   //=======================================================================

   void ExitHandler()
   {
      API_RET_TYPE uReturnCode;

      //Notify LAN Manager that the service will uninstall.
      ssStatus.svcs_status = SERVICE_UNINSTALL_PENDING |
                             SERVICE_UNINSTALLABLE |
                             SERVICE_NOT_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      uReturnCode = NetServiceStatus((char far *) &ssStatus,
 sizeof(ssStatus));

   // Exit processing would go here.

      /*
       * If the service is registered to receive alerts, deregister and
       * remove the alert semaphore or mailslot.
       */

      if (fAlertRegistered)
      {
         NetAlertStop(COFFEE_ALERT, ALERT_MAILBOX);
         DosDeleteMailslot(hMailSlot);
      }

      // Notify LAN Manager that the service is uninstalled.
      ssStatus.svcs_status = SERVICE_UNINSTALLED |
                             SERVICE_UNINSTALLABLE |
                             SERVICE_NOT_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      NetServiceStatus((char far *) &ssStatus, sizeof(ssStatus));
      return;
   }

   //=======================================================================
   //  AlertHandler
   //
   //  AlertHandler is a thread spawned by the main thread to service
   //  processing of the COFFEE_ALERT type alert event. The thread is

   //  terminated from the ExitHandler routine when this service is stopped.
   //=======================================================================

   void far AlertHandler(void *arg)
   {
      API_RET_TYPE uReturnCode;          // API return code
      KBDKEYINFO kbci;                   // Used to get keyboard input
      unsigned short usRow = 5;          // Screen row
      unsigned short usColumn = 5;       // Screen column
      char sVioString[80];               // Popup output string
                                         // Delay popup if one on screen
      unsigned short fPopUp = VP_WAIT | VP_OPAQUE;
      unsigned char bAttr = 0x17;        // Screen attributes
      unsigned short cbReturned;         // Message size
      unsigned short cbNextSize;         // Next message size
      unsigned short cbNextPriority;     // Next message priority
      char cbAlertBuffer[MESSAGE_SIZE];  // Message buffer

   // Notify LAN Manager that the service is active.
      ssStatus.svcs_status = SERVICE_INSTALLED |
                             SERVICE_ACTIVE |
                             SERVICE_UNINSTALLABLE|
                             SERVICE_PAUSABLE;
      ssStatus.svcs_code = SERVICE_UIC_NORMAL;

      uReturnCode = NetServiceStatus((char far *) &ssStatus,
 sizeof(ssStatus));

      // Make a mailbox to listen to alert messages.

      uReturnCode = DosMakeMailslot(ALERT_MAILBOX, // Mailbox name
                                    MESSAGE_SIZE,  // Maximum message
   size
                                    MAILSLOT_SIZE, // Mailslot size
                                    &hMailSlot);   // Mailslot handle

      if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRMAKEMAIL, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

      /*
       * Register to receive COFEE_ALERT-type alerts
       * in ALERT_MAILBOX mailbox.
       */

      uReturnCode = NetAlertStart(COFFEE_ALERT, ALERT_MAILBOX, MESSAGE_SIZE);

      // Already registered? If yes, deregister and register fresh.
      if (uReturnCode == NERR_AlertExists)
      {
         uReturnCode = NetAlertStop(COFFEE_ALERT, ALERT_MAILBOX);

         if (uReturnCode != NERR_Success)
         {
            sprintf(szErrBuffer, MSGERRALERTSTOP, uReturnCode);
            ErrOut(uReturnCode, szErrBuffer);
         }

   uReturnCode = NetAlertStart(COFFEE_ALERT, ALERT_MAILBOX,
                                     MESSAGE_SIZE);
         if (uReturnCode != NERR_Success)
         {
            sprintf(szErrBuffer, MSGERRALERTSTART, uReturnCode);
            ErrOut(uReturnCode, szErrBuffer);
         }
      }
      else if (uReturnCode != NERR_Success)
      {
         sprintf(szErrBuffer, MSGERRALERTSTART, uReturnCode);
         ErrOut(uReturnCode, szErrBuffer);
      }

      fAlertRegistered = TRUE;

      /*
       * Loop forever now, waiting to receive the alert. Once the
       * alert is received, tell the user by sending a popup.
       */

      for ( ; ; )
      {
         /*
          * Check if the service has been asked to pause. Wait until
   the
          * service is asked to continue.
          */
         uReturnCode = DosSemWait(&hSemPause, SEM_INDEFINITE_WAIT);

         if (uReturnCode != NERR_Success)
         {
            sprintf(szErrBuffer, MSGERRSEMWAIT, uReturnCode);
            ErrOut(uReturnCode, szErrBuffer);
         }

         // Wait to receive alert from LAN Manager.

         uReturnCode = DosReadMailslot(hMailSlot,
                                    cbAlertBuffer,
                                    &cbReturned,
                                    &cbNextSize,
                                    &cbNextPriority,
                                    WAIT_FOR_ALERT_TIME);

   if ((uReturnCode != NERR_Success)
              && (uReturnCode != ERROR_SEM_TIMEOUT))
         {
            sprintf(szErrBuffer, MSGERRREADMAIL, uReturnCode);
            ErrOut(uReturnCode, szErrBuffer);
         }
         // If the alert is received, send a popup.
         if ((uReturnCode == NERR_Success) && (cbReturned))
         {
            VioPopUp(&fPopUp, 0);
            // Paint the screen blue.
            VioWrtNAttr(&bAttr, 25 * 80, 0, 0, 0);
            // Show the message.
            sprintf(sVioString,"%s", ALERT_TYPE_MESSAGE);
            VioWrtCharStrAtt(sVioString, strlen(sVioString),
                             usRow, usColumn, &bAttr, 0);
            usRow += 2;
            sprintf(sVioString, "%s","Hit any key to get back to prompt");
            // Set the cursor positition.
            VioSetCurPos(usRow, usColumn+strlen(sVioString)+1, 0);
            VioWrtCharStrAtt(sVioString, strlen(sVioString),
                             usRow, usColumn, &bAttr, 0);

            // Wait for user to press key.
            KbdCharIn(&kbci, IO_WAIT,0);
            // Close popup.
            VioEndPopUp(0);
         }
      } // End for loop.
      return;
   }




   /*
      ALERT.C -- This program demonstrates NetAlertRaise and is designed

                 to be used in conjunction with SERVICE.C to demonstrate
   a
                 sample service.

      usage:  ALERT

      Build Commands:

         For Microsoft C 5.1:
            CL /c ALERT.C
            LINK /NOD /NOI ALERT,,,SLIBCE+DOSCALLS+LAN;

         For Microsoft C 6.0:
            CL /c ALERT.C
            LINK /NOD /NOI ALERT,,,SLIBCE+OS2+LAN;

      Run Instructions:
         a) Build SERVICE.EXE and start in one full-screen session.
         b) Execute ALERT.EXE in another full-screen session.

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied, as
      to its usability in any given situation.
   */

   #define     INCL_NETALERT
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdlib.h>
   #include    <string.h>
   #include    <time.h>
   #include    <stdio.h>      // C run-time header files

   #define PROGRAM_NAME  "ALERT"
   #define COFFEE_ALERT  "COFFEE_ALERT"       // Alert to raise


   void main (void)
   {
      API_RET_TYPE uReturnCode;               // API return code
      struct std_alert StdAlert;              // Standard alert data
   structure

   // Fill in the std_alert structure.
      time(&(StdAlert.alrt_timestamp));
      strcpy(StdAlert.alrt_eventname,   COFFEE_ALERT);
      strcpy(StdAlert.alrt_servicename, PROGRAM_NAME);

      // Issue the alert.
      uReturnCode = NetAlertRaise(COFFEE_ALERT,     // Alert type
                          (char far *)&StdAlert,    // Alert information
                          sizeof(struct std_alert), // Buffer size
                          ALERT_MED_WAIT);          // Time-out value

      // Print results.
      printf("NetAlertRaise returned %u\n", uReturnCode);
      exit(0);
   }








 Appendix D  Building the Sample Programs
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 This appendix describes how to build and run the sample programs listed with
 each API function category in Chapter 2, "API Function Descriptions." These
 sample programs demonstrate how LAN Manager API functions are typically
 used. The goal of the examples is to illustrate how the functions are used
 and to point out potential pitfalls. The examples do not represent
 production code.

 Although this appendix describes how to build the sample programs, you can
 use the same methods to build other programs that use LAN Manager API
 functions.

 The sample programs are organized by category. The following table shows
 which programs demonstrate particular category functions:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Category                          Program Name
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Access Permissions                NETACC.C

 Alert                             NETALRT.C

 Auditing                          NETAUD.C

 Character Device                  NETCHAR1.C and NETCHAR2.C

 Configuration                     NETCNFG.C

 Connection                        NETCONS.C

 Domain                            NETDOM.C

 Error Logging                     NETERR.C

 File                              NETFILE.C

 Category                          Program Name
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Group                             NETGROUP.C

 Handle                            NETHAND1.C and NETHAND2.C

 Mailslot                          NETMAIL.C

 Message                           NETMSG.C

 Named Pipes                       NPSERVER.C and NPCLIENT.C

 NetBIOS                           NETBIOS.C

 Print Destination                 NETPRD.C

 Print Job                         NETPRJ.C

 Printer Queue                     NETPRQ.C

 Category                          Program Name
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Remote Utility                    NETREM.C

 Server                            NETSERV.C

 Service                           NETSVC.C

 Session                           NETSESS.C

 Share                             NETSHARE.C

 Statistics                        NETSTATS.C

 Use                               NETUSE.C

 User                              NETUSER.C

 Workstation                       NETWKSTA.C

 Category                          Program Name
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 The program NETSESS.C also demonstrates using the DosGetMessage function to
 print LAN Manager or MS OS/2 system error messages.

 This appendix assumes that you are using the Microsoft C Optimizing Compiler
 5.1 or later, and that you have installed either the MS-DOS or MS OS/2
 standard libraries as your default libraries. It also assumes that you have
 installed the appropriate LAN Manager header files and libraries, and set
 the LIB and INCLUDE environment variables to point to these files. The link
 libraries needed are described in Chapter 1, "Overview."

 If you are not using the Microsoft C Optimizing Compiler, or if you have not
 installed the proper libraries and header files, the command lines shown in
 this chapter may not work as described.


 Building SAMPLES.LIB

 The sample programs can be built by using makefiles, or by compiling them
 from the command line. The first step is to create the example program
 companion library, SAMPLES.LIB. The source code for SAMPLES.LIB is contained
 in the file SAMPLES.C, listed at the end of this appendix.

 The following command lines can be used to build SAMPLES.LIB:

   CL /c SAMPLES.C
   LIB SAMPLES.LIB +SAMPLES.OBJ;

 The first line uses CL to compile SAMPLES.C and produce the object file
 SAMPLES.OBJ. The LIB utility is then used to create the library SAMPLES.LIB,
 containing the code in SAMPLES.C. This library file is needed because it
 contains routines commonly used in many of the sample programs.


 Building the Sample Programs

 To build the sample programs discussed in the preceding section, you must
 first create SAMPLES.LIB, and then compile and link the appropriate sample
 code.

 The next step is to compile the required sample code, and then link it with
 SAMPLES.LIB and the required LAN Manager library. For example, to build
 NETUSE.EXE, you can use either of the following lines:

   CL NETUSE.C /link LAN.LIB SAMPLES.LIB /STACK:4096

 or

   CL NETUSE.C /link DOSLAN.LIB SAMPLES.LIB /STACK:4096

 The first example links to the LAN Manager API library for MS OS/2. The
 second example links to the LAN Manager API library for MS-DOS. In both
 cases it is assumed that the appropriate C run-time library is available.

 Because some LAN Manager API functions require as much as 4K of stack space,
 the /STACK:4096 switch is supplied to ensure a stack size of 4096 bytes.
 Another useful compile switch is /W3, used to provide warnings of possible
 problems in the code. The /Zi and /Od compile switches are combined with the
 /CO link switch to produce files that can be used with Microsoft
 CodeView(R). A compile line using all of these options looks like this:

   CL /W3 /Zi /Od NETUSE.C /link LAN.LIB SAMPLES.LIB /STACK:4096
   /CO

 Some of the sample programs use MS OS/2 function calls. As well as linking
 with LAN.LIB, these examples need to be linked with OS2.LIB (if linking with
 Microsoft C 6.0 libraries) or with DOSCALLS.LIB (if linking with Microsoft C
 5.1 libraries). The Print Destination, Print Job, and Printer Queue example
 programs must also be linked with the PMSPL.LIB library supplied with LAN
 Manager 2.0.

 For example, to compile and link the Print Job category example program, use
 the following command line:

   CL NETPRJ.C /link LAN.LIB OS2.LIB SAMPLES.LIB PMSPL.LIB /STACK:4096

 If running on an MS-DOS system and using MS OS/2 Family API (FAPI) system
 calls such as DosOpen, DosBufReset, and DosRead, the libraries SYSCALL0.LIB
 and API.LIB are also required. If used, SYSCALL0.LIB must immediately
 precede the FAPI library, API.LIB.


 Binding the Sample Programs

 The BIND utility takes programs that are compiled to run in protected mode
 and converts them so that they can be run in both real mode and protected
 mode. A bound version of NPCLIENT.EXE could be produced by using the
 following commands:

   CL NPCLIENT.C /link LAN.LIB SAMPLES.LIB /STACK:4096
   BIND NPCLIENT.EXE DOSCALLS.LIB LAN.LIB DOSLAN.LIB SYSCALL0.LIB API.LIB

 The first line produces a version of NPCLIENT.EXE that can run with MS OS/2.
 The second line produces a version of NPCLIENT.EXE that can run with either
 MS OS/2 or MS-DOS. The disadvantage of the second version is that it is
 larger and slower than the first.

 The BIND command given here works with the Microsoft Bind Utility 1.3,
 provided with Microsoft C 6.0. Different versions have different syntax. For
 more information about BIND, see your Microsoft C manual(s).


 Running the Programs

 All sample programs are designed so that, once they are compiled, they can
 be run by typing only the name of the program. For example, the Use category
 example can be run by typing

   NETUSE

 The API functions used, and their return codes, are usually displayed when
 each API function is called. Some parameter values used by the sample
 programs can be set from the command line. The command-line switches used to
 set these values vary from program to program. Each program has a built-in
 usage statement that can be displayed by using the -H switch. For example,
 with the Use category sample program, NETUSE -H displays the following:

   Usage: NETUSE [-s \\server] [-d device] [-r resource] [-p password]


 SAMPLES.C

 The SAMPLES.C file contains the following code:

   /*
      SAMPLES.C -- a file containing common routines for the Programmer's
                   Reference sample programs.

      These common routines for the sample programs are intended to be
   compiled
      into SAMPLES.LIB. They provide a safe memory allocation function
   and
      three sample string manipulation functions that take far pointers.

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #include <malloc.h>
   #include <stdio.h>
   #include <stdlib.h>

   //========================================================================
   //  _SafeMallocFunc()
   //
   //  This safe version of malloc provides a quick check that a malloc
   //  succeeds; it terminates with an error if malloc does not succeed.
   //  Production code, especially for a Windows or an MS OS/2 Presentation
   //  Manager environment, should use a more robust version of
   //  SafeMallocFunc(). This function is not meant to be called directly.
   //  Instead, call the SafeMalloc macro defined in SAMPLES.H as
   //
   //  #define  SafeMalloc(size)  _SafeMallocFunc(size, __FILE__, __LINE__)
   //========================================================================

   void *_SafeMallocFunc(unsigned cbSize, char *pszFilename, unsigned
   usLine)
   {
      void *ptr;

      if ((ptr = malloc(cbSize)) == NULL)
      {
         fprintf(stderr, "Malloc failed.  size:%u  file:%s  line:%u\n",
                 cbSize, pszFilename, usLine);
         exit(1);
      }
      else
         return (ptr);
   }

   //========================================================================
   //  The following string functions use far pointers.
   //
   //  Since much of the string data returned from LAN Manager API
   //  functions uses far pointers, they cannot be easily manipulated
   using
   //  the standard C run-time library calls if your program is in small
   or
   //  medium memory model. By using these far versions and their function
   //  prototypes, the sample programs will work in any memory model
   (near
   //  pointers will be promoted to far if necessary).
   //========================================================================

   char far * FarStrcpy(char far *pszDestination, char far *pszSource)
   {
      char far * pszReturn = pszDestination;

      while (*pszDestination++ = *pszSource++)
              ;                   // Copy source over destination
      return (pszReturn);
   }

   char far * FarStrcat(char far *pszDestination, char far *pszSource)
   {
      char far * pszReturn = pszDestination;

      while (*pszDestination)
              pszDestination++;   // Go to end of destination string
      while (*pszDestination++ = *pszSource++)
              ;                   // Concatenate source to destination
      return (pszReturn);
   }

   int FarStrcmpi(char far *pszDestination, char far *pszSource)
   {
      int f,l;

      do {
         f = tolower(*pszDestination);
         l = tolower(*pszSource);
         pszDestination++;
         pszSource++;
      } while (f && (f == l));

      return (f - l);
   }


 SAMPLES.H

 The SAMPLES.H file contains the following code:

   /*
      SAMPLES.H -- header file for routines in SAMPLES.LIB.
                   See SAMPLES.C for descriptions.
   */

   char far * FarStrcpy(char far *pszDestination, char far *pszSource);
   char far * FarStrcat(char far *pszDestination, char far *pszSource);
   int        FarStrcmpi(char far *pszDestination, char far *pszSource);

   void     * _SafeMallocFunc(unsigned cbSize,   // Count of bytes to
   allocate
                              char *pszFilename, // Program calling
 SafeMalloc
                              unsigned uLine);   // Line in program

   #define    SafeMalloc(size)  _SafeMallocFunc(size, __FILE__, __LINE__)









 Appendix E  NetBIOS Category
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 The NetBIOS API functions provide direct access to network device drivers.
 The NetBiosOpen function requires that the Workstation service be started;
 the other NetBIOS functions require that the network device driver be
 installed, but do not require that the Workstation service be started.

 The NetBIOS category functions, datatypes, structures, and constants are
 defined in the NCB.H, NETBIOS.H, and NETCONS.H header files. A source
 program can access these definitions by defining the constants
 INCL_NETERRORS and INCL_NETBIOS, and including the master header file,
 LAN.H. For more information, see the "Example" section, later in this
 appendix.

 These are the NetBIOS API functions:


   þ   NetBiosClose

   þ   NetBiosEnum

   þ   NetBiosGetInfo

   þ   NetBiosOpen

   þ   NetBiosSubmit



 Description

 NetBIOS API functions support existing applications that write directly to
 earlier versions of the network interface. New applications should not use
 the NetBIOS API functions. New applications should use mailslots and named
 pipes, which are independent of the transport implementation. For more
 information about mailslots, see the Mailslot category API functions. For
 more information about named pipes, see Appendix F, "Network Considerations
 for Named Pipes."

 NetBiosEnum lists information about all logical networks installed on a
 computer. NetBiosGetInfo obtains information about one specific logical
 network.

 NetBiosOpen opens a handle to the logical network. NetBiosClose releases the
 handle to the logical network. NetBiosSubmit submits network control blocks
 (NCBs) to the logical network specified by the handle.


 Data Structures

 NetBiosEnum and NetBiosGetInfo return data in the netbios_info_X data
 structure, where X is 0 or 1, depending on the specified level of detail
 requested.

 Data in the [networks] section of the LANMAN.INI file is returned in the
 netbios_info_X data structure. For more information, see your LAN Manager
 administrator's manual(s).

 Entries in the [networks] section of the LANMAN.INI file use this format:

 net1 = devicename$,ln,type,sess,ncb,name

 For more information, see your LAN Manager network device drivers manual.

 NetBiosSubmit requires the standard ncb data structure that is used to
 define NCBs.


 Network Control Block format

 The ncb data structure has this format:

   struct ncb {
       unsigned char   ncb_command;
       unsigned char   ncb_retcode;
       unsigned char   ncb_lsn;
       unsigned char   ncb_num;
       char far *      ncb_buffer;
       unsigned short  ncb_length;
       char            ncb_callname[NCBNAMSZ];
       char            ncb_name[NCBNAMSZ];
       unsigned char   ncb_rto;
       unsigned char   ncb_sto;
       unsigned long   ncb_post;
       unsigned char   ncb_lana_num;
       unsigned char   ncb_cmd_cplt;
       unsigned char   ncb_reserve[14];
   };

 where

 ncb_command
   Contains a command code and a flag that indicates whether the NCB is to be
   processed asynchronously. The most significant bit contains the ASYNCH
   flag. A value of 1 for the most significant bit (the constant ASYNCH,
   0x80) indicates that the NCB is to be processed asynchronously. The NCB.H
   header file defines these possible command codes:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code            Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code            Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NCBCALL         0x10   Call.
 NCBLISTEN       0x11   Listen.
 NCBHANGUP       0x12   Hang up.
 NCBSEND         0x14   Send.
 NCBRECV         0x15   Receive.
 NCBRECVANY      0x16   Receive any.
 NCBCHAINSEND    0x17   Chain send.
 NCBDGSEND       0x20   Send datagram.
 NCBDGRECV       0x21   Receive datagram.
 NCBDGSENDBC     0x22   Send broadcast datagram.
 NCBDGRECVBC     0x23   Receive broadcast datagram.
 NCBADDNAME      0x30   Add a name.
 NCBDELNAME      0x31   Delete a name.
 NCBRESET        0x32   Reset.
 NCBASTAT        0x33   Give adapter status.
 NCBSSTAT        0x34   Give session status.
 NCBCANCEL       0x35   Cancel.
 NCBADDGRNAME    0x36   Add groupname.
 NCBUNLINK       0x70   Unlink.
 Code            Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NCBUNLINK       0x70   Unlink.
 NCBSENDNA       0x71   Send no acknowledgment.
 NCBCHAINSENDNA  0x72   Chain send no acknowledgment.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 ncb_retcode
   Specifies the return code. The NCB.H header file defines these possible
   values:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NRC_GOODRET      0x00   Good return.

 NRC_BUFLEN       0x01   Illegal buffer length given.

 NRC_BFULL        0x02   Buffers are full, no receive issued.

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NRC_ILLCMD       0x03   Illegal command was given.

 NRC_CMDTMO       0x05   Command was timed out.

 NRC_INCOMP       0x06   Message was incomplete; issue another command.

 NRC_BADDR        0x07   Illegal buffer address was given.

 NRC_SNUMOUT      0x08   Session number is out of range.

 NRC_NORES        0x09   No resource is available.

 NRC_SCLOSED      0x0A   Session is closed.

 NRC_CMDCAN       0x0B   Command is canceled.

 NRC_DMAFAIL      0x0C   PC DMA failed.

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NRC_DUPNAME      0x0D   Duplicate name exists.

 NRC_NAMTFUL      0x0E   Name table is full.

 NRC_ACTSES       0x0F   No deletions; name has active sessions.

 NRC_INVALID      0x10   Name was not found or no valid name exists.

 NRC_LOCTFUL      0x11   Local session table is full.

 NRC_REMTFUL      0x12   Remote session table is full.

 NRC_ILLNN        0x13   Illegal name number was given.

 NRC_NOCALL       0x14   No callname was given.

 NRC_NOWILD       0x15   Cannot put * in NCB_NAME.

 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NRC_INUSE        0x16   Name already in use on remote adapter.

 NRC_NAMERR       0x17   Called name cannot equal name, number.

 NRC_SABORT       0x18   Session ended abnormally.

 NRC_NAMCONF      0x19   Name conflict was detected.

 NRC_IFBUSY       0x21   Interface is busy.

 NRC_TOOMANY      0x22   Too many commands are outstanding; retry later.

 NRC_BRIDGE       0x23   The NCB_BRIDGE field is not
                         00 or 01.

 NRC_CANOCCR      0x24   Command was completed while cancel was occurring.

 NRC_RESNAME      0x25   Reserved name was specified.
 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NRC_RESNAME      0x25   Reserved name was specified.

 NRC_CANCEL       0x26   Command not valid to cancel.

 NRC_MULT         0x33   Multiple requests were made for the same session.

 NRC_MAXAPPS      0x36   Maximum number of applications was exceeded.

 NRC_NORESOURCES  0x38   Requested resources are not available.

 NRC_SYSTEM       0x40   System error occurred.

 NRC_ROM          0x41   ROM checksum failure occurred.

 NRC_RAM          0x42   RAM test failure occurred.

 NRC_DLF          0x43   Digital loopback failure occurred.

 NRC_ALF          0x44   Analog loopback failure occurred.
 Code             Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
NRC_ALF          0x44   Analog loopback failure occurred.

 NRC_IFAIL        0x45   Interface failure occurred.

 NRC_ADPTMALFN    0x50   Network adapter malfunctioned.

 NRC_PENDING      0xFF   Asynchronous command is not yet finished.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 ncb_lsn
   Specifies the local session number.

 ncb_num
   Specifies the number of the network name.

 ncb_buffer
   Points to the message buffer.

 ncb_length
   Specifies the size (in bytes) of the message buffer.

 ncb_callname
   Specifies a string (padded with blanks) that contains the remote name. The
   constant NCBNAMSZ is defined in the NCB.H header file.

 ncb_name
   Contains a string (padded with blanks) that specifies the local name. The
   constant NCBNAMSZ is defined in the NCB.H header file.

 ncb_rto
   Specifies the receive time-out count.

 ncb_sto
   Specifies the send time-out count.

 ncb_post
   Specifies the asynchronous notification handle. Under MS OS/2, this is the
   handle of a system semaphore. With MS-DOS, this is the memory address of
   the routine to call when the asynchronous NCB completes.

 ncb_lana_num
   Specifies the LAN adapter number.

 ncb_cmd_cplt
   Specifies the command complete code.

 ncb_reserve
   Reserved. This element should not be used.


 Network Device Driver Information (level 0)

 The netbios_info_0 data structure has this format:

   struct netbios_info_0 {
       char nb0_net_name[NETBIOS_NAME_LEN+1]
   };

 where

 nb0_net_name
   Specifies the name of the network device driver. The constant
   NETBIOS_NAME_LEN is defined in the NETCONS.H header file. The nb0_net_name
   element is equivalent to the netn entry in the [networks] section of the
   LANMAN.INI file.


 Network Device Driver Information (level 1)

 The netbios_info_1 data structure has this format:

   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;
       unsigned short  nb1_max_names;
   };

 where

 nb1_net_name
   Specifies the name of the network. The constant NETBIOS_NAME_LEN is
   defined in the NETCONS.H header file. The nb1_net_name element is
   equivalent to the netn entry in the [networks] section of the LANMAN.INI
   file. (This value is usually net1 because a workstation is usually
   connected to only one network.)

 nb1_driver_name
   Specifies the name of the network device driver. The constant DEVLEN is
   defined in the NETCONS.H header file. The nb1_driver_name element is
   equivalent to the devicename entry in the [networks] section of the
   LANMAN.INI file. This value represents the name of the NetBIOS device
   driver (for example, ubxns$, sytek$,  or loopdrv$).

 nb1_lana_num
   Specifies the network adapter card number used by the device driver
   specified by nb1_driver_name. The nb1_lana_num element is equivalent to
   the ln entry in the [networks] section of the LANMAN.INI file. This value
   represents the LAN adapter number. If the driver is set up to handle more
   than one of the same kind of network adapter card, ln specifies which card
   to access.

 nb1_pad_1
   Aligns the next data structure element on a word boundary.

 nb1_driver_type
   Contains an unsigned short integer that specifies the device driver
   protocol type. The NETBIOS.H header file defines these possible values:

 Code         Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NB_TYPE_NCB  1      Network control block protocol.
 NB_TYPE_MCB  2      Message control block protocol.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

   The nb1_driver_type element is equivalent to the type entry in the
   [networks] section of the LANMAN.INI file.

 nb1_net_status
   Contains an unsigned short integer that indicates the status of the device
   driver. The NETBIOS.H header file defines the nb1_net_status bits in the
   following tables.

   The NB_LAN_FLAGS_MASK code has the value 0x3FFF. This bit mask isolates
   these LAN flags:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NB_LAN_MANAGED    0x0001  The network is managed by the redirector.
 NB_LAN_LOOPBACK   0x0002  The network is a loopback driver.
 NB_LAN_SENDNOACK  0x0004  SendNoAck NCBs are supported.
 NB_LAN_LMEXT      0x0008  Extended NCBs are supported.
 NB_LAN_INTNCB     0x0010  NCB submission at interrupt time is supported.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


   The NB_OPEN_MODE_MASK code has the value 0xC000. This bit mask isolates
   the open mode, as follows:

 Code                Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NB_OPEN_REGULAR     0x4000  NetBIOS opened in regular mode.
 NB_OPEN_PRIVILEGED  0x8000  NetBIOS opened in privileged mode.
 NB_OPEN_EXCLUSIVE   0xC000  NetBIOS opened in exclusive mode.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 nb1_net_bandwidth
   Contains an unsigned long integer that specifies the number of bits per
   second the network hardware can accommodate.

 nb1_max_sess
   Contains an unsigned short integer that specifies the maximum number of
   concurrent sessions that can be established by each device driver. The
   nb1_max_sess element is equivalent to the sess entry in the [networks]
   section of the LANMAN.INI file.

 nb1_max_ncbs
   Contains an unsigned short integer that specifies the maximum number of
   NCBs that can be outstanding at any time. The nb1_max_ncbs element is
   equivalent to the ncb entry in the [networks] section of the LANMAN.INI
   file.

 nb1_max_names
   Contains an unsigned short integer that specifies the maximum number of
   network names a network adapter card can establish. The nb1_max_names
   element is equivalent to the name entry in the [networks] section of the
   LANMAN.INI file.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 LANMAN.INI sections               LAN Manager installation manual

 Mailslots                         Mailslot Category

 Named pipes                       Appendix F, "Named Pipes," and
                                   MSOS/2 programming manual(s)

 NCBs                              IBM PC-NET technical reference manual(s)

 Regular, privileged, and          MSOS/2 programming manual(s)
 exclusive modes


 NetBiosClose
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetBiosClose closes a handle to a network device driver.

 LAN Manager 2.0 applications should use mailslots and/or named pipes instead
 of NetBIOS calls.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege is required to successfully execute NetBiosClose.


 Syntax

   #define INCL_NETBIOS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetBiosClose (unsigned short  hDevName,
                 unsigned short  usReserved
                );

 where

 hDevName
   Contains an unsigned short integer that specifies the handle to the device
   driver.

 usReserved
   Reserved; must be 0.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_INVALID_FUNCTION            1       The function is invalid.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_HANDLE              6       The handle specified is invalid.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 NetBiosClose terminates access to a network device driver by invalidating
 its handle and canceling any outstanding network control blocks (NCBs).

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Listing all network device        NetBiosEnum
 drivers on a computer

 Mailslots                         Mailslot Category

 Named pipes                       Appendix F, "Named Pipes," and
                                   MSOS/2 programming manual(s)

 Opening a network device driver   NetBiosOpen


 NetBiosEnum
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetBiosEnum returns information about all network device drivers installed
 on a computer.

 LAN Manager 2.0 applications should use mailslots and/or named pipes instead
 of NetBIOS calls.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local or remote operation

   þ   MS OS/2 version 1.1, local or remote operation

   þ   MS-DOS not supported



 Privilege Level

 Admin privilege is required to successfully execute NetBiosEnum on a remote
 server.


 Syntax

   #define INCL_NETBIOS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetBiosEnum (const char far *      pszServer,
                short                 sLevel,
                char far *            pbBuffer,
                unsigned short        cbBuffer,
                unsigned short far *  pcEntriesRead,
                unsigned short far *  pcTotalAvail
               );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the remote server on
   which to execute NetBiosEnum. A null pointer or null string specifies the
   local computer.

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a sequence of netbios_info_X data structures,
   where X is 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcEntriesRead
   Points to an unsigned short integer that specifies the number of entries
   returned. This count is valid only if NetBiosEnum returns NERR_Success or
   ERROR_MORE_DATA.

 pcTotalAvail
   Points to an unsigned short integer that specifies the number of entries
   available. This count is valid only if NetBiosEnum returns NERR_Success or
   ERROR_MORE_DATA.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Mailslots                         Mailslot Category

 Named pipes                       Appendix F, "Named Pipes," and
                                   MSOS/2 programming manual(s)


 NetBiosGetInfo
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetBiosGetInfo returns information about a particular network device driver
 installed on a computer.

 LAN Manager 2.0 applications should use mailslots and/or named pipes instead
 of NetBIOS calls.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local or remote operation

   þ   MS OS/2 version 1.1, local or remote operation

   þ   MS-DOS not supported



 Privilege Level

 Admin privilege is required to successfully execute NetBiosGetInfo on a
 remote server.


 Syntax

   #define INCL_NETBIOS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetBiosGetInfo (const char far *      pszServer,
                   const char far *      pszNetBiosName,
                   short                 sLevel,
                   char far *            pbBuffer,
                   unsigned short        cbBuffer,
                   unsigned short far *  pcbTotalAvail
                  );

 where

 pszServer
   Points to an ASCIIZ string that contains the name of the server on which
   to execute NetBiosGetInfo. A null pointer or null string specifies the
   local computer.

 pszNetBiosName
   Points to an ASCIIZ string that contains the name of the network (for
   example, net1).

 sLevel
   Specifies the level of detail (0 or 1) requested.

 pbBuffer
   Points to the buffer in which to store the returned data. On a successful
   return, the buffer contains a netbios_info_X data structure, where X can
   be 0 or 1, depending on the level of detail requested.

 cbBuffer
   Specifies the size (in bytes) of the buffer pointed to by pbBuffer.

 pcbTotalAvail
   Points to an unsigned short integer that specifies the number of bytes
   returned in the buffer pointed to by pbBuffer. This count is valid only if
   NetBiosGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall.


 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NO_MORE_FILES               18      No more files are available.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_BAD_NETPATH                 53      The network path was not found.

 ERROR_NETWORK_ACCESS_DENIED       65      Network access is denied.

 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 ERROR_INVALID_LEVEL               124     The level for information
                                           retrieval or setting is invalid.

 ERROR_MORE_DATA                   234     Additional data is available.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_BufTooSmall                  2123    The supplied buffer is too small.

 NERR_BadTransactConfig            2141    The server is not configured for
                                           this transaction: IPC$ is not
                                           shared.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Mailslots                         Mailslot Category

 Named pipes                       Appendix F, "Named Pipes," and
                                   MSOS/2 programming manual(s)


 NetBiosOpen
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetBiosOpen opens a handle to a particular network device driver.

 LAN Manager 2.0 applications should use mailslots and/or named pipes instead
 of NetBIOS calls.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege is required to successfully execute NetBiosOpen.


 Syntax

   #define INCL_NETBIOS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetBiosOpen (char far *            pszDevName,
                char far *            pszReserved,
                unsigned short        usOpenOpt,
                unsigned short far *  phDevName
               );

 where

 pszDevName
   Points to an ASCIIZ string that contains the network name (for example,
   net1).

 pszReserved
   Reserved; must be 0.

 usOpenOpt
   Contains an unsigned short integer that specifies the access mode. A
   process can have exclusive or restricted access for opening the device
   driver. The NETBIOS.H header file defines these possible values:

 Code           Value  Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NB_REGULAR     1      Regular mode. Any number of processes can open the
                       device driver. Does not allow the reset or use of
                       permanent names in any network control block (NCB),
                       nor does the device driver receive any-to-any NCBs.

 NB_PRIVILEGED  2      Privileged mode. Only one process can open the
                       device driver. Other processes can open the driver
                       if they use regular mode. Does not allow the reset
                       or receiving of any-to-any NCBs. NetBiosOpen fails
                       if any other process has the device driver open in
                       privileged or exclusive mode.

 NB_EXCLUSIVE   3      Exclusive mode. Only one process can open the device
                       driver. Any NCB operation is allowed. NetBiosOpen
                       fails if any other process has an open handle to the
                       device driver.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 phDevName
   Points to an unsigned short integer in which the handle to the device
   driver is returned.

 Return Codes

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success                      0       The function encountered no
                                           errors.

 ERROR_FILE_NOT_FOUND              2       The file was not found.

 ERROR_ACCESS_DENIED               5       The user has insufficient
 Code                              Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ERROR_ACCESS_DENIED               5       The user has insufficient
                                           privilege for this operation.

 ERROR_NOT_SUPPORTED               50      This network request is not
                                           supported.

 ERROR_INVALID_PARAMETER           87      The parameter specified is
                                           invalid.

 NERR_NetNotStarted                2102    The LAN Manager NETWKSTA driver
                                           is not installed.

 NERR_InvalidComputer              2351    The specified computername is
                                           invalid.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Remarks

 Before an application can open a handle to the logical network, the
 Workstation service must be running.

 A device driver's handle is not automatically inherited by child processes.
 The process that creates a device driver handle must pass the handle to
 other functions.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Mailslots                         Mailslot Category

 Named pipes                       Appendix F, "Named Pipes," and
                                   MSOS/2 programming manual(s)


 NetBiosSubmit
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 NetBiosSubmit passes a network control block (NCB) packet to a network
 device driver.

 LAN Manager 2.0 applications should use mailslots and/or named pipes instead
 of NetBIOS calls.


 Operating Systems Supported


   þ   MS OS/2 version 1.2, local only

   þ   MS OS/2 version 1.1, local only

   þ   MS-DOS not supported



 Privilege Level

 No special privilege is required to successfully execute NetBiosSubmit.


 Syntax

   #define INCL_NETBIOS
   #define INCL_NETERRORS
   #include <lan.h>

   API_FUNCTION
   NetBiosSubmit (unsigned short    hDevName,
                  unsigned short    usNcbOpt,
                  struct ncb far *  pNCB
                 );

 where

 hDevName
   Specifies the handle of the network device driver. If hDevName is 0, the
   NCB is passed to the first installed device driver.

 usNcbOpt
   Specifies the chaining option flags for the submitted NCB. The chaining
   option specifies whether a single NCB or an NCB chain is being passed.
   These are the possible values for usNcbOpt:

 Value                             Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 A single NCB is being passed.

 1                                 A single NCB with the error-retry
                                   chaining option is being passed.

 2                                 An NCB chain with the proceed-on-error
                                   chaining option is being passed.

 3                                 An NCB chain with the stop-on-error
                                   chaining option is being passed.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 pNCB
   Points to the chained or unchained NCB, as specified by usNcbOpt. If
   unchained, pNCB points to the ncb data structure. If chained, it points to
   the link word preceding the NCB.

 Return Codes

 Code                     Value   Meaning
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NERR_Success             0       The function encountered no errors.
 ERROR_INVALID_HANDLE     6       The handle specified is invalid.
 ERROR_INVALID_PARAMETER  87      The parameter specified is invalid.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Remarks

 Chained NCBs must be in the same memory segment so that they can be linked
 by a 16-bit offset pointer that precedes each NCB. An offset of 0xFFFF
 specifies the end of the chain.

 In a proceed-on-error chain, each NCB executes regardless of errors that
 occur. In a stop-on-error chain, no NCBs are processed after an error occurs
 during processing of an NCB. The unprocessed NCB command elements are set to
 0xB (command canceled).

 For an asynchronous NCB, the value of the ncb_post element of the ncb data
 structure must be 0 or the handle to a nonexclusive system semaphore that is
 to be cleared upon completion of the NCB.

 A single NCB can be executed with optional error retry, in which case LAN
 Manager reissues the NCB in response to some errors.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Mailslots                         Mailslot Category

 Named pipes                       Appendix F, "Named Pipes," and
                                   MSOS/2 programming manual(s)





 NetBIOS Category Example

   /*
      NETBIOS.C -- a sample program demonstrating NetBIOS API functions.

      This program requires that you have admin privilege on the specified
      server.

         usage: netbios [-s \\server] [-n netname] [-l level]
                        [-d device] [-o open option] [-c command]
         where \\server    = Name of the server. A servername must be
                             preceded by two backslashes (\\).
               netname     = Name of the network.
               level       = Level of detail.
               device      = Logical network name, such as net1.
               open option = Flag for NetBiosOpen.
               command     = Command code for NCB.

      API                 Used to...
      ===============     =============================================
      NetBiosEnum         List network names
      NetBiosGetInfo      Get information about each network
      NetBiosOpen         Open a handle to a logical network
      NetBiosSubmit       Submit an NCB to the network
      NetBiosClose        Close specified files on the specified server

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_NETBIOS
   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   #define DEFAULT_BUFFER_SIZE        1024
   #define DEFAULT_DEV                "NET1"
   #define NCB_CHAIN_SINGLE           0
   #define NCB_CHAIN_ERROR_RETRY      1
   #define NCB_CHAIN_PROCEED_ON_ERROR 2
   #define NCB_CHAIN_STOP_ON_ERROR    3
   void Usage(char *pszString);

   void main(int argc, char *argv[])
   {
      char * pszServer = "";              // Servername
      char * pszNetName = "";             // Network name
      char * pszDevName = DEFAULT_DEV;    // Devicename
      int    iCount;                      // Index counter
      unsigned short hDevName;            // Handle to logical network
      unsigned char  cbCommand = NCBCALL| ASYNCH; // Command to submit
      unsigned short usOpenOpt = NB_REGULAR; // Access mode
      unsigned short sLevel = 1;          // Level
      unsigned short cbBuffer;            // Count of bytes
      unsigned short cEntriesRead;        // Count of entries read
      unsigned short cTotalAvail;         // Count of entries or bytes
      API_RET_TYPE   uRet;                // API function return code
      struct netbios_info_0 *p0;          // Pointer to level 0 data
      struct netbios_info_1 *p1;          // Pointer to level 1 data
      char *pbBuffer;                     // Return buffer
      NCB ncbblock;                       // NCB block


      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1))) // Process switches
            {
               case 's':                        // -s servername
                  pszServer = argv[++iCount];
                  break;
               case 'n':                        // -n network name
                  pszNetName = argv[++iCount];
                  break;
               case 'l':                        // -l level
                  sLevel = atoi(argv[++iCount]);
                  break;
               case 'd':                        // -d device
                  pszDevName = argv[++iCount];
                  break;
               case 'o':                        // -o open option
                  usOpenOpt = atoi(argv[++iCount]);
                  break;
               case 'c':                        // -c command for submit
                  cbCommand = (unsigned char) atoi(argv[++iCount]);
                  break;

   case 'h':
               default:
                  Usage(argv[0]);
                  break;
            }
         }
         else
            Usage(argv[0]);
      }

   //========================================================================
   //  NetBiosEnum
   //
   //  This API lists all logical networks on the computer.
   //========================================================================

      cbBuffer = DEFAULT_BUFFER_SIZE;
      pbBuffer = SafeMalloc(cbBuffer);
      uRet = NetBiosEnum(pszServer,       // Null ptr or string means
   local
                         sLevel,          // Level (0 or 1)
                         pbBuffer,        // Return buffer
                         cbBuffer,        // Size of return buffer
                         &cEntriesRead,   // Count of entries returned
                         &cTotalAvail);   // Count of bytes available

      printf("NetBiosEnum returned %u\n", uRet);
      if (uRet == NERR_Success)
      {
         for (iCount = 0; iCount < (int) cEntriesRead; iCount++)
         {
            if (sLevel == 0)
            {
               p0 = (struct netbios_info_0 *)  // Pointer to next entry
                       ( pbBuffer + iCount * sizeof(struct netbios_info_0));
               printf("Network name = %s\n", p0->nb0_net_name);
            }
            else  // Assume sLevel == 1
            {
               p1 = (struct netbios_info_1 *)  // Pointer to next entry
                       (pbBuffer + iCount * sizeof(struct netbios_info_1));
               printf("   Network name: %s\n", p1->nb1_net_name);
               printf("   Driver name : %s\n", p1->nb1_driver_name);
               printf("   Adapter card: %c\n", p1->nb1_lana_num);
               printf("   Driver type : %hu\n", p1->nb1_driver_type);
               printf("   Status      : %hu\n", p1->nb1_net_status);
               printf("   Bandwidth   : %lu\n", p1->nb1_net_bandwidth);
               printf("   Max sessions: %hu\n", p1->nb1_max_sess);
               printf("   Max ncbs    : %hu\n", p1->nb1_max_ncbs);
               printf("   Max names   : %hu\n", p1->nb1_max_names);
            }
         }
         printf("%hu out of %hu entries read\n", cEntriesRead, cTotalAvail);
      }
      free(pbBuffer);

   //========================================================================
   // NetBiosGetInfo
   //
   // This API gets information about the specified network name.
   //========================================================================

      uRet = NetBiosGetInfo(pszServer,    // NULL means local
                 pszNetName,              // Network name
                 sLevel,                  // Level (0 or 1)
                 NULL,                    // Return buffer
                 0,                       // Size of return buffer
                 &cTotalAvail);           // Count of bytes available


      cbBuffer = cTotalAvail;
      pbBuffer = SafeMalloc(cbBuffer);

      uRet = NetBiosGetInfo(pszServer,    // NULL means local
                 pszNetName,              // Network name
                 sLevel,                  // Level (0 or 1)
                 pbBuffer,                // Return buffer
                 cbBuffer,                // Size of return buffer
                 &cTotalAvail);           // Count of bytes available


      printf("NetBiosGetInfo returned %u\n", uRet);
      if (uRet == NERR_Success)
      {
         if (sLevel == 0)
         {
            p0 = (struct netbios_info_0 *) pbBuffer;
            printf("   Network name = %s\n", p0->nb0_net_name);
         }
         else  // Assume sLevel == 1
         {
            p1 = (struct netbios_info_1 *) pbBuffer;
            printf("   Network name: %s\n", p1->nb1_net_name);
            printf("   Driver name : %s\n", p1->nb1_driver_name);
            printf("   Adapter card: %c\n", p1->nb1_lana_num);
            printf("   Driver type : %hu\n", p1->nb1_driver_type);
            printf("   Status      : %hu\n", p1->nb1_net_status);
            printf("   Bandwidth   : %lu\n", p1->nb1_net_bandwidth);
            printf("   Max sessions: %hu\n", p1->nb1_max_sess);
            printf("   Max ncbs    : %hu\n", p1->nb1_max_ncbs);
            printf("   Max names   : %hu\n", p1->nb1_max_names);
         }
      }
      free(pbBuffer);

   //========================================================================
   //  NetBiosOpen, NetBiosSubmit, NetBiosClose
   //
   //  These APIs open a handle to a particular logical network,
   //  submit an NCB, and then close the handle.
   //========================================================================

      uRet = NetBiosOpen(pszDevName,             // Devicename
                         0,                      // Reserved; must be
   0
                         usOpenOpt,              // Access mode
                         &hDevName);             // Pointer to handle

      printf("NetBiosOpen returned %u\n", uRet);
      if (uRet == NERR_Success)
      {
         ncbblock.ncb_command = cbCommand;

         uRet = NetBiosSubmit(hDevName,          // Handle for device
                              NCB_CHAIN_SINGLE,  // Chaining option
                              &ncbblock);        // Pointer to NCB

         printf("NetBiosSubmit returned %u\n", uRet);
         printf("   Return code = 0x%0x\n", ncbblock.ncb_retcode);

         uRet = NetBiosClose(hDevName,           // Handle for device
                             0);                 // Reserved; must be
   0

         printf("NetBiosClose returned %u\n", uRet);
      }
     exit(0);
   }

   void Usage(char *pszString)
   {
      fprintf(stderr, "Usage:  %s [-s \\\\server]", pszString);
      fprintf(stderr, " [-n netname] [-l level]\n");
      fprintf(stderr, "\t\t[-d device] [-o open option] [-c command]\n");
      exit(1);
   }







 Appendix F  Network Considerations for Named Pipes
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Named pipes provide a method for transferring data between different
 processes. The Named Pipe API functions control interprocess communication
 (IPC) for named pipes. These functions are part of MS OS/2 and do not
 require LAN Manager to be installed.

 This appendix provides a brief description of the Named Pipe API functions
 and outlines things you should consider when using named pipes in a network
 environment. For a full description of the Named Pipe API functions, see
 your MS OS/2 programming manual(s).

 The Named Pipe functions, datatypes, structures, and constants are defined
 in the MS OS/2 header file BSEDOS.H. A source program can access these
 definitions by defining the constant INCL_DOSNMPIPES, and including the MS
 OS/2 master header file, OS2.H.

 These are the Named Pipe API functions:

 (This figure may be found in the printed book.)


 Description

 A named pipe is a bidirectional interprocess communication facility that
 allows two processes, either local or remote, to communicate with each other
 over the network. A process that creates a named pipe is called a server
 process. A process that establishes a connection to a named pipe is called a
 client process.

 An example client/server pair of programs using named pipes is provided at
 the end of this appendix. For information about how to build the executable
 files for this example, see Appendix D, "Building the Sample Programs."

 To create an instance of a named pipe on the local computer, an application
 must call the DosMakeNmPipe function. This API function specifies
 information that enables the server process to control the named pipe and
 allows client processes to access the named pipe. To create a named pipe,
 DosMakeNmPipe needs the following:


   þ   The name of the named pipe in the format

        \pipe\pipename

       where pipename must be a valid MS OS/2 pathname

   þ   The directions (inbound, outbound, or full-duplex) in which the named
       pipe can send and/or receive data

   þ   Information as to whether the handle of the named pipe can be passed
       to spawned processes

   þ   The maximum number of concurrent instances of the named pipe that can
       be created

   þ   Other low-level parameters used by MS OS/2


 Note that the DosMakeNmPipe fsOpenMode and fsPipeMode parameters each
 contain several fields. The fsOpenMode parameter contains an access mode
 flag, an inheritance flag, and a write-behind flag. The fsPipeMode parameter
 contains an instance count, a read-mode flag, a type flag, and a wait flag.
 To ensure correct operation, values should be explicitly set for each of
 these elements.

 Each time DosMakeNmPipe is called with the same pipename, it creates another
 instance of the named pipe. Each instance is associated with a unique handle
 returned by DosMakeNmPipe. Thus, calling DosMakeNmPipe five times with the
 same information creates five different instances (or handles) of the same
 named pipe. Only the first call creates the pipe and sets the way it
 operates (for example, setting the duplex mode or the number of instances of
 the pipe that can be created).

 The direction in which data can be transferred across a named pipe is
 specified when the pipe is first created. A pipe created with the
 NP_ACCESS_INBOUND mode can transfer information only from the client to the
 server. A pipe created with the NP_ACCESS_OUTBOUND mode can transfer
 information only from the server to the client. A pipe created with the
 NP_ACCESS_DUPLEX mode can transfer information either way. The NP_ constants
 are defined in the BSEDOS.H header file.

 Even though a server process creates a named pipe on a computer, client
 processes cannot use the pipe until the server process calls
 DosConnectNmPipe. The call to DosConnectNmPipe must be made for each
 instance of the named pipe, when that instance is ready to receive a
 connection from a client process. The call does not return until a client
 process opens that instance of the named pipe, unless the pipe has a mode
 of NP_NOWAIT.

 A client application can call DosOpen to open an instance of the named pipe.
 DosOpen returns a handle to the client process; the handle can be used to
 read from and write to the named pipe. If DosOpen returns ERROR_PIPE_BUSY,
 there is no instance of the named pipe currently waiting for a connection.
 DosWaitNmPipe can be called to wait for an instance of the named pipe to
 become available.

 DosWaitNmPipe can be configured to time out after a particular period of
 time or to wait indefinitely for an instance of the named pipe. When an
 instance of the named pipe becomes available, DosWaitNmPipe returns to the
 waiting client process. At this point, the client process can call DosOpen
 to open the named pipe. After a client process has opened an instance of a
 named pipe, it can read and write to the pipe.

 DosWaitNmPipe returns as soon as an instance of the named pipe becomes
 available. If multiple clients attempt to connect to the pipe, as is likely
 with multiple workstations all trying to connect to one server, the wait and
 open operations should be put in a loop, as shown here:

   while (TRUE)
   {
       if ((usReturnCode = DosOpen(pszNamedPipe, ...) != ERROR_PIPE_BUSY)
    break;
       DosWaitNmPipe(pszPipeName, ...);
   }

 This is necessary because another client process can connect to the
 available instance of the pipe between the time DosWaitNmPipe returns and
 DosOpen opens the pipe.

 Note that a remote named pipe can be opened by specifying the pipename, as
 follows:

 \\server\pipe\pipename

 To transfer data over the named pipe, the client process can use DosRead and
 DosWrite. Both of these functions accept the handle returned by DosOpen. If
 a server or client process requires that reading and writing of named pipes
 be executed asynchronously, the process can call DosReadAsync or
 DosWriteAsync.

 Data written to the client end of a remote named pipe can be held
 temporarily in a data buffer. The length of time data is held there is
 controlled by the charcount and chartime parameters of the LANMAN.INI file.
 The charcount parameter specifies the maximum number of bytes of data that
 will be buffered before being sent over the network. If less than charcount
 bytes are written to the pipe, they will not be transferred for up to
 chartime milliseconds. These values can be tuned on a per-handle basis by
 using the NetHandleSetInfo function. For more information, see the Handle
 category API functions in Chapter 2, "API Function Descriptions."

 DosBufReset can be called on either side of a named pipe to ensure all data
 written to a named pipe has been read from the other end. The call does not
 return until all data has been read.

 A process can call DosPeekNmPipe to see if there is any data written to a
 named pipe. DosPeekNmPipe reads the data in a named pipe but does not remove
 the data; it never blocks waiting for data to become available.

 A process can call DosDupHandle to replicate a handle to either end of a
 named pipe. DosDupHandle returns a new handle to the same instance of the
 pipe. This handle can be passed to any function that could use the old
 handle.

 DosTransactNmPipe and DosCallNmPipe decrease the overhead involved in
 writing to and reading from a named pipe. DosTransactNmPipe writes a message
 to, and then reads a message from, an opened named pipe. DosCallNmPipe
 opens, writes to, reads from, and then closes a named pipe. Because these
 functions reduce the number of network transactions, they should be used on
 the pipe in network operations instead of DosOpen, DosRead, DosWrite, and
 DosClose.

 When a client process no longer requires access to a named pipe, it can call
 DosClose to close the named pipe. Calling DosClose on the server end of the
 named pipe removes the instance of the pipe but does not break the
 connection. Data already written to the pipe can still be read by the
 client. When the client also closes the pipe, that instance of the pipe is
 no longer available.

 When a server process no longer requires a connection to a named pipe, it
 can call DosDisConnectNmPipe to remove that instance of the named pipe by
 specifying its handle. If a client process is still accessing the named
 pipe, DosDisConnectNmPipe breaks the connection.

 The following API functions enable server or client processes to obtain
 information about a named pipe or its handle:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Function                          Purpose
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 DosQFHandState                    Determines whether the handle can be
                                   inherited and if write-behind is allowed.


 DosQHandType                      Returns the type of handle.

 DosQNmPHandState                  Returns the low-level parameters
                                   associated with a handle and the pipe's
 Function                          Purpose
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  associated with a handle and the pipe's
                                   operating mode, including the instance
                                   count.

 DosQNmPipeInfo                    Returns the size of buffers and the
                                   number of instances currently available.


 DosQNmPipeSemState                Returns the state of a semaphore
                                   associated with a named pipe.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 MS OS/2 provides three API functions that enable server or client processes
 to set specific information that can be queried about a named pipe. You can
 set the following functions and parameters:

 Function                          Purpose
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 DosSetFHandState                  Sets whether a named pipe's handle can
                                   be inherited and if write-behind is
                                   allowed.



 DosSetNmPHandState                Sets low-level parameters associated
                                   with a particular instance of a pipe,
                                   such as read and write mode.

 DosSetNmPipeSem                   Sets the association of a semaphore to a
                                   named pipe.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 You can set the transfer mode of a named pipe by using either DosMakeNmPipe
 or DosSetNmPHandState; a named pipe transfers data in byte-stream or
 message-stream mode.

 A named pipe operating in byte-stream mode operates like an anonymous pipe;
 all data written is transferred without any special processing performed on
 it. When operating in message-stream mode, a named pipe can distinguish
 between the different messages read from and written to it. It can also
 distinguish the size of each message.

 Named pipes are designed so that a client process need not know what type of
 resource it is opening (pipe or file). Client processes can use DosOpen,
 DosRead, and DosClose to open, read, and close both types of
 resourcesÄwithout being aware that one is a file and the other is a named
 pipe. The Microsoft C run-time library functions open( ), read( ), write( ),
 and close( ) can also be used with named pipes.

 The following table describes the transition state of a named pipe, based on
 the action a server or client process indicates:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Current State        Action/Process               Next State
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Pipe does not exist  DosMakeNmPipe, server        NP_DISCONNECTED
 Current State        Action/Process               Next State
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Pipe does not exist  DosMakeNmPipe, server        NP_DISCONNECTED
 NP_DISCONNECTED      DosConnectNmPipe, server     NP_LISTENING
 NP_LISTENING         DosOpen, client              NP_CONNECTED
 NP_CONNECTED         DosDisConnectNmPipe, server  NP_DISCONNECTED
 NP_CONNECTED         DosClose, client             NP_CLOSING
 NP_CLOSING           DosDisConnectNmPipe, server  NP_DISCONNECTED
 NP_CONNECTED         DosClose, server             NP_CLOSING
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Note that the MS OS/2 DosChgFilePtr function (and other functions that
 perform seek operations on files) does not work with named pipes.


 MS-DOS Considerations

 Named pipes cannot be created on a computer running MS-DOS. However, client
 applications can access named pipes created on a remote server, provided
 that the client has the appropriate access permissions.

 MS-DOS does not support asynchronous reading and writing of named pipes.

 The Family API replacement library routine for DosOpen provides support for
 DASD opens (OPEN_FLAGS_DASD). Since MS-DOS does not support this operation,
 pipe operations on this type of file handle return ERROR_INVALID_HANDLE
 rather than ERROR_BAD_PIPE.

 DosBufReset works differently depending on which version of MS-DOS you are
 programming with. With versions 3.3 and 4.0, DosBufReset returns
 ERROR_BROKEN_PIPE if the handle is to a named pipe that has already been
 closed. With MS-DOS 3.2 and earlier versions, DosBufReset returns NO_ERROR
 even if the pipe is already closed.

 With MS-DOS 3.2 and earlier versions, DosBufReset does not wait until the
 pipe is empty before resetting it. With MS-DOS 3.3 and 4.0, DosBufReset
 waits for the pipe to be emptied.

 See Also

 For information about             See
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Anonymous pipes, named pipes, or  MSOS/2 programming manual(s)
 interprocess communication (IPC)





 Named Pipes Category Example

   /*
      NPSERVER.C -- A sample program demonstrating named pipes.

      NPSERVER and NPCLIENT work together to demonstrate using named
   pipes in
      a simple client/server application pair. Since no LAN Manager-specific
      API functions are used, these programs can run without LAN Manager
      being installed.

      usage:  npserver [-c count]

      where count = Number of clients to support.

      Start NPSERVER on a computer running MS OS/2, specifying the number
      of clients to support (see below). From other MS OS/2 sessions
   on
      the same computer or from a remote computer, start as many instances
      of NPCLIENT as NPSERVER was instructed to support. Each NPCLIENT

      writes and reads 1 message when any key is pressed. After
      10 messages have been written/read, NPCLIENT terminates. For each
      message received, NPSERVER echoes the message to the sender.

      NPSERVER uses only two threads to handle all pipe instances created.
      The primary thread, after creating a pipe instance, associates
   a
      semaphore with the instance. Then, by calling DosMuxSemWait, NPSERVER
      waits for pipe activity. When DosMuxSemWait returns, NPSERVER responds
      to the pipe instance whose semaphore was cleared, and then waits
   again.

      The second thread is a monitor thread that wakes every 10 seconds
      and scans for pipe instances that are now closed (the client
 application

      is no longer using the pipe). The pipe instance is then disconnected
   and
      reconnected to make it available to possible new clients.

      This technique allows multiple pipe instances to be handled with
      a minimum number of threads. Instead of using DosMuxSemWait,
      DosQNmPipeSemState can also be used. It is also possible to associate
      its own thread with each pipe instance.

      API                  Used to...
      ===========          ==================================================
      DosMakeNmPipe        Create a multi-instance named pipe
      DosConnectNmPipe     Start listening for each instance
      DosSetNmPipeSem      Associate each pipe instance with a semaphore


   DosPeekNmPipe        Check if the pipe is still active
      DosDisConnectNmPipe  Disconnect the pipe (so the pipe can be reused)
      DosRead              Read data from the named pipe
      DosWrite             Write data to the named pipe

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_BASE
   #include    <os2.h>        // MS OS/2 base header files

   #include    <stdio.h>      // C run-time header files
   #include    <stdlib.h>
   #include    <string.h>
   #include    <malloc.h>

   #include    "samples.h"    // Internal routine header file

   #define  MAXPIPES    (16)        // Max. semaphores for DosMuxSemWait
   = 16
   #define  BUFSIZE     (1024)      // Input and output buffers for named
   pipes
   #define  STACKSIZE   (2048)      // Stack for monitor thread
   #define  PIPE_NAME   "\\PIPE\\MYPIPE.XYZ"
   #define  SEM_NAME    "\\SEM\\MYSEM.A"

   #define  FATALERROR(mess, var)   { fprintf(stderr, mess, var); exit(1);
   }
   DEFINEMUXSEMLIST(MuxList, MAXPIPES)       // Structure for DosMuxSemWait
   HPIPE    hPipe[MAXPIPES];                 // Array of pipe handles
   USHORT   usNumPipes = 8;                  // Max. instances of pipe
   created

   // Function prototypes.
   VOID     CreatePipes(USHORT usNumPipes);
   VOID     MessageLoop(void);
   VOID FAR Monitor(void);
   TID      StartMonitor(void);
   VOID     Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      INT  iCount;                                // Index counter

   for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1)))   // Process switches
            {
               case 'c':                          // -c clients
                  usNumPipes = atoi(argv[++iCount]);
                  usNumPipes = max(usNumPipes, 1);
                  usNumPipes = min(usNumPipes, MAXPIPES);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

      CreatePipes(usNumPipes);         // Create pipes and associate
   semaphores
      StartMonitor();                  // Begin monitoring for closed
   pipes

      printf("Ready to connect to %u clients\n", usNumPipes);

      MessageLoop();

      DosExit(EXIT_PROCESS, 0);
   }

   //========================================================================
   //  CreatePipes
   //
   //  Create specified number of instances of the named pipe. A more
   memory-
   //  efficient method is to make new instances only when they are needed.

   //  This avoids unnecessary named-pipe buffer overhead.
   //========================================================================

   void CreatePipes(USHORT usNumPipes)
   {
      CHAR     *pszPipeName = PIPE_NAME;              // Pipename
      CHAR     *pszSemName  = SEM_NAME;               // Pipe semaphore
   name
      USHORT   usInst;                                // Pipe instance
   counter
      USHORT   usResult;                              // MS OS/2 return
   code

   MuxList.cmxs = usNumPipes;
      if (usResult = DosSetMaxFH(usNumPipes + 20))
         FATALERROR("Error setting max file handles: %hu\n", usResult)
      for (usInst = 0; usInst < usNumPipes; usInst++)
      {
         // Create a new semaphore for each instance of the pipe.
         usResult = DosCreateSem(CSEM_PUBLIC, &MuxList.amxs[usInst].hsem,
                                 pszSemName);
         if (usResult)
         {
            if (usResult == ERROR_ALREADY_EXISTS)
               printf("Error: This application has already started.\n");
            else
               printf("Error creating semaphore: %hu\n", usResult);
            exit(1);
         }

         // Set the semaphore name for the next pipe instance (e.g.,
   mysem.b).
         pszSemName[strlen(pszSemName)-1]++;

         usResult = DosMakeNmPipe(pszPipeName,
                    &hPipe[usInst],             // Pipe handle (returned)
                    NP_ACCESS_DUPLEX |          // Open mode
                    NP_WRITEBEHIND,
                    NP_TYPE_MESSAGE |           // Pipe mode
                    NP_NOWAIT       |           // No blocking
                    usNumPipes,                 // Max. number of instances
                    BUFSIZE,                    // Size of output buffer

                    BUFSIZE,                    // Size of input buffer

                    0L);                        // Time-out value (use
   default)
         if (usResult)
            FATALERROR("Error making named pipe: %hu\n", usResult)

         usResult = DosConnectNmPipe(hPipe[usInst]);
         if ((usResult != NO_ERROR) && (usResult !=
 ERROR_PIPE_NOT_CONNECTED))
            FATALERROR("Error connecting named pipe: %hu\n", usResult)

         if (usResult = DosSetNmPipeSem(hPipe[usInst],
                                        MuxList.amxs[usInst].hsem, usInst))
            FATALERROR("DosSetNmPipeSem error: %hu\n", usResult)

         if (usResult = DosSemSet(MuxList.amxs[usInst].hsem))
            FATALERROR("Error setting semaphore: %hu\n", usResult)
      }
   }

   //========================================================================
   //  StartMonitor
   //
   //  Start monitor thread to check for closed pipes.
   //========================================================================

   TID StartMonitor(void)
   {
      USHORT      usResult;                  // MS OS/2 return code
      BYTE FAR    *pStack;                   // Pointer to child's stack
      TID         tidMonThread;              // Child process TID

      pStack = (BYTE FAR *)SafeMalloc(STACKSIZE);
      if (pStack == NULL)
         FATALERROR("Error: Out of memory.\n", 0)
      pStack += STACKSIZE;                   // Pointer to top of stack

      if (usResult = DosCreateThread(Monitor, &tidMonThread, pStack))
         FATALERROR("Error creating Monitor thread: %hu\n", usResult)

      return(tidMonThread);
   }

   //========================================================================
   //  Monitor
   //
   //  Monitor the status of all pipes every 10 seconds. If this thread
   finds
   //  a pipe that has been closed (making the pipe no longer usable),
   it
   //  disconnects and reconnects it, making it available again for a
   client
   //  to open it with DosOpen.
   //========================================================================

   VOID FAR Monitor(void)
   {
      USHORT     usInst;                     // Pipe instance counter
      USHORT     usBytesRead;                // Bytes read from pipe
      AVAILDATA  bAvailData;                 // Number of bytes available
      USHORT     usState;                    // Pipe state
      USHORT     usResult;                   // MS OS/2 return code

      for (;;)
      {
         DosSleep(10000L);                   // Sleep for 10 seconds
         for (usInst = 0; usInst < usNumPipes; usInst++)

   {
            usResult = DosPeekNmPipe(hPipe[usInst],   // Pipe handle
                                     NULL,            // Do not read
   pipe data
                                     0,               // Length of buffer
                                     &usBytesRead,    // Number of bytes
   read
                                     &bAvailData,     // Bytes available
                                     &usState);       // Pipe state
            if (usState & NP_CLOSING)
            {
               usResult = DosDisConnectNmPipe(hPipe[usInst]);
               usResult = DosConnectNmPipe(hPipe[usInst]);
            }
         }
      }
   }

   //========================================================================
   //  MessageLoop
   //
   //  This is the point where the template ends and your program begins.
   //  This example simply reads a message, displays it, and sends a
   reply.
   //  A typical application would first get a logon-type message identifying
   //  the user of a particular pipe instance, store the user information
   (to
   //  keep track of which users are using which instances of the pipe),
   and
   //  then process each additional request when received.
   //========================================================================

   VOID MessageLoop(void)
   {
      USHORT   usInst;                          // Pipe instance counter
      USHORT   usMsgCnt = 0;                    // Message counter
      USHORT   usResult;                        // MS OS/2 return code
      USHORT   usBytesRead;                     // Bytes read by DosRead
      USHORT   usBytesWritten;                  // Bytes written by DosWrite
      CHAR     *pszBuf;                         // Read buffer
      CHAR     pszReply[80];                    // Message to send to
   client

      // Allocate the read buffer.
      if ((pszBuf = SafeMalloc(BUFSIZE)) == NULL)
         FATALERROR("Out of memory.\n", 0)

      // Process pipe request forever.
      for (;;)



   {
         // Wait for activity to occur on a pipe.
         if (usResult = DosMuxSemWait(&usInst, &MuxList,
 SEM_INDEFINITE_WAIT))
            FATALERROR("Error in DosMuxSemWait: %hu\n", usResult)

         // Reset the semaphore.
         if (usResult = DosSemSet(MuxList.amxs[usInst].hsem))
            FATALERROR("DosSemSet returns %hu\n", usResult)

         // Read the message from the client.
         usResult = DosRead(hPipe[usInst], pszBuf, BUFSIZE, &usBytesRead);
         if ((usResult == ERROR_NO_DATA) || (usBytesRead == 0))
            continue;                       // False alarm, nothing to
   read
         printf("Message received from %hu: %s\n", usInst, pszBuf);

         // Reply to the user (with the user's message incremented).
         sprintf(pszReply, "Reply number %u", usMsgCnt++);
         usResult = DosWrite(hPipe[usInst],
                             pszReply,
                             strlen(pszReply)+1,
                             &usBytesWritten);
         if ((usResult != NO_ERROR) ||
             (usBytesWritten != (strlen(pszReply)+1)))
            printf("DosWrite returned %hu with %u bytes written.\n",
                    usResult, usBytesWritten);
      }
   }

   //========================================================================
   //  Usage
   //
   //  Print the usage statement, then exit.
   //========================================================================

   VOID Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-c count] \n", pszProgram);
      exit(1);
   }

   /*
      NPCLIENT.C -- A sample program demonstrating named pipes.

      NPSERVER and NPCLIENT work together to demonstrate using named
   pipes in
      a simple client/server application pair. Since no LAN Manager-specific
      API functions are used, these programs can run without LAN Manager

      being installed.

      The client application, NPCLIENT, opens the named pipe, sends and
      receives 10 messages (one message each time a key is pressed),
   closes
      the pipe, and terminates. For additional details, see NPSERVER.C.

      NOTE:  Because this program uses Family API functions (FAPIs) for

             pipe access, it must be built as a bound application.

      usage:  npclient [-s \\servername]

      where \\server = Name of the server (defaults to the local
                       machine). A servername must be preceded by
                       two backslashes (\\).

      API                  Used to...
      ===========          =================================================
      DosOpen              Open a named pipe
      DosWrite             Write a message to the pipe
      DosRead              Send a message to the pipe
      DosClose             Close a named pipe

      This code sample is provided for demonstration purposes only.
      Microsoft makes no warranty, either express or implied,
      as to its usability in any given situation.
   */

   #define     INCL_DOSNMPIPES
   #define     INCL_DOSERRORS
   #include    <os2.h>        // MS OS/2 header files

   #define     INCL_NETERRORS
   #include    <lan.h>        // LAN Manager header files

   #include    <conio.h>      // C run-time header files
   #include    <stdio.h>
   #include    <stdlib.h>
   #include    <string.h>

   #include    "samples.h"    // Internal routine header file

   #define     BUFSIZE                 (1024)
   #define     PIPE_NAME               "\\PIPE\\MYPIPE.XYZ"
   #define     FATALERROR(mess, var)   { fprintf(stderr, mess, var);
   exit(1); }

   // Function prototypes.
   VOID Usage (char * pszProgram);

   void main(int argc, char *argv[])
   {
      USHORT   usResult;                     // MS OS/2 return code
      USHORT   usAction;                     // DosOpen file action
      USHORT   usByteCnt;                    // Bytes read/written
      INT      iCount;                       // Index counter
      HPIPE    hPipe;                        // Named pipe handle
      CHAR     *pbBuf;                       // Receive buffer
      CHAR     pszMessage[80];               // Send buffer
      CHAR     pszPipeName[80];              // Pipename

      *pszPipeName = '\0';

      for (iCount = 1; iCount < argc; iCount++)
      {
         if ((*argv[iCount] == '-') || (*argv[iCount] == '/'))
         {
            switch (tolower(*(argv[iCount]+1)))    // Process switches
            {
               case 's':                           // -s servername
                  strcpy(pszPipeName, argv[++iCount]);
                  break;
               case 'h':
               default:
                  Usage(argv[0]);
            }
         }
         else
            Usage(argv[0]);
      }

      strcat(pszPipeName, PIPE_NAME);              // Set pipename

      if ((pbBuf = SafeMalloc(BUFSIZE)) == NULL)   // Allocate data buffer
         FATALERROR("Out of memory.\n", 0)

      usResult = DosOpen(pszPipeName,              // Pipename
                         &hPipe,                   // Pipe handle
                         &usAction,                // Action
                         0L,                       // Initial file size
                         FILE_NORMAL,              // File attribute
                         FILE_CREATE | FILE_OPEN,  // Open flag
                         OPEN_ACCESS_READWRITE |   // Bidirectional pipe
                         OPEN_SHARE_DENYREADWRITE,
                         0L);                      // Reserved; must
   be 0

      // Check for standard MS OS/2 errors first.
      if (usResult == ERROR_PATH_NOT_FOUND)
         FATALERROR("Unable to open pipe\n", 0)

      else if (usResult == ERROR_PIPE_BUSY)
         FATALERROR("The maximum number of clients are already connected\n",
   0)

      /*
       * The next two errors are defined in NETCONS.H and are returned
       * only for remote pipes.
       */
      else if (usResult == ERROR_BAD_NETPATH)
         FATALERROR("Network path \"%s\" is not valid\n", pszPipeName)

      else if (usResult == ERROR_NETWORK_ACCESS_DENIED)
         FATALERROR("You do not have permission on that server\n", 0)

      // Otherwise, if an error was returned, it's an unexpected one.
      else if (usResult)
         FATALERROR("Error opening named pipe: %u\n", usResult)

      printf("Ready to send messages 0 to 9 (press Enter)\n");
      for (iCount = 0; iCount < 10; iCount++)
      {
         getch();                      // Wait for key press

         sprintf(pszMessage, "Message number %u", iCount);
         usResult = DosWrite(hPipe,                // Pipe handle
                             pszMessage,           // Output data
                             strlen(pszMessage)+1, // Output size
                             &usByteCnt);          // Bytes written
         if (usResult != NO_ERROR)
           printf("DosWrite returned error %u\n", usResult);

         usResult = DosRead(hPipe,                 // Pipe handle
                            pbBuf,                 // Input buffer
                            BUFSIZE,               // Input size
                            &usByteCnt);           // Bytes read

   if (usResult == NO_ERROR)
            printf("Received message: %s\n", pbBuf);
         else
            printf("DosRead returned error %u\n", usResult);
      }

      DosClose(hPipe);
      exit(0);
   }

   VOID Usage (char * pszProgram)
   {
      fprintf(stderr, "Usage: %s [-s \\\\server] \n", pszProgram);
      exit(1);
   }








 Appendix G  Workstation and Server Heuristics
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Heuristics are flags or settings used to configure workstation and server
 performance. The workstation heuristics element, wkiX_heuristics, is an
 element of the wksta_info_X data structure, where X is 0 or 1. Workstation
 heuristics optimize a workstation's performance. The server heuristics
 element, svX_srvheuristics, is an element of the server_info_X data
 structure, where X is 2 or 3. Server heuristics optimize a server's
 performance.


 Workstation Heuristics

 wkiX_heuristics (MS OS/2 only)

   A set of digits that configure how a workstation processes network
   information. Digits read from left (0) to right (54). A value of 0 means
   "off" or "inactive" ; 1 means "on" or "active." Other values are explained
   in the following descriptions of each digit:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 Request opportunistic locking of files.
                                   This opens files on the server with
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  This opens files on the server with
                                   "deny none" rights, allowing faster
                                   buffering. If another workstation
                                   requests access to the same file, the
                                   server lets the first workstation flush
                                   data before granting access to the
                                   second.

                                   The default is 1.

 1                                 Optimize performance for command files.
                                   Heuristic 0, opportunistic locking, must
                                   be set to 1.

                                   The default is 1.

 2                                 Unlock and WriteUnlock asynchronously as
                                   follows:

                                   0 = Never
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  0 = Never
                                   1 = Always
                                   2 = Only on a LAN Manager virtual
                                   circuit (VC)

                                   The default is 1.

                                   When a user unlocks a file, it usually
                                   works if the application is written
                                   correctly. If Unlocks and WriteUnlocks
                                   are asynchronous, the user need not wait
                                   for the server to indicate the bytes
                                   were unlocked. If asynchronous Unlock
                                   and WriteUnlock is selected, the user
                                   overlaps local processing with the
                                   server processing the Unlock (and
                                   overlap transport time). Asynchronous
                                   Unlock and WriteUnlock are not used if
                                   write-through is set.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 3                                 Close and WriteClose asynchronously as
                                   follows:

                                   0 = Never
                                   1 = Always
                                   2 = Only on a LAN Manager VC

                                   The default is 1.

                                   When transferring large files, the
                                   workstation can get ahead of the server
                                   if all data transferred to the server is
                                   in its buffers but not processed to disk.
                                   When the server gets a Close or
                                   WriteClose request, it flushes all data
                                   to disk (or to the operating system
                                   cache) before it processes and returns
                                   the Close response. When this digit is
                                   set to 1, the Close is sent, the
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  set to 1, the Close is sent, the
                                   workstation does not wait for the
                                   response, and a user can overlap local
                                   processing with the server (write to
                                   disk at the same time). A "some data may
                                   have been lost" popup message warns
                                   users if all data is not written to disk.


 4                                 Buffer named pipes and communication
                                   devices.

                                   The default is 1.

                                   Buffering named pipes and communication
                                   devices protects information by putting
                                   it in a buffer. Then the workstation
                                   reads
                                   the information from the buffer.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 5                                 LockRead and WriteUnlock as follows:

                                   0 = Never
                                   1 = Always
                                   2 = Only on a LAN Manager VC

                                   The default is 1.





                                   The following diagrams illustrate this
                                   option for a database. The first diagram
                                   shows what happens when LockRead and
                                   WriteUnlock is 0:



 Workstation                       Server
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 lock -->

 <--                               OK,, it's locked

 read -->

 <--                               OK,, here is your data

 (update data record)

 write -->

 <--                               OK,, data written

 unlock -->

 <--                               OK,, it's unlocked

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                   This diagram shows what happens when
                                   LockRead and WriteUnlock is 1 (default):


 Workstation                       Server
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 LockRead -->,

 <--                               OK,, it's locked and here is your data

 (update data record)

 WriteUnlock -->

 <--                               OK,, it's written and unlocked

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                   Some applications use a dummy file to
                                   control the real database file (this
                                   means the application locks file A and
                                   reads file B). Data read along with the
                                   lock on file A is never used. On a
                                   high-speed network this should not
                                   matter, but on a slow network this could
                                   cause a time loss. If you have a slow
                                   network and regularly use a database
                                   that uses a dummy file, consider setting
                                   this heuristic to 0.



ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 6                                 Use Open and Read.

                                   Set to 1, this heuristic combines Open
                                   and Read to get the first portion of a
                                   file at the same time the file is opened.
                                   This is faster because most files are
                                   read sequentially. For files that are
                                   not read sequentially, little
                                   performance is lost on a high-speed
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  performance is lost on a high-speed
                                   network. On a slow network, turn this
                                   off (0) if you use many applications
                                   that read files randomly.

                                   The default is 1.

 7                                 Read-ahead to sector boundary.

                                   A file system that is not sensitive to
                                   the location of information or the
                                   reading of partial sectors on a disk (or
                                   one that has an active cache) performs
                                   better by reading ahead to a sector
                                   boundary.

                                   The default is 1.

 8                                 Use the "chain send" NetBIOS NCB as
                                   follows:
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  follows:

                                   0 = Never
                                   1 = Only if the server's buffer is
                                   larger than the workstation buffer
                                   2 = Always (to avoid copy)

                                   The default is 2.

                                   A chained send enables sending data
                                   directly from the user's buffer to the
                                   transport driver (bypassing data copy).
                                   The transport driver design determines
                                   which setting is optimal.

 9                                 Buffer small read/write requests
                                   (reading and writing a full buffer) as
                                   follows:

                                   0 = Never
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  0 = Never
                                   1 = Always
                                   2 = Only on a LAN Manager VC

                                   The default is 1.

 10                                Use buffer mode (assuming that shared
                                   access is granted) as follows:

                                   0 = Always read bufsize if request is
                                   smaller than bufsize
                                   1 = Use full buffer if file is open for
                                   read/write
                                   2 = Use full buffer if reading/writing
                                   sequentially
                                   3 = Buffer all requests that are smaller
                                   than bufsize

                                   The default is 3.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 11                                Use raw data transfer (RAW) read/write
                                   server message block (SMB) protocols.

                                   The default is 1.

 12                                Use large RAW read-ahead buffer.

                                   The default is 1.

 13                                Use large RAW write-behind buffer.

                                   The default is 1.

 14                                Use read multiplex (MPX) SMB protocols.

                                   The default is 1.

 15                                Use write multiplex SMB protocols.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

                                   The default is 1.

 16                                Use big buffer for large core reads.

                                   The default is 1.

 17                                Set the read-ahead size as follows:

                                   0 = Read to sector boundary
                                   1 = Use a multiple of the size the user
                                   is reading

                                   The default is 1.

                                   For example, if the user is reading
                                   50-byte pieces of a 4096-byte buffer,
                                   LAN Manager reads ahead to fill the
                                   buffer to 4050 bytes.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 18                                Set the write-behind size as follows:

                                   0 = Write to sector boundary
                                   1 = Use a multiple of the size the user
                                   is writing

                                   The default is 1.

 19                                Force 512-byte maximum transfers to and
                                   from core servers. At one time, core
                                   servers (same base SMB protocols as LAN
                                   Manager) could handle a maximum of
                                   512-byte buffers. Set this bit only if
                                   your network has this type of server and
                                   your workstation accesses the server.

                                   The default is 0.

 20                                Flush pipes and devices on DosBufReset
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
20                                Flush pipes and devices on DosBufReset
                                   or DosClose as follows:

                                   0 = Only files/devices opened by caller;
                                   spin until flushed
                                   1 = Only files/devices opened by caller;
                                   flush only once
                                   2 = All files and all short-term
                                   pipe/device I/O; spin until flushed
                                   3 = All files and all short-term
                                   pipe/device I/O; flush only once
                                   4 = All files and pipe/device I/O; spin
                                   until flushed
                                   5 = All files and pipe/device I/O; flush
                                   only once

                                   The default is 0.

 21                                Use encryption if the server supports it.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

                                   The default is 1.

 22                                Control log entries for multiple
                                   occurrences of an error. Prevent a
                                   recurring error from filling up the
                                   error log by activating an interim table.

                                   Non-zero values for this heuristic
                                   define the number of errors in the table.
                                   For example, if you set the heuristic to
                                   5, the error table holds
                                   5 errors in the following form:

                                   Error id number
                                   Number of occurrences

                                   Set the heuristic as follows:

                                   0 = Log all error occurrences in the
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  0 = Log all error occurrences in the
                                   error log
                                   1 = Use error table, size 1
                                   2 = Use error table, size 2
                                   3 = Use error table, size 3
                                   4 = Use error table, size 4
                                   5 = Use error table, size 5
                                   6 = Use error table, size 6
                                   7 = Use error table, size 7
                                   8 = Use error table, size 8
                                   9 = Use error table, size 9

                                   The default is 0.

                                   For each entry in the table, LAN Manager
                                   writes to the error log on the 1st, 4th,
                                   8th, 16th, 32nd, and every further 32nd
                                   occurrence of the error.

                                   When an error occurs, LAN Manager
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  When an error occurs, LAN Manager
                                   determines whether the error
                                   is already listed in the table. If it is,
                                   LAN Manager increments the number of
                                   occurrences. If the error is not in the
                                   table, LAN Manager adds it to the table.
                                   If the table is full, LAN Manager
                                   discards the entry with the lowest
                                   number of occurrences to make room for
                                   the new entry.

                                   NOTE "Out of Resource" errors are logged
                                   only once per resource type regardless
                                   of the value of this heuristic.



ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 23                                Buffer all files opened with "deny write"
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 23                                Buffer all files opened with "deny write"
                                   rights.

                                   The default is 1.

 24                                Buffer all files opened with R (read
                                   only) attribute.

                                   The default is 1.

 25                                Read ahead when opening a file for
                                   execution. (Sometimes reading an
                                   executable file appears sequential when
                                   it is not.)

                                   The default is 1.

 26                                Handle CTRL-C as follows:

                                   0 = Do not allow interrupts
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  0 = Do not allow interrupts
                                   1 = Allow interrupts only on long-term
                                   operations
                                   2 = Always allow interrupts

                                   The default is 2.

 27                                Force correct open mode when creating
                                   files on a core server. Core servers
                                   open a new file in compatibility mode,
                                   which is not ordinarily a problem. This
                                   heuristic forces the workstation to
                                   close the file and reopen it in the
                                   proper mode.

                                   The default is 0.

 28                                Use the NetBIOS NoAck mode (transfer
                                   data without an immediate acknowledgment)
                                   as follows:
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  as follows:

                                   0 = Never
                                   1 = NoAck on send only
                                   2 = NoAck on receive only
                                   3 = NoAck on send and receive

                                   The default is 0.

 29                                Send data along with SMB write-block-RAW
                                   requests.

                                   The default is 1.

 30                                Send a popup when the workstation logs
                                   an error, as follows:

                                   0 = Never
                                   1 = On write fault errors only (no
                                   time-out)
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  time-out)
                                   2 = On write fault and internal errors
                                   only (no time-out)
                                   3 = On all errors (no time-out)
                                   4 = (Reserved)
                                   5 = On write fault errors only (time-out)

                                   6 = On write fault and internal errors
                                   only (time-out)
                                   7 = On all errors (time-out)

                                   The default is 1.

 31                                Close the print job, causing the remote
                                   spooler to print it if no activity
                                   occurs on the printer for the time
                                   specified:

                                   0 to 8 = (value+1) * 8 seconds
                                   9 = Number of seconds specified by
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  9 = Number of seconds specified by
                                   printbuftime

                                   The default is 2.


 32                                Controls BufReset and SMBFlush behavior
                                   for the MS-DOS compatibility box:

                                   0 = Flush dirty buffers to server, and
                                   wait for server to flush buffers to
                                    hard disk
                                   1 = Flush dirty buffers to server, but
                                   do not wait
                                   2 = Ignore BufReset

                                   The default is 2.

 33                                Controls the time-out value for
                                   performing logon validation from a
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  performing logon validation from a
                                   domain controller, as follows:

                                   0 = 5 seconds
                                   1 = 15 seconds
                                   2 = 30 seconds
                                   3 = 45 seconds
                                   4 = 1 minute
                                   5 = 1 minute, 30 seconds
                                   6 = 2 minutes
                                   7 = 4 minutes
                                   8 = 8 minutes
                                   9 = 15 minutes

                                   The default is 1.

 34-54                             Reserved.



 wkiX_heuristics (MS-DOS only)
   A set of digits that configure how an MS-DOS workstation processes network
   information. Digits read from left (0) to right (32). A value of 0 means
   "off" or "inactive"; 1 means "on" or "active." Other values are explained
   in the following descriptions of each digit:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 Turn on write-through bit on all open
                                   files.

                                   The default is 1.

 1                                 Do asynchronous write buffer and close
                                   operations.

                                   The default is 1.

 2                                 Determine if NetBIOS performs a SEND
                                   operation during Power-On, Self-Test
                                   (POST).
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  (POST).

                                   The default is 1 (allow NetBIOS to SEND
                                   during POST).

 3                                 Use buffer size transfer as follows:

                                   0 = Limit transfer to local buffer size
                                   1 = Use two read operations for core
                                   read
                                   2 = Use "Message Incomplete" error for
                                   transfer (system performance   is
                                   degraded)

                                   The default is 1.

                                   This parameter is used for I/O core
                                   servers.

 4                                 Use buffer mode (assuming that shared
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
4                                 Use buffer mode (assuming that shared
                                   access is granted) as follows:

                                   0 = Always read bufsize if request is
                                   smaller than bufsize
                                   1 = Use full buffer if file is open for
                                   read/write
                                   2 = Use full buffer if reading/writing
                                   sequentially

                                   The default is 2.

 5                                 Pop up for hard errors.

                                   The default is 1 (pop up hard errors).

 6                                 Big buffer read-ahead. If not selected,
                                   system performance could be degraded.

                                   The default is 1 (use big buffer
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  The default is 1 (use big buffer
                                   read-ahead).

 7                                 Send process exit SMBs as follows:

                                   0 = Don't send
                                   1 = Always send
                                   2 = Send based on redirector process
                                   data block (RPDB) structure
                                     (this option is not implemented in LAN
                                   Manager 2.0)

                                   The default is 0.

 8                                 Request opportunistic locking of files.
                                   This opens files on the server with
                                   "deny none" rights, allowing faster
                                   buffering. If another workstation
                                   requests access to the same file, the
                                   server lets the first workstation flush
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  server lets the first workstation flush
                                   data before granting access to the
                                   second.

                                   0 = Do not request "Oplock"
                                   1 = Request "Oplock"

                                   The default is 1.

 9                                 Use Open and Read.

                                   0 = No Open and Read
                                   1 = Open and Read on files with Read and
                                   Write access
                                   2 = Open and Read on files with Read,
                                   Write, and Execute access

                                   The default is 2.

 10                                Controls BufReset and SMBFlush behavior
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
10                                Controls BufReset and SMBFlush behavior
                                   as follows:

                                   0 = Flush dirty buffers to server, and
                                   wait for server to flush buffers to
                                     hard disk
                                   1 = Flush dirty buffers to server, but
                                   do not wait
                                   2 = Ignore BufReset

                                   The default is 2.

 11                                Controls beeping while the workstation
                                   waits for a network request to be
                                   processed. The value is the number of
                                   four-second intervals that
                                   the workstation waits before beeping. If
                                   the value is 0, beeping is off. The
                                   range is 0 through 9.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

                                   The default is 1 (one beep every four
                                   seconds).

 12                                Perform asynchronous read-ahead as
                                   follows:

                                   0 = Never perform asynchronous
                                   read-ahead
                                   1 = Perform asynchronous read-ahead at
                                   buffer end
                                   2 = Perform asynchronous read-ahead for
                                   second pass on a buffer

                                   The default is 2.

 13                                Controls three-way write, unlock, lock,
                                   and read SMB as follows:

                                   0 = Don't issue
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  0 = Don't issue
                                   1 = Issue

                                   The default is 0.

 14-32                             Reserved.




 Server Heuristics

 svX_srvheuristics
   Points to an ASCIIZ string of flags used to control a server's operations.
   The server heuristics are 20 digits that configure how a server processes
   network requests. Digits read from left (0) to right (19). A value of 0
   means "off" or "inactive"; 1 means "on" or "active." Other values are
   explained in the following descriptions of each digit:

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                                 Request opportunistic locking when
                                   opening files to make the Server service
                                   seem like the only application running
                                   on the server, then the service can
                                   safely buffer a file with "deny none"
                                   rights.

                                   The default is 1.

 1                                 Use read-ahead when the client performs
                                   sequential access as follows:

                                   0 = Do not use read-ahead
                                   1 = Use single-thread read-ahead
                                   2 = Use asynchronous read-ahead thread

                                   The default is 1.

 2                                 Use write-behind (tell the client that a
                                   write is completed before actually
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  write is completed before actually
                                   performing the write). If the write
                                   generates an error, the error appears on
                                   a subsequent write. Files opened for
                                   write-through cannot use write-behind.

                                   The default is 1.

 3                                 Use chain sends.

                                   The default is 1.

 4                                 Check all incoming server message blocks
                                   (SMBs) for correct format. This is
                                   useful with mixed versions and brands of
                                   network software on the network.

                                   The default is 1.

 5                                 Support file control block (FCB) opens
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
5                                 Support file control block (FCB) opens
                                   (collapse all FCB opens for a file to a
                                   single open). This is only useful with
                                   MS-DOS workstations on the network.

                                   The default is 1.


 6                                 Set the priority for the server. For a
                                   definition of "class" and "delta," see
                                   your MS OS/2 programming manual(s) for
                                   the MS OS/2 function DosSetPriority.
                                   Otherwise, if you set the priority to 5
                                   rather than 4, the server responds more
                                   quickly to commands typed at the
                                   keyboard, but this lowers network
                                   response performance. The possible
                                   values are shown in the following table:


 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Server Priority
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Setting          Class  Delta
 0                3      31
 1                3      23
 2                3      15
 3                3      7
 4                3      0
 5                2      31
 6                2      23
 7                2      15
 8                2      7
 9                2      0 ,
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                   The default is 5.

 7                                 Allocate additional memory for searches,
                                   with a maximum of 1927 searches. This
                                   should be set to 1 if MS-DOS
                                   workstations are on the network. For
                                   more information about searches, see the
                                   maxsearches entry.

                                   The default is 1.

 8                                 Write records to the audit log only when
                                   the scavenger wakes up. The scavenger is
                                   a thread of the server process that
                                   performs the following tasks:

                                   Disconnects sessions automatically
                                   Sends administrative alerts
                                   Writes to the audit log
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  Writes to the audit log

                                   When this value is 0, any write to the
                                   audit log wakes up the scavenger.
                                   (Heuristic 10 controls the wake-up
                                   interval of
                                   the scavenger.)

                                   The default is 1.

 9                                 Perform full buffering (as controlled by
                                   heuristics 1 and 2) when a file is
                                   opened with "deny write." When this
                                   value is 0, deny write access has no
                                   buffering.

                                   The default is 1.

 10                                Set the interval for the scavenger to
                                   wake up as follows:
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  wake up as follows:

                                   0 = 5 seconds
                                   1 = 10 seconds
                                   2 = 15 seconds
                                   3 = 20 seconds
                                   4 = 25 seconds
                                   5 = 30 seconds
                                   6 = 35 seconds
                                   7 = 40 seconds
                                   8 = 45 seconds
                                   9 = 50 seconds

                                   The default is 1.

                                   Heuristic 8 can cause the scavenger to
                                   wake up at other times.



ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 11                                Control how the server regulates access
                                   to .EXE, .COM, and .BAT files when more
                                   than one workstation requests access.
                                   Access is regulated by the following
                                   modes: "compatibility mode" allows
                                   exclusive access to the file by one
                                   workstation, "Deny Write sharing mode"
                                   allows the file to be read from but not
                                   written to by other workstations while
                                   open, and "Deny None sharing mode"
                                   allows the file to be read from and
                                   written to by other workstations while
                                   open. Values are as follows:

                                   0 = Always use compatibility mode.
                                   1 = Use Deny None sharing mode if the
                                   workstation requests
                                     read-only access to a .EXE or .COM
                                   file. Use compatibility mode
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  file. Use compatibility mode
                                     for a .BAT file or if the workstation
                                   requests write access to a
                                     .EXE or .COM file.
                                   2 = Use Deny None sharing mode if the
                                   workstation requests
                                     read-only access to a .EXE or .COM
                                   file. Use Deny Write sharing
                                     mode if the workstation requests
                                   read-only access to a .BAT file.
                                     Use compatibility mode if the
                                   workstation requests write access to
                                     a .EXE, .COM, or .BAT file.
                                   3 = Translate all compatibility mode
                                   opens to Deny None sharing
                                     mode opens.

                                   The default is 2.

                                   NOTE For servers with the
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  NOTE For servers with the
                                   high-performance file system 386
                                   (HPFS386), values are: 0 = Always use
                                   compatibility mode; 1, 2, or 3 =
                                   Translate read-only requests to Deny
                                   Write sharing mode for all files.

 12                                Enable MS-DOS workstations to use a
                                   second virtual circuit (VC) when sending
                                   print jobs. If this is not set, a second
                                   VC terminates any previous sessions set
                                   up for that MS-DOS workstation.

                                   The default is 1.

 13                                Set the number of big buffers used for
                                   read-ahead. Possible values are 0
                                   through 9, where 0 means that read-ahead
                                   is disabled. If this is set to a value
                                   larger than numbigbuf, it is reset to
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  larger than numbigbuf, it is reset to
                                   the value of (numbigbuf -1). Each big
                                   buffer is divided into sixteen 4K
                                   read-ahead buffers. Allocate more than
                                   one big buffer if you process many files
                                   with small reads simultaneously.

                                   The default is 1.

 14                                "Canonicalize" all incoming path
                                   specifications, converting characters to
                                   uppercase and slashes (/) to backslashes
                                   (\). This is useful when there are XENIX
                                   computers on the network.

                                   The default is 0.

 15                                Set the time that the server waits after
                                   breaking an opportunistic lock (see
                                   heuristic 0). You might want to set a
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  heuristic 0). You might want to set a
                                   longer time if the network is subject to
                                   long delays. The possible values are
                                   shown in the following table:



ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Opportunistic Lock Time-out
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Value                                 Time (seconds)
 0                                     35
 1                                     70
 2                                     140
 3                                     210
 4                                     280
 5                                     350
 6                                     420
 7                                     490
 8                                     560
 Opportunistic Lock Time-out
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
8                                     560
 9                                     640
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                   If a second client attempts to open a
                                   locked file, the server notifies the
                                   first client to flush buffers and
                                   prepare to unlock. If the first client
                                   does not respond within the specified
                                   time, the server closes the first
                                   client's open of the file.

                                   The default is 0.

 16                                Validate Input/Output controls (IOCtl)
                                   over the network. When this value is 1,
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  over the network. When this value is 1,
                                   the server accepts only generic device
                                   IOCtls (categories 01H, 05H, and 0BH),
                                   as defined in the device driver manual
                                   for MS OS/2.

                                   With this value set to 0, the server
                                   could receive invalid IOCtl pointers due
                                   to differences in device drivers between
                                   vendors. This can crash the server. You
                                   may need to set this digit to 0 in order
                                   to use certain device drivers, such as
                                   custom-built drivers.

                                   The default is 1.

 17                                Set the time the server maintains unused
                                   dynamic big buffers before freeing the
                                   memory. This digit can be from 0 through
                                   9, with the following meanings:
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  9, with the following meanings:



 Digit          Time-out
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0              0 seconds (timeout immediately after use)
 1              1 second
 2              10 seconds
 3              1 minute
 4              5 minutes
 5              10 minutes
 6              20 minutes
 7              40 minutes
 8              1 hour
 9              Maintain big buffers indefinitely

                                   The default is 3.

 18                                Set the time the server waits after
                                   failing to allocate a big buffer before
                                   trying again. This value can be from 0
                                   through 5,, with the following meanings:

 Digit                    Time-out
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 0                        0 seconds
 1                        1 second
 2                        10 seconds
 3                        1 minute
 4                        5 minutes
 5                        10 minutes
 6-9                      Illegal
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                   The default is 3.

 19                                Controls server's response to announce
                                   stimulus from workstations with
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  stimulus from workstations with
                                   incomplete server tables. Server
                                   responds to such requests only if this
                                   value is 1.

                                   Note that this does not control the
                                   normal periodic announcement of servers;
                                   it controls only the announcement in
                                   response to a workstation's reqannc
                                   packet.
                                   0 = No response to requests
                                   1 = Always respond to requests

                                   The default is 1.

                                   Set this to 0 to reduce datagram traffic
                                   on the network.

                                   Set this to 1 to increase the chance
                                   that a workstation will get a complete
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
                                  that a workstation will get a complete
                                   server list for the very first call to
                                   NetServerEnum2,
                                   net view, and so on.








 Appendix H  Defined Constants
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 This appendix lists constants that are defined in the LAN Manager header
 files. These constants are used to specify the maximum values for such
 things as lengths of variable names or sizes of buffers. Some values are
 specified in terms of other constants because this is how they are defined
 in the header file.

 The following table lists the constant, gives its value, describes what the
 constant is used for, and lists the header file in which it is defined. In
 all cases, the constant represents the maximum length for the data element
 listed.

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Constant              Value             Comment/Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 AFLEN                 64                Alert names element; NETCONS.H

 ALERTSZ               128               Alert string; NETCONS.H

 CCHMAXPATHCOMP        256               Queuename; BSEDOS.H

 CLTYPE_LEN            12                Client type string; NETCONS.H

 CNLEN                 15                Computername; NETCONS.H

 CRYPT_KEY_LEN         7                 Encryption key; NETCONS.H

 Constant              Value             Comment/Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 CRYPT_TXT_LEN         8                 Encryption text; NETCONS.H

 DEVLEN                8                 Devicename; NETCONS.H

 DNLEN                 CNLEN             Domain name; NETCONS.H

 DRIV_DEVICENAME_SIZE  31                Device driver data string; PMSPL.H

 DRIV_NAME_SIZE        8                 Device driver name; PMSPL.H

 DTLEN                 9                 Spool file datatype; NETCONS.H

 ENCRYPTED_PWLEN       16                Encrypted password; NETCONS.H

 EVLEN                 16                Event name; NETCONS.H

 FORMNAME_SIZE         31                Form name; PMSPL.H

 Constant              Value             Comment/Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 GNLEN                 UNLEN             Maximum group name; NETCONS.H

 JOBSTLEN              80                Print job status; NETCONS.H

 MAX_DG_SIZE           512               Datagram; NCB.H

 MAXCOMMENTSZ          48                Comment for queue, server, shared
                                         resource, and user; NETCONS.H

 NNLEN                 12                "8.3" network name; NETCONS.H

 NCBNAMSZ              NETBIOS_NAME_LEN  Network name; NCB.H

 NETBIOS_NAME_LEN      16                NetBIOS name; NETCONS.H

 PATHLEN               260               Path; NETCONS.H

 PDLEN                 8                 Print destination; NETCONS.H
 Constant              Value             Comment/Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
PDLEN                 8                 Print destination; NETCONS.H

 PRINTERNAME_SIZE      32                Printer name; PMSPL.H

 PWLEN                 14                Password; NETCONS.H

 QNLEN                 12                Queuename; NETCONS.H

 QP_DATATYPE_SIZE      15                Spooler queue data string; PMSPL.H

 RMLEN                 (UNCLEN+1+NNLEN)  Remote name; NETCONS.H

 SESSION_PWLEN         24                Encrypted session password;
                                         NETCONS.H

 SESSION_CRYPT_KLEN    21                Encrypted session key; NETCONS.H

 SHPWLEN               8                 Share password; NETCONS.H

 Constant              Value             Comment/Header File
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 SNLEN                 15                Service name; NETCONS.H

 STXTLEN               63                Service text; NETCONS.H

 SV_MAX_CMD_LEN        PATHLEN           Command string; SERVER.H

 UNCLEN                (CNLEN+2)         UNC computername; NETCONS.H

 UNLEN                 20                Username; NETCONS.H

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ









 Glossary
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Absolute path
 A pathname whose reference to a file or directory does not depend on the
 current drive or directory. An absolute path must start with a drive letter,
 a colon (:), and a backslash (\), in the format
 n:\directory[[\subdirectory][\filename] . . .]. See also Network path,
 Path, Pathname, and Relative path.

 Access control entry (ACE)
 A username or groupname and its corresponding access permissions (given as a
 name/permission pair). There can be up to 64 access control entries (ACEs)
 in an access control list (ACL). See also Access control list (ACL).

 Access control list (ACL)
 A list of access control entries (ACEs) for a specified resource. The access
 control list (ACL) also includes the name of the resource and an audit
 attribute flag that defines what type of events are audited for that
 resource. See also Access control entry (ACE).

 Account
 The record of a user on a server. To use any of the server's shared
 resources, a user must first have an account on a server that has user-level
 security.

 Accounts database
 See User accounts subsystem (UAS) database.

 Accounts operator
 An operator privilege that allows a user with user privilege to create,
 remove, and modify user accounts (except those that have admin privilege)
 and groups. See also Admin privilege, Comm operator, Operator privilege,
 Print operator, Server operator, and User privilege.

 ACE
 See Access control entry (ACE).

 ACL
 See Access control list (ACL).

 Admin
 A function requirement that specifies that the calling process must have
 administrative privileges to execute the function.

 Admin alert
 A message from LAN Manager about server and resource use. See also Alert.

 Admin privilege
 A privilege level that allows a user at a server to issue all types of
 administrative commands and use all the resources shared by that server,
 regardless of the user's access permissions. User accounts that have admin
 privilege are part of the special group admins. See also Privilege level.

 ADMIN$
 An administrative resource that enables remote administration of servers.
 For a server to be administered remotely, its ADMIN$ must be shared. See
 also IPC$.

 admins group
 A special group made up of users who have admin privilege. See also Admin
 privilege and Privilege level.

 Administrator
 An individual responsible for managing the local-area network. This person
 typically configures the network, maintains the network's shared resources
 and security, assigns passwords and privileges, and helps users. See also
 Operator privilege.

 Alert
 Notification to registered clients that a LAN Manager or application event
 occurred. LAN Manager provides a basic set of alerts that can be added to by
 the Alert functions. See also Admin alert, Error alert, Messenger service,
 and Printer alert.

 Alerter service
 A LAN Manager service that monitors LAN Manager alerts. See also Services.

 Anonymous pipe
 A one-way data storage buffer maintained in RAM and used for interprocess
 communication (IPC). See also Interprocess communication (IPC) and Named
 pipe.

 API
 See Application programming interface (API).

 API_FUNCTION
 A C-language type definition used for all LAN Manager API functions. It is
 defined as "unsigned far pascal" and indicates that the API function returns
 an unsigned value.

 Application programming interface (API)
 The set of functions, structures, datatypes, and constants that enable a
 program to perform a particular action on the network.

 ASCIIZ string
 A sequence of ASCII characters terminated by the ASCII character NUL ('\0').

 Audit
 The process in which LAN Manager writes an entry to the audit log when a
 user accesses a resource in a certain way or logs on to the network. See
 also Audit entry and Audit log.

 Audit entry
 Data (in binary format) that results from a monitored operation. An audit
 entry includes the username, resource type, and date and time the operation
 occurred. See also Audit and Audit log.

 Audit log
 A file that contains audit entries. See also Audit, Audit entry, and Log.

 Backup domain controller
 A server in a domain that shares and uses a copy of the domain's user
 accounts database to validate logon requests. See also Member server,
 Netlogon service, and Primary domain controller.

 Broadcast message
 A message sent to all users on the local-area network or to all users in a
 specified domain.

 Centralized logon security
 A security system in which a central server verifies the user's logon
 password. See also Distributed logon security.

 Character device
 A hardware device that processes ASCII characters (for example, a printer,
 modem, or FAX machine).

 Character-device queue
 An ordered list of requests for character devices. A character-device queue
 is created when a character device, such as a modem, is shared as a network
 resource. Several character-device queues can access the same device.
 Exclusive access to each device is given according to the priority of the
 queue. See also Pool, Queue, and Unspooled.

 Client process
 A process that communicates with a server process by using LAN Manager
 interprocess communication (IPC) features. Distributing computing tasks to
 client and server processes allows better performance and stronger network
 administrative capabilities, such as improved security. The client process
 usually  acts as a "front-end," accepting and displaying information. The
 server process is usually a "back-end," responsible for data storage,
 security, and integrity. The two processes communicate using named pipes.
 See also Interprocess communication (IPC), IPC$, Named pipe, and Server
 process.

 Command
 A word or phrase the user types at the MS OS/2 or MS-DOS prompt to instruct
 the computer to carry out an action.

 Comm device
 See Communication device.

 Comm operator
 An operator privilege that allows a user with user privilege to create,
 share, and modify communication-device queues and requests. See also
 Accounts operator, Operator privilege, Print operator, Server operator, and
 User privilege.

 Comm queue
 See Communication-device queue.

 Comm-device queue
 See Communication-device queue.

 Communication device
 A COMM or LPT connection on a local computer (for example, modems, image
 scanners, and serial ports).

 Communication-device queue
 An ordered list of communication-device requests. The queue stores the
 requests and then sends the requests, one by one, to one or more
 communication devices or to a pool. See also Pool, Queue, and Unspooled.

 Computer
 In a local-area network, a workstation or a server. A computer can have only
 one computername by which it is known to LAN Manager. See also Computername.

 Computername
 A name given to a workstation or server and used by LAN Manager to identify
 that server or workstation. Each computername must be unique on the network.
 A computername can have as many as CNLEN bytes (as defined in the NETCONS.H
 header file).

 Configuration
 How a workstation, server, or local-area network (including both hardware
 and software) is set up. See also LANMAN.INI.

 Connect
 To redirect a local devicename to a shared resource on a server. See also
 Devicename.

 Connection
 A communication link from a local device to a shared resource on a server. A
 connection can be made by assigning a local devicename on the workstation to
 a resource shared on a server. A connection can also be made when the
 resource is accessed by using a command-line command with a network pathname
 or from an application. See also Devicename and Network path.

 Continue
 To restart a LAN Manager service or resource that has been paused. See also
 Pause.

 Default
 A value coded into the LAN Manager software. For LANMAN.INI entries, the
 default value of an entry is assumed when the entry is missing from the
 LANMAN.INI file. See also LANMAN.INI.

 Device
 A peripheral hardware component that is connected to a computer and that
 performs a specific type of task. There are three types of devices: disk,
 print, and communication. See also Communication device, Device driver, Disk
 device, and Print device.

 Device driver
 A program that transforms standard, device-independent input/output (I/O)
 requests into the operations necessary to activate a specific device,
 enabling a workstation to recognize and use a particular piece of hardware.

 Devicename
 A name that identifies a specific printer, disk drive, or other peripheral
 device. A devicename can have as many as DEVLEN bytes (as defined in the
 NETCONS.H header file).

 Directory
 A structure for organizing files into groups. A directory can contain files
 and subdirectories of files in the following format: \dir\...\filename.ext

 Directory name
 A name that identifies a specific directory.

 Disk device
 A device assigned a devicename and that stores information in the form of
 files.

 Distributed logon security
 A security system in which each server verifies user permissions. See also
 Centralized logon security.

 Domain
 Servers and workstations grouped into an administrative unit.

 Error alert
 A message from LAN Manager about a local-area network or system error. These
 messages are stored in the error log. See also Alert, Error log, and Log.

 Error log
 A file that stores error messages (in binary format). See also Error alert
 and Log.

 Event
 An occurrence for which an alert is raised. LAN Manager defines certain
 events for which alerts will be raised and then received by the Alerter
 service. Users can define other events for which alerts will be raised. See
 also Alert and Audit log.

 Eventname
 A name of a particular type of system event. An eventname can have as many
 as EVLEN bytes (as defined in the NETCONS.H header file).

 Explicit connection
 A connection established by using the NetUseAdd function, where a local
 devicename is redirected to a server's shared resource.

 FAT
 See File allocation table (FAT) file system.

 File allocation table (FAT) file system
 An MS OS/2 and MS-DOS file system that tracks the location of files in
 directories. The file allocation table (FAT) file system allocates free
 space on disks to ensure space is available for new files. MS OS/2 1.2 can
 replace the FAT file system with an installable file system (IFS), such as
 the high-performance file system (HPFS). See also High-performance file
 system (HPFS) and Installable file system (IFS).

 Filename
 A unique name that identifies a file. With the file allocation table (FAT)
 file system, the filename has the "8.3" format; it can contain as many as
 eight characters followed by an optional filename extension that consists of
 a period (.) and as many as three characters (for example, filename.ext).
 With the high-performance file system (HPFS), a filename can have as many as
 255 characters.

 File handle
 A value that represents an open file; used in all input/output (I/O)
 operations.

 Group
 A set of users, identified by a common name (the groupname) and treated as a
 single entity, who can share common permissions for one or more resources.
 Individually assigned user permissions take precedence over those assigned
 through groups.

 Groupname
 A name assigned to a particular set of users. A groupname can have as many
 as GNLEN bytes (as defined in the NETCONS.H header file).

 guests group
 A special group made up of users who have guest privilege. See also Guest
 privilege and Privilege level.

 Guest privilege
 The lowest level of privilege given to a user account. Accounts with guest
 privilege can view and use network resources and send messages. See also
 Permissions and Privilege level.

 Handle
 An arbitrary numeric value that MS OS/2 returns to a program to represent a
 system resource. To use the resource, the program can then return that value
 to MS OS/2 in subsequent calls.

 Heuristics
 Flags or settings used to configure workstation and server performance.

 High-performance file system (HPFS)
 An MS OS/2 1.2 installable file system (IFS) that has faster input/output
 (I/O) than the file allocation table (FAT) file system. HPFS is compatible
 with the FAT system, but it does not restrict file naming to the FAT system
 "8.3" format. HPFS allows as many as 255 characters in filenames. When LAN
 Manager server software is installed on an HPFS partition, it becomes an
 HPFS386 partition. See also File allocation table (FAT) file system and
 High-performance file system 386 (HPFS386).

 High-performance file system 386 (HPFS386)
  An enhanced version of the high-performance file system (HPFS), designed to
 work with a 386 computer. HPFS386 includes an enhanced disk cache for
 servers and implements local security. See also High-performance file system
 (HPFS).

 HPFS
 See High-performance file system (HPFS).

 HPFS386
 See High-performance file system 386 (HPFS386).

 IFS
 See Installable file system (IFS).

 Implicit connection
 A link to a server's shared resource that is established without attaching
 it to a local device. For example, an implicit connection is established
 using the following format: \\server\sharename\file.txt

 Installable file system (IFS)
 File-system code that allows software to manage the file system, including
 creating and maintaining directories, and allocating disk space. In addition
 to the existing file allocation table (FAT) file system, MS OS/2 1.2 allows
 installable file systems (IFS) to be installed. For example, the
 high-performance file system (HPFS) and LAN Manager redirector software are
 installable file systems for MS OS/2 1.2. See also File allocation table
 (FAT) file system and High-performance file system (HPFS).

 Interprocess communication (IPC)
 The ability of local and remote processes to transfer data and messages
 among themselves, and to offer services to and receive services from other
 programs on the network. This communication can be between different
 processes of a program, between different computers running parts of a
 single program, or between two programs working together.

 IPC$
 An administrative resource that controls how interprocess communication
 (IPC) works on servers. A server's IPC$ must be shared before the resources
 shared by the server can be viewed on the network, before the server can be
 administered remotely, and before users can use the Netrun service or
 distributed applications on the server. See also ADMIN$ and Named pipe.

 LAN
 See Local-area network (LAN).

 LAN pathname
 A computername followed by a sharename and one or more directory names,
 followed by a filename (in the format \\server\sharename\file.ext). See also
 Computername, Directory name, Filename, and Sharename.

 LANMAN.INI
 The LAN Manager initialization file. The values in this file determine the
 option settings for computers on the local-area network, although the net
 start and net config command options can temporarily override LANMAN.INI
 values. These values can be modified to suit the network requirements. See
 also Default.

 Local
 A workstation or server at which the user or administrator is currently
 working, or a device or resource located at that workstation or server. See
 also Remote.

 Local-area network (LAN)
 A group of computers, connected by cable or other physical means, that
 enables users to share information and equipment.

 Local computer
 The computer at which a user is working. See also Remote computer.

 Local device
 A device physically attached to the local workstation (for example, the disk
 drives in the computer).

 Local devicename
 The name by which a device is known (for example, C: or LPT1).

 Local security
 A security method available for 386 servers with the high-performance file
 system (HPFS386). This method extends LAN Manager security measures to
 protect files on a server by restricting access for the users working at the
 server. With local security, a user must be assigned permissions to access
 any file or directory in an HPFS386 volume, whether or not the resource is
 shared as part of a LAN Manager resource.

 Log
 A file that contains a list of information. LAN Manager uses error logs,
 message logs, and audit logs.

 Log off
 To cancel connections to local-area network resources but not stop LAN
 Manager services.

 Log on
 To access the local-area network by entering a username and password at a
 workstation. When connecting to resources, LAN Manager validates the
 username and password before granting access. See also Log off.

 Logon domain
 The domain specified when logging on to the local-area network.

 Logon hours
 The days and times during which a user can access and use a server's
 resources. See also Logon restrictions.

 Logon restrictions
 The logon hours during which a user can access a server's resources, and the
 workstations from which the user can access a server's resources. See also
 Logon hours.

 Logon script
 A batch program, written for one or more users, that contains LAN Manager
 and operating system commands used to configure the workstation. When the
 user logs on, the logon script runs at the user's workstation.

 Logon security
 A security and permissions system that restricts access to the local-area
 network's information, settings, and resources, and that verifies the
 identities of users when they log on to the local-area network and unifies
 the user accounts database for a domain into one user accounts database,
 copies of which are kept on servers throughout the domain. See also Netlogon
 service, Single system image (SSI), and User accounts subsystem (UAS)
 database.

 Logon server
 For a domain, the primary domain controller and the backup domain
 controllers. For a user, the server that processes the user's logon request.
 See also Netlogon service and Primary domain controller.

 Mailslot
 An object that can store or forward data to users or applications.

 Mailslot name
 A name of an object that can receive data. Mailslot names must be preceded
 by \mailslot\, in the format \mailslot\mailslotname.

 Member server
 A server in a domain that keeps and uses a copy of the domain's user
 accounts database but does not validate logon requests. See also Backup
 domain controller, Netlogon service, and Primary domain controller.

 Message
 A buffer or file of data sent to a message alias. See also Message alias.

 Message alias
 A registered name used for receiving messages.

 Message forwarding
 The ability to reroute messages intended for a user or application  on one
 computer to a user or application on another computer.

 Message log
 A file that contains all messages received by the computer. The default file
 is MESSAGES.LOG in the LOGS directory.

 Message logging
 The process of saving all incoming messages to a file.

 Messenger service
 A LAN Manager service that enables a message alias to receive messages from
 local-area network users. This service can also store messages in a file.
 See also Message alias and Services.

 Named pipe
 An interprocess communication (IPC) method used to transfer data between
 separate processes, usually on separate computers. An administrator can set
 permissions on named pipes. See also Interprocess communication (IPC) and
 IPC$.

 NCB (Network control block)
 See Network control block (NCB).

 Netlogon service
 A LAN Manager service that implements logon security. When a server in a
 domain runs the Netlogon service, LAN Manager checks the username and
 password supplied by each user who attempts to log on in the domain. All
 servers that have logon security run the Netlogon service; the Netlogon
 service replicates the user accounts database to these servers.  See also
 Logon security, Services, Standalone server, and User accounts subsystem
 (UAS) database.

 Netpopup service
 A LAN Manager service that displays messages on the screen when they arrive
 from other local-area network users or from LAN Manager. See also Popup and
 Services.

 Netrun service
 A LAN Manager service that lets users, from their own workstations, run
 applications on a server. See also Services.

 Network control block (NCB)
 A block of sequential data of fixed length. This data includes an opcode
 that indicates the operation to be performed and elements that indicate the
 status of the operation. See also Opcode.

 Network path
 The computername of a server followed by the sharename of a shared resource.
 A server's computername is preceded by two backslashes (\\); a sharename is
 preceded by one backslash (\). For example, \\SALES\REPORT is a network path
 for the shared resource REPORT on the computer named SALES. See also
 Computername, Resource, and Sharename.

 NUL
 The ASCII constant '\0'. Used as a character in a string.

 NULL
 The constant ((void *) 0), as defined in the C-language header file STDIO.H.
 Used as the value of a pointer.

 Null pointer
 A pointer that contains the value NULL. Note that a far pointer given the
 value NULL has the value 00:00. A near pointer given the value NULL has the
 value DS:00.

 Null string
 A string that has as its first character the ASCII character NUL. This is
 known as a zero-length or ASCIIZ string because no characters precede the
 NUL character that terminates the string. See also ASCIIZ string.

 Opcode
 Operation code; a code, usually a number, that specifies an operation to be
 performed. An opcode is often the first component in a contiguous block of
 data; it indicates how other data in the block should be interpreted. See
 also Network control block (NCB).

 Operator privilege
 Privilege granted to a user that allows the user to perform certain
 administrative tasks. See also Accounts operator, Admin privilege, Comm
 operator, Print operator, and Server operator.

 P permission
 A special permission level, given to a user on a resource-by-resource basis,
 that allows the user to change the access control list (ACL) for that
 particular resource. See also Access control list (ACL).

 Password
 An ASCIIZ string used to access the network. User passwords can have as many
 as PWLEN bytes; passwords for shared resources can have as many as SHPWLEN
 bytes (as defined in the NETCONS.H header file).

 Path
 A set of directory names that define a directory's location. A backslash (\)
 precedes each directory name except the top-level one (for example, the path
 REPORTS\ACCT\NORTH indicates that the NORTH directory is in the ACCT
 subdirectory of the REPORTS directory). An initial backslash indicates that
 the path begins at the drive's root directory. When the path begins with a
 drive letter, it is an absolute path. See also Absolute path, Network path,
 Pathname, and Relative path.

 Pathname
 A file specification that describes the location of the file, in the
 following format: devicename:\directory\subdirectory\...\filename.  A
 pathname can have as many as PATHLEN bytes (as defined in the NETCONS.H
 header file). A backslash (\) precedes each directory name and filename (for
 example, E:\BIN\USR\NETCONS.H is the pathname to the NETCONS.H header file
 in the USR subdirectory of the BIN directory on the E drive). To specify a
 pathname on the local drive, omit the drivename and begin the path with
 \directory. See also Path.

 Pause
 To suspend a LAN Manager service or function. When a service is paused,
 current requests continue but new requests are not allowed. See also
 Continue.

 Peer service
 A LAN Manager service that enables an MS OS/2 workstation to share
 directories, one printer queue, and one communication-device queue with one
 other user at a time. The Peer service performs most of the same services as
 the Server service, but on a smaller scale. See also Server service and
 Services.

 Permissions
 Settings for a shared resource that determine which users can access the
 resource. Permissions can also refer to a user's privileges. On the
 local-area network, certain levels of permission can be set, giving the user
 various degrees of freedom in accessing resources and in reading or changing
 information. With user-level security, each user can be assigned permissions
 for each resource. With share-level security, each resource is assigned
 permissions, and all users who access the resource must have these
 permissions. See also Permission levels, Privilege level, Share-level
 security, and User-level security.

 Permission levels
 The degree to which a user can use a shared resource. LAN Manager provides
 three general permission levels (admin, guest, and user). It is also
 possible to set access permissions on a resource-by-resource basis.

 Pipe
 See Anonymous pipe and Named pipe.

 Pipename
 The name given to an object that allows two processes to communicate with
 each other. A pipename must be preceded by \pipe\, in the format
 \\servername\pipe\pipename.

 Pool
 A group of printers or communication devices that receive requests from the
 same queue. See also Printer queue, Queue, and Spooled.

 Popup
 A temporary text window, usually containing a message received over the
 network. The popup is superimposed on the current screen without altering
 the contents of the current screen. Popups allow users to receive messages
 even while they are working in other screen groups with other applications.

 Primary domain controller
 The server at which the master copy of a domain's user accounts database is
 maintained. The primary domain controller also validates logon requests. See
 also Backup domain controller, Member server, and Netlogon service.

 Print destination
 A hardware component that prints print jobs. A print destination name can
 have as many as PDLEN bytes (as defined in the NETCONS.H header file).

 Print device
 A device that copies data from a computer onto paper. A print device is
 known to LAN Manager by the name of the port to which it is connected. See
 also Devicename.

 Print operator
 An operator privilege that allows a user to create, share, and modify
 printer queues and control print jobs. See also Accounts operator, Comm
 operator, Operator privilege, Server operator, and User privilege.

 Printer alert
 A message from LAN Manager that specifies a print job is complete or that a
 print error has occurred. See also Alert.

 Printer queue
 An ordered list of print requests. A printer queue stores print jobs and
 then sends them, one by one, to a printer or pool. See also Pool and
 Spooled.

 Privilege
 See Privilege level.

 Privilege level
 With user-level security, one of three settings (admin, guest, and user)
 assigned for each user account. The privilege level defines the range of
 actions a user can perform on the network. See also Admin privilege, Guest
 privilege, Operator privilege, Permissions, and User privilege.

 Profile file
 A set of commands that can be executed to restore all shared resources and
 uses of shared resources.

 Queue
 An ordered list of elements waiting to be processed. LAN Manager supports
 character-device queues and printer queues. The queuename  can have as many
 as QLEN bytes (as defined in the NETCONS.H header file). See also
 Communication-device queue, Pool, Printer queue, and Spooled.

 Raise alert
 To notify a user or application of a particular event. See also Alert.

 Relative path
 A path relative to the current drive and directory (for example, from the
 C:\LANMAN directory, a relative path to the directory C:\LANMAN\ACCOUNTS is
 simply ACCOUNTS). See also Absolute path, Network path, Path, and Pathname.

 Remote
 Any server, workstation, or resource that is not located on the local
 computer where a process is executing.

 Remote administration
 Conducting administrative tasks from a remote computer.

 Remote computer
 A server or workstation not located where the user or administrator is
 currently working. See also Local computer.

 Remote device
 A device, accessed by LAN Manager, not located where the user or
 administrator is currently working. See also Local device.

 Remoteboot service
 A LAN Manager service that provides software support for starting MS OS/2
 and MS-DOS workstations over the local-area network.

 Replicator service
 A LAN Manager service that maintains identical sets of files and directories
 on different servers and MS OS/2 workstations.

 Resource
 Any disk drive, directory, printer, modem, image scanner, or equipment a
 server can share over a local-area network. LAN Manager also has
 administrative resources that govern how certain processes work on each
 server. See also Communication-device queue, Disk device, Printer queue, and
 Shared resource.

 Security
 A variety of methods that enable an administrator to control access to
 network resources. See also Local security, Logon security, Share-level
 security, and User-level security.

 Server
 A computer on a local-area network that controls access to shared resources
 such as files, printers, and modems.

 Server message block (SMB)
 A block of data that contains a work request from a workstation to a server,
 or that contains the response from the server to the workstation. Server
 message blocks (SMBs) correspond to network file activity, such as opening a
 file, reading, searching, or setting attributes.

 Servername
 The name of a particular network server. A servername can have as many as
 CNLEN bytes (as defined in the NETCONS.H header file).

 Server operator
 An operator privilege that allows a user with user privilege to start and
 stop services, share resources, use the server's error log, and close users'
 sessions. See also Accounts operator, Comm operator, Operator privilege,
 Print operator, and User privilege.

 Server process
 A process that communicates with a client process using LAN Manager
 interprocess communication (IPC) features. Distributing computing tasks to
 client and server processes allows better performance and stronger network
 administrative capabilities, such as improved security. The server process
 acts as a "back-end," responsible for data storage, security, and integrity.
 The client process usually acts as a "front-end," accepting and displaying
 information. The two processes communicate using named pipes. See also
 Client process, Interprocess communication (IPC), IPC$, and Named pipe.

 Server service
 A LAN Manager service that enables a computer to share resources over the
 network and that provides administrators with tools for controlling and
 monitoring resource use. See also Peer service and Services.

 Services
 The main components of the LAN Manager software. The basic service is the
 Workstation service, which lets a computer use local-area network resources.
 The Workstation service must be running for any other service to run. The
 Server service enables a computer to share resources over the network. Other
 services include the Alerter, Messenger, Netlogon, Netpopup, Netrun, Peer,
 Remoteboot, Replicator, Timesource, and UPS services.

 Servicename
 A name of a network service. A servicename can have as many as SNLEN bytes
 (as defined in the NETCONS.H header file).

 Session
 A link between a workstation and a server. A session is established the
 first time a workstation requests to use a server's resource.

 Share
 To make a local resource available to remote users or other processes. Only
 local resources can be shared.

 Share-level security
 A type of security that limits access to each shared resource by requiring a
 password. Permissions are assigned to the resource (rather than to the
 user). All users who know the password can use the resource within the
 bounds of the permissions assigned for that resource. See also Password,
 Persmissions, and User-level security.

 Shared resource
 A resource on a server that has been made available to network users and
 that can be accessed by a workstation on the network. See also Resource.

 Sharename
 A name assigned to a shared resource. Remote users and processes use this
 name to access the shared resource. A sharename can have as many as NNLEN
 bytes (as defined in the NETCONS.H header file).

 Single system image (SSI)
 A domain that has the Logon service running and that propagates its UAS
 database throughout the domain. See also Logon security and User accounts
 subsystem (UAS) database.

 SMB
 See Server message block (SMB).

 Spool file datatype
 Defines the type of print jobs a printer queue can process. A spool file
 datatype name can have as many as DTLEN bytes (as defined in the NETCONS.H
 header file).

 Spooled
 The type of queue used with printers configured with a parallel interface.
 See also Devicename, Pool, and Printer queue.

 SSI
 See Single system image (SSI).

 Standalone logon
 A logon request that is not validated by a logon server. In domains without
 logon security, each logon request is granted standalone logon status. In
 domains with logon security, a logon request with a username not found in
 the domain's user accounts database is granted standalone logon status.

 Standalone server
 A server that has user-level security, has its own user accounts database,
 and does not participate in domain logon verification.

 Server message block (SMB)
 A file system protocol that sends messages and replies to system calls.

 Timesource service
 A LAN Manager service that provides the time of day for the specified
 domain. See also Services.

 Timestamp
 A record of the time a system event occurred. Timestamps are usually
 calculated as the number of seconds elapsed since 00:00:00, January 1, 1970.
 Timestamps are used for statistics.

 UAS
 See User accounts subsystem (UAS) database.

 UNC
 See Universal naming convention (UNC).

 UNC name
 Using the universal naming convention (UNC), a name given to a device,
 computer, or resource to allow users and applications to establish an
 explicit connection and access the resources on the network (for example,
 \\servername\sharename\filename is a UNC name).

 Universal naming convention (UNC)
 Another term for network path. See also Network path and UNC name.

 Unspooled
 A queue used with communication devices and printers configured with a
 serial interface. See also Communication-device queue and Devicename.

 UPS service
 A LAN Manager service that enables a server to use an uninterruptible power
 supply (UPS). The UPS service protects the server from data loss during a
 power failure.

 Use
 To establish a connection from a local device to a shared resource.

 users group
 A special group made up of users who have user privilege. See also Privilege
 level.

 User accounts subsystem (UAS) database
  A subsystem of LAN Manager that includes user, group, and access
 information.

 User privilege
 A privilege that allows a person to use local-area network resources, view
 information about a server's shared resources and the status of printer and
 communication-device queues, and send and receive messages. See also
 Permissions and Privilege level.

 User-level security
 A type of security in which an account is established for each user.
 Permissions are granted to each user or group for specific resources,
 defining exactly what actions each user can take with each resource. See
 also Logon security, Password, and Share-level security.

 Username
 With user-level security, the name by which the local-area network
 identifies a user. The username is part of a user account; the user supplies
 a password for the user account. To access resources shared on a server, the
 user must supply both the username and password. With logon security, the
 user must supply a username and password to gain access to the network. A
 username can have as many as UNLEN bytes (as defined in the NETCONS.H header
 file).

 Virtual circuit
 A full-duplex transport-level connection that allows reliable exchange of
 data between two network names on the local-area network. A virtual circuit
 can be established between two different computers, between two different
 network names on the same computer, or from one name back to itself.

 Workstation
 The computer from which a user or application accesses server resources.

 Workstation domain
 The domain in which a workstation is a member, specified when the
 Workstation service is started. See also Logon domain and Workstation
 service.

 Workstation service
 A LAN Manager service that enables a computer to use local-area network
 resources and services. The Workstation service must be running for any
 other LAN Manager service to run.





 INDEX
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




     A
 Absolute path
 Access control entry (ACE)
 Access control list (ACL)
   restrictions
 Access permission
   checking
   defined
   deleting a user account
   rules for
 Access Permissions category
   data structures
     access_info_0
     access_info_1
     access_list
   example
   NetAccessAdd
   NetAccessCheck
   NetAccessDel
   NetAccessEnum
   NetAccessGetInfo
   NetAccessGetUserPerms
   NetAccessSetInfo
   overview
 ACCESS.H header file
   with Access Permissions functions
   with Domain functions
   with Group functions
   with User functions
 access_info_0
 access_info_1
 access_list
 Account
 Accounts database
 Accounts operator privilege
 Admin privilege
 ADMIN$
 Admin
 Administrator
 admins group
 admin_other_info
 ae_acclim
 ae_aclmod
 ae_closefile
 ae_connrej
 ae_connstart
 ae_connstop
 ae_netlogoff
 ae_netlogon
 ae_resaccess
 ae_resaccess2
 ae_resaccessrej
 ae_servicestat
 ae_sesslogoff
 ae_sesslogon
 ae_sesspwerr
 ae_srvstatus
 ae_uasmod
 Alert category
   data structures
     admin_other_info
     errlog_other_info
     print_other_info
     std_alert
     user_other_info
   example
   NetAlertRaise
   NetAlertStart
   NetAlertStop
   overview
 ALERT.H header file
 Alert
   class
     ALERT_ADMIN_EVENT
     ALERT_ERRORLOG_EVENT
     ALERT_MESSAGE_EVENT
     ALERT_PRINT_EVENT
     ALERT_USER_EVENT
   events
   macros
   types
 Alerter service
 Alerts
 ALERT_OTHER_INFO(ptr) macro
 ALERT_OTHER_INFO_F(ptr) macro
 ALERT_VAR_DATA(ptr) macro
 ALERT_VAR_DATA_F(ptr) macro
 Anonymous pipe
 API function categories
   Access Permissions
   Alert
   Auditing
   Character Device
   Configuration
   Connection
   Domain
   Error Logging
   File
   Group
   Handle
   Mailslot
   Message
   Named pipe
   NetBIOS
   Print Destination
   Print Job
   Printer Queue
   Remote Utility
   Server
   Service
   Session
   Share
   Statistics
   Use
   User
   Workstation
 API naming conventions
 API_FUNCTION
 Application Programming Interface (API)
 Application
   converting into a service
   run as a service
   written as a service
 Array sizes
 ASCIIZ string
 Audit entry data structures
   access control list change
   access denied
   access granted
   account limit exceeded
   connection rejected
   connection started
   connection stopped
   file closed
   logon denied
   logon
   password error
   server status changes
   service status code or text changed
   session begins
   session ends
   types of
   UAS change
 Audit entry
 Audit log
   audit entry types
   audit entry
   auditing APIs
   clearing
   default pathname
   reading
   setting maximum size
   writing an audit entry to
 Audit
 Auditing category
   data structures
     ae_aclmod
     ae_closefile
     ae_connrej
     ae_connstart
     ae_connstop
     ae_netlogoff
     ae_netlogon
     ae_resaccess
     ae_resaccess2
     ae_resaccessrej
     ae_servicestat
     ae_sesslogoff
     ae_sesslogon
     ae_sesspwerr
     ae_srvstatus
     ae_uasmod
     audit_entry
   example
   NetAuditClear API
   NetAuditRead API
   NetAuditWrite API
   overview
 Auditing network events
   server configuration
 audit_entry

     B
 Backup domain controller
 Binding
 Broadcast message
   defined
   maximum size
   sending a buffer
   sending a file
 BSEDOS.H header file
 Buffers
   input data
   return data
 Building sample programs

     C
 Centralized logon security
 Changes in functionality
 Character Device category
   data structures
     chardevQ_info_1
   example
   NetCharDevControl
   NetCharDevEnum
   NetCharDevGetInfo
   NetCharDevQEnum
   NetCharDevQGetInfo
   NetCharDevQPurge
   NetCharDevQPurgeSelf
   NetCharDevQSetInfo
   overview
 Character device
 Character-device queue
 CHARDEV.H header file
   with character device functions
   with Handle category
 chardevQ_info_0
 chardevQ_info_1
 chardev_info
 chardev_info_0
 chardev_info_1
 Client process
   defined
   waiting for named pipe
 Closing server resources
 Comm device
 Comm operator
 Comm queue
 Comm-device queue
 Command
 Communication device
   closing
   controlling information
   described
   forcing closed
   getting information about
   remote
 Communication-device queue
   checking routing list
   defined
   deleting all requests in
   deleting certain requests in
   explicit connection
   getting information about
   implicit connection to
   modifying status of
   using
 Communications parameters
   character-device handles
   named-pipe handles
 Compiling applications
 Computernames
 CONFIG.H header file
 Configuration category
   example
   NetConfigGet2
   NetConfigGetAll2
   overview
 Configuration
 Configuring
   server performance
   workstation performance
 Connection category
   data structures
     connection_info_0
     connection_info_1
   example
   NetConnectionEnum
   overview
 Connection
   compared to session
   controlling
   defined
   devicename
     implicit
   establishing
   getting information about
   listing to remote shared resources
   listing
   terminating
   Universal-naming convention
     explicit
     implicit
 Connections
   between workstations and servers
   controlling
   difference from sessions
   types
     devicename
     universal-naming (UNC)
 connection_info_0
 connection_info_1
 Constants
   defined
   header files
 Continue
 Control-completion-pending (CCP) code
 Converting existing applications
 copy_info

     D
 Data structure names
 Data structures
   access_info_0
   access_info_1
   access_list
   admin_other_info
   ae_acclim
   ae_aclmod
   ae_closefile
   ae_connrej
   ae_connstart
   ae_connstop
   ae_netlogoff
   ae_netlogon
   ae_resaccess
   ae_resaccess2
   ae_resaccessrej
   ae_servicestat
   ae_sesslogoff
   ae_sesslogon
   ae_sesspwerr
   ae_srvstatus
   ae_uasmod
   audit_entry
   chardevQ_info_0
   chardevQ_info_1
   chardev_info
   chardev_info_0
   chardev_info_1
   connection_info_0
   connection_info_1
   copy_info
   DEVOPENSTRUC
   DRIVDATA
   errlog_other_info
   error_log
   file_info_0
   file_info_1
   file_info_2
   file_info_3
   group_info_0
   group_info_1
   group_users_info_0
   handle_info_1
   handle_info_2
   move_info
   msg_info_0
   msg_info_1
   ncb
   netbios_info_0
   netbios_info_1
   prdest_info
   PRDINFO
   PRDINFO3
   print_other_info
   PRJINFO
   PRJINFO2
   PRJINFO3
   prjob_info
   PRQINFO
   PRQINFO3
   prq_info
   server_info_0
   server_info_1
   server_info_2
   server_info_3
   service_info_0
   service_info_1
   service_info_2
   service_status
   session_info_0
   session_info_1
   session_info_10
   session_info_2
   share_info_0
   share_info_1
   share_info_2
   stat_server_0
   stat_workstation_0
   std_alert
   time_of_day
   user_info_0
   user_info_1
   user_info_10
   user_info_11
   user_info_2
   user_logoff_info_1
   user_logon_info_0
   user_logon_info_1
   user_logon_info_2
   user_logon_req_1
   user_modals_info_0
   user_modals_info_1
   user_other_info
   use_info_0
   use_info_1
   wksta_info_0
   wksta_info_1
   wksta_info_10
   level parameter
   sample structures
 Debugging
 #define statement
 Devicename connection
   explicit
 Devicename, redirecting
 DEVOPENSTRUC
 Disk directory
 Disk drives
   listing on a server
 Domain category
   data structures
     user_logon_info_0
     user_logon_info_2
   example
   NetGetDCName
   NetLogonEnum
   overview
 Domain controller
   getting name of
   listing
 Domain
   listing servers and workstations
   listing users of
 DosBufReset
 DosCallNmPipe
 DosChgFilePtr
 DosClose
 DosConnectNmPipe
 DosCreateThread
 DosDeleteMailslot
 DosDevIOCtl
 DosDisconnectNmPipe
 DosDisConnectNmPipe
 DosDupHandle
 DosError
 DosExecPgm
 DosGetMessage
 DosGetPID
 DosMailslotInfo
 DosMakeMailslot
 DosMakeNmPipe
 DosMuxSemWait
 DosOpen
 DosPeekMailslot
 DosPeekNmPipe
 DosPrintDestAdd
 DosPrintDestControl
 DosPrintDestDel
 DosPrintDestEnum
 DosPrintDestGetInfo
 DosPrintDestSetInfo
 DosPrintDestStatus
 DosPrintJobContinue
 DosPrintJobDel
 DosPrintJobEnum
 DosPrintJobGetId
 DosPrintJobGetInfo
 DosPrintJobPause
 DosPrintJobSetInfo
 DosPrintQAdd
 DosPrintQContinue
 DosPrintQDel
 DosPrintQEnum
 DosPrintQGetInfo
 DosPrintQPause
 DosPrintQPurge
 DosPrintQSetInfo
 DosQFHandState
 DosQHandType
 DosQNmpHandState
 DosQNmPHandState
 DosQNmPipeInfo
 DosQNmPipeSemState
 DosRead
 DosReadAsync
 DosReadMailslot
 DosSetFHandState
 DosSetNmPHandState
 DosSetNmPipeSem
 DosSetPriority
 DosSetSigHandler
 DosTransactNmPipe
 DosWaitNmPipe
 DosWrite
 DosWriteAsync
 DosWriteMailslot
 DRIVDATA
 Dynamic-link libraries
   fault handling
   protection violation handling
   stack overflow handling

     E
 ERRLOG.H header file
 errlog_other_info
 Error alert
 Error codes
 Error log codes
 Error log entry
   defined
   notification of
   writing
 Error log
   clearing
   default pathname
   default
   defined
   reading
   setting maximum size
   writing an entry to
 Error Logging category
   data structures
     error_log
   example
   NetErrorLogClear
   NetErrorLogRead
   NetErrorLogWrite
   overview
 Errors
   during pointer type conversion
   hard-coded values
 error_log
 Events
 Explicit connection
 Explicit devicename connection
 Explicit UNC connection

     F
 Fault
   dynamic-link libraries
 FAX machine
 File allocation table (FAT) file system
 File category
   data structures
     file_info_0
     file_info_1
     file_info_2
     file_info_3
   example
   NetFileClose2
   NetFileEnum2
   NetFileGetInfo2
   overview
 File
   copying on a remote server
   invalid accesses allowed
   managing remote
   moving on a remote server
   moving
 Filenames
   FAT
   HPFS
   restrictions
     character
     length
 Files
   initialization
     LANMAN.INI
   remote
     copying
     executing
     moving
 file_info_0
 file_info_1
 file_info_2
 file_info_3
 Fixed-length data
 Function names, parts of

     G
 GetInfo functions
   with SetInfo functions
 Group category
   data structures
     group_info_0
     group_info_1
     group_users_info_0
   example
   NetGroupAdd
   NetGroupAddUser
   NetGroupDel
   NetGroupDelUser
   NetGroupEnum
   NetGroupGetInfo
   NetGroupGetUsers
   NetGroupSetInfo
   NetGroupSetUsers
   overview
 Group
   assigning members
   creating
   deleting members
   disbanding
   limitations of
   special
     admins
     guests
     local
     user
 Groupname
 Groups
   adding users to
   assigning members to
   creating new
   defined
   deleting users from
   deleting
   getting information about
   listing members
   listing
   maintaining
   setting group information
   setting user information
   special
     admins
     guests
     users
 group_info_0
 group_info_1
 group_users_info_0
 Guest account
   privilege
 Guest privilege
 guests group

     H
 Handle category
   data structures
     handle_info_1
     handle_info_2
   example
   NetHandleGetInfo API
   NetHandleSetInfo API
   overview
 handle_info_1
 handle_info_2
 Header files
   ACCESS.H
   ALERT.H
   AUDIT.H
   BSEDOS.H
   CHARDEV.H
   CONFIG.H
   ERRORLOG.H
   MAILSLOT.H
   MESSAGE.H
   NCB
   NCB.H
   NETCONS.H
   NETSPOOL.H
   NETSTATS.H
   OS2DEF.H
   PMSPL.H
   REMUTIL.H
   SERVER.H
   SERVICE.H
   SHARE.H
   SHARES.H
   USE.H
   WKSTA.H
 Heuristics
   for MS OS/2
   for MS-DOS
   server
   workstation
 High-performance file system (HPFS)
 High-performance file system 386 (HPFS386)
 HPFS computers
   with local security
   without local security

     I
 Implicit connection
 Implicit UNC connection
 #include statement
 Install pending (IP) codes
 Installable file system (IFS)
 Interprocess communication (IPC)
 IPC$

     L
 LAN Manager
   API function names, parts of
   errors
   header files
   naming convention
   return codes
   service
 LANMAN.INI file
   format of
   network configuration information
   retrieving values from
   setting server values
   setting workstation values
 Level parameter
 Levels of data structure
 Linking applications
 Local and remote function calls
 Local devicename
 Log off username
 Log on username
 Logon restrictions

     M
 Mailslot category
   DosDeleteMailslot
   DosMailslotInfo
   DosMakeMailslot
   DosPeekMailslot
   DosReadMailslot
   DosWriteMailslot
   example
   overview
 Mailslot message delivery
   first-class
   second-class
 MAILSLOT.H header file
 Mailslot
   classes of delivery
   creating
   defined
   deleting
   getting information about
   managing
   maximum message size
   maximum size
   message classes
   message delivery
   priority of messages
   reading and deleting messages
   reading messages
   sample program with
   sending data
   size of messages
   writing message to
 Message (to message alias)
   broadcast
   described
   forwarding
   maximum size
   sending a file
   sending
   stopping the forwarding of
 Message alias
   adding
   case sensitivity
   defined
 Message category
   data structures
     msg_info_0
     msg_info_1
   example
   NetMessageBufferSend
   NetMessageFileSend
   NetMessageLogFileGet
   NetMessageLogFileSet
   NetMessageNameAdd
   NetMessageNameDel
   NetMessageNameEnum
   NetMessageNameFwd
   NetMessageNameGetInfo
   NetMessageNameUnFwd
   overview
 Message log
   default pathname
   enable/disable logging
   retrieving name and status of
   specifying
 Message name table
   managing
   registering a message alias in
   retrieving an alias from
 MESSAGE.H header file
 Messages
   aliases
   delivery
   first-class
   forwarding
   IPC
   mailslot
   maximum size
   MS OS/2 limits
   MS-DOS considerations
   priority
   receiving
   second-class
   sending
 Messenger service
   and Message functions
 Microsoft Bind Utility 1.3
 Microsoft C 5.1
 Microsoft C 6.0
 Microsoft C Optimizing Compiler
 Microsoft CodeView
 Microsoft LAN Manager application programming interface (API)
 Microsoft Operating System/2 (MS OS/2)
 Microsoft Windows
 Modem
 Monitoring server resources
 move_info
 MS OS/2
   data structures
   data types
   heuristics
   protection faults
   protection violations
   return codes
   standard libraries
   version 1.1
   version 1.2
 MS-DOS
   heuristics
   standard libraries
   workstation heuristics
 msg_info_0
 msg_info_1

     N
 Named Pipe category
   DosBufReset
   DosCallNmPipe
   DosClose
   DosConnectNmPipe
   DosDisConnectNmPipe
   DosDupHandle
   DosMakeNmPipe
   DosOpen
   DosPeekNmPipe
   DosQFHandState
   DosQHandType
   DosQNmPHandState
   DosQNmPipeInfo
   DosQNmPipeSemState
   DosRead
   DosReadAsync
   DosTransactNmPipe
   DosWaitNmPipe
   DosWrite
   DosWriteAsync
   example
   examples
   overview
 Named pipe handle
   getting information about
   replicating
   setting information
 Named Pipe
 Named pipe
   creating
   getting information about
 Named pipes
   MS-DOS considerations
   network considerations for
 Naming convention
 ncb
 NCB.H header file
 net command
   executing
   net start
   net view
 NetAccessAdd
 NetAccessCheck
 NetAccessDel
 NetAccessEnum
 NetAccessGetInfo
 NetAccessGetUserPerms
 NetAccessSetInfo
 NetAlertRaise
 NetAlertStart
 NetAlertStop
 NetAuditClear
 NetAuditOpen
 NetAuditRead
 NetAuditWrite
 NetBIOS category
   data structures
     ncb
     netbios_info_0
     netbios_info_1
   example
   NetBiosClose
   NetBiosEnum
   NetBiosGetInfo
   NetBiosOpen
   NetBiosSubmit
   overview
 NetBiosClose
 NetBiosEnum
 NetBiosGetInfo
 NetBiosOpen
 NetBiosSubmit
 netbios_info_0
 netbios_info_0
 netbios_info_1
 NetCharDevControl
 NetCharDevEnum
 NetCharDevGetInfo
 NetCharDevQEnum
 NetCharDevQGetInfo
 NetCharDevQPurge
 NetCharDevQPurgeSelf
 NetCharDevQSetInfo
 NetConfigGet
 NetConfigGet2
 NetConfigGetAll
 NetConfigGetAll2
 NetConnectionEnum
 NETCONS.H header file
 NetErrorLogClear
 NetErrorLogOpen
 NetErrorLogRead
 NetErrorLogWrite
 NetFileClose
 NetFileClose2
 NetFileEnum
 NetFileEnum2
 NetFileGetInfo
 NetFileGetInfo2
 NetGetDCName
 NetGroupAdd
 NetGroupAddUser
 NetGroupDel
 NetGroupDelUser
 NetGroupEnum
 NetGroupGetInfo
 NetGroupGetUsers
 NetGroupSetInfo
 NetGroupSetUsers
 NetHandleGetInfo
 NetHandleSetInfo
 Netlogon service
 NetLogonEnum
 NetMessageBufferSend
 NetMessageFileSend
 NetMessageLogFileGet
 NetMessageLogFileSet
 NetMessageNameAdd
 NetMessageNameDel
 NetMessageNameEnum
 NetMessageNameFwd
 NetMessageNameGetInfo
 NetMessageNameUnFwd
 Netpopup service
 NetProfileLoad
 NetProfileSave
 NetRemoteCopy function
 NetRemoteCopy
 NetRemoteExec
 NetRemoteMove
 NetRemoteTOD
 Netrun service
 NetServerAdminCommand
 NetServerDiskEnum
 NetServerEnum
 NetServerEnum2
 NetServerGetInfo
 NetServerSetInfo
 NetServiceControl
 NetServiceEnum
 NetServiceGetInfo
 NetServiceInstall
 NetServiceStatus
 NetSessionDel
 NetSessionEnum
 NetSessionGetInfo
 NetShareAdd
 NetShareCheck
 NetShareDel
 NetShareEnum
 NetShareGetInfo
 NetShareSetInfo
 NetSpecialSMB
 NETSPOOL.DLL dynamic-link library
 NETSPOOL.H header file
 NetStatisticsClear
 NetStatisticsGet
 NetStatisticsGet2
 NETSTATS.H header file
 NetUseAdd
 NetUseDel
 NetUseEnum
 NetUseGetInfo
 NetUserAdd
 NetUserDel
 NetUserEnum
 NetUserGetGroups
 NetUserGetInfo
 NetUserModalsGet
 NetUserModalsSet
 NetUserPasswordSet
 NetUserSetGroups
 NetUserSetInfo
 NetUserValidate
 NetUserValidate2
 NetWkstaAnnounce
 NetWkstaGetInfo
 NetWkstaInit
 NetWkstaLogoff
 NetWkstaLogon
 NetWkstaReInit
 NetWkstaReLogon
 NetWkstaSetInfo
 NetWkstaSetUID
 NetWkstaSetUID2
 Network announce rate, setting
 Network control block (NCB)
 Network Device Driver Information (level 0)
 Network Device Driver Information (level 1)
 Network management
 Network names
   FAT
   HPFS
   restrictions
 Network path
 New API functions
 New applications
   using mailslots
   using named pipes
 Non-supported API functions
 Notational conventions

     O
 Obsolescent API functions
 Opcode
 Open files, information about
 Open resources, listing
 Operator privileges
   accounts
   comm
   print
   server
 Optimized file copying, and remote files
 Optimizing performance
 OS2DEF.H header file

     P
 P permission
 Password
   assigning in user account
   changing in user account
   methods of changing
   validating user
 Path
 Pathname, conventions for specifying
 Permissions
   changing
   checking
   defining for a new resource
   deleting
   described
   directory
   file
   for resources
   for server with share-level security
   for server with user-level security
   group
   guest account
   individual
   listing for a user or group
   listing for multiple resources
   listing for one resource
   verifying
 Pipe
   anonymous
   named
 Pipename
 PMSPL.H header file
   with Print Destination functions
   with Print Job functions
   with Printer Queue functions
 Pointer type conversion
 prdest_info
 PRDINFO
 PRDINFO3
 Print Destination category
   compatibility with 1.0 applications
   data structures
     PRDINFO
     PRDINFO3
   DosPrintDestAdd
   DosPrintDestControl
   DosPrintDestDel
   DosPrintDestEnum
   DosPrintDestGetInfo
   DosPrintDestSetInfo
   example
   overview
 Print destination
   configuring
   continuing
   defined
   deleting from computer
   deleting
   establishing
 Print Destination
   getting information about
 Print destination
   listing
   pausing and continuing
   pausing
 Print Destination
   retrieving list of
 Print destination
   setting
 Print device
 Print Job category
   compatibility with 1.0 applications
   data structures
     PRJINFO
     PRJINFO2
     PRJINFO3
   DosPrintJobContinue
   DosPrintJobDel
   DosPrintJobEnum
   DosPrintJobGetId
   DosPrintJobGetInfo
   DosPrintJobPause
   DosPrintJobSetInfo
   example
   overview
 Print job
   changing position of
   controlling
   deleting
   getting information about a remote
   getting information about
   pausing
   setting priority of a submitted
 Print Jobs
   continuing after pausing
 Print jobs
   deleting all
   listing
   pausing
 Print operator
 Print spooler
 Printer definition, creating
 Printer Queue category
   compatibility with 1.0 applications
   data structures
     PRQINFO
     PRQINFO3
   DosPrintQAdd
   DosPrintQContinue
   DosPrintQDel
   DosPrintQEnum
   DosPrintQGetInfo
   DosPrintQPause
   DosPrintQPurge
   DosPrintQSetInfo
   example
   overview
 Printer queue
   adding jobs
   changing job position
   checking routing list
   configuring
   continuing a paused
   controlling
   creating
   deleting jobs
   deleting
   getting information about
   individual jobs
   listing all on a server
   listing print jobs in
   pausing
   purging
 print_other_info
 Privilege level
   assigning in user account
   changing
   checking
   groups
   methods of assigning
   user's
 Privileges
   accounts operator
   admin
   comm
   guest
   print
   server
   user
 PRJINFO
 PRJINFO2
 PRJINFO3
 prjob_info
 Process
   client
   server
 Profile file
 Programs
   binding
   executing remotely
   protected mode
   real mode
   running
 Protection violation, and dynamic-link libraries
 PRQINFO
 PRQINFO3
 prq_info

     R
 Real-Mode Windows 3.0 Applications
 Redirector, registering a user
 Reference pages, format
 Remote Utility category
   data structures
     copy_info
     move_info
     time_of_day
   example
   NetRemoteCopy
   NetRemoteExec
   NetRemoteMove
   NetRemoteTOD
   overview
 Remote
   calls
     buffer size in
     using variable-length data in
   computer
   device
   file
     copying
     managing
   server requirements
 Remoteboot service
 REMUTIL.H header file
 Replicator service
 Resource
   closing
   forcing closed
   sharing
   type
     communication-device queue
     directory
     drive
     file
     path
     pipe
     printer queue
     UNC
 Return codes
   classes of errors
   MS OS/2
   quick reference
   ranges
 Running sample programs

     S
 Sample data structures
 Sample programs
   binding
   building
   running
 Semaphore
 Server category
   data structures
     server_info_0
     server_info_1
     server_info_2
     server_info_3
   example
   NetServerAdminCommand
   NetServerDiskEnum
   NetServerEnum2
   NetServerGetInfo
   NetServerSetInfo
   overview
 SERVER.H header file
   with Server APIs
 Server
   administrating
   configuring
   controlling
   getting configuration settings
   getting statistics
   heuristics
   listing all visible
   listing connections
   listing disk drives on
   listing open files on
   listing user accounts on
   message block (SMB)
   operator
   process
   service
   statistics
   time, getting
 server_info_0
 server_info_1
 server_info_2
 server_info_3
 Service category
   data structures
     service_info_0
     service_info_1
     service_info_2
     service_status
   example
   NetServiceControl
   NetServiceEnum
   NetServiceGetInfo
   NetServiceInstall
   NetServiceStatus
   overview
 SERVICE.H header file
 Service
   continuing
   defined
   disabling standard input and output
   example
   getting information about
   installing
   managing
   names
   pausable
   pausing
   querying
   reporting errors
   run in detached mode
   setting status and codes
   signal handler
   starting and stopping
   starting
   uninstallable
   uninstalling
 Servicename
 Services
   Alerter
   Apple File Protocol (AFP)
   continuing
   controlling
   encryption service for MS-DOS LAN Manager
   handling signals
   installing signal handler
   installing
   Messenger
   Netlogon
   Netpopup
   Netrun
   parameters, parsing
   pausing
   Peer
   querying
   Remoteboot
   Replicator
   reporting installation status
   requirements
   run with MS OS/2
   Server
   signal handler function
   spawning the application thread
   Spooler
   SQL Server
   starting
   stopping
   Timesource
   uninstalling
   UPS
   Workstation
 service_info_0
 service_info_1
 service_info_2
 service_status
 Session category
   data structures
     session_info_0
     session_info_1
     session_info_10
     session_info_2
   example
   NetSessionDel
   NetSessionEnum
   NetSessionGetInfo
   overview
 Session
   between workstations and servers
   controlling
   defined
   ending
   establishing
   getting information about
   managing
   terminating
 session_info_0
 session_info_1
 session_info_10
 session_info_2
 SetInfo functions
   with GetInfo functions
 Share category
   data structures
     share_info_0
     share_info_1
     share_info_2
   example
   NetShareAdd
   NetShareCheck
   NetShareDel
   NetShareEnum
   NetShareGetInfo
   NetShareSetInfo
   overview
 Share
 Share-level security
 Shared resource
   accessing
   checking for devices
   connecting to
   controlling
   defined
   establishing a connection to
   getting information about
   listing connections to
   managing
   setting parameters of
   terminating a connection to
 Sharename
   defined
   deleting
   naming conventions
 Sharenames
 SHARES.H header file
   FRK_INIT macro
   with Connection functions
   with File functions
   with Session functions
   with Share functions
 share_info_0
 share_info_1
 share_info_2
 Signal handler
 Special permission
 Spooler
 Stack overflow
 Stack space, allocating for API function calls
 Start-up code
 Statistics category
    NetStatisticsGet2
   data structures
     stat_server_0
     stat_workstation_0
   example
   overview
 Statistics
   clearing server
   clearing workstation
 stat_server_0
 stat_workstation_0
 std_alert
 String length, constants
 Superseded API functions
 Superseded API Functions
 Superseded API functions

     T
 Text style meanings
 Time servers, listing
 time_of_day
 Transferring different processes

     U
 UNC name
 Universal-naming convention (UNC)
   explicit connection
   implicit connection
 Upgrading 1.0 applications
 Upgrading existing applications
 Use category
   data structures
     use_info_0
     use_info_1
   example
   NetUseAdd
   NetUseDel
   NetUseEnum
   NetUseGetInfo
   overview
 Use
 USE.H header file
 User account
   changing password
   creating
   getting information about
   listing all for one user
   managing
   modifying
   removing
   setting modals information
   validating
 User accounts subsystem (UAS) database
   listing accounts in
   managing accounts in
   managing user accounts in
 User category
   data structures
     group_info_0
     user_info_0
     user_info_1
     user_info_10
     user_info_11
     user_info_2
     user_modals_info_0
     user_modals_info_1
   example
   NetUserAdd
   NetUserDel
   NetUserEnum
   NetUserGetGroups
   NetUserGetInfo
   NetUserModalsGet
   NetUserModalsSet
   NetUserPasswordSet
   NetUserSetGroups
   NetUserSetInfo
   NetUserValidate2
   overview
 User privilege
 User profile management database
 User-level security
   assigning a password
   changing a user password
   sharing resources
 Useraccount, getting modals information about
 Username
   changing
   naming conventions
 Users group
 user_info_0
 user_info_1
 user_info_10
 user_info_11
 user_info_2
 user_logoff_info_1
 user_logon_info_0
 user_logon_info_1
 user_logon_info_2
 user_logon_req_1
 user_modals_info_0
 user_modals_info_1
 user_other_info
 use_info_0
 use_info_1

     V
 Variable names
 Variable-length data in remote calls
 Variable-length data
 VioPopup
 Virtual circuit

     W
 Windows 2
 Windows 3.0 protected-mode applications
 WKSTA.H header file
 wksta_info_0
 wksta_info_1
 wksta_info_10
 Workstation category
   data structures
     user_logoff_info_1
     user_logon_info_1
     wksta_info_0
     wksta_info_1
     wksta_info_10
   example
   NetWkstaGetInfo
   NetWkstaSetInfo
   NetWkstaSetUID2
   overview
 Workstation
   configuration parameters
   configuring
   controlling
   domain
   getting configuration information
   getting statistics
   heuristics
   heuristics, MS-DOS
   listing all visible
   logging off user
   logging on user
   logon script with
   service
   statistics


