[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Commands Reference, Volume 2
fcpushstk Command
Purpose
Records information about failure or noteworthy conditions to the First
Failure Data Capture Error Stack.
Syntax
/usr/sbin/rsct/bin/fcpushstk { [-aassoc_fid] -cmessage_catalog_name
-mmessage_set -nmessage_number [-omessage_param[,message_param,...]]
-llpp_name -pline_of_code_pos -rresource -ssource_filename -vsidlevel
{[-ddetail_data] | [-fdetail_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 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.
- -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
:
:
Related Information
Commands: fcdecode, fcdispfid, fcinit, fcreport, fcstkrpt, fcteststk
Subroutines: fc_push_stack (see the RSCT First Failure Data Capture Programming Guide and Reference)
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]