tapealert(1M)

NAME
     tapealert - Decodes TapeAlert events

SYNOPSIS
     tapealert -i -f /var/opt/SUNWsamfs/devlog/nn

AVAILABILITY
     SUNWsamfs

DESCRIPTION
     The TapeAlert feature displays diagnostic and status
     messages for tape drives and automated library devices.
     These messages can provide network administrators with
     critical diagnostic information, such as for media or drive
     failure, when user intervention is urgent and data is at
     risk.  TapeAlert messages also warn you when media or
     devices need servicing, and the messages also provide
     information regarding media or device status.

     The TapeAlert feature enables a tape drive or automated
     library to convey diagnostic information to network
     administrators.  TapeAlerts interpret log sense page 0x2e.
     The log sense page contains 64 industry-standard error
     flags.  Robots and tape drives support TapeAlert though
     their own set of specific error flags.

     The SAM-QFS software automatically writes TapeAlert events
     to the device log file, /var/opt/SUNWsamfs/devlog/nn.
     TapeAlert events are logged in many situations, for example
     positioning errors, drive self-test errors, and others.  If
     a TapeAlert event is logged, user action is often required.

     The tapealert command reads the events logged in the device
     log file, interprets them, and writes them to a text file
     for easier viewing. The TapeAlert events can be used to
     diagnose hardware and media problems for a particular tape
     volume.  In addition, you can enable real-time TapeAlert
     output to be sent to you in the form of an email or pager
     message.

     Only unique, discrete, nonzero TapeAlert events are written
     to the device log (devlog/nn).  If repeated identical
     TapeAlert events are detected, only one is written to the
     device log.  This keeps the device log manageable, accurate,
     and comprehensive without becoming unwieldy.  If a TapeAlert
     event occurs when a drive is empty, no VSN is recorded in
     the device log or sent with the sysevent.  For more
     information on the device log file and the information
     written to it, see the devlog(4) man page.

     TapeAlert writes device-specific messages to device-specific
     files.  For each device, whether it is an automated library
     or a tape drive, TapeAlert writes messages specific to that
     device in the device's own file.  Messages are logged as
     follows:

     o  For automated libraries, TapeAlerts are accessed at the
        following events:  SAM-QFS device identification, move
        media, door lock, door unlock, position element,
        exchange, and after unrecoverable device errors.

     o  For tape drives, TapeAlerts are accessed at the following
        events:  SAM-QFS device identification, load, unload, and
        after unrecoverable device errors.

     The tapealert command is not supported for magneto optical
     or mixed-media libraries.  TapeAlert is supported on
     direct-attached hosts only.  TapeAlert is not supported on
     network-attached hosts.

OPTIONS
     The tapealert command requires you to specify one of the
     following options:

     -f /var/opt/SUNWsamfs/devlog/nn
               Specifies the file to be read and interpreted.
               For nn, enter the Equipment Number of the device.
               The Equipment Number is the second field in the
               master configuration file
               (/etc/opt/SUNWsamfs/mcf).  Each device has its own
               unique devlog/nn file.  The system writes each
               device's TapeAlert events to its own unique file.

               For more information on mcf files, see the mcf(4)
               man page.

     -i        Reads standard input for interpretation.

     For an example of tapealert command output, see the EXAMPLES
     section of this man page.

USAGE
     You can create a TapeAlert sysevent event handler to record
     all, or only some, automated library and tape drive
     TapeAlert flags in real time in a single place.  The
     following sections describe the TapeAlert name-value pairs
     that are needed to build an event handler and describe how
     to create various types of event handlers.

  TapeAlert Sysevent Class and Name-Value Pairs
     To create a custom TapeAlert sysevent event handler, the
     following information is required:

     Field     Value

     Class     Device

     Subclass  TapeAlert

     Vendor    SUNW

     Publisher SUNWsamfs

     In addition, you can include all or some of the following
     TapeAlert sysevent name-value pairs:

     Name                Value and Data Type

     VENDOR              Inquiry vendor.  Data type is string.

     PRODUCT             Inquiry product.  Data type is string.

     REV                 Inquiry revision.  Data type is string.

     USN                 Inquiry unit serial number.  Data type
                         is string.

     TOD                 Time of day.  Data type is int32.

     SET                 mcf file Family Set.  Data type is
                         string.

     FSEQ                mcf file Family Set Equipment Number.
                         Data type is int16.

     EQ_ORD              mcf file Equipment Number.  Data type is
                         int16.

     NAME                Device name.  Data type is string.

     VERSION             Inquiry version.  Data type is byte.

     INQ_TYPE            Inquiry peripheral device type.  Data
                         type is byte.

     VSN                 Volume serial name.  Data type is
                         string.

     FLAGS_LEN           TapeAlert flags number.  Data type is
                         int16.

     FLAGS               TapeAlert flags 64-1.  Data type is
                         uint64.

  Creating the Event Handler
     Creating the event handler is a two-procedure process.  In
     the first procedure, you create the event handler itself.

     In the second procedure, you create a notification
     mechanism.

     The following procedure describes how to create the event
     handler.

     1. Log in as root.

     2. Create the notification system.

        After the event handler is created, you need to create a
        notification system.  This can be done through your own
        user-created script or through a C program event handler.
        The following procedures describe how to create a C
        program event handler and how to establish email
        notification.

        To Create a C Program Notifier:

        The following C program, /var/tmp/event_handler.c, writes
        TapeAlert events to a temporary file:

        #include <stdio.h>
        #include <time.h>
        #include <string.h>
        #include <stdlib.h>

        int main(int argc, char **argv)
        {
                char *vendor, *product, *revision, *name, *vsn;
                time_t tod;
                char *todstr;
                short eq_num;
                uchar_t inq_type;
                int flags_len;
                uint64_t flags;
                FILE *fp;

                vendor = argv[1];
                product = argv [2];
                revision = argv[3];
                tod = (time_t)strtol(argv[4], NULL, 10);
                todstr = asctime(localtime (&tod));
                *(strchr (todstr, '\n')) = '\0';
                eq_num = atoi(argv[5]);
                name = argv[6];
                inq_type = (uchar_t)strtol(argv[7], NULL, 16);
                vsn = argv[8];
                flags_len = atoi(argv[9]);
                flags = (uint64_t)strtoll(argv[10], NULL, 16);

                if ((fp = fopen ("/var/tmp/tapealert", "a+")) == NULL)
                        return 1;
                fprintf (fp, "%s %-8s %-16s %-4s VSN %s\n", todstr, vendor,
                         product, revision, vsn);
                fprintf (fp, "Eq num. %d Dev name %s\n", eq_num, name);
                fprintf (fp, "TapeAlert %d flags %016llx\n", flags_len, flags);
                fprintf (fp, "\n");
                fclose (fp);
                return 0;
        }

        After this file is created, you must compile it.  After
        compilation, you can run the following commands to load
        the event handler into the sysevent daemon:

     # syseventadm add -c Device -s TapeAlert -v SUNW -p SUNWsamfs
     /var/tmp/event_handler \"\$VENDOR\" \"\$PRODUCT\" \"\$REV\" \$TOD
     \$EQ_ORD \"\$NAME\" \$INQ_TYPE \"\$VSN\" \$FLAGS_LEN \$FLAGS

     # syseventadm restart

        The following commands show the critical clean drive
        TapeAlert flag 20 active for drive 81 and 82:

     # tail -f /var/tmp/tapealert
     Mon Jun 16 10:42:45 2003 "EXABYTE " "EXB-89008E030203" "V39e" VSN "000166"
     Eq num. 81 Dev name "/dev/rmt/1cbn"
     TapeAlert 49 flags 0000000000080000

     Mon Jun 16 10:42:51 2003 "EXABYTE " "EXB-89008E030203" "V39e" VSN "000165"
     Eq num. 82 Dev name "/dev/rmt/0cbn"
     TapeAlert 49 flags 0000000000080000

        To Create an Email Notifier:

        The following procedure describes how to enable email
        notification.

        1. Log in as root.

        2. In the script file /var/tmp/email_pager, send yourself
           or your pager a TapeAlert email by adding a line
           similar to the following:

           echo $2 | /usr/ucb/mail -s "TapeAlert $1" admin@support.com

        3. Run commands to load the event handler in the sysevent
           daemon.

           Issue the syseventadm(1M) commands, as follows:

           # syseventadm add -c Device -s TapeAlert -v SUNW -p SUNWsamfs
           /var/tmp/email_pager $EQ_ORD "$VSN"
           # syseventadm restart

EXAMPLES
     Example 1.  The following mcf file defines one automated
     library and two tape drives:

     # OVERLAND NEO Series
     /dev/samst/c2t6u0    80    rb   NEO_Series on
     /var/opt/SUNWsamfs/catalog/NEO_Series
     /dev/rmt/0cbn        81    tp   NEO_Series on
     /dev/rmt/1cbn        82    tp   NEO_Series on

     historian            90    hy   -        -
     /var/opt/SUNWsamfs/catalog/historian

     You could decode the TapeAlert flags for these devices using
     the following tapealert commands:

     # tapealert -f /var/opt/SUNWsam/devlog/80
     # tapealert -f /var/opt/SUNWsam/devlog/81
     # tapealert -f /var/opt/SUNWsam/devlog/82

     Example 2.  The following examples show tapealert command
     output:

     # tapealert -f /var/opt/SUNWsamfs/devlog/91
     2003/11/18 15:05:20 Eq no. 91 Seq no. 7
     Code: 0x27
     Flag: Diagnostics required
     Severity: Warning
     Application message:
     The tape drive may have a hardware fault. Run extended diagnostics
     to verity and diagnose the problem. Check the tape drive users
     manual for device specific instructions on running extended
     diagnostics tests.
     Probable cause:
     The drive may have a hardware fault that may be identified by
     extended diagnostics (i.e. SEND DIAGNOSTIC command).

     Code: 0x32
     Flag: Lost statistics
     Severity: Warning
     Application message:
     Media statistics have been lost at some time in the past.
     Probable cause:
     Drive or library powered down with tape loaded.

FILES
     /etc/sysevent/config/SUNW,sysevent.conf

     /var/opt/SUNWsamfs/devlog/nn

SEE ALSO
     samd(1M), syseventadm(1M).

     devlog(4), mcf(4), sefsysevent(4).

NOTES
     The T10 Technical Committee is responsible for SCSI
     architecture standards.  This tapealert command supports the
     TapeAlert functionality as defined by T10 in the following
     papers:

     o  SCSI Stream Commands - 2 (SSC-2).  For a copy of this
        paper, see www.t10.org/ftp/t10/drafts/ssc2/ssc2r08g.pdf.

     o  SCSI Media Changer Commands - 2 (SMC-2).  For a copy of
        this paper, see
        www.t10.org/ftp/t10/drafts/smc2/smc2r05b.pdf.

     The preceding URLs are supported as of June 2003.  If you
     have difficulty accessing these papers, consult the main T10
     Technical Committee webpage at www.t10.org.

     Portions of this man page were based on or derived from the
     following T10 Technical Committe publications:

     1. SCSI Stream Commands - 2 (SSC-2), Revision 08d, 9
        September 2002.

     2. SCSI-3 Media Changer Commands - 2 (SMC-2), Revision 5,
        July 12, 2002.

     TapeAlert is limited to direct attached SCSI automated
     libraries and tape drives that support Log Sense Page 0x2e.

     Sun is not responsible for the availability of third-party
     Web sites mentioned in this document.  Sun does not endorse
     and is not responsible or liable for any content,
     advertising, products, or other materials that are available
     on or through such sites or resources.  Sun will not be
     reponsible for any actual or alleged damage or loss caused
     by or in connection with the use of or reliance on any such
     content, goods, or services that are available on or through
     such sites or resources.