DOCERR: Important Information on RPC 1.0 Missing from the Docs

• Microsoft Windows Software Development Kit (SDK) for Windows for Workgroups version 3.11
• Microsoft Win32 Software Development Kit (SDK) for Windows NT version 3.1

SUMMARY

This article documents important information about Microsoft RPC version 1.0 that is not included in the Microsoft RPC programming documentation or in Help. This information is identical to the information contained in the file RPCREAD.ME included with the Win32 SDK for Windows NT version 3.1.

MORE INFORMATION

Introduction

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

• MIDL compilers for Microsoft Windows NT and Microsoft Windows 3.x.
• C/C++ language header files (.H) and run-time libraries (.LIB and .DLL) for Microsoft Windows NT, Microsoft Windows 3.x, and MS-DOS.
• Sample programs for Microsoft Windows NT, Microsoft Windows 3.x, Microsoft Windows for Workgroups, and MS-DOS.
• RPC reference Help files, Windows Write files, and PostScript files.

Installation

The Microsoft Win32 SDK installs the components of the Microsoft RPC toolkit as part of its standard installation. No additional installation is required.

To develop client-side distributed applications for MS-DOS, Microsoft Windows 3.x, and Windows for Workgroups version 3.1, you must install the Microsoft Windows 3.x/MS-DOS version of the RPC toolkit. Cross-compilation of Windows version 3.x and MS-DOS clients with Microsoft Windows NT requires a 16-bit C compiler in the Microsoft Windows NT environment. This development environment is not installed during RPC SDK setup. The Microsoft RPC toolkit for MS-DOS and Microsoft Windows 3.x requires:

• A 16-bit compiler such as Microsoft Visual C++ Development System for Windows or the Microsoft C/C++ 7.0 compiler.
• One of the following:

      - Microsoft Windows for Workgroups version 3.1 (or later) with named
        pipes, NetBIOS, or TCP/IP.
  

        -or-
  

      - Microsoft LAN Manager version 2.1 (or later) with named pipes,
        NetBIOS, or TCP/IP.
  

        -or-
  

      - DEC PATHWORKS 4.0 (or later) with NetBIOS, TCP/IP, or DECNet.
  

        -or-
  

      - Novell Netware 3.x with SPX.
  

        -or-
  

      - Other networking software compatible with the Windows Sockets API
        standard.
  

When you install the RPC toolkit in a directory different from the directory you used for Microsoft C/C++ version 7.0, you must set the environment variables INCLUDE, LIB, and PATH to point to the directories that contain the RPC header files, libraries, and DLLs and binaries, respectively. You cannot install the RPC toolkit in the same directory as the Visual C++ compiler binaries because of name conflicts.

RPC Documentation

The following Microsoft RPC version 1.0 reference materials are available in Windows Write format and in PostScript file format:

Microsoft RPC Programmer's Guide and Reference:

• Part I: Programmer's Guide
• Part II: MIDL Language Reference
• Part III: Run-Time API Reference
• Part IV: Installing RPC
• Part V: Appendixes

The following run-time and MIDL reference Help file is available on line:

   RPC.HLP   WinHelp MIDL and run-time API reference

Release Notes for MIDL compiler

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, marshaling from and unmarshaling 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

Release Notes for RPC Run-Time/Transport Libraries & Windows NT Services

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

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.

Release Notes for Installation & Configuration Issues for This Release

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

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:

1. Copy your executable files.

2. Copy Microsoft RPC run-time and transport DLLs.

3. Set Microsoft RPC-related registry entries as needed.

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-side 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

RPCNS.RPC      Microsoft RPC name-service provider
RPCNSLM.RPC    Microsoft RPC name-service 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

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

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

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

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

   \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

REFERENCES

RPCREAD.ME in \MSTOOLS\SAMPLES\RPC in Win32SDK for Windows NT version 3.1 on MSDN.