The comm_status and fault_status attributes cause the status code of any communications failure or server runtime failure that occurs in a remote procedure call to be stored in a parameter or returned as an operation result, instead of being raised to the client application code as an exception.
The comm_status attribute causes communications failures to be reported through a specified parameter. The fault_status attribute causes server failures to be reported through a specified parameter. Applying both attributes causes all remote and communications failures to be reported through status. Any local exception caused by an error during marshalling, correctness checking performed by the client stubs, or an error in application routines continues to be returned as an exception.
The comm_status and fault_status attributes have the following syntax. (See the examples at the end of this topic.)
For an operation:
[comm_status | fault_status] operation_name ([parameter_list]);
For a parameter:
operation_name ([comm_status | fault_status] parameter_name);
Note: You can apply one of each attribute to the same operation and/or parameter at the same time. Separate the attributes with a comma. (See the example below.)
If the parameter named in a comm_status or fault_status attribute is in the parameter list for the operation in the IDL file, then it must have the out attribute in the IDL file. (Additional ACF parameters do not have in and out directional attributes.)
If the status attribute occurs on the operation, the returned value result must be defined as type error_status_t in the IDL file. If an error occurs during execution of the operation, the error code is returned as the operation result. If the operation completes successfully, the value returned to the client is the value returned by the manager code.
Note: The error_status_t type is equivalent to unsigned32, which is the data type used by the RPC runtime for an error status. The status code error_status_ok is equivalent to rpc_s_ok, which is the RPC runtime success status code.
If the status attribute occurs on a parameter, the parameter name does not have to be defined in the IDL file, although it can be. Note the following:
· If the parameter name is one used in the IDL file, then that parameter must be an output parameter of type error_status_t. If the operation completes successfully, the value of this parameter is the value returned by the manager code.
· If the parameter name is different from any name defined within the operation definition in the IDL file, then the IDL compiler creates an extra output parameter of type error_status_t in your application code after the last parameter defined in the IDL file. In a successfully completed remote call, the extra parameter has the value error_status_ok.
In either case, if an error occurs during the remote call, the error code is returned to the parameter that has the status attribute. (See the OSF DCE Problem Determination Guide for an explanation of status codes.)
If you define both additional comm_status and additional fault_status parameters, they are automatically added at the end of the procedure declaration in the order of specification in the ACF.
In the following example, there are three possible uses of the status attributes: as the operation result of add, as a parameter of subtract as defined in the IDL file, and as an additional parameter of multiply.
Example Using the comm_status and fault_status Attributes
ACF
[auto_handle] interface math_4
{
[comm_status,fault_status] add( );
subtract ([comm_status,fault_status] s);
/*
* 'sts' is not a parameter in the interface definition of
* operation 'multiply'. This specifies that the application
* wants a trailing parameter 'sts' that is of type
* error_status_t, after the parameters a and b.
*/
multiply ([comm_status] c_sts,[fault_status] f_sts);
}
IDL File
[uuid(91365000-2d28-11c9-ad5a-08002b0ecef1)]
interface math_4
{
error_status_t add ([in] double a,
[in] double b,
[out] double *c);
double subtract ([in] double a,
[in] double b,
[out] error_status_t *s);
double multiply ([in] double a,
[in] double b);
}
server.c
/*
* The three server procedures below illustrate the different
* models of comm_status and fault_status appearing in the idl
* and acf declarations above.
*
* RPC automatically passes back DCE error codes through
* comm_status and fault_status. These examples differ in their
* handling of the non-error case.
*/
error_status_t add (double a,
double b,
double * c)
{
...
*c = answer;
/*
* comm_status and fault_status are operation attributes. If
* no error occurs, the client will see the value that the
* server returns.
*
* We return error_status_ok here for the normal successful
* case.
*/
return error_status_ok;
}
double subtract (double a,
double b,
error_status_t * s)
{
/*
* "s" appears in both the idl definition and the acf
* specification.
*
* In the successful case, the client is returned the
* value that the server puts in *s. Therefore, assume
* success here.
*/
*s = error_status_ok;
...
return answer;
}
double multiply (double a,
double b,
error_status_t * c_sts,
error_status_t * f_sts)
{
/*
* c_sts and f_sts appear in the acf, but do not appear in
* the idl definition. In this case, c_sts and f_sts are
* placed at the end of the parameter list generated by the idl
* compiler. To conform to the prototype generated by idl,
* your server code must also declare these parameters.
*
* In the successful case, c_sts and f_sts are automatically
* returned to the client as error_status_ok. Even though
* c_sts and f_sts are parameters to the function, the server
* code must not modify these parameters or store through
* them.
*/
...
return answer;
}