Tutorial Toolkit Function Descriptions > Utilities > RPCs
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">   
RPCs
The following describes the functional interface used for performing RPC calls from a MSC.Patran client (in PCL) to a RPC server. The functions are broken into three distinct groups: client calls (initialization, service requests), data write calls and data read calls. Every client has two associated “data streams”; the output stream (commands and data sent to the server) and the input stream (status and/or data returned from the server). In order to manage these streams properly, every client will require the following steps in the listed order:
client/server initialization
• Register the server (once only) [rpc_add_server]
• Initialize the server (once only) [rpc_init_client]
client/server data manipulation
• Write the output stream [rpc_put_xxx]
• Call the server [rpc_call]
• Read the input stream [rpc_get_xxx]
The first two steps are done during client start-up/initialization only. The last three steps must be done for every server request.
The allowable data types are described below.
 
MSC.Patran Datatype
Value
Purpose
Status
1
server SUCCESS/FAILURE return
Command
2
client request code
Integer
3
whole number (C int)
Boolean
4
TRUE/FALSE
Real
5
single precision float (C float)
String
6
text (C char[])
Integer Array
7
array of Integer
Boolean Array
8
array of Boolean
Real Array
9
array of Real
Output stream (data write) calls
All of the rpc_put_xxx routines will send data to the output stream.
 
Note:  
Any malloc failure will cause the entire output stream to be cleared.
Input stream (data read) calls
All of the rpc_get_xxx routines will copy data from the input stream into input variable. After these routines are called, the input stream pointer will automatically advance to the next position. There is no opportunity to retrieve the same data more than once. There are data inquiry commands that do not advance this pointer (rpc_inquire_xxx).
Example of the C code used to generate a server:
static char rcsid[]=
"$Header: /kola/users/pflib/testfiles/rpc/RCS/test1.c,v 1.2 93/10/04 16:20:02 malamut Exp $";
RpcHandler(handle)
int handle;
{ int type, count, rand_int, arr_int[5], cnt, bufsize;
float rand_flt, arr_flt[5];
char string[256];
char buf[256];
	RpcInquireItem(handle, &type, &count);
	printf("type = %d,  count = %d\n", type, count);
	switch ( type ) {
/* Datatype status */
	case 1:
		RpcGetStatus(handle, &rand_int);
		RpcPutStatus(handle, rand_int);
		break;
/* Datatype command */
	case 2:
		RpcGetCommand(handle, &rand_int);
		RpcPutCommand(handle, rand_int);
		break;
/* Datatype integer */
	case 3:
		RpcGetInteger(handle, &rand_int);
		RpcPutInteger(handle, rand_int);
		break;
/* Datatype boolean */
	case 4:
		RpcGetBoolean(handle, &rand_int);
		RpcPutBoolean(handle, rand_int);
		break;
/* Datatype real */
	case 5:
		RpcGetReal(handle, &rand_flt);
		RpcPutReal(handle, rand_flt);
		break;
/* Datatype string */
	case 6:
		RpcGetString(handle, &string[0], sizeof(string));
		RpcPutString(handle, string);
		break;
/* Datatype integer array */
	case 7:
		bufsize = sizeof(arr_int)/sizeof(arr_int[0]);
		RpcGetIntArray(handle, &arr_int, &cnt, bufsize);
		RpcPutIntArray(handle, arr_int, cnt);
		break;
/* Datatype boolean array */
	case 8:
		bufsize = sizeof(arr_int)/sizeof(arr_int[0]);
		RpcGetBoolArray(handle, &arr_int, &cnt, bufsize);
		RpcPutBoolArray(handle, arr_int, cnt);
		break;
/* Datatype real array */
	case 9:
		bufsize = sizeof(arr_flt)/sizeof(arr_flt[0]);
		RpcGetRealArray(handle, &arr_flt, &cnt, bufsize);
		RpcPutRealArray(handle, arr_flt, cnt);
		break;
	default:
	RpcServerEnd();  /* Server will die after current Rpc call completes */
	}
}
/****************************************************************************
*
* The all PDA RPC servers must make a call to RpcInitServer.  This establishes
* the server's run-time environment as follows.  All clients must make a call
* to RpcAddServer and RpcInitClient.
*
*      RpcInitServer(  int prognum - program number for client/server
*      same value as in RpcInitClient
*                      int progver           - program version
*                      void (*handler)(int)  - RPC service handler
*                      logical inetd         - server startup via inetd.
*                      int server_timeout    - # of seconds of inactivity
*                                              before server dies
*                      logical rpc_debug     - display rpc data on stdout
***************************************************************************/
main(argc, argv)
int argc;
char **argv;
{
int prognum;
		if((argc != 2) || (sscanf(argv[1], "%d", &prognum) != 1)){
			printf("usage : %s <prognum>\n", argv[0]);
			exit(2);
		}
		RpcInitServer(prognum, 1, RpcHandler, 0, 30, 0);
}
 
rpc_add_server
(server, prog_num, prog_ver, host)
Description:
rpc_add_server “registers” a service name (server) and associates it with a program number, program version and server host. This service name may be used later. Typically, all servers will be registered during start-up processing. This does not cause the server to start.
Input:
STRING
server[]
Name of RPC server.
INTEGER
prog_num
Server program number.
INTEGER
prog_ver
Server program version.
STRING
host[]
Host where server will run.
Output:
INTEGER
<Return Value>
Integer indicating the success or failure of the routine.
Error Conditions:
Success (0)-> registered OK
47000001-> Malloc failure (FATAL)
47000004-> RPC exists, warning only (ignore)
Remarks:
None.
Example:
Please see rpc_add_server (p. 1447) in the MSC Acumen Toolkit - Code Example.
 
rpc_init_client
(server, handle)
 
Description:
rpc_init_client returns a handle to be used for all server communication. It initializes the client/server communication link and data structures and will cause the server to start execution.
Input:
STRING
server[]
Name of RPC server program.
Output:
INTEGER
handle
Handle used by client to communicate with server.
INTEGER
<Return Value>
Integer indicating the success or failure of the routine.
Error Conditions:
Success (0)-> registered OK
47000004-> server not registered
47000001->Malloc failure (FATAL)
47000003->Client create error (FATAL)
Remarks:
None.
Example:
Please see rpc_init_client (p. 1474) in the MSC Acumen Toolkit - Code Example.
 
rpc_call
(handle)
Description:
rpc_call will send make an RPC (remote procedure call). The client’s output data will be sent and the client will wait for a response from the server.
Input:
INTEGER
handle
Pointer to client/server communication structure.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
Success (0)-> Registered OK
47000008-> RPC call failure.
Remarks:
None.
Example:
Please see rpc_call (p. 1449) in the MSC Acumen Toolkit - Code Example.
 
rpc_timeout
(handle, seconds )
 
Description:
rpc_timeout will change the amount of time before all subsequent rpc_call()s will timeout.
Input:
INTEGER
handle
Server handle.
INTEGER
seconds
Timeout in seconds.
Output:
LOGICAL
<Return Value>
FALSE - timeout setting failed
TRUE - timeout successful.
Error Conditions:
None.
Remarks:
None.
Example:
Please see rpc_timeout (p. 1502) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_bool_array
(handle, value, count)
Description:
rpc_put_bool_array will put the number of booleans as indicated by count from the array value into the output stream.
Input:
INTEGER
status
Pointer to client/server communications structure.
LOGICAL
value(5)
Array of booleans to put to the type data stream.
INTEGER
count
Number of booleans to send
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc Failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_bool_array (p. 1482) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_int_array
(handle, value, count )
Description:
rpc_put_int_array will put the number of integers as indicated by count from the array value into the output stream.
Input:
INTEGER
status
Pointer to client/server communications structure.
INTEGER
value(5)
Array of integers to put to the data stream.
INTEGER
count
Number of integers to send.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc Failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_int_array (p. 1489) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_real_array
()
Description:
rpc_put_real_array will put the number of reals as indicated by count from the array value into the output stream
Input:
INTEGER
handle
Pointer to client/server communications structure.
REAL
value(count)
Array of reals to put to the data stream.
INTEGER
count
Number of reals to send.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_real_array (p. 1495) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_boolean
(handle, value )
Description:
rpc_put_boolean will put a single boolean into the output stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
LOGICAL
value
Boolean value to put to the data stream.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_boolean (p. 1484) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_command
(handle, value )
 
Description:
rpc_put_command will put a command value into the output stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
INTEGER
value
Command value to put to the data stream.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_command (p. 1486) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_integer
(handle, value )
Description:
rpc_put_integer will put an integer value into the output stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
INTEGER
value
Integer value to put to the data stream.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_integer (p. 1491) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_real
(handle, value )
Description:
rpc_put_real will put a real value into the output stream.
Input:
INTEGER
handle
Handle to server.
INTEGER
value
Real value.
Output:
INTEGER
<Return Value>
Success (0)
Error Conditions:
47000001-> Malloc failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_real (p. 1493) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_status
(handle, value )
Description:
rpc_put_status will put a status value into the output stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
INTEGER
value
Status code to put to the data stream.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_status (p. 1498) in the MSC Acumen Toolkit - Code Example.
 
rpc_put_string
(handle, value )
Description:
rpc_put_string will put a string value into the output stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
STRING
value[]
String value to put to the data stream.
Output:
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
Remarks:
None.
Example:
Please see rpc_put_string (p. 1500) in the MSC Acumen Toolkit - Code Example.
 
rpc_clear_output
(handle )
 
Description:
rpc_clear_output will reset the output data stream. Any unsent data will be lost.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
None
Error Conditions:
None.
Remarks:
None.
Example:
Please see rpc_clear_output (p. 1451) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_bool_array
(handle, value, [count])
Description:
rpc_get_bool_array will copy a boolean array from the input stream. The number of elements copied will be the lesser of the number in the input stream or the array size. Additionally, the number of elements in the input stream will be placed in count (unless omitted).
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
LOGICAL
value(count)
Array of booleans.
INTEGER
count
Num of booleans in input stream (Optional).
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_bool_array (p. 1454) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_int_array
(handle, value [,count] )
Description:
rpc_get_int_array will copy an integer array from the input stream. The number of elements copied will be the lesser of the number in the input stream or the array size. Additionally, the number of elements in the input stream will be placed in count (unless omitted).
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
INTEGER
value
Array of integers.
INTEGER
count
Number of integers in input stream (Optional).
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_int_array (p. 1461) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_real_array
(handle, value [,count] )
Description:
rpc_get_real_array will copy a real array from the input stream. The number of elements copied will be the lesser of the number in the input stream or the array size. Additionally, the number of elements in the input stream will be placed in count (unless omitted).
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
REAL
value()
Array of reals.
INTEGER
count
Number of reals in input stream (Optional).
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_real_array (p. 1468) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_boolean
(handle, value)
Description:
rpc_get_boolean will get a single boolean from the input stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
LOGICAL
value
Boolean value.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_boolean (p. 1456) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_command
(handle, value )
Description:
rpc_get_command will get a command from the input stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
INTEGER
value
Command value.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_command (p. 1458) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_integer
(handle, value )
Description:
rpc_get_integer will get a integer from the input stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
INTEGER
value
Integer value.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_integer (p. 1463) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_real
(handle, value )
Description:
rpc_get_real will get a real value from the input stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
REAL
value
Real value.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_real (p. 1465) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_status
(handle, value )
Description:
rpc_get_status will get a status from the input stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
INTEGER
value
Status value.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_status (p. 1470) in the MSC Acumen Toolkit - Code Example.
 
rpc_get_string
(handle, value )
 
Description:
rpc_get_string will get a string from the input stream.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
STRING
value[]
String value.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_get_string (p. 1472) in the MSC Acumen Toolkit - Code Example.
 
rpc_inquire_count
(handle, count )
Description:
rpc_inquire_count will determine how many item remain in the input stream. Each different data type (integer, status, real array, etc.) counts as one.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
INTEGER
count
Number of items remaining in the input stream.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_inquire_count (p. 1477) in the MSC Acumen Toolkit - Code Example.
 
rpc_inquire_item
(handle, type[,count] )
Description:
rpc_inquire_item will return the type of the current input stream item and optionally, its size or count(see the available data types listed at the beginning of thissection). The count will be 1 for all simple datatypes. A string will have a size equal to the number of bytes required to represent it plus 1. Arrays will have a count equal to the number of elements in the array.
Input:
INTEGER
handle
Pointer to client/server communications structure.
Output:
INTEGER
type
Type of data in current list item.
INTEGER
count
Number of items in current list item.
INTEGER
<Return Value>
Returns the success or failure of the routine.
Error Conditions:
47000001-> Malloc failure (FATAL)
47000006-> warning, end of input
47000005-> warning, type mismatch
Remarks:
None.
Example:
Please see rpc_put_bool_array (p. 1482) in the MSC Acumen Toolkit - Code Example.