Provided by: gnuspool_1.7_amd64 bug

NAME

       xtlhp - hpnpf protocol server driver

SYNOPSIS

       xtlhp -h hostname -p port [ -d n ] [ -f file ] [ -c file ] [ -l log ] [ -b blksize ] [ -c
       community ] [ -T timeout ] [ -S snmp ] [ -D n ]

DESCRIPTION

       xtlhp is a terminal server program for use by GNUspool where the destination is an HPNPF
       server. Alternatively other printer devices which accept input using "reverse telnet" and
       allow status to be interrogated via SNMP (or other means) may be driven.

       After each block is transmitted, the status of the printer is interrogated using a
       supplied control script.

       Versions of xtlhp after 23.6 perform SNMP operations directly, rather than relying on an
       external program being available.

OPTIONS

       -h hostname
               This is the host name or IP address to be used to access the printer. In GNUspool
               setup files, it may be appropriate to substitute $SPOOLDEV or $SPOOLPTR here.

       -p port number
               This is the port number or service port name to be used.

       -f configname
               This is the location of the definitions file, if not xtsnmpdef in the GNUspool
               internal programs directory.

       -c file Specifies a control file for obtaining the printer status. See the CONTROL FILE
               section below.

       -l logfile
               Specify error message destination if not standard error.

       -b n    Specify output block size. n may be a number, or followed by b, k, m or g to
               denote blocks, kilobytes, megabytes or gigabytes.

               Otherwise a default block size of 10K is assumed.

       -d n    Debug. Displays activities on standard error, if n is greater than zero. Higher
               values of n will give more output, including tracing of SNMP operations.

       -D n    As for -d, except that no output is attempted, the control script is executed once
               only and the appropriate exit code returned. Use an argument of zero to just
               invoke the script and exit.

       -c name Specify the community in SNMP operations. The default is public.

       -T timeout
               Specify the timeout to wait for SNMP replies. The default is 1 second, but the
               value given may be fractional.

       -S snmp Specify the SNMP port name to use, if not "snmp".

CONFIGURATION FILE

       The configuration file xtsmnpdef provides a series of mnemonics for the SNMP definition of
       the form:

        system 1.3.6.1.4.1.11.2
        gdStatusBytes system.3.9.1.1.1

       The function of these definitions is to "macrogenerate" constructs which appear in the
       control file, for example (with appropriate definitions)

        gdStatusPaperOut.0

       may be used as an abbreviation for

        1.3.6.1.4.1.11.2.3.9.1.2.8.0

       Previous versions of xtlhp expected quotes around the columns of the file, but this is no
       longer expected. The file may define names in terms of previously-defined names and may
       redefine names. If a name is redefined, names already defined using the previous
       definition are unaffected.

CONTROL FILE FORMAT

       The control file consists of a series of command structures involving options to obtain
       SNMP values, run commands, string and numeric comparisons and assignments.

       Constructs are based upon the shell, but control names are in upper case.

   Expressions
       'string'
               A single-quoted string is taken literally, as per the shell.

       ''string''
               A string enclosed in double-quote characters is subject to name expansions of
               macros defined in the configuration file and variables assigned in the script.

       SNMPVAR(objid)
               The specified objid, which may be specified using macros, is returned, treated as
               a numeric value.

       SNMPSTR(objid)
               The specified objid, which may be specified using macros, is returned, treated as
               a string value.

       `string`
               A back-quoted string is a shell command to execute and the output taken as a
               string. Variable names are expanded within the string before execution.

       [string]
               A string enclosed in square brackets is a shell command to execute, with the
               output taken to be a decimal numeric value, the whole returning a numeric value.
               Variable names are expanded within the string before execution.

       {string}
               A string enclosed in braces is a shell command to execute, with the output assumed
               to be a hexadecimal value. (This is required for snmpinfo(8) on AIX systems, which
               returns hexadecimal values).  Variable names are expanded within the string before
               execution.

       number  a numeric value.

       name    The value currently assigned to name, if any, is the value of the expression.

       LASTVAL The last SNMP value obtained (possibly using "DEFINED" or "UNDEFINED") as a
               numeric or string value.

   Constructs
       The following constructs or "statements" are used in the control file.

       =       Assignment, as in

                X = "ABC"

               The value on the right is assigned to the name on the left.

       :=      One time assignment. As per assignment, but the operation is turned into a no-op
               after the first execution.

               For example

                Host = `hostname`

               would be evaluated each time the script is run (after every block), but

                Host := `hostname`

               would only be evaluated the first time.

       comparison
               Comparison of strings is performed with alphabetic operators LT, LE, EQ, NE, GE
               and GT, and numerics with symbolic operators < etc.

       DEFINED(objid)
               Return a true value if the given object id (which may be specified using macros)
               is defined, otherwise false. If the value is defined, LASTVAL is set to whatever
               value that was to save further fetches.

       UNDEFINED(objid)
               As for DEFINED but the other truth value is returned. LASTVAL is still set if the
               value is defined.

       ISNUM value
               Return a true value if the value is a number.

       ISSTRING value
               Return a true value if the value is a string.

       AND OR "&&" "||"
               Combine boolean operations in tests. AND is more binding than OR. "Short circuit"
               evaluation is performed, so beware of relying on LASTVAL.

       IF .. THEN .. [ELIF .. THEN ] [ELSE .. ] FI
               Conditional construct with optional ELIF and ELSE parts.

       MSG STRING
               Display message on standard error.

       EXIT number
               Exit xtlhp with specified exit code (from 0 to 255).

       FLUSH   Send flush command (ESC-E) to socket.

   EXAMPLE
       This is the control file supplied by default, with definitions for "gdStatusLineState" etc
       being provided in the definitions file supplied.

       Note that if no EXIT appears, then script file has "succeeded" and output continues.

        # Test the status to see if there are problems

        IF SNMPVAR(gdStatusLineState.0) != 0
        THEN
               # Look at paper out indication and exit
               # message

               IF SNMPVAR(gdStatusPaperOut.0) != 0
               THEN
                       MSG 'Out of paper'
                       EXIT 100

               # Likewise paper jam

               ELIF SNMPVAR(gdStatusPaperJam.0) != 0
               THEN
                       MSG 'Out of paper'
                       EXIT 101

               # Likewise toner low

               ELIF SNMPVAR(gdStatusTonerLow.0) != 0
               THEN
                       MSG 'Out of toner'
                       EXIT 102

               #  Give up just give general message

               ELSE
                       MSG SNMPSTR(npSysStatusMessage.0)
                       EXIT 103
               FI
        FI

DIAGNOSTICS

       xtlhp generates any appropriate diagnostics on standard error.

EXIT CODES

       Normal termination is denoted by an exit code of zero.

       Most of the other exit codes are determined by the control file and can be adjusted by the
       user as required.

       1   Usage error, invalid option etc.

       2   Device error, cannot connect socket etc.

       4   System error.

       5   SNMP error.

SEE ALSO

       xilp(8), xtelnet(8), xtftp(8), xtlpc(8).

COPYRIGHT

       Copyright (c) 2009 Free Software Foundation, Inc.  This is free software. You may
       redistribute copies of it under the terms of the GNU General Public License
       <http://www.gnu.org/licenses/gpl.html>.  There is NO WARRANTY, to the extent permitted by
       law.

AUTHOR

       John M Collins, Xi Software Ltd.