19. ONC RPC Sample Programs

Introduction

This chapter is for RPC programmers. It explains:

  How to run the sample programs.

  The purpose of each sample program file.

Introducing Sample Programs

The ONC RPC sample programs are divided into three groups:

  GETSYI

  PRINT

  SYSINFO

Each group has a command procedure to facilitate compiling and linking. All command procedures are in the TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC] directory.

For more information on each program, see the comments in the GETSYI.COM, PRINT.COM, and SYSINFO.COM files.

Running Sample Programs

To run an RPC sample program, follow these steps:

1   Move to the directory where you want the command procedure to place the client and server sample programs. It must be a directory in which you have write privilege.

2   Compile the sample client and server programs by entering one of the following commands at the DCL prompt:

$ @TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC]PRINT
$ @TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC]SYSINFO
$ @TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC]GETSYI XDR1
$ @TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC]GETSYI XDR2

3   Verify whether the Port Mapper is running. Use the RPCINFO command or the NETCU SHOW SERVICES command. If the Port Mapper is not running, ask the system manager to start it.

4   Log on to a second terminal. Run the server that you compiled in step 2. To stop the server, type CTRL/C.

5   Define symbols that point to the executable client program. A symbol can point to either a logical or a disk/directory specification, as follows:

symbol:==$logical:prog
symbol
:==$disk:[dir]prog

     symbol specifies GETSYI, PRINTF, or SYSINFO.

     logical is the logical pointing to the directory that contains the .EXE client program. This logical must translate to a disk and directory specification.

     prog is the .EXE program for GETSYI, PRINT, or SYSINFO.

     disk:[dir] is the disk and directory where the .EXE client program is located.

These symbols remain valid until you log off.

6   Run the clients. Use the commands given in the following sections.

Running GETSYI Client

To run the GETSYI client, enter the following command at the DCL prompt:

$ GETSYI [-u | -t][-d#][-nnode][-hhost]code[code...]

GETSYI

Runs the GETSYI client.

-u

UDP transport. Supported only for the GETSYI_CLNT_CALL client. This is the default.

-t

TCP transport. Supported only for the GETSYI_CLNT_CALL client.

-d#

Debugging value passed to the ONCRPC_SET_CHAR routine. Debugging values are defined in the ONCRPC_CONST.H file. The pound sign (#) represents a hexadecimal number. The default is 0.

-nnode

Name of the node about which the server is returning information. Can be used only if the server is part of a VMS cluster. The default is a NULL string (no node).

-hhost

Domain name of the host running the remote server. If you omit host, node is used as the default. If node is not specified, the default is the local host.

code

String indicating what information the server needs to return. You can enter up to 64 codes. The codes are

     BOOTTIME  NODE_SWVERS

     CLUSTER_NODES NODENAME

     CPU   PAGEFILE_FREE

     NODE_HWTYPE  PAGEFILE_PAGE

     NODE_HWVERS  SWAPFILE_FREE

     NODE_NUMBER  SWAPFILE_PAGE

     NODE_SWTYPE  VERSION

 

The GETSYI_SVC_SUBS.C file defines all possible codes. Three codes in the file are specific to VMS Version 5.x or OpenVMS. These are commented out. You can remove the comments in order to use them.

 

The OpenVMS System Services Reference Manual describes each code under the
$ GETSYI system service.

 

Running PRINT Client

To run the PRINT client, type the following command at the DCL prompt:

PRINTF [-d#][-hhost]filename

-d#

Debugging value that is passed to the ONCRPC_SET_CHAR routine. Debugging values are defined in the ONCRPC_CONST.H file. The pound sign (#) represents a hexadecimal number. The default is 0.

-hhost

Domain name of the host running the remote server. The default is the local host.

filename

Name of the file to be displayed on the screen. You must have the appropriate privilege to gain access to this file.

 

Running SYSINFO Client

To run the SYSINFO client, type the following command at the DCL prompt:

SYSINFO [-d#][limit]

-d#

Debugging value that is passed to the ONCRPC_SET_CHAR routine. Debugging values are defined in the ONCRPC_CONST.H file. The pound sign (#) represents a hexadecimal number. The default is 0.

limit

Maximum number of replies the client can receive before it exits. The client processes until it reaches this limit or it times out, whichever comes first.

 

Miscellaneous Clients and Servers

The sample programs listed in Table 20-1 include three client programs using the client_call, callrpc, and pmap_rmtcall routines; a synchronous server; and a server using the registerrpc routine.

In this group of programs, a client calls a server to request system information, and the server provides the information.

Table 20-1     GETSYI Sample Programs 

File

Description

GETSYI.COM

Command procedure that compiles and links related RPC sample programs.

GETSYI.H

Header file used by the sample RPC GETSYI programs. Generated by RPCGEN.

GETSYI.X

Sample RPCGEN input file for the TCP and UDP transports.

GETSYI_CLNT.C

Sample client code generated by the RPCGEN compiler.

GETSYI_CLNT_CALL.C

Sample RPC client program using the clnt_call routine.

GETSYI_CLNT_CALLRPC.C

Sample RPC client program using the callrpc routine.

GETSYI_CLNT_RMTCALL.C

Sample RPC client program using the pmap_rmtcall routine.

GETSYI_CLNT_SUBS.C

Miscellaneous client support routines.

GETSYI_DEF.H

Contains various structure definitions used by the RPC sample programs.

GETSYI_PROC_S.C

Sample RPC procedure for a synchronous server.

GETSYI_SVC.C

Sample RPC program for a synchronous server. Generated by RPCGEN.

GETSYI_SVC_REG.C

Sample RPC program and procedure using the registerrpc routine.

GETSYI_SVC_SUBS.C

Miscellaneous server support routines for the sample GETSYI programs.

GETSYI_XDR.C

XDR routines generated by RPCGEN, used by sample RPC clients and servers.

GETSYI_XDR_2.C

Alternative XDR routines using xdr_union, used by sample RPC clients and servers.

Batch RPC Sample Programs

In the batch programs listed in Table 20-2, a client sends a file to a server one record at a time. After the last record is sent, the client flushes the pipeline and receives the total number of records received by the server.

Table 20-2     Sample RPC Batch Programs 

File

Description

PRINT.C

Sample RPC batch client program.

PRINT.COM

Command procedure that compiles and links related RPC sample programs.

PRINT.H

Header file for the sample RPC batch programs. Generated by RPCGEN.

PRINT.X

RPCGEN input file used by the sample RPC batch programs.

PRINT_DEF.H

Contains various structure definitions used by the RPC sample batch programs.

PRINT_SVC.C

Sample RPC batch server program.

PRINT_XDR.C

XDR routines used by the sample RPC batch programs. Generated by RPCGEN.

Broadcast RPC Sample Programs

In the broadcast RPC programs listed in Table 20-3, the server returns the name of its host and operating system. The each result routine displays the address of the remote host and the values returned.

The clnt_broadcast routine waits for replies until it times out or reaches the specified limit. Then the client stops processing.

Table 20-3     Broadcast RPC Sample Programs 

File

Description

SYSINFO.C

Sample RPC client program using broadcast RPC.

SYSINFO.COM

Command procedure that compiles and links related RPC sample programs.

SYSINFO.H

Header file used by the sample RPC broadcast programs. Generated by RPCGEN.

SYSINFO.X

RPCGEN input file used by the sample RPC broadcast programs.

SYSINFO_DEF.H

Contains various structure definitions used by the sample RPC broadcast programs.

SYSINFO_SVC.C

Sample RPC server program using broadcast RPC.

SYSINFO_XDR.C

XDR routines used by the sample RPC broadcast programs. Generated by RPCGEN.