home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 2.ddi / CBAK / README
Encoding:
Text File  |  1989-12-11  |  10.5 KB  |  315 lines
  1.                         cbak 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 shows how a 'callback' facility can be created
  18. through simple RPC customizations. In 'callback', the server
  19. temporarily becomes a client and makes remote procedure
  20. calls back to the client (which acts as a server) during the
  21. processing of a remote procedure.
  22.  
  23.  
  24.  
  25.  
  26. 3.  Keywords
  27.  
  28. callback, import statement
  29.  
  30.  
  31.  
  32.  
  33. 4.  Files
  34.  
  35. Source files for this example reside in the following sub-
  36. directories:
  37.  
  38. server:
  39.  
  40.      Contains code and build procedures for the server part
  41.      of this distributed application.  The server consists
  42.      of the server control procedure, which is provided with
  43.      the product distribution, the dispatcher procedure and
  44.      server stub routines, which are generated by the RPC
  45.      Compiler, and the remote procedures, which are provided
  46.      with this example.  Also included is the code necessary
  47.      to support callback, where the server becomes the
  48.      client.
  49.  
  50.      rproc.c       remote procedure application and callback
  51.                    support 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.  The
  65.      client also includes the code necessary to support
  66.      callback, where the client becomes the server.
  67.  
  68.      client.c      client application code (main program)
  69.  
  70.      client.mk     makefile for building the client
  71.  
  72. common:
  73.  
  74.      Contains the RPC interface specification used by the
  75.      RPC compiler to create the client and server stubs.  It
  76.      also contains the RPC interface specification for the
  77.      callback, which is used by the RPC compiler to create
  78.      client stubs for the server and server stubs for the
  79.      client.  Each of the 2 RPC specification files provides
  80.      a general description of the callback mechanism and
  81.      imports a RPC specification file to provide the
  82.      descriptions for this example.
  83.  
  84.      cbak.rpc      RPC interface specification for this
  85.                    example
  86.  
  87.      cbak_c.rpc    callback RPC interface specification
  88.  
  89. cbak/common:
  90.  
  91.      Contains the RPC interface specifications consisting of
  92.      declarations, Hooks, and the source code to terminate
  93.      the callback.
  94.  
  95.      cbak_i.rpc    RPC specification for normal client
  96.                    server interaction
  97.  
  98.      cbak_c_i.rpc  RPC specification to support the callback
  99.                    (reversal of client and server roles)
  100.  
  101. cbak/client
  102.  
  103.      Contains the build procedure for compiling the
  104.      cbak_i.rpc and cbak_c_i.rpc RPC specifications.
  105.  
  106.      client_i.mk   makefile for building the cbak_i and
  107.                    cbak_c_i include files and the RPC code
  108.                    files (which are themselves then
  109.                    compiled) for the client
  110.  
  111. cbak/server
  112.  
  113.      Contains the build procedure for compiling the
  114.      cbak_i.rpc and the cbak_c_i.rpc RPC specifications.
  115.  
  116.      server_i.mk   makefile for building the cbak_i and
  117.                    cbak_c_i include files and the RPC code
  118.                    files (which are themselves then
  119.                    compiled) for the server
  120.  
  121.  
  122.  
  123.  
  124. 5.  Network Configuration
  125.  
  126. Before you can run this example, you may have to ask your
  127. system administrator to configure your system specifically
  128. for your needs.  The required configuration is described in
  129. the file: ..\..\READSPX
  130.  
  131.  
  132.  
  133.  
  134. 6.  Server Name
  135.  
  136. As distributed, the server for this example will register
  137. under the name "example".  However, it is strongly suggested
  138. that a unique server name be assigned to this example before
  139. it is built.
  140.  
  141. A unique server name will prevent two or more users from
  142. invoking a server process using the same server name.
  143. Choose a server name not likely to be selected by someone
  144. else.  For example, use your user or login name.
  145.  
  146. The server name must be changed in both the client and the
  147. server, and the SAME name must be used.  To change the
  148. server name for the client program, change to the client
  149. directory (client) and edit the file client.c.  Change the
  150. #define Server_Name statement as follows:
  151.  
  152.       #define Server_Name "example"
  153.           is changed to
  154.       #define Server_Name "myname"
  155.  
  156. To change the server name for the server program, change to
  157. the server directory (server) and edit the file serv_def.h,
  158. which contains the define statements for the server control
  159. procedure.  As with the client program, simply change the
  160. #define Server_Name statement.
  161.  
  162.  
  163.  
  164.  
  165. 7.  Building Client & Server
  166.  
  167. Procedures are included for building the example program.
  168. These procedures assume that your environment is set up as
  169. follows:
  170.  
  171.    - The PATH environment variable must specify the location
  172.      of the RPC Compiler executable files.
  173.  
  174.    - The LIB environment variable must specify the location
  175.      of the RPC runtime libraries.
  176.  
  177.    - The INCLUDE environment variable must specify the
  178.      location of the RPC .h include files.
  179.  
  180.    - The PDUDIR environment variable must specify the
  181.      location of the RPC .rpc files.
  182.  
  183.    - The RPCSCP environment variable must specify the
  184.      location of the RPC server control procedures.
  185.  
  186. The PATH, LIB, and INCLUDE environment variables should be
  187. set in your autoexec.bat file by modifying their current
  188. definitions. The PDUDIR and RPCSCP environment variables can
  189. be set in your autoexec.bat file, or in a local .bat file,
  190. or directly with the "set" command.
  191.  
  192. Since a distributed application runs on two machines, you
  193. must install an executable version of the client or server
  194. on another machine.  If the two machines are identical, you
  195. can build both executables (the client and server) on one
  196. machine and then move one of the executables.  However, if
  197. the two machines are not identical, you must follow the
  198. directions on the other machine for running this example and
  199. build one of the executable programs there (note that the
  200. executable filenames may differ across products).
  201.  
  202. Note that with the Microsoft C Compiler and utilities,
  203. numerous warnings will be generated when executing the
  204. makefiles. For example, you may see a "target does not
  205. exist" or "module not in library" warning. These simply mean
  206. that the file the makefile is currently creating does not
  207. yet exist. Generally, all warnings may be ignored.
  208.  
  209. To build the example program, you simply execute the build
  210. procedures in each subdirectory as follows:
  211.  
  212.   1.  Change to the client directory of the imported file
  213.       (cbak/client) and build the client files associated
  214.       with the imported RPC specification file:
  215.  
  216.            make client_i.mk
  217.  
  218.   2.  Change to the server directory of the imported file
  219.       (cbak/server) and build the server files associated
  220.       with the imported RPC specification file:
  221.  
  222.            make server_i.mk
  223.  
  224.   3.  Change to the client directory (client) and build the
  225.       client:
  226.  
  227.            make client.mk
  228.  
  229.   4.  Change to the server directory (server) and build the
  230.       server:
  231.  
  232.            make server.mk
  233.  
  234.  
  235.  
  236.  
  237.  
  238. 8.  Running the Distributed Application
  239.  
  240. The server program should be started before the client
  241. program is run.
  242.  
  243. To run the example on two machines, proceed as follows:
  244.  
  245.   1.  Change to the server directory (server) on the machine
  246.       running the server and start the server:
  247.  
  248.            server
  249.  
  250.   2.  Change to the client directory (client) on the machine
  251.       running the client and start the client:
  252.  
  253.            client
  254.  
  255.  
  256.  
  257.  
  258.  
  259. 9.  Description
  260.  
  261. A distributed application constructed using the RPC Tool
  262. consists of client and server programs, where the client
  263. program makes remote calls to procedures that execute in the
  264. server. In some cases, it can be useful for the server to be
  265. able to make calls back into the client.  This idea is known
  266. as "callback" and is demonstrated in this example program.
  267.  
  268. In callback, the client and server temporarily switch roles
  269. during the processing of a remote procedure call. The server
  270. becomes a client, and makes remote procedure calls into the
  271. client program, which must act as a server to service these
  272. calls.
  273.  
  274. To use callback, two RPC interfaces must be described.
  275. First, the interface between the client and server must be
  276. declared in the usual way. Next, the calls that the server
  277. will make back to the client must be described. These are
  278. referred to as the "nested" calls.
  279.  
  280. For this example, the top-level interface is described in
  281. the file "cbak.rpc". It includes customizations for callback
  282. in the file "cbak_i.rpc". The nested interface is declared
  283. in "cbak_c.rpc" and includes customizations from the file
  284. "cbak_c_i.rpc". While the files "cbak.rpc" and "cbak_c.rpc"
  285. are specific to this example, the callback customizations in
  286. "cbak_i.rpc" and "cbak_c_i.rpc" are designed to be
  287. reasonably general.
  288.  
  289. For the server, callback is quite simple. While handling an
  290. RPC request, the current connection id is saved in a global
  291. variable. This variable is used for binding by the nested
  292. RPC calls.  The situation is only slightly more complicated
  293. for the client. For remote procedure calls from the client,
  294. the client stub sends its RPC request normally. It then goes
  295. into a loop calling a dispatcher procedure for the nested
  296. interface. After the last nested RPC is serviced, the client
  297. state machine continues, receiving the reply to the original
  298. remote procedure, and returning.
  299.  
  300. For this example program, callback is used to access data in
  301. the client application. The client program is to sum the
  302. elements of an array of numbers (given on the command line)
  303. using a remote procedure named 'sum_array'.  Instead of
  304. passing the array as a parameter, only the number of
  305. elements in the array is given.  The remote procedure (on
  306. the server) uses callback to retrieve each individual
  307. element as it is needed,  using the remote procedure (on the
  308. client)
  309.  
  310. When 'sum_array' has finished, it returns the result, and
  311. customization code in the server stub automatically
  312. terminates the callback sequence.  The client stops
  313. processing callback procedures and awaits the reply message
  314. for 'sum_array'.
  315.