--- mstools/samples/rpc/rpcread.me 2018/08/09 18:21:57 1.1.1.1 +++ mstools/samples/rpc/rpcread.me 2018/08/09 18:24:12 1.1.1.2 @@ -1,853 +1,455 @@ -More Information about Microsoft RPC version 1.0 -____________________________________________________________ +More Information about RPC version 1.0 +________________________________________________________________________ -This document contains important information about Microsoft RPC version -1.0 that is not included in the Microsoft RPC Programmer's Guide and -Reference or in help. - -Using 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 on using Notepad, press F1. - -____________________________________________________________ - -Introduction - -Microsoft RPC version 1.0 is a toolkit for developing network-aware -distributed applications in C/C++. The RPC toolkit includes: - - o MIDL compilers for Microsoft Windows NT and MS-DOS - - o C/C++ language header files (.H) and run-time libraries - (.LIB and .DLL) for Microsoft Windows NT, Microsoft - Windows, and MS-DOS - - o Sample programs for Microsoft Windows NT, Microsoft - Windows, Microsoft Windows for Workgroups, and MS-DOS - - o RPC reference Help files and PostScript(TM) files - -The Microsoft Windows NT SDK contains the Microsoft Windows NT and -Microsoft Windows 3.x/MS-DOS versions of the RPC SDK. - -Installation - -The Microsoft Windows NT SDK installs the components of the Microsoft -Windows NT RPC SDK 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 3.x and MS-DOS clients on 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 SDK for MS-DOS and Microsoft Windows requires: - - o Microsoft C/C++ version 7.0 - - o DOS protected-mode interface (DPMI) server that - supports version 0.9 or later of the DPMI specification and - the MS-DOS extensions to the DPMI (Microsoft Windows or - Windows for Workgroups versions 3.1) - - o Either Microsoft Windows for Workgroups version 3.1 or - Microsoft LAN Manager version 2.1 with NetBEUI, Named Pipes, - or TCP/IP - -To install the Microsoft Windows and MS-DOS version of the RPC toolkit, -run the Setup program in the directory MSTOOLS\ RPC_DOS\NSETUP. 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 SDK 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. When you install the RPC SDK in the same directory as the -directory you used for Microsoft C/C++ version 7.0, these environment -variables are already set by the C/C++ version 7.0 installation program. - -RPC Documentation - -The following Microsoft RPC version 1.0 reference materials are -available in published book form and in PostScript file format: - - Microsoft RPC Programmer's Guide and Reference - Part I: Programmer's Guide - Part II: Run-time API Reference - Part III: MIDL Language Reference - -Use the PostScript files to print individual chapters of the -documentation on your PostScript printer. - -The following run-time and MIDL reference Help files are available on -line: - -RPC10WH.HLP WinHelp run-time API reference -RPC10QH.HLP QuickHelp run-time API reference -MIDL10WH.HLP WinHelp MIDL reference -MIDL10QH.HLP QuickHelp MIDL reference - -RPC sample-program source files are available in the directory -MSTOOLS\SAMPLES\RPC. MS-DOS and Microsoft Windows versions of some -samples are available when you install the MS-DOS and Microsoft Windows -3.x version of the RPC SDK. You must compile the client samples on the -client computer. The file MSTOOLS\SAMPLES\RPC\README.TXT describes each -sample. - -____________________________________________________________ - -Contents - -These release notes contain additional information on the following -topics: - -1.0 DCE interoperability issues - -2.0 Gateway required for DCE NSI API interoperability - -3.0 Using Microsoft RPC with Microsoft Windows for Workgroups - -4.0 Packing and alignment considerations - -5.0 MIDL switch "-env generic" not supported - -6.0 C stub source code causes compilation warnings - -7.0 Updated command line help for the MIDL compiler - -8.0 Creating installation disks for your application - -9.0 Running the locator and endpoint mapper - -10.0 Updating RPC registry entries for new NetBIOS configurations - -11.0 Support for multiple locators - -12.0 NetBIOS requires larger MS-DOS application stack - -13.0 Using the new C _stdcall calling convention with RPC - -14.0 RpcWinSetYieldInfo not supported for Win32 applications - -15.0 Uuidgen utility provided for Microsoft Windows NT - -16.0 Use NULL security descriptor with RpcUseAllProtseqs - -17.0 Leading zeroes in version numbers do not create unique values - -18.0 Const initialization - -19.0 Include three header files in your distributed applications - -20.0 Context handle issues - -21.0 Only one error_status_t parameter allowed - -22.0 Unsized arrays issues - -23.0 Separate in, out parameters to avoid memory orphaning - -24.0 Small model application development not supported - -25.0 Single process cannot be client, server using NetBIOS - -26.0 Escape sequences not correct in the generated header files - -27.0 Ncalrpc transport issues - -28.0 RpcNsBindingExport requires non-null interface parameter - -29.0 Configuring RPC name service for LAN Manager networks -30.0 Length_is applied to pointer causes error -____________________________________________________________ +This document contains important information about Microsoft RPC +version 1.0 that is not included in the Microsoft RPC programming +documentation or in Help. -1.0 DCE interoperability issues -The Microsoft RPC endpoint mapper and run-time libraries are compatible -with the DCE endpoint mapper interface. +Use Notepad to View This Document -When you use the DCE Cell Directory Service, you must use a gateway to -the DCE server (see release note 2.0). +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. -Full pointers (pointers associated with the attribute [ptr]) are not -completely implemented in Microsoft RPC version 1.0. To allow -portability of DCE applications, the MIDL compiler treats full pointers -as unique pointers, which means that aliasing is not supported. The use -of full pointers that cause aliasing can lead to undefined results. - -DCE host names are case-sensitive. Specify the hostname exactly as it -appears or the client will not be able to locate the host server. - -In DCE-compatibility mode, the MIDL compiler provided with this beta -release of Microsoft RPC version 1.0 incorrectly accepts handles in -positions other than the first parameter. The MIDL compiler in DCE- -compatibility mode incorrectly does not accept BOOLEAN as a switch type. - -This beta release does not support the name service environment variable -RPC_DEFAULT_ENTRY_NAME, but it does provide an alternate method to -specify the default syntax. Microsoft RPC configuration settings are -available in the Microsoft Windows NT registry and in the MS-DOS and -Microsoft Windows 3.x file RPCREG.DAT. To change the default syntax, set -the registry entry SOFTWARE\Microsoft\Rpc\NameService\DefaultSyntax. - -Other differences between the Microsoft and DCE implementations are -documented in the RPC Programmer's Guide and Reference. - -2.0 Gateway required for DCE NSI API interoperability - -When using Microsoft RPC version 1.0 for Microsoft Windows in an OSF DCE -environment, the DCE Cell Directory Service (CDS) is used as the RPC -name service. However, the OSF has not yet released a specification of -the protocol used to access the CDS. To allow interoperation between DCE -computers and RPC client applications that call RPC name service API -functions, you must use a gateway to the DCE CDS. - -To help you develop such a gateway, the Microsoft RPC SDK provides an -interface for a gateway protocol in the files SAMPLES\NS\CDS\NSICLT.IDL, -NSSVR.IDL, and NSICOM.IDL, and provides the client-side implementation -of this gateway protocol in RPCNS.DLL. One such implementation of the -server side gateway is currently available in the Digital Equipment -Corporation DCE Starter Kit. - -To use the gateway so that your RPC application can interoperate with -DCE RPC applications: - -1) Verify that the gateway is started on the DCE host - -2) Verify that the client is running the TCP/IP transport - -3) (Microsoft Windows NT only) Set the registry entry -Software\Microsoft\Rpc\NameService\ServerNetworkAddress to a string of -the form "; ...", -where is the ip address of the nth gateway in -the list. - -4) Set the following registry entries under Software\ -Microsoft\Rpc\NameService to the following values: - -Entry Value - -Protocol ncacn_ip_tcp -NetworkAddress ; ... -Endpoint - -To change registry entry settings on Microsoft Windows NT, use the -REGEDIT utility. On MS-DOS and Microsoft Windows, edit the text file -RPCREG.DAT. - -3.0 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 - -4.0 Packing and Alignment Considerations - -You must use the same packing and alignment settings (/Zp switch) with -both the C compiler and the MIDL compiler. Using different packing -levels for each compiler causes undefined results. Default values are -set for each target operating system. You can specify the /Zp switch to -verify that the correct packing and alignment settings are used on both -compilers. - -For Microsoft Windows 3.x and MS-DOS-based distributed applications, use -one of the following two methods: - -a. Compile using /Zp2 with both the MIDL and C compilers - -b. Compile using any /Zp level (use the same level for both the MIDL -and C compilers; the level /Zp4 produces the most efficient marshalling -code) and add the following code to the files RPC.H and RPCNDR.H: - -#pragma pack(2) /* at start of rpc.h and rpcndr.h */ -... -#pragma pack () /* at end, restore default level */ - -5.0 MIDL switch "-env generic" not supported - -The MIDL compiler environment switch "-env generic" is not supported in -this version. When your target operating system is the same as the -development environment, you do not have to specify an environment -switch; the default settings are correct. Otherwise, use the specific -environment switch that corresponds to your target application -environment: "-env win32", "-env win16", or "-env dos". - -The MIDL compiler can generate C code for other platforms when you use -these switches. However, to cross-compile the C code for other -platforms, you must configure your C development environment. For -example, to cross-compile MS-DOS applications on a Microsoft Windows NT -computer, you must set up your computer to use a 16-bit C compiler, -include the correct header files, and link with the appropriate -libraries. A development environment that supports MS-DOS cross- -compilation is not provided during Microsoft Windows NT installation. - -6.0 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. - -Unsigned character string arguments generate "incompatible pointer -assignment warnings" when you compile the stubs. The C run-time library -functions use char * arguments rather than unsigned char * arguments. - -When your C compiler does not use the same default character sign as the -MIDL compiler, use the MIDL compiler switch /char to generated explicit -declarations in the generated file. For more information, see the Microsoft -RPC Programmer's Guide and Reference. - -Compiler warning messages about unreferenced local variables, mismatched -comparisons between integral types, and mismatched pointer assignments -in stubs can be safely ignored. - -7.0 Updated command line help - -The updated help text for the MIDL compiler appears as follows: - - -MIDL COMPILER OPTIONS- - -MODE- -/ms_ext Microsoft extensions mode -/app_config Application configuration mode -/implicit_local Assume non-remote data is [local] - - -INPUT- -/acf filename Specify the attribute configuration file -/I directory Specify directory for import and include files -/import ms_ext Support only used types; one file -/import ms_nt Support only used types; multiple files -/import osf Assume imported IDL files are compiled separately -/no_def_idir Ignore the current and the INCLUDE directories - - -OUTPUT FILE GENERATION- -/client all Generate client stub and aux files -/client aux Generate client auxiliary file only -/client none Generate no client files -/client stub Generate client stub file only -/out directory Destination directory for output files -/server all Generate server stub and aux files -/server aux Generate server aux file only -/server none Generate no server files -/server stub Generate server stub file only -/syntax_check Check syntax only; do not generate output files -/Zs Check syntax only; do not generate output files - - -OUTPUT FILE NAMES- -/caux filename Specify client auxiliary file name -/cstub filename Specify client stub file name -/cswtch filename Specify switch stub file name -/header filename Specify header file name -/saux filename Specify server auxiliary file name -/sstub filename Specify server stub file name - - -C COMPILER AND PREPROCESSOR OPTIONS- -/cpp_cmd cmd_line Specify name of C preprocessor -/cpp_opt options Specify additional C preprocessor options -/D name[=def] Pass #define name, optional value to C preprocessor -/no_cpp Turn off the C preprocessing option -/U name Remove any previous definition (undefine) - - -ENVIRONMENT- -/char signed C compiler default char is signed -/char unsigned C compiler default char is unsigned -/char ascii7 Char values limited to 0-127 -/env dos MS-DOS client -/env win16 Microsoft Windows 16-bit (Win 3.x) -/env win32 Microsoft Windows 32-bit (NT) -/env generic Produce one header for all environments - - -ERROR AND WARNING MESSAGES- -/error all Check for all types of errors -/error allocation Check for out of memory errors -/error enum Check for errors converting long, short enum -/no_warn Suppress compiler warning messages -/W{0|1|2|3|4} Warning level 0-4 (default = 1) -/warn{0|1|2|3|4} Warning level 0-4 (default = 1) -/WX Treat all warnings as errors - - -OPTIMIZATION- -/pack {1|2|4|8} Designate packing level of structures -/Zp{1|2|4|8} Designate packing level of structures - - -MISCELLANEOUS- -@response_file Accept input from a response file -/? List MIDL compiler switch settings -/confirm Display options without compiling MIDL source -/help Display a list of MIDL compiler switches -/prefix "s1" "s2" Replace default suffix "s1" with prefix "s2" - -8.0 Creating installation disks for your application - -Your distributed application's installation program must set up the RPC -runtime for users. Two batch files help you create RPC run-time -installation disks that can accompany your distributed application. -These batch files create installation disks that contain the Setup -program and the Microsoft RPC run-time libraries, allowing you to -distribute the Microsoft RPC run-time libraries with your distributed -application. The following two batch files are provided: - -wrundisk.bat creates Microsoft Windows/MS-DOS run-time install disk -drundisk.bat creates MS-DOS-only run-time install disk +To print this document, choose the Print command from the File menu. -8.1 Creating installation disks for Microsoft Windows applications +For help with using Notepad, press F1. -Insert a formatted, blank floppy disk in the destination drive. Start -the installation disk utility by typing "wrundisk" followed by the -optional source and destination drive names. The wrundisk.bat file uses -the following syntax: -wrundisk [source:[path] [dest:]] +_______________________________________________________________________ -where +Introduction -source is a disk or directory that contains the compressed files that -are provided in the Microsoft Windows NT SDK directory -\mstools\rpc_dos\disk1. +Microsoft RPC version 1.0 is a toolkit for developing network-aware +distributed applications in C/C++. The RPC toolkit includes: -dest is a drive name specifying the drive that contains the formatted, -blank floppy disk. + * MIDL compilers for Microsoft Windows NT and Microsoft Windows + 3.x/MS-DOS -For example,"wrundisk c:\nt\mstools\rpc_dos\disk1 a:" copies the -compressed files to the floppy disk in the drive A. + * C/C++ language header files (.H) and run-time libraries + (.LIB and .DLL) for Microsoft Windows NT, Microsoft + Windows 3.x, and MS-DOS -Your application user can then insert the resulting installation disk in -her computer's floppy drive and run its Setup from Microsoft Windows to -install the RPC run-time libraries for Microsoft Windows and MS-DOS. + * Sample programs for Microsoft Windows NT, Microsoft + Windows 3.x, Microsoft Windows for Workgroups, and MS-DOS -8.2 Installation disks for MS-DOS Distributed Applications + * RPC reference Help files, Windows Write files, and PostScript + files -The drundisk utility copies files from an installed RPC SDK. To ensure -that all MS-DOS loadable transports are present on the run-time -installation disk, you must select all loadable transports at the time -you install the Microsoft RPC SDK. +The Win32 SDK contains the Microsoft Windows NT and Microsoft Windows 3.x/MS- +DOS versions of the RPC SDK. -Insert a formatted, blank floppy disk in the destination drive. Start -the installation utility by typing "drundisk" followed by the optional -source and destination drive names. The drundisk.bat file uses the -following syntax: -drundisk [directory [dest:]] +Installation -where directory is the name of the directory that contains all loadable -transport (.RPC) files and all name service dynamic link libraries. +The Microsoft Win32 SDK installs the components of the Microsoft RPC toolkit +as part of its standard installation. No additional installation is required. -For example, the command "drundisk c:\lanman.dos\netprog a:" copies the -MS-DOS run-time libraries, the loadable transport files, and name -service DLLs from the C hard drive to the floppy disk in drive A. Your -application user can then use the Setup program on the run-time -installation disk to install the RPC run-time libraries. +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 +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 + * Microsoft LAN Manager version 2.1 (or later) with named + pipes, NetBIOS, or TCP/IP + * DEC PATHWORKS 4.0 (or later) with NetBIOS, TCP/IP, or DECNet + * Novell Netware 3.x with SPX + * 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. -9.0 Running the locator and endpoint mapper -In this release of Microsoft RPC version 1.0, the locator and endpoint -mapper are not provided as services but as programs that you must start -from the Microsoft Windows NT command line. The locator is the Microsoft -implementation of the RPC name service independent API functions (NSI). -The endpoint mapper allows the use of dynamic endpoints. +RPC Documentation -Start the locator using the following command syntax: +The following Microsoft RPC version 1.0 reference materials are available in +Windows Write format and in PostScript file format: -locator /noservice +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 -Start the endpoint mapper on the RPC server using the following syntax: +Use the PostScript files to print individual chapters of the documentation on +your PostScript printer. -rpcss noservice +The following run-time and MIDL reference Help file is available on line: -Start the locator and endpoint mapper before starting the server -application. + RPC.HLP WinHelp MIDL and run-time API reference -Note: These services are not complete in this beta release of Microsoft -RPC version 1.0. The endpoint mapper does not support dynamic endpoints -for the TCP/IP transport on MIPS computers and does not support dynamic -endpoints for NetBIOS transports. The locator service does not start -automatically in this beta release. In a LAN Manager network -environment, you must start the locator service on the primary domain -controller and on each RPC server. For more information about -configuring the RPC Name Service, see release notes 2.0 and 29.0. +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. -10.0 Updating RPC registry entries for new NetBIOS configurations -The Microsoft RPC Setup program automatically maps protocol strings to -NetBIOS lana numbers and writes these settings in the registry. These -mappings work as long as you only have one network card and one network -protocol. If this is not the case, or if you change your network -configuration after installing Microsoft RPC, you must update the -registry to indicate the new correspondences between protocol strings -and NetBIOS lana numbers. +_______________________________________________________________________ -For Microsoft Windows NT, the mapping string appears in the registry -tree under \Software\Microsoft\Rpc\NetBios. For MS-DOS, the mapping -string appears in the registry file RPCREG.DAT. +1.0 The following release notes relate to the MIDL compiler and to building +distributed applications. -The mapping string uses the following syntax: -ncacn_nb_ = +1.1 Packing and Alignment Considerations -where +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. - indicates the protocol type. For MS-DOS, the valid -value is "nb". For Microsoft Windows NT, valid values are as -follows: +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. - Protocol type +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. - xns XNS - nb NetBEUI - tcpip TCP/IP +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. - indicates a unique digit associated with each instance of a -protocol. Use the value 0 for the first instance of a protocol and use -the next consecutive digit for each additional instance of that -protocol. For example, assign the value ncacn_nb_nb0 to the first -NetBEUI entry; assign the value ncacn_nb_nb1 to the second NetBEUI -entry. - indicates the NetBIOS lana number. A unique lana number is -associated with each network adapter present in the computer. For LAN -Manager networks, the lana numbers for each network card are available -in the configuration files LANMAN.INI and PROTOCOL.INI. For more -information about the lana number, see your network documentation. +1.2 C Stub Source Code Causes Compilation Warnings -For example, the following mapping string describes a configuration that -uses the NetBEUI protocol over an adapter card that is assigned lana -number 0: +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. -ncacn_nb_nb0=0 +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. -When you install a second card that supports both XNS and NetBEUI -protocols, the mapping strings appear as follows: -ncacn_nb_nb0=0 -ncacn_nb_nb1=1 -ncacn_nb_xns0=2 +1.3 Use Six-Character Filenames on the FAT File System -11.0 Support for multiple locators +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. -This release supports cooperation among multiple locators when the -primary locator is an i386 computer. Each locator passes its request to -the computer specified in the registry entry -"SOFTWARE\Microsoft\Rpc\NameService\NetworkAddress". The default value -for this registry entry specifies the primary domain controller as the -primary locator. -For more information about the locator, see release notes 2.0 and 29.0. +1.4 Specifying Local and UUID Attributes -12.0 NetBIOS requires larger MS-DOS application stack +If the base IDL file contains no procedures, you don't have to specify local +or UUID attributes. -The NetBIOS transport provided with this release of Microsoft RPC -version 1.0 for MS-DOS requires a 4K stack. You can set a 4K stack for -your applications with the linker option "/stack:4096" or with the -exehdr utility. -The link /stack option that sets the size of the stack to 4K is as -follows: +1.5 MIDL Extra Server Files in the Windows 3.x/MS-DOS Environment - link /stack:0x1000 +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. -The exehdr utility uses the following syntax: - exehdr /stack:0x1000 appname +1.6 Working with Visual C++ on 16-Bit Machines -where +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. - appname is the name of your application. For example, to set the -required NetBIOS stack size for the helloc.exe sample program, enter the -command: - exehdr /stack:0x1000 helloc.exe +1.7 Memory Leak Possible with Multiple Context Handles -See your Microsoft C/C++ version 7.0 documentation for more information -about these options. +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. -13.0 Using the new C _stdcall calling convention with RPC -Microsoft Win32 API functions (including the Microsoft RPC API -functions) are defined using the C language keyword _stdcall. This -keyword specifies a calling convention in which arguments are pushed -onto the stack in the same order as the C language calling convention, -but the called function (rather than the caller) pops the arguments. +1.8 Use Zero or Positive Values for the size_is and length_is Variables -Functions defined with _stdcall cannot use a variable number of -arguments. The new C calling convention is also applied when you use the -C compiler switch /Gz. +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. -The old C language calling convention is specified using the C language -keyword _cdecl or the C compiler switch /Gd. -When your application combines old C and new C calling conventions, you -must take care to specify the correct function prototypes, C compiler -switches, and linker options for these calling conventions. +1.9 RPC Cannot Pass More than 63K Worth of Data on 16-Bit Platforms -This beta release of the Microsoft RPC MIDL compiler generates C code -stub files that do not specify the _stdcall calling convention keyword -(or macros that map to _stdcall). When you compile the server stubs with -the old C calling convention, calls from the RPC server run-time library -to the server stubs do not operate correctly. +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. -A workaround is to specify the C compiler switch /Gz to select the -_stdcall calling convention at compile time. Because the main() routine -takes a variable number of arguments, it cannot be declared as _stdcall. -You must explicitly declare main() as old C calling convention by using -either the _cdecl keyword or the _CRTAPI1 macro. The RPC sample programs -and makefiles demonstrate this workaround. -For more information about the _stdcall and _cdecl calling conventions, -see the Microsoft C/C++ compiler documentation provided with Microsoft -Windows NT. +1.10 Windows 3.x Applications Using the [callback] Attribute -14.0 RpcWinSetYieldInfo not supported for Win32 applications, TCP/IP +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. -The RPC API function RpcWinSetYieldInfo is provided for use with Win 3.x -applications only. The ability to yield during RPC calls in the -Microsoft Windows 3.x environment provides the following benefits: - o other Windows 3.x applications are not blocked during - a lengthy remote procedure call - o the application that makes the remote call can - continue to process messages such as WM_PAINT +1.11 Building RPC Samples with Visual C++ for Microsoft Windows NT - o users can choose to cancel the remote call +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): -The function RpcWinSetYieldInfo is not supported in the Win32 -environment in this release. The yield capability provided by this -function is not as important in the Win32 environment as it is in the -Windows 3.x environment. The Win32 preemptive multitasking environment -lets you design your application to use multiple threads and allows your -applications to run with other applications. + #define _CRTAPI1 _cdecl -In this beta release, the function RpcWinSetYieldInfo has no effect when -RPC calls are made over the TCP/IP transport. -15.0 Uuidgen utility provided for Microsoft Windows NT +_______________________________________________________________________ +_ -This release of the Microsoft RPC SDK includes a version of the uuidgen -utility for Microsoft Windows NT. If the endpoint mapper has not been -started, you must start the endpoint mapper before you start the uuidgen -utility. To run uuidgen, enter: +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. - rpcss noservice - uuidgen -After the endpoint mapper has been started once, you can start the -uuidgen utility by entering "uuidgen." The "rpcss noservice" step is not -required for the MS-DOS version of uuidgen. -16.0 Use NULL security descriptor with RpcUseAllProtseqs +2.1 RpcServerUseAllProtseqs Requires a Null Security Descriptor -The RpcUseAllProtseqs security descriptor parameter must be set to NULL -in this beta release of Microsoft RPC version 1.0. The NULL parameter -indicates that the default ACL is applied. +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. -In this beta release, you should not use the "system" account with the -named pipe transport because this account has a default ACL. -17.0 Leading zeroes in version numbers do not create unique values +2.2 Named-Pipes Security Descriptor -The period between the major and minor numbers is a delimiter and does -not represent a decimal point. For example, the version setting 1.11 -represents a major value of one and a minor value of eleven. Version -1.11 does not represent a value between 1.1 and 1.2. Version 1.11 -represents a value between 1.10 and 1.12. Do not use leading zeroes in -the minor version value. +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. -18.0 Const initialization -The MIDL compiler accepts void pointer initialization in some cases when -it should report an error, as in the following: +2.3 Multiple Networks - void * v = 1; +The Microsoft Locator does not work with a router. -Although accepted by this release of the MIDL compiler, this -initialization is not valid. -19.0 Include three header files in your distributed applications +2.4 RpcNsBindingExport IP Addresses -With this version of the Microsoft RPC SDK, your distributed application -should include the following header files, in the following sequence: +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. - #include - #include - #include "mystub.h" -where mystub.h is the stub file generated by the MIDL compiler. +2.5 SPX Transport Limitations -20.0 Context handle issues +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. -An [in, out] context handle can be NULL on input only if another, -explicit, handle is used as the binding handle. -Context handles cannot be used as function return values, as in the -following example: +2.6 All Machines Must Use the Same SPX Packet Size -[context_handle] long * MyFunc(...); +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: -21.0 Only one error_status_t parameter allowed + IPX PACKET SIZE LIMIT=xxxx + where + xxxx is the packet size in bytes. -The Microsoft RPC implementation of the type error_status_t is -equivalent to the DCE error_status_t associated with the attributes -[fault_status, comm_status]. +Consult your Novell documentation for more information. Note that some older +drivers do not support setting IPX PACKET SIZE LIMIT. -Unlike the DCE specification, which allows multiple parameters of type -error_status_t, the MIDL compiler supports only one parameter of type -error_status_t in each remote procedure. +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. -22.0 Unsized arrays issues +2.7 Windows 3.x Applications Using TCP/IP Must Call RpcWinSetYieldInfo -In this release of Microsoft RPC version 1.0, IDL files that feature -unsized arrays with the size_is attributes can cause the MIDL compiler -to generate C language stubs that contain errors. As a workaround for -this software error, specify a maximum array size and use the length_is -attribute. +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. -23.0 Separate in, out parameters to avoid memory orphaning -When your distributed application uses an [in, out, unique] pointer -parameter, the server side of the application can change the value of -the pointer parameter to NULL. When the server returns the NULL value to -the client, memory referenced by the pointer before the remote procedure -call is still present on the client side but is no longer accessible -from that pointer. This memory is said to be "orphaned." +2.8 When Writing MS-DOS Applications, Avoid Calling _exit Directly -Memory can also be orphaned even when the server returns a non-null -value for the pointer parameter. For example, if the parameter points to -a complex data structure such as a tree, the server side of the -application can delete nodes of the tree without modifying the value of -the pointer to the root node of the tree. +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. +_______________________________________________________________________ _____ -Repeated orphaning of memory on the client without freeing the unused -memory can lead to a situation where the client runs out of available -memory resources. You can prevent such a client "memory leak" by -maintaining pointers to the allocated memory. One method that maintains -pointers to allocated memory on the client is to use separate [in] and -[out, unique] parameters rather than a single [in, out, unique] -parameter. -By using separate [in] and [out] parameters, you can force the -distributed application to allocate memory on both the client and server -each time the client application calls the remote procedure. The server -stub allocates memory for [in] data when the client calls the remote -procedure. The client stub allocates memory for [out] data during return -from the remote procedure. -This technique, like double-buffering, can use twice as much memory as -needed for each data structure. To reduce memory use, your client -application can free the memory associated with the [in] parameter after -making the remote procedure call. +3.0 The following release notes are related to installation and configuration +issues for this release: -24.0 Small model application development not supported -This beta release of Microsoft RPC version 1.0 for MS-DOS and Microsoft -Windows 3.x supports development of large model applications only. The -link libraries and dynamic link libraries supplied with this release are -large-model libraries. -In this beta release, you cannot create small-model applications that -use RPC. +3.1 Using Microsoft RPC with Microsoft Windows for Workgroups -25.0 Single process cannot be client, server using NetBIOS +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: -This beta release of Microsoft RPC version 1.0 does not support -applications that use the NetBIOS transport and that are designed as a -single process that makes calls to both the client and server run-time -libraries. + net stop workstation /y + win -26.0 Escape sequences not correct in the generated header files -The MIDL compiler provided with this beta release of Microsoft RPC -version 1.0 does not correctly produce escape sequences in generated C -language header files. +3.2 Creating Installation Disks for Your Distributed Application -Character constants that use hexadecimal notation in the IDL file -incorrectly appear as null characters in the generated header file. For -example, the IDL file statement: +After you have developed your distributed application using Microsoft RPC, +you should provide a way for your users to install your application. -const char HexNotationChar = '\x10'; +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 -generates the incorrect definition in the generated .H file: +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. -#define HexNotationChar '\0' +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. -Strings that contain the escaped double-quote character appear in the -generated header file without the escape character. For example, the -string "an escaped double quote\"" is incorrectly generated as the -string "an escaped double quote"". +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. -As a workaround, define escape sequences in a common header file that -can be directly included by your application. +Some files include an embedded version-control number for use by the Setup +Toolkit for Windows. These files are noted in the lists below. -27.0 Ncalrpc transport issues +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: -In this beta release of Microsoft RPC version 1.0, client applications -that use the protocol ncalrpc with implicit handles must include code to -handle exceptions before the client can connect to the server. The -number of exceptions raised during binding is related to the number of -times a client has connected to the server. Exception 0x6E6 is raised. -After handling this exception as many times as it is raised, the client -can connect to the server. + 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 ncalrpc transport supplied in this beta release does not support -callbacks and does not support buffers larger than 32K. +The following MS-DOS RPC files should be installed in a directory that is +specified by the PATH environment variable: -28.0 RpcNsBindingExport requires a non-null interface parameter + 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 -In this release of Microsoft RPC version 1.0, the RPC API function -RpcNsBindingExport requires a non-zero value for the parameter IfSpec. -When you supply a NULL value for IfSpec, the function incorrectly -returns the value RPC_S_NAME_SERVICE_UNAVAILABLE. +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. -29.0 Configuring RPC name service for LAN Manager networks -To run the locator service on LAN Manager networks, you must run a -primary locator on a domain controller and you must run a locator on -each computer that runs an RPC server. +Setting RPC Registry Entries -When the primary locator runs on the primary domain controller (PDC), no -configuration is needed. The default registry settings assume that the -primary locator runs on the PDC. +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. -When the primary locator runs on a computer other than the primary -domain controller, change the registry entry -SOFTWARE\Microsoft\Rpc\NameService\NetworkAddress to the names of the -computers that run the locator service. Separate computer names with the -semicolon character ";". +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 NameService registry entry NetworkAddress is used by clients during -name service lookup operations. The NameService registry entry -ServerNetworkAddress is used by servers during name service export -operations. +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. -For Microsoft Windows NT, use the regedit utility to change the registry -entry. For MS-DOS and Microsoft Windows 3.1, use a text editor to change -the entry name \Root\Software\Microsoft\Rpc\NameService\NetworkAddress -in the file RPCREG.DAT. +If the Microsoft Locator is the name-service provider: -For information about using the RPC name service with DCE host -computers, see the instructions provided in release note 2.0, "Gateway -required for DCE NSI API interoperability." + \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 -30.0 Length_is applied to pointer causes error +If CDS is the name-service provider via NSID: -The MIDL compiler supplied with this beta release of Microsoft RPC -version 1.0 generates incorrect stub code for an IDL file that applies -the length_is attribute to a pointer that represents an unsigned array. -For example, in the following example, the data size is specified as 1 -rather than the value represented by the variable s: + \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 -void foo( [length_is(s)] long * pl, short s); +The NetBIOS transport entries have the following form: ------------------------------------------------------------ -PostScript is a registered trademark of Adobe Systems, Inc. + \Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_= +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. + + +----------------------------------------------------------------------- +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.