fcteststk Command

Purpose

Test for the presence of a First Failure Data Capture Error Stack environment.

Syntax

/usr/sbin/rsct/bin/fcteststk [-q] │ [-h]

Description

fcteststk can be called by any application program that wishes to use the FFDC Error Stack to test if these facilities have been activated . By performing this test, applications can avoid the performance burden of collecting failure information in cases where an FFDC Environment has not been established. This interface is provided primarily for use by library routines, which would not have any knowledge of whether their client application established or inherited an FFDC Environment.

An FFDC Error Stack Environment is established by a process when that process wants to have failure information from itself, any threads it may create, and any descendant processes it may create to be recorded in an FFDC Error Stack. An FFDC Error Stack Environment is inherited by a process when that process wants to record failure information to an FFDC Error Stack file only when one of its ancestors has requested for processes to do so; in all other cases, the process will not record failure information to the FFDC Error Stack. Processes use fcinit to either establish or inherit the FFDC Error Stack Environment.

The FFDC Error Stack Environment reserves an FFDC Error Stack file, so that failure information is recorded to a file in the /var/adm/ffdc/stacks directory. These files use the naming format script_name.PID.date_and_time, where script_name is the name of the script itself, PID is the process identifier of the script, and date_and_time is the date and time when the script was executed. Whenever this script or children processes of this script record failure information to the FFDC Error Stack, it will be recorded in this file.

Applications use the fcpushstk interface to record failure information to the FFDC Error Stack. However, the application may need to collect this information from various locations before recording the information, and obtaining this information can impact the application's overall performance. The application should not need to collect this information if the FFDC Error Stack Environment was not established or inherited. To avoid this performance impact, the application can issue fcteststk to determine if an FFDC Error Stack Environment is available, and if so, begin collecting the failure information. If the FFDC Error Stack Environment does not exist, the application can avoid collecting this information.

Processes that use the fclogerr FFDC interface can use fclogerr when an FFDC Environment exists, whether or not an FFDC Error Stack is in use by the FFDC Environment. Whenever fclogerr is used, failure information is recorded to the AIX® Error Log and the BSD System Log, regardless of whether an FFDC Error Stack was reserved. Any application that records information using the fclogerr interface must always collect the failure information and record it, regardless of whether an FFDC Error Stack is in use.

Flags

Item Description
-h Displays a usage message for this command. No further processing is performed.
-q Suppresses output from this command that explains whether or not an FFDC Environment was established. The command user will be required to test the exit status from the command to determine whether an FFDC Environment is established for this process.

Parameters

FFDC_Failure_ID

Specifies the FFDC Failure Identifier of the failure to begin the report. fcreport will attempt to obtain the failure information for this failure, as well as any failures that this report lists as an associated failure. Only one FFDC Failure Identifier may be provided to this command.

Security

fcreport uses rsh to obtain failure reports that may reside on remote nodes. The user must have sufficient privilege to execute rsh commands to these remote nodes. If the user does not have this permission, fcreport can only trace the list of related failures so long as they exist on the local node.

Exit Status

0
An FFDC Error Stack Environment exists.
2
Help information displayed and processing ended.
12
No processing performed. An invalid option was specified.
15
FFDC Error Stack Environment has not been established or inherited by the client at this point in time.
17
FFDC Error Stack Environment appears to be corrupted and should be considered unusable.

Examples

To test whether an FFDC Error Stack Environment exists for an application:

fcteststk -q
if (($? == 0))
then
    # Collect failure information
         :
         :
    # Use fcpushstk to record failure info
         :
         :
fi

Implementation Specifics

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