NAME

rpc_server_listen- tells the RPC run-time system to listen for remote procedure calls

SYNOPSIS

#include <dce/rpc.h>

void rpc_server_listen(
	unsigned32 max_calls_exec,
	unsigned32 *status);

PARAMETERS

Input

max_calls_exec

Specifies the number of concurrent executing remote procedure calls the server must be able to handle. The RPC run-time system allocates sufficient call threads to handle this number of concurrent calls.

The value rpc_c_listen_max_calls_default specifies an implementation-dependent default value >= 1.

Note:

The following routines also specify a max_call_requests argument that specifies the network resources allocated for concurrent call requests:

 

rpc_server_use_all_protseqs()
rpc_server_use_all_protseqs_if()
rpc_server_use_protseq()
rpc_server_use_protseq_ep()
rpc_server_use_protseq_if()

Normally the values of max_calls_exec and max_call_requests are the same. Servers are guaranteed to support the minimum of max_calls_exec and max_call_requests concurrent remote procedure calls. Applications should not rely on a server handling more than this number.

Output

status

Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

rpc_s_already_listening

Server already listening.

rpc_s_max_calls_too_small

Maximum calls value is too small. Must be > 0.

rpc_s_no_protseqs_registered

No protocol sequences registered.

DESCRIPTION

The rpc_server_listen() routine causes a server to listen for remote procedure calls. The max_calls_exec argument specifies the number of concurrent remote procedure calls the server is guaranteed to be able to execute, assuming that the server has allocated sufficient network resources to receive this number of call requests.

A server application that specifies a value for max_calls_exec greater than 1 is responsible for concurrency control among the server manager routines, since each executes in a separate thread.

When the server receives more remote procedure calls than it can execute (that is, more calls than the value of max_calls_exec), the RPC run-time system accepts and queues additional remote procedure calls until a call execution thread is available; that is, the number of concurrently executing threads is < max_calls_exec. From the client's perspective a queued remote procedure call appears the same as one that the server is actively executing.

The rpc_server_listen() routine returns to the caller when one of the following events occurs:

• The rpc_mgmt_stop_server_listening() routine is called by one of the server application's manager routines.

• A client makes an authorised remote rpc_mgmt_stop_server_listening() routine call to the server.

After rpc_server_listen() returns, no further calls are processed.

RETURN VALUE

None.

SEE ALSO

rpc_mgmt_stop_server_listening()
rpc_server_register_if()
rpc_server_use_all_protseqs()
rpc_server_use_all_protseqs_if()
rpc_server_use_protseq()
rpc_server_use_protseq_ep()
rpc_server_use_protseq_if().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.