More Information about RPC version 1.0 for Chicago
________________________________________________________________________

This document contains important information about Microsoft RPC version 
1.0 that is not included in the Microsoft RPC programming documentation 
or in Help. 

Use Notepad to View This Document

To move through this document, press PAGE UP and PAGE DOWN or click the 
arrows at the top and bottom of the scroll bar along the right side of 
the window.

To print this document, choose the Print command from the File menu.

For help with using Notepad, press F1.


_______________________________________________________________________

Introduction

Microsoft RPC version 1.0 is a toolkit for developing network-aware 
distributed applications in C/C++.

Two versions of the toolkit are available, one for 32-bit development 
environments (Microsoft Windows NT and Chicago) and one for 16-bit 
development environments (Microsoft Windows 3.x, Windows for Workgroups 
3.1 and MS-DOS). Only the 32-bit version is provided with Chicago. The 
16-bit version is provided as part of the Win32 SDK. Each version of the 
RPC toolkit includes:

     *   MIDL compiler

     *   C/C++ language header files (.H) and run-time libraries (.LIB 
and .DLL)

     *   Sample programs

     *   WinHelp files

The RPC toolkit for the 32-bit development environment is installed with 
the SDK when the SDK is installed. No additional installation is 
required.

The following Microsoft RPC version 1.0 reference materials are 
available in Microsoft Word format:

     Microsoft RPC Programmer's Guide and Reference

The following WinHelp file is available on line:

     RPC.HLP   WinHelp MIDL and run-time API reference 

_______________________________________________________________________
0.0 The following release notes relate to the Chicago SDK.

0.1 Chicago supports RPC clients and RPC server applications

This release of RPC for Chicago supports both client and server 
applications that use the following protocol sequences:

     ncacn_nb_nb     NetBIOS over Microsoft NetBEUI
     ncacn_spx       Connection-oriented SPX

0.2 Chicago beta does not support name service and endpoint mapper

This beta release of Chicago does not support the Microsoft RPC name 
service provider and endpoint mapper. With this release, all clients 
that access Chicago server applications must use well-known endpoints.

1.0 The following release notes relate to the MIDL compiler and to 
building distributed applications.

1.1  Packing and Alignment Considerations

You must use the same packing and alignment settings (/Zp switch) for 
both the C compiler and the MIDL compiler. Using different packing 
levels for the two compilers causes undefined results. Specify the /Zp 
switch to verify that the correct packing and alignment settings are 
used on both compilers.

This release of the MIDL compiler does not support the switches /Zp1 and 
/Zp2 in the MIPS environment, although the compiler does not prevent the 
use of /Zp1 and /Zp2.

Use /Zp1 or /Zp2 for 16-bit client platforms. Objects of types with 
natural alignment greater than 2 that are allocated on the stack as 
local variables in the client application are not necessarily allocated 
on 4- and 8-byte boundaries by the C compiler. Because the C compiler 
does not guarantee alignment on the stack, marshalling from and 
unmarshalling into such objects may cause problems.

Generic stubs (/env generic) must be specified with /Zp1 or /Zp2 in 16-
bit client environments.  Generic stubs specified with /Zp1 or /Zp2 
cannot be used in the MIPS environment.  MIDL uses /Zp4 by default for 
generic stubs.

1.2  C Stub Source Code Causes Compilation Warnings

The stub files generated by the MIDL compiler may generate warnings when 
they are compiled at compiler warning-level 3 and higher. These warnings 
can generally be safely ignored.

When your C compiler does not use the same default character sign as the 
MIDL compiler, use the MIDL compiler switch /char to generate explicit 
declarations in the header file. For more information, see the Microsoft 
RPC programming documentation.

1.3 Use Six-Character Filenames on the FAT File System

Because RPC version 1.0 appends _C, _X, and similar extensions to 
filenames, limit your filenames to six characters or less. Filenames 
that total more than eight characters are too long for some file systems 
and can fail. 

1.4 Specifying Local and UUID Attributes

If the base IDL file contains no procedures, you don't have to specify 
local or UUID attributes.

1.5 MIDL Extra Server Files in the Windows 3.x/MS-DOS Environment

MIDL does not produce server files in the Windows 3.x/MS-DOS 
environment. For this reason, if you specify the /env switch as /env dos 
or /env win16, server stubs are not produced. To produce server stubs, 
specify that the /env switch is either /env win32 or /env generic.

1.6 Working with Visual C++ on 16-Bit Machines

Do not install the 16-bit RPC toolkit in the same directory as Visual 
C++. MIDL requires the Microsoft C 7.0 front end for C preprocessing. 
The installer will install the Microsoft C 7.0 front end if needed. Use 
the /cpp_cmd switch to make sure MIDL is using the right C compiler.

1.7 Memory Leak Possible with Multiple Context Handles

Memory can leak when data argument(s) precede context-handle argument(s) 
and the call is directed by another handle. The leak happens on the 
server side if the data requires memory allocation and if the context 
handle that is used (as opposed to initialized) is invalid. The stub 
raises an exception as it is supposed to, but it doesn't do the clean 
up.

1.8 Use Zero or Positive Values for the size_is and length_is Variables

You must use a zero or a positive value for the size_is and length_is 
variables. A negative value for the size_is or length_is variable causes 
an exception.

1.9 RPC Cannot Pass More than 63K Worth of Data on 16-Bit Platforms

An MS-DOS or Windows 3.x system cannot pass more than 63K worth of data 
in a single remote procedure call. Trying to pass more than 63K worth of 
data results in undefined behavior.

1.10  Windows 3.x Applications Using the [callback] Attribute

If you use the [callback] attribute for a procedure specified in the IDL 
file and if your application runs with Windows 3.x, you must compile all 
stubs with the /GA C-compiler switch. Note that the /GA switch should 
not be used for Windows callback functions (as opposed to RPC callback 
functions) that are called in the context of another process.

1.11  Building RPC Samples with Visual C++ for Microsoft Windows NT

You can build RPC applications with the Visual C++ SDK for Microsoft 
Windows NT using the RPC*.H files distributed with that SDK. To build 
RPC samples with Visual C++ for Windows NT, add the following definition 
to RPC.H (this applies to Intel processors only):

     #define     _CRTAPI1    _cdecl

_______________________________________________________________________

2.0 The following release notes are related to the RPC run-time 
libraries, transport libraries, and Windows NT services provided with 
Microsoft RPC version 1.0.

2.1 RpcServerUseAllProtseqs Requires a Null Security Descriptor 

The RpcServerUseAllProtseqs security-descriptor parameter must be set to 
NULL in this release of Microsoft RPC version 1.0. The null parameter 
allows everyone access.

2.2 Named-Pipes Security Descriptor

Named pipes (ncacn_np) allows everyone access when a null security 
descriptor is supplied. This accessibility is independent of whether or 
not the account used to start the server has a default ACL.

2.3 Multiple Networks

The Microsoft Locator does not work with a router.

2.4 RpcNsBindingExport IP Addresses

If a server has two IP addresses and as a result is on two subnets, 
RpcNsBindingExport adds only one of the two addresses to the name 
service. For this reason, clients on one of the two networks cannot 
import a valid handle to that server. Clients that already know the 
server address will work using either well-known or dynamic endpoints. 

2.5 SPX Transport Limitations

The MS-DOS SPX transport does not function in a Windows DOS box or 
Windows NT DOS box.  The Windows SPX transport does not function in 
Windows standard mode or in emulation mode with Windows NT.

2.6 All Machines Must Use the Same SPX Packet Size

To use the ncacn_spx protocol sequence (RPC over SPX), both the client 
and the server must use the same maximum IPX packet size.  Otherwise, 
multipacket RPC calls will fail with RPC_S_CALL_FAILED.  To adjust the 
packet size on a machine running MS-DOS, Windows 3.x, or Windows for 
Workgroups, add the following line to your NET.CFG or SHELL.CFG file:

      IPX PACKET SIZE LIMIT=xxxx
 where
      xxxx is the packet size in bytes.

Consult your Novell documentation for more information.  Note that some 
older drivers do not support setting IPX PACKET SIZE LIMIT.

To adjust the maximum packet size on machines running Windows NT, use 
REGEDT32.EXE to set HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ 
Services\NWLINKIPX\NetConfig\Driver01\MaxPktSize to the proper value. 
Consult the Windows NT Resource Kit for more information on the 
registry.

2.7  Windows 3.x Applications Using TCP/IP Must Call RpcWinSetYieldInfo

Applications based on Windows 3.x that use TCP/IP (ncacn_ip_tcp) must 
call the RpcWinSetYieldInfo routine.  Applications making RPC calls that 
don't call RpcWinSetYieldInfo will always hit an exception.  The 
exception occurs because Windows Sockets API standard requires that 
applications yield while using the network.

2.8 When Writing MS-DOS Applications, Avoid Calling _exit Directly 

Always write your RPC applications for MS-DOS to call the complete C-
library termination function exit or _cexit rather than the "quick" C-
library termination function _exit or _c_exit because the quick-
termination functions do not call the atexit function. The MS-DOS RPC 
run-time libraries use the atexit function to clean up system resources.  
When you call the _exit or _c_exit function, the atexit function is not 
invoked and resources are not freed correctly.
_______________________________________________________________________

3.0 The following release notes are related to installation and 
configuration issues:

3.1  Using Microsoft RPC with Microsoft Windows for Workgroups

To successfully run Microsoft RPC distributed applications with 
Microsoft Windows for Workgroups version 3.1, you must use the Windows 
for Workgroups network services.  Stop all real-mode network services 
before starting Windows for Workgroups. At the MS-DOS prompt, enter:

     net stop workstation /y
     win

3.2  Creating Installation Disks for Your Distributed Application

After you have developed your distributed application using Microsoft 
RPC, you should provide a way for your users to install your 
application.

To enable your users to install your application, perform the following 
steps when installing RPC:
     *   Copy your executable files
     *   Copy Microsoft RPC run-time and transport DLLs
     *   Set Microsoft RPC-related registry entries as needed

To provide an installation tool for your users, use the Microsoft Setup 
Toolkit for Windows. Microsoft Setup provides important version-control 
features that prevent users from overwriting newer versions of the RPC 
run-time libraries with older, incompatible versions.

You can also use the template batch files provided with Microsoft RPC 
for MS-DOS and Windows 3.x to help your users install your distributed 
applications. The files DRUNDISK.BAT and WRUNDISK.BAT copy the Microsoft 
RPC Setup program and associated files and direct the Microsoft RPC 
Setup program to install all needed RPC system files. You must customize 
the .INF file for your application. For more information about changing 
the .INF file, see the documentation for the Microsoft Setup Toolkit for 
Windows.

If you use another installation method, you should implement some form 
of version control. Version-control methods ensure that you do not 
distribute incompatible versions of the RPC run-time and transport 
libraries that can cause software errors in your application and other 
applications.

Some files include an embedded version-control number for use by the 
Setup Toolkit for Windows. These files are noted in the lists below.

The following Microsoft Windows 3.x RPC files should be installed in the 
system directory or in a directory specified by the LIBPATH environment 
variable:

     DNETAPI.DLL    Non-Microsoft environments for DEC PATHWORKS
                    interoperability with Microsoft LAN Manager
     NETAPI.DLL     Microsoft LAN Manager transport DLL;
                    has version number for use with Microsoft Setup
     RPCNS1.DLL     Microsoft RPC name-service provider
     RPCRT1.DLL     Microsoft RPC client run-time library
     RPC16C1.DLL    RPC transport DLL for client-side named pipes
     RPC16C3.DLL    RPC transport DLL for client-side WinSock TCP/IP 
     RPC16C3X.DLL   RPC transport DLL for client WSOCKETS.DLL TCP/IP 
     RPC16C4.DLL    RPC transport DLL for client-side DECnet
     RPC16C5.DLL    RPC transport DLL for client-side NetBIOS
     RPC16C6.DLL    RPC transport DLL for client-side SPX

The following MS-DOS RPC files should be installed in a directory that 
is specified by the PATH environment variable:

     RPCNS.RPC      Microsoft RPC name-service provider
     RPCNSLM.RPC    Microsoft RPC NS provider LAN Manager support
     RPCNSMGM.RPC   Microsoft RPC name-service provider support module
     RPC16C1.RPC    RPC transport DLL for client-side named pipes
     RPC16C3.RPC    RPC transport DLL for client-side TCP/IP
     RPC16C4.RPC    RPC transport DLL for client-side DECnet
     RPC16C5.RPC    RPC transport DLL for client-side NetBIOS
     RPC16C6.RPC    RPC transport DLL for client-side SPX

You need not install 32-bit versions of the Microsoft RPC run-time 
libraries and transports. Microsoft 32-bit platforms support Microsoft 
RPC version 1.0.  If you want to run Microsoft Windows 3.x or MS-DOS RPC 
applications with Microsoft 32-bit platforms, install the above RPC DLLs 
on the system.

Setting RPC Registry Entries

Your installation procedure should set any registry entries your 
application needs. Registry entries are used by the RPC run-time 
libraries and the RPC name-service provider to obtain information about 
the transport an application intends to use.

By default, MS-DOS and Windows 3.x registry entries are present in the 
file RPGREG.DAT in the root directory of the boot drive.  You can use a 
different file by setting the value of the environment variable 
RPC_REG_DATA_FILE to the path and filename of the alternate file.

The RPC Setup program for MS-DOS and Microsoft Windows 3.x creates the 
registry file RPCREG.DAT. If you write your own installation program, 
you must create RPCREG.DAT and set appropriate entries for the name-
service and NetBIOS transports supported in that environment. 

If the Microsoft Locator is the name-service provider:

    \Root\Software\Microsoft\Rpc\NameService\Protocol=ncacn_np
    \Root\Software\Microsoft\Rpc\NameService\NetworkAddress=\\.
    \Root\Software\Microsoft\Rpc\NameService\Endpoint=\pipe\locator
    \Root\Software\Microsoft\Rpc\NameService\DefaultSyntax=3

If CDS is the name-service provider via NSID:

    \Root\Software\Microsoft\Rpc\NameService\Protocol=ncacn_ip_tcp
    \Root\Software\Microsoft\Rpc\NameService\NetworkAddress=name of NSID
                                                            host
    \Root\Software\Microsoft\Rpc\NameService\Endpoint=
    \Root\Software\Microsoft\Rpc\NameService\DefaultSyntax=3

The NetBIOS transport entries have the following form:

    \Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_<A><B>=<C>

where
     <A> is the NetBIOS sub-protocol sequence (nb, ipx, or tcp).
     <B> is a unique digit for each protocol sequence.
     <C> is the lana number.

For example, if you have two net cards in a system, running NetBEUI on 
both and TCP/IP on one, and the lana numbers on the system are 
configured as NetBEUI on card0 is 0, TCP/IP on card0 is 1, and NetBEUI 
on card1 is 2, then the RPC NetBIOS registry entries are:

     \Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_nb0=0
     \Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_nb1=2
     \Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_tcp0=1

For more information about the strings generated in the file RPCREG.DAT, 
run Microsoft RPC Setup and inspect the strings.

-----------------------------------------------------------------------
Microsoft, MS, and MS-DOS are registered trademarks and Microsoft 
Windows, Win32, and Microsoft Windows NT are trademarks of Microsoft 
Corporation.

Portions of this documentation are provided under license from Digital 
Equipment Corporation. All rights reserved.  DEC is registered trademark 
and DECnet and PATHWORKS are trademarks of Digital Equipment 
Corporation.  Intel is a registered trademark of Intel Corporation.
