Name

hszterm − Control program for HSZ40 disk array controller. 

Syntax

hszterm [ options ] [ commands ]

Options

−fspecialCharacter special device name of an HSZ40 logical units.  If no logical units are defined, the bus and target number can be specified instead. 

−bbus-number
Specify the SCSI bus number.

−ttarget-number
Specify the SCSI target ID.

−lLUN-number
Specify the logical unit number.  The default is zero.

−ologfileSpecifies the name of an optional log file.  Messages sent to and received from the HSZ40 are appended to this file. 

−qDisplay the results of a SCSI Inquiry command at startup. 

−hPrint a brief help message. 

−vSet level of verbosity.  Hszterm can be made to perform its actions with a great deal of, generally extraneous, output.  This option allows setting the level of verbosity of this extra output. 

Description

The hszterm command either starts a virtual terminal session with the HSZ40 or sends commands to the HSZ40 with the output of those commands going to stdout. All hszterm communication with the HSZ40 is done over the SCSI bus. 

To run hszterm a device representing one of the units on the HSZ40 must be specified. This can be by using the -f option and providing the the path to the device, or by using the -b -t and -l options and providing the bus, target and LUN information. 

If no additional arguments are provided, hszterm starts a virtual terminal session to the HSZ40. The session and the program can be ended by entering the EOF character. 

If additional arguments are provided, hszterm will uses the remaining arguments on the command line as commands to be passed to the HSZ.  If the command to be passed consists of multiple words, it must be surrounded by quotes. 

Example

This example passes the command "show devices full" to the HSZ40 that is expected to correspond to the special device /dev/rrz10c . 

# hszterm -f /dev/rrz10c "show devices full"

Restrictions

The hszterm command restricts access to the HSZ40 programs that can be used with the RUN command.  The set of allowed commands can be set using the environment variable HSZTERM_RUN.  This is a comma separated list of the utilities the user would like to be able to run.  If no list is specified the default list will consist of CONFIG, FLS, FMU, CLCP and CLONE.  It will never allow running the utilities CFMENU, VTDPY, DILX or TILX, even when they are included in the list specified by HSZTERM_RUN. 

Example

This example limits the run list to CONFIG, CLONE and FLS. 

# setenv HSZTERM_RUN CONFIG,CLONE,FLS

There can only be one hszterm session to an HSZ40 controller at a any time. 

Digital recommends that, when possible, the bus, target and LUN options should be used to specify the HSZ40.  Further the LUN should not be one presented by the controller. 
 

Sometimes, after the system or controller has been rebooted a command may fail with the message:

Device does not support Virtual Terminal protocol.

This problem seems specific to the KZTSA TURBOchannel SCSI adapter.  The work-around is to simply retry the command. 
 

Diagnostics

Most error messages are preceded by the string HSZterm.  The errors message fall in three general categories; SCSI communication errors, virtual terminal errors and other errors. 
 

Getopt got confused
The library function getopt(3) is used to parse the command line.  This message is printed when an unrecognized option is used.
 

Can’t open %s: %s. 
If HSZterm is unable to open the /dev/cam or the special device file of the HSZ40, this message is printed.  The system message corresponding to the error is provided.
 

Can’t open %s for logging: %s. 
If HSZterm can’t open the log file, this message is printed.
 

Can’t close %s: %s. 
HSZterm tries to close all the files it opens before it exits. If one of the files can’t be closed, this message is printed with the name of the file and system error message being given.
 

DEVIOCGET I/O control failed: %s. 
HSZterm uses the DEVIOCGET I/O control to get the SCSI bus, target and LUN from the device.  This message is printed when it can’t do so.
 

Error during license check %s. 
This message will be printed, if HSZterm fails to find a license.  It checks for the OSF-BASE license.
 

Invalid LUN selection. Valid range %d through %d. 
Invalid target selection. Valid range %d through %d.
HSZterm verifies the range of the SCSI target ID and LUN.  For both, the valid values are between zero (0) and seven (7), inclusive.
 

No device selected. Select a device and try again. 
This message is printed when no device has been selected.
 

The following messages indicate errors in the virtual terminal protocol used to communicate with the HSZ40. 
 
Device does not support Virtual Terminal protocol.
Failed to send response to remote program.
Failed to receive message.
 

The following messages are the result of errors in the handling of SCSI commands sent through the CAM interface. 
 
ASC = %x, ASQ = %x.
BUSY status returned from SCSI command.
CHECKSENSE status returned from SCSI command.
Data protected from writing.
Device not ready.
Hardare error.
INQUIRY ioctl failed: %s.
Illegal Request.
Medium error.
No sense data available.
RECEIVE DIAGNOSTIC RESULTS ioctl failed: %s.
REQUEST SENSE ioctl failed: %s.
SEND DIAGNOSTIC ioctl failed: %s.
SIM Queue Release ioctl failed: %s.
TEST UNIT READY ioctl failed: %s.
Unit Attention.
Unknown sense key: %x.
Unknown status returned from SCSI command: %x.
Waiting...