fcpushstk Command

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.