### How Programs Use Serviceability

The DCE serviceability mechanism uses XPG4 message catalogs to hold message text. Additional files contain the messages' associated documentation and other extra information used by the mechanism. All of these files, including the message catalog, are generated in a single step by running the DCE sams utility. The input to sams is a single sams file that is written by the developer, and which contains all the necessary information (text, documentation, additional information) for each message. The message catalogs and associated information generated by sams are then accessed whenever dce_svc_printf( ) or one of the other serviceability routines is called to print or log a message.

Thus, the result of converting a program to use serviceability will essentially be that all printf( ), fprintf( ), and other such routines will be replaced by calls to dce_svc_printf( ) or one of the related serviceability routines. For example, a line of code such as the first one that follows would be replaced by the second:

fprintf(stderr, "File %s not found\n", filename);

dce_svc_printf(DCE_SVC(cmp_svc_handle, ""), cmp_s_server, \

svc_c_sev_error, cmp_s_file_not_found, filename);

where the constants cmp_s_server and cmp_s_file_not_found were generated by sams, and identify the server "subcomponent" of the application and the message to be written, respectively. The cmp_svc_handle constant is the application's handle to its serviceability message tables and other necessary data; cmp_s_server is actually an index to a subtable within this dynamically generated area, and cmp_s_file_not_found is the index of the message text within the subtable.

By convention, cmp is a three-character code identifying the application as a whole; serviceability uses it to group all of an application's message and table data together. Specifying svc_c_sev_error gives the message the severity of "error;" the significance of severity in serviceability will be explained in the following topics. DCE_SVC( ) is a macro that helps simplify the coding of dce_svc_printf( ) calls; as will be seen, another macro mechanism can be used to make the calls much simpler still.

###