home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 2.ddi / EXAMPLES / POINTER1 / README
Encoding:
Text File  |  1989-12-11  |  7.1 KB  |  233 lines
  1.                       pointer1 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 is a more complex demonstration of passing a
  18. pointer variable as a parameter to a remote procedure.  A
  19. pointer to a sequence of pointers to structures is passed to
  20. the server, which allocates space for the pointers and the
  21. structures.
  22.  
  23.  
  24.  
  25.  
  26. 3.  Keywords
  27.  
  28. pointer, termination expression, memory management, Exit
  29. statement
  30.  
  31.  
  32.  
  33.  
  34. 4.  Files
  35.  
  36. Source files for this example reside in the following sub-
  37. directories:
  38.  
  39. server:
  40.  
  41.      Contains code and build procedures for the server part
  42.      of this distributed application.  The server consists
  43.      of the server control procedure, which is provided with
  44.      the product distribution, the dispatcher procedure and
  45.      server stub routines, which are generated by the RPC
  46.      Compiler, and the remote procedures, which are provided
  47.      with this example.
  48.  
  49.      rproc.c       remote procedure application code
  50.  
  51.      server.mk     makefile for building the server
  52.  
  53.      serv_def.h    include file with macro definitions for
  54.                    the server control procedure
  55.  
  56. client:
  57.  
  58.      Contains code and build procedures for the client part
  59.      of this distributed application.  The client consists
  60.      of the client main program and any associated routines,
  61.      which are provided with this example, and the client
  62.      stubs, which are generated by the RPC compiler.
  63.  
  64.      client.c      client application code (main program)
  65.  
  66.      client.mk     makefile for building the client
  67.  
  68. common:
  69.  
  70.      Contains the RPC interface specification used by the
  71.      RPC compiler to create the client and server stubs.
  72.  
  73.      pointer1.rpc  RPC interface specification for this
  74.                    example
  75.  
  76.  
  77.  
  78.  
  79. 5.  Network Configuration
  80.  
  81. Before you can run this example, you may have to ask your
  82. system administrator to configure your system specifically
  83. for your needs.  The required configuration is described in
  84. the file: ..\..\READSPX
  85.  
  86.  
  87.  
  88.  
  89. 6.  Server Name
  90.  
  91. As distributed, the server for this example will register
  92. under the name "example".  However, it is strongly suggested
  93. that a unique server name be assigned to this example before
  94. it is built.
  95.  
  96. A unique server name will prevent two or more users from
  97. invoking a server process using the same server name.
  98. Choose a server name not likely to be selected by someone
  99. else.  For example, use your user or login name.
  100.  
  101. The server name must be changed in both the client and the
  102. server, and the SAME name must be used.  To change the
  103. server name for the client program, change to the client
  104. directory (client) and edit the file client.c.  Change the
  105. #define Server_Name statement as follows:
  106.  
  107.       #define Server_Name "example"
  108.           is changed to
  109.       #define Server_Name "myname"
  110.  
  111. To change the server name for the server program, change to
  112. the server directory (server) and edit the file serv_def.h,
  113. which contains the define statements for the server control
  114. procedure.  As with the client program, simply change the
  115. #define Server_Name statement.
  116.  
  117.  
  118.  
  119.  
  120. 7.  Building Client & Server
  121.  
  122. Procedures are included for building the example program.
  123. These procedures assume that your environment is set up as
  124. follows:
  125.  
  126.    - The PATH environment variable must specify the location
  127.      of the RPC Compiler executable files.
  128.  
  129.    - The LIB environment variable must specify the location
  130.      of the RPC runtime libraries.
  131.  
  132.    - The INCLUDE environment variable must specify the
  133.      location of the RPC .h include files.
  134.  
  135.    - The PDUDIR environment variable must specify the
  136.      location of the RPC .rpc files.
  137.  
  138.    - The RPCSCP environment variable must specify the
  139.      location of the RPC server control procedures.
  140.  
  141. The PATH, LIB, and INCLUDE environment variables should be
  142. set in your autoexec.bat file by modifying their current
  143. definitions. The PDUDIR and RPCSCP environment variables can
  144. be set in your autoexec.bat file, or in a local .bat file,
  145. or directly with the "set" command.
  146.  
  147. Since a distributed application runs on two machines, you
  148. must install an executable version of the client or server
  149. on another machine.  If the two machines are identical, you
  150. can build both executables (the client and server) on one
  151. machine and then move one of the executables.  However, if
  152. the two machines are not identical, you must follow the
  153. directions on the other machine for running this example and
  154. build one of the executable programs there (note that the
  155. executable filenames may differ across products).
  156.  
  157. Note that with the Microsoft C Compiler and utilities,
  158. numerous warnings will be generated when executing the
  159. makefiles. For example, you may see a "target does not
  160. exist" or "module not in library" warning. These simply mean
  161. that the file the makefile is currently creating does not
  162. yet exist. Generally, all warnings may be ignored.
  163.  
  164. To build the example program, you simply execute the build
  165. procedures in each subdirectory as follows:
  166.  
  167.   1.  Change to the client directory (client) and build the
  168.       client:
  169.  
  170.            make client.mk
  171.  
  172.   2.  Change to the server directory (server) and build the
  173.       server:
  174.  
  175.            make server.mk
  176.  
  177.  
  178.  
  179.  
  180.  
  181. 8.  Running the Distributed Application
  182.  
  183. The server program should be started before the client
  184. program is run.
  185.  
  186. To run the example on two machines, proceed as follows:
  187.  
  188.   1.  Change to the server directory (server) on the machine
  189.       running the server and start the server:
  190.  
  191.            server
  192.  
  193.   2.  Change to the client directory (client) on the machine
  194.       running the client and start the client:
  195.  
  196.            client
  197.  
  198.  
  199.  
  200.  
  201.  
  202. 9.  Description
  203.  
  204. In this example, the address of a sequence of pointers to
  205. structures is passed to the remote procedure, which
  206. allocates space for the pointers and the structures.
  207.  
  208. The client allocates space only for the pointer to the array
  209. of pointers; all other memory is dynamically allocated by
  210. the client stub upon return from the server.  The client can
  211. deallocate that memory by freeing each block of dynamically
  212. allocated memory.  Note that the client cannot deallocate
  213. the entire data structure by simply freeing the pointer to
  214. the array of pointers.
  215.  
  216. The server must allocate space for the array of pointers,
  217. for each structure, and for the character strings within
  218. each structure.  Any of these which are dynamically
  219. allocated can be deallocated within the Exit statement in
  220. the RPC specification.  The freemem example also
  221. demonstrates how to handle dynamically allocated memory.
  222.  
  223. The array of pointers has a termination expression in the
  224. RPC specification so the RPC Compiler knows that "**data"
  225. is, in fact, a sequence of pointers and not a single item.
  226. Each character string in the structure also has a
  227. termination expression.
  228.  
  229. For more information, see "Pointer Declarations," in
  230. Chapter 6, "Customizing the RPC Code," in Chapter 7, and
  231. Chapter 12, "Memory Management", in the NetWare RPC User's
  232. Manual.
  233.