fclogerr 命令

用途

将有关故障或值得注意的情况的信息记录到AIX®错误日志和 BSD 系统日志中。

语法

/opt/rsct/bin/fclogerr { -e 事件 -t 错误模板标签 -i error_template_headerfile -r 资源 -s 源文件名 -p 代码行位置 -v 边级 -l lpp_name -a 用户名 { [ -d 详细数据项[,详细数据项,...] -x 详细数据类型[,详细数据类型,...] -y detail_data_len[,detail_data_len,...] ] ]。| [ '-f detail_data_file] } -b BSD_syslog_message_text}。| '-h

描述

任何希望向AIX错误日志和 BSD 系统日志记录信息的脚本程序都可以使用该接口。 写入该设备的信息，是用于系统管理员或操作员去确定系统上已发生了哪些需要关注的故障情况或其他值得注意的情况。 AIX 错误日志和 BSD 系统日志的目的是记录有关某个条件的足够信息，以便可以从报告中确定该条件的性质，影响和响应，而不需要重新创建该条件以检测发生了什么情况以及在何处发生。 任何软件，如果遇到永久性故障情况（这种情况将持续到某种直接干预发生为止），或遇到应引起系统管理员注意的情况，都应使用fclogerr将此信息记录到AIX错误日志和 BSD 系统日志中。

脚本程序应在使用 fclogerr 之前，通过直接创建或继承，建立一个基本的 FFDC 环境或一个 FFDC 错误堆栈环境。 fclogerr 会将信息记录到AIX错误日志和 BSD 系统日志，即使这些环境尚未建立，但除非这些环境之一存在，否则接口将无法生成 FFDC 故障标识符。

设计用来使用 FFDC 错误堆栈的进程也可以使用 fclogerr 接口，而且当进程遇到需要管理员注意或干预解决的情况时，也应使用它。

为确保正确识别发生的情况以及发生的位置，FFDC 策略建议应在脚本源代码模块中内联调用 fclogerr ，并且一旦检测到情况发生时就调用。 fclogerr 将记录源代码文件名和代码信息行，以帮助识别和定位遇到此情况的源代码。 如果有必要记录此信息，那么子例程或者自动装入的例程可以调用 fclogerr，只要所有的位置信息以及必要的故障详细信息对于此外部例程来说可用。 外部的记录例程必须要记录下检测到的情况的真实位置。

虽然fclogerr会向AIX错误日志和 BSD 系统日志报告信息，但必须为每个记录设备的接口提供不同的选项。 记录到AIX错误日志中的详细数据信息不会同时记录到 BSD 系统日志中；BSD 系统日志信息通过不同的命令选项提供。 这可能要求 fclogerr 的用户在该调用中复制一些信息。

标志

-a

包含了软件所报告一个故障情况的 FFDC 故障标识，该软件被导致或引起了在此时被记录的该故障情况的应用程序使用。 该标识应已经返回给应用程序作为软件结果指示的一部分。 调用程序在这里给出此标识，以便 FFDC 错误堆栈能够将此时所产生的故障报告与原来所记录的故障报告联系起来。 这就能够使问题调查者从该应用程序产生的各种症状中跟踪故障的原因，并使他人找出其他软件中的根本原因。 如果没有其他的软件故障和这种情况有关，或是如果其他软件没有返回一个 FFDC 故障标识作为其结果信息的一部分时，应省略该选项。

-b

说明要被写入 BSD 系统日志的文本消息。

-d

提供条件详细信息的一个或多个数据项，用于在AIX错误日志条目中提供详细数据。 如果信息的细节太长了，那么这些详细信息会被写入一个文件中，且那个文件名会作为 detail_data_file 参数。 如果给出了一个详细数据文件名，那么应省略该选项。 如果没有提供detail_data或detail_data_file参数，或者这两个参数看起来都无效，那么AIX错误日志中的详细数据将记录为空信息。

该选项可以给出一个以上的数据项。 每一个数据项必须用逗号（,）分隔，中间不能有空格。 如果数据项包含空白字符，则必须用双引号（"）括起来。数据项本身不得包含逗号（,），因为该命令将逗号解释为字段分隔符。

该选项必须与 -x 选项和 -y 选项一起使用。

-e

说明了 FFDC 日志事件类型。 当前有效值为 FFDC_EMERG ， FFDC_ERROR ， FFDC_STATE ， FFDC_TRACE ， FFDC_RECOV 和 FFDC_DEBUG。 该代码给出了所记录的事件类型的常规性描述（紧急情况，永久性情况，通知信息，调试信息等等。） 以及发生情况的严重程度。 如果没有该选项，那么事件记录的事件类型被赋值为 FFDC_DEBUG。

-f

某个文件名，该文件包含了所报告情况的详细信息。 当详细信息太长，而不能记录在由 fclogerr 命令留给应用程序用来记录详细数据信息的 100 个字节的空间中时，或是当存在一个能够分析详细信息的实用程序时，使用该选项。 该文件的内容将被复制到/var/adm/ffdc/dumps目录，文件的新位置将作为详细数据记录在AIX错误日志条目中。

-h

在标准输出设备上显示帮助消息并退出。 不管指定什么选项，都不执行其他处理。

-i

指定头文件（.h）的绝对路径名，该文件包含与-l选项中指定的error_template_label相对应的错误日志模板标识号。 此模板必须也存在于节点的错误日志模板库中（/var/adm/ras/errtmplt）。 该头文件是作为软件源代码的建立过程的一部分，由 errupdate 命令生成的，且该头文件应被包括在 LPP 包中，LPP 包随该软件安装在节点上。 如果在执行脚本程序时没有指定此选项，或找不到头文件，那么 fclogerr 会使用自身缺省的错误模板来记录故障信息（标号是 FFDC_DEF_TPLT_TR，标识代码是 2B4F5CAB）。

-l

指定在其中装载了该软件的许可编程产品名称的缩写。 此值对于用户和支持应用程序的服务都必须可识别，并且将它作为 LPP 可接受的名称。 此类值的示例包括 :PSSP ， GPFS ， LoadLeveler®和 RSCT。 如果此选项未提供或者看起来无效，那么使用字符串 PPS_PRODUCT。

-p

指定在源代码模块中产生情况报告的代码行位置。 此值必须是有效的整数值。 要对情况作出正确的识别和定位，此值应尽可能接近检测到发生情况的代码行位置。 Korn Shell 程序脚本能够使用 $LINENO 的值。 不能提供一个特定行计数变量的脚本语言可以提供一个符号值，开发者可以使用该符号值，在使用 fclogerr 的源代码中定位那个地点。 如果此选项无效或者没有提供，那么将会采用 0 值。

-q

禁止命令中警告消息的生成。 当该命令必须使用缺省信息去代替缺少的信息，或是当该命令不能将 detail_data_file 复制到 /var/adm/ffdc/dumps 目录中的时候，生成警告消息。

-r

指定软件组件名。 这是一个产生报告的软件的符号名，该符号名应被客户和应用程序支持服务所识别。 字符串的长度限制为 16 个字符。

-s

指定包含遇到报告情况的代码行的源文件名。 对于 Korn 和 Borne shell 脚本来说，该选项的参数应设置为 $0；C shell 脚本应将此参数值设置为 ${0}。 如果此选项未提供或者无效，那么使用字符串 unknown_file。

-t

表示给错误日志库中AIX错误日志模板的符号标签。 建立错误日志模板的 errupdate 命令创建了一个宏，该宏将此标号映射到一个整数代码。 此标号以字符 ERRID_ 打头，最大长度为 19 个字符。 如果未指定此选项，或执行脚本时找不到头文件，fclogerr将调用Erlogger，使用 OPMSG 模板在AIX错误日志中创建一条信息。

-v

指示检测出所记录情况的源代码模块的 SCCS 版本号。 对于在 SCCS 控制下建立的源代码，版本号将被设置为 "1.1"（必须有双引号）。 如果此选项未提供或者无效，那么使用字符串 unknown。

-x

表示在向AIX错误日志记录信息时，如何解释-d选项指定的数据项。 这些类型必须与-t选项中指定的AIX错误日志模板的相应字段一致。 每一种类型都指示了 -d 列表中相应数据项是如何被解释的。 此选项的可接受值为 ALPHA ， HEX 和 DEC。 对于-d列表中的每个参数，-x参数中必须列出匹配的类型。

如果提供了-d选项，则必须 提供该选项。

-y

指示了由 -d 选项所指定的数据项长度（按字节数）。 这些长度必须与-t选项中指定的AIX错误日志模板的相应字段一致。 对于 -d 列表中的每一个参数，必须有一个在 -y 参数中相匹配的类型。

如果提供了-d选项，则必须 提供该选项。

参数

file_name

用于搜索一个 FFDC 故障标识的文件名。 可能提供多个文件。 如果没有给出文件名，那么 fcfilter 从标准输入中读入。

退出状态

fclogerr 在成功结束时，返回以下退出状态码：

0

已成功将信息排队以写入 AIX 错误日志和 BSD 系统日志。 该记录的 FFDC 故障标识显示在标准输出中。 调用者应该捕获标准输出以获得该值。

2

显示帮助信息，处理结束。

12

未将任何信息记录到 AIX 错误日志中，并且该命令未提供 FFDC 故障标识。 该命令的使用者给出了命令的一个无效选项。

在除AIX 之外的AIX平台上，发生故障时fclogerr会返回以下退出状态代码：

38

BSD 系统日志不能为该事件产生一个记录。 系统日志正遇到了某种故障。 在 AIX 系统上，向 AIX 错误日志记录了报告; 在其他系统上，这应视为失败。

当给 fclogerr 提供了不完整的信息时，它将用缺省信息去代替缺少的信息，并试图在 FFDC错误堆栈上产生一个记录。 在这些情况下，将产生警告，并且生成警告消息，除非指定了 -q 选项。 当检测到多个警告情况时，该命令将返回一个退出状态码，该代码表示了该命令所认为的最严重情况。 当检测到警告情况时， fclogerr 将返回以下退出状态代码：

10

命令的使用者没有成功为该命令提供一个 -i 选项，或不能定位作为 -i 选项参数指定的头文件。 在这种情况下，命令将使用首次故障数据捕获默认模板（标签 FFDC_DEF_TPLT_TR，标识符代码2B4F5CAB）向AIX错误日志记录通用信息。

26

给该例程提供了一个详细数据串和一个详细数据文件。 该例程选择详细数据串并忽略详细数据文件。

28

没有提供检测到此事件的资源名。 使用缺省的资源名 ffdc 来替换缺少的资源名。

29

检测应用程序的信息中至少有一项没有给出，这些项是源代码文件名、源代码文件版本、LPP 名、代码行位置。 这些丢失信息被缺省信息所代替。

32

在 detail_data_file 参数中指定的文件不能被复制到 /var/adm/ffdc/dumps 目录中。 FFDC 错误堆栈条目引用了该文件的原始版本。 不要废弃该文件原有的副本。

33

没有指定 -e 选项，或没有指定一个有效的 FFDC 事件类型。 事件类型 FFDC_DEBUG 被赋值给了此事件记录。

34

在 format 参数中没有给出消息。 因此，在 BSD 系统日志中记录了此事件的一条一般性消息。

35

没有提供关于该事件的详细信息。 如果没有这些详细的信息，那么为了说明这次事件的细节，事后做问题分析时就可能会变得很困难。

36

详细信息数据字符串的长度大于 AIX 错误日志条目限制的容量。 将截短该详细数据以适应空间的大小。 在信息的截短过程中，可能会丢失事件的一些信息。

37

不能为该例程所建立的报告去构造一个 FFDC 错误标识。 FFDC 故障标识未写入标准输出，但有关突发事件的信息已记录到 AIX 错误日志和 BSD 系统日志中。

38

在 BSD 系统日志中不能产生该事件的一个记录。 系统日志可能处于禁用，或遇到了故障。 在 AIX 系统上，向 AIX 错误日志记录了报告; 在其他系统上，这应视为失败。

示例

例如，一个 Korn shell 脚本试图访问某个文件中的配置信息。 如果尝试失败，代码将使用以下模板源代码将失败记录到AIX错误日志中：

*! mymesgcat.cat
+ SP_FFDCEXMPL_ER:
    Comment        = "Configuration Failed - Exiting"
    Class          = S
    Log       = true
    Report         = true
    Alert          = false
    Err_Type  = PERM
    Err_Desc  = {3, 10, "CONFIGURATION FAILURE - EXITING"}
    Prob_Causes    = E89B
    User_Causes    = E811
    User_Actions   = 1056
    Fail_Causes    = E906, E915, F072, 108E
    Fail_Actions   = {5, 14, "VERIFY USER HAS CORRECT PERMISSIONS TO ACCESS FILE"},
               {5, 15, "VERIFY CONFIGURATION FILE"}
    Detail_Data    = 46, 00A2, ALPHA
    Detail_Data    = 42, EB2B, ALPHA
    Detail_Data    = 42, 0030, ALPHA
    Detail_Data    = 16, EB00, ALPHA
    Detail_Data    = 16, 0027, ALPHA
    Detail_Data    = 4, 8183, DEC
    Detail_Data    = 4, 8015, DEC
    Detail_Data    = 60, 8172, ALPHA

此定义生成以下 AIX 错误日志记录模板:

LABEL:            ERRID_SP_FFDCEXMPL_ER
IDENTIFIER:        <calculated by errupdate during source code build>

Date/Time:         <filled in by AIX Error Log subsystem>
Sequence Number:   <filled in by AIX Error Log subsystem>
Machine Id:        <filled in by AIX Error Log subsystem>
Node Id:           <filled in by AIX Error Log subsystem>
Class:             S
Type:              PERM
Resource Name:     <filled in by -r option to fclogerr>

Description
CONFIGURATION FAILURE - EXITING

Probable Causes
COULD NOT ACCESS CONFIGURATION FILE

User Causes
USER CORRUPTED THE CONFIGRATION DATABASE OR METHOD

    Recommended Actions
    RE-CREATE FILE

Failure Causes
COULD NOT ACCESS CONFIGURATION FILE
PERMISSIONS ERROR ACCESSING CONFIGURATION DATABASE
FILE READ ERROR
FILE IS CORRUPT

    Recommended Actions
    VERIFY USER HAS CORRECT PERMISSIONS TO ACCESS FILE
    VERIFY CONFIGURATION FILE

Detail Data
DETECTING MODULE
<filled in by fclogerr options>
ERROR ID
<The FFDC Failure Identifier created by fclogerr>
REFERENCE CODE
<The -a option value to fclogerr>
FILE NAME
<Must be supplied as part of -d option list to fclogerr>
FUNCTION
<Must be supplied as part of -d option list to fclogerr>
RETURN CODE<Must be supplied as part of -d option list to fclogerr>
ERROR CODE AS DEFINED IN sys/errno.h
<Must be supplied as part of -d option list to fclogerr>
USER ID<Must be supplied as part of -d option list to fclogerr>

前三个“细节数据字段”由 fclogerr 例程根据参数中传递的信息来构造。 其余的“详细数据”必须用 -d 选项提供，且提供的数据类型必须由 -x 选项指出。 下面的示例源代码段演示了如何实现这一功能，以及如何调用fclogerr在AIX错误日志和 BSD 系统日志中记录信息。

typeset CONFIG_FNAME
typeset INBUF
typeset MINUSDOPTS
typeset MINUSXOPTS
typeset MINUSYOPTS
typeset FID
integer MYCLIENT
integer RC
    :
MYCLIENT=$$
CONFIG_FNAME="/configfile.bin"
exec 3< $CONFIG_FNAME
    :
read -u3 INBUF
RC=$?
if ((RC != 0))
then
    # Create Detail Data Memory Block for AIX Error Log Template
    # Need to know the EXACT structure of the Template to do this correctly.
    #    Field 1 - filled in by fc_log_error
    #    Field 2 - filled in by fc_log_error
    #    Field 3 - filled in by fc_log_error
    #    Field 4 - name of configuration file being used - 16 bytes
    #    Field 5 - name of function call that failed - 16 bytes
    #    Field 6 - return code from failing function - 4 byte integer
    #    Field 7 - errno from failing function call (unused) - 4 byte integer
    #    Field 8 - user ID using this software - remaining space (62 bytes)
    # This source code supplied fields 4 through 8 in the "-d" option, and
    # describes the data types for each in the "-x" option.
    MINUSDOPTS=$CONFIG_FNAME
    MINUSXOPTS="ALPHA"
    MINUSYOPTS="16"
    MINUSDOPTS="$MINUSDOPTS,read"
    MINUSXOPTS="$MINUSXOPTS,ALPHA"
    MINUSYOPTS="$MINUSYOPTS,16"
    MINUSDOPTS="$MINUSDOPTS,$RC"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,0"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,$MYCLIENT"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,60"
    FID=$(fclogerr -e FFDC_ERROR -t ERRID_SP_FFDCEXMPL_ER -i /usr/lpp/ssp/inc/
myprog.h -r myprog -s myprog.ksh -p $LINEPOS -v "1.1" -l PSSP -d $MINUSDOPTS -x
$MINUSXOPTS -y $MINUSYOPTS -b "myprog Configuration Failure - Exiting")
    RC=$?
    if ((RC == 0))
    then
         fcdispfid $FID
         return 1
    else
         :
    fi
fi

现在考虑对上述示例稍作改动，使用相同的AIX错误日志模板，但这次使用外部命令从该源代码提供的文件中获取配置数据。 该命令如果遇到了任何故障情况，那么以非零的退出状态值退出，并在标准输出中显示一个 FFDC 故障标识。 另外，要演示在 -d 列表中使用双引号的情况，配置文件在名称中要有一个嵌入的空格：

typeset CONFIG_FNAME
typeset INBUF
typeset MINUSDOPTS
typeset MINUSXOPTS
typeset MINUSYOPTS
typeset FID
typeset OUTPUT
integer MYCLIENT
integer RC
    :
MYCLIENT=$$
CONFIG_FNAME="This is a test"
OUTPUT=$(configdabeast $CONFIG_FNAME)
RC=$?
if ((RC != 0))
then
    # Create Detail Data Memory Block for AIX Error Log Template
    # Need to know the EXACT structure of the Template to do this correctly.
    #    Field 1 - filled in by fc_log_error
    #    Field 2 - filled in by fc_log_error
    #    Field 3 - filled in by fc_log_error
    #    Field 4 - name of configuration file being used - 16 bytes
    #    Field 5 - name of function call that failed - 16 bytes
    #    Field 6 - return code from failing function - 4 byte integer
    #    Field 7 - errno from failing function call (unused) - 4 byte integer
    #    Field 8 - user ID using this software - remaining space (62 bytes)
    # This source code supplied fields 4 through 8 in the "-d" option, and
    # describes the data types for each in the "-x" option.
    MINUSDOPTS="\""$CONFIG_FNAME"\""
    MINUSXOPTS="ALPHA"
    MINUSYOPTS="16"
    MINUSDOPTS="$MINUSDOPTS,configdabeast"
    MINUSXOPTS="$MINUSXOPTS,ALPHA"
    MINUSYOPTS="$MINUSYOPTS,16"
    MINUSDOPTS="$MINUSDOPTS,$RC"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,0"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,4"
    MINUSDOPTS="$MINUSDOPTS,$MYCLIENT"
    MINUSXOPTS="$MINUSXOPTS,DEC"
    MINUSYOPTS="$MINUSYOPTS,60"
    FID=$(fclogerr -e FFDC_ERROR -t ERRID_SP_FFDCEXMPL_ER -i /usr/lpp/ssp/inc/
myprog.h -r myprog -s myprog.ksh -p $LINEPOS -v "1.1" -l PSSP -d $MINUSDOPTS -x
$MINUSXOPTS -y $MINUSYOPTS -a $OUTPUT -b "myprog Configuration Failure - Exiting")
    RC=$?
    if ((RC == 0))
    then
         fcdispfid $FID
         return 1
    else
         :
    fi
fi

实现细节

此命令是 Reliable Scalable Cluster Technology (RSCT) 文件集的一部分。