ANSI C, C++

#include <dcrpc.h>
int  dc_rpc_poll_any_replies (int des, DCLONG timeout,
                              DCLONG flags)

K&R C

#include <dcrpc.h>
int  dc_rpc_poll_any_replies (des, timeout, flags)
int        des;
DCLONG     timeout;
DCLONG     flags;

The function dc_rpc_poll_any_replies() receives the processing results of a service requested through an asynchronous-response-type RPC (DCRPC_NOWAIT specified for flags of the function dc_rpc_call()).

To designate a specific asynchronous response received, specify DCRPC_SPECIFIC_MSG for flags. If this flag is set, the function dc_rpc_poll_any_replies() receives the response of the asynchronous response-type RPC which returned the descriptor specified for des.

Not to designate a specific asynchronous response received, specify DCNOFLAGS for flags. In this case, the value specified for des is ignored. When the function dc_rpc_poll_any_replies() with DCNOFLAGS specified for flags terminates normally, it returns the same value as the descriptor of the received asynchronous response.

The function dc_rpc_poll_any_replies() returns in the following cases:

• A response is received from an asynchronous-response RPC.
• A response wait timeout occurs (the response wait time specified in timeout has elapsed).

When the function dc_rpc_poll_any_replies() terminates normally, the received response is stored in the response area specified in the function dc_rpc_call() using the asynchronous response-type RPC.

The following items are described after the list of return values. See each description For details on the function dc_rpc_poll_any_replies().

(1) timeout, an argument of the function dc_rpc_poll_any_replies()

(2) Timing when the function dc_rpc_poll_any_replies() results in error

(3) Specification for returning the value DCRPCER_SERVICE_TERMINATED

(4) Relationship between error return values and synchronization point processing

(5) When a response cannot be received by the function dc_rpc_poll_any_replies()

(6) Notes on using the function dc_rpc_poll_any_replies()

des

Specify the descriptor which was normally returned by the function dc_rpc_call() (DCRPC_NOWAIT specified for flags) of asynchronous response-type RPC. If DCNOFLAGS is specified for flags, the value set here will be ignored.

timeout

Specify wait time (in seconds or milliseconds) until the results of the function dc_rpc_call() of an asynchronous-response-type RPC are returned. The specified wait time must be in the range from -1 to the maximum value which can be indicated by DCLONG type.

When the function dc_rpc_poll_any_replies() receives an asynchronous response, the response waiting interval specified in the UAP is not referenced.

If 0 is specified here, DCNOFLAGS or DCRPC_SPECIFIC_MSG is specified for flags, and no response is returned, then the function dc_rpc_poll_replies() will immediately return with the return value DCRPCER_TIMED_OUT. If DCRPC_WAIT_MILLISEC is specified for flags, the wait time will be 50 milliseconds.

When -1 is specified, the function dc_rpc_poll_any_replies() continues to wait until a response is returned.

flags

Use the following format:

{DCNOFLAGS|DCRPC_SPECIFIC_MSG}[|DCRPC_WAIT_MILLISEC]

DCNOFLAGS

Asynchronous responses received by the function dc_rpc_poll_any_replies() will not be identified.

DCRPC_SPECIFIC_MSG

The response to the asynchronous-response-type RPC which returned the descriptor specified for des will be received.

DCRPC_WAIT_MILLISEC

The wait time specified by timeout is assumed to be in milliseconds.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

The monitoring time for receiving an asynchronous response is reset each time a response is returned. Therefore, when a specific asynchronous response received is designated (DCRPC_SPECIFIC_MSG is specified for flags), a response may be received even if the time specified for timeout has elapsed. Alternatively, the function dc_rpc_poll_any_replies() may not return with an error, giving the return value DCRPCER_TIMED_OUT even if the time specified for timeout has elapsed.

The following explains the timing when an error is returned from the client UAP if the SPP to which the service request is addressed terminates abnormally.

If an SPP to execute a service terminates abnormally before completion of the processing, the function dc_rpc_poll_any_replies() returns with an error, giving the return value DCRPCER_TIMED_OUT. If -1 is specified for timeout, an argument of the function dc_rpc_poll_any_replies(), the function returns with an error, giving the return value DCRPCER_SERVICE_NOT_UP.

When the function dc_rpc_poll_any_replies() results in error due to time monitoring for the function

In the following cases, the function returns with an error, giving the return value DCRPCER_TIMED_OUT, after the time specified for timeout, an argument of the function dc_rpc_poll_any_replies(), has elapsed:

• The entire OpenTP1 at the node containing the SPP terminates abnormally.
• An error occurs before the server UAP receives service request data or before the client UAP receives the result after the server UAP processing is completed.

You may want to determine whether the SPP that requested a service terminated abnormally before completion of processing based on a returned value other than DCRPCER_TIMED_OUT or DCRPCER_SERVICE_NOT_UP. If so, specify 00000001 in the rpc_extend_function operand of the user service definition. This specification returns DCRPCER_SERVICE_TERMINATED if the above error occurs. If 00000000 is specified in the rpc_extend_function operand, or the operand is omitted, DCRPCER_TIMED_OUT or DCRPCER_SERVICE_NOT_UP is returned rather than DCRPCER_SERVICE_TERMINATED.

The relationship between return values of the function dc_rpc_poll_any_replies() and synchronization point processing (commitment and rollback) is explained below. The description applies to the service request which is a transaction, rather than the service request which is not a transaction (including the case when DCRPC_TPNOTRAN is specified for flags of the function dc_rpc_call()).

If commitment is performed even though the function dc_rpc_poll_any_replies() returns with an error

The return value DCRPCER_TIMED_OUT may be returned due to abnormal termination of the service function which the service request is addressed, a node error, or network error. However, when the client UAP is not a transaction, the service function which the service request is addressed may terminate normally and database may be updated.

Error return values which require rollback processing

If the function dc_rpc_poll_any_replies() called from a transaction returns with an error, some return values always require rollback processing for the transaction (the server UAP enters in rollback_only state). In this case, rollback processing is always performed even if either of the commitment function or rollback function is used. The following return values of the function dc_rpc_poll_any_replies() always require rollback processing for the transaction:

• DCRPCER_INVALID_REPLY
• DCRPCER_NO_BUFS_AT_SERVER
• DCRPCER_NO_SUCH_SERVICE
• DCRPCER_REPLY_TOO_BIG_RB

The function dc_rpc_poll_any_replies() cannot receive a response if either of the following functions is called by the UAP requesting a service with an asynchronous response-type RPC.

1. The receiving of asynchronous responses is rejected by the function dc_rpc_discard_further_replies()
2. Commitment or rollback processing is performed in the synchronization point processing function when a service is requested from a transaction.

The response returned after the above function is called is discarded. Receive all required asynchronous responses by using the function dc_rpc_poll_any_replies() before calling the above function when an asynchronous response-type RPC is used.

1. If the function dc_rpc_poll_any_replies() is called with the wait time as 0 (0 specified for the argument timeout), it may be probable that responses which have arrived cannot be received, because of a scheduling problem in a multithread environment. Note that a program which calls the function dc_rpc_poll_any_replies() with the wait time as 0 could be trapped in an endless loop until all responses are received.
2. If the function dc_rpc_poll_any_replies() with no descriptor specified returns with an error, the descriptor of the error response is undefined. To know the corresponding descriptor when the function dc_rpc_poll_any_replies() returns with an error, specify DCRPC_SPECIFIC_MSG for flags.