Purpose
Records information about failure
or noteworthy conditions to the First Failure Data Capture Error Stack.
Syntax
/usr/sbin/rsct/bin/fcpushstk { [-a assoc_fid] -c message_catalog_name -m message_set -n message_number [-o message_param [,message_param,...]] -l lpp_name -p line_of_code_pos -r resource -s source_filename -v sidlevel {[-d detail_data] │ [-f detail_data_file]}
} default_message │ -h
Description
fcpushstk is used by
scripts to record failure information to the FFDC Error Stack. Scripts
record descriptive information and debugging data to the FFDC Error
Stack for use in later problem determination efforts.
The FFDC
Error Stack is used to help understand failure conditions that occur
when multiple related processes or threads are executing together
on a node to perform a common task. This device is best applied to
an application that creates one or more threads or subprocesses, which
in turn, may also create threads or subprocesses themselves. To use
the FFDC Error Stack, the script establishes an FFDC Error Stack
Environment using the fcinit interface. After this environment
is established, the application and any of its descendants can make
use of the FFDC Error Stack.
Not all software applications
will establish an FFDC Error Stack Environment. However, these applications
may be invoked by other applications or scripts that establish FFDC
Error Stack Environments. In these cases, the scripts or applications
invoking this software may wish to capture the failure information
from this software, to analyze it along with other failure information
from other software it invokes to discover any relationships or patterns
in the failures. For this reason, software that ordinarily would not
make use of the FFDC Error Stack under normal operational conditions
should at least support the use of the FFDC Error Stack when it is
used by any client invoking the software. This is accomplished by inheriting the FFDC Error Stack Environment from the parent
process through the fcinit interface.
fcpushstk records descriptions and details about noteworthy conditions to
the FFDC Error Stack. If an FFDC Error Stack Environment has
not been established by the script, either by creation or inheritance, fcpushstk does not record any information and returns control
back to the caller. This action permits the script to run in a normal
"silent" mode when debugging information is not requested, but also
permits the script to support the use of the FFDC Error Stack when
debugging information is requested.
Scripts must make explicit
calls to fcpushstk to record information to the FFDC Error
Stack when an FFDC Error Stack Environment is established. Merely
establishing the environment is not enough to result in failure data
being recorded. The fclogerr command will not make any records
to the FFDC Error Stack.
To ensure proper identification of
the condition and the location at which it was encountered, fcpushstk should be called in-line in the script's source code module, invoked
as soon as the condition is detected. fcpushstk will record
source code file name and line of code information to assist in identifying
and locating the source code that encountered the condition. fcpushstk 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 the incident was detected.
The maximum size
of an FFDC Error Stack entry is given by the FC_STACK_MAX definition
in the <rsct/ct_ffdc.h> header file. FC_STACK_MAX defines
a length in bytes. This value should be used only as a rough guide,
since this length includes data that will be used by fcpushstk to record the detecting file information, description information,
and FFDC Failure Identifier information. Any records longer than FC_STACK_MAX
bytes will be truncated to fit within the FC_STACK_MAX limit.
Flags
- -a
- Specifies an 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, the -a option should not be
provided.
- -c
- Indicates the name of the XPG/4-compliant message catalog that
contains a description of the failure being recorded. This name is
relative to the /usr/lib/nls/msg/$LANG directory. If the message
catalog cannot be found, the default_message will be displayed
to describe the failure. Note that the default_message will
not be translated between locales.
- -d
- A character string that provides detailed information on the condition,
similar to the Detail Data concept used by the AIX® Error Log. If details
of the information are too lengthy, these details can be written to
a file, and the name of that file provided as an argument to the -f option. The -d and -f options cannot be specified
at the same time. If neither the -d or the -f options
are provided or appear valid, the character string no detail data is recorded.
- -f
- Specifies the name of a file containing details about the condition
being reported, similar to the Detail Data concept used by the AIX Error Log. This option
is used when the details are too lengthy to record within the FFDC
Error Stack itself, 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 FFDC Error Stack. If a file containing
details of the condition does not exist, do not specify this option.
The -d and -f options cannot be specified at the same
time.
- -h
- Displays a help message to standard output and exits. No other
processing is performed, regardless of the options specified.
- -l
- Specifies an abbreviation of the name of the licensed program
in which this software was shipped. This value should be recognizable
to customer and application-support services as an acceptable name
for the licensed program (AIX, for example). If this option is not
provided or does not appear to be valid, the character string PPS_PRODUCT is used.
- -m
- Specifies the message set containing the message describing the
failure in the message catalog file. If this message set cannot be
located, the default_message will be displayed to describe
the failure. Note that default_message will not be translated
to the user's locale.
- -n
- Specifies the message number that describes the failure being
recorded. If this message cannot be located, the default_message will be displayed to describe the failure. Note that default_message will not be translated to the user's locale.
- -o
- Specifies a list of substitution parameters within the message
indicated by the -n option. fcpushstk only supports
character strings as substitutional parameters (%s) due to the shell
operating environment. If multiple substitutional parameters are provided,
each one must be separated by a comma (,). If any of these substitution
parameters contain imbedded white space, they must be enclosed in
double quotes ("").
- -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.
- -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 fcpushstk is being used. If this option is not valid or not
provided, the value of 0 is used.
- -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.
- -v
- Indicates the SCCS version number of the source code module that
detected the condition being recorded. For source code 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.
Parameters
- default_message
- Indicates a default message to be used as a description of the
failure, when the information cannot be retrieved from the message
catalog information supplied through the -c, -m, and -n options. If this string contains positional parameters, all
positional parameters must be specified to be character strings (%s).
The message should be enclosed in double quotes ("") if it contains
any embedded white space. fcpushstk limits the overall length
of this string to 72 characters.
Exit Status
fcpushstk returns the
following exit status codes upon successful completion:
- 0
- FFDC Error Stack Environment exists, and failure information successfully
recorded in the FFDC Error Stack. 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.
fcpushstk returns the following exit status
codes when a failure occurs:
- 11
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. The client requested to use
an option not supported in this release of the FFDC software
- 12
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. Unknown function parameter
provided to the interface.
- 15
- FFDC Error Stack Environment does not exist. No information recorded
to the FFDC Error Stack. No FFDC Failure Identifier is generated by
this command. This is the normal return code to the FFDC client when
an FFDC Error Stack Environment did not exist to be inherited via fcinit.
- 17
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. The FFDC Error Stack Environment
appears to be corrupted and should be considered unusable.
- 19
- No information recorded to the FFDC Error Stack - the FFDC Error
Stack directory does not exist or cannot be used. No FFDC Failure
Identifier is provided by this command.
- 20
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. Unable to access the FFDC
Error Stack file. The file may have been removed, or permissions on
the file or its directory have been changed to prohibit access to
the FFDC Error Stack.
- 22
- No information recorded to the FFDC Error Stack - the FFDC Error
Stack file could not be locked for exclusive use by this interface.
Repeated attempts had been made to lock this file, and all attempts
failed. Another process may have locked the file and failed to release
it, or the other process may be hung and is preventing other processes
from using the FFDC Error Stack. No FFDC Failure Identifier is provided
by this command.
- 24
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. The FFDC Error Stack file
appears to be corrupted. The client should consider the FFDC Error
Stack Environment unusable.
- 25
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. The FFDC Error Stack file
name is set to a directory name. The FFDC Error Stack Environment
should be considered corrupted and unusable.
- 32
- A dump file could not be copied to the /var/adm/ffdc/dumps directory. There is insufficient space in the file system containing
the /var/adm/ffdc directory. The fcclear command should
be used to remove unneeded FFDC Error Stacks and dump files, or the
system administrator needs to add more space to the file system. No
FFDC Failure Identifier is provided by this command.
- 40
- No information recorded to the FFDC Error Stack - information
could not be recorded in the FFDC Error Stack. There is insufficient
space in the file system containing the /var/adm/ffdc directory.
The fcclear command should be used to remove unneeded FFDC
Error Stacks and dump files, or the system administrator needs to
add more space to the file system. No FFDC Failure Identifier is provided
by this command.
- 41
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. A failure occurred when reading
control information from the FFDC Error Stack or writing incident
information to the FFDC Error Stack. The client should conclude that
the entry was not recorded for this incident.
- 99
- No information recorded to the FFDC Error Stack, and no FFDC Failure
Identifier is provided by this command. An unexpected internal failure
occurred in the fc_push_stack routine.This problem may require
the attention of application-support services.
When fcpushstk 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 displayed to the
standard error device unless the -q option has been specified.
In cases where more than one warning condition was detected, the command
generates an exit status code corresponding to the most severe warning
condition it detected. The following exit status codes are returned
by fcpushstk when warning conditions are detected:
- 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 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.
- 30
- No default message was provided to describe the nature of the
incident. If the XPG/4 message catalog containing the description
message cannot be found, no description for this condition will be
displayed by the fcstkrpt command.
- 31
- No message was provided to describe the nature of the incident,
or a component of the XPG/4 information—catalog file name, message
set number, message number—was not provided. No description for this
condition can be displayed by the fcstkrpt command.
- 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.
- 35
- No detailed information was provided for this incident. Later
problem analysis may be difficult without these details to indicate
specifics on the incident.
- 37
- An FFDC Failure Identifier could not be constructed for the report
created by this routine. No FFDC Failure Identifier is provided by
this command, but information on the incident was recorded to the
FFDC Error Stack.
- 44
- The information provided to this command would have caused an
FFDC Error Stack record to exceed the FC_STACK_MAX limit. The record
was truncated to allow it to be recorded within the system limits.
Important information about the failure may have been lost during
the truncation process. Modify the script to provide less information,
or to record the information to a detail data file and submit the
detail data file name to this command instead.
Examples
To record information about a
failure to the FFDC Error Stack when the FFDC Environment is established
or inherited by the process:
-
#!/bin/ksh
:
:
cp /tmp/workfile $FILENAME
RC=$?
if ((RC != 0))
then
FFDCID=$(fcpushstk -c mymsg.cat -m2 -n10 -o$FILENAME -r myprog
-d"cp exit status $RC - file being copied /tmp/workfile" -s$0
-p$LINENO -v"1.1" -lPSSP "Cannot update configuration file %1$s")
if (($? == 0))
then
fcdispfid $FFDCID
return 1
fi
fi
:
:
To make the same recording from a script language
that does not have a line of code variable available:
-
#!/bin/bsh
:
:
CODESCTN=14 # Used to identify where in the script code we are
cp /tmp/workfile $FILENAME
RC=$?
if test $RC -ne 0
then
FFDCID=`fcpushstk -c mymsg.cat -m2 -n10 -o$FILENAME -r myprog
-d"cp exit status $RC - file being copied /tmp/workfile" -s$0
-p$CODESCTN -v"1.1" -lPSSP "Cannot update configuration file %1$s"`
if test $? -eq 0
then
fcdispfid $FFDCID
return 1
fi
fi
CODESECTION=15 # New code section begins - a different task starts
:
:
To record information about a failure condition
that is related to another failure condition previously recorded to
the FFDC Error Stack by an application exploiting FFDC:
-
#!/bin/ksh
:
:
ASSOC_FID=$(/usr/lpp/ssp/bin/somecmd -a -b)
RC=$?if ((RC != 0))
then
FFDCID=$(fcpushstk -a$ASSOC_FID -c mymsg.cat -m2 -n10 -o$FILENAME -r myprog
-d"cp exit status $RC - file being copied /tmp/workfile" -s$0
-p$LINENO -v"1.1" -lPSSP "Cannot update configuration file %1$s")
if (($? == 0))
then
fcdispfid $FFDCID
return 1
fi
fi
:
:
Implementation Specifics
This command is
part of the Reliable Scalable Cluster Technology (RSCT) fileset.