home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 2.ddi / EXAMPLES / PERSIST / README
Encoding:
Text File  |  1989-12-11  |  7.9 KB  |  249 lines
  1.                       persist 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 demonstrates a client program that uses a
  18. persistent binding; in other words, a binding that is used
  19. for multiple remote procedure calls.  Thus, in this example,
  20. the client will establish a binding with the server, use
  21. this binding for subsequent remote procedure calls, and
  22. finally terminate the binding once the server is no longer
  23. required.
  24.  
  25.  
  26.  
  27.  
  28. 3.  Keywords
  29.  
  30. persistent binding, single-binding model, connection_id
  31. binding type
  32.  
  33.  
  34.  
  35.  
  36. 4.  Files
  37.  
  38. Source files for this example reside in the following sub-
  39. directories:
  40.  
  41. server:
  42.  
  43.      Contains code and build procedures for the server part
  44.      of this distributed application.  The server consists
  45.      of the server control procedure, which is provided with
  46.      the product distribution, the dispatcher procedure and
  47.      server stub routines, which are generated by the RPC
  48.      Compiler, and the remote procedures, which are provided
  49.      with this example.
  50.  
  51.      rproc.c       remote procedure application code
  52.  
  53.      server.mk     makefile for building the server
  54.  
  55.      serv_def.h    include file with macro definitions for
  56.                    the server control procedure
  57.  
  58. client:
  59.  
  60.      Contains code and build procedures for the client part
  61.      of this distributed application.  The client consists
  62.      of the client main program and any associated routines,
  63.      which are provided with this example, and the client
  64.      stubs, which are generated by the RPC compiler.
  65.  
  66.      client.c      client application code (main program)
  67.  
  68.      client.mk     makefile for building the client
  69.  
  70. common:
  71.  
  72.      Contains the RPC interface specification used by the
  73.      RPC compiler to create the client and server stubs.
  74.  
  75.      persist.rpc   RPC interface specification for this
  76.                    example
  77.  
  78.  
  79.  
  80.  
  81. 5.  Network Configuration
  82.  
  83. Before you can run this example, you may have to ask your
  84. system administrator to configure your system specifically
  85. for your needs.  The required configuration is described in
  86. the file: ..\..\READSPX
  87.  
  88.  
  89.  
  90.  
  91. 6.  Server Name
  92.  
  93. As distributed, the server for this example will register
  94. under the name "example".  However, it is strongly suggested
  95. that a unique server name be assigned to this example before
  96. it is built.
  97.  
  98. A unique server name will prevent two or more users from
  99. invoking a server process using the same server name.
  100. Choose a server name not likely to be selected by someone
  101. else.  For example, use your user or login name.
  102.  
  103. The server name must be changed in both the client and the
  104. server, and the SAME name must be used.  To change the
  105. server name for the client program, change to the client
  106. directory (client) and edit the file client.c.  Change the
  107. #define Server_Name statement as follows:
  108.  
  109.       #define Server_Name "example"
  110.           is changed to
  111.       #define Server_Name "myname"
  112.  
  113. To change the server name for the server program, change to
  114. the server directory (server) and edit the file serv_def.h,
  115. which contains the define statements for the server control
  116. procedure.  As with the client program, simply change the
  117. #define Server_Name statement.
  118.  
  119.  
  120.  
  121.  
  122. 7.  Building Client & Server
  123.  
  124. Procedures are included for building the example program.
  125. These procedures assume that your environment is set up as
  126. follows:
  127.  
  128.    - The PATH environment variable must specify the location
  129.      of the RPC Compiler executable files.
  130.  
  131.    - The LIB environment variable must specify the location
  132.      of the RPC runtime libraries.
  133.  
  134.    - The INCLUDE environment variable must specify the
  135.      location of the RPC .h include files.
  136.  
  137.    - The PDUDIR environment variable must specify the
  138.      location of the RPC .rpc files.
  139.  
  140.    - The RPCSCP environment variable must specify the
  141.      location of the RPC server control procedures.
  142.  
  143. The PATH, LIB, and INCLUDE environment variables should be
  144. set in your autoexec.bat file by modifying their current
  145. definitions. The PDUDIR and RPCSCP environment variables can
  146. be set in your autoexec.bat file, or in a local .bat file,
  147. or directly with the "set" command.
  148.  
  149. Since a distributed application runs on two machines, you
  150. must install an executable version of the client or server
  151. on another machine.  If the two machines are identical, you
  152. can build both executables (the client and server) on one
  153. machine and then move one of the executables.  However, if
  154. the two machines are not identical, you must follow the
  155. directions on the other machine for running this example and
  156. build one of the executable programs there (note that the
  157. executable filenames may differ across products).
  158.  
  159. Note that with the Microsoft C Compiler and utilities,
  160. numerous warnings will be generated when executing the
  161. makefiles. For example, you may see a "target does not
  162. exist" or "module not in library" warning. These simply mean
  163. that the file the makefile is currently creating does not
  164. yet exist. Generally, all warnings may be ignored.
  165.  
  166. To build the example program, you simply execute the build
  167. procedures in each subdirectory as follows:
  168.  
  169.   1.  Change to the client directory (client) and build the
  170.       client:
  171.  
  172.            make client.mk
  173.  
  174.   2.  Change to the server directory (server) and build the
  175.       server:
  176.  
  177.            make server.mk
  178.  
  179.  
  180.  
  181.  
  182.  
  183. 8.  Running the Distributed Application
  184.  
  185. The server program should be started before the client
  186. program is run.
  187.  
  188. To run the example on two machines, proceed as follows:
  189.  
  190.   1.  Change to the server directory (server) on the machine
  191.       running the server and start the server:
  192.  
  193.            server
  194.  
  195.   2.  Change to the client directory (client) on the machine
  196.       running the client and start the client:
  197.  
  198.            client
  199.  
  200.  
  201.  
  202.  
  203.  
  204. 9.  Description
  205.  
  206. This example demonstrates a client program that uses a
  207. persistent binding; in other words, a binding that is used
  208. for multiple remote procedure calls.  Thus, in this example,
  209. the client will establish a binding with the server, use
  210. this binding for subsequent remote procedure calls, and
  211. finally terminate the binding once the server is no longer
  212. required.
  213.  
  214. You should consider using persistent connections when your
  215. client and server interact extensively, and the overhead of
  216. binding establishment will impact the design of your
  217. distributed application.
  218.  
  219. In addition to increasing performance, a persistent binding,
  220. client-server relationship allows a server to offer an
  221. interface that groups a set of remote procedures into a
  222. logical category.  You may want to consider using persistent
  223. bindings in cases where the remote procedures are related
  224. functionally or act upon the same data structures. Indeed,
  225. the persistent-binding model can be used in performing a
  226. transaction style of client-server interaction.
  227.  
  228. To demonstrate a persistent connection, the client is set up
  229. to "sleep" between remote procedure calls, so it keeps the
  230. binding open for a short time.  If, during that time,
  231. another client were to try to establish a binding to this
  232. server, that client would wait.  The multicli example shows
  233. how to support multiple client process bindings
  234. simultaneously.
  235.  
  236. See Chapter 6, "Process Binding," and Chapter 14, "Server
  237. Control Procedures" of the NetWare RPC User's Manual for
  238. more information on persistent bindings and single-
  239. binding servers.
  240.  
  241. Note that the server shown in this example is a single-
  242. threaded server; in other words, the server handles one and
  243. only one binding at any point in time.  Other client
  244. requests must wait their turn, until the server completes
  245. handling the preceding bindings.  If your environment
  246. supports multi-threaded processes or multi-tasking, other
  247. examples will demonstrate the use of a multi-threaded or
  248. multi-tasking server supporting persistent bindings.
  249.