dce_svc_define_filter(3dce)
DCE serviceability filtering routines
Synopsis
#include <stdarg.h>
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svcfilter.h>
void dce_svc_define_filter(
dce_svc_handle_t handle,
dce_svc_filter_proc_t filter_function,
dce_svc_filterctl_proc_t
filter_ctl_function,
error_status_t *status);
Description
The serviceability interface provides a hook into the message-output mechanism that allows applications to decide at the time of messaging whether the given message
should be output or not. The application defines its own routine to perform whatever checking is desired, and installs the routine (the filter_function parameter) with a call to
dce_svc_define_filter( ).
The filter routine to be installed must have the signature defined by the dce_svc_filter_proc_t typedef. Once installed, the routine will be automatically invoked every time a serviceability routine is called to output a message. The filter receives a prolog argument which contains all the pertinent information about the message. If the filter returns TRUE, the message is output per the original serviceability call. If the filter returns FALSE, the message is not output. The information in the prolog allows such decisions to be made on the basis of severity level, subcomponent, message index, and so on. For details, see the header file dce/svcfilter.h.
In addition, an application that installs a message-filtering routine must also define a routine that can be called remotely to alter the operation of the filter routine. This procedure must have the signature defined by the dce_svc_filterctl_proc_t typedef. The routine will be invoked with an opaque byte array parameter (and its length), which it is free to interpret in an appropriate manner. The remote-control routine is installed by the same call to dce_svc_define_filter( ) (as the filter_ctl_function parameter) in which the filter itself is installed. See dce_svc_filter(3dce).
Examples
The following code fragment consists of example versions of an application's routines to: filter serviceability messages; alter the behavior of the filter routine;
install the two routines.
/*****
* Filter routine -- this is the routine that's hooked into the serviceability
* mechanism when you install it by calling
*
dce_svc_define_filter().
*****/
boolean app_filter(prolog, args)
dce_svc_prolog_t prolog;
va_list args;
{
if (filter_setting) {
printf("The value of filter_setting is TRUE\n");
printf("The progname is %s\n", prolog->progname);
if (prolog->attributes & svc_c_sev_notice)
printf("This is a Notice-type message\n");
switch (prolog->table_index) {
case app_s_server:
printf("Server sub-component\n");
break;
case app_s_refmon:
printf("Refmon sub-component\n");
break;
case app_s_manager:
printf("Manager sub-component\n");
break;
}
}
return 1;
}
/*****
* Filter Control routine -- this is the entry point for the remote-control
* call to
modify the filter routine's behavior.
*****/
void app_filter_control(arg_size, arg, status)
idl_long_int arg_size;
idl_byte *arg;
error_status_t *status;
{
if (strncmp(arg, "Toggle", arg_size) != 0)
return;
else {
filter_setting = (filter_setting == FALSE) ? TRUE : FALSE;
if (filter_setting)
printf(" FILTER IS TURNED ON\n");
else
printf(" FILTER IS TURNED OFF\n");
}
return;
}
/*****
*
install_filters-- calls dce_svc_define_filter() to install the above 2 routines.
*****/
void install_filters()
{
unsigned32 status;
filter_setting = TRUE;
dce_svc_define_filter(app_svc_handle, app_filter,
dce_svc_filterctl_proc_t)app_filter_control, &status);
}
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
Related Information
Functions: dce_svc_register(3dce)