fclogerr Command

Purpose

Records information about failure or noteworthy conditions to the AIX® error log and the BSD system log.

Syntax

/usr/sbin/rsct/bin/fclogerr { -e event -t error_template_label -i error_template_headerfile -r resource -s source_filename -p line_of_code_pos -v sidlevel -l lpp_name -a assoc_fid { [ -d detail_data_item[,detail_data_item,...] -x detail_data_type[,detail_data_type,...] -y detail_data_len[,detail_data_len,...] ] | [ -f detail_data_file] } -b BSD_syslog_message_text } | -h

Description

This interface is used by any script program that wishes to record information to the AIX Error Log and the BSD System Log. The information written to this device is intended for use by the system administrator or operator to determine what failure conditions or other noteworthy conditions have occurred on the system that require attention. The purpose of the AIX Error Log and the BSD System Log is to record enough information about a condition so that the nature, impact, and response to the condition can be determined from the report, without requiring a recreation of the condition to detect what condition occurred and where. Any software that encounters permanent failure conditions that will persist until some type of direct intervention occurs, or encounters a condition that should be brought to the attention of the system administrator, should use fclogerr to record this information in the AIX Error Log and the BSD System Log.

Scripts should establish a basic FFDC Environment or an FFDC Error Stack Environment before using fclogerr, either by creating or inheriting the environment. fclogerr records information to the AIX Error Log and the BSD System Log even if these environments are not established, but the interface will not be capable of generating an FFDC Failure Identifier unless one of these environments exists.

Processes designed to use the FFDC Error Stack can also make use of the fclogerr interface, and should make use of it if they encounter conditions that require administrator attention or intervention to resolve.

To ensure proper identification of the condition and the location at which it was encountered, the FFDC Policy recommends that fclogerr should be called in-line in the script's source code module and invoked as soon as the condition is detected. fclogerr will record source code file name and line of code information to assist in identifying and locating the source code that encountered the condition. fclogerr can be invoked by a subroutine or autoloaded routine to record this information if this is necessary, provided that all location information and necessary failure detail information is made available to this external routine. The external recording routine must record the true location where incident was detected.

Although fclogerr reports information to both the AIX Error Log and the BSD System Log, different options must be provided to this interface for each recording device. The Detail Data information recorded to the AIX Error Log is not also recorded to the BSD System Log; BSD System Log information is provided through different command options. This may require the fclogerr user to duplicate some information in this call.

Flags

-a
Contains the FFDC Failure Identifier for a failure condition reported by software used by this application which causes or influenced the condition being recorded at this time. This identifier should have been returned to this application as part of the software's result indication. The caller provides this identifier here so that the FFDC Error Stack can associate the failure report it is making at this time with the previously recorded failure report. This permits problem investigators to trace the cause of a failure from its various symptoms in this application and others to the root cause in the other software. If no other software failure is responsible for this condition, or if the other software did not return an FFDC Failure Identifier as part of its result information, this option should be omitted.
-b
Specifies the text message to be written to the BSD System Log.
-d
One or more data items that provides detailed information on the condition, used to provide the Detail Data in the AIX Error Log entry. If details of the information are too lengthy, these details can be written to a file, and the name of that file provided as the detail_data_file parameter. If a detail data file name is provided, this option should be omitted. If neither the detail_data or the detail_data_file parameters are provided or appear valid, null information will be recorded for the detail data in the AIX Error Log.

More than one data item may be provided with this option. Each data item must be separated by commas (,) with no intervening white-space characters. If a data item has imbedded whitespace characters, the data item must be enclosed in double quotes ("). The data items themselves must not contain commas (,), as the command interprets commands a field separators.

This option must be accompanied by the -x and -y options.

-e
Specifies the FFDC Log Event Type. Current valid values are FFDC_EMERG, FFDC_ERROR, FFDC_STATE, FFDC_TRACE, FFDC_RECOV, and FFDC_DEBUG. This code gives a general description of the type of event being logged (emergency condition, permanent condition, informational notification, debugging information, etc.) and the severity of the condition. If this option is not specified, the event type FFDC_DEBUG is assigned to this incident record.
-f
Name of a file containing details about the condition being reported. This option is used when the details are too lengthy to record within the remaining 100 bytes of Detail Data information left to the application by fclogerr, or when a utility exists that can analyze the detail information. The contents of this file is copied to the /var/adm/ffdc/dumps directory, and the file's new location is recorded as the Detail Data in the AIX Error Log entry.
-h
Displays a help message to standard output and exits. No other processing is performed, regardless of the options specified.
-i
Specifies the absolute path name of the header file (.h) that contains the error logging template identification number that corresponds to the error_template_label specified in the -l option. This template must also be found in the node's error logging template repository (/var/adm/ras/errtmplt). This header file was generated by the errupdate command as part of the source code's building procedures, and should have been included in the LPP's packaging to be installed on the node with the software. If this option is not specified or the header file cannot be found when the script is executed, fclogerr will record the failure information using its own default error template (label FFDC_DEF_TPLT_TR, identifier code 2B4F5CAB).
-l
Specifies an abbreviation of the name of the licensed programming product in which this software was shipped. This value should be recognizable to both customer and application-support services as an acceptable name for the LPP. Examples of such values are: PSSP, GPFS™, LoadLeveler®, and RSCT. If this option is not provided or appears invalid, the character string PPS_PRODUCT is used.
-p
Specifies the line of code location within the source code module where the condition is being reported. The value provided must be a valid integer value. To allow for proper identification and location of the condition, this value should be as close to the line of code that detected the condition as possible. Korn Shell scripts can use the value of $LINENO. Script languages that do not provide a special line count variable can provide a symbolic value here that a developer can use to locate the spot in the source code where fclogerr is being used. If this option is not valid or not provided, the value of 0 is used.
-q
Suppresses the generation of warning messages from the command. Warning are generated when the command must substitute default information for missing information, or when the command is unable to copy the detail_data_file to the /var/adm/ffdc/dumps directory.
-r
Specifies the software component name. This is a symbolic name for the software making the report and should be a name recognizable to both customer and application-support services. The character string is limited to 16 characters.
-s
Specifies the name of the source file containing the line of code that encountered the condition being reported. For Korn and Borne Shell scripts, the argument to this option should be set to $0; C Shell scripts would set this argument to ${0}. If this option is not provided or not valid, the character string unknown_file is used.
-t
Indicates the symbolic label given to the AIX Error Logging template in the error log repository. The errupdate command that builds error logging templates creates a macro that maps this label to an integer code. This label begins with the characters ERRID_ and is a maximum of 19 characters. If this option is not specified or the header file cannot be found when the script is executed, fclogerr will invoke the errlogger to create a message in the AIX Error Log using the OPMSG template.
-v
Indicates the SCCS version number of the source code module that detected the condition being recorded. For source code built under SCCS control, this should be set to "1.1" (the double-quotes are necessary). If this option is not provided or is not valid, the character string unknown is used.
-x
Indicates how the data items specified by the -d option are to be interpreted when recording this information to the AIX Error Log. These types must agree with the corresponding fields of the AIX Error Logging template specified in the -t option. Each type indicates how the corresponding data item in the -d list is interpreted. Acceptable values for this option are ALPHA, HEX, and DEC. There must be a matching type listed in the -x argument for each argument in the -d list.

This option must be supplied if the -d option is provided.

-y
Indicates the length of the data items (in bytes) specified by the -d option. These lengths must agree with the corresponding fields of the AIX Error Logging template specified in the -t option. There must be a matching type listed in the -y argument for each argument in the -d list.

This option must be supplied if the -d option is provided.

Parameters

file_name
The name of the file to be searched for an FFDC Failure Identifier. More than one file may be provided. If a file name is not provided, fcfilter reads from standard input.

Exit Status

fclogerr returns the following exit status codes upon successful completion:

0
Information successfully queued to be written to the AIX Error Log and the BSD System Log. An FFDC Failure Identifier for the record is displayed to standard output. The caller should capture standard output to obtain this value.
2
Help information displayed and processing ended.
12
No information recorded to the AIX Error Log, and no FFDC Failure Identifier is provided by the command. The command user provided an invalid option to this command.

On AIX platforms other than AIX, fclogerr returns the following exit status codes when a failure occurs:

38
A record could not be made int he BSD System Log for this incident. The System Log is experiencing a failure condition. On AIX systems, a report was recorded to the AIX Error Log; on other systems, this should be considered a failure.

When fclogerr is provided with incomplete information, it substitutes default information for the missing information and attempts to make a record in the FFDC Error Stack. Warnings are generated in these cases, and warning messages are generated unless the -q option is specified. In cases where more than one warning condition was detected, the command returns an exit status code for the condition it considered the most severe. The following exit status codes are returned by fclogerr when warning conditions are detected:

10
The command user failed to provide the -i option to this command, or the header file named as the argument to the -i option could not be located. The command will record generic information to the AIX Error Log in this case, using the First Failure Data Capture default template (label FFDC_DEF_TPLT_TR, identifier code 2B4F5CAB).
26
Both a detailed data string and a detail data file were provided to this routine. The routine chose the detail data string and ignored the detail data file.
28
The name of the resource detecting the incident was not provided. The default resource name ffdc was substituted for the missing resource name.
29
At least one component of the detecting application information—source code file name, source code file version, LPP name, line of code position—was not provided. Default information was substituted for the missing information.
32
The file named in the detail_data_file parameter could not be copied to the /var/adm/ffdc/dumps directory. The FFDC Error Stack entry cites the original version of this file. Do not discard the original copy of this file.
33
The -e option was not specified, or did not specify a valid FFDC event type. The event type FFDC_DEBUG has been assigned to this incident record.
34
A message was not supplied in the format parameter. As a result, a generic message was recorded to the BSD System Log for this incident.
35
No detailed information was provided for this incident. Later problem analysis may be difficult without these details to indicate specifics on the incident.
36
The length of the detail data string was greater than the capacity of the AIX Error Log entry limit. Detail data was truncated to fit in the available space. Some information on the incident may have been lost in this truncation.
37
An FFDC Error Identifier could not be constructed for the report created by this routine. An FFDC Failure Identifier is not written to standard output, but information on the incident was recorded to the AIX Error Log and the BSD System Log.
38
A record could not be made in the BSD System Log for this incident. The System Log may not be enabled, or may be experiencing problems. On AIX systems, a report was recorded to the AIX Error Log; on other systems, this should be considered a failure.

Examples

For this example, a Korn Shell script attempts to access configuration information from a file. If this attempt fails, the code will record a failure to the AIX Error Log using the following template source code:

*! mymesgcat.cat
+ SP_FFDCEXMPL_ER:
    Comment        = "Configuration Failed - Exiting"
    Class          = S
    Log       = true
    Report         = true
    Alert          = false
    Err_Type  = PERM
    Err_Desc  = {3, 10, "CONFIGURATION FAILURE - EXITING"}
    Prob_Causes    = E89B
    User_Causes    = E811
    User_Actions   = 1056
    Fail_Causes    = E906, E915, F072, 108E
    Fail_Actions   = {5, 14, "VERIFY USER HAS CORRECT PERMISSIONS TO ACCESS FILE"},
               {5, 15, "VERIFY CONFIGURATION FILE"}
    Detail_Data    = 46, 00A2, ALPHA
    Detail_Data    = 42, EB2B, ALPHA
    Detail_Data    = 42, 0030, ALPHA
    Detail_Data    = 16, EB00, ALPHA
    Detail_Data    = 16, 0027, ALPHA
    Detail_Data    = 4, 8183, DEC
    Detail_Data    = 4, 8015, DEC
    Detail_Data    = 60, 8172, ALPHA

This definition yields the following AIX Error Logging Template:

LABEL:            ERRID_SP_FFDCEXMPL_ER
IDENTIFIER:        <calculated by errupdate during source code build>

Date/Time:         <filled in by AIX Error Log subsystem>
Sequence Number:   <filled in by AIX Error Log subsystem>
Machine Id:        <filled in by AIX Error Log subsystem>
Node Id:           <filled in by AIX Error Log subsystem>
Class:             S
Type:              PERM
Resource Name:     <filled in by -r option to fclogerr>

Description
CONFIGURATION FAILURE - EXITING

Probable Causes
COULD NOT ACCESS CONFIGURATION FILE

User Causes
USER CORRUPTED THE CONFIGRATION DATABASE OR METHOD

    Recommended Actions
    RE-CREATE FILE

Failure Causes
COULD NOT ACCESS CONFIGURATION FILE
PERMISSIONS ERROR ACCESSING CONFIGURATION DATABASE
FILE READ ERROR
FILE IS CORRUPT

    Recommended Actions
    VERIFY USER HAS CORRECT PERMISSIONS TO ACCESS FILE
    VERIFY CONFIGURATION FILE

Detail Data
DETECTING MODULE
<filled in by fclogerr options>
ERROR ID
<The FFDC Failure Identifier created by fclogerr>
REFERENCE CODE
<The -a option value to fclogerr>
FILE NAME
<Must be supplied as part of -d option list to fclogerr>
FUNCTION
<Must be supplied as part of -d option list to fclogerr>
RETURN CODE<Must be supplied as part of -d option list to fclogerr>
ERROR CODE AS DEFINED IN sys/errno.h
<Must be supplied as part of -d option list to fclogerr>
USER ID<Must be supplied as part of -d option list to fclogerr>

The first three Detail Data Fields are constructed by the fclogerr routine from information passed in the parameters. The remaining Detail Data must be supplied with the -d option, and the type of data supplied must be indicated by the -x option. The example source code segment below demonstrates how this is done, and how fclogerr is invoked to record the information in the AIX Error Log and the BSD System Log.

typeset CONFIG_FNAME
typeset INBUF
typeset MINUSDOPTS
typeset MINUSXOPTS
typeset MINUSYOPTS
typeset FID
integer MYCLIENT
integer RC
    :
MYCLIENT=$$
CONFIG_FNAME="/configfile.bin"
exec 3< $CONFIG_FNAME
    :
read -u3 INBUF
RC=$?
if ((RC != 0))
then
    # Create Detail Data Memory Block for AIX Error Log Template
    # Need to know the EXACT structure of the Template to do this correctly.
    #    Field 1 - filled in by fc_log_error
    #    Field 2 - filled in by fc_log_error
    #    Field 3 - filled in by fc_log_error
    #    Field 4 - name of configuration file being used - 16 bytes
    #    Field 5 - name of function call that failed - 16 bytes
    #    Field 6 - return code from failing function - 4 byte integer
    #    Field 7 - errno from failing function call (unused) - 4 byte integer
    #    Field 8 - user ID using this software - remaining space (62 bytes)
    # This source code supplied fields 4 through 8 in the "-d" option, and
    # describes the data types for each in the "-x" option.
    MINUSDOPTS=$CONFIG_FNAME
    MINUSXOPTS="ALPHA"
    MINUSYOPTS="16"
    MINUSDOPTS="$MINUSDOPTS,read"
    MINUSXOPTS="$MINUSXOPTS,ALPHA"
    MINUSYOPTS="$MINUSYOPTS,16"
    MINUSDOPTS="$MINUSDOPTS,$RC"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,0"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,$MYCLIENT"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,60"
    FID=$(fclogerr -e FFDC_ERROR -t ERRID_SP_FFDCEXMPL_ER -i /usr/lpp/ssp/inc/
myprog.h -r myprog -s myprog.ksh -p $LINEPOS -v "1.1" -l PSSP -d $MINUSDOPTS -x
$MINUSXOPTS -y $MINUSYOPTS -b "myprog Configuration Failure - Exiting")
    RC=$?
    if ((RC == 0))
    then
         fcdispfid $FID
         return 1
    else
         :
    fi
fi

Now consider a slight variation on the above example, using the same AIX Error Logging template, but this time using an external command to obtain the configuration data from a file that this source code supplies. The command exits with a non-zero exit status and prints an FFDC Failure Identifier to standard output if it encounters any failure conditions. Also, to demonstrate the use of double-quotes in the -d list, the configuration file will have an embedded space in the name:

typeset CONFIG_FNAME
typeset INBUF
typeset MINUSDOPTS
typeset MINUSXOPTS
typeset MINUSYOPTS
typeset FID
typeset OUTPUT
integer MYCLIENT
integer RC
    :
MYCLIENT=$$
CONFIG_FNAME="This is a test"
OUTPUT=$(configdabeast $CONFIG_FNAME)
RC=$?
if ((RC != 0))
then
    # Create Detail Data Memory Block for AIX Error Log Template
    # Need to know the EXACT structure of the Template to do this correctly.
    #    Field 1 - filled in by fc_log_error
    #    Field 2 - filled in by fc_log_error
    #    Field 3 - filled in by fc_log_error
    #    Field 4 - name of configuration file being used - 16 bytes
    #    Field 5 - name of function call that failed - 16 bytes
    #    Field 6 - return code from failing function - 4 byte integer
    #    Field 7 - errno from failing function call (unused) - 4 byte integer
    #    Field 8 - user ID using this software - remaining space (62 bytes)
    # This source code supplied fields 4 through 8 in the "-d" option, and
    # describes the data types for each in the "-x" option.
    MINUSDOPTS="\""$CONFIG_FNAME"\""
    MINUSXOPTS="ALPHA"
    MINUSYOPTS="16"
    MINUSDOPTS="$MINUSDOPTS,configdabeast"
    MINUSXOPTS="$MINUSXOPTS,ALPHA"
    MINUSYOPTS="$MINUSYOPTS,16"
    MINUSDOPTS="$MINUSDOPTS,$RC"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,0"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,$MYCLIENT"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,60"
    FID=$(fclogerr -e FFDC_ERROR -t ERRID_SP_FFDCEXMPL_ER -i /usr/lpp/ssp/inc/
myprog.h -r myprog -s myprog.ksh -p $LINEPOS -v "1.1" -l PSSP -d $MINUSDOPTS -x
$MINUSXOPTS -y $MINUSYOPTS -a $OUTPUT -b "myprog Configuration Failure - Exiting")
    RC=$?
    if ((RC == 0))
    then
         fcdispfid $FID
         return 1
    else
         :
    fi
fi

Implementation Specifics

This command is part of the Reliable Scalable Cluster Technology (RSCT) fileset.