home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Beijing Paradise BBS Backup
/
PARADISE.ISO
/
software
/
BBSDOORW
/
NETCLB35.ZIP
/
NETCLB35.EXE
/
DOCS
/
NETWARE.TXT
< prev
next >
Wrap
Text File
|
1996-01-03
|
306KB
|
7,188 lines
╔═════════════════════════════════════════════════════════╗
║ ║
║ Netware C Library ║
║ ║
║ Version 3.5 ║
║ ║
║ Reference Manual ║
║ ║
║ Copyright (c) Adrian M. Cunnelly 1992-1995 ║
║ ║
║ Internet: adrian@amcsoft.demon.co.uk ║
║ ║
╚═════════════════════════════════════════════════════════╝
Netware C Library Contents-1
────────────────────────────────────────────────────────────────────────────────
1. Introduction.........................................1-1
1.1 General Information............................1-1
1.2 Registration Information.......................1-1
1.3 Disclaimer.....................................1-1
1.4 Future Enhancements............................1-1
1.5 Change History.................................1-1
1.6 Function List..................................1-2
1.7 Using the Libraries............................1-5
1.8 Netware Data Types.............................1-6
1.9 Date/Time formats..............................1-7
1.10 Contacting the Author..........................1-8
2. Bindery Services.....................................2-1
2.1 Bindery Objects................................2-1
2.1.1 Object Type .............................2-1
2.1.2 Object Name..............................2-2
2.1.3 Object Flag..............................2-2
2.1.4 Object Security..........................2-2
2.1.5 Properties Flag..........................2-2
2.2 Properties and their values....................2-2
2.2.1 Property Name............................2-2
2.2.2 Property Flag............................2-3
2.2.3 Property Security........................2-3
2.2.4 Property Values Flag.....................2-3
2.3 Bindery Functions..............................2-4
2.3.1 AddBinderyObjectToSet...................2-4
2.3.2 ChangeBinderyObjectPassword.............2-4
2.3.3 ChangeBinderyObjectSecurity.............2-4
2.3.4 ChangePropertySecurity..................2-5
2.3.5 CloseBindery............................2-5
2.3.6 CreateBinderyObject.....................2-5
2.3.7 CreateProperty..........................2-5
2.3.8 DeleteBinderyObjectFromSet..............2-6
2.3.9 DeleteBinderyObject.....................2-6
2.3.10 DeleteProperty..........................2-6
2.3.11 GetBinderyAccessLevel...................2-6
2.3.12 GetBinderyObjectID......................2-7
2.3.13 GetBinderyObjectName....................2-7
2.3.14 IsBinderyObjectInSet....................2-7
2.3.15 OpenBindery.............................2-8
2.3.16 ReadPropertyValue.......................2-8
2.3.17 RenameBinderyObject.....................2-8
2.3.18 ScanBinderyObject.......................2-9
2.3.19 ScanProperty............................2-9
2.3.20 VerifyBinderyObjectPassword.............2-10
2.3.21 WritePropertyValue......................2-10
3. File Server Environment Services....................3-1
Netware C Library Contents-2
────────────────────────────────────────────────────────────────────────────────
3.1 File Server Environment Functions..............3-1
3.1.1 CheckConsolePrivileges..................3-1
3.1.2 ClearConnectionNumber...................3-1
3.1.3 ConvertPathToDirectoryEntry.............3-1
3.1.4 DisableFileServerLogin..................3-2
3.1.5 DisableTransactionTracking..............3-2
3.1.6 DownFileServer..........................3-2
3.1.7 EnableFileServerLogin...................3-2
3.1.8 EnableTransactionTracking...............3-2
3.1.9 GetBinderyObjectDiskSpaceLeft...........3-3
3.1.10 GetConnectionsOpenFiles.................3-3
3.1.11 GetConnectionsUsageStatistics...........3-4
3.1.12 GetDiskCacheStatistics..................3-4
3.1.13 GetDiskUtilisation......................3-4
3.1.14 GetFileServerDateTime...................3-5
3.1.15 GetFileServerInformation................3-5
3.1.16 GetFileServerLoginStatus................3-5
3.1.17 GetNetworkSerialNumber..................3-6
3.1.18 GetPathFromDirectoryEntry...............3-6
3.1.19 GetPhysicalDiskStatistics...............3-6
3.1.20 GetSemaphoreInformation.................3-7
3.1.21 SendConsoleBroadcast....................3-7
4. Connection/Workstation Services.....................4-1
4.1 Workstation Tables.............................4-1
4.1.1 File Server Name Table..................4-1
4.1.2 Connection ID Table.....................4-1
4.1.3 Drive Flag Table........................4-1
4.1.4 Drive Connection ID Table...............4-1
4.1.5 Drive Handle Table......................4-2
4.2 Multiple Servers...............................4-2
4.3 Connection Functions...........................4-3
4.3.1 AttachToFileServer......................4-3
4.3.2 DetachFromFileServer....................4-3
4.3.3 EnterLoginArea..........................4-3
4.3.4 GetConnectionInformation................4-3
4.3.5 GetConnectionNumber.....................4-4
4.3.6 GetInternetAddress......................4-4
4.3.7 GetObjectConnectionNumbers..............4-5
4.3.8 GetStationAddress.......................4-5
4.3.9 LoginToFileServer.......................4-5
4.3.10 LogoutFromFileServer....................4-5
4.3.11 Logout..................................4-6
4.4 Workstation Functions..........................4-6
4.4.1 EndOfJob................................4-6
4.4.2 GetConnectionIDTable....................4-6
4.4.3 GetDefaultConnectionID..................4-6
4.4.4 GetDriveConnectionID....................4-6
4.4.5 GetDriveFlagTable.......................4-7
Netware C Library Contents-3
────────────────────────────────────────────────────────────────────────────────
4.4.6 GetDriveHandleTable.....................4-7
4.4.7 GetFileServerName.......................4-7
4.4.7 GetFileServerTable......................4-7
4.4.8 GetNetwareShellVersion..................4-8
4.4.9 GetNumberOfLocalDrives..................4-8
4.4.10 GetPreferredConnectionID................4-8
4.4.11 GetPrimaryConnectionID..................4-8
4.4.12 GetServerConnectionID...................4-9
4.4.13 IsShellLoaded...........................4-9
4.4.14 SetEndofJobStatus.......................4-9
4.4.15 SetNWErrorMode..........................4-9
4.4.16 SetPreferredConnectionID................4-10
4.4.17 SetPrimaryConnectionID..................4-10
5. Queue Services......................................5-1
5.1 Queue Functions................................5-1
5.1.1 AbortServicingQueueJobAndFile...........5-1
5.1.2 AttachQueueServerToQueue................5-2
5.1.3 ChangeQueueJobEntry.....................5-2
5.1.4 ChangeQueueJobPosition..................5-2
5.1.5 ChangeToClientRights....................5-3
5.1.7 CloseFileAndAbortQueueJob...............5-3
5.1.8 CloseFileAndStartQueueJob...............5-3
5.1.6 CreateQueue.............................5-4
5.1.9 CreateQueueJobAndFile...................5-4
5.1.10 DestroyQueue............................5-5
5.1.11 DetachQueueServerFromQueue..............5-5
5.1.12 FinishServicingQueueJobAndFile..........5-5
5.1.13 GetQueueJobList.........................5-6
5.1.14 GetQueueJobsFileSize....................5-6
5.1.15 ReadQueueCurrentStatus..................5-6
5.1.16 ReadQueueJobEntry.......................5-7
5.1.17 ReadQueueServerCurrentStatus............5-7
5.1.18 RemoveJobFromQueue......................5-8
5.1.19 RestoreQueueServerRights................5-8
5.1.20 ServiceQueueJobAndOpenFile..............5-8
5.1.21 SetQueueCurrentStatus...................5-8
5.1.22 SetQueueServerCurrentStatus.............5-9
6. Message Services....................................6-1
6.1 Message Functions..............................6-1
6.1.1 BroadcastToConsole......................6-1
6.1.2 CheckPipeStatus.........................6-1
6.1.3 CloseMessagePipe........................6-2
6.1.4 GetBroadcastMessage.....................6-2
6.1.5 GetBroadcastMode........................6-2
6.1.6 GetPersonalMessage......................6-3
6.1.7 LogNetworkMessage.......................6-3
6.1.8 OpenMessagePipe.........................6-4
6.1.9 SendBroadcastMessage....................6-4
6.1.10 SendPersonalMessage.....................6-5
6.1.11 SetBroadcastMode........................6-5
Netware C Library Contents-4
────────────────────────────────────────────────────────────────────────────────
7. File Services.......................................7-1
7.1 Directory Handles..............................7-1
7.2 Search Attributes..............................7-1
7.3 File Attributes................................7-1
7.4 Extended File Attributes.......................7-2
7.5 File Functions.................................7-2
7.5.1 EraseFiles..............................7-2
7.5.2 FileServerFileCopy......................7-3
7.5.3 PurgeAllErasedFiles.....................7-3
7.5.4 PurgeErasedFiles........................7-3
7.5.5 ScanFileInformation.....................7-4
7.5.6 SetFileInformation......................7-5
8. Directory Services..................................8-1
8.1 Directory Handle Table.........................8-1
8.2 Drive Handle Table.............................8-1
8.3 Drive Flag Table...............................8-1
8.4 Drive Connection ID Table......................8-2
8.5 Trustee Rights Mask............................8-2
8.6 Directory Functions............................8-3
8.6.1 AddTrusteeToDirectory...................8-3
8.6.2 AddUserDiskSpaceRestriction.............8-3
8.6.3 AllocPermanentDirectoryHandle...........8-4
8.6.4 AllocTemporaryDirectoryHandle...........8-4
8.6.5 CreateDirectory.........................8-5
8.6.6 DeallocateDirectoryHandle...............8-5
8.6.7 DeleteDirectory.........................8-5
8.6.8 DeleteFakeRoot..........................8-6
8.6.9 DeleteTrusteeFromDirectory..............8-6
8.6.10 GetCurrentDirectory.....................8-6
8.6.11 GetDirectoryHandle......................8-6
8.6.12 GetDirectoryPath........................8-7
8.6.13 GetEffectiveDirectoryRights.............8-7
8.6.14 GetVolumeInformation....................8-7
8.6.15 GetVolumeInfoWithHandle.................8-8
8.6.16 GetVolumeInfoWithNumber.................8-8
8.6.17 GetVolumeName...........................8-9
8.6.18 GetVolumeNumber.........................8-9
8.6.19 MapFakeRoot.............................8-9
8.6.20 ModifyMaximumRightsMask.................8-10
8.6.21 RenameDirectory.........................8-10
8.6.22 RestoreDirectoryHandle..................8-10
8.6.23 SaveDirectoryHandle.....................8-11
8.6.24 ScanBinderyObjectTrusteePaths...........8-11
8.6.25 ScanDirectoryForTrustees................8-12
8.6.26 ScanDirectoryInformation................8-13
8.6.27 SetDirectoryHandle......................8-13
8.6.28 SetDirectoryInformation.................8-14
9. Print Services......................................9-1
Netware C Library Contents-5
────────────────────────────────────────────────────────────────────────────────
9.1 Print Functions................................9-1
9.1.1 CancelLPTCapture........................9-1
9.1.2 CancelSpecificLPTCapture................9-1
9.1.3 EndLPTCapture...........................9-1
9.1.4 EndSpecificLPTCapture...................9-1
9.1.5 FlushLPTCapture.........................9-2
9.1.6 FlushSpecificLPTCapture.................9-2
9.1.7 GetBannerUserName.......................9-2
9.1.8 GetLPTCaptureStatus.....................9-2
9.1.9 GetDefaultLocalPrinter..................9-2
9.1.10 GetDefaultCaptureFlags..................9-3
9.1.11 GetPrinterStatus........................9-3
9.1.12 GetSpecificCaptureFlags.................9-3
9.1.13 SetBannerUserName.......................9-4
9.1.14 SetCapturePrintQueue....................9-4
9.1.15 SetDefaultLocalPrinter..................9-4
9.1.16 SetDefaultCaptureFlags..................9-4
9.1.17 SetSpecificCaptureFlags.................9-5
9.1.18 SpecifyCaptureFile......................9-5
9.1.19 StartLPTCapture.........................9-5
9.1.20 StartSpecificLPTCapture.................9-5
10. Synchronisation Services...........................10-1
10.1 Semaphores....................................10-1
10.2 Synchronisation Functions.....................10-2
10.2.1 CloseSemaphore..........................10-2
10.2.2 ExamineSemaphore........................10-2
10.2.3 OpenSemaphore...........................10-2
10.2.4 SignalSemaphore.........................10-3
10.2.5 WaitOnSemaphore.........................10-3
11. Communication Services.............................11-1
11.1 IPX Protocol..................................11-1
11.1.1 IPX Packet Structure....................11-1
11.2 SPX Protocol..................................11-2
11.2.1 SPX Packet Structure....................11-2
11.3 Event Control Block (ECB).....................11-4
11.3.1 ECB Structure...........................11-4
11.4 IPX Functions.................................11-7
11.4.1 IPXCancelEvent..........................11-7
11.4.2 IPXCloseSocket..........................11-7
11.4.3 IPXDisconnectFromTarget.................11-7
11.4.4 IPXGetInternetworkAddress...............11-8
11.4.5 IPXGetIntervalMarker....................11-8
11.4.6 IPXGetLocalTarget.......................11-8
Netware C Library Contents-6
────────────────────────────────────────────────────────────────────────────────
11.4.7 IPXInitialise...........................11-8
11.4.8 IPXListenForPacket......................11-9
11.4.9 IPXOpenSocket...........................11-9
11.4.10 IPXRelinquishControl....................11-9
11.4.11 IPXScheduleIPXEvent.....................11-10
11.4.12 IPXSendPacket...........................11-10
11.5 SPX Functions..................................11-11
11.5.1 SPXAbortConnection......................11-11
11.5.2 SPXEstablishConnection..................11-11
11.5.3 SPXGetConnectionStatus..................11-12
11.5.4 SPXInitialise...........................11-12
11.5.5 SPXListenForConnection..................11-12
11.5.6 SPXListenForSequencedPacket.............11-13
11.5.7 SPXSendSequencedPacket..................11-14
11.5.8 SPXTerminateConnection..................11-14
Appendix I Netware Result Codes......................A1-1
Appendix II Function List.............................A2-1
Appendix III Data Structures...........................A3-1
A3.1 CONNECTION_ID_TABLE...........................A3-1
A3.2 DISK_CACHE_STATISTICS.........................A3-3
A3.3 FILE_SERVER_INFO..............................A3-5
A3.4 OPEN_FILES_INFO...............................A3-6
A3.5 PHYSICAL_DISK_STATISTICS......................A3-8
A3.6 PRINT_CONTROL_DATA............................A3-10
A3.7 QUEUE_JOB_ENTRY...............................A3-12
A3.8 SPX_CONNECTION_STATUS.........................A3-14
A3.9 VOLUME_STATISTICS.............................A3-16
Appendix IV Order Form................................A4-1
Netware C Library Chapter One - Introduction Page: 1-1
────────────────────────────────────────────────────────────────────────────────
1. Introduction
1.1 General Information
This document and the associated C libraries provide the network
programmer with a whole host of functions for accessing Novell Netware
Services. Only the small memory model libraries for Microsoft C, Turbo C
and Borland C++ are provided, but a Microsoft Windows DLL and medium and
large memory models are provided with registration. The source code is
also available, see registration below, enabling libraries for other
compilers to be produced.
The libraries were produced using Microsoft C v6.0 & v7.0, Turbo C v2.0
and Borland C++ v2.0 & 3.1. All the functions have been tested with
Novell Advanced Netware 286 v2.15, and some have been tested on Netware
3.11 and Netware 4.1.
1.2 Registration Information
Registration provides the following :-
■ Windows DLL.
■ Latest version of the libraries which will include small, medium and
large memory models for Microsoft C, Turbo C and Borland C++.
■ Royalty-free use of all library functions.
■ Unlimited technical support via e-mail or snail-mail.
■ Low-cost upgrades.
■ Source code (optional).
1.3 Disclaimer
The author, Adrian Cunnelly, claims no responsibility for any damages
caused by the use or misuse of this product. This product is distributed
"as is" with no warranty expressed or implied. The author will not be
responsible for any losses incurred, either directly or indirectly, by the
use of this product. Use this product entirely at your own risk. The
author reserves the right to make modifications at any time. Prices are
subject to change without notice.
1.4 Future Enhancements
Future versions of this library will contain Accounting, TTS and IPX
Diagnostic Services along with additional File and Synchronization
Services. The windows DLL will also be enhanced to include the IPX/SPX
services.
All registered users will be automatically informed of all updates. Which
will be available for a small fee.
1.5 Change History
For a complete list of changes see the file history.txt.
Netware C Library Chapter One - Introduction Page: 1-2
────────────────────────────────────────────────────────────────────────────────
1.6 Function List
The following functions are provided in this library:
Message Services:
BroadcastToConsole LogNetworkMessage
CheckPipeStatus OpenMessagePipe
CloseMessagePipe SendBroadcastMessage
GetBroadcastMessage SendPersonalMessage
GetBroadcastMode SetBroadcastMode
GetPersonalMessage
Connection\Workstation Services:
AttachToFileServer GetNumberOfLocalDrives
DetachFromFileServer GetObjectConnectionNumbers
EndOfJob GetPreferredConnectionID
EnterLoginArea GetPrimaryConnectionID
GetConnectionIDTable GetServerConnectionID
GetConnectionInformation GetStationAddress
GetConnectionNumber IsShellLoaded
GetDefaultConnectionID LoginToFileServer
GetDriveConnectionID Logout
GetDriveFlagTable LogoutFromFileServer
GetDriveHandleTable SetEndofJobStatus
GetFileServerName SetNWErrorMode
GetFileServerTable SetPreferredConnectionID
GetInternetAddress SetPrimaryConnectionID
GetNetwareShellVersion
Directory Services:
AddTrusteeToDirectory GetVolumeInfoWithHandle
AddUserDiskSpaceRestriction GetVolumeInfoWithNumber
AllocPermanentDirectoryHandle GetVolumeName
AllocTemporaryDirectoryHandle GetVolumeNumber
CreateDirectory MapFakeRoot
DeallocateDirectoryHandle ModifyMaximumRightsMask
DeleteDirectory RenameDirectory
DeleteFakeRoot RestoreDirectoryHandle
DeleteTrusteeFromDirectory SaveDirectoryHandle
GetCurrentDirectory ScanBinderyObjectTrusteePaths
GetDirectoryHandle ScanDirectoryForTrustees
GetDirectoryPath ScanDirectoryInformation
GetEffectiveDirectoryRights SetDirectoryHandle
GetVolumeInformation SetDirectoryInformation
File Services:
EraseFiles PurgeErasedFiles
FileServerFileCopy ScanFileInformation
PurgeAllErasedFiles SetFileInformation
Netware C Library Chapter One - Introduction Page: 1-3
────────────────────────────────────────────────────────────────────────────────
File Server Environment Services:
CheckConsolePrivileges GetDiskCacheStatistics
ClearConnectionNumber GetDiskUtilisation
ConvertPathToDirectoryEntry GetFileServerDateTime
DisableFileServerLogin GetFileServerInformation
DisableTransactionTracking GetFileServerLoginStatus
DownFileServer GetNetworkSerialNumber
EnableFileServerLogin GetPathFromDirectoryEntry
EnableTransactionTracking GetPhysicalDiskStatistics
GetBinderyObjectDiskSpaceLeft GetSemaphoreInformation
GetConnectionsOpenFiles SendConsoleBroadcast
GetConnectionsUsageStatistics
Bindery Services:
AddBinderyObjectToSet GetBinderyObjectID
ChangeBinderyObjectPassword GetBinderyObjectName
ChangeBinderyObjectSecurity IsBinderyObjectInSet
ChangePropertySecurity OpenBindery
CloseBindery ReadPropertyValue
CreateBinderyObject RenameBinderyObject
CreateProperty ScanBinderyObject
DeleteBinderyObjectFromSet ScanProperty
DeleteBinderyObject VerifyBinderyObjectPassword
DeleteProperty WritePropertyValue
GetBinderyAccessLevel
Print Services:
CancelLPTCapture GetPrinterStatus
CancelSpecificLPTCapture GetSpecificCaptureFlags
EndLPTCapture SetBannerUserName
EndSpecificLPTCapture SetCapturePrintQueue
FlushLPTCapture SetDefaultLocalPrinter
FlushSpecificLPTCapture SetDefaultCaptureFlags
GetBannerUserName SetSpecificCaptureFlags
GetLPTCaptureStatus SpecifyCaptureFile
GetDefaultLocalPrinter StartLPTCapture
GetDefaultCaptureFlags StartSpecificLPTCapture
Communication Services:
IPXCancelEvent IPXInitialise
IPXCloseSocket IPXListenForPacket
IPXDisconnectFromTarget IPXOpenSocket
IPXGetInternetworkAddress IPXRelinquishControl
IPXGetIntervalMarker IPXScheduleIPXEvent
IPXGetLocalTarget IPXSendPacket
SPXAbortConnection SPXListenForConnection
SPXEstablishConnection SPXListenForSequencedPacket
SPXGetConnectionStatus SPXSendSequencedPacket
SPXInitialise SPXTerminateConnection
Netware C Library Chapter One - Introduction Page: 1-4
────────────────────────────────────────────────────────────────────────────────
Synchronisation Services:
CloseSemaphore SignalSemaphore
ExamineSemaphore WaitOnSemaphore
OpenSemaphore
Queue Management Services:
AbortServicingQueueJobAndFile FinishServicingQueueJobAndFile
AttachQueueServerToQueue GetQueueJobList
ChangeQueueJobEntry GetQueueJobsFileSize
ChangeQueueJobPosition ReadQueueCurrentStatus
ChangeToClientRights ReadQueueJobEntry
CloseFileAndAbortQueueJob ReadQueueServerCurrentStatus
CloseFileAndStartQueueJob RemoveJobFromQueue
CreateQueue RestoreQueueServerRights
CreateQueueJobAndFile ServiceQueueJobAndOpenFile
DestroyQueue SetQueueCurrentStatus
DetachQueueServerFromQueue SetQueueServerCurrentStatus
Netware C Library Chapter One - Introduction Page: 1-5
────────────────────────────────────────────────────────────────────────────────
1.7 Using the libraries
DOS:
To use the library functions from within a DOS application, the
following must be specified in your source code:
#include "netware.h"
and your object files must be linked with one of the following
libraries:
BC2NWRES.LIB - Borland C++ v2.x Small Model Library
BC2NWREM.LIB - Borland C++ v2.x Medium Model Library
BC2NWREL.LIB - Borland C++ v2.x Large Model Library
BC3NWRES.LIB - Borland C++ v3.x Small Model Library
BC3NWREM.LIB - Borland C++ v3.x Medium Model Library
BC3NWREL.LIB - Borland C++ v3.x Large Model Library
MS6NWRES.LIB - Microsoft C v6.x Small Model Library
MS6NWREM.LIB - Microsoft C v6.x Medium Model Library
MS6NWREL.LIB - Microsoft C v6.x Large Model Library
MS7NWRES.LIB - Microsoft C v7.x Small Model Library
MS7NWREM.LIB - Microsoft C v7.x Medium Model Library
MS7NWREL.LIB - Microsoft C v7.x Large Model Library
TC2NWRES.LIB - Turbo C v2.x Small Model Library
TC2NWREM.LIB - Turbo C v2.x Medium Model Library
TC2NWREL.LIB - Turbo C v2.x Large Model Library
The medium and large model libraries are only supplied with the
registered version.
Windows (Registered version only):
To use the library functions from within a Windows application, the
following must be specified in your source code:
#define NETC_WIN
#include "netware.h"
and your object files must be linked the following Import library:
NCLIBV35.LIB
This will provide the link between your application and the windows
DLL:
NCLIBV35.DLL
Netware C Library Chapter One - Introduction Page: 1-6
────────────────────────────────────────────────────────────────────────────────
1.8 Netware Data Types
Netware numeric items are different from the native representation
internal to the PC. Instead of integers being in low-high format Netware
expects them to be in high-low format. This means that the bytes of int
and long values will have to be swapped round.
The following structures are declared in the header file "Netware.h":
typedef unsigned long dword; /* four bytes */
typedef unsigned int word; /* two bytes */
typedef unsigned char byte; /* single byte */
typedef struct { byte hi_byte;
byte lo_byte; } nw_int;
typedef struct { byte hihi_byte;
byte hilo_byte;
byte lohi_byte;
byte lolo_byte; } nw_long;
And the following functions are provided to convert between Netware
internal format and native PC format:
PC int to Netware int:
void ConvertIntToNWInt(int in,nw_int *convert);
PC long to Netware long:
void ConvertLongToNWLong(unsigned long in,nw_long *convert);
Netware int to PC int:
int ConvertNWIntToInt(nw_int in);
Netware long to PC long:
long ConvertNWLongToLong(nw_long *in);
1.9 Date/Time formats
The following structures are used by the library routines to hold date and
time values:
typedef struct { unsigned char hours; /* Hours */
unsigned char minutes; /* Minutes */
unsigned char seconds; /* Seconds */
} nw_time;
typedef struct { unsigned int year; /* Year */
unsigned char month; /* Month (1 = Jan) */
unsigned char day; /* Day (1 to 31) */
} nw_date;
Netware C Library Chapter One - Introduction Page: 1-7
────────────────────────────────────────────────────────────────────────────────
1.10 Contacting the Author
The author, Adrian Cunnelly, can be contacted by letter post at:
18 Kingsley Avenue,
Heaton Norris,
Stockport,
Cheshire.
SK4 1PW
United Kingdom
or by email to: adrian@amcsoft.demon.co.uk
Netware C Library Chapter Two - Bindery Services Page: 2-1
────────────────────────────────────────────────────────────────────────────────
2. Bindery Services
The bindery is basically a database, maintained by the Netware file
server, of the resources and users available on the network. It consists
of objects and properties. An object can be a user,group or any other
entity on the network that has been given a name. Each object can have
many properties associated with it, and each property may have an
associated value.
┌────────────┐
│ Object │
└─────┬──────┘
┌────────────────┼────────────────┐
┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐
│ Property │ │ Property │ │ Property │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐
│ Prop Value │ │ Prop Value │ │ Prop Value │
└─────────────┘ └─────────────┘ └─────────────┘
2.1 Bindery Objects
Each bindery object consists of: object ID, object type, object name,
object flag, object security, and properties flag. The object ID is a
4-byte unique identifier assigned by Netware when the object is created.
The object type and object name uniquely identify the object. The object
flag indicates whether the object is dynamic or static. The object
security determines whether other objects can access it. The properties
flag indicates whether the object has any properties associated with it.
2.1.1 Object Type
The following object types are currently recognised by Netware:
Description Object Type #define in Netware.h
Unknown 0x0000 UNKNOWN
User 0x0001 USER
User Group 0x0002 USER_GROUP
Print Queue 0x0003 PRINT_Q
File Server 0x0004 FILE_SERVER
Job Server 0x0005 JOB_SERVER
Gateway 0x0006 GATEWAY
Print Server 0x0007 PRN_SERVER
Archive Queue 0x0008 ARCHIVE_Q
Archive Server 0x0009 ARC_SERVER
Job Queue 0x000a JOB_Q
Administration 0x000b ADMIN
Remote Bridge Server 0x0026 REM_BRIDGE
Advertising Print Server 0x0047 ADV_PRN_SERVER
Reserved up to 0x8000
Wild 0xffff (-1) WILDCARD
Netware C Library Chapter Two - Bindery Services Page: 2-2
────────────────────────────────────────────────────────────────────────────────
2.1.2 Object Name
The object name contains a 48-byte null terminated string. The name
can be 1 - 47 characters long and must contain only printable
characters, it cannot include spaces or the following characters:
slash (/), backslash (\), colon (:), semicolon (;), comma (,),
asterisk (*) and question mark (?).
2.1.3 Object Flag
The object flag specifies whether the object is Static (0x00) or
Dynamic (0x01). A static object is permanent until it is specifically
deleted, but a dynamic object will disappear when the file server is
rebooted.
2.1.4 Object Security
The object security specifies who has access rights to the object, it
consists of 1 byte where the low-order nibble (bottom 4 bits) define
the read access and the high-order nibble (top 4 bits) define the
write access. The following are defined for each nibble:
Binary Access Description
0 0 0 0 Anyone Access allowed to all users
0 0 0 1 Logged Access to all logged in users
0 0 1 0 Object Access only to users who have logged in
with this object name,type and password
0 0 1 1 Supervisor Access only to supervisor users
0 1 0 0 Netware Access only allowed by Netware itself
2.1.5 Properties flag
The properties flag is an indicator which is set if there are any
properties associated with this object.
2.2 Properties and their Values
Properties are either Item Properties or Set Properties. An item property
has associated with it a 128 byte value, whereas a set property has
associated with it a list of 1 to 32 object IDs contained in a 128 byte
segment.
Each property consists of: property name, property flags, property
security and property values flag.
2.2.1 Property Name
The property name can be 1 to 15 characters long of which the
following are currently defined by Netware:
LOGIN_CONTROL Item ACCOUNT_SERVERS Set
ACCOUNT_BALANCE Item SECURITY_EQUALS Set
PASSWORD Item GROUP_MEMBERS Set
NET_ADDRESS Item GROUPS_I'M_IN Set
IDENTIFICATION Item OPERATORS Set
USER_DEFAULTS Item
Netware C Library Chapter Two - Bindery Services Page: 2-3
────────────────────────────────────────────────────────────────────────────────
2.2.2 Property Flag
The property flags is a 1 byte field, where only 2 bits are defined:
Bits 7 6 5 4 3 2 1 0
- - - - - - - 0 The property is static
- - - - - - - 1 The property is dynamic
- - - - - - 0 - The property is an item
- - - - - - 1 - The property is a set
2.2.3 Property Security
The property security specifies who has access rights to the property,
it consists of 1 byte where the low-order nibble (bottom 4 bits)
defines who can scan for and find the property and the high-order
nibble (top 4 bits) defines who can add values to the property. The
following are defined for each nibble:
Binary Access Description
0 0 0 0 Anyone Access allowed to all users
0 0 0 1 Logged Access to all logged in users
0 0 1 0 Object Access only to users who have logged in
with this object name,type and password
0 0 1 1 Supervisor Access only to supervisor users
0 1 0 0 Netware Access only allowed by Netware itself
2.2.4 Property Values Flag
The property values flag is an indicator which is set if there are any
values associated with this property.
Netware C Library Chapter Two - Bindery Services Page: 2-4
────────────────────────────────────────────────────────────────────────────────
2.3 Bindery Functions
2.3.1 AddBinderyObjectToSet
Adds a bindery object to a set property.
int AddBinderyObjectToSet(int objectType,char *objectName,
char *propertyName,int memberType,char *memberName);
Input:
objectType: Bindery object type of property owner
objectName: 48-byte null terminated Object Name of property
owner
propertyName: 16-byte null terminated Property Name
memberType: Bindery object type of object to add to the set
memberName: 48-byte null terminated Object name of object
to add to the set
Returns: Result code (see Appendix I)
2.3.2 ChangeBinderyObjectPassword
Changes the password of a bindery object. The password will be
automatically encrypted by this call, if encrypted passwords are in
use.
int ChangeBinderyObjectPassword(int objectType,char *objectName,
char *oldPassword,char *newPassword);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object Name
oldPassword: 128-byte null terminated old password, this can
be a null string if the current bindery user is
supervisor equivalent.
newPassword: 128-byte null terminated new password
Returns: Result code (see Appendix I)
2.3.3 ChangeBinderyObjectSecurity
Allows the supervisor to change the security of a bindery object.
int ChangeBinderyObjectSecurity(byte newSecurity,int objectType,
char *objectName);
Input:
newSecurity: The new security setting for this object
objectType: Bindery object type
objectName: 48-byte null terminated Object Name
Returns: Result code (see Appendix I)
Netware C Library Chapter Two - Bindery Services Page: 2-5
────────────────────────────────────────────────────────────────────────────────
2.3.4 ChangePropertySecurity
Changes the security of a bindery objects property.
int ChangePropertySecurity(int objectType,char *objectName,
byte newPropSecurity,char *propName);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object Name
newPropSecurity: The new property security
propName: 16-byte null terminated Property name
Returns: Result code (see Appendix I)
2.3.5 CloseBindery (Supervisor)
Allows the supervisor to close the bindery, it closes all bindery
files. Whilst the bindery is closed no other bindery calls can be
serviced, so the time spent with the bindery closed should be kept
to a minimum.
int CloseBindery(void);
Returns: Result code (see Appendix I)
2.3.6 CreateBinderyObject (Supervisor)
Allows the supervisor to create a bindery object.
int CreateBinderyObject(byte flag,byte security,int objectType,
char *objectName);
Input:
flag: Specifies whether static (0x00) or dynamic (0x01)
security: Security setting for this object
objectType: Bindery object type
objectName: 48-byte null terminated Object name
Returns: Result code (see Appendix I)
2.3.7 CreateProperty
Adds a property to a bindery object.
int CreateProperty(int objectType,char *objectName,
byte propFlags,byte propSecurity,char *propName);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
propFlags: Property flags (static/dynamic & item/set)
propSecurity: Security setting for this property
propName: 16-byte null terminated Property name
Returns: Result code (see Appendix I)
Netware C Library Chapter Two - Bindery Services Page: 2-6
────────────────────────────────────────────────────────────────────────────────
2.3.8 DeleteBinderyObjectFromSet
Deletes a bindery object from a set property.
int DeleteBinderyObjectFromSet(int objectType,char *objectName,
char *propertyName,int memberType,char *memberName);
Input:
objectType: Bindery object type of property owner
objectName: 48-byte null terminated Object name of property
owner
propertyName: 16-byte null terminated Set Property name
memberType: Bindery object type of object to remove from set
memberName: 48-byte null terminated Object name of object
to remove from set
Returns: Result code (see Appendix I)
2.3.9 DeleteBinderyObject (Supervisor)
Allows the supervisor to delete a bindery object.
int DeleteBinderyObject(int objectType,char *objectName);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
Returns: Result code (see Appendix I)
2.3.10 DeleteProperty
Deletes a property from a bindery object.
int DeleteProperty(int objectType,char *objectName,char *propName);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
propName: 16-byte null terminated Property name
Returns: Result code (see Appendix I)
2.3.11 GetBinderyAccessLevel
Returns the current users access level to the server's bindery.
int GetBinderyAccessLevel(long *objectID,byte *accessLevel);
Output:
objectID: Returns Bindery object ID of logged in user
accessLevel: Returns Bindery access level of logged in user.
See Object Security above.
Returns: Result code (see Appendix I)
Netware C Library Chapter Two - Bindery Services Page: 2-7
────────────────────────────────────────────────────────────────────────────────
2.3.12 GetBinderyObjectID
Returns a bindery object's identification number.
int GetBinderyObjectID(int objectType,char *objectName,
long *objectID);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
Output:
objectID: Returns ID number of specified object.
Returns: Result code (see Appendix I)
2.3.13 GetBinderyObjectName
Returns the type and name of the specified object.
int GetBinderyObjectName(long objectID,int *objectType,
char *objectName);
Input:
objectID: Bindery object identification number.
Output:
objectType: Returns bindery object type.
objectName: Returns 48-byte null terminated Bindery object name.
Returns: Result code (see Appendix I)
2.3.14 IsBinderyObjectInSet
Determines if a bindery object is a member of the specified set
property.
int IsBinderyObjectInSet(int objectType,char *objectName,
char *propertyName,int memberType,char *memberName);
Input:
objectType: Bindery object type of property owner
objectName: 48-byte null terminated Object Name of property
owner
propertyName: 16-byte null terminated Property Name
memberType: Bindery object type of object to check
memberName: 48-byte null terminated Object name of object to
check
Returns: Result code (see Appendix I)
Netware C Library Chapter Two - Bindery Services Page: 2-8
────────────────────────────────────────────────────────────────────────────────
2.3.15 OpenBindery (Supervisor)
Allows the supervisor to open the bindery, it opens all the bindery
files. The bindery files are normally kept open and locked, so this
function is only needed following a call to CloseBindery.
int OpenBindery(void);
Returns: Result code (see Appendix I)
2.3.16 ReadPropertyValue
Returns the value of a bindery objects property. This function must
be called repeatedly to return all values associated with a
particular property.
int ReadPropertyValue(int objectType,char *objectName,
char *propertyName,int segment,char *propertyValues,
byte *moreSegments,byte *propertyFlag);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
propertyName: 16-byte null terminated Property name
segment: The first time this call is made 1 should be
placed in this field, it should then be increased
by 1 for each subsequent call until the call sets
the more_segments field to 0 or a result code
of 0xec (No such segment) is returned.
Output:
propertyValues: Returns the 128-byte property value.
moreSegments: Returns if there are any more property values
to be read:
0 = No more, 0xff = More.
propertyFlag: Returns property flag.
See definition of Properties.
Returns: Result code (see Appendix I)
2.3.17 RenameBinderyObject (Supervisor)
Allows the supervisor to rename a bindery object.
int RenameBinderyObject(int objectType,char *objectName,
char *newObjectName);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated original bindery
object name
newObjectName: 48-byte null terminated new bindery object name
Returns: Result code (see Appendix I)
Netware C Library Chapter Two - Bindery Services Page: 2-9
────────────────────────────────────────────────────────────────────────────────
2.3.18 ScanBinderyObject
Searches the bindery for the specified object. This can be called
iteratively in order to scan the bindery for several objects of a
particular type.
int ScanBinderyObject(int scanObjectType,char *scanObjectName,
long *lastObjectID,int *objectType,char *objectName,
byte *objectHasProperties,byte *objectSecurity,
byte *objectFlag);
Input:
scanObjectType: Type of object to scan for. This can be
one particular type, e.g. USER 0x0001, or
all object types, e.g. WILDCARD 0xffff.
scanObjectName: 48-byte null terminated object name for
which the call should scan. The object
name can contain wildcard characters.
Output:
lastObjectID: Returns id of object found, this should
be set to -1 on the first call to this
procedure.
objectType: Returns type of object found
objectName: Returns 48-byte null terminated name of
object found
objectHasProperties: Returns whether the object has any
properties:
0x00 = No properties associated
0xff = There are some properties
objectSecurity: Returns access security bits.
See Object Security in definition of
Bindery Objects.
objectFlag: Returns object flag:
0x00 = Object is Static
0x01 = Object is Dynamic
Returns: Result code (see Appendix I)
2.3.19 ScanProperty
Searches for an objects property.
int ScanProperty(int objectType,char *objectName,
char *scanPropertyName,long *lastSequence,
char *propertyName,byte *propertyFlags,byte *propertySecurity,
byte *propertyHasValue,byte *moreProperties);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
scanPropertyName: 16-byte null terminated property name to
scan for
Netware C Library Chapter Two - Bindery Services Page: 2-10
────────────────────────────────────────────────────────────────────────────────
Output:
lastSequence: Returns the sequence number of the last
property found. This should be set to -1 on
the first call to this procedure.
propertyName: Returns 16-byte null terminated name of
the property found
propertyFlags: Returns property flag.
propertySecurity: Returns property access bits.
propertyHasValue: 0x00 = No values associated
0xff = This property has some values
moreProperties: 0x00 = No more properties
0xff = Yes there are more properties
Returns: Result code (see Appendix I)
2.3.20 VerifyBinderyObjectPassword
Verifies that the specified password matches the actual password of
the specified bindery object. The password will be automatically
encrypted by this call, if encrypted passwords are in use.
int VerifyBinderyObjectPassword(int objectType,char *objectName,
char *password);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
password: 128-byte null terminated Password to verify
Returns: Result code (see Appendix I)
2.3.21 WritePropertyValue
Writes a value to a property. Property values are stored in
128-byte segments known as value segments. Before creating value
segment n, segments 1 through n-1 must be created.
This call must not be used to write values to Set Properties,
instead use AddBinderyObjectToSet.
int WritePropertyValue(int objectType,char *objectName,
int segment,byte eraseRemaining,char *propName,byte *value);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object name
segment: Segment number to write
eraseRemaining: This specifies whether any segments that exist
after this segment are to be deleted.
0x00 = Erase all following segments
0xff = Do not erase following segments
propName: 16-byte null terminated Name of property to
amend
value: 128-byte value segment to write
Returns: Result code (see Appendix I)
Netware C Library Chapter Three - File Server Services Page: 3-1
────────────────────────────────────────────────────────────────────────────────
3. File Server Environment Services
These services allow an application to return information about the file
system, transaction tracking system, physical disks, disk channels,
volumes, disk caches etc. In fact it provides many of the functions
performed by FCONSOLE. Most of the calls in this section require either
Operator or Supervisor rights.
3.1 File Server Functions
3.1.1 CheckConsolePrivileges
This call returns whether the current logged in user has console
operator rights.
int CheckConsolePrivileges(void);
Returns: 0x00 Successful (has operator rights)
0xc6 No console rights
3.1.2 ClearConnectionNumber (Supervisor)
This clears a logical connection from the file server. It closes a
connections open files and release any file locks. On a TTS file
server it causes a connections transactions to be aborted.
int ClearConnectionNumber(int connection);
Input:
connection: Contains the connection number of the workstation
that is to be cleared.
Returns: Result code (see Appendix I)
3.1.3 ConvertPathToDirectoryEntry
Returns the volume number and directory entry for a specified path.
int ConvertPathToDirectoryEntry(byte directoryHandle,
char *directoryPath,word *volumeNumber,dword *dirEntryNumber);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full pathname
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
Netware C Library Chapter Three - File Server Services Page: 3-2
────────────────────────────────────────────────────────────────────────────────
Output:
volumeNumber: Returns the volume number containing the
directory.
directoryEntry: Returns the offset in the servers Directory
Entry Table.
Returns: Result code (see Appendix I)
3.1.4 DisableFileServerLogin (Operator)
This disables all future logins to the default file server.
int DisableFileServerLogin(void);
Returns: Result code (see Appendix I)
3.1.5 DisableTransactionTracking (Operator)
Disable transaction tracking on the default file server. It has no
effect if TTS is not installed.
int DisableTransactionTracking(void);
Returns: Result code (see Appendix I)
3.1.6 DownFileServer (Supervisor)
Close down the file server.
int DownFileServer(int forceIt);
Input:
forceIt: 0x00 = Do not close down if there are any open files
0x01 = Force close down regardless of any open files
Returns: Result code (see Appendix I)
3.1.7 EnableFileServerLogin (Operator)
Enable logins on the default file server.
int EnableFileServerLogin(void);
Returns: Result code (see Appendix I)
3.1.8 EnableTransactionTracking (Operator)
Enable transaction tracking on the default file server.
int EnableTransactionTracking(void);
Returns: Result code (see Appendix I)
Netware C Library Chapter Three - File Server Services Page: 3-3
────────────────────────────────────────────────────────────────────────────────
3.1.9 GetBinderyObjectDiskSpaceLeft
Return a bindery objects remaining disk space.
int GetBinderyObjectDiskSpaceLeft(long objectID,
long *systemElapsedTime,long *unusedDiskBlocks,
byte *restrictionsEnforced);
Input:
objectID: Bindery object identification number, this
must be the currently logged in object,
unless the logged object has console
operator rights.
Output:
systemElapsedTime: Returns time that has elapsed since the
server was loaded, in clock ticks. Where
18.2 ticks = 1 second approx. When this
field reaches 0xFFFFFFFF it wraps back to
zero.
unusedDiskBlocks: Returns the number of remaining blocks the
bindery object can allocate (1 block=4,096
bytes). The unused disk blocks available to
a user do not reflect how much disk space
is really available.
restrictionsEnforced: Returns whether disk restrictions are
active:
0x00 = Disk resource limit is active
0xff = Disk resource limit is not active
Returns: Result code (see Appendix I)
3.1.10 GetConnectionsOpenFiles (Operator)
Returns information about files a specific connection has open.
int GetConnectionsOpenFiles(int connection,int maxEntries,
OPEN_FILES_INFO *openFiles,int *fileCount);
Input:
connection: Logical connection number
maxEntries: Contains the maximum number of elements that can
be returned.
Output:
openFiles: Pointer to a row of OPEN_FILES_INFO structures
which will contain the details of the files that
the specified connection has open.
The structure is declared in "nwserver.h".
See Appendix III.
fileCount: Returns the total number of files that the
connection has open.
Returns: Result code (see Appendix I)
Netware C Library Chapter Three - File Server Services Page: 3-4
────────────────────────────────────────────────────────────────────────────────
3.1.11 GetConnectionsUsageStatistics (Operator)
Returns a logical connection's usage statistics. Console operator
rights are required unless the requesting workstation's connection
number is used.
This function is not supported in Netware 386.
int GetConnectionsUsageStatistics(int connection,
long *systemElapsedTime,double *bytesRead,
double *bytesWritten,long *totalRequestPackets);
Input:
connection: Logical connection number
Output:
systemElapsedTime: Returns time that has elapsed since the
server was loaded, in clock ticks. Where
18.2 ticks = 1 second approx. When this
field reaches 0xFFFFFFFF it wraps back to
zero.
bytesRead: Returns the number of bytes that have been
read since the workstation was logged in.
bytesWritten: Returns the number of bytes that have been
written since the workstation was logged
in.
totalRequestPackets: Returns the number of request packets sent
by the workstation to the server since the
workstation attached.
Returns: Result code (see Appendix I)
3.1.12 GetDiskCacheStatistics (Operator)
Return statistics from the default file servers cache software.
int GetDiskCacheStatistics(DISK_CACHE_STATISTICS *buffer);
Output:
buffer: Returns all cache statistics.
The structure is declared in "nwserver.h".
See Appendix III.
Returns: Result code (see Appendix I)
3.1.13 GetDiskUtilisation
Returns the disk usage of a bindery object on a volume.
int GetDiskUtilisation(long objectID,byte volumeNumber,
word *usedDirectories,word *usedFiles,word *usedBlocks);
Input:
objectID: Bindery object identification number
volumeNumber: This identifies the volume in the Volume Table
on the file server
Netware C Library Chapter Three - File Server Services Page: 3-5
────────────────────────────────────────────────────────────────────────────────
Output:
usedDirectories: Returns the number of directories owned by the
bindery object.
usedFiles: Returns the number of files created by the
bindery object
usedBlocks: Returns the number of blocks used by "usedFiles"
Returns: Result code (see Appendix I)
3.1.14 GetFileServerDateTime
Returns the current date and time on the server.
void GetFileServerDateTime(nw_time *time,nw_date *date,
int *dayOfWeek);
Output:
time: Current time, see chapter 1 for the structure format.
date: Current date, see chapter 1 for the structure format.
dayOfWeek: Returns the day of the Week (0 to 6, 0=Sunday)
3.1.15 GetFileServerInformation
Returns information about the default file server.
int GetFileServerInformation(FILE_SERVER_INFO *info);
Output:
info: Returned Information.
The Structure is declared in the header "nwserver.h".
See Appendix III.
Returns: Result code (see Appendix I)
3.1.16 GetFileServerLoginStatus (Operator)
Returns the default file server's login status.
int GetFileServerLoginStatus(int *loginEnabled);
Output:
loginEnabled: Returns whether login is enabled (0xff) or
disabled (0x00).Logins can be disabled by calling
DisableFileServerLogin and subsequently enabled
with EnableFileServerLogin.
Returns: Result code (see Appendix I)
Netware C Library Chapter Three - File Server Services Page: 3-6
────────────────────────────────────────────────────────────────────────────────
3.1.17 GetNetworkSerialNumber
Returns the default file server's serial number and application
number.
int GetNetworkSerialNumber(dword *serverSerialNumber ,
word *appSerialNumber);
Output:
serverSerialNumber: Returns the file server's serial number.
appSerialNumber: Returns the file server's application
serial number.
Returns: Result code (see Appendix I)
3.1.18 GetPathFromDirectoryEntry
Returns the full file path associated with a specified directory
entry number on a particular volume.
int GetPathFromDirectoryEntry(byte nameSpace,byte volumeNumber,
int directoryEntry,char *path);
Input:
nameSpace: The name space to use. This value is ignored for
Netware 2.x.
volumeNumber: Volume number containing the directory.
directoryEntry: The offset in the servers Directory Entry Table.
This is returned by GetConnectionsOpenFiles.
Output:
path: Returns the 256-byte null terminated full file
path of the directory.
Returns: Result code (see Appendix I)
3.1.19 GetPhysicalDiskStatistics (Operator)
Returns information about a physical disk.
int GetPhysicalDiskStatistics(byte physicalDiskNumber,
PHYSICAL_DISK_STATISTICS *diskStats);
Input:
physicalDiskNumber: Physical number of the disk.
Output:
diskStats: Returns structure containing the disk
statistics.
The structure is declared in the header file
"nwserver.h".
See Appendix III.
Returns: Result code (see Appendix I)
Netware C Library Chapter Three - File Server Services Page: 3-7
────────────────────────────────────────────────────────────────────────────────
3.1.20 GetSemaphoreInformation (Operator)
This call returns information about the specified semaphore.
int GetSemaphoreInformation( char *semaphoreName,word *openCount,
int *semaphoreValue,int maxConnections,
word *logicalConnections,word *taskNumbers,
int *connectionCount);
Input:
semaphoreName: The name of the semaphore for which
information is to be retrieved.
maxConnections: Maximum number of elements in the logical
connection and task number arrays.
Output:
openCount: Returns the number of logical connections that
have this semaphore open.
semaphoreValue: Returns the current value of the semaphore, in
the range -127 to 127. A negative value is the
number of applications that are currently
waiting for the semaphore, a positive value is
the number of applications that can still use
the semaphore.
logicalConnection: Pointer to a row of words that will contain
the logical connections that are using the
semaphore.
taskNumber: Pointer to a row of words that will contain
the task numbers within the logical
connections that have the semaphore open.
connectionCount: Total number of connections that have this
semaphore open.
Returns: Result code (see Appendix I)
3.1.21 SendConsoleBroadcast (Operator)
Send a message to a number of logical connections.
int SendConsoleBroadcast(byte connectionCount,byte *connections,
char *message );
Input:
connectionCount: Number of connections that are to receive the
message. If this is zero then all attached
workstations are broadcast to. Maximum number
of connections that can be broadcast is 100.
connections: List of connections to which message is to be
sent. Must contain "connectionCount" entries.
message: 60-byte null terminated message to send to the
specified connections.
Returns: Result code (see Appendix I)
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-1
────────────────────────────────────────────────────────────────────────────────
4. Connection/Workstation Services
These services allow applications to connect to a file server and to
obtain information about current connections and the current workstation.
4.1 Workstation Tables
These are the various tables maintained by the workstation shell:
4.1.1 File Server Name Table
This table contains the name of each file server to which the
current workstation is attached. There are 8 entries each of which
is 48 bytes in length.
4.1.2 Connection ID Table
This is used to manage connections with file servers. There is one
entry for each attached file server. The entries in the File Server
Name Table correspond to entries in this table. See the description
of the CONNECTION_ID_TABLE structure in appendix III of this manual.
4.1.3 Drive Flag Table
This table contains a flag for each workstation drive that indicates
the type of drive it is mapped to. There are 32 1-byte entries, one
for each drive letter (A to Z) and one for each temporary drive:
[ (left square bracket)
\ (backslash)
] (right square bracket)
^ (caret)
_ (underline)
' (apostrophe)
Each slot in the table contains a value which defines the type of
drive:
0x00 Not allocated
0x01 Permanent Network drive
0x02 Temporary Network drive
0x80 Local drive
0x81 Local drive allocated as a permanent network drive
0x82 Local drive allocated as a temporary network drive
4.1.4 Drive Connection ID Table
This table indicates which server each drive is mapped to. Each
entry contains a server connection number, 0 to 8, which is an index
into the Connection ID Table, a value of 0 indicates that the drive
is not mapped. There are 32 1-byte entries, one for each drive
letter (A to Z) and one for each temporary drive ([\]^_').
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-2
────────────────────────────────────────────────────────────────────────────────
4.1.5 Drive Handle Table
This table holds the file server directory handles to which each
drive is mapped. Local and unallocated drives do not have entries.
There are 32 1-byte entries, one for each drive letter (A to Z) and
one for each temporary drive ([\]^_'), each entry contains a
directory handle.
4.2 Multiple Servers
When multiple file servers are used, then the following algorithm is used
by Netware to determine which server to send the request to.
1) If the function call requires a drive letter or a connection ID
then the Server to which this points is used.
2) If a preferred file server has been set using a call to
SetPreferredConnectionID, then send the request to this server.
3) If the default drive is a network drive, then send the request
to the server associated with this drive.
4) Send the request to the primary server, which is the server the
workstation is logged into unless changed by a call to
SetPrimaryConnectionID.
5) Send the request to the first server in the Server Name Table.
This is only if the connection to the primary server has been
lost.
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-3
────────────────────────────────────────────────────────────────────────────────
4.3 Connection Functions
4.3.1 AttachToFileServer
Attaches the workstation to the specified file server. The
workstation must already be logged into at least one server, and can
be attached to as many as eight.
int AttachToFileServer(char *serverName,int *conectionID);
Input:
serverName: Name of server to which the current workstation
is to attach.
Output:
connectionID: Returns the position in the File Server Name
Table (1 to 8) allocated to this server.
Returns: Result code (see Appendix I)
4.3.2 DetachFromFileServer
Detaches the workstation from the specified file server.
int DetachFromFileServer(char *serverName);
Input:
serverName: Name of server to detach from
Returns: Result code (see Appendix I)
4.3.3 EnterLoginArea
Puts the workstation in the server's SYS:LOGIN directory and tells
Netware the name of the subdirectory beneath SYS:LOGIN in which the
login utility is located.
int EnterLoginArea(int numberOfLocalDrives,char *loginDirectoryName)
Input:
numberOfLocalDrives: Used to determine the workstation drive
ID to assign to SYS:
loginDirectoryName: 256-byte null terminated ASCII string
containing the name of the subdirectory.
Returns: Result code (see Appendix I)
4.3.4 GetConnectionInformation
Returns information about the user logged in on a connection.
int GetConnectionInformation(word connectNo,char *objectName,
int *objectType,long *objectID,byte *loginTime);
Input:
connectNo: Logical connection number
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-4
────────────────────────────────────────────────────────────────────────────────
Output:
objectName: Returns the 48-byte null terminated name of the
logged in object.
objectType: Returns the bindery object type of the logged in
object.
objectID: Returns the bindery object identification of the
logged in object.
loginTime: Returns the date and time the bindery object logged
in:
Byte: 0 Year (0 to 99, where 80=1980,81=1981 etc.
however a value less than 80 is
considered to be in the 21st century)
1 Month (1 to 12)
2 Day (1 to 31)
3 Hour (0 to 23)
4 Minute (0 to 59)
5 Second (0 to 59)
6 Week Day (0 to 6, where 0=Sunday etc.)
Returns: Result code (see Appendix I)
4.3.5 GetConnectionNumber
Returns the connection number of the requesting workstation.
int GetConnectionNumber(void);
Returns: Workstations connection number (1-100) or zero if
the workstation shell is not loaded.
4.3.6 GetInternetAddress
Returns a connections internetwork address.
int GetInternetAddress(int conn_no,byte *networkNumber,
byte *nodeAddress,word *socketNumber);
Input:
conn_no: Logical connection number
Output:
networkNumber: Returns the 4-byte network number identifying the
file server the workstation is physically attached
to.
nodeAddress: Returns the 6-byte network address of the
workstations LAN board.
socketNumber: Returns the socket that the workstation uses to
communicate with the file server. This socket
must not be used by other applications.
Returns: Result code (see Appendix I)
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-5
────────────────────────────────────────────────────────────────────────────────
4.3.7 GetObjectConnectionNumbers
Returns a list of upto 100 connection numbers indicating how many
times and under what connection numbers a bindery object is logged
in to the default file server.
int GetObjectConnectionNumbers(int objectType,char *objectName,
word *connectionCount,byte *connections);
Input:
objectType: Bindery object type
objectName: 48-byte null terminated Object Name
Output:
connectionCount: Returns the number of connections
connections: Returns a list of connection numbers, each one
is 1 byte.
Returns: Result code (see Appendix I)
4.3.8 GetStationAddress
Returns the physical node address of the requesting workstation.
void GetStationAddress(byte *physicalNodeAddress);
Output:
physicalNodeAddress: Returns the 6-byte physical address of the
workstation.
4.3.9 LoginToFileServer
Log a bindery object into the default file server. The password
will be automatically encrypted by this call, if encrypted passwords
are in use.
int LoginToFileServer(int connectionID,int objectType,
char *objectName,char *objectPassword);
Input:
connectionID: The connection ID (1-8) of the server.
objectType: Bindery object type
objectName: 48-byte null terminated Object name
objectPassword: 128-byte null terminated Object password.
Returns: Result code (see Appendix I)
4.3.10 LogoutFromFileServer
This logs the object out from the specified server, but does not
detach the workstation from the server.
void LogoutFromFileServer(char *serverName);
Input:
serverName: Name of the file server to log out from.
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-6
────────────────────────────────────────────────────────────────────────────────
4.3.11 Logout
This closes all open files belonging to the object, and logs the
object out from all files servers. It then detaches the workstation
from all servers except the default one.
void Logout(void);
4.4 Workstation Functions
4.4.1 EndOfJob
The workstation shell will automatically issue this call when a
program exits (i.e. DOS functions 0x00 and 0x4c are actioned ), so
that the workstation environment will be reset. All resources used
on the server, ( open files, locks etc. ), will be released.
void EndOfJob(void);
4.4.2 GetConnectionIDTable
This returns the workstation shells Connection ID Table. The
structure ConnectionIDTable is defined in the header file
"nwwrkstn.h"
int GetConnectionIDTable(CONNECTION_ID_TABLE *table);
Output:
table: Structure containing the connection ID table for each
attached server. This must be setup with at least eight
elements. It is declared in the header file "nwwrkstn.h".
See Appendix III.
Returns: Result code (see Appendix I)
4.4.3 GetDefaultConnectionID
Returns the connection ID (1-8) of the file server to which request
packets are currently being sent.
int GetDefaultConnectionID(void);
Returns: Default server connection ID (1-8)
4.4.4 GetDriveConnectionID
This returns the workstation shells Drive Connection ID Table. It
consists of 32 1-byte entries and each entry contains the connection
ID of the server that is associated with that drive. A value of
zero indicates that the drive is not mapped to a file server, i.e.
it is a local drive or it is not used.
void GetDriveConnectionID(char *table);
Output:
table: 32-byte string to contain the Drive Connection ID Table.
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-7
────────────────────────────────────────────────────────────────────────────────
4.4.5 GetDriveFlagTable
This returns the workstation shells Drive Flag Table. It consists
of 32 1-byte entries and each entry contains the current status of
the drive.
0x00 Not allocated
0x01 Permanent Network drive
0x02 Temporary Network drive
0x80 Local drive
0x81 Local drive allocated as a permanent Network drive
0x82 Local drive allocated as a temporary Network drive
void GetDriveFlagTable(char *table);
Output:
table: 32-byte string to contain the Drive Flag Table.
4.4.6 GetDriveHandleTable
Returns the workstation shells Drive Handle Table. It consists of
32 1-byte entries and each entry contains the directory handle on
the file server. A value of zero indicates a drive is not mapped to
a directory.
void GetDriveHandleTable(char *table);
Output:
table: 32-byte string to contain the Drive Handle Table.
4.4.7 GetFileServerName
Returns the name of the server which has the specified connection id
(1-8)
void GetFileServerName(int serverID,char *serverName);
Input:
serverID: The connection id of the server. This will be a
value between 1 and 8.
Output:
serverName: Name of the file server.
4.4.8 GetFileServerTable
Returns the workstation shells File Server Name Table. It consists
of 8 48-byte entries and each entry contains a null-terminated
server name.
void GetFileServerTable(char *table);
Output:
table: 384-byte string to contain the File Server Name Table.
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-8
────────────────────────────────────────────────────────────────────────────────
4.4.9 GetNetwareShellVersion
Returns information about the workstations shell.
void GetNetwareShellVersion(char *shellInfo,byte *majorVersion,
byte *minorVersion,byte *revisionLevel,byte *shellType);
Output:
shellInfo: 40-byte string which will contain the following
four null-terminated strings:
1) Operating system type
2) Operating system version
3) Hardware type
4) Short hardware type
majorVersion: Returns the major version number of the
workstations shell.
minorVersion: Returns the minor version number of the
workstations shell.
revisionLevel: Returns the revision number of the shell.
1 = A, 2 = B etc.
shellType: Returns the memory type of the loaded shell.
0 = conventional, 1 = expanded, 2 = extended.
This is only valid if the workstation shell is
release 3.00 or above.
4.4.10 GetNumberOfLocalDrives
Returns the number of local drives on the workstation.
int GetNumberOfLocalDrives(void);
Returns: Number of local drives.
4.4.11 GetPreferredConnectionID
This returns the connection ID of the preferred file server.
int GetPreferredConnectionID(void);
Returns: The connection ID (1-8) of the Preferred File Server.
This has been set by calling SetPreferredConnectionID.
4.4.12 GetPrimaryConnectionID
This returns the connection ID of the primary file server.
int GetPrimaryConnectionID(void);
Returns: The connection ID (1-8) of the Primary File Server.
This has been set by calling SetPrimaryConnectionID.
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-9
────────────────────────────────────────────────────────────────────────────────
4.4.13 GetServerConnectionID
Get the connection ID of the specified server.
int GetServerConnectionID(char *serverName,int *connectionID);
Input:
serverName: Server name
Output:
connectionID: The connection ID of the specified server (1-8)
Returns: Result code (see Appendix I)
4.4.14 IsShellLoaded
Checks whether a netware shell is loaded in the workstation.
int IsShellLoaded(void);
Returns: 0x00 - Shell Loaded
0xbb - No Shell Loaded
4.4.15 SetEndofJobStatus
This enables\disables the end of job performed automatically by the
workstation shell when control returns to "COMMAND.COM".
int SetEndofJobStatus(int NewStatus);
Input:
NewStatus: New end of job flag, 0 = Disabled, 1 = Enabled.
Returns: Original end of job flag.
4.4.16 SetNWErrorMode
This sets the workstation shell to determine how it should respond
to DOS emulation call errors. It has three modes :-
Mode: 0 This is the default, it uses the normal response
format used by DOS. (i.e. "Abort, Retry, Fail")
1 This will not invoke the normal INT 24h handler, but
will return the error code for all file I/O calls in
AL.
2 The shell will attempt to map the Netware error code
to a DOS error code and return it.
int SetNWErrorMode(int NewMode);
Input:
NewMode: New error mode.
Returns: Original error mode.
Netware C LibraryChapter Four - Connection/Workstation Services Page: 4-10
────────────────────────────────────────────────────────────────────────────────
4.4.17 SetPreferredConnectionID
This sets the preferred file server.
void SetPreferredConnectionID(int connection_id);
Input:
connection_id: The connection ID (1-8) of the preferred server.
4.4.18 SetPrimaryConnectionID
This sets the primary file server.
void SetPrimaryConnectionID(int connection_id);
Input:
connection_id: The connection ID (1-8) of the primary server.
Netware C Library Chapter Five - Queue Services Page: 5-1
────────────────────────────────────────────────────────────────────────────────
5. Queue Services
These services allow an application to use Netware queues for controlling
jobs and services on the network.
A queue is a bindery object, which has several bindery properties that
govern who can use the queue, who can service the queue, and who can alter
the queue information.
The properties associated with a queue are:
Q_DIRECTORY
Queues have a directory in which the queue system files and job
files are stored. This property is an item property which contains
the base directory name, the full directory name can be found by
concatenating the queues object id number. The maximum number of
characters allowed is 118, including the null terminator.
Q_USERS
This is a set property that contains all the object ids of users and
groups that can place jobs in the queue. If this property does not
exist, then any logged in object can place jobs in the queue. The
supervisor must be included in this property.
Q_SERVERS
This is a set property that contains all the object ids that are
allowed to attach and service jobs in the queue.
Q_OPERATORS
This is a set property that contains all the object ids that are
allowed to change fields in the job entry structure, reorder the
jobs and change the status of the queue.
5.1 Queue Functions
5.1.1 AbortServicingQueueJobAndFile
This call is used by a job server to inform the Queue Management
System that it cannot complete a job that it had previous accepted.
When a job is aborted, the QMS checks the service restart flag for
the job to determie whether the job can be automatically restarted.
If it is set, the entry is left in the queue in its current
position. If it is unset, the job is removed from the queue and its
associated file is deleted.
int AbortServicingQueueJobAndFile(long queueID,word jobNumber,
int fileHandle);
Input:
queueID: This is the id of the queue from which the job was
accepted for servicing.
Netware C Library Chapter Five - Queue Services Page: 5-2
────────────────────────────────────────────────────────────────────────────────
jobNumber: This is the job entry number identifying the job to
be aborted.
fileHandle: The dos file handle of the job file.
Returns: Result code (see Appendix I)
5.1.2 AttachQueueServerToQueue
This call allows a job server to attach itself to a specified queue.
A job server must attach itself to a queue before it can accept any
jobs for servicing. A maximum of 25 servers can be attached to a
queue at any one time.
The current logged in object must be security equivalent to one of
the objects listed in the queue's Q_SERVERS property.
int AttachQueueServerToQueue(long queueID);
Input:
queueID: This is the id of the queue from which the job was
accepted for servicing.
Returns: Result code (see Appendix I)
5.1.3 ChangeQueueJobEntry
This call allows information in a job's entry record to be changed.
If the job is currently being serviced, then no change will be made
and an error will be returned.
This call can be made by the user who originally created the job, or
by an operator.
int ChangeQueueJobEntry(long queueID,QUEUE_JOB_ENTRY *jobEntry);
Input:
queueID: This is the id of the queue which contains the job.
jobEntry: Pointer to the job entry structure.
The structure is declared in "nwqueue.h",see App.III
Only the following fields are allowed to be changed,
■ Target Server ID ■ Target Execution Time
■ Job Type ■ Job Control Flags
■ Text Job Description ■ Client Record Area
Returns: Result code (see Appendix I)
5.1.4 ChangeQueueJobPosition (Operator)
This call changes the position of a job within a queue.
int ChangeQueueJobPosition(long queueID,word jobNumber,
byte newPosition);
Input:
queueID: This is the id of the queue which contains the job.
Netware C Library Chapter Five - Queue Services Page: 5-3
────────────────────────────────────────────────────────────────────────────────
jobNumber: This is the job entry number of the job which is to
be repositioned.
NewPosition: This is the new position for the job. It can have a
value between 1 and 250.
Returns: Result code (see Appendix I)
5.1.5 ChangeToClientRights
This allows a job server to assume the identity of the client that
placed the job into the queue.
The job servers path mappings are not affected by this call, but the
job servers rights to the directories will be recalculated. The
RestoreQueueServerRights function reverses the effects of this call.
int ChangeToClientRights(long queueID,word jobNumber);
Input:
queueID: This is the id of the queue which contains the job.
jobNumber: This is the job entry number of the job.
Returns: Result code (see Appendix I)
5.1.6 CloseFileAndAbortQueueJob
Removes a job from the queue and deletes its associated file. This
call can only follow a call to CreateQueueJobAndFile.
int CloseFileAndAbortQueueJob(long queueID,word jobNumber,
int fileHandle);
Input:
queueID: This is the id of the queue containing the job.
jobNumber: This is the job entry number identifying the job.
fileHandle: The dos file handle of the job file.
Returns: Result code (see Appendix I)
5.1.7 CloseFileAndStartQueueJob
This call closes a job file and marks the job ready for servicing by
a job server. After closing the job file, the entry open flag in
the job control flags field will be cleared.
Only the station that created the job can make this call.
int CloseFileAndStartQueueJob(long queueID,word jobNumber,
int fileHandle);
Input:
queueID: This is the id of the queue containing the job.
jobNumber: This is the job entry number identifying the job.
fileHandle: The dos file handle of the job file.
Returns: Result code (see Appendix I)
Netware C Library Chapter Five - Queue Services Page: 5-4
────────────────────────────────────────────────────────────────────────────────
5.1.8 CreateQueue (Supervisor)
This call creates a queue of the specified name and type.
int CreateQueue(char *queueName,int queueType,
char directoryHandle,char *pathName,long *queueID);
Input:
queueName: Name of the queue to create.
queueType: Bindery object type of the queue to create.
directoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "pathName" contains the full path
name then this must be 0x00.
directoryPath: 256-byte null terminated directory path
name. This can either be a full path name,
i.e. VOLUME:DIR\..\DIR or a partial name
containing at least a directory name.
Output:
queueID: Returns the bindery object id of the created
queue.
Returns: Result code (see Appendix I)
5.1.9 CreateQueueJobAndFile
This call enters a new job into a queue.
Any station that is security equivalent to one of the objects in the
queue's Q_USER property can make this call.
int CreateQueueJobAndFile(long queueID,QUEUE_JOB_ENTRY *jobEntry,
int *fileHandle);
Input:
queueID: This is the id of the queue into which the job is to
be placed.
jobEntry: Pointer to the job entry structure.
The structure is declared in "nwqueue.h",see App III.
The following fields must be initialised:
■ Target Server ID
■ Target Execution Time
■ Job Type
■ Job Control Flags
■ Text Job Description
■ Client Record Area
And the following fields will be set after the call:
■ Client Station
■ Client Task Number
■ Client ID
■ Job Entry Time
Netware C Library Chapter Five - Queue Services Page: 5-5
────────────────────────────────────────────────────────────────────────────────
■ Job Position
■ Job File Name and Job File Handle
Output:
fileHandle: Returns DOS file handle of the job file.
Returns: Result code (see Appendix I)
5.1.10 DestroyQueue (Supervisor)
This call destroys the specified queue.
int DestroyQueue(long queueID);
Input:
queueID: This is the id of the queue to be destroyed.
Returns: Result code (see Appendix I)
5.1.11 DetachQueueServerFromQueue
This call removes the caller from the queues list of active job
servers.
int DetachQueueServerFromQueue(long queueID);
Input:
queueID: This is the id of the queue from which the calling
station is to be detached.
Returns: Result code (see Appendix I)
5.1.12 FinishServicingQueueJobAndFile
This call allows a job server to signal that it has finished
servicing a queue job.
int FinishServicingQueueJobAndFile(long queueID,word jobNumber,
long charge,int fileHandle);
Input:
queueID: This is the id of the queue from which the job was
accepted for servicing.
jobNumber: This is the job entry number identifying the job.
charge: This is not used at in the current implementation
of QMS, but is provided for future releases that
will allow job servers to charge their customers
and to log accounting information.
fileHandle: The dos file handle of the job file.
Returns: Result code (see Appendix I)
Netware C Library Chapter Five - Queue Services Page: 5-6
────────────────────────────────────────────────────────────────────────────────
5.1.13 GetQueueJobList
This call extracts all job numbers of jobs contained in a specified
queue.
Any station that is security equivalent to an object listed in the
queue's Q_USERS property or Q_OPERATORS property can make this call.
int GetQueueJobList(long queueID,word *jobCount,word *jobNumbers);
Input:
queueID: This is the id of the queue.
Output:
jobCount: Returns the total number of jobs in the queue.
jobNumbers: Pointer to a row of 250 words which will contain
the job numbers of all jobs in the queue.
Returns: Result code (see Appendix I)
5.1.14 GetQueueJobsFileSize
This call returns the size of a jobs associated file.
Any station that is security equivalent to an object listed in the
queue's Q_USERS property, Q_OPERATORS property or Q_SERVERS property
can make this call.
int GetQueueJobsFileSize(long queueID,word jobNumber,
long *fileSize);
Input:
queueID: This is the id of the queue which contains the job.
jobNumber: This is the job entry number identifying the job.
Output:
fileSize: Returns the size of the job file.
Returns: Result code (see Appendix I)
5.1.15 ReadQueueCurrentStatus
This call retrieves the current status of a queue.
int ReadQueueCurrentStatus(long queueID,byte *queueStatus,
byte *numberOfJobs,byte *numberOfServers,long *serverIDList,
word *serverStationList);
Input:
queueID: This is the id of the queue.
Output:
queueStatus: Returns the current status of the queue.
This can take any of the following values or'd
together:
0x01 New jobs cannot be added to the queue.
Netware C Library Chapter Five - Queue Services Page: 5-7
────────────────────────────────────────────────────────────────────────────────
0x02 New job servers cannot attach to the
queue.
0x04 Job servers cannot service entries in
the queue.
numberOfJobs: Returns the number of jobs in the queue.
numberOfServers: Returns the number of servers attached.
serverIDList: Returns up to 25 object IDs of attached
servers.
serverStationList: Returns up to 25 station numbers of attached
servers.
Returns: Result code (see Appendix I)
5.1.16 ReadQueueJobEntry
This call returns information about a specified job in a queue.
int ReadQueueJobEntry(long queueID,word jobNumber,
QUEUE_JOB_ENTRY *jobEntry);
Input:
queueID: This is the id of the queue which contains the job.
jobNumber: This is the job number for which information is to
be returned.
Output:
jobEntry: Pointer to the jobs's job entry structure.
The structure is declared in "nwqueue.h".
see Appendix III for details.
Returns: Result code (see Appendix I)
5.1.17 ReadQueueServerCurrentStatus
This call returns the status of a job queue server.
int ReadQueueServerCurrentStatus(long queueID,long serverID,
byte serverStation,byte *serverStatusRecord);
Input:
queueID: This is the id of the queue.
serverID: This is the ID of the job server.
serverStation: This is the station number of the job server.
Output:
serverStatusRecord: This is the 64 byte server status record
that has been set by the call to the function
SetQueueServerCurrentStatus.
Returns: Result code (see Appendix I)
Netware C Library Chapter Five - Queue Services Page: 5-8
────────────────────────────────────────────────────────────────────────────────
5.1.18 RemoveJobFromQueue
This call removes a job from a job queue.
int RemoveJobFromQueue(long queueID,word jobNumber);
Input:
queueID: This is the id of the queue which contains the job.
jobNumber: This is the job number which is to be removed.
Returns: Result code (see Appendix I)
5.1.19 RestoreQueueServerRights
This call restores a job servers own identity following a call to
ChageToClientRights.
int RestoreQueueServerRights(void);
Returns: Result code (see Appendix I)
5.1.20 ServiceQueueJobAndOpenFile
This call allows a job server to accept a new job for servicing.
int ServiceQueueJobAndOpenFile(long queueID,word targetJobType,
QUEUE_JOB_ENTRY *jobEntry,int *fileHandle);
Input:
queueID: This is the id of the queue.
targetJobType: Contains a number specifying the job type that
will be accepted for services, a value of -1
indicates that the server will accept any job type
from the queue.
Output:
jobEntry: Returs the selected jobs's job entry structure.
The structure is declared in "nwqueue.h".
see Appendix III for details.
fileHandle: Returns a dos file hanndle to the jobs job file.
Returns: Result code (see Appendix I)
5.1.21 SetQueueCurrentStatus (Operator)
This call allows a operator to control the adding of jobs and job
servers to a queue, or the preventing of current jobs being serviced
by setting or clearing bits in the queue status byte.
int SetQueueCurrentStatus(long queueID,byte queueStatus);
Input:
queueID: This is the id of the queue.
queueStatus: The queue status to be set.
This can take any of the following values or'd
together:
Netware C Library Chapter Five - Queue Services Page: 5-9
────────────────────────────────────────────────────────────────────────────────
0x01 New jobs cannot be added to the queue.
0x02 New job servers cannot attach to the
queue.
0x04 Job servers cannot service entries in
the queue.
Returns: Result code (see Appendix I)
5.1.22 SetQueueServerCurrentStatus
This call updates the current job servers status record.
int SetQueueServerCurrentStatus(long queueID,
byte *serverStatusRecord);
Input:
queueID: This is the id of the queue to which the job
server is attached.
serverStatusRecord: This is the 64-byte status field that is to
be associated with the job server. QMS does
not interpret this field, except the first 4
bytes which should contain an estimated price
for the job server to complete an average
job.
Returns: Result code (see Appendix I)
Netware C Library Chapter Six - Message Services Page: 6-1
────────────────────────────────────────────────────────────────────────────────
6. Message Services
These calls enable applications to send messages to specified connections.
The sending and destination stations must both be attached to the same
server. The messages can either be broadcast messages or pipe messages.
Each connection on a file server has a 55-byte message buffer which is
used for broadcast messages, and a six slot message queue for pipe
messages where each slot can hold a 126-byte message. Before pipe
messages can be used, the sending and receiving connections must open a
message pipe with the OpenMessagePipe function.
6.1 Message Functions
6.1.1 BroadcastToConsole
Broadcast a message to the default file servers system console.
int BroadcastToConsole(char *message);
Input:
message: 60-byte null terminated message which is to be
broadcast on the servers console.
Returns: Result code (see Appendix I)
6.1.2 CheckPipeStatus
This call enables the status of one or more message pipes to be
checked.
int CheckPipeStatus(byte connectionCount,byte *connections,
byte *pipeStatus);
Input:
connectionCount: Number of message pipes (1-100) that are to be
checked.
connections: List of the connections whose message pipe is
to be checked. There must be "connectionCount"
entries, and each entry has a corresponding
entry in the "pipeStatus" below.
Output:
pipeStatus: Returns a code for each specified connection.
0x00 OPEN. The message pipe is complete
at both ends.
0xfe INCOMPLETE. The target connections
half of the message pipe does not
exist.
0xff CLOSED. The callers half of the
message pipe does not exist, or the
connection number is not in use or is
invalid.
Returns: Result code (see Appendix I)
Netware C Library Chapter Six - Message Services Page: 6-2
────────────────────────────────────────────────────────────────────────────────
6.1.3 CloseMessagePipe
This call closes this workstations half of one or more message
pipes.
int CloseMessagePipe(byte connectionCount,byte *connections,
byte *resultCodes);
Input:
connectionCount: Number of message pipes (1-100) that are to be
closed.
connections: List of the connections whose message pipe is
to be closed. There must be "connectionCount"
entries, and each entry has a corresponding
entry in the "resultCodes" below.
Output:
resultCodes: This contains a code for each specified
connection.
0x00 Successful. The message pipe was
successfully closed.
0xfd Failure. The target connection is no
longer valid.
0xff No Pipe. There is no pipe to close.
Returns: Result code (see Appendix I)
6.1.4 GetBroadcastMessage
This is used to poll for and retrieve a broadcast message from the
default file server.
int GetBroadcastMessage(char *message)
Output:
message: 56-byte null terminated retrieved message. If the
returned message has a length of zero then there was
no message waiting.
Returns: Result code (see Appendix I)
6.1.5 GetBroadcastMode
Returns the message mode of the requesting workstation.
int GetBroadcastMode(void);
Returns: Message mode which can be one of the following :-
0x00 Attached servers will store both user and server
messages intended for this workstation. The
workstation shell will automatically retrieve and
display these messages.
Netware C Library Chapter Six - Message Services Page: 6-3
────────────────────────────────────────────────────────────────────────────────
0x01 Attached servers will store server messages intended
for this workstation, but all user messages will be
discarded. The workstation shell will automatically
retrieve and display these messages.
0x02 Attached servers will store server messages intended
for this workstation, but all user messages will be
discarded. The workstation shell will not retrieve
these messages automatically, but a program can call
GetBroadcastMessage to poll for and retrieve the
most recently stored message.
0x03 Attached servers will store both user and server
messages intended for this workstation. The
workstation shell will not retrieve these messages
automatically, but a program can poll for and
retrieve the most recently stored message by making
a call to GetBroadcastMessage.
6.1.6 GetPersonalMessage
This retrieves the oldest message from this connections pipe queue
on the default file server.
int GetPersonalMessage(char *message,byte *sourceConnection);
Output:
message: 126-byte null terminated retrieved message. If
the returned message has a length of zero then
there was no message in the pipe queue.
sourceConnection: This is the connection number of the sending
station. If this is zero then there was no
message in the pipe queue.
Returns: Result code (see Appendix I)
6.1.7 LogNetworkMessage
This logs a message in the default file servers NET$LOG.MSG file
which is held in the SYS:SYSTEM directory. The message is
automatically prefixed with the date and time and logical connection
number.
This function is not supported in Netware 386.
void LogNetworkMessage(char *message);
Input:
message: 80-byte null terminated message to write to the log
file. The message cannot contain characters with
ASCII values less than 20h or greater than 7eh.
Netware C Library Chapter Six - Message Services Page: 6-4
────────────────────────────────────────────────────────────────────────────────
6.1.8 OpenMessagePipe
This creates the calling connections half of one or more message
pipes. Before 2 connections can exchange pipe messages, both must
establish a connection by calling this function.
int OpenMessagePipe(byte connectionCount,byte *connections,
byte *resultCodes);
Input:
connectionCount:Number of connections (1-100) to which this
workstation opens a pipe.
connections: List of the connections to which this workstation
opens a pipe.
Output:
resultCodes: Returns a result code for each connection
specified in the "connections" field:
0x00 Successful. The message pipe is
complete at both ends.
0xfe Incomplete Pipe. The connections has
not yet created its half of the pipe.
0xff Failure. The connection is not valid,
or the connection is not in use.
Returns: Result code (see Appendix I)
6.1.9 SendBroadcastMessage
This sends a broadcast message to the specified connections on the
default file server.
int SendBroadcastMessage(byte connectionCount,byte *connections,
char *message,byte *resultCodes);
Input:
connectionCount:Number of connections (1-100) that are to be
broadcast.
connections: List of the connections who are to receive the
broadcast message.
message: 55-byte null terminated message to be broadcast.
Output:
resultCodes: Returns a result code for each connection
specified in the "connections" field:
0x00 Successful. The message was stored in
the connections message buffer.
0xfc Rejected. The connections message
buffer already contains a message.
0xfd Invalid Connection. The connection
number is not known.
0xff Blocked. The connections message mode
is set to block messages, or the
connection is not in use.
Netware C Library Chapter Six - Message Services Page: 6-5
────────────────────────────────────────────────────────────────────────────────
Returns: Result code (see Appendix I)
6.1.10 SendPersonalMessage
This sends a pipe message to the specified connections on the
default file server. Before this can be called, the procedure
OpenPipeMessage must have been called by both the sending and
receiving workstations.
int SendPersonalMessage(byte connectionCount,byte *connections,
char *message,byte *resultCodes);
Input:
connectionCount:Number of connections (1-100) that are to receive
the message.
connections: List of the connections who are to receive the
message.
message: 126-byte null terminated message to be sent.
Output:
resultCodes: Returns a result code for each connection
specified in the "connections" field:
0x00 Successful. The message was stored in
the connections pipe queue.
0xfc Rejected. The connections pipe queue
is full (six slots already in use).
0xfe Incomplete Pipe. The connections pipe
half does not exist.
0xff Failure. The source connectiosn pipe
half does not exist, or the connection
number is not in use.
Returns: Result code (see Appendix I)
6.1.11 SetBroadcastMode
Set the message mode for the requesting workstation.
int SetBroadcastMode(int messageMode);
Input:
messageMode: Message mode to set :-
0x00 Attached servers will store both user and server
messages intended for this workstation. The
workstation shell will automatically retrieve and
display these messages.
0x01 Attached servers will store server messages intended
for this workstation, but all user messages will be
discarded. The workstation shell will automatically
retrieve and display these messages.
0x02 Attached servers will store server messages intended
for this workstation, but all user messages will be
discarded. The workstation shell will not retrieve
Netware C Library Chapter Six - Message Services Page: 6-6
────────────────────────────────────────────────────────────────────────────────
these messages automatically, but a program can call
GetBroadcastMessage to poll for and retrieve the
most recently stored message.
0x03 Attached servers will store both user and server
messages intended for this workstation. The
workstation shell will not retrieve these messages
automatically, but a program can poll for and
retrieve the most recently stored message by making
a call to GetBroadcastMessage.
Returns: Message mode that was set.
Netware C Library Chapter Seven - File Services Page: 7-1
────────────────────────────────────────────────────────────────────────────────
7. File Services
The file services include calls that enable applications to manipulate
extended file attributes, restore erased files, permanently delete files
and set file information.
7. 1 Directory Handles
Most of the calls in the File services identify files by specifying a file
path and a directory handle. A directory handle is a value from 1 to 255
which references a volume or directory. For the function calls that
require a directory handle then zero can be supplied, but the volume name
must be specified in the file path.
For more information about directory handles and where they are stored
then see the section on Directory Services.
7.2 Search Attributes
Some functions within the File services can act on normal, hidden, or
system files. These depend on the value of the search attributes
parameter.
The following values can be supplied :-
0 - Normal files only
2 - Normal and Hidden files
4 - Normal and System files
6 - Normal, Hidden and System files
7.3 File Attributes
These are held as 1 byte, and contain the following settings:
Bits 7 6 5 4 3 2 1 0
- - - - - - - x Read only
- - - - - - x - Hidden File (not shown on directory listing)
- - - - - x - - System File (not shown on directory listing)
- - - - x - - - Execute only (cannot be cleared, once set)
- - - x - - - - Entry is a subdirectory
- - x - - - - - Needs to be archived
- x - - - - - - Not used
x - - - - - - - File is shareable
Netware C Library Chapter Seven - File Services Page: 7-2
────────────────────────────────────────────────────────────────────────────────
7.4 Extended File Attributes
These, like the file attributes, are held as 1 byte, and contain the
following settings:
Bits 7 6 5 4 3 2 1 0
- - - - - x x x Search mode bits (see below)
- - - - x - - - Reserved
- - - x - - - - Transaction bit ( used by TTS )
- - x - - - - - Index bit (file allocation table is indexed
for faster access, should be set if the file
is larger than 2 MB)
- x - - - - - - Read audit bit ( not used currently )
x - - - - - - - Write audit bit ( not used currently )
The search mode bits are only applicable for executable files, they
specify how the Netware shell should search for any files that this
file opens whilst it is running. The following values are defined:
0 No mode, use the shell's default search mode.
1 Search for files in the current directory and then in the
current search drives, only if no path is specified.
2 Search for files in the current directory only.
3 Search current directory and then in the current search
drives, only if the file is being opened in read-only
mode and no path has been specified.
5 Search for files in the current directory and then in the
current search drives regardless of whether a drive or
directory is specified.
7 Search for files in the current directory and then in the
current search drives regardless of whether a drive or
directory is specified, but only if the file is being
opened in read-only mode.
7.5 File Functions
7.5.1 EraseFiles
This marks the specified file for deletion.
int EraseFiles(byte searchAttributes,byte directoryHandle,
char *filePath);
Input:
searchAttributes: This is the type of file to be deleted.
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
filePath: 256-byte null terminated directory path name.
This can either be a full path name,
i.e. VOLUME:DIR\..\DIR in which case the
directory handle must be 0x00, or a partial
directory name which will be used in
conjunction with the directory handle.
Returns: Result code (see Appendix I)
Netware C Library Chapter Seven - File Services Page: 7-3
────────────────────────────────────────────────────────────────────────────────
7.5.2 FileServerFileCopy
This functions copies files within a server. No data is brought
back to the workstation, so network traffic is reduced. The file to
be copied and the target file must both be on the same server.
int FileServerFileCopy(int sourceFileHandle,
int destinationFileHandle,long sourceFileOffset,
long destinationFileOffset,long numberOfBytesToCopy,
long *numberOfBytesCopied);
Input:
sourceFileHandle: A dos file handle of the source file.
destinationFileHandle: A dos file handle of the destination
file.
sourceFileOffset: The offset within the source file from
which copying is to start, specify 0 for
the start of the file.
destinationFileOffset: The offset within the target file which
is to start receiving data.
numberOfBytesToCopy: The total number of bytes to copy. Specify
0 to copy the whole file.
Output:
numberOfBytesCopied: The total number of bytes copied to the
target file.
Returns: Result code (see Appendix I)
7.5.3 PurgeAllErasedFiles (Operator)
This permanently deletes all files marked for deletion by all
workstations on the network.
int PurgeAllErasedFiles(void);
Returns: Result code (see Appendix I)
7.5.4 PurgeErasedFiles
This permanently deletes all files marked for deletion by this
workstation.
int PurgeErasedFiles(void);
Returns: Result code (see Appendix I)
Netware C Library Chapter Seven - File Services Page: 7-4
────────────────────────────────────────────────────────────────────────────────
7.5.5 ScanFileInformation
Return information about the specified file. This call can be made
iteratively to return information about a group of files by
including wildcards in the filepath.
See chapter 1 for the nw_date and nw_time structure formats.
int ScanFileInformation(byte directoryHandle,char *filePath,
byte searchAttributes,int *sequenceNumber,
char *fileName,byte *fileAttributes,
byte *extendedFileAttributes,long *fileSize,
nw_date *creationDate,nw_date *lastAccessDate,
nw_date *lastUpdateDate,nw_time *lastUpdateTime,
nw_date *lastArchiveDate,nw_time *lastArchieTime,
long *fileOwnerId);
Input:
directoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "filePath" contains the full
path name then this must be 0x00.
filePath: 256-byte null terminated directory path
name. This can either be a full path name,
i.e. VOLUME:DIR\..\DIR in which case
source directory handle must be 0x00, or
a partial directory name which will be
used in conjunction with the directory
handle.
searchAttributes: This is the type of file to be scanned
for. (see section 7.2)
Output:
sequenceNumber: On the first call this must contain -1.
Do not alter for subsequent calls.
fileName: 15-byte null terminated file name.
fileAttributes: Files attributes (see section 7.3)
extendedFileAttributes: Extended attributes (see section 7.4)
fileSize: This is the size of the file in bytes.
creationDate: Date the file was created:
lastAccessDate: Date the file was last accessed.
lastUpdateDate Date the file was last updated.
lastUpdateTime: Time the file was last updated.
lastArchiveDate: Date the file was last archived.
lastArchiveTime: Time the file was last archived.
fileOwnerId: The bindery object ID of the user who
created the file.
Returns: Result code (see Appendix I)
Netware C Library Chapter Seven - File Services Page: 7-5
────────────────────────────────────────────────────────────────────────────────
7.5.6 SetFileInformation
Return information about the specified file. This call can be made
iteratively to return information about a group of files by
including wildcards in the filepath.
See chapter 1 for the nw_date and nw_time structure formats.
int SetFileInformation(byte directoryHandle,char *filePath,
byte searchAttributes,byte *fileAttributes,
byte *extendedFileAttributes,nw_date *creationDate,
nw_date *lastAccessDate,nw_date *lastUpdateDate,
nw_time *lastUpdateTime,nw_date *lastArchiveDate,
nw_time *lastArchiveTime,long *fileOwnerId);
Input:
directoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "filePath" contains the full
path name then this must be 0x00.
filePath: 256-byte null terminated directory path
name. This can either be a full path name,
i.e. VOLUME:DIR\..\DIR in which case
source directory handle must be 0x00, or
a partial directory name which will be
used in conjunction with the directory
handle.
searchAttributes: This is the search attributes for the
file. (see section 7.2)
fileAttributes: New file attributes (see section 7.3).
Specify NULL if this isn't to be changed.
extendedFileAttributes: New extended attributes (see section 7.4)
Specify NULL if this isn't to be changed.
creationDate: New creation date.
Specify NULL if this isn't to be changed.
lastAccessDate: New last accessed date.
Specify NULL if this isn't to be changed.
lastUpdateDate New last updated date.
Specify NULL if this isn't to be changed.
lastUpdateTime: New last updated time.
Specify NULL if this isn't to be changed.
lastArchiveDate: New last archived date.
Specify NULL if this isn't to be changed.
lastArchiveTime: New last archived time.
Specify NULL if this isn't to be changed.
fileOwnerId: New file owners bindery object ID.
Specify NULL if this isn't to be changed.
Returns: Result code (see Appendix I)
Netware C Library Chapter Eight - Directory Services Page: 8-1
────────────────────────────────────────────────────────────────────────────────
8. Directory Services
These calls can allocate and deallocate directory handles; create, rename
and destroy directories; add and delete directory trustees; return
information about volumes and directories; and modify a directories
maximum rights mask.
8.1 Directory Handle Table
Every connection on a file server has the ability to have up to 256
directory handles, these are held on the server in the Directory Handle
Table, one table for each connection, each table contains 256 slots where
each slot represents a directory handle. A directory handle is a number,
1 to 255, that points to a volume or a directory path. Once a directory
handle has been set this can be used when a volume or directory path needs
to be specified.
8.2 Drive Handle Table
This is maintained by the workstations shell program. It contains 32
1-byte entries. The first 26 slots represent the permanent drive letters
A-Z, the last six slots represent the temporary drive letters:-
[ (left square bracket)
\ (backslash)
] (right square bracket)
^ (caret)
_ (underline)
' (apostrophe)
Each slot in the table contains a directory handle number.
8.3 Drive Flag Table
This is maintained by the workstations shell program. It contains 32
1-byte entries. The first 26 slots represent the permanent drive letters
A-Z, the last six slots represent the temporary drive letters:-
[ (left square bracket)
\ (backslash)
] (right square bracket)
^ (caret)
_ (underline)
' (apostrophe)
Each slot in the table contains a value which defines the type of drive:
0x00 Not allocated
0x01 Permanent Network drive
0x02 Temporary Network drive
0x80 Local drive
0x81 Local drive allocated as a permanent network drive
0x82 Local drive allocated as a temporary network drive
Netware C Library Chapter Eight - Directory Services Page: 8-2
────────────────────────────────────────────────────────────────────────────────
8.4 Drive Connection ID Table
This is maintained by the workstations shell program. It contains 32
1-byte entries. The first 26 slots represent the permanent drive letters
A-Z, the last six slots represent the temporary drive letters:-
[ (left square bracket)
\ (backslash)
] (right square bracket)
^ (caret)
_ (underline)
' (apostrophe)
Each slot contains a value, 0 to 8, identifying the server to which the
drive letter is mapped. A value of 0 indicates that the drive is not
mapped, a value of 1-8 represents the position of the server in the
workstations Server Name Table.
8.5 Trustee Rights
A users trustee rights and a directories maximum rights are held as 1 byte
consisting of the following settings:-
(MSB) Bit 7: Modify (file attributes can be modified)
6: Search (directory can be searched)
5: Parental (subdirectories can be created/deleted
& trustee rights granted/revoked)
4: Delete (files can be deleted)
3: Create (files can be created)
2: Open (files can be opened)
1: Write (file writes allowed)
(LSB) 0: Read (file reads allowed)
When a users trustee rights and a directories maximum rights mask are
logically anded together, they produce a users effective rights in the
specified directory.
Netware C Library Chapter Eight - Directory Services Page: 8-3
────────────────────────────────────────────────────────────────────────────────
8.6 Directory Functions
8.6.1 AddTrusteeToDirectory
Add a trustee to a directories trustee list. The requesting
workstation must have parental rights to the target directory, or to
a parent directory.
int AddTrusteeToDirectory(byte directoryHandle,char *directoryPath,
long trusteeObjectID,byte trusteeRightsMask);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full pathname
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
trusteeObjectID: Bindery object ID of user name to add to
the specified directories trustee list.
trusteeRightsMask: The rights mask to be given to the user.
If the user is already a trustee in the
specified directory, then this replaces the
existing rights.
Returns: Result code (see Appendix I)
8.6.2 AddUserDiskSpaceRestriction
Sets an object's volume disk space restriction. All restrictions are
in 4k blocks.
int AddUserDiskSpaceRestriction(byte volumeNumber,
long objectID, long volumeLimit);
Input:
volumeNumber: This identifies the volume in the file servers
Volume Table.
objectID: Bindery object ID of the user to which disk space
restriction is to be added.
volumeLimit: Disk space limit. Valid value is from 0 to
0x40000000.
Returns: Result code (see Appendix I)
Netware C Library Chapter Eight - Directory Services Page: 8-4
────────────────────────────────────────────────────────────────────────────────
8.6.3 AllocPermanentDirectoryHandle
Permanently assign a workstation drive to a network directory.
int AllocPermanentDirectoryHandle(byte directoryHandle,
char *directoryPath,char driveLetter,byte *newDirectoryHandle,
byte *effectiveRightsMask);
Input:
directoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "directoryPath" contains the
full path name then this must be 0x00.
directoryPath: 256-byte null terminated directory path
name. This can either be a full path name,
i.e. VOLUME:DIR\..\DIR or a partial name
containing at least a directory name.
driveLetter: Drive letter to assign to the directory.
Output:
newDirectoryHandle: The new directory handle pointing to the
specified directory.
effectiveRightsMask: This is the result of logically anding
the users trustee rights with the
directories maximum rights.
Returns: Result code (see Appendix I)
8.6.4 AllocTemporaryDirectoryHandle
Temporarily assign a workstation drive to a network directory. The
allocation is only valid until the application executes an EndOfJob,
or until the job deallocates the drive with
DeallocateDirectoryHandle.
int AllocTemporaryDirectoryHandle(byte directoryHandle,
char *directoryPath,char driveLetter,byte *newDirectoryHandle,
byte *effectiveRightsMask);
Input:
directoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "directoryPath" contains the
full path name then this must be 0x00.
directoryPath: 256-byte null terminated directory path
name. This can either be a full path name,
i.e. VOLUME:DIR\..\DIR or a partial name
containing at least a directory name.
driveLetter: Drive letter to assign to the specified
directory.
Output:
newDirectoryHandle: The new directory handle pointing to the
specified directory.
Netware C Library Chapter Eight - Directory Services Page: 8-5
────────────────────────────────────────────────────────────────────────────────
effectiveRightsMask: This is the result of logically anding
the users trustee rights with the
directories maximum rights.
Returns: Result code (see Appendix I)
8.6.5 CreateDirectory
This creates a subdirectory under the directory which is pointed to
by "directoryHandle".
int CreateDirectory(byte directoryHandle,byte maximumRightsMask,
char *directoryPath);
Input:
directoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "directoryPath" contains the
full path name then this must be 0x00.
maximumRightsMask: This indicates the maximu rights that a
user can have in this directory.
directoryPath: 256-byte null terminated directory path
name. This can either be a full path name,
i.e. VOLUME:DIR\..\DIR or a partial name
containing at least a directory name.
Returns: Result code (see Appendix I)
8.6.6 DeallocateDirectoryHandle
Deallocate a permanent or temporary directory handle.
int DeallocateDirectoryHandle(byte directoryHandle);
Input:
directoryHandle: Directory handle to deallocate.
Returns: Result code (see Appendix I)
8.6.7 DeleteDirectory
int DeleteDirectory(byte directoryHandle,char *directoryPath);
Input:
directoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "directoryPath" contains the
full path name then this must be 0x00.
directoryPath: 256-byte null terminated directory path
name. This can either be a full path name,
i.e. VOLUME:DIR\..\DIR or a partial name
containing at least a directory name.
Returns: Result code (see Appendix I)
Netware C Library Chapter Eight - Directory Services Page: 8-6
────────────────────────────────────────────────────────────────────────────────
8.6.8 DeleteFakeRoot
This call deletes a fake root, that was created using MapFakeRoot.
void DeleteFakeRoot(byte drive);
Input:
drive: Drive number to remove ( 0=current, 1=A, 2=B etc. )
8.6.9 DeleteTrusteeFromDirectory
This removes a trustee form a directorys trustee list.
int DeleteTrusteeFromDirectory(byte directoryHandle,
char *directoryPath,long trusteeObjectID);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full path name
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
trusteeObjectID: Bindery object ID of user name to remove
from the specified directories trustee list.
Returns: Result code (see Appendix I)
8.6.10 GetCurrentDirectory
This returns the current directory for the given drive.
int GetCurrentDirectory(char driveNumber,char *directoryPath);
Input:
driveNumber: Drive number whose current directory is to be
returned. (0 to 25 = A-Z, 26 to 31 = [\]^_')
Output:
directoryPath: 256-byte null terminated current path of
specified drive.
Returns: Result code (see Appendix I)
8.6.11 GetDirectoryHandle
Returns the directory handle of the given drive.
int GetDirectoryHandle(char driveNumber,byte *statusFlags);
Input:
driveNumber: Drive number whose handle is to be returned.
(0 to 25 = A-Z, 26 to 31 = [\]^_' )
Netware C Library Chapter Eight - Directory Services Page: 8-7
────────────────────────────────────────────────────────────────────────────────
Output:
statusFlags: This is 1-byte with the following bits defined:-
(MSB) Bit 7: Mapped to a local drive
6-2: Unused
1: Temporary directory handle
(LSB) 0: Permanent directory handle
Returns: Directory Handle (1 to 255), or zero if invalid.
8.6.12 GetDirectoryPath
Returns the directory path of the specified handle.
int GetDirectoryPath(byte directoryHandle,char *directoryPath);
Input:
directoryHandle: Directory handle whose path is to be returned.
Output:
directoryPath: 256-byte null terminated full path name.
Returns: Result code (see Appendix I)
8.6.13 GetEffectiveDirectoryRights
Returns the current users effective rights to the directory.
int GetEffectiveDirectoryRights(byte directoryHandle,
char *directoryPath,byte *effectiveRights);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full path name
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
Output:
effectiveRights: Users effective rights in this directory.
Returns: Result code (see Appendix I)
8.6.14 GetVolumeInformation
This returns information about the specified volume. The structure
VolumeStatistics is defined in the header file "NWDirect.h"
int GetVolumeInformation(byte volumeNumber,
VOLUME_STATISTICS *replyBuffer);
Input:
volumeNumber: This identifies the volume in the file servers
Volume Table.
Netware C Library Chapter Eight - Directory Services Page: 8-8
────────────────────────────────────────────────────────────────────────────────
Output:
replyBuffer: Structure containing the volume statistics.
It is declared in the header file "NWDirect.h".
See Appendix III.
Returns: Result code (see Appendix I)
8.6.15 GetVolumeInfoWithHandle
This returns information about a volume using a directory handle.
int GetVolumeInfoWithHandle(byte directoryHandle,
char *volumeName,word *sectorsPerBlock,word *totalBlocks,
word *availableBlocks,word *totalDirectorySlots,
word *availableDirectorySlots,int *volumeIsRemovable);
Input:
directoryHandle: Directory handle pointing to an entry
in the servers Directory Handle Table.
Output:
volumeName: 17-byte null terminated volume name
sectorsPerBlock: This is the number of 512-byte
sectors contained in each block of
the specified volume.
totalBlocks: This is the total number of blocks
on the specified volume.
availableBlocks: This is the total number of unused
blocks on the specified volume.
totalDirectorySlots: This is the number of directory slots
that the installer allocated.
availableDirectorySlots: This is the total number of unused
directory slots.
volumeIsRemovable: A value of zero indicates that the
volume cannot be removed.
Returns: Result code (see Appendix I)
8.6.16 GetVolumeInfoWithNumber
This returns information about a volume using a volume number.
int GetVolumeInfoWithNumber(byte volumeNumber,char *volumeName,
word *sectorsPerBlock,word *totalBlocks,word *availableBlocks,
word *totalDirectorySlots,word *availableDirectorySlots,
int *volumeIsRemovable);
Input:
volumeNumber: Number of the volume in the servers
Volume Name Table.
Output:
volumeName: 17-byte null terminated volume name
Netware C Library Chapter Eight - Directory Services Page: 8-9
────────────────────────────────────────────────────────────────────────────────
sectorsPerBlock: This is the number of 512-byte
sectors contained in each block of
the specified volume.
totalBlocks: This is the total number of blocks
on the specified volume.
availableBlocks: This is the total number of unused
blocks on the specified volume.
totalDirectorySlots: This is the number of directory slots
that the installer allocated.
availableDirectorySlots: This is the total number of unused
directory slots.
volumeIsRemovable: A value of zero indicates that the
volume cannot be removed.
Returns: Result code (see Appendix I)
8.6.17 GetVolumeName
This call returns the volume name of the specified volume.
int GetVolumeName(int volumeNumber,char *volumeName);
Input:
volumeNumber: This identifies the volume in the servers volume
table, it is an integer in the range 0-31.
Output:
volumeName: 17-byte null terminated name of the volume.
Returns: Result code (see Appendix I)
8.6.18 GetVolumeNumber
This call returns the volume number of the specified volume.
int GetVolumeNumber(char *volumeName,int *volumeNumber);
Input:
volumeName: 17-byte null terminated Volume name.
Output:
volumeNumber: Returned internal number of the specified volume.
Returns: Result code (see Appendix I)
8.6.19 MapFakeRoot
This call allows you to map any drive as a fake root. If the drive
is not currently mapped then this will create the mapping and set
the fake root.
int MapFakeRoot(byte drive,char *path);
Input:
drive: Drive number to map ( 0 = current, 1 = A ,
2 = B etc. )
Netware C Library Chapter Eight - Directory Services Page: 8-10
────────────────────────────────────────────────────────────────────────────────
path: The full path for the fake root.
Returns: Result code (see Appendix I)
8.6.20 ModifyMaximumRightsMask
Modify the maximum rights mask of a specific directory.
int ModifyMaximumRightsMask(byte directoryHandle,
char *directoryPath,byte revokeRightsMask,byte grantRightsMask);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full path name
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
revokeRightsMask: The rights to be removed.
grantRightsMask: The rights to be added
Returns: Result code (see Appendix I)
8.6.21 RenameDirectory
Renames the specified server directory.
int RenameDirectory(byte directoryHandle,char *directoryPath,
char *newDirectoryName);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full path name
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
newDirectoryName: 15-byte null terminated new directory name.
Returns: Result code (see Appendix I)
8.6.22 RestoreDirectoryHandle
Restores a previously saved directory handle
int RestoreDirectoryHandle(char *saveBuffer,
byte *newDirectoryHandle,byte *effectiveRightsMask);
Input:
saveBuffer: 16-byte save buffer.
Netware C Library Chapter Eight - Directory Services Page: 8-11
────────────────────────────────────────────────────────────────────────────────
Output:
newDirectoryHandle: The directory handle that has been restored.
effectiveRightsMask: The users current effective rights here.
Returns: Result code (see Appendix I)
8.6.23 SaveDirectoryHandle
Saves a specific directory handle.
int SaveDirectoryHandle(byte directoryHandle,char *saveBuffer);
Input:
directoryHandle: Directory handle to be saved.
Output:
saveBuffer: 16-byte buffer which contains the saved
information.
Returns: Result code (see Appendix I)
8.6.24 ScanBinderyObjectTrusteePaths
This returns the directory paths to which the specified object has
trustee rights. This call must be made repeatedly to obtain all
paths.
int ScanBinderyObjectTrusteePaths(long objectID,byte volumeNumber,
int *sequenceNumber,char *trusteeAccessMask,
char *trusteePathName);
Input:
objectID: Bindery object ID to scan for.
volumeNumber: Server volume number to scan (0-31)
sequenceNumber: On the first call this must contain zero.
Do not alter for subsequent calls.
Output:
sequenceNumber: Returns the sequence number of the next path.
trusteeAccessMask: The rights the object has in this directory.
trusteePathName: 256-byte null terminated path name.
Returns: Result code (see Appendix I)
Netware C Library Chapter Eight - Directory Services Page: 8-12
────────────────────────────────────────────────────────────────────────────────
8.6.25 ScanDirectoryForTrustees
This returns the trustees of the specified directory. This call
must be made repeatedly in order to obtain all the trustees of the
specified directory.
See chapter 1 for the nw_date and nw_time structure formats.
int ScanDirectoryForTrustees(byte directoryHandle,
char *directoryPath,int *sequenceNumber,char *directoryName,
nw_date *creationDate,nw_time *creationTime,long *ownerID,
long *trusteeID,byte *trusteeRightsMask);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full path name
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
sequenceNumber: On the first call this must contain zero.
Do not alter for subsequent calls.
Output:
sequenceNumber: Returns the sequence number of the next trustee
directoryName: 16-byte name of the directory.
creationDate: Date the directory was created.
creationTime: Time the directory was created.
ownerID: The bindery object ID of the user that created
this directory.
trusteeID: The bindery object ID of a trustee of the
directory.
trusteeRightsMask:The trustees effective rights in this
directory.
Returns: Result code (see Appendix I)
Netware C Library Chapter Eight - Directory Services Page: 8-13
────────────────────────────────────────────────────────────────────────────────
8.6.26 ScanDirectoryInformation
This returns information about the first or next subdirectory of the
specified directory.
See chapter 1 for the nw_date and nw_time structure formats.
int ScanDirectoryInformation(byte searchDirectoryHandle,
char *searchDirectoryPath,int *subdirNumber,char *directoryName,
nw_date *creationDate,nw_time *creationTime,long *ownerObjectID,
byte *maximumRightsMask);
Input:
searchDirectoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "searchDirectoryPath" contains
the full path name then this must be
0x00.
searchDirectoryPath: 256-byte null terminated directory path
name. This can either be a full path name
i.e. VOLUME:DIR\..\DIR or a partial name
containing at least a directory name. The
path can contain wildcard characters.
subdirNumber: On the first call this must contain zero.
Do not alter for subsequent calls.
Output:
subdirNumber: Returns the directory number of the next
sub directory.
directoryName: 16-byte name of the directory.
creationDate: Date the directory was created.
creationTime: Time the directory was created.
ownerObjectID: The bindery object ID of the user that
created this directory.
maximumRightsMask: This is the maximum rights that any user
will have in this subdirectory. See
section 8.5 for possible settings.
Returns: Result code (see Appendix I)
8.6.27 SetDirectoryHandle
Assigns a directory handle to a given path.
int SetDirectoryHandle(byte sourceDirectoryHandle,
char *sourceDirectoryPath,byte targetDirectoryHandle);
Input:
sourceDirectoryHandle: An optional directory handle, pointing to
an entry in the servers Directory Handle
Table. If "sourceDirectoryPath" contains
the full path name then this must be 0x00
Netware C Library Chapter Eight - Directory Services Page: 8-14
────────────────────────────────────────────────────────────────────────────────
sourceDirectoryPath: 256-byte null terminated directory path
name. This can either be a full path name
i.e. VOLUME:DIR\..\DIR in which case
source directory handle must be 0x00, or
a partial directory name which will be
used in conjunction with the source
directory handle.
targetDirectoryHandle: The directory handle which is to point
to the above specified directory. If the
call fails, then this will point to its
original directory.
Returns: Result code (see Appendix I)
8.6.28 SetDirectoryInformation
This functions sets information for a specified directory.
See chapter 1 for the nw_date and nw_time structure formats.
int SetDirectoryInformation(byte directoryHandle,
char *directoryPath,nw_date *creationDate,nw_time *creationTime,
long *ownerObjectID,byte *maximumRightsMask);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "directoryPath" contains the full path name
then this must be 0x00.
directoryPath: 256-byte null terminated directory path name.
This can either be a full path name, i.e.
VOLUME:DIR\..\DIR or a partial name containing
at least a directory name.
creationDate: New directory creation date.
Specify NULL if this isn't to be changed.
creationTime: New directory creation time.
Specify NULL if this isn't to be changed.
ownerObjectID: New owner of the directory.
Specify NULL if this isn't to be changed.
maximumRightsMask: New maximum rights mask for the directory.
Specify NULL if this isn't to be changed.
Returns: Result code (see Appendix I)
Netware C Library Chapter Nine - Print Services Page: 9-1
────────────────────────────────────────────────────────────────────────────────
9. Print Services
These services allow data that is sent to a LPT device, to be captured and
redirected to a specific file server.
9.1 Print Functions
9.1.1 CancelLPTCapture
This cancels the capture of the default LPT device. The print queue
job entry is removed and the capture file is deleted unless it is a
permanent file. The LPT device is then returned to local printing
mode.
int CancelLPTCapture(void);
Returns: Result code (see Appendix I)
9.1.2 CancelSpecificLPTCapture
This cancels the capture of a specific LPT device. The print queue
job entry is removed and the capture file is deleted unless it is a
permanent file. The LPT device is then returned to local printing
mode.
int CancelSpecificLPTCapture(int prnNo);
Input:
prnNo: LPT device number (0-2,0=LPT1)
Returns: Result code (see Appendix I)
9.1.3 EndLPTCapture
This call ends the capture of the default LPT device. The capture
file will be closed and the queue job entry will be released so that
a print service may process it. The LPT device is then returned to
local printing mode.
int EndLPTCapture(void);
Returns: Result code (see Appendix I)
9.1.4 EndSpecificLPTCapture
This call ends the capture of a specific LPT device. The capture
file will be closed and the queue job entry will be released so that
a print service may process it. The LPT device is then returned to
local printing mode.
int EndSpecificLPTCapture(int prnNo);
Input:
prnNo: LPT device number (0-2,0=LPT1)
Returns: Result code (see Appendix I)
Netware C Library Chapter Nine - Print Services Page: 9-2
────────────────────────────────────────────────────────────────────────────────
9.1.5 FlushLPTCapture
This closes the current capture file of the default LPT device.
After this call is made, the default LPT device remains in a
captured state.
int FlushLPTCapture(void);
Returns: Result code (see Appendix I)
9.1.6 FlushSpecificLPTCapture
This closes the current capture file of a specific LPT device.
After this call is made, the specificied LPT device remains in a
captured state.
int FlushSpecificLPTCapture(int prnNo);
Input:
prnNo: LPT device number (0-2, 0=LPT1)
Returns: Result code (see Appendix I)
9.1.7 GetBannerUserName
Returns the user name that is printed on the banner page.
int GetBannerUserName(char *pointer);
Output:
pointer: 13-byte null terminated user name
Returns: Result code (see Appendix I)
9.1.8 GetLPTCaptureStatus
This returns whether the default capture is active.
int GetLPTCaptureStatus(void);
Returns: Capture Status.
0x00 Capture is not active
0xff Capture is active
9.1.9 GetDefaultLocalPrinter
This returns the number of the default LPT device.
int GetDefaultLocalPrinter(void);
Returns: Default LPT device number.
0x00 LPT1
0x01 LPT2
0x02 LPT3
Netware C Library Chapter Nine - Print Services Page: 9-3
────────────────────────────────────────────────────────────────────────────────
9.1.10 GetDefaultCaptureFlags
Returns the print job flags for the default LPT device.
int GetDefaultCaptureFlags(PRINT_CONTROL_DATA *reply);
Output:
reply: Structure containing flags.
See Appendix III.
Returns: Result code (see Appendix I)
9.1.11 GetPrinterStatus
This returns the current status of the specified server printer.
int GetPrinterStatus(int prnNo,byte *printerHalted,
byte *printerOffline,byte *formType,byte *targetPrinterNumber);
Input:
prnNo: Server printer number (0-4).
Output:
printerHalted: A value of 0x00 indicates that the printer
is active, and a value of 0xff if the
printer is stopped.
printerOffline: A value of 0x01 indicates the printer is
offline.
formType: This is the form type that is currently
in use.
targetPrinterNumber: This should be the same as the printer
number specified in prnNo, unless the
server console has rerouted the printer.
Returns: Result code (see Appendix I)
9.1.12 GetSpecificCaptureFlags
Returns the print job flags for the specified LPT device.
int GetSpecificCaptureFlags(int device,PRINT_CONTROL_DATA *pData);
Input:
device: LPT device number (0-2, 0=LPT1)
Output:
pData: Structure containing flags.
See Appendix III.
Returns: Result code (see Appendix I)
Netware C Library Chapter Nine - Print Services Page: 9-4
────────────────────────────────────────────────────────────────────────────────
9.1.13 SetBannerUserName
Sets the user name that is printed on the banner page. This applies
to local LPT devices.
int SetBannerUserName(char *pointer);
Input:
pointer: 13-byte null terminated user name.
Returns: Result code (see Appendix I)
9.1.14 SetCapturePrintQueue
Sets the target print queue for the next capture of the specified
device.
int SetCapturePrintQueue(int device,long queueID);
Input:
device: LPT device number (0-2, 0=LPT1)
queueID: This is the bindery object ID of the queue where
print jobs are to be sent.
Returns: Result code (see Appendix I)
9.1.15 SetDefaultLocalPrinter
This sets the default LPT device, for all default local LPT
capturing.
int SetDefaultLocalPrinter(int device);
Input:
device: LPT device number (0-2, 0=LPT1)
Returns: Result code (see Appendix I)
9.1.16 SetDefaultCaptureFlags
Sets the capture flags for the default LPT device.
int SetDefaultCaptureFlags(PRINT_CONTROL_DATA *flags);
Input:
flags: Structure containing flags.
See Appendix III.
Returns: Result code (see Appendix I)
Netware C Library Chapter Nine - Print Services Page: 9-5
────────────────────────────────────────────────────────────────────────────────
9.1.17 SetSpecificCaptureFlags
Sets the capture flags for the specified LPT device.
int SetSpecificCaptureFlags(int device,PRINT_CONTROL_DATA *flags);
Input:
device: LPT device number (0-2, 0=LPT1)
flags: Structure containing flags.
See Appendix III.
Returns: Result code (see Appendix I)
9.1.18 SpecifyCaptureFile
This creates a capture file for the next capture process.
int SpecifyCaptureFile(int directoryHandle,char *filename);
Input:
directoryHandle: An optional directory handle, pointing to an
entry in the servers Directory Handle Table.
If "filename" contains the full path name
then this must be 0x00.
filename: 256-byte null terminated file name. This can
either be a full path name, i.e.
VOLUME:DIR\..\DIR\FILE or a partial name
containing at least the terminal name of the
file.
Returns: Result code (see Appendix I)
9.1.19 StartLPTCapture
This starts the capture of the default LPT device.
int StartLPTCapture(void);
Returns: Result code (see Appendix I)
9.1.20 StartSpecificLPTCapture
This starts the capture of the specified LPT device.
int StartSpecificLPTCapture(int device);
Input:
device: LPT device number (0-2, 0=LPT1)
Returns: Result code (see Appendix I)
Netware C Library Chapter Ten - Synchronisation Services Page: 10-1
────────────────────────────────────────────────────────────────────────────────
10. Synchronisation Services
These services allow applications to control access to files and other
network resources. These are split into two categories: file/record
locking and semaphores. This document and associated library currently
only covers semaphores, file/record locking functions will be provided in
a future release.
10.1 Semaphores
A semaphore is a named location that has a value associated with it. The
name can be up to 127 bytes long and the value can be in the range -127 to
127. Semaphores are generally used to control access to resources on a
network.
Before an application can access a semaphore, it must first open it by
calling OpenSemaphore, if the semaphore does not already exist then it
will be automatically created by this call. OpenSemaphore must be passed
an initial value for the semaphore which will only be used if the
semaphore is to be created, this value is the number of processes that can
access the network resource at any one time and must be in the range 1 to
127. After opening the specified semaphore, the associated open count
will be incremented and the value returned to the caller.
When the application wishes to access the resource associated with the
semaphore, it must first call WaitOnSemaphore. When WaitOnSemaphore is
called, the value associated with the semaphore is decremented. If this
value is still positive, i.e. greater than or equal to zero, then a zero
response is returned indicating that the resource is available otherwise
the application will be placed in a queue and a wait will be performed for
the specified period. If the semaphore value should become positive
during the wait, i.e. another application has released it, then the wait
will be terminated and a zero response will be returned. If the semaphore
value is still negative at the end of the wait, then the application is
removed from the queue, the semaphore value will be incremented and a
failing response will be returned indicating that the resource is not
available.
After an application has finished with the resource, it must call
SignalSemaphore in order to increment the semaphore value.
Before the application terminates it must call CloseSemaphore in order to
decrement the open count associated with the semaphore. If this count
should become zero then the semaphore will be automatically deleted.
The current value and open count of a semaphore can be obtained by calling
ExamineSemaphore. The semaphore does not need to be opened by the
application in order to call this.
Netware C Library Chapter Ten - Synchronisation Services Page: 10-2
────────────────────────────────────────────────────────────────────────────────
10.2 Synchronisation Functions
10.2.1 CloseSemaphore
This decrements the semaphore's open count, if the count becomes
zero then the semaphore will be deleted.
int CloseSemaphore( long semaphoreHandle );
Input:
semaphoreHandle: Handle returned from the call to OpenSemaphore.
Returns: Result code (see Appendix I)
10.2.2 ExamineSemaphore
Returns the current open count and value of the specified semaphore.
int ExamineSemaphore( long semaphoreHandle,int *semaphoreValue,
word *openCount);
Input:
semaphoreHandle: Handle returned from the call to OpenSemaphore.
Output:
semaphoreValue: Current semaphore value, in the range -127 to
127. A positive value indicates that
applications can access the resource associated
with this semaphore, a negative value indicates
that there is currently a queue of processes
waiting for the semaphore to become free.
openCount: The current number of processes that have this
semaphore open.
Returns: Result code (see Appendix I)
10.2.3 OpenSemaphore
This opens/creates the specified semaphore.
int OpenSemaphore( char *semaphoreName,int initialValue,
long *semaphoreHandle,word *openCount);
Input:
semaphoreName: Name of the semaphore to be opened.
initialValue: The value to be given to the semaphore if it is
created. i.e. the number of applications that
can simultaneously access the resource that is
associated with the named semaphore.
Output:
semaphoreHandle: A handle to the semaphore.
openCount: The current number of processes that have this
semaphore open.
Returns: Result code (see Appendix I)
Netware C Library Chapter Ten - Synchronisation Services Page: 10-3
────────────────────────────────────────────────────────────────────────────────
10.2.4 SignalSemaphore
This increments the value of the specified semaphore.
int SignalSemaphore( long semaphoreHandle );
Input:
semaphoreHandle: Handle returned from the call to OpenSemaphore.
Returns: Result code (see Appendix I)
10.2.5 WaitOnSemaphore
This decrements the semaphore value. If the value becomes negative
then the call will wait for the specified length of time.
int WaitOnSemaphore( long semaphoreHandle , int timeoutLimit );
Input:
semaphoreHandle: Handle returned from the call to OpenSemaphore.
timeoutLimit: The length of time the process must wait if the
semaphore is not available. This is a number of
clock ticks, where 18.2 ticks = 1 second
approximately.
Returns: Result code (see Appendix I)
Netware C Library Chapter Eleven - Communication Services Page: 11-1
────────────────────────────────────────────────────────────────────────────────
11. Communication Services
These services allow applications to use the Netware Internetwork Packet
Exchange (IPX) and the Netware Sequenced Packet Exchange (SPX) protocols.
These protocols are based on the Xerox Network Systems (XNS) Internet
Transport Protocols.
Both IPX and SPX allow peer-to-peer communication. This means that all
communication is done directly between two or more workstations on the
internet, bypassing the file server.
Because nodes on an internet can communicate in various ways, the
International Standards Organisation (ISO) proposed a standard model
called the Open Systems Interconnection (OSI) model. The OSI model
basically consists of seven layers, which are: Physical, Data Link,
Network, Transport, Session, Presentation and Application. Each layer
provides services to the next higher layer. The IPX protocol maps onto
layer three (Network), which is concerned with packet addressing and
routing, and the SPX protocol maps onto layer four (Transport), which is
concerned with the guaranteed and sequenced delivery of packets.
11.1 IPX Protocol
IPX is known as a connectionless or datagram protocol, this means that
when IPX is used to communicate between two nodes on the network, no
connection is established. Therefore there is no guarantee that data sent
from one node will be received by the destination node.
There are two structures that are needed in order to use IPX, these are
the IPX packet and the Event Control Block (ECB). For every IPX packet
there is an associated ECB.
11.1.1 IPX Packet Structure
An IPX packet consists of a 30-byte header plus any number of data
fragments as long as the total length of the packet does not exceed 576
bytes. IPX does not use the data fragments, and so these can be
application defined, but the header, as defined in the file "nwipxspx.h",
is as follows:
typedef struct { byte network_number[4];
byte node_address[6];
nw_int socket_number;
} NETWORK_ADDR;
typedef struct { nw_int checksum;
nw_int length;
byte transport_control;
byte packet_type;
NETWORK_ADDR dest_addr;
NETWORK_ADDR srce_addr;
} IPX_HEADER;
All the fields with the exception of "packet_type" and "dest_addr" are set
automatically by IPX.
Netware C Library Chapter Eleven - Communication Services Page: 11-2
────────────────────────────────────────────────────────────────────────────────
For IPX "packet_type" should be set to either 0 or 4, but it can take the
following values:
0 Unknown packet type
1 Routing information packet
2 Echo packet
3 Error packet
4 Packet exchange packet
5 Sequenced packet protocol packet
16 Experimental protocol
17 Netware core protocol
18-31 Experimental protocols
The "dest_addr" field contains the network number and node address of the
destination node, along with the socket number that the destination is
listening on for this communication, see the definition of the
function IPX_OPEN_SOCKET for more information about sockets.
11.2 SPX Protocol
SPX is known as a connection-oriented protocol, this means that before a
packet can be sent a connection must be established between the source and
destination nodes. SPX automatically performs the tasks of guaranteeing
delivery of packets, sequencing of packets and the detection and
correction of errors.
Like IPX there are two structures that are needed in order to use SPX,
these are the SPX packet and the Event Control Block (ECB). For every SPX
packet there is an associated ECB.
11.2.1 SPX Packet Structure
An SPX packet consists of a 42-byte header plus any number of data
fragments as long as the total length of the packet does not exceed 576
bytes. SPX does not use the data fragments, and so these can be
application defined, but the header, as defined in the file "nwipxspx.h",
is as follows:
typedef struct { IPX_HEADER ipx;
byte connection_control;
byte datastream_type;
nw_int source_connection_id;
nw_int dest_connection_id;
nw_int sequence_number;
nw_int acknowledge_number;
nw_int allocation_number;
} SPX_HEADER;
The first 30 bytes have the same meaning as the IPX header, except that
the packet type field must be set to 5 to signify that it is an SPX
packet. The additional fields for SPX are defined as follows:
connection_control:
This field contains four flags that are used by SPX to control the
flow of data across the connection:
Netware C Library Chapter Eleven - Communication Services Page: 11-3
────────────────────────────────────────────────────────────────────────────────
Bits 7 6 5 4 3 2 1 0
- - - x - - - - End-of-Message
- - x - - - - - Attention
- x - - - - - - Acknowledgement-Required
x - - - - - - - System-Packet
End-of-Message:
This flag is set to signal an end of connection. SPX
ignores this bit and passes it on unchanged to the
destination.
Attention:
This flag is set if the packet is an attention packet.
SPX ignores this bit and passes it on unchanged to the
destination.
Acknowledgement-Required:
This bit is set by SPX if an acknowledgement packet is
required. SPX handles acknowledgement requests and
responses automatically.
System-Packet:
SPX sets this bit if the packet is a system packet.
These packets are used internally by SPX.
datastream_type:
This indicates the type of data that can be found in the packet. It
can take the following values:
0 to 253 User defined ( SPX ignores these values ).
254 End-of-Connection. This packet type is generated by
SPX when an SPXTerminateConnection call is issued.
255 End-of-Connection-Acknowledgement. This is sent by
SPX whenever a workstation receives an
End-of-Connection packet.
source_connection_id:
SPX sets this field to the SPX connection id of the source
workstation.
dest_connection_id:
SPX sets this field to the SPX connection id of the destination
workstation.
sequence_number:
SPX uses this field to identify and discard duplicate packets. It is
set and maintained by SPX.
Netware C Library Chapter Eleven - Communication Services Page: 11-4
────────────────────────────────────────────────────────────────────────────────
acknowledge_number:
SPX uses this field to indicate the sequence number of the next
packet SPX expects to receive.
allocation_number:
This is used internally by SPX, it contains the number of packets
sent but not yet acknowledged by the destination workstation.
11.3 Event Control Block (ECB)
This is a structure that contains details about the IPX/SPX packet,
particularly the number of fragments and the size and address of each one.
For a send ECB, IPX will collect together all the fragments that are
specified in the ECB into one buffer before transmitting the packet, and
for a receive ECB, IPX will distribute the received packet into the
appropriate addresses specified by the ECB. The ECB also contains the
completion code of the send or receive process.
11.3.1 ECB Structure
The ECB structure declared in "nwipxspx.h" contains only two fragments,
the first is for the IPX/SPX header and the second is for the users data.
The structure definition is as follows:
typedef struct { void _far *address;
word length;
} ECB_FRAGMENT;
typedef struct { void _far *link_address;
void (_far *esr)(void);
byte in_use;
byte completion_code;
nw_int socket_number;
byte IPX_workspace[4];
byte driver_workspace[12];
byte immediate_address[6];
word fragment_count;
ECB_FRAGMENT fragment[2];
} EVENT_CONTROL_BLOCK;
link_address:
This is maintained by IPX whilst the ECB is in use. When the ECB is
not in use then the application can use this field.
esr:
This contains the address of an application defined Event Service
Routine (ESR) that IPX will call when the send or receive event
finishes. IPX also maintains the in_use and completion_code fields,
so an application could simply poll these fields instead of using an
ESR. If no ESR is required then this field should be set to a null
pointer.
Netware C Library Chapter Eleven - Communication Services Page: 11-5
────────────────────────────────────────────────────────────────────────────────
in_use:
Whilst the ECB is in use, this field will contain a non-zero value.
Once IPX has finished with the ECB, i.e. the send or receive has
finished, then this value will be set to zero.
completion_code:
This field is set by IPX to indicate the result of the send or
receive event. This field is undefined whilst the in_use flag is
non-zero. The following completion codes can be reported:
Send-ECB: 0x00 Successful - The request was sent
0xfc Cancelled - The send request was cancelled
0xfd Malformed - The packet was malformed
0xfe Undelivered - The packet could not be delivered
0xff Hardware Failure - There has been a physical
hardware or network failure.
Listen-ECB: 0x00 Successful - A packet was received
0xfc Cancelled - The listen request was cancelled
0xfd Overflow - A packet was received, but the
fragment count in the ECB is zero, or the
available space specified in the ECB is not
large enough to hold the entire packet.
0xff Closed - The listening socket is not open.
Timer-ECB: 0x00 Successful
0xfc Cancelled - The timer event was cancelled.
socket_number:
This contains the number of the previously opened socket that is to
be associated with this ECB. This is held in high-low format, so
must be stored using the function NWintconvert, see section 1.7.
IPX_workspace:
This is reserved for use by IPX.
driver_workspace:
This is reserved for use by the network driver.
immediate_address:
This contains the address of the node to which the packet is to be
sent or from which it was received. If the node is not on the local
network then this will contain the address of an internetwork bridge.
fragment_count:
This contains the number of data fragments that are associated with
this ECB.
Netware C Library Chapter Eleven - Communication Services Page: 11-6
────────────────────────────────────────────────────────────────────────────────
fragment.address:
This contains the address of this fragment.
fragment.length:
This contains the length of this fragment.
Netware C Library Chapter Eleven - Communication Services Page: 11-7
────────────────────────────────────────────────────────────────────────────────
11.4 IPX Functions
The following function calls use two structures that are declared in the
header file "nwipxspx.h". These are:
typedef struct { byte network_number[4];
byte node_address[6];
} INTER_NETWORK_ADDR;
typedef struct { INTER_NETWORK_ADDR ina;
nw_int socket_number;
} NETWORK_ADDR;
11.4.1 IPXCancelEvent
This cancels an IPX/SPX event that is associated with a particular
ECB. A completion code will be returned in the cancelled ECB, but
the ESR wil not be actioned.
word IPXCancelEvent( EVENT_CONTROL_BLOCK *ecb );
Input:
ecb: Address of the ECB that is to be cancelled.
Returns: Result code (see Appendix I)
11.4.2 IPXCloseSocket
This closes a socket that was previously opened by IPXOpenSocket.
Any events that are associated with the socket will be cancelled.
void IPXCloseSocket( word socketNumber );
Input:
socketNumber: Number of the socket to close.
11.4.3 IPXDisconnectFromTarget
An application uses this function to notify a listening node that no
more IPX packets are going to be sent.
void IPXDisconnectFromTarget( NETWORK_ADDR *networkAddress );
Input:
networkAddress: Full network address of the node with which the
connection is being terminated.
Netware C Library Chapter Eleven - Communication Services Page: 11-8
────────────────────────────────────────────────────────────────────────────────
11.4.4 IPXGetInternetworkAddress
This returns the network number and node address of the calling
workstation.
void IPXGetInternetworkAddress(INTER_NETWORK_ADDR *networkAddress);
Output:
networkAddress: Network number and node address of the calling
workstation.
11.4.5 IPXGetIntervalMarker
This returns the number of clock ticks that have occured in the
requesting workstation since IPX was loaded. Approximately 18.2
clock ticks occur every second.
word IPXGetIntervalMarker( void );
Returns: The number of clock ticks since IPX was loaded.
11.4.6 IPXGetLocalTarget
This returns the information that is required for the
immediate_address field in an IPXSendPacket ECB. The returned node
address is either the address of the nearest bridge, if the packet
must cross a bridge, or the address of the destination workstation.
word IPXGetLocalTarget( INTER_NETWORK_ADDR *networkAddress ,
byte *immediateAddress,
word *transportTime );
Input:
networkAddress: The network number and node address of the
destination workstation.
Output:
immediateAddress: The routing address of the destination. This
must be placed in the immediate_address field
of a send ECB.
transportTime: This is the number of timer ticks that a packet
will take in order to get to the destination.
Returns: Result code (see Appendix I)
11.4.7 IPXInitialise
This initialises the areas used by the IPX library functions. It
must be the first IPX function that is called.
word IPXInitialise( void );
Returns: 0 IPX is installed
-1 IPX is not installed
Netware C Library Chapter Eleven - Communication Services Page: 11-9
────────────────────────────────────────────────────────────────────────────────
11.4.8 IPXListenForPacket
One or more calls to this function must be made in order to give IPX
the address of a buffer in which the next incoming message packet
must be placed. Each call gives IPX an ECB that is then placed in a
pool of listening ECBs. An immediate return to the calling program
is made after each call.
When IPX receives a packet one of the listening ECBs that has a
matching socket number is selected. The ECBs are selected in a
random order.
word IPXListenForPacket( EVENT_CONTROL_BLOCK *ecb );
Input:
ecb: Address of the listening ECB.
Returns: Result code (see Appendix I)
11.4.9 IPXOpenSocket
This function opens a socket that can then be used by either IPX or
SPX, but not by both simultaneously.
word IPXOpenSocket( word *socketNumber, byte longevity );
Input:
socketNumber: The number of the socket to open. A value of zero
will cause IPX to generate a socket number in the
range 0x4000 to 0x8000.
Socket numbers in the range 0x0000 to 0x0bb9 and
0x8001 to 0xffff are reserved and must not be
used.
longevity: This specifies whether the socket is short-lived
(0x00) or long-lived (0xff). A short-lived socket
is closed automatically when the application
terminates or when a call to IPXCloseSocket is
made, long-lived sockets must be closed explicitly
by calling IPXCloseSocket.
Output:
socketNumber: Returns the actual socket number that was opened.
Returns: Result code (see Appendix I)
11.4.10 IPXRelinquishControl
This must be called at periodic intervals in order to give IPX time
to process events.
void IPXRelinquishControl( void );
Netware C Library Chapter Eleven - Communication Services Page: 11-10
────────────────────────────────────────────────────────────────────────────────
11.4.11 IPXScheduleIPXEvent
This function passes an ECB to IPX for processing at a later time.
IPX returns to the application immediately after this call and waits
in the background until the delay period has expired.
void IPXScheduleIPXEvent( EVENT_CONTROL_BLOCK *ecb ,
word delayTicks );
Input:
ecb: Address of the ECB to be processed.
delayTicks: Number of clock ticks that IPX must wait for before
processing the ECB. Approximately 18.2 clock ticks
occur every second.
11.4.12 IPXSendPacket
This function instructs IPX to send a data packet.
void IPXSendPacket( EVENT_CONTROL_BLOCK *ecb );
Input:
ecb: Address of the ECB containing the routing information
and the data that is to be used in constructing the
packet.
Netware C Library Chapter Eleven - Communication Services Page: 11-11
────────────────────────────────────────────────────────────────────────────────
11.5 SPX Functions
11.5.1 SPXAbortConnection
This function aborts an SPX connection by abnormally terminating any
outstanding SPX events. No notification of the termination is sent
to the other station.
void SPXAbortConnection( word connectionID );
Input:
connectionID: SPX connection id of the connection to be broken.
11.5.2 SPXEstablishConnection
This function creates a connection between the calling station and
the specified destination station. The destination station must
have issued an SPXListenForConnection.
Before issuing this call, the application must have created at least
two listen ECBs and passed them to SPX by calling the function
SPXListenForSequencedPacket. Once the establish connection packet
has been sent, then SPX will use one of the listen ECBs to receive
an acknowledgement packet from the destination station.
word SPXEstablishConnection( word retryCount, word watchdogFlag ,
EVENT_CONTROL_BLOCK *ecb ,word *connectionID );
Input:
retryCount: This specifies how many times SPX will resend an
unacknowledged packet before giving up. A value of
zero indicates that SPX should use its internal
default value.
watchdogFlag: This can have the value of 0 (watchdog disabled)
or 1 (watchdog enabled). If watchdog is enabled
then the SPX watchdog process will monitor the SPX
connection to ensure that it is functioning. If
watchdog process determines that a connection has
failed, then it will use one of the outstanding
listen ECBs to report the failure.
ecb: Address of the ECB containing the information that
is required in order to establish the connection.
The socket number, fragment count and fragment
descriptor fields in the ECB must be setup. The
fragment count field must be 1, and the fragment
descriptor field msut point to a 42-byte SPX
packet header. The SPX packet header's destination
network node and socket number must be initialised
to their relevant values.
Output:
connectionID: The returned SPX connection id.
Returns: Result code (see Appendix I)
Netware C Library Chapter Eleven - Communication Services Page: 11-12
────────────────────────────────────────────────────────────────────────────────
11.5.3 SPXGetConnectionStatus
This function returns the status of the specified SPX connection.
word SPXGetConnectionStatus( word connectionID ,
SPX_CONNECTION_STATUS *connectionStatus );
Input:
connectionID: SPX connection id.
Output:
connectionStatus: Structure containing the status of the SPX
connection. It is declared in the header file
"nwipxspx.h". See Appendix III.
Returns: Result code (see Appendix I)
11.5.4 SPXInitialise
This function determines whether SPX is installed.
int SPXInitialise(byte *majorVersion,byte *minorVersion,
word *maxConnections,word *availableConnections );
Output:
majorVersion: Major revision number of SPX.
minorVersion: Minor revision number of SPX.
maxConnections: Maximum number of SPX connections that
are supported.
availableConnections: The number of SPX connections that are
available.
Returns: 0 SPX is installed
-1 SPX is not installed
11.5.5 SPXListenForConnection
This function instructs SPX to expect a request from another station
to establish a connection. SPX returns immediately to the caller,
and waits for the request packet in background.
void SPXListenForConnection( word retryCount, word watchdogFlag ,
EVENT_CONTROL_BLOCK *ecb );
Input:
retryCount: This specifies how many times SPX will resend an
unacknowledged packet before giving up. A value of
zero indicates that SPX should use its internal
default value.
watchdogFlag: This can have the value of 0 (watchdog disabled)
or 1 (watchdog enabled). If watchdog is enabled
then the SPX watchdog process will monitor the SPX
connection to ensure that it is functioning. If
watchdog process determines that a connection has
failed, then it will use one of the outstanding
listen ECBs to report the failure.
Netware C Library Chapter Eleven - Communication Services Page: 11-13
────────────────────────────────────────────────────────────────────────────────
ecb: Address of the ECB containing the information that
is required in order to establish the connection.
The socket number, fragment count and fragment
descriptor fields in the ECB must be setup. The
fragment count field must be 1, and the fragment
descriptor field msut point to a 42-byte SPX
packet header.
When a connection is made, then SPX will return a
connection ID in the first two bytes of the
IPX_workspace field of the ECB associated with the
SPXListenForConnection call, the driver_workspace
field will also contain the address of the partner
node.
11.5.6 SPXListenForSequencedPacket
This function gives SPX an ECB and a packet buffer it can use when
it receives an incoming data packet. SPX will place each ECB and
buffer in a pool and will then return immediately to the caller. On
receiving a data packet, SPX will select one of the available
listening ECBs for the relevant socket number.
void SPXListenForSequencedPacket( EVENT_CONTROL_BLOCK *ecb );
Input:
ecb: Address of the listening ECB.
The ecb should be initialised as follows:
fragment_count = 2
fragment[0].address = Address of SPX header
fragment[0].length = 42
fragment[1].address = Address of data buffer
fragment[1].length = Length of data buffer
Netware C Library Chapter Eleven - Communication Services Page: 11-14
────────────────────────────────────────────────────────────────────────────────
11.5.7 SPXSendSequencedPacket
This function instructs SPX to send a data packet to the other
station associated with the connection. The actual send operation
is performed in the background.
void SPXSendSequencedPacket( word connectionID,
EVENT_CONTROL_BLOCK *ecb );
Input:
connectionID: SPX connection id.
ecb: Address of the send ecb.
The ecb should be initialised as follows:
fragment_count = 2
fragment[0].address = Address of SPX header
fragment[0].length = 42
fragment[1].address = Address of data buffer
fragment[1].length = Length of data buffer
11.5.8 SPXTerminateConnection
This function terminates an SPX connection. The termination
operation is performed in the background. A termination packet will
be sent to the partner station.
void SPXTerminateConnection( word connectionID ,
EVENT_CONTROL_BLOCK *ecb );
Input:
connectionID: SPX connection id.
ecb: Address of the ecb.
The ecb should be initialised as follows:
fragment_count = 1
fragment[0].address = Address of SPX header
fragment[0].length = 42
Netware C Library Appendix I - Netware Result Codes Page: A1-1
────────────────────────────────────────────────────────────────────────────────
╔════╤═════════════════════════════════╦═════╤═══════════════════════════════╗
║Hex │Meaning ║ Hex │Meaning ║
╠════╪═════════════════════════════════╬═════╪═══════════════════════════════╣
║00h │Action Successful ║ 9Ah │Renaming Across Volumes ║
║ │Server Not In Use ║ 9Bh │Bad Directory Handle ║
║ │TTS Not Available ║ 9Ch │Invalid Path ║
║01h │Server In Use ║ │No more Trustees ║
║ │Semaphore Overflow ║ 9Dh │No More Directory Handles ║
║ │TTS Available ║ 9Eh │Invalid Filename ║
║02h │DOS File Not Found ║ 9Fh │Directory Active ║
║03h │DOS Path Not Found ║ A0h │Directory Not Empty ║
║04h │DOS Too Many Open Files ║ A1h │Directory IO Error ║
║05h │DOS Access Denied ║ A2h │Read File With Record Locked ║
║06h │DOS Invalid File Handle ║ BBh │No Netware shell loaded ║
║07h │DOS Memory Blocks Destroyed ║ C0h │No Account Privileges ║
║08h │DOS Insufficient Memory ║ C1h │Login Denied - ║
║09h │DOS Invalid Memory Block Address ║ │No Account Balance ║
║0Ah │DOS Invalid Environment ║ C2h │Account Credit limit Exceeded ║
║0Bh │DOS Invalid Format ║ │Login Denied - No credit ║
║0Ch │DOS Invalid Access Code ║ C3h │Account - Too many Holds ║
║0Dh │DOS Invalid Data ║ C5h │Intruder Detection Lock ║
║0Fh │DOS Invalid Drive Specified ║ C6h │Not Console Operator ║
║10h │DOS Attempt To Delete Current Dir║ D0h │Queue Error ║
║11h │DOS Not Same Device ║ D1h │No Queue ║
║12h │DOS No More Files ║ D2h │No Queue Server ║
║20h │DOS Sharing Violation ║ D3h │No Queue Rights ║
║21h │DOS Lock Violation ║ D4h │Queue Full ║
║80h │File In User Error ║ D5h │No Queue Job ║
║81h │No More File Handles ║ D6h │No Job Rights ║
║82h │No Open Privileges ║ D7h │Password Not Unique ║
║83h │IO Error Network Disk ║ │Queue Servicing ║
║84h │No Create Privileges ║ D8h │Password Too Short ║
║85h │No Delete Privileges ║ │Queue Not Active ║
║86h │Create File Exists Read Only ║ D9h │Login Denied - No connection ║
║87h │Wild Cards in Create File Name ║ │Station Not Server ║
║88h │Invalid File Handle ║ DAh │Unauthorized login time - ║
║89h │No Search Privileges ║ │Queue Halted ║
║8Ah │No Delete Privileges ║ DBh │Unauthorized login station - ║
║8Bh │No Rename Privileges ║ │Max Queue Servers ║
║8Ch │No Modify Privileges ║ DCh │Account Disabled ║
║8Dh │Some Files Affected In Use ║ DEh │Password has expired - No Grace║
║8Eh │No Files Affected In Use ║ DFh │Password has expired ║
║8Fh │Some Files Affected Read Only ║ E8h │Not Item Property - ║
║90h │No Files Affected Read Only ║ │Write Property to Group ║
║91h │Some Files Renamed - Name Exists ║ E9h │Member Already Exists ║
║92h │No Files Renamed - Name Exists ║ EAh │No Such Member ║
║93h │No Read Privileges ║ EBh │Not Group Property ║
║94h │No Write Privileges or Read Only ║ ECh │No Such Segment ║
║95h │File Detached ║ EDh │Property Already Exists ║
║96h │Server Out Of Memory ║ EEh │Object Already Exists ║
║ │Out Of Dynamic Workspace ║ EFh │Invalid Name ║
║97h │No Disk Space for Spool File ║ F0h │Wild Card Not Allowed ║
║98h │Volume Does Not Exist ║ F1h │Invalid Bindery Security ║
║99h │Directory Full ║ F2h │No Object Read Privilege ║
╚════╧═════════════════════════════════╩═════╧═══════════════════════════════╝
Netware C Library Appendix I - Netware Result Codes Page: A1-2
────────────────────────────────────────────────────────────────────────────────
╔════╤═════════════════════════════════╦═════╤═══════════════════════════════╗
║Hex │Meaning ║ Hex │Meaning ║
╠════╪═════════════════════════════════╬═════╪═══════════════════════════════╣
║F3h │No Object Rename Privilege ║ FFh │Bad Printer Error ║
║F4h │No Object Delete Privilege ║ │Bad Record Offset ║
║F5h │No Object Create Privilege ║ │Close FCB Error ║
║F6h │No Property Delete Privilege ║ │File Extension Error ║
║ │Not Same Local Drive ║ │File Name Error ║
║F7h │No Property Create Privilege ║ │Hardware Failure ║
║ │Target Drive Not Local ║ │Invalid Drive Number ║
║F8h │Already Attached To Server ║ │Invalid Initial Semaphore Value║
║ │No Property Write Privilege ║ │Invalid Semaphore Handle ║
║ │Not Attached To Server ║ │IO Bound Error ║
║F9h │No Free Connection Slots ║ │No Files Found Error ║
║ │No Property Read Privilege ║ │No Response From Server ║
║FAh │No More Server Slots ║ │No Such Object ║
║ │Temporary Remap Error ║ │Bad Password ║
║FBh │Invalid Parameters ║ │Path Not Locatable ║
║ │No Such Property ║ │Queue Full Error ║
║ │Unknown Request ║ │Request Not Outstanding ║
║FCh │Unknown File Server ║ │Transaction Not Yet Written ║
║ │Message Queue Full ║ │No More Matching Files ║
║ │No Such Object ║ │Bindery Failure ║
║FDh │Bad Station Number ║ │Explicit Transaction Active ║
║ │Unknown Request ║ │No Explicit Transaction Active ║
║ │Field Already Locked ║ │No Record Found ║
║ │TTS Disabled ║ │Output Buffer Full ║
║FEh │Bindery Locked ║ │ ║
║ │Directory Locked ║ │ ║
║ │Invalid Semaphore Name Length ║ │ ║
║ │Server Bindery Locked ║ │ ║
║ │Spool Directory Error ║ │ ║
║ │Supervisor has disabled login ║ │ ║
║ │Timeout Failure ║ │ ║
║ │Transaction ends Record Lock ║ │ ║
║ │Implicit Transaction Active ║ │ ║
╚════╧═════════════════════════════════╩═════╧═══════════════════════════════╝
Netware C Library Appendix II - Function List Page: A2-1
────────────────────────────────────────────────────────────────────────────────
AbortServicingQueueJobAndFile Queue Management Services 5.1.1
AddBinderyObjectToSet Bindery Services 2.3.1
AddTrusteeToDirectory Directory Services 8.6.1
AddUserDiskSpaceRestriction Directory Services 8.6.2
AllocPermanentDirectoryHandle Directory Services 8.6.3
AllocTemporaryDirectoryHandle Directory Services 8.6.4
AttachQueueServerToQueue Queue Management Services 5.1.2
AttachToFileServer Connection Services 4.3.1
BroadcastToConsole Message Services 6.1.1
CancelLPTCapture Print Services 9.1.1
CancelSpecificLPTCapture Print Services 9.1.2
ChangeBinderyObjectPassword Bindery Services 2.3.2
ChangeBinderyObjectSecurity Bindery Services 2.3.3
ChangePropertySecurity Bindery Services 2.3.4
ChangeQueueJobEntry Queue Management Services 5.1.3
ChangeQueueJobPosition Queue Management Services 5.1.4
ChangeToClientRights Queue Management Services 5.1.5
CheckConsolePrivileges File Server Services 3.1.1
CheckPipeStatus Message Services 6.1.2
ClearConnectionNumber File Server Services 3.1.2
CloseBindery Bindery Services 2.3.5
CloseFileAndAbortQueueJob Queue Management Services 5.1.7
CloseFileAndStartQueueJob Queue Management Services 5.1.8
CloseMessagePipe Message Services 6.1.3
CloseSemaphore Synchronisation Services 10.2.1
ConvertPathToDirectoryEntry File Server Services 3.1.3
CreateBinderyObject Bindery Services 2.3.6
CreateDirectory Directory Services 8.6.5
CreateProperty Bindery Services 2.3.7
CreateQueue Queue Management Services 5.1.6
CreateQueueJobAndFile Queue Management Services 5.1.9
DeallocateDirectoryHandle Directory Services 8.6.6
DeleteBinderyObject Bindery Services 2.3.9
DeleteBinderyObjectFromSet Bindery Services 2.3.8
DeleteDirectory Directory Services 8.6.7
DeleteFakeRoot Directory Services 8.6.8
DeleteProperty Bindery Services 2.3.10
DeleteTrusteeFromDirectory Directory Services 8.6.9
DestroyQueue Queue Management Services 5.1.10
DetachFromFileServer Connection Services 4.3.2
DetachQueueServerFromQueue Queue Management Services 5.1.11
DisableFileServerLogin File Server Services 3.1.4
DisableTransactionTracking File Server Services 3.1.5
DownFileServer File Server Services 3.1.6
EnableFileServerLogin File Server Services 3.1.7
EnableTransactionTracking File Server Services 3.1.8
EndLPTCapture Print Services 9.1.3
EndOfJob Workstation Services 4.4.1
EndSpecificLPTCapture Print Services 9.1.4
EnterLoginArea Connection Services 4.3.3
EraseFiles File Services 7.5.1
ExamineSemaphore Synchronisation Services 10.2.2
FileServerFileCopy File Services 7.5.2
FinishServicingQueueJobAndFile Queue Management Services 5.1.12
FlushLPTCapture Print Services 9.1.5
FlushSpecificLPTCapture Print Services 9.1.6
Netware C Library Appendix II - Function List Page: A2-2
────────────────────────────────────────────────────────────────────────────────
GetBannerUserName Print Services 9.1.7
GetBinderyAccessLevel Bindery Services 2.3.11
GetBinderyObjectDiskSpaceLeft File Server Services 3.1.9
GetBinderyObjectID Bindery Services 2.3.12
GetBinderyObjectName Bindery Services 2.3.13
GetBroadcastMessage Message Services 6.1.4
GetBroadcastMode Message Services 6.1.5
GetConnectionIDTable Workstation Services 4.4.2
GetConnectionInformation Connection Services 4.3.4
GetConnectionNumber Connection Services 4.3.5
GetConnectionsOpenFiles File Server Services 3.1.10
GetConnectionsUsageStatistics File Server Services 3.1.11
GetCurrentDirectory Directory Services 8.6.10
GetDefaultCaptureFlags Print Services 9.1.10
GetDefaultConnectionID Workstation Services 4.4.3
GetDefaultLocalPrinter Print Services 9.1.9
GetDirectoryHandle Directory Services 8.6.11
GetDirectoryPath Directory Services 8.6.12
GetDiskCacheStatistics File Server Services 3.1.12
GetDiskUtilisation File Server Services 3.1.13
GetDriveConnectionID Workstation Services 4.4.4
GetDriveFlagTable Workstation Services 4.4.5
GetDriveHandleTable Workstation Services 4.4.6
GetEffectiveDirectoryRights Directory Services 8.6.13
GetFileServerDateTime File Server Services 3.1.14
GetFileServerInformation File Server Services 3.1.15
GetFileServerLoginStatus File Server Services 3.1.16
GetFileServerName Workstation Services 4.4.7
GetFileServerTable Workstation Services 4.4.7
GetInternetAddress Connection Services 4.3.6
GetLPTCaptureStatus Print Services 9.1.8
GetNetwareShellVersion Workstation Services 4.4.8
GetNetworkSerialNumber File Server Services 3.1.17
GetNumberOfLocalDrives Workstation Services 4.4.9
GetObjectConnectionNumbers Connection Services 4.3.7
GetPathFromDirectoryEntry File Server Services 3.1.18
GetPersonalMessage Message Services 6.1.6
GetPhysicalDiskStatistics File Server Services 3.1.19
GetPreferredConnectionID Workstation Services 4.4.10
GetPrimaryConnectionID Workstation Services 4.4.11
GetPrinterStatus Print Services 9.1.11
GetQueueJobList Queue Management Services 5.1.13
GetQueueJobsFileSize Queue Management Services 5.1.14
GetSemaphoreInformation File Server Services 3.1.20
GetServerConnectionID Workstation Services 4.4.12
GetSpecificCaptureFlags Print Services 9.1.12
GetStationAddress Connection Services 4.3.8
GetVolumeInformation Directory Services 8.6.14
GetVolumeInfoWithHandle Directory Services 8.6.15
GetVolumeInfoWithNumber Directory Services 8.6.16
GetVolumeName Directory Services 8.6.17
GetVolumeNumber Directory Services 8.6.18
IPXCancelEvent Communication Services 11.4.1
IPXCloseSocket Communication Services 11.4.2
IPXDisconnectFromTarget Communication Services 11.4.3
IPXGetInternetworkAddress Communication Services 11.4.4
Netware C Library Appendix II - Function List Page: A2-3
────────────────────────────────────────────────────────────────────────────────
IPXGetIntervalMarker Communication Services 11.4.5
IPXGetLocalTarget Communication Services 11.4.6
IPXInitialise Communication Services 11.4.7
IPXListenForPacket Communication Services 11.4.8
IPXOpenSocket Communication Services 11.4.9
IPXRelinquishControl Communication Services 11.4.10
IPXScheduleIPXEvent Communication Services 11.4.11
IPXSendPacket Communication Services 11.4.12
IsBinderyObjectInSet Bindery Services 2.3.14
IsShellLoaded Workstation Services 4.4.13
LoginToFileServer Connection Services 4.3.9
LogNetworkMessage Message Services 6.1.7
Logout Connection Services 4.3.11
LogoutFromFileServer Connection Services 4.3.10
MapFakeRoot Directory Services 8.6.19
ModifyMaximumRightsMask Directory Services 8.6.20
OpenBindery Bindery Services 2.3.15
OpenMessagePipe Message Services 6.1.8
OpenSemaphore Synchronisation Services 10.2.3
PurgeAllErasedFiles File Services 7.5.3
PurgeErasedFiles File Services 7.5.4
ReadPropertyValue Bindery Services 2.3.16
ReadQueueCurrentStatus Queue Management Services 5.1.15
ReadQueueJobEntry Queue Management Services 5.1.16
ReadQueueServerCurrentStatus Queue Management Services 5.1.17
RemoveJobFromQueue Queue Management Services 5.1.18
RenameBinderyObject Bindery Services 2.3.17
RenameDirectory Directory Services 8.6.21
RestoreDirectoryHandle Directory Services 8.6.22
RestoreQueueServerRights Queue Management Services 5.1.19
SaveDirectoryHandle Directory Services 8.6.23
ScanBinderyObject Bindery Services 2.3.18
ScanBinderyObjectTrusteePaths Directory Services 8.6.24
ScanDirectoryForTrustees Directory Services 8.6.25
ScanDirectoryInformation Directory Services 8.6.26
ScanFileInformation File Services 7.5.5
ScanProperty Bindery Services 2.3.19
SendBroadcastMessage Message Services 6.1.9
SendConsoleBroadcast File Server Services 3.1.21
SendPersonalMessage Message Services 6.1.10
ServiceQueueJobAndOpenFile Queue Management Services 5.1.20
SetBannerUserName Print Services 9.1.13
SetBroadcastMode Message Services 6.1.11
SetCapturePrintQueue Print Services 9.1.14
SetDefaultCaptureFlags Print Services 9.1.16
SetDefaultLocalPrinter Print Services 9.1.15
SetDirectoryHandle Directory Services 8.6.27
SetDirectoryInformation Directory Services 8.6.28
SetEndofJobStatus Workstation Services 4.4.14
SetFileInformation File Services 7.5.6
SetNWErrorMode Workstation Services 4.4.15
SetPreferredConnectionID Workstation Services 4.4.16
SetPrimaryConnectionID Workstation Services 4.4.17
SetQueueCurrentStatus Queue Management Services 5.1.21
SetQueueServerCurrentStatus Queue Management Services 5.1.22
SetSpecificCaptureFlags Print Services 9.1.17
Netware C Library Appendix II - Function List Page: A2-4
────────────────────────────────────────────────────────────────────────────────
SignalSemaphore Synchronisation Services 10.2.4
SpecifyCaptureFile Print Services 9.1.18
SPXAbortConnection Communication Services 11.5.1
SPXEstablishConnection Communication Services 11.5.2
SPXGetConnectionStatus Communication Services 11.5.3
SPXInitialise Communication Services 11.5.4
SPXListenForConnection Communication Services 11.5.5
SPXListenForSequencedPacket Communication Services 11.5.6
SPXSendSequencedPacket Communication Services 11.5.7
SPXTerminateConnection Communication Services 11.5.8
StartLPTCapture Print Services 9.1.19
StartSpecificLPTCapture Print Services 9.1.20
VerifyBinderyObjectPassword Bindery Services 2.3.20
WaitOnSemaphore Synchronisation Services 10.2.5
WritePropertyValue Bindery Services 2.3.21
Netware C Library Appendix III - Data Structures Page: A3-1
────────────────────────────────────────────────────────────────────────────────
These are the structures that are used by some of the Netware calls.
All the structures are declared in the header files provided with the
libraries.
A3.1 CONNECTION_ID_TABLE
This is used by GetConnectionIDTable in the Workstation Services.
typedef struct { byte slot_in_use;
byte servers_order_number;
byte servers_network_number[4];
byte physical_node_address[6];
int socket_number;
word receive_timeout;
byte routers_physical_node_address[6];
byte packet_sequence_number;
byte connection_number;
byte connection_status;
word maximum_time_out;
word connection_word;
byte major_server_version;
byte server_flags;
byte minor_server_version; } CONNECTION_ID_TABLE;
slot_in_use: A zero value indicates that this slot is
not in use, possible non-zero values are:
0xe0 = AES Temporary Indicator
0xf8 = IPX in critical process
0xfa = Processing
0xfb = Holding (in processing after
an event occurred)
0xfc = AES Waiting
0xfd = Waiting
0xfe = Receiving
0xff = Sending
servers_order_number: This is the order number assigned to the
corresponding server. The server with the
lowest network/node address has the lowest
order number. This will be a value 1 - 8.
servers_network_number: This identifies the network which the file
server is attached. If the server is
attached to more than one LAN then this
will always be for the servers LAN A.
physical_node_address: This is the address of the servers LAN
board.
socket_number: The socket the shell uses for communicating
with the server.
receive_timeout: How long the shell should wait before
resending an unanswered request. This is
adjusted dynamically by the shell, but will
never exceed the value in maximum_time_out.
routers_physical_node_address: This is the address of the preferred bridge
to route requests through, if it is not a
direct connection.
packet_sequence_number: This is used as a packet ID to check that
Netware C Library Appendix III - Data Structures Page: A3-2
────────────────────────────────────────────────────────────────────────────────
the reply received is answering the last
request.
connection_number: This corresponds to the entry in the file
servers connection table.
0xff = No Connection.
connection_status: This is the status of the connection.
0x00 = Connection functioning
maximum_time_out: This is the maximum length of time that
the shell should wait before resending
an unanswered request.
connection_word: 2-byte connection number, use this instead
of connection_number.
major_server_version: Major version number, less 2, of the
corresponding server.
server_flags: Low order bit will be set if burst mode is
enabled.
minor_server_version: Minor version number of the corresponding
server.
Netware C Library Appendix III - Data Structures Page: A3-3
────────────────────────────────────────────────────────────────────────────────
A3.2 DISK_CACHE_STATISTICS
This is used by GetDiskCacheStatistics in the File Server Environment
Services.
typedef struct { long system_elapsed_time;
int cache_buffer_count;
int cache_buffer_size;
int dirty_cache_buffers;
long cache_read_requests;
long cache_write_requests;
long cache_hits;
long cache_misses;
long physical_read_requests;
long physical_write_requests;
int physical_read_errors;
int physical_write_errors;
long cache_get_requests;
long cache_full_write_requests;
long cache_partial_write_requests;
long background_dirty_writes;
long background_aged_writes;
long total_cache_writes;
long cache_allocations;
int thrashing_count;
int LRU_block_was_dirty;
int read_beyond_write;
int fragmented_write_occurred;
int cache_hit_unavail_block;
int cache_block_scrapped; } DISK_CACHE_STATISTICS;
system_elapsed_time: This is the number of clock ticks, since the
server was loaded. Where 18.2 clock ticks =
1 second approximately. When this reaches
0xffffffff it wraps back to zero.
cache_buffer_count: The number of cache buffers in the server.
cache_buffer_size: Number of bytes in a cache buffer.
dirty_cache_buffers: Number of buffers containing data that has
not yet been written to disk.
cache_read_requests: Number of times the cache software was asked
to read some data.
cache_write_requests: Number of times the cache software was asked
to write some data.
cache_hits: Number of times cache requests were available
in existing cache blocks.
cache_misses: Number of times cache requests were not
available in cache blocks.
physical_read_requests: Number of actual reads on the disk the cache
software actioned.
physical_write_requests: Number of actual writes to the disk the cache
software actioned.
physical_read_errors: Number of errors the cache software received
whilst reading from the disk.
physical_write_errors: Number of errors the cache software received
whilst writing to the disk.
cache_get_requests: The number of times the cache software was
Netware C Library Appendix III - Data Structures Page: A3-4
────────────────────────────────────────────────────────────────────────────────
asked to read information from the disk.
cache_full_write_requests: The number of times the cache software was
told to write information that exactly
filled one or more sectors.
cache_partial_write_requests:
The number of times the cache software was
told to write information that didn't exactly
fill one or more sectors, this requires a
disk pre-read.
background_dirty_writes: The number of times that a whole cache block
was completely written to a disk.
background_aged_writes: Number of times a partially filled cache
block was written to a disk, because it had
not been accessed for a period of time.
total_cache_writes: Total number of cache buffers written to disk.
cache_allocations: Number of times a cache block was allocated
for use.
thrashing_count: Number of times a cache block was not
available when a block allocation was
requested.
LRU_block_was_dirty: Number of times the least recently used (LRU)
cache block algorithm reclaimed a dirty cache
block.
read_beyond_write: Number of times a file read request was made
when file writes had not yet filled the cache
block.
fragmented_write_occurred: Number of dirty cache blocks that contained
non-contiguous sectors of information were
written, and the skipped sectors were not
pre-read from the disk, this requires
multiple disk writes.
cache_hit_unavail_block: Number of cache requests that could be
serviced from an available cache block, but
the cache buffer could not be used, because
it was in the process of being written to or
read from the disk.
cache_block_scrapped: The number of times a cache blocked is
scrapped. This is due to the process going to
sleep whilst it is waiting for a spare cache
block, but when it wakes the data it was
requesting has been read into another cache
block by another process. This process has
to then scrap the cache block it was waiting
for and use the block that already contains
the data.
Netware C Library Appendix III - Data Structures Page: A3-5
────────────────────────────────────────────────────────────────────────────────
A3.3 FILE_SERVER_INFO
This is used by GetFileServerInformation in the File Server Environment
Services.
typedef struct { char server_name[48];
byte netware_version;
byte netware_subversion;
int connections_supported;
int connections_in_use;
int max_connected_volumes;
byte os_revision;
byte SFT_level;
byte TTS_level;
int peak_connections_used;
byte accounting_version;
byte VAP_version;
byte queuing_version;
byte print_server_version;
byte virtual_console_version;
byte security_restrictions_level;
byte internet_bridge_version;
byte reserved[60]; } FILE_SERVER_INFO;
server_name[48]: 48-byte null terminated name of the server.
netware_version: Version of Netware (1-255).
netware_subversion: Sub-version of Netware (0-99).
connections_supported: Number of connections supported.
connections_in_use: Number of connections currently in use.
max_connected_volumes: Maximum number of volumes on the server.
os_revision: The revision number of the Operating System.
SFT_level: System Fault Tolerance level.
TTS_level: Transaction Tracking System level.
peak_connections_used: Maximum number of connections that have been
made since the server was loaded.
accounting_version: The accounting version that is being used.
VAP_version: The Value Added Process version number.
queuing_version: The Queuing version number.
print_server_version: The Print Server version number.
virtual_console_version: The Virtual Console version number.
security_restrictions_level:
The security restrictions level.
internet_bridge_version: The Internetwork Bridge version number.
reserved[60]: Currently undefined.
Netware C Library Appendix III - Data Structures Page: A3-6
────────────────────────────────────────────────────────────────────────────────
A3.4 OPEN_FILES_INFO
typedef struct { word task_number;
dword parent_dir_entry;
dword directory_entry;
byte lock_flag;
byte access_flag;
byte lock_type;
byte name_space;
byte volume_number;
byte reserved;
char file_name[14]; } OPEN_FILES_INFO;
taskNumber: The task number within the workstation that has the file
open.
lockFlag: Bit settings indicating the file's locks.
(MSB) Bit 7: Transaction flag set
6: TTS Holding lock
5-4: Not Used
3: Open Normal
2: Logged
1: Open Shareable
(LSB) 0: Locked
accessFlag: Bit settings indicating the connection's access rights to
the file :-
(MSB) Bit 7: Not Used
6: TTS Holding Open
5: TTS Holding Detach
4: File Detached
3: Deny Write Requests from
Other Stations
2: Deny Read Requests from
Other Stations
1: Open For Write by this Station
(LSB) 0: Open For Read by this Station
lockType: A flag indicating the type of lock.
0x00 Not Locked
0xFE Locked by a File Lock
0xFF Locked by Begin Share File Set
nameSpace: The name space used by this entry.
This is only returned on Netware 3.xx, a value of zero
will be returned on Netware 2.xx.
volumeNumber: The volume number within the servers volume table that
holds this file.
parentDirEntry: An offset in the servers directory entry table for the
parent directory of this file.
Use GetPathFromDirectoryEntry to get the path name this
points to.
Netware C Library Appendix III - Data Structures Page: A3-7
────────────────────────────────────────────────────────────────────────────────
directoryEntry: An offset in the servers directory entry table for the
file.
Use GetPathFromDirectoryEntry to get the path name this
points to. This will always be zero on Netware 2.xx.
fileName[14]: Returns a 14-byte null terminated string containing the
terminal file name.
Netware C Library Appendix III - Data Structures Page: A3-8
────────────────────────────────────────────────────────────────────────────────
A3.5 PHYSICAL_DISK_STATISTICS
This is used by GetPhysicalDiskStatistics in the File Server Environment
Services.
typedef struct { long system_elapsed_time;
byte physical_disk_channel;
byte drive_removable_flag;
byte physical_drive_type;
byte controller_drive_number;
byte controller_number;
byte controller_type;
long drive_size;
int drive_cylinders;
byte drive_heads;
byte sectors_per_track;
char drive_definition_string[64];
int io_error_count;
long hot_fix_table_start;
int hot_fix_table_size;
int hot_fix_blocks_available;
byte hot_fix_disabled; } PHYSICAL_DISK_STATISTICS;
system_elapsed_time: This is the number of clock ticks, since the
server was loaded. Where 18.2 clock ticks =
1 second approximately. When this reaches
0xffffffff it wraps back to zero.
physical_disk_channel: The disk channel the disk is attached to.
drive_removable_flag: A non-zero value indicates this drive is
removable.
physical_drive_type: The type of drive:
1=XT, 2=AT, 3=SCSI,
4=disk coprocessor,
5=PS/2 MFM controller,
6=PS/2 ESDI controller,
7=Convergent Technology SBIC,
50 to 255=Value-added disk drive.
controller_drive_number: Drive number of the disk relative to the
controller number.
controller_number: The address on the physical disk channel of
the disk's controller.
controller_type: Contains a number indicating the type,
make and model of the controller.
drive_size: Size of the disk in blocks, 1 block = 4096
bytes. This does not include the area of the
disk reserved for Hot Fix.
drive_cylinders: Number of cylinders on the drive.
drive_heads: Number of heads on the drive.
sectors_per_track: The number of sectors on each track.
1 sector = 512 bytes.
drive_definition_string: 64-byte null terminated string holding
the make and model of the drive.
io_error_count: This is the number of I/O errors on the disk
since the server was loaded.
hot_fix_table_start: This is the first block of the Hot Fix area
on the disk.
Netware C Library Appendix III - Data Structures Page: A3-9
────────────────────────────────────────────────────────────────────────────────
hot_fix_table_size: Number of blocks in the Hot Fix area.
hot_fix_blocks_available: Number of unused blocks in the Hot Fix area.
hot_fix_disabled: A non-zero value indicates that Hot Fix
redirection is disabled.
Netware C Library Appendix III - Data Structures Page: A3-10
────────────────────────────────────────────────────────────────────────────────
A3.6 PRINT_CONTROL_DATA
This is used by the Print Services: GetDefaultCaptureFlags,
GetSpecificCaptureFlags,
SetDefaultCaptureFlags,
SetSpecificCaptureFlags.
typedef struct { byte Status;
byte PrintFlags;
byte TabSize;
byte ServerPrinter;
byte NumberCopies;
byte FormType;
byte Reserved1;
byte BannerText[13];
byte Reserved2;
byte LocalLPTDevice;
int FlushTimeoutCounter;
byte FlushOnClose;
int MaximumLines;
int MaximumChars;
byte FormName[13];
byte LPTFlag;
byte FileFlag;
byte TimeoutFlag;
long SetupBufferAddress;
long ResetBufferAddress;
byte ConnectIdQPrintJob;
byte InProgress;
byte PrintQFlag;
byte PrintJobValid;
long PrintQID;
int PrintJobNumber; } PRINT_CONTROL_DATA;
Status: This is always set to 0x00
PrintFlags: This includes the following bits:
(MSB) Bit 7: The banner page is printed
6: Tab size plus other print control
sequences, will be interpreted by the
server's print process.
5-4: Not specified
3: The server's print service will
suppress the automatic form feed at
the end of the print job
2: The print job is released for
printing if the capture is broken by
the connection to the server being
lost.
1: Not specified
(LSB) 0: Not specified
TabSize: Current tab size (1-18)
ServerPrinter: Printer number on which the captured file will be
printed (0-4).
Netware C Library Appendix III - Data Structures Page: A3-11
────────────────────────────────────────────────────────────────────────────────
NumberCopies: Number of copies to print (0-255)
FormType: The type of form that must be mounted in the printer
for this file to be printed (0-255).
Reserved1: Undefined
BannerText[13]: 13-byte string that will be printed on the bottom
half of a banner page. If this is null then the
capture file name will be printed.
Reserved2: Undefined
LocalLPTDevice: The default LPT device (0-2,0=LPT1)
FlushTimeoutCounter: This starts counting down every time an INT 17h is
executed. When the timeout expires the capture file
is flushed (0-65535).
FlushOnClose: If this is zero (enabled) then the server will flush
the capture file when the program ends the capture of
the default LPT device. A non-zero value indicates
this is disabled.
MaximumLines: The maximum lines per page.
MaximumChars: The maximum characters per line.
FormName[13]: The name of the form that must be mounted in the
printer for this file to print.
LPTFlag: This is set (0xff) when the capture of the default
LPT device is started, and cleared (0x00) when it is
ended.
FileFlag: This is et (0xff) when a capture filename is
specified, but cleared (0x00) when one has not been
specified.
TimeoutFlag: This is set (0xff) when the timeout counter is
counting down, and cleared (0x00) when it isn't.
SetupBufferAddress: This points to a buffer containing the printer setup
string. The buffer size is stored in the first word.
ResetBufferAddress: This points to a buffer containing the printer reset
string. The buffer size is stored in the first word.
ConnectIdQPrintJob: This is the connection ID of the server queuing the
print job.
InProgress: This is set (0xff) when the first character of the
print job is sent to the default LPT device. It is
cleared (0x00) when then capture is ended,flushed or
cancelled.
PrintQFlag: This is set (0xff) when the print queue job entry is
placed in the print queue. It is cleared (0x00) when
the capture is ended, or cancelled.
PrintJobValid: This is set (0xff) whilst the capture file is open,
and cleared (0x00) when the capture is ended,
cancelled or flushed.
PrintQID: This is the bindery object ID of the print queue on
the target server.
PrintJobNumber: This is the job number the Queue Management System
assigns to a print queue job entry.
Netware C Library Appendix III - Data Structures Page: A3-12
────────────────────────────────────────────────────────────────────────────────
A3.7 QUEUE_JOB_ENTRY
This is a queue job's job entry structure used by the Queue Management
Services.
typedef struct { byte client_station;
byte client_task_number;
long client_id_number;
long target_server_id_number;
byte target_execution_time[6];
byte job_entry_time[6];
word job_number;
word job_type;
byte job_position;
byte job_control_flags;
byte job_file_name[14];
byte job_file_handle[6];
byte server_station;
byte server_task_number;
long server_id_number;
char text_job_description[50];
byte client_record_area[152]; } QUEUE_JOB_ENTRY;
client_station: Provided by the Queue Management System, it is
the connection number of the station that placed
the job into the queue.
client_task_number: Provided by the Queue Management System, it is
the number of the task that was active on the
workstation when the job was placed into the
queue.
client_id_number: Provided by the Queue Management System, it is
the object id number of the station that placed
the job into the queue.
target_server_id_number: Provided by the client that placed the job into
the queue, it is the bindery object id of the
queue server that can service the job.
target_execution_time[6]: Provided by the client that placed the job into
the queue, it is the earliest time that the job
can be serviced, if this field is set to all
0xff, then the job can be serviced at the
earliest oportunity.
(Byte 0=year,1=month,2=day,3=hour,4=minutes,
5=seconds)
job_entry_time[6]: Provided by the Queue Management System, it is
the date and time when the job entered the queue
according to the system clock of the server.
(Byte 0=year,1=month,2=day,3=hour,4=minutes,
5=seconds)
job_number: Provided by the Queue Management System, it is
the job number allocated to the job.
job_type: Provided by the client that placed the job into
the queue, it is the type of job represented by
this job entry. A job server can request only
jobs of a specific type, it should be set to
zero if it is not used, and must never be set
to -1.
Netware C Library Appendix III - Data Structures Page: A3-13
────────────────────────────────────────────────────────────────────────────────
job_position: Provided by the Queue Management System, it is
the position of the job within the queue.
job_control_flags: Provided by the client that placed the job into
the queue, bits in this field are set as
(MSB) Bit 7: Operator hold
Prevents the job from being
serviced, can only be set by
an operator.
6: User hold flag
Prevents the job from being
serviced, can be set by an
operator, or the user that
placed the job in the queue.
5: Entry open flag
Set by the client to indicate
that the job is not yet ready
for service, i.e. the job file
has not yet been written. This
bit is cleared by Close File And
Start Queue Job.
4: Service restart flag
If set, the job will remain in
the queue if a job server aborts
the job.
3: Service auto-start flag
The job will be automatically
serviced, if a server connection
is lost and the client has not
yet released the job.
2: Not specified
1: Not specified
(LSB) 0: Not specified
job_file_name[14]: Provided by the Queue Management System, it
specifies the name of the job file associated
with this job.
job_file_handle[6]: Provided by the Queue Management System, it
specifies the netware file handle of the job
file associated with this job.
server_station: Provided by the Queue Management System, it
specifies the station number of the job server
servicing the job.
server_task_number: Provided by the Queue Management System, it
specifies the task number within the job server
that is servicing the job.
server_id_number: Provided by the Queue Management System, it
specifies the bindery object id of the job
server that is servicing the job.
text_job_description[50]: Set by the client that placed the job into the
queue, it is a null-terminated ASCII text
description of the purpose of the job.
client_record_area[152]: Set by the client that placed the job into the
queue, it provides additional information for
the job server.
Netware C Library Appendix III - Data Structures Page: A3-14
────────────────────────────────────────────────────────────────────────────────
A3.8 SPX_CONNECTION_STATUS
This is used by SPXGetConnectionStatus in the Communication Services.
typedef struct { byte connection_state;
byte watchdog_is_on;
int local_connection_id;
int remote_connection_id;
int sequence_number;
int local_acknowledge_number;
int local_allocation_number;
int remote_acknowledge_number;
int remote_allocation_number;
int local_socket;
byte immediate_address[6];
byte network_number[4];
byte node_address[6];
int socket;
int retransmission_count;
int est_roundtrip_delay;
int retransmitted_packets;
int suppressed_packets; } SPX_CONNECTION_STATUS;
connection_state: Current state of the connection.
0x01 Waiting. SPX is listening on the
connection, waiting for an
establish connection packet.
0x02 Starting. SPX is attempting to
make a connection by sending
establish connection packets.
0x03 Established. SPX has established
a connection with a remote
workstation.
0x04 Terminating. The remote work-
station has terminated the
connection.
watchdog_is_on: If bit 1 is set, then the watchdog process is
monitoring the connection.
local_connection_id: The SPX connection id of this workstation.
remote_connection_id: The SPX connection id of the remote station.
sequence_number: The sequence number that the local SPX will
assign to the next packet that it sends. This
is incremented each time a packet is sent.
When it reaches 0xffff it wraps back to zero.
local_acknowledge_number: The sequence number of the next packet that
the local SPX expects to receive.
local_allocation_number: This is the number of outstanding listen ECBs
that are available for the local SPX. The
remote SPX is allowed to send packets with
sequence numbers up to and including the
local_allocation_number. This number is
incremented as the local workstation generates
listen ECBs. When this number reaches 0xffff
it wraps back to zero.
Netware C Library Appendix III - Data Structures Page: A3-15
────────────────────────────────────────────────────────────────────────────────
remote_acknowledge_number: This is the sequence number of the next packet
that the remote SPX expects to receive from
the local SPX.
remote_allocation_number: This is the number of outstanding listen ECBs
that are available to the remote SPX. The
local SPX is allowed to send packets with
sequence numbers up to and including the
remote_allocation_number. This number is
incremented as the remote station generates
listen ECBs. When this number reaches 0xffff
it wraps back to zero.
local_socket: This is the socket number that the local SPX
is using to send and receive packets.
immediate_address[6]: This is the address of the bridge that routes
the packets to and from the remote station. If
the loacl and remote stations are on the same
local network, then this is the address of the
remote station.
network_number[4]: The network number that the remote station is
on.
node_address[6]: The node address of the remote station.
socket: The socket number that the remote station is
using to send and receive packets.
retransmission_count: The number of times that SPX will attempt to
resend an unacknowledged packet before it
determines that the remote half of the
connection is no longer responding.
est_roundtrip_delay: This is the number of clock ticks that the
local SPX will wait for before resending
a packet.
retransmitted_packets: The number of times that the local SPX has
had to resend a packet for this connection.
suppressed_packets: The number of packets that have been discarded
by the local SPX, possibly due to a duplicate
packet being received.
Netware C Library Appendix III - Data Structures Page: A3-16
────────────────────────────────────────────────────────────────────────────────
A3.9 VOLUME_STATISTICS
This is used by GetVolumeInformation in the Directory Services.
typedef struct { long system_elapsed_time;
byte volume_number;
byte logical_drive_number;
int sectors_per_block;
int starting_block;
int total_blocks;
int available_blocks;
int total_directory_slots;
int available_directory_slots;
int max_used_dir_entries;
byte volume_is_hashed;
byte volume_is_cached;
byte volume_is_removable;
byte volume_is_mounted;
char volume_name[17]; } VOLUME_STATISTICS;
system_elapsed_time: This is the number of clock ticks, since the
server was loaded. Where 18.2 clock ticks =
1 second approximately. When this reaches
0xffffffff it wraps back to zero.
volume_number: This identifies the volume in the servers
Volume Table.
logical_drive_number: This is the volumes logical drive number on
the server.
sectors_per_block: This is the number of 512-byte sectors held
in each block.
starting_block: The number of the first block of the volume.
total_blocks: Total number of blocks on the volume.
available_blocks: Total number of unused blocks on the volume.
total_directory_slots: Total number of directory slots allocated for
the volume at installation time.
available_directory_slots: Total number of unused directory slots.
max_used_dir_entries: Maximum directory slots used at any one time
on the volume.
volume_is_hashed: A non-zero value indicates that the volume is
hashed in the servers memory.
volume_is_cached: A non-zero value indicates that the volume is
cached in the servers memory.
volume_is_removable: A non-zero value indicates that the disk that
holds the volume is removable.
volume_is_mounted: A non-zero value indicates that the volume is
mounted.
volume_name[17]: The 17-byte null terminated volume name
Netware C Library Appendix IV - Order Form Page: A4-1
────────────────────────────────────────────────────────────────────────────────
Return to: Adrian Cunnelly
18 Kingsley Avenue,
Heaton Norris,
Stockport,
Cheshire.
SK4 1PW
ENGLAND
Name: __________________________________________________
Company: __________________________________________________
Address: __________________________________________________
__________________________________________________
__________________________________________________
__________________________________________________
Phone: __________________________________________________
Email: __________________________________________________
Diskette size (Select one): [___] 5.25" 1.2mb
[___] 5.25" 360k
[___] 3.5" 1.44mb
[___] 3.5" 720k
Pounds US
Sterling Dollars Quantity Total
-------- ------- -------- -----
Registration ......................£40.00 $68.00 [ ] [ ]
includes:
1) The latest version of the library
(large,medium & small models) for
Microsoft C 6.0,7.0, Turbo C 2.0
and Borland C++ 2.0,3.1.
2) Windows DLL.
3) Printed manual.
Registration + Full Source code ...£75.00 $128.00 [ ] [ ]
includes:
1) The latest version of the library
(large,medium & small models) for
Microsoft C 6.0,7.0, Turbo C 2.0
and Borland C++ 2.0,3.1.
2) Windows DLL.
3) Printed manual.
4) Full library source code.
Additional manuals .........(each) £15.00 $25.00 [ ] [ ]
Total......................................................... _____
Netware C Library Appendix IV - Order Form Page: A4-2
────────────────────────────────────────────────────────────────────────────────
All the above prices include postage and packing.
Payment must be in the form of a cheque, money order or bankers draft,
in UK Pounds Sterling, or US Dollars, and must be made payable to
Adrian Cunnelly.
