Microsoft KB Archive/129142

{|
 * width="100%"|

DOCERR: Important Information on RPC 1.0 Missing from the Docs

 * }

Q129142

-

The information in this article applies to:


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

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.

The Win32 SDK contains the Microsoft Windows NT and Microsoft Windows 3.x versions of the RPC SDK.

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.

To install the Microsoft Windows 3.x/MS-DOS version of the RPC toolkit, run the Setup program in the directory MSTOOLS\RPC_DOS. To start the Setup program, choose the Run command from the File menu in the Microsoft Windows 3.x Program Manager.

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

Use the PostScript files to print individual chapters of the documentation on your PostScript printer.

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

"RPC.HLP WinHelp MIDL and run-time API reference" RPC sample-program source files are available in the directory MSTOOLS\SAMPLES\RPC. MS-DOS and Microsoft Windows 3.x versions of some samples are available when you install the Windows 3.x/MS-DOS version of the RPC toolkit. The file MSTOOLS\SAMPLES\RPC\README.TXT describes the available samples.

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

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.

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-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 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 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 You need not install the Microsoft Windows NT versions of the Microsoft RPC run-time libraries and transports. Microsoft Windows NT computers support Microsoft RPC version 1.0. If you want to run Microsoft Windows 3.x or MS-DOS RPC applications with Microsoft Windows NT, 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=NSID host name \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_&lt;A&gt;&lt;B&gt;=&lt;C&gt; Where:  is the NetBIOS sub-protocol sequence (nb, ipx, or tcp).

 is a unique digit for each protocol sequence.

 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.