Records information about failure or noteworthy conditions to the AIX error log and the BSD system log.
/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
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.
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.
This option must be supplied if the -d option is provided.
This option must be supplied if the -d option is provided.
fclogerr returns the following exit status codes upon successful completion:
On UNIX platforms other than AIX, fclogerr returns the following exit status codes when a failure occurs:
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:
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
Commands: errpt, fcdecode, fcdispfid, fcinit, fcpushstk, fcreport
Files: ct_ffdc.h
Subroutines: fc_log_error (see the RSCT First Failure Data Capture Programming Guide and Reference)