Using the dcecp log Object

The log object exports a number of operations. The following operations are useful for serviceability message routing:

· log list returns a list of the components registered by the server. The -comp option allows you to also return a list of the subcomponents for one or more named components.

· log show returns a list describing the current serviceability routing specifications for a server.

· log modify sets message routing specifications for one or more specified servers.

For a complete description of the dcecp log object and the syntax for its supported operations, refer to the log(8dce) reference page.

The remainder of this topic describes only the log modify operation and how to use it to establish routings for serviceability messages. Remember that routing is always set on a per-server basis and is recorded in the log object for each server.

The syntax for the log modify operation is:

log modify {string_binding_to_server | RPC_server_namespace_entry } \
{-change serviceability_routing_specifications}

You can specify multiple target servers as a space-separated list. Specify each server by supplying either the RPC string binding that describes the server's network location (string_binding_to_server) or a namespace entry of the server (RPC_server_namespace_entry). When specifying multiple servers, you can mix the forms in the same list.

A serviceability_routing_specification is a space-separated list of serviceability routing elements. No spaces are allowed within the specification of an individual routing element. Each routing element is a sub-string consisting of four fields containing PCS (Portable Character Set) data, as follows (shown in string syntax form):

severity:output_form:destination[:application-defined]

where:

severity
Is one of the message severity levels: FATAL, ERROR, WARNING, NOTICE, or NOTICE_VERBOSE.

output_form
Specifies how messages of the associated severity level should be processed, and must be one of the following:

BINFILE
Write these messages as binary log entries

TEXTFILE
Write these messages as human-readable text

FILE
Equivalent to TEXTFILE

DISCARD
Do not record these messages

STDOUT
Write these messages as human-readable text to standard output

STDERR
Write these messages as human-readable text to standard error

Files written as BINFILEs can be read and manipulated with a set of logfile APIs, which are described in the DCE Application Development Guide.

The BINFILE, TEXTFILE, and FILE output_form specifiers may be followed by a two-number specifier of the form:

.gens.count

where:

gens
Is an integer that specifies the number of files (that is, generations) that should be kept

count
Is an integer specifying how many entries (that is, messages) should be written to each file

The multiple files are named by appending a dot to the simple specified name, followed by the current generation number. When the number of entries in a file reaches the maximum specified by count, the file is closed, the generation number is incremented, and the next file is opened. When the maximum number of files have been created and filled, the generation number is reset to 1, and a new file with that number is created and written to (thus overwriting the already existing file with the same name), and so on. Thus the files wrap around to their beginning, and the total number of log files never exceeds gens, although messages continue to be written as long as the program continues writing them.

destination
Specifies where the message should be sent, and is a path name. You can leave this field blank if the output_form specified is DISCARD, STDOUT, or STDERR. The field can also contain a %ld string in the file name which, when the file is written, will be replaced by the process ID of the program that wrote the message(s). File names may not contain colons (:), semicolons (;), percent signs (%), or spaces.

application-defined
Is used for application-specific information. Standard DCE programs ignore it.

String Syntax

The string syntax for a serviceability routing specification is:

severity:output_form:destination[:application-defined][; . . . ]

Note that you can define multiple routing specifications as a semi-colon separated list.

For example, this specification

FATAL:TEXTFILE:/dev/console;STDOUT:

ERROR:TEXTFILE.5.100:/tmp/errors

EXIT:DISCARD:

*:FILE:/tmp/svc-log

NOTICE:BINFILE:/tmp/log%ld

WARNING:STDOUT:

instructs the serviceability mechanism to:

· Send fatal error messages to the console and to standard output.

· Send other error messages to a log-rolled file.

· Discard normal exit reports.

· Write all messages to a log file.

· Send informational messages to a temporary binary log.

· Send warnings to standard output.

Tcl Syntax

The Tcl syntax for a serviceability routing specification takes the form:

{severity\ output_form\ destination\ application-defined}

where severity, output_form, destination, and application-defined are specified as described above. In Tcl syntax, multiple routing specifications take the form:

{ {specification} {specification} {specification} }

For example, the specification examples shown in string format above would be expressed in Tcl syntax as follows:

{FATAL { {TEXTFILE /dev/console} STDOUT} }

{ERROR TEXTFILE.5.100 /tmp/errors}

{EXIT DISCARD}

{* FILE /tmp/svc-log}

{NOTICE BINFILE /tmp/log%ld }

{WARNING STDOUT {} }