Chapter 7 - VINES Session and Presentation Layer Protocols
VINES session layer protocols are responsible for the overall coordination of communications activity between processes in the network. The session layer transparently handles the conversion between ordinary local procedure calls from processes and IPC reliable messages on the VINES transport layer.
The VINES presentation layer is responsible for converting data formats between machine format and standard network representation.
Within VINES, the NetRPC Remote Procedure Call utility and the SMB protocol provide both session and presentation layer functions.
This chapter explains NetRPC protocols and functions as follows:
![]()
Overview of NetRPC ![]()
How applications use NetRPC ![]()
NetRPC data types ![]()
Remote procedure definitions ![]()
NetRPC protocol specification ![]()
NetRPC protocol implementation notes ![]()
NetRPC at runtime
This chapter also provides an explanation of VINES SMB.
One of the most powerful and flexible communication methods in distributed systems is a Remote Procedure Call (RPC) mechanism. A service consumer, called a client, makes requests to a service provider, called a service. In the source code, these requests look like ordinary local procedure calls, even though the client and service can reside on separate machines or even different networks.
Example Client/Service Interaction
A good example of client/service interaction is the Intelligent Messaging mail client and service. In Figure 7-1, a mail client running on a DOS workstation sends a request to read a mail message - Message A - to the service. The service responds with Message A.
NetRPC is the VINES Remote Procedure Call mechanism. NetRPC defines both a protocol and a specification language, as follows:
![]()
The protocol specifies how remote procedures are invoked and how parameters and results of various data types are transmitted. ![]()
The specification language provides a simple way of defining the remote interfaces of distributed programs.
NetRPC uses a language and data transmission format that makes production of service/client interfaces automatic. NetRPC consists of the following components:
![]()
A specification language that defines remote interfaces of distributed programs, including the data types of all arguments ![]()
A compiler that translates a NetRPC specification into C source code for both the service and client components ![]()
A standard library for each machine supported by VINES
With one NetRPC specification, you can set up the remote procedure interface for a service and multiple clients.
NetRPC provides these functions to a process running in a network:
![]()
Interprocess communications between service and client or service and service. NetRPC transparently converts RPCs into IPC reliable messages on the VINES transport layer. ![]()
A rendezvous mechanism with other processes. Services can register on the network by setting up a NetRPC listening port known to the StreetTalk naming service. Client programs and other services can then find the service by name through StreetTalk and initiate communication. ![]()
A tasking system that listens for incoming RPCs and distributes them to the appropriate procedures within the service. The tasking system also allows multiple incoming RPCs at any one time. ![]()
Reliable data typing for arguments to and from RPCs. ![]()
An RPC interface to the StreetTalk naming service and the Server Service. ![]()
The ability to handle architectural differences between platforms, such as byte-alignment.
The simplest form of a distributed application using NetRPC consists of three parts:
Part One - The specification, written in the NetRPC language, is contained in a specification file and must declare all procedures of the program that are called remotely (the service procedures).
Part Two - The implementation of the service procedures.
Part Three - The client portion of the program that calls the service procedures.
The NetRPC compiler generates two program modules using the specification (part one):
![]()
One for the client program ![]()
One for the service program
These program modules contain the necessary data type transformations and message protocol interface for communication in a procedure call fashion.
The NetRPC compiler expects two basic inputs:
![]()
A formal specification of the service procedures using NetRPC data types ![]()
The processor class of the service and client machines (such as IBM PC)
The NetRPC compiler accepts one file as input, which is the NetRPC specification for the service. The specification contains the following information:
![]()
General information (for example, the name of the service). ![]()
Definitions of the data types used for all data elements passed between the client and the service. ![]()
Definitions of each procedure that can be invoked remotely. These definitions include the parameters, in terms of the data types declared, that each procedure requires. These parameters are marked as inputs, outputs, or both to the remote procedure.
The output of the compiler is source code generated in a common programming language. The source code must be compiled with the language compiler for the target machine. Throughout this chapter, it is assumed that NetRPC generates the source code in the C programming language. The NetRPC specification language contains facilities for declaring new types and constants of given types. Data types can be chosen from either a predefined type list or can be constructed out of simpler types.
Figure 7-2 illustrates the generation of service code.
NetRPC data types are divided into these categories:
![]()
Simple types ![]()
Constructed types ![]()
Constants ![]()
Pointer data types
The following sections briefly explain these data types. For more information on these data types, see your VINES Applications Toolkit documentation.
Simple types are used in procedure definitions and to declare constructed types. Table 7-1 shows the NetRPC simple data types and their C equivalents.
Table 7-2 shows the NetRPC constructed data types and their C equivalents.
Although the NetRPC language allows declaration of constants of any data type, it is difficult to define constants of constructed types in C language programs. Consequently, constants are currently restricted to a numeric. For example:
MAXBUFFERSIZE: CARDINAL = 1024;
is represented in C as:
#define MAXBUFFERSIZE 1024
The NetRPC compiler also supports runtime pointers to data objects. A pointer data type is declared with the & symbol immediately before the data type. Pointer data objects are not allowed on procedure arguments. The way in which NetRPC allocates or de-allocates objects referred to by data pointers depends on how the objects are used. How objects are used is declared in the remote procedures.
Every remote procedure that applications can access must be declared in the NetRPC description. This declaration is called a remote procedure definition. Each procedure is declared as an object to NetRPC. The procedure can use parameters when invoked, return parameters if the procedure succeeds, and report an error status if the procedure fails. The arguments and results of a procedure are data objects; the argument types and number are specified in the description. Each argument and result can be either predefined or constructed.
Each procedure must have a name, an assigned argument type, and an identification number.
The name serves as the basic identifier for all variations of the procedure, whether called by the client or by another service.
To further define the meaning of the procedure, arguments must be typed as follows:
IN - The argument passes from client to service.
OUT - The argument passes from service to client.
INOUT - The same argument passes in both directions.
NetRPC assumes IN if you do not state the direction of an argument. The NetRPC compiler optimizes transport of the parameters between the client and the service with this information. To avoid wasted communications line bandwidth, use accurate types.
Each procedure must be assigned a unique procedure number ranging from 0 to 199. At runtime, NetRPC transparently uses the number to identify which procedure within a service should respond to a RPC.
For more information on remote procedure definitions, see your VINES Applications Toolkit documentation.
NetRPC uses IPC reliable messages for client-to-service and service-to-service communications. The NetRPC header follows the IPC long header, as shown in Figure 7-3.
The contents of the NetRPC header depends on the NetRPC message type. NetRPC message types are as follows:
![]()
Call message ![]()
Reject message ![]()
Abort message ![]()
Return message ![]()
Search message ![]()
Search-all message ![]()
Return address message
NetRPC message types are discussed in the following sections.
A client sends the NetRPC call message to a service to request a specific action. The call message constitutes a RPC request. In response to this request, the service sends a reject, abort, or return message. These message types are described in the following sections.
Table 7-3 describes the parameters contained in the header of call type messages.
The service returns the reject message to the client. The reject message indicates that the RPC could not be processed because of NetRPC error conditions specified in the header. Table 7-4 describes the parameters in the header of reject messages.
The rejection details parameter can have one of several values, depending on the type of error that caused the rejection. The values and their meanings are as follows:
0x0 - Unknown program number.
0x1 - Unknown version number.
0x2 - No such procedure number.
0x3 - Bad data type. For example, the procedure receives a LONG CARDINAL when it expects an integer.
0x4 to 0xFFFE - Reserved by Banyan.
0xFFFF - UNSPECIFIED error. 0xFFFF in NetRPC language is equivalent to -1.
The service returns the abort message to the client. The abort message indicates that the RPC aborted because of conditions specified in the abort message header. Table 7-5 describes the parameters in the header of abort messages.
The service returns the results of the RPC to the client in the return message. The return message indicates successful completion of the processing of the service request. Table 7-6 describes the parameters in the header of return messages.
With the NetRPC search message, a client locates a particular type of distributed service. Using a well-known port associated with the service, NetRPC broadcasts the message to all instances of the distributed service within a certain range of the client. The search message is a record data type, variable in length. Table 7-7 describes the parameters contained in the header of search messages.
The NetRPC search-all message is similar in function to the search message. Whereas the client uses the search message to locate any one instance of a distributed service (for example, StreetTalk), the client uses the search-all message to locate a set of instances of the service. The search-all message is a record data type, variable in length. Table 7-8 describes the parameters in the header of search-all messages.
The first instance of a service to respond to a search-all message is the one that the client uses. The client drops subsequent responses.
A service returns the return address message to a client in response to a search or search-all message. The return address message contains the service's port address. The return address message is a record data type, variable in length. Table 7-9 describes the parameters in the header of return address messages.
NetRPC Protocol Implementation Notes
NetRPC currently uses the IPC reliable message service of the transport layer. Typically, the remote operation completes and returns control (and possibly values) to the caller. However, if the remote service or server terminates or becomes unreachable while processing a remote request, the caller uses timeouts to detect the service's lack of response. The timeout value is based on the expected service time in the NetRPC specification file and the estimated roundtrip communications delay time. The expected service time is specified by the application developer. The estimated roundtrip communications delay time is automatically calculated by IPC.
When a NetRPC-based application, such as a client, is compiled, underlying communications IPC communications functions are built in. For example, on VINES servers, VINES socket communications functions are built in to the application.
For example, when a client calls a service, the client supplies the port number of the service. If an IPC socket is not already open, NetRPC opens one using the VnsOpenSocket communications function. When the client sends a message, NetRPC calls VnsSocketSend and includes the port number of the destination service. NetRPC allocates a buffer to process the message. The msg field of the socket request block points to this buffer, which is used to both send and receive during communication with the service. To receive messages, NetRPC calls VnsSocketReceive. See the VINES Service Developer's Guide for more information on VINES socket functions.
Figure 7-4 shows how NetRPC interfaces with IPC.
Procedure arguments in the call message record are packed. NetRPC includes only those arguments that are relevant for the direction (IN, OUT, INOUT) of the message. For example, for a service request message transmitted from a client to a service, only the IN or INOUT arguments are packed. Arguments of parameter type OUT are not represented. On the service side, only OUT and INOUT arguments are packed.
All procedure argument values in the NetRPC message are formatted in network standard form. Bytes are numbered in the data message, starting at byte 0 (zero). Multibyte fields are organized with the high-order (most significant) byte as the lowest-numbered byte in the field.
All packed procedure arguments in the NetRPC message occupy the same amount of space as the local representations of the specified data type, with the following exceptions:
![]()
Pointers to objects are not passed. All pointers are not referenced and the associated objects are passed. ![]()
Objects of data type string are packed with a 2-byte prefix. The prefix indicates the length of the string and is followed by the elements of the string. The value of the length field is equal to the number of relevant byte positions of the string, not including the null terminator. The packed string within the message is terminated by a null byte only when the number of relevant characters of the string is an odd-numbered value. ![]()
Only the relevant number of elements for variable-length data types (for example, sequence types) are packed in the NetRPC message.
NetRPC makes RPCs appear exactly the same as local procedure calls. To create this appearance, the compiler creates a C language runtime environment so that neither clients nor services can tell whether a particular call is remote or local.
This section briefly discusses the client and service views of communication and how arguments are passed at NetRPC runtime. For more information on NetRPC at runtime, see the VINES Service Developer's Guide.
Clients use communications ports to identify remote services. These ports are of type IPCPORT, a C type definition that corresponds to a 16-byte array. Ports should be treated as a unit. The first argument of all RPCs must be the address of the remote port where the procedure should be executed. This port can be fabricated, as in a broadcast address, or can be obtained from the StreetTalk naming system.
In VINES networks, NetRPC and StreetTalk work together to help clients locate services. For example, a service obtains its own IPC port from NetRPC and registers it with StreetTalk. The client can then use StreetTalk to look up the service's port. The client then supplies the service IPC port when it calls the service.
The caller is suspended until the call completes or an error returns. This makes the semantics of remote calls closely correspond to local procedure calls. Note that when the tasking system is used with NetRPC requests, only the currently running task is suspended.
Procedures defined in NetRPC are invoked from a client as follows:
status = <procedure> (<remoteport>, <arg2>, ... <argn>);
Status is a CARDINAL status code that represents one of the following statuses:
![]()
Status of the actual remote procedure ![]()
Status of the NetRPC runtime system when it attempts to perform the functions
arg2 is the first argument in the NetRPC specification.
VINES supports a variation of the Microsoft® core and extended Server Message Block (SMB) file-sharing protocol. VINES SMB is a file-sharing protocol for communications between DOS and OS/2 redirectors and file services on VINES and ENS for UNIX servers.
SMB file-sharing communications are performed over SPP connections. The SMB header follows the SPP header, as shown in Figure 7-5.
Note: The Banyan word size is 2 bytes.
For more information on SMB protocol formats, see the SMB specifications from Microsoft.
VINES SMB Protocol Implementation Notes
This section describes Banyan support for SMB commands and error codes.
Core Commands
Table 7-10 lists the core SMB command support as of VINES 5.5. For descriptions of these commands, see the SMB specifications from Microsoft.
Extended Commands
Table 7-11 lists the extended SMB command support as of VINES 5.5. For descriptions of these commands, see the SMB specifications from Microsoft.
VINES SMB Commands
Table 7-12 lists the VINES SMB commands as of VINES 5.5. These commands were developed by Banyan for the VINES implementation of SMB.
Error Codes
The VINES SMB implementation makes use of standard Microsoft SMB error codes. See the SMB specifications from Microsoft for more information.