home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 6.ddi / EXAMPLES / TIMER / README
Encoding:
Text File  |  1989-12-08  |  9.5 KB  |  294 lines
  1.                        timer 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 Borland Turbo C Compiler and utilities,
  10. and that uses the NOVELL SPX network library.
  11.  
  12.  
  13.  
  14.  
  15. 2.  Overview
  16.  
  17. This example shows how to add custom code to an RPC
  18. specification so that a client can set a limit on the time
  19. it waits for a response from a remote procedure.
  20.  
  21.  
  22.  
  23.  
  24. 3.  Keywords
  25.  
  26. timeout, Hooks, Traps, RPC macros, polling
  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.      The RPC interface specification imports the timer RPC
  70.      specification file to provide the time-out interface.
  71.  
  72.      timer.rpc     RPC interface specification for this
  73.                    example
  74.  
  75. timer:
  76.  
  77.      Contains the RPC interface specification consisting of
  78.      client stub Hooks code and the source code for
  79.      poll_reply, which provide for a time-out interface.
  80.  
  81.      timer_i.rpc   timer RPC specification and polling
  82.                    routine
  83.  
  84.      timer_i.mk    makefile for building the timer library
  85.                    and include file
  86.  
  87.      Note that the RPC Compiler is run only once with this
  88.      RPC specification file as input.  Generally, the
  89.      Compiler should be run with the file twice: once for
  90.      the client and once for the server, producing header
  91.      files and RPC code files for each.  However, for this
  92.      example the procedure is simplified because the single
  93.      header file produced can be used by both the client and
  94.      the server, the RPC Compiler is told to run in client
  95.      mode, and the only application code in the file is for
  96.      the client.
  97.  
  98.  
  99.  
  100.  
  101. 5.  Network Configuration
  102.  
  103. Before you can run this example, you may have to ask your
  104. system administrator to configure your system specifically
  105. for your needs.  The required configuration is described in
  106. the file: ..\..\READSPX
  107.  
  108.  
  109.  
  110.  
  111. 6.  Server Name
  112.  
  113. As distributed, the server for this example will register
  114. under the name "example".  However, it is strongly suggested
  115. that a unique server name be assigned to this example before
  116. it is built.
  117.  
  118. A unique server name will prevent two or more users from
  119. invoking a server process using the same server name.
  120. Choose a server name not likely to be selected by someone
  121. else.  For example, use your user or login name.
  122.  
  123. The server name must be changed in both the client and the
  124. server, and the SAME name must be used.  To change the
  125. server name for the client program, change to the client
  126. directory (client) and edit the file client.c.  Change the
  127. #define Server_Name statement as follows:
  128.  
  129.       #define Server_Name "example"
  130.           is changed to
  131.       #define Server_Name "myname"
  132.  
  133. To change the server name for the server program, change to
  134. the server directory (server) and edit the file serv_def.h,
  135. which contains the define statements for the server control
  136. procedure.  As with the client program, simply change the
  137. #define Server_Name statement.
  138.  
  139.  
  140.  
  141.  
  142. 7.  Building Client & Server
  143.  
  144. Procedures are included for building the example program.
  145. These procedures assume that your environment is set up as
  146. follows:
  147.  
  148.    - The PATH environment variable must specify the location
  149.      of the RPC Compiler executable files.
  150.  
  151.    - The LIB environment variable must specify the location
  152.      of the RPC runtime libraries.
  153.  
  154.    - The INCLUDE environment variable must specify the
  155.      location of the RPC .h include files.
  156.  
  157.    - The PDUDIR environment variable must specify the
  158.      location of the RPC .rpc files.
  159.  
  160.    - The RPCSCP environment variable must specify the
  161.      location of the RPC server control procedures.
  162.  
  163. The PATH environment variable should be set in your
  164. autoexec.bat file by modifying its current definition. The
  165. PDUDIR and RPCSCP environment variables can be set in your
  166. autoexec.bat file, or in a local .bat file, or directly with
  167. the "set" command.
  168.  
  169. The location of the NetWare RPC libraries should be specified
  170. by adding this line to the turboc.cfg file (which is located
  171. in the top level Turbo C directory):
  172.  
  173.      -Lc:\rpc\lib
  174.  
  175. The location of the NetWare RPC .h include files should be
  176. specified by adding this line to the turboc.cfg file:
  177.  
  178.      -Ic:\rpc\include\spx
  179.  
  180. Since a distributed application runs on two machines, you
  181. must install an executable version of the client or server
  182. on another machine.  If the two machines are identical, you
  183. can build both executables (the client and server) on one
  184. machine and then move one of the executables.  However, if
  185. the two machines are not identical, you must follow the
  186. directions on the other machine for running this example and
  187. build one of the executable programs there (note that the
  188. executable filenames may differ across products).
  189.  
  190. Note that with the Borland Turbo C Compiler and utilities,
  191. numerous warnings will be generated when executing the
  192. makefiles. For example, you may see "Possibly incorrect
  193. assignment in function 'function-name'", or "Parameter
  194. 'parm_name' is never used in function 'function_name'", or
  195. "'parm_name' is assigned a value which is never used in
  196. function 'function_name'". Generally, all warnings may be
  197. ignored.
  198.  
  199. To build the example program, you simply execute the build
  200. procedures in each subdirectory as follows:
  201.  
  202.   1.  Change to the timer directory and build the files
  203.       associated with the imported RPC specification file:
  204.  
  205.            make -ftimer_i.mk
  206.  
  207.   2.  Change to the client directory (client) and build the
  208.       client:
  209.  
  210.            make -fclient.mk
  211.  
  212.   3.  Change to the server directory (server) and build the
  213.       server:
  214.  
  215.            make -fserver.mk
  216.  
  217.  
  218.  
  219.  
  220.  
  221. 8.  Running the Distributed Application
  222.  
  223. The server program should be started before the client
  224. program is run.
  225.  
  226. To run the example on two machines, proceed as follows:
  227.  
  228.   1.  Change to the server directory (server) on the machine
  229.       running the server and start the server:
  230.  
  231.            server
  232.  
  233.   2.  Change to the client directory (client) on the machine
  234.       running the client and start the client:
  235.  
  236.            client -l loops
  237.  
  238.       If the argument "loops" is passed to the client, it
  239.       specifies the number of times the remote procedures
  240.       are called. If no argument is specified, the
  241.       procedures are called only once.
  242.  
  243.  
  244.  
  245.  
  246. 9.  Description
  247.  
  248. This example shows how to add custom code to an RPC
  249. specification so that a client can set a limit on the time
  250. it waits for a response from a remote procedure.
  251.  
  252. To facilitate the ability of the client to limit time for a
  253. remote procedure call, this example separates the client
  254. timer code into a special RPC specification called
  255. "timer_i.rpc." This RPC specification contains Hooks
  256. statements to customize client stubs so that they do not
  257. wait for replies beyond a specified time limit.  By
  258. importing "timer_i.rpc" within an RPC specification, all
  259. client stubs generated from this specification provide
  260. client interfacse to the described remote procedures that
  261. can limit time spent waiting for replies.
  262.  
  263. Once the client stubs have been customized to incorporate
  264. the timer code, the client can call a client stub to
  265. generate a request and send this request to the server.
  266. Having initiated the remote procedure call, the client stub
  267. polls to determine if a reply has been received.  If one is
  268. not received within a specified time, the client stub
  269. returns an error code to the client, as defined in the
  270. imported RPC specification "timer_i.rpc."
  271.  
  272. To assist in determining when the reply message has been
  273. received, the "timer_i.rpc" specification is accompanied by
  274. a library containing a routine called poll_reply.  This
  275. procedure returns an integer value.
  276.  
  277. A value of 1 means that a reply has been received; call the
  278. stub again with exactly the same parameters as before.
  279. A value of 0 means that a reply has not been received yet;
  280. continue as before, but do not call the stub yet.
  281. An error code value means that an error was detected; call
  282. the stub again with exactly the same parameters as before so
  283. the state machine can clean up.
  284.  
  285. Using the poll_reply procedure, the client stub can
  286. determine when the reply has been received from the server.
  287.  
  288. Note that a server requires no special modifications to
  289. interact with a client that includes this timer code.
  290.  
  291. For more information on adding custom code, see the
  292. NetWare RPC User's Manual, Chapter 7, "Customizing the
  293. RPC Code."
  294.