fcinit Command

Purpose

Establishes or inherits a First Failure Data Capture execution environment.

Syntax

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 ]

Description

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:

• The script may wish to record information to the AIX Error Log. Scripts can use fcinit to establish a basic FFDC Environment
• The script wants to have itself and any descendant processes created by itself or its children to record failure information to the FFDC Error Stack. In this case, the script considers itself a "top-level" application that will cause multiple "lower-level" applications to be created, and the success of the "top-level" application depends upon the success of these "lower-level" applications. When using fcinit in this fashion, the process is said to establish or create the FFDC Error Stack Environment.
• The script uses the FFDC Error Stack or the FFDC Trace only in those cases when the script is invoked by an ancestor process that wants failure information or trace information recorded to these devices. In all other cases, the script does not wish to use these devices. When using fcinit in this fashion, the process is said to inherit the FFDC Error Stack Environment.

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.

Flags

-h

Displays a help message to standard output and exits. No other processing is performed, regardless of the options specified.

-l

Indicates that the process wishes to make use of the AIX Error Log only. This option is not necessary when the -s option is specified, since use of the AIX Error Log is permitted within an FFDC Error Stack Environment.

-s

Indicates that an FFDC Error Stack Environment is to be established. Applications wishing to use the fcpushstk interface must specify this flag. Upon successful completion of this command, an FFDC Error Stack file is reserved for the script in the /var/adm/ffdc/stacks directory. This flag must be specified with one of two possible options:

c

Requests that the FFDC Error Stack Environment be created. If an FFDC Error Stack Environment was not created by an ancestor process, it will be created. If such an environment was previously created by an ancestor process, this process will inherit the FFDC Error Stack Environment as if the i option had been specified.

i

Specifies that an FFDC Error Stack Environment is to be inherited if it was previously established by an ancestor process. If an FFDC Error Stack Environment was not previously established by an ancestor process, an FFDC Error Stack Environment is not established for this process, and this process cannot make use of an FFDC Error Stack (although it may make use of the AIX Error Log and the BSD System Log).

Parameters

file_name

The name of the file to be searched for an FFDC Failure Identifier. More than one file may be provided. If a file name is not provided, fcfilter reads from standard input.

Exit Status

fcinit returns the following exit status codes upon completion:

0

FFDC Environment successfully established.

1

FFDC Environment successfully inherited.

2

Help information displayed and processing ended.

fcinit returns the following exit status codes upon detection of a failure:

12

FFDC Environment not established or inherited - Unknown function parameter provided.

13

FFDC Error Stack Environment not established or inherited - caller indicated that the FFDC Environment should be both created and inherited.

14

FFDC Environment not established in this call - the caller already has an FFDC Environment established for itself - this routine may have been executed multiple times.

15

FFDC Error Stack Environment not established or inherited - an FFDC Error Stack Environment did not exist, and the FC_INHERIT option was specified.

16

FFDC Environment not established or inherited - the client's process environment could not be modified by this routine.

17

FFDC Environment not established or inherited - the FFDC Environment appears to be corrupted and should be considered unusable.

18

FFDC Environment not established or inherited - the routine could not allocate the memory required to modify the client's process environment.

19

FFDC Error Stack Environment not established or inherited - Unable to reserve the FFDC Error Stack file for the calling process - the FFDC Error Stack directory does not exist or cannot be used.

21

FFDC Error Stack Environment not established or inherited - Unable to reserve the FFDC Error Stack file for the calling process - the file already exists

42

FFDC Error Stack Environment not established or inherited - creation and use of FFDC Error Stacks has been disabled by the system administrator. Scripts can establish only a basic FFDC Environment that makes use of the AIX Error Log and the BSD System Log.

99

FFDC Environment not established or inherited - an unexpected internal failure occurred within fcinit. This condition may require the attention of customer and application-support services.

Examples

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

Note: The FFDC client may receive an indication that an FFDC Error Stack Environment was inherited, instead of created by the fcinit call. This occurs when an FFDC Error Stack Environment was already established by one of the process's ancestors.

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

Implementation Specifics

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