=head1 NAME

xtlhp - hpnpf protocol server driver

=head1 SYNOPSIS

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

=head1 DESCRIPTION

B<xtlhp> is a terminal server program for use by B<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 B<xtlhp> after 23.6 perform SNMP operations directly, rather
than relying on an external program being available.

=head1 OPTIONS

=over 8

=item -h I<hostname>

This is the host name or IP address to be used to access the
printer. In B<GNUspool> setup files, it may be appropriate to
substitute C<$SPOOLDEV> or C<$SPOOLPTR> here.

=item -p I<port number>

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

=item -f I<configname>

This is the location of the definitions file, if not F<xtsnmpdef> in
the B<GNUspool> internal programs directory.

=item -c I<file>

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

=item -l I<logfile>

Specify error message destination if not standard error.

=item -b I<n>

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

Otherwise a default block size of 10K is assumed.

=item -d I<n>

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

=item -D I<n>

As for B<-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.

=item -c I<name>

Specify the community in SNMP operations. The default is B<public>.

=item -T I<timeout>

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

=item -S I<snmp>

Specify the SNMP port name to use, if not C<snmp>.

=back

=head1 CONFIGURATION FILE

The configuration file F<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 B<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.

=head1 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.

=head2 Expressions

=over 8

=item 'string'

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

=item ''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.

=item SNMPVAR(objid)

The specified I<objid>, which may be specified using macros, is
returned, treated as a numeric value.

=item SNMPSTR(objid)

The specified I<objid>, which may be specified using macros, is
returned, treated as a string value.

=item `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.

=item [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.

=item {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.

=item I<number>

a numeric value.

=item I<name>

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

=item LASTVAL

The last SNMP value obtained (possibly using C<DEFINED> or
C<UNDEFINED>) as a numeric or string value.

=back

=head2 Constructs

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

=over 8

=item =

Assignment, as in

 X = "ABC"

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

=item :=

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.

=item I<comparison>

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

=item 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,
B<LASTVAL> is set to whatever value that was to save further fetches.

=item UNDEFINED(objid)

As for B<DEFINED> but the other truth value is returned. B<LASTVAL> is
still set if the value is defined.

=item ISNUM I<value>

Return a true value if the value is a number.

=item ISSTRING I<value>

Return a true value if the value is a string.

=item AND OR "&&" "||"

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

=item IF .. THEN .. [ELIF .. THEN ] [ELSE .. ] FI

Conditional construct with optional B<ELIF> and B<ELSE> parts.

=item MSG I<STRING>

Display message on standard error.

=item EXIT I<number>

Exit B<xtlhp> with specified exit code (from 0 to 255).

=item FLUSH

Send flush command (ESC-E) to socket.

=back 

=head2 EXAMPLE

This is the control file supplied by default, with definitions for
C<gdStatusLineState> etc being provided in the definitions file
supplied.

Note that if no B<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

=head1 DIAGNOSTICS

B<xtlhp> generates any appropriate diagnostics on standard error.

=head1 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.

=over 4

=item 1

Usage error, invalid option etc.

=item 2

Device error, cannot connect socket etc.

=item 4

System error.

=item 5

SNMP error.

=back

=head1 SEE ALSO

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

=head1 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.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
