home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 2.ddi / EXAMPLES / LINK / README
Encoding:
Text File  |  1989-12-11  |  7.0 KB  |  229 lines
  1.                         link Example
  2.  
  3.  
  4.  
  5.  
  6. 1.  Environment
  7.  
  8. This example is designed to be built and executed on a PC
  9. that runs DOS, the Microsoft C Compiler and utilities, and
  10. that uses the NetWare network library.
  11.  
  12.  
  13.  
  14.  
  15. 2.  Overview
  16.  
  17. This example illustrates the use of a more complex data
  18. structure (a linked list) and the use of the Pointer Table.
  19.  
  20.  
  21.  
  22.  
  23. 3.  Keywords
  24.  
  25. pointer to structure, linked list, Pointer Table, MAXPTRS
  26. interface variable
  27.  
  28.  
  29.  
  30.  
  31. 4.  Files
  32.  
  33. Source files for this example reside in the following sub-
  34. directories:
  35.  
  36. server:
  37.  
  38.      Contains code and build procedures for the server part
  39.      of this distributed application.  The server consists
  40.      of the server control procedure, which is provided with
  41.      the product distribution, the dispatcher procedure and
  42.      server stub routines, which are generated by the RPC
  43.      Compiler, and the remote procedures, which are provided
  44.      with this example.
  45.  
  46.      rproc.c       remote procedure application code
  47.  
  48.      server.mk     makefile for building the server
  49.  
  50.      serv_def.h    include file with macro definitions for
  51.                    the server control procedure
  52.  
  53. client:
  54.  
  55.      Contains code and build procedures for the client part
  56.      of this distributed application.  The client consists
  57.      of the client main program and any associated routines,
  58.      which are provided with this example, and the client
  59.      stubs, which are generated by the RPC compiler.
  60.  
  61.      client.c      client application code (main program)
  62.  
  63.      client.mk     makefile for building the client
  64.  
  65. common:
  66.  
  67.      Contains the RPC interface specification used by the
  68.      RPC compiler to create the client and server stubs.
  69.  
  70.      link.rpc      RPC interface specification for this
  71.                    example
  72.  
  73.  
  74.  
  75.  
  76. 5.  Network Configuration
  77.  
  78. Before you can run this example, you may have to ask your
  79. system administrator to configure your system specifically
  80. for your needs.  The required configuration is described in
  81. the file: ..\..\READSPX
  82.  
  83.  
  84.  
  85.  
  86. 6.  Server Name
  87.  
  88. As distributed, the server for this example will register
  89. under the name "example".  However, it is strongly suggested
  90. that a unique server name be assigned to this example before
  91. it is built.
  92.  
  93. A unique server name will prevent two or more users from
  94. invoking a server process using the same server name.
  95. Choose a server name not likely to be selected by someone
  96. else.  For example, use your user or login name.
  97.  
  98. The server name must be changed in both the client and the
  99. server, and the SAME name must be used.  To change the
  100. server name for the client program, change to the client
  101. directory (client) and edit the file client.c.  Change the
  102. #define Server_Name statement as follows:
  103.  
  104.       #define Server_Name "example"
  105.           is changed to
  106.       #define Server_Name "myname"
  107.  
  108. To change the server name for the server program, change to
  109. the server directory (server) and edit the file serv_def.h,
  110. which contains the define statements for the server control
  111. procedure.  As with the client program, simply change the
  112. #define Server_Name statement.
  113.  
  114.  
  115.  
  116.  
  117. 7.  Building Client & Server
  118.  
  119. Procedures are included for building the example program.
  120. These procedures assume that your environment is set up as
  121. follows:
  122.  
  123.    - The PATH environment variable must specify the location
  124.      of the RPC Compiler executable files.
  125.  
  126.    - The LIB environment variable must specify the location
  127.      of the RPC runtime libraries.
  128.  
  129.    - The INCLUDE environment variable must specify the
  130.      location of the RPC .h include files.
  131.  
  132.    - The PDUDIR environment variable must specify the
  133.      location of the RPC .rpc files.
  134.  
  135.    - The RPCSCP environment variable must specify the
  136.      location of the RPC server control procedures.
  137.  
  138. The PATH, LIB, and INCLUDE environment variables should be
  139. set in your autoexec.bat file by modifying their current
  140. definitions. The PDUDIR and RPCSCP environment variables can
  141. be set in your autoexec.bat file, or in a local .bat file,
  142. or directly with the "set" command.
  143.  
  144. Since a distributed application runs on two machines, you
  145. must install an executable version of the client or server
  146. on another machine.  If the two machines are identical, you
  147. can build both executables (the client and server) on one
  148. machine and then move one of the executables.  However, if
  149. the two machines are not identical, you must follow the
  150. directions on the other machine for running this example and
  151. build one of the executable programs there (note that the
  152. executable filenames may differ across products).
  153.  
  154. Note that with the Microsoft C Compiler and utilities,
  155. numerous warnings will be generated when executing the
  156. makefiles. For example, you may see a "target does not
  157. exist" or "module not in library" warning. These simply mean
  158. that the file the makefile is currently creating does not
  159. yet exist. Generally, all warnings may be ignored.
  160.  
  161. To build the example program, you simply execute the build
  162. procedures in each subdirectory as follows:
  163.  
  164.   1.  Change to the client directory (client) and build the
  165.       client:
  166.  
  167.            make client.mk
  168.  
  169.   2.  Change to the server directory (server) and build the
  170.       server:
  171.  
  172.            make server.mk
  173.  
  174.  
  175.  
  176.  
  177.  
  178. 8.  Running the Distributed Application
  179.  
  180. The server program should be started before the client
  181. program is run.
  182.  
  183. To run the example on two machines, proceed as follows:
  184.  
  185.   1.  Change to the server directory (server) on the machine
  186.       running the server and start the server:
  187.  
  188.            server
  189.  
  190.   2.  Change to the client directory (client) on the machine
  191.       running the client and start the client:
  192.  
  193.            client
  194.  
  195.  
  196.  
  197.  
  198.  
  199. 9.  Description
  200.  
  201. The link.rpc file defines a doubly linked list (struct
  202. customer) which is a data structure with multiple pointers
  203. (forward and backward pointers) to each structure element in
  204. the list.
  205.  
  206. In order to handle this complex data structure, an interface
  207. specification is used to define the interface variable
  208. MAXPTRS. Setting MAXPTRS causes the creation of a Pointer
  209. Table, which tracks multiple pointers to the same structure.
  210. MAXPTRS must be set to the maximum number of unique
  211. structure pointers that you expect to appear in handling a
  212. single remote procedure call.  With the information from the
  213. Pointer Table, the RPC code that is unpacking a Protocol
  214. Data Unit (PDU) can reconstruct the data structure as it
  215. appeared before it was packed.
  216.  
  217. If the Pointer Table were not used, multiple pointers to the
  218. same structure would result in separate copies of that
  219. structure.  Further, in this example, a fatal error would
  220. result when packing the list, since there are circularities
  221. in the data structure (one element points to the next, which
  222. in turn points back to the first).
  223.  
  224. See "Pointers to Structures," in Chapter 6, and "MAXPTRS,"
  225. in Chapter 11 of the NetWare RPC User's Manual for more
  226. information on pointers to structures and the Pointer Table.
  227. In addition, the lostptr example demonstrates some memory
  228. management considerations when using pointers to structures.
  229.