This section contains the data access synchronization protocols. These protocols enable clients to coordinate access to network files and other network resources. They are divided into two categories: 1) File and Record Locks and 2) Semaphores.
File and Record Locks
The NetWare Core Protocol supports file locking, physical record locking, and logical record locking. A file lock locks a complete file; a physical record lock locks a specified byte range within a file; a logical record lock locks a logical record name associated with one or more files and/or records.
All files and records to be locked must first be logged. Logging files and records before locking them ensures that either all necessary files or records are locked, or none are. When clients log files or records, information (such as location, size, and byte range) about them is recorded in a log table on the file server. This log table is associated exclusively with the requesting task on the workstation. The calls that log files and records also allow the client to immediately lock them. If immediate locking is specified in a logging call, the client can specify a timeout period that the server uses to retry locking. If files or records are not logged for immediate locking, other calls are provided for locking them. If all logged files or records are available, the file server locks them when the locks are requested. If, however, any of the files or records are being used by another client and the timeout value has expired, the call to lock them fails.
Unlike a physical record lock, a logical record lock does not actually lock a byte range in a file. Instead, a logical record lock acts somewhat like a semaphore. Clients cooperatively define a logical record name that represents a group of files, records or structures. In this case, a client locks only the logical record name and not the actual group of files, records, or structures the name represents.
Note, however, that files and records with logical locks can still be accessed directly. Therefore, clients using logical record locks must not use other locking techniques simultaneously. The logical record name described here is also referred to as a synchronization string or Synch Name.
Clients can specify a timeout value with locking calls. If any of the files or records are not available, the timeout value instructs the file server to wait for the files or records to become available. If the files or records are still not available at the end of the time specified by the timeout value, the locking call fails. This reduces client retries and, ultimately, network traffic. The timeout value is counted in units of approximately 1/18 of a second.
Semaphores
NetWare provides system calls that enable clients to create, open, examine, and close semaphores. Clients can also use semaphore system calls to increment and decrement the value associated with a semaphore.
Like a logical record lock, a semaphore is a name associated with network resources such as files and records. Both logical record locks and semaphores limit the number of clients that can access network resources at one time. Logical record locks limit the number of clients to one. Semaphores, however, allow a configurable number of clients (1 to 127) to access a network resource at one time.
When a client creates a semaphore using Open Semaphore (function 32, subfunction 0), the client assigns a value to the semaphore to indicate how many clients can simultaneously access the resource associated with the semaphore. For example, a semaphore value of 4 indicates that 5 clients can access the associated resource at one time (0 to 4). All calls accessing a semaphore must obtain a semaphore handle by first making a call to Open Semaphore.
After opening an existing semaphore, a client first checks the semaphore's value using Examine Semaphore (function 32, subfunction 1). If the value is greater than or equal to zero, the client can access the associated network resource. The client decrements the value by calling Wait On Semaphore (function 32, subfunction 2) and then accesses the resource. After accessing the resource, the client increments the semaphore value by calling Signal Semaphore (function 32, subfunction 3), and then exits the semaphore.
If the Semaphore Value is negative, the client cannot access the resource immediately. The client can either wait a specified timeout interval for the resource to become available (accessible), or the client can retry later.
The following algorithm illustrates semaphore usage:
| v2.x | v3.x | v4.x | v5.x |
Request
Offset Content Type (request header) 6 FunctionCode (87) byte 7 SubFunctionCode (38) byte 8 NameSpace byte 9 reserved (0) byte 10 reserved2 (0) word 12 NWHandlePathStruct structure
Reply
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This new NCP replaces the NCP Clear File (0x2222 07 --). This new NCP allows a client to release the locks on a file, and close the file (if open) by using the NWHandlePathStruct instead of by using only a 1-byte directory handle and a file name.
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (7) byte 7 DirectoryHandle byte 8 FileNameLen byte 9 FileName byte[FileNameLen]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 150 0x96 Server Out Of Memory 152 0x98 Disk Map Error 155 0x9B Bad Directory Handle 156 0x9C Invalid Path 161 0xA1 Directory I/O Error 253 0xFD Bad Station Number 255 0xFF Unlock Error
Remarks
This NCP clears one file from the calling client's logged file table. If the specified file is open, it is closed, and its file handle is invalidated. The file can then be accessed by other clients. If the calling client had the file open multiple times, it is closed as many times and all associated file handles are invalidated.
See Also
Log File (0x2222 105 --)
Lock File Set (0x2222 106 --) and Clear File Set (0x2222 08 --)
Release File (0x2222 05 --) and Release File Set (0x2222 06 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (8) byte 7 LockFlag byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This NCP clears all files from the client's logged file table. All open files are closed and all the client's file handles are invalidated. File I/O cannot be performed while files are closed.
See Also
Log File (0x2222 105 --)
Lock File Set (0x2222 106 --)
Release File (0x2222 05 --)
Release File Set (0x2222 06 --)
Clear File (0x2222 07 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (112) byte 7 WaitNode structure
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 127 0x7F ERR_LOCK_WAITING 255 0xFF Lock Error
Remarks
This NCP aborts a pending asynchronous lock by clearing the asynchronous lock WaitNode specified by the WaitNode parameter.
The WaitNode parameter is a handle to a ASyncLockWaitStructure structure that has been allocated by calling one of the following asynchronous locking NCPs:
Log File 0x2222 105 --
Lock File Set 0x2222 106 --
Log Logical Record 0x2222 107 --
Lock Record Set 0x2222 108 --
Log Physical Record 0x2222 109 --
Log Physical Record Set 0x2222 110 --
The ASyncLockWaitStructure is defined as follows:
struct ASyncLockWaitStructure
{
struct ASyncLockWaitStructure *ALink;
LONG AStation;
LONG ATask;
LONG ACompletionCode;
LONG ALastTime;
BYTE AStatus;
BYTE AWaitType;
};
The ALink field is a pointer to the next ASyncLockWaitStructure in a linked list.
The AStation field is the connection that has allocated a structure.
The ATask field is the task number for which a structure is allocated.
The ACompletionCode field is the completion code.
The ALastTime field contains a value to determine the wake up time for the WaitNode.
The AStatus field indicates the status of the WaitNode as follows:
| Value | Status |
|---|---|
| 0 | Inserting |
| 1 | Waiting |
| 2 | Completed |
The AWaitType field is the type of WaitNode lock as follows:
See Also
Log File (0x2222 105 --)
Lock File Set (0x2222 106 --),
Log Logical Record (0x2222 107 --)
Lock Record Set (0x2222 108 --)
Log Physical Record (0x2222 109 --)
Log Physical Record Set (0x2222 110 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (11) byte 7 SynchNameLen byte 8 SynchName byte[SynchNameLen]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 255 0xFF Unlock Error
Remarks
This NCP releases the specified synchronization string (Synch Name) and removes it from the client's synchronization string table. The synchronization string cannot be used until it is relogged by the client.
See Also
Log Logical Record (0x2222 107 --)
Lock Logical Record Set (0x2222 108 --)
Clear Logical Record Set (0x2222 14 --)
Release Logical Record (0x2222 12 --)
Release Logical Record Set (0x2222 13 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (14) byte 7 LockFlag byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This NCP releases all of the client's synchronization strings (logical record locks) and clears the client's synchronization string table.
See Also
Log Logical Record (0x2222 107 --)
Lock Logical Record Set (0x2222 10 --)
Clear Logical Record (0x2222 11 --)
Release Logical Record (0x2222 12 --)
Release Logical Record Set (0x2222 13 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (30) byte 7 Reserved byte 8 FileHandle byte[6] 14 LockAreaStartOffset long (Hi-Lo) 18 LockAreaLen long (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 255 0xFF Unlock Error
Remarks
This NCP removes the specified byte range from the client's data byte range table. If the byte range is locked, then it is cleared. The client can't use the specified byte range until that range is again logged and locked.
The byte range specified must match a byte range previously logged. Clearing only a portion of a previously logged byte range is not allowed.
See Also
Log Physical Record (0x2222 109 --)
Lock Physical Record Set (0x2222 110 --)
Release Physical Record (0x2222 28 --)
Release Physical Record Set (0x2222 29 --)
Clear Physical Record Set (0x2222 31 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (31) byte 7 LockFlags byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This NCP clears the client's data byte range table of all byte ranges held by the file server for the calling task. All locked ranges are released.
See Also
Log Physical Record (0x2222 109 --)
Lock Physical Record Set (0x2222 110 --)
Release Physical Record (0x2222 28 --)
Release Physical Record Set (0x2222 29 --)
Clear Physical Record (0x2222 30 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (111) byte 7 SubFunctionCode (01) byte 8 SemaphoreHandle long (Lo-Hi)
Reply Format
Offset Content Type (reply header) 8 OpenCount byte 9 ShareCount byte
Completion Code
0 0x00 Successful 255 0xFF Lock Error
Remarks
This NCP allows a client to close a semaphore that is no longer needed. The corresponding Semaphore Open Count (number of clients accessing the semaphore) is decremented by one. If the Semaphore Open Count is zero after this call, the server deletes the semaphore.
See Also
Open/Create a Semaphore (0x2222 111 00)
Examine Semaphore (0x2222 111 01)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (32) byte 7 SubFunctionCode (4) byte 8 SemaphoreHandle long (Lo-Hi)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 255 0xFF Lock Error
Remarks
This call allows a client to close a semaphore that is no longer needed. The corresponding Semaphore Open Count (number of clients accessing the semaphore) is decremented by one. If the Semaphore Open Count is zero after this call, the server deletes the semaphore.
See Also
Examine Semaphore (0x2222 32 01)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (111) byte 7 SubFunctionCode (04) byte 8 SemaphoreHandle long (Lo-Hi)
Reply Format
Offset Content Type (reply header) 8 SemaphoreValue byte 9 SemaphoreOpenCount byte
Completion Code
0 0x00 Successful 255 0xFF Lock Error
Remarks
This NCP returns the current value of the target semaphore. Semaphore Open Count is the number of clients that are using the semaphore. Semaphore Value is the current value of the semaphore. Semaphore Value is discussed in the Wait On Semaphore and Signal Semaphore calls.
See Also
Close Semaphore (0x2222 111 04)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (32) byte 7 SubFunctionCode (1) byte 8 SemaphoreHandle long (Lo-Hi)
Reply Format
Offset Content Type (reply header) 8 SemaphoreValue byte 9 SemaphoreOpenCount byte
Completion Code
0 0x00 Successful 255 0xFF Lock Error
Remarks
This call returns the current value of the target semaphore. Semaphore Open Count is the number of clients that are using the semaphore. Semaphore Value is the current value of the semaphore. Semaphore Value is discussed in the Wait On Semaphore and Signal Semaphore calls.
See Also
Close Semaphore (0x2222 32 04)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (1) byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This request locks sharable files that the calling station has open. It is provided for compatibility with previous versions of NetWare.
See Also
File Release Lock (0x2222 02 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (2) byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This request releases locks on sharable files that were locked by the last File Set Lock request. It is provided for compatibility with previous versions of NetWare.
See Also
File Set Lock (0x2222 01 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (106) byte 7 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 127 0x7F ERR_LOCK_WAITING 255 0xFF Lock Error
Remarks
This NCP locks all files logged by the calling client's current task. If all files cannot be locked immediately, the file server will retry the call for the amount of time specified in the timeout value (Lock Timeout). If all files cannot be locked, no files are locked.
See Also
Lock File Set (0x2222 106 --)
Log File (0x2222 105 --)
Release File (0x2222 05 --)
Release File Set (0x2222 06 --)
Clear File (0x2222 07 --)
Clear File Set (0x2222 08 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (4) byte 7 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This call locks all files logged by the calling client's current task. If all files cannot be locked immediately, the file server will retry the call for the amount of time specified in the timeout value (Lock Timeout). If all files cannot be locked, no files are locked.
See Also
Log File (0x2222 03 --)
Release File (0x2222 05 --)
Release File Set (0x2222 06 --)
Clear File (0x2222 07 --)
Clear File Set (0x2222 08 --)
Lock File Set (0x2222 104 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (108) byte 7 LockFlag byte 8 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 127 0x7F ERR_LOCK_WAITING 255 0xFF Lock Error
Remarks
This NCP locks all the client's logged synchronization strings. If all files cannot be locked immediately, the server will retry the call for the amount of time specified in the timeout value (Lock Timeout). If all records cannot be locked, the NCP will fail and Lock Error will be returned as the Completion Code. In this case, none of the records in the set are locked by the calling station. If bit 1 of the Lock flag is set, the lock types are exclusive (read-write); otherwise, they are shareable (read-only).
See Also
Lock Logical Record Set (0x2222 108 --)
Log Logical Record (0x2222 107 --)
Clear Logical Record (0x2222 11 --)
Clear Logical Record Set (0x2222 14 --)
Release Logical Record (0x2222 12 --)
Release Logical Record Set (0x2222 13 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (10) byte 7 LockFlag byte 8 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This call locks all the client's logged synchronization strings. If all files cannot be locked immediately, the file server will retry the call for the amount of time specified in the timeout value (Lock Timeout). If all records cannot be locked, the call will fail and Lock Error will be returned as the Completion Code. In this case, none of the records in the set are locked by the calling station.
See Also
Log Logical Record (0x2222 09 --)
Clear Logical Record (0x2222 11 --)
Clear Logical Record Set (0x2222 14 --)
Release Logical Record (0x2222 12 --)
Release Logical Record Set (0x2222 13 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (110) byte 7 LockFlag byte 8 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 127 0x7F Waiting 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This NCP locks all byte ranges currently logged by the calling client. If all byte ranges are not immediately available, the server will retry the call until the amount of time specified in the Lock Timeout value expires.
If the lock is currently available, the server returns a completion code of 0x7F. This frees the requester so that it can send other NCPs for other sessions. When the client times out or the lock becomes available, the server sends an out-of-bounds packet (3rd socket) to the requester. The requester sends NCP 0x2222 112 -- to find out the status. If bit 1 of the Lock flag is set, the lock types are shareable (read-only); otherwise, the lock types are exclusive (read-write).
See Also
Lock Physical Record Set (0x2222 110 --)
Log Physical Record (0x2222 109 --)
Release Physical Record (0x2222 28 --)
Release Physical Record Set (0x2222 29 --)
Clear Physical Record (0x2222 30 --)
Clear Physical Record Set (0x2222 31 --)
Request Format
Offset Content Type (request header) 6 FunctionCode (27) byte 7 LockFlag byte 8 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This call locks all byte ranges currently logged by the calling client. If all byte ranges are not immediately available, the server will retry the call until the amount of time specified in the Lock Timeout value expires.
If bit 1 of the Lock flag is set, the lock types are shareable (read-only); otherwise, the lock types are exclusive (read-write).
See Also
Log Physical Record (0x2222 26 --)
Release Physical Record (0x2222 28 --)
Release Physical Record Set (0x2222 29 --)
Clear Physical Record (0x2222 30 --)
Clear Physical Record Set (0x2222 31 --)
Lock Physical Record Set (0x2222 110 --)
| v2.x | v3.x | v4.x | v5.x |
Request
Offset Content Type (request header) 6 FunctionCode (87) byte 7 SubFunctionCode (36) byte 8 NameSpace byte 9 reserved (0) byte 10 reserved2 (0) word (Lo-Hi) 12 LogFileFlags (see below) long (Lo-Hi) 16 WaitTime long (Lo-Hi) 20 NWHandlePathStruct structure
Reply
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This new NCP replaces the older NCPs Log File (0x2222 03 -- and 0x2222 105 --). This new NCP allows a client to access a file using the NWHandlePathStruct instead of by using only a 1-byte directory handle and a file name. Note too that the callback capabilities provided by Log File (0x2222 105 --) will be accessible by enabling the call back bit in the LogFileFlag field of the new NCP.
LogFileFlags
LockFileImmediatelyBit 0x00000001
CallBackRequestedBit 0x00008000
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (105) byte 7 DirectoryHandle byte 8 LockFlag byte 9 LockTimeout word (Hi-Lo) 11 FileNameLen byte 12 FileName byte[255]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 130 0x82 No Open Privileges 150 0x96 Server Out Of Memory 127 0x7F ERR_LOCK_WAITING 255 0xFF Lock Error
Remarks
This NCP logs the specified file for exclusive use by the calling client. If bit 0 of the Lock flag is set, the server will immediately attempt to lock the file. A file can be locked by a client even if the file does not yet exist, and this reserves the file name for use by that client.
See Also
Log File (0x2222 105 --)
Lock File Set (0x2222 106 --)
Release File (0x2222 05 --)
Release File Set (0x2222 06 --)
Clear File (0x2222 07 --)
Clear File Set (0x2222 08 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (3) byte 7 DirectoryHandle byte 8 LockFlag byte 9 LockTimeout word (Hi-Lo) 11 FileNameLen byte 12 FileName byte[FileNameLen]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 130 0x82 No Open Privileges 150 0x96 Server Out Of Memory 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This NCP logs the specified file for exclusive use by the calling client. If bit 0 of the Lock flag is set, the server will immediately attempt to lock the file. A file may be locked by a client even if the file does not yet exist. This reserves the file name for use by the client that locked it.
See Also
Lock File Set (0x2222 04 --)
Release File (0x2222 05 --)
Release File Set (0x2222 06 --)
Clear File (0x2222 07 --)
Clear File Set (0x2222 08 --)
Log File (0x2222 105 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (107) byte 7 LockFlag byte 8 LockTimeout word (Hi-Lo) 10 SynchNameLen byte 11 SynchName byte[255]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 150 0x96 Server Out Of Memory 127 0x7F Lock Waiting Error 255 0xFF Lock Error
Remarks
This NCP logs a synchronization string for use by the calling client. The string may be up to 128 characters long. If bit 0 of the Lock flag is set, the server will immediately attempt to lock the string. The Lock Timeout value determines how long the server will try to lock the string before reporting failure.
See Also
Log Logical Record (0x2222 23 107 --)
Lock Logical Record Set (0x2222 10 --)
Clear Logical Record (0x2222 11 --)
Clear Logical Record Set (0x2222 14 --)
Release Logical Record (0x2222 12 --)
Release Logical Record Set (0x2222 13 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (9) byte 7 LockFlag byte 8 LockTimeout word (Hi-Lo) 10 SynchNameLen byte 11 SynchName byte[SynchNameLen]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 150 0x96 Server Out Of Memory 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This NCP logs a synchronization string for use by the calling client. The string may be up to 128 characters long. If bit 0 of the Lock flag is set, the server will immediately attempt to lock the string. The Lock Timeout value determines how long the server will try to lock the string before reporting failure.
See Also
Lock Logical Record Set (0x2222 10 --)
Clear Logical Record (0x2222 11 --)
Clear Logical Record Set (0x2222 14 --)
Release Logical Record (0x2222 12 --)
Release Logical Record Set (0x2222 13 --)
Log Logical Record (0x2222 107 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (109) byte 7 LockFlag byte 8 NWFileHandle byte[6] 14 LockAreaStartOffset long (Hi-Lo) 18 LockAreaLen long (Hi-Lo) 22 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 136 0x88 Invalid File Handle 150 0x96 Server Out Of Memory 253 0xFD Lock Collision 127 0x7F ERR_LOCK_WAITING 255 0xFF Lock Error
Remarks
This NCP locks a byte range within a file for the calling client's use. The following table describes the Lock Flag field:
| Lock Flag | Result |
|---|---|
| 00h | The byte range is not locked, but is logged for future locking. |
| 01h | The byte range is locked with "exclusive" (read/write) access. |
| 03h | The byte range is locked with "shareable" (read-only) access. |
The Lock Timeout value specifies how long the file server will attempt to lock the byte range before returning a Failure Completion Code. The Lock Timeout is only valid if the Lock flag is 01h or 3h.
Locked byte ranges can be used only by the task making the lock request. Overlapping lock ranges are allowed.
See Also
Lock Physical Record Set (0x2222 110 --)
Log Physical Record (0x2222 109 --)
Release Physical Record (0x2222 28 --)
Release Physical Record Set (0x2222 29 --)
Clear Physical Record (0x2222 30 --)
Clear Physical Record Set (0x2222 31 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (26) byte 7 LockFlag byte 8 FileHandle byte[6] 14 LockAreaStartOffset long (Hi-Lo) 18 LockAreaLen long (Hi-Lo) 22 LockTimeout word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 136 0x88 Invalid File Handle 150 0x96 Server Out Of Memory 253 0xFD Lock Collision 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This call locks a byte range within a file for the calling client's use. The following table describes the Lock Flag field:
| Lock Flag | Result |
|---|---|
| 00h | The byte range is not locked, but is logged for future locking. |
| 01h | The byte range is locked with "exclusive" (read/write) access. |
| 03h | The byte range is locked with "shareable" (read-only) access. |
The Lock Timeout value specifies how long the file server will attempt to lock the byte range before returning a Failure Completion Code. The Lock Timeout is only valid if the Lock flag is 01h or 11h.
Locked byte ranges can be used only by the task making the lock request. Overlapping lock ranges are allowed.
See Also
Lock Physical Record Set (0x2222 27 --)
Release Physical Record (0x2222 28 --)
Release Physical Record Set (0x2222 29 --)
Clear Physical Record (0x2222 30 --)
Clear Physical Record Set (0x2222 31 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (32) byte 7 SubFunctionCode (0) byte 8 InitialSemaphoreValue byte 9 SemaphoreNameLen byte 10 SemaphoreName byte[SemaphoreNameLen]
Reply Format
Offset Content Type (reply header) 8 SemaphoreHandle long (Lo-Hi) 12 SemaphoreOpenCount byte
Completion Code
0 0x00 Successful 150 0x96 Server Out Of Memory 255 0xFF Lock Error
Remarks
This NCP allows a client to open a named semaphore. If the semaphore does not exist, the server creates one. If the semaphore already exists, the Initial Semaphore Value specified by the calling client is ignored. The Semaphore Handle returned by the server must be used by the client when accessing the semaphore. The Semaphore Open Count indicates how many clients currently have the semaphore open. If the calling client created this semaphore, Semaphore Open Count will equal 1.
See Also
Close Semaphore (0x2222 32 04)
Open/Create Semaphore (0x2222 111 00)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (111) byte 7 SubFunctionCode (0) byte 8 InitialSemaphoreValue byte 9 SemaphoreNameLen byte 10 SemaphoreName byte[512]
Reply Format
Offset Content Type (reply header) 8 SemaphoreHandle long (Lo-Hi) 12 SemaphoreOpenCount byte
Completion Code
0 0x00 Successful 150 0x96 Server Out Of Memory 255 0xFF Lock Error
Remarks
This NCP allows a client to open a named semaphore. If the semaphore does not exist, the file server creates one. If the semaphore already exists, the Initial Semaphore Value specified by the calling client is ignored.
The Semaphore Handle returned by the server must be used by the client when accessing the semaphore. The Semaphore Open Count indicates how many clients currently have the semaphore open. If the calling client created this semaphore, Semaphore Open Count will equal 1.
See Also
Close Semaphore (0x2222 111 04)
| v2.x | v3.x | v4.x | v5.x |
Request
Offset Content Type (request header) 6 FunctionCode (87) byte 7 SubFunctionCode (37) byte 8 NameSpace byte 9 reserved (0) byte 10 reserved2 (0) word 12 NWHandlePathStruct structure
Reply
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This new NCP replaces the old NCP Release File (0x2222 05 --). This new NCP allows a client to release the locks on a file using the NWHandlePathStruct instead of using only a 1-byte directory handle and a file name.
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (5) byte 7 DirectoryHandle byte 8 FileNameLen byte 9 FileName byte[FileNameLen]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 156 0x9C Invalid Path 255 0xFF Unlock Error
Remarks
This NCP releases the specified file, previously locked by the calling client. Releasing a file allows it to be used by others clients. If the file is open, the file handle becomes invalid. The file remains in the calling client's logged file table and can be locked by future calls to Lock File Set (0x2222 04 --). The client cannot perform I/O to the file until the file is again locked by the client.
See Also
Log File (0x2222 105 --)
Lock File Set (0x2222 106 --)
Release File Set (0x2222 06 --)
Clear File (0x2222 07 --)
Clear File Set (0x2222 08 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (6) byte 7 LockFlag byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This NCP releases all the client's currently logged or locked files for use by other clients. File handles for any files that are open become invalid. The client will not be able to perform I/O to the files until they are again locked using the Lock File Set (0x2222 04 --). The files remain in the client's logged file table.
See Also
Log File (0x2222 105 --)
Lock File Set (0x2222 106 --)
Release File (0x2222 05 --)
Clear File (0x2222 07 --)
Clear File Set (0x2222 08 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (12) byte 7 SynchNameLen byte 8 SynchName byte[SynchNameLen]
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 255 0xFF Unlock Error
Remarks
This NCP releases one synchronization string held by the calling client. Releasing logical records allows other clients to lock the records. The string remains in the calling client's synchronization string table and will be relocked when the client calls Lock Logical Record Set (0x2222 10 --).
See Also
Log Logical Record (0x2222 23 107 --)
Lock Logical Record Set (0x2222 10 --)
Clear Logical Record (0x2222 11 --)
Clear Logical Record Set (0x2222 14 --)
Release Logical Record Set (0x2222 13 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (13) byte 7 LockFlag byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This NCP releases all the client's locked synchronization strings for use by other clients. The strings remain in the calling client's synchronization string table and will be relocked when the client calls Lock Logical Record Set (0x2222 10 --).
See Also
Log Logical Record (0x2222 23 107 --)
Lock Logical Record Set (0x2222 10 --)
Clear Logical Record (0x2222 11 --)
Clear Logical Record Set (0x2222 14 --)
Release Logical Record (0x2222 12 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (28) byte 7 Reserved byte 8 FileHandle byte[6] 14 LockAreaStartOffset long (Hi-Lo) 18 LockAreaLen long (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 255 0xFF Unlock Error
Remarks
This NCP releases a byte range previously locked by the calling client. The released byte range will remain in the client's logged data block table and will be relocked by subsequent calls to Lock Physical Record Set (0x2222 27 --). Released byte ranges must match locked byte ranges. Releasing only a portion of a previously locked byte range is not allowed. If the byte range being released overlaps any other byte range lock(s) still in effect, all but the overlapped bytes will be released.
See Also
Log Physical Record (0x2222 109 --)
Lock Physical Record Set (0x2222 110 --)
Release Physical Record Set (0x2222 29 --)
Clear Physical Record (0x2222 30 --)
Clear Physical Record Set (0x2222 31 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (29) byte 7 LockFlags byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful
Remarks
This NCP releases all byte ranges locked by the calling client. The byte ranges are left in the client's data byte range table for future locking with Lock Physical Record Set (0x2222 27 --).
See Also
Log Physical Record (0x2222 109 --)
Lock Physical Record Set (0x2222 110 --)
Release Physical Record (0x2222 28 --)
Clear Physical Record (0x2222 30 --)
Clear Physical Record Set (0x2222 31 --)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (111) byte 7 SubFunctionCode (03) byte 8 SemaphoreHandle long (Lo-Hi)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 255 0xFF Lock Error
Remarks
This NCP increments the semaphore value by one. If another client is waiting on the semaphore, a Successful Completion Code is returned to the waiting client.
See Also
Wait On (P) Semaphore (0x2222 111 02)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (32) byte 7 SubFunctionCode (3) byte 8 SemaphoreHandle long (Lo-Hi)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 255 0xFF Lock Error
Remarks
This call increments the semaphore value by one. If another client is waiting on the semaphore, a Successful Completion Code is returned to the waiting client.
See Also
Wait On Semaphore (0x2222 32 02)
Signal (V) Semaphore (0x2222 111 03)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (111) byte 7 SubFunctionCode (02) byte 8 SemaphoreHandle long (Lo-Hi) 12 SemaphoreTimeOut word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This NCP allows a client to wait on a semaphore. The semaphore value is decremented by one. If the resulting value is greater than or equal to zero, a Successful Completion Code is returned to the calling client. If the resulting value is less than zero, the server will wait for a Signal Semaphore (0x2222 32 03) for the amount of time specified by Semaphore Time Out. If no signal arrives, the server automatically re-increments the semaphore value and returns a Timeout Completion Code to the calling client, indicating that the semaphore is not available.
See Also
Signal (V) Semaphore (0x2222 111 03)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (32) byte 7 SubFunctionCode (2) byte 8 SemaphoreHandle long (Lo-Hi) 12 SemaphoreTimeOut word (Hi-Lo)
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 254 0xFE Timeout 255 0xFF Lock Error
Remarks
This call allows a client to wait on a semaphore.
The semaphore value is decremented by one. If the resulting value is greater than or equal to zero, a Successful Completion Code is returned to the calling client. If the resulting value is less than zero, the server waits for a Signal Semaphore (0x2222 32 03) for the amount of time specified by Semaphore Time Out. If no signal arrives, the server automatically re-increments the semaphore value and returns a Timeout Completion Code to the calling client, indicating that the semaphore is not available.
See Also
Signal Semaphore (0x2222 32 03)
Wait On (P) Semaphore (0x2222 111 02)