VMS Help DCE, dce_intro, dce_svc_intro, dce_svc_printf  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   dce_svc_printf - Generates a serviceability message

 SYNOPSIS

   #include <dce/dce.h>

   void dce_svc_printf(
           DCE_SVC(dce_svc_handle_t handle, char * argtypes),
           const unsigned32 table_index,
           const unsigned32 attributes,
           const unsigned32 messageID,
           . . . );

 PARAMETERS

   Input

   handle The caller's serviceability handle.

   argtypes
          Format string for the message.

   table_index
          The message's sub-component name (defined in the sams file).

   attributes
          Any routing, severity, action, or debug attributes that are
          to associated with the generated message, OR'd together.

   messageID
          The message ID, defined in the message's code field in the
          sams file.

   . . .  Any format arguments for the message string.

 DESCRIPTION

   The dce_svc_printf() routine is the normal call for writing or
   displaying serviceability messages.  It cannot be called with a
   literal text argument.  Instead, the message text is retrieved
   from a message catalog or an in-core message table.  These are
   generated by the sams utility, which in turn outputs sets of tables
   from which the messages are extracted for output.

   There are two main ways in which to call the routine. If a message
   has been defined in the sams file with both sub-component and
   attributes specified, then the sams output will include a
   "convenience macro" for the message that can be passed as the single
   argument to dce_svc_printf(), for example:

        dce_svc_printf(SIGN_ON_MSG);

   The convenience macro's name will be generated from the uppercase
   version of the message's code value (as specified in the sams file),
   with the string _MSG appended.

   If a convenience macro is not generated, or if you want to override
   some of the message's attributes at the time of output, then you must
   call the routine in its long form. An example of this form of the call
   looks as follows:

        dce_svc_printf(DCE_SVC(app_svc_handle, ""), app_subcomponent,
                       svc_c_sev_error | svc_c_route_stderr, messageID);

   DCE_SVC() is a macro that must be passed as the first argument to
   dce_svc_printf() if a convenience macro is not being used. It takes
   two arguments:

     +  The caller's serviceability handle

     +  A format string for the message that is to be output

   The format string is for use with messages that have been coded with
   argument specifiers.  It is a character string consisting of the
   argument types as they would be passed to a printf call.  If the
   message is to be routed to a binary file, the format is extended to
   include a %b specifier; using %b in a different routing will give
   unpredictable results. The %b specifier takes two arguments: an
   integer size, and a buffer pointer.

   The remaining arguments passed to dce_svc_printf() are as follows:

     +  subcomponent table index

        This symbol is declared in the sub-component list coded in
        Part II of the sams file; its value is used to index into the
        subtable of messages in which the desired message is located.

     +  message attribute(s)

        This argument consists of one or more attributes to be applied
        to the message that is to be printed.  Note that you must
        specify at least one severity here.  Multiple attributes are
        OR'd together, as shown in the following example.

        There are four categories of message attributes:

        Routing   The available routing attribute constants are:

                    - svc_c_route_stderr

                    - svc_c_route_nolog

                  However, most routing is done either by passing
                  specially-formatted strings to dce_svc_routing() or
                  by environment variable values.  Note that using
                  svc_c_route_nolog without using svc_c_route_stderr
                  will result in no message being generated.

        Severity  The available severity attribute constants are:

                    - svc_c_sev_fatal

                    - svc_c_sev_error

                    - svc_c_sev_warning

                    - svc_c_sev_notice

                    - svc_c_sev_notice_verbose

        Action    The available message action attribute constants are:

                    - svc_c_action_abort

                    - svc_c_action_exit_bad

                    - svc_c_action_exit_ok

                    - svc_c_action_brief

                    - svc_c_action_none

                  Note that svc_c_action_brief is used to suppress
                  the standard prolog.

        Debug Level
                  Nine different debug levels can be specified
                  (svc_c_debug1...svc_c_debug9 or svc_c_debug_off).

     +  message ID

        This argument consists of the message's code, as declared in
        the sams file.

 ERROR CODES

   This routine has no return value.

 RELATED INFORMATION

   Functions: dce_svc_register
              DCE_SVC_DEFINE_HANDLE