Establishes or inherits a First Failure Data Capture execution environment.
For Bourne and Korn shells:
. /usr/sbin/rsct/bin/fcinit.sh [ [-l] [-s{c|i}] ] | [-h]
For C shells:
source /usr/sbin/rsct/bin/fcinit.csh [ [-l] [-s{c|i}] ] | [-h]
This interface must be used by a script program that wishes to use the FFDC interfaces for recording information to the AIX Error Log, the BSD System Log, or the FFDC Error Stack .
Applications may wish to establish an FFDC Environment for one of the following reasons:
Any process wishing to record information to the AIX Error Log or the BSD System Log through the FFDC interfaces must establish an FFDC Environment. If the process does not wish to make use of an FFDC Error Stack, the process can establish a basic FFDC Environment that does not make use of an FFDC Error Stack. An FFDC Error Stack Environment, which contains an FFDC Error Stack, 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, which contains an FFDC Error Stack, 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.
The FFDC Error Stack Environment, which contains an FFDC Error Stack, 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.
In order for information to be recorded in the FFDC Error Stack by a process, the process must use the fcpushstk FFDC interface, and the process has to be operating within an established FFDC Error Stack Environment. If an FFDC Error Stack Environment does not exist, or if the fcpushstk interface is not used when an FFDC Error Stack Environment exists, no information is recorded by that process in the FFDC Error Stack. This function permits processes to run in a normal or "silent" mode when failure debugging information is not wanted or needed, but also permits this information to be available when the process is invoked within a special environment for debugging.
fcinit must be executed within the FFDC client's process environment ("sourced") in order for the command to properly set the FFDC Environment for the script. Script-based FFDC clients using this command must "source" the command in order for fcinit to execute within the client's process image. If this is not done. the FFDC interface is executed within its own process image; any settings of the FFDC Environment are lost after the FFDC interface completes. To demonstrate how a script-based application would "source" the fcinit command, a Korn Shell program would issue the following instruction:
. fcinit.sh <options and arguments>
A C Shell script would do the following:
source fcinit.csh <options and arguments>
Processes that use the fclogerr FFDC interface must establish an FFDC Environment. If the process only wishes to use the fclogerr interface, the FFDC Environment can be established without an FFDC Error Stack.
If an FFDC Environment already exists when a script attempts to create one, the script inherits the existing FFDC Environment instead of creating its own.
fcinit returns the following exit status codes upon completion:
fcinit returns the following exit status codes upon detection of a failure:
For a Korn Shell script to establish a basic FFDC Environment for using the AIX Error Log and the BSD System Log only (an FFDC Error Stack is not to be used or reserved):
# Set up an FFDC Environment to use the AIX Error Log only. An FFDC Error # Stack is not needed for this script. . fcinit.sh -1 rc=$? if ((rc != 0)) then print "fcinit failed with exit code of $rc" exit 1 fi # Normal processing starts
For a Korn Shell script to establish an FFDC Error Stack Environment that causes the script and any descendant process to record failure information to the FFDC Error Stack:
# Set up FFDC Environment to record failure information to the FFDC Error # Stack . fcinit.sh -sc rc=$? if ((rc != 0)) then print "fcinit failed with a code of $rc" exit 1 fi # Normal processing starts
To inherit an FFDC Error Stack Environment from the process's parent process:
# Inherit an FFDC Environment from parent process if it exists - otherwise, # operate in a normal "silent" mode . fcinit.sh -si rc=$? if ((rc != 0)) then print "fcinit failed with a code of $rc" exit 1 fi # Normal processing starts
Commands: fccheck, fclogerr, fcpushstk, fcteststk
Subroutines: fc_init (see the RSCT First Failure Data Capture Programming Guide and Reference)