Beijing Paradise BBS Backup

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 | 298.6 KB | 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.