Introduction to NCPs

Introduction

Collectively, the set of routines and primitives that drive NetWare are known as The NetWare Core Protocol. Most often, however, these routines are referred to as the NCPs. The NCPs make up the fundamental Language, or in other words, the core protocol that NetWare speaks. Each routine is also referred to individually as an NCP. This introduction describes NCPs in general, explains what the fundamental NCP structures are, and discusses the way NCPs interface with and provide services to a client.

Service Connections

Service between a client and a server begins with the establishment of a NCP connection. A client builds a message containing all required procedure parameters and sends the message across the connection to the Server by means of an underlying network message delivery system such as IPX or SPX. The server executes the indicated procedure and delivers the results back to the client. NCP Messages passed across this connection are assigned monotonically increasing identification numbers. Each NCP request from a client elicits exactly one NCP response.

Session Interface/Datagram Interface

NCPs allow a client and a server to converse using one of two network interfaces or message delivery systems. If available, a network session layer such as SPX can be used. It supports message sequencing and guaranteed message delivery. If a network session layer is unavailable or if performance considerations warrant, a client and a server may communicate using a lower-level unreliable datagram interface such as IPX.

The datagram interface provides two important advantages. First, it allows porting of NCPs to networks where standard session interfaces do not exist. Second, it allows the client and the server to derive performance advantages from the inherently efficient nature of their protocol interactions.

Current server implementations restrict a client to no more than one NCP request outstanding on a given connection at any time. But multiple connections can exist between two physical computers. So if a client computer were being used as a multi-user system for example, then each user could have a separate connection to a server, and NCP requests could be outstanding on all connections at once.

Because server access security is determined on a per-connection basis, it is normal for a single user's multiple tasks to share a single connection. But new connections could be established for each task in a multitasking environment if the client's operating system required it or if the user's application warranted it. The server treats each connection as a logically distinct entity, regardless of the physical machine from which the connection originated. A client machine can of course maintain as many current connections to as many different servers as it finds necessary.

NCP Names and Numbers

Each NCP is known by its number. The name, although important in describing the task that the NCP performs, otherwise has no meaning. Each NCP number is comprised of three fields. For example, the number for the bindery NCP Change Bindery Object Password is 0x2222 23 64. Other bindery NCPs would include, for example, 0x2222 23 50 (Create Bindery Object) or 0x2222 23 51 (Delete Bindery Object). Other groups of NCPs such as Directory Services NCPs include NCPs such as Get Directory Disk Space Restriction (0x2222 22 35) and so on.

For all NCPs the first one-word field (0x2222) serves both as a unique service identifier stamp and as a service category field. An NCP may have one of five possible values in this field. Shown below, these values and their meanings categorize the NCPs:

     Oxllll        Create a Service Connection
     0x2222        Service Request
     0x3333        Service Response
     0x5555        Destroy a Service Connection
     0x9999        Previous Request Still Being Processed

Of these five service categories, Service Request (0x2222) and Service Response (0x3333)-are the most common. Every NCP except the four listed below begins as a Service Request(0x2222). And many of the Service Request NCPs evoke a Service Response(0x3333). Only the following four NCPs do NOT begin as Service Requests:

     Create Service Connection    (Oxllll -- --)
     Destroy Service Connection   (0x5555 O  --)
     Request Being Processed      (0x9999)
     Request Processed            (0x3333)

The other two fields in the NCP number are the NCP function and subfunction numbers. The function number identifies where in the switch table a generic function exists, and the subfunction number eventually identifies the specific NCP function that must be executed.

These NCP numbers and the functions to which they refer are divided into categories based primarily on the function of the NCP. The categories, however, are often large and somewhat haphazard. For example, most, but not all Case 23 calls are categorized as Accounting, Bindery, Connection, or File Server calls. Most Case 22 calls are Directory calls. Case 17 are Print calls, and so on.

NCP Request and Reply Structures

An NCP message consists of a fixed header block followed by a variable data block. The header block contains controlling connection information and indicates the service required by the caller. The data block contains parameters required by the remotely executing procedure.

Message Header Structure

Each NCP message begins with a small message header that carries general status information about the current state of the connection between the client and the server. A client's request header is seven bytes long, while a server's reply header is eight bytes long. The NCP request and reply headers are shown below, and explained in the following section.

   Request Header
      OffsetContent                                          TYPE
      -------------------------------------------------------------
      O   RequestType             (0x2222)                   word
      2   SequenceNumber          (LastSequence + 1)         byte
      3   ConnectionNumberLow     (ServiceConnection)        byte
      4   TaskNumber              (CurrentTaskNumber)        byte
      5   ConnectionNumberHigh    (ServiceConnecrion)        byte

   Reply Header
      OffsetContent                                          TYPE
      -------------------------------------------------------------
      O  ReplyType                (0x3333)                   word
      2  SequenceNumber           (RequestSequenceNumber)    byte
      3  ConnectionNumberLow      (ServiceConnection)        byte
      4  TaskNumber               (ClientTaskNumber)         byte
      5  ConnectionNumberHigh     (ServiceConnection)        byte
      6  Completioncode           (Ccode)                    byte
      7  ConnectionStatusFlags    (StatusFlags)              byte

Of course, a header is also followed by other data fields as required by the particular NCP.

Note that numeric fields composed of more than 1 byte can be in two opposite formats: high-low and low-high. High-low numbers contain the most significant byte in the first byte of the held, the next-most significant byte in the second byte, and so on, with the least significant byte appearing last. Low-high numbers are stored in exactly the opposite order.

The architecture of the 8086, 80186, and 80286 microprocessors is geared towards storing numbers in low-high order. Therefore, care must be taken that numeric values retrieved from an incoming Service Reply message are reversed to low-high format where required. Likewise, all values placed in an outgoing service request must be stored in high-low format. In an NCP request for NetWare 386 v3.0 and above, fields default to a low-high format. In these cases, exceptions are marked high-low.

Description of Request/Reply Structure Fields

Following is a description of the meaning and use of each field in the NCP message header.

Request Type/Reply Type

This one-word field serves both as a unique service identifier stamp and as a service category field. The following values are defined:

     Oxllll        Create a Service Connection
     0x2222        Service Request
     0x3333        Service Response
     0x5555        Destroy a Service Connection
     0x9999        Previous Request Still Being Processed

Sequence Number

This field is a wraparound message sequence number. When a "Create Service Connection" request is issued this field should be set to zero. All subsequent requests should increment the field by one, allowing wraparound to zero again. Service Response messages will always contain the same request number as the service request message to which they are responding.

Connection Number Low

This field must contain a zero when a "Create a Service Connection" request is made. All subsequent service requests must contain the service connection returned by the server in response to the "Create a Service Connection" request.

Task Number

This field indicates which client task is making the service request. The server tracks which tasks are opening files, locking data, etc. so that the server can automatically deallocate those resources when the client's task ceases execution. Up to 255 tasks (0x01 to OxFF) may share a single connection. Task number O is reserved for the "End of Task" call, where it can be used to signal that all tasks have ceased execution.

Connection Number High

Completion Code

In the Reply Header, the information at offset 6 is the Completion Code. The Completion Code field is returned by a server as part of its header response to a client's service request. Any non-zero completion code indicates that an error occurred while processing the client's request.


   IMPORTANT: Whenever a non-zero completion code is returned by
   the server, the remainder of the server's response message is NOT
   returned to the client.

Connection Status

In the Reply Header, the information at offset 7 is the Connection Status. The Connection Status Flags field is returned by a server as part of its header response to a client's service request. This flag field is a bit field with the following bits defined:
Bit O Set if the client's request contained a bad service connection. Bit 2 Set if the client requested a connection and the server has no connections available. Bit 4 Set if the server is down. Bit 6 Set if the server is holding a broadcast message for the client.
This flag field should be checked by the client each time a service response is received. If the "server down" bit is ever set then the client must infer that the service connection has been terminated on the server's end because the server has been taken down.