|
|
|
|
The LOG_MESSAGE verb records a message in the SNAP-IX error or audit log file. The text for the message is taken from a user-defined message file; the verb can also supply parameters to be inserted in the message.
If you use this verb, you will need to supply an appropriate message file for use with the application. For more information, see Creating a Log Message File.
For more information about the SNAP-IX audit and error log files and the format of the logged messages, refer to the SNAP-IX Diagnostics Guide.
typedef struct log_message
{
AP_UINT16 opcode; /* Verb identifying operation code. */
unsigned char opext; /* Verb extension code - reserved. */
unsigned char reserv2; /* Reserved. */
AP_UINT16 primary_rc; /* Primary return code from verb. */
AP_UINT32 secondary_rc; /* Secondary (qualifying) return code. */
AP_UINT16 msg_num; /* Number of message to log. */
unsigned char origntr_id[8]; /* ID of the originator of the message. */
unsigned char msg_file_name[3]; /* Message file to search for the */
/* required message number. */
unsigned char msg_act; /* Message action - how to log the msg. */
AP_UINT16 msg_ins_len; /* Length of data for insertion in msg. */
unsigned char *msg_ins_ptr; /* Address of data for insertion in msg.*/
};
The program using this verb supplies the following parameters:
Number of the message in the message file specified by msg_file_name .
The message identifier shown in the SNAP-IX log file consists of two parts: the SNAP-IX component identifier and the message number. The msg_num parameter gives the message number; the component identifier for a message logged by this verb is always 32,767.
Name of the component issuing the LOG_MESSAGE verb; a string of up to eight characters. This parameter is optional; set the first byte to 0x00 if you do not want to include it.
If you specify this name, SNAP-IX uses it as the first parameter inserted
into the message text; that is, this name replaces %1
in the
message text. For further information, see Creating a Log Message File.
Name of the file containing the text for the message to be logged. For information about how to create this message file, see Creating a Log Message File.
The message file must have a name consisting of three characters followed by the .msg extension. This parameter specifies only the base file name; the .msg extension is added automatically.
The message file must be stored in the directory /opt/sna/lib on the computer where the application is running. If SNAP-IX is set up to use centralized logging on a single server, the same message file must also be in /opt/sna/lib on the server that holds the log file.
Action to be taken when processing the message. This defines the log category (problem, exception, or audit) of the logged message; refer to the SNAP-IX Diagnostics Guide for more information about log categories. Possible values are:
Log as a problem message.
Log as an exception message.
Log as an audit message.
For compatibility with other CSV implementations, the following values are also supported.
These are provided for migration only, because the mapping between these values
and the SNAP-IX log categories is only approximate and may not always give
the most appropriate category; use the values
Equivalent to
Equivalent to
Equivalent to
A message of type
Length of data to be inserted into the message (0-1000 characters). Specify a length of 0 (zero) if no data is to be inserted.
Address of the data to be inserted into the message. This parameter is ignored if msg_ins_len is 0 (zero).
The data consists of 1-19 null-terminated strings. The total length of the inserted data must not exceed 1000 characters.
When you create a log message file, you specify the positions in the message text where these data strings are to be inserted. For further information, see Creating a Log Message File. The data supplied to this verb must include a string for each parameter required by the message text; the first string may be supplied in the origntr_id parameter instead of in this data string.
After the verb executes, SNAP-IX returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was unsuccessful.
If the verb executes successfully, SNAP-IX returns the following parameter:
Either the message was logged successfully, or the message was ignored because SNAP-IX is not currently configured to log messages of the specified type (exception or audit).
When a verb does not execute successfully, SNAP-IX returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.
If the verb does not execute because of a parameter error, SNAP-IX returns the following parameters:
SV_PARAMETER_CHECK
One of the following:
The first character of the msg_file_name parameter was zero or a space character.
The msg_act parameter contained a value that was not valid.
There is no SV_PARAMETER_CHECK secondary return code indicating that the specified message file was not found or could not be opened; this error will cause a return code of SV_UNEXPECTED_DOS_ERROR .
Other conditions can result in the following primary return codes ( primary_rc):
The SNAP-IX software has not been started. Contact the System Administrator for corrective action.
The opcode parameter did not match the operation code of any verb. No verb executed.
The operating system has encountered an error while processing the verb. The operating system return code is returned through the secondary_rc . If the problem persists, consult the System Administrator for corrective action.
For the meaning of the operating system return code, refer to the file /usr/include/errno.h.
The snamsgf program provided with SNAP-IX, enables you to produce your own message files to be used with the LOG_MESSAGE verb.
To use this facility, you must first create a text file containing the message numbers and text, and then use snamsgf to convert it into a message file.
A message source file is a plain ASCII text file. You can include a comment line anywhere in the file by using an asterisk (*) as the first character of the line. SNAP-IX ignores all the remaining text on this line.
The first line in the source file must be ID:
, followed
by a character string of 1-8 characters identifying the component logging
the message. This string is printed out at the start of each message in the
log file. Specify a string that identifies the user of this message file;
for example, the name of the application if only one application uses this
message file, or a string identifying a group of applications that use the
same message file.
The rest of the message source file consists of entries for individual messages. Each message is defined as a series of fields, as shown in the example that follows.
ID:MYAPPL Message: 1 Type: PROBLEM Cause Type: CSV Cause: The specified file could not be opened. Action: Check the reason shown on this message for more information. Flags: NONE String: Could not open the file.$ Filename = %1\nReason = %2
The fields are as follows:
A unique identifier for the message (a decimal number in the range 1-65,535). The messages in the file must be listed in ascending order of message number. Numbers do not need to be consecutive; however, large ranges of unused message numbers will increase the size of the message file.
The category of log message. Specify PROBLEM, EXCEPTION, or AUDIT. The actual category that SNAP-IX uses when logging the message is determined by the msg_act parameter of the LOG_MESSAGE verb. In the source file, this information is included for readability, but SNAP-IX ignores it.
A summary of the cause of the message. Specify CSV (to indicate that the message was logged using the CSV LOG_MESSAGE verb), or one of the following values:
Internal error in the application.
Resource shortage (for example, insufficient memory on the Solaris computer).
User error (for example, parameters that are not valid supplied on the command line to an application program).
SNA protocol violation by a remote system.
Configuration mismatch.
A normal event, reported for information only.
The cause of the condition being logged.
Any action that the local System Administrator should take as a result of the message. For audit messages, which provide accounting and progress information instead of reporting error conditions, there is generally no action required.
Specify CONSOLE to indicate that the message should be written to the Solaris computer's system console as well as to the log file, or NONE to indicate that the message should be written only to the log file.
The text of the message (1-256 characters). To include parameters supplied to the LOG_MESSAGE verb, use %1, %2, and so on to indicate the position of each parameter. When logging the message, SNAP-IX replaces %1 with the first parameter supplied to LOG_MESSAGE, %2 with the second parameter, and so on.
The origintr_id parameter supplied to LOG_MESSAGE, if any, replaces %1. The first parameter in the data string supplied to LOG_MESSAGE replaces %2 (if origntr_id was used) or %1 (if origntr_id was not used); the second parameter in the data string replaces %3 or %2, and so on.
The following also applies to these fields:
Each field name (such as Message) must be at the start of a line, followed by a colon. Spaces or tabs following the colon are ignored. All the text associated with the field name must be in a single line (except when lines are concatenated using the $ character, as described below); there is no limit on the length of the line.
In the Cause, Action, and String fields, the following characters can be used to control the format of the text written to the log file:
Insert a tab character in the output text.
Insert a new-line character in the output text, and continue with the following line of the source file. This enables you to specify a text field that extends over more than one line. The last line of the text field must not end with a $ character.
Insert a new-line character in the output text, and continue with the following character of the source file. This enables you to specify a text field as a single line in the source file, and to specify where line breaks will appear in the output. However, it is recommended that you split long text fields into multiple lines using the $ character, as described above, for readability.
Insert a $ character in the output text.
Stringparameter only)
Insert the nth parameter supplied to the log call in the output text.
The logging code does not insert new-line characters into text strings except where \n or $ characters are included in the source text. To ensure that the output text is easily readable on an 80-column screen, use these characters to force line breaks.
The fields Message, Type, Cause Type, Flags, and String must be specified. The fields Cause and Action are optional; to indicate that one of these fields is not used, specify the following string, with capitalization as shown:
@!* Not Used
For example, if the message is an audit message and no action is required, use the following line:
Action: @!* Not UsedIn this case, SNAP-IX will not include the Action field when writing the message to the log file.
The total length of the Cause and Action fields must not exceed 2048 characters.
The previous section shows a sample entry in the message source file.
If you build a message file from a source file containing this entry, an application
can call LOG_MESSAGE specifying message number 1 in this message file. The
application's supplied data must contain two null-terminated strings, one
specifying the file name (for example, /usr/jim/myfile)
and one specifying the reason for the failure (for example, File not
found
). The output will then be as follows:
------------------12:17:28 BST 05/13/1994 ------------------ MYAPPL Message 32767-1, Subcode: 0 Log category: PROBLEM Cause Type: CSV System: jimsbox Process ID: 12345 Could not open the file. Filename = /usr/jim/myfile Reason = File not found Cause: The specified file could not be opened. Action: Check the reason shown on this message for more information.
This sample output assumes that verbose logging (not succinct logging) is being used. For more information about succinct logging, and the format of entries in the log file if it is being used, refer to the chapter on log messages in the SNAP-IX Diagnostics Guide.
To convert the text file into a message file, use the snamsgf program as follows:
snamsgf infile outfile
The name of the input text file is infile, including a path if it is not in the current directory.
The name of the output message file is outfile, as specified by the msg_file_name parameter on LOG_MESSAGE. The output file must have a name consisting of 1-3 characters with the extension .msg; you need not specify the extension on the command line.
The output file is created in the current directory. It must be stored in the directory /opt/sna in order for SNAP-IX to find it when it is specified by a LOG_MESSAGE verb.
For example, the following command creates the message file new.msg from the source text file /usr/fred/myfile.text :
snamsgf /usr/fred/myfile.text new
The snamsgf program writes error messages to standard error if it detects errors in the input file format.
|
|
|
 |
|