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 Oracle HSM 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:

For automated libraries, TapeAlerts are accessed at the following events: Oracle HSM device identification, move media, door lock, door unlock, position element, exchange, and after unrecoverable device errors.
For tape drives, TapeAlerts are accessed at the following events: Oracle HSM 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:

Class: Device
Subclass: TapeAlert
Vendor: SUNW
Publisher: SUNWsamfs

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

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.

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

.nf
# 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.

Log in as root.
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
```

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" 
.nf
# syseventadm restart

EXAMPLES

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

# OVERLAND NEO Series
∕dev∕scsi∕changer∕c2t500104F0008E6C2Cd0    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

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:

SCSI Stream Commands - 2 (SSC-2). For a copy of this paper, see www.t10.org∕ftp∕t10∕drafts∕ssc2∕ssc2r08g.pdf.
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:

SCSI Stream Commands - 2 (SSC-2), Revision 08d, 9 September 2002.
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.

Oracle is not responsible for the availability of third-party Web sites mentioned in this document. Oracle 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. Oracle 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.