PrinterStuff plugin for Take Command / TCC / TCC/LE
beta version 0.70.0.4 2023-10-15
Charles Dye
Purpose:
This plugin provides features to manage local printers from within TCC. It adds commands to create, delete, and list printers; list available printing ports; create and delete IP printing ports; list and cancel print jobs on a given printer; display or set the current user’s default printer; and print a test page. New functions return information about a given printer, create a TCP/IP printing port on the local machine, and allow you to enumerate installed printers. New internal variables return the number of installed printers and printing ports, as well as the name of the current user’s default printer.
Note that these features only affect the local system. This plugin will not create, remove, or change printers on a remote server.
Installation:
To use this plugin, copy the files PrinterStuff.dll
and PrinterStuff.chm to some known location on your hard drive.
(If you are still using the 32-bit version of Take Command, take
PrinterStuff-x86.dll instead of
PrinterStuff.dll.) Load the plugin with a
PLUGIN /L command. For example:
plugin /l c:\bin\tcmd\test\printerstuff.dll
If you copy the .DLL file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.
Syntax Note:
The syntax definitions in the following text use these conventions for clarity:
BOLD CODE | indicates text which must be typed exactly as shown. |
CODE | indicates optional text, which may be typed as shown or omitted. |
| Bold italic | names a required argument; a value must be supplied. |
| Regular italic | names an optional argument. |
| ellipsis… | after an argument means that more than one may be given. |
Plugin Features:
New Commands:
ADDIPPORT — Create a
TCP/IP printing port on the local machine.
Syntax:
ADDIPPORT address /P:port /Q:queue
| address | most often a static IP, but you may use a hostname instead |
/P:port | the name for the new printing port |
/Q:queue | the queue name for an LPR port |
The address parameter is required.
The new port will be created on the local machine. The new IP port will
be a raw TCP port unless /Q:queue
is specified, in which case an LPR port will be created. If you
don’t supply a port name, the plugin
will generate a default name.
If you need to specify a TCP port number, append it to the IP address
with a colon, e.g. /A:192.168.10.24:9101.
addipport 192.168.0.16
Note: This command has been superceded by the
@ADDIPPORT function, which does the same
job but also returns the name of the newly created port. It may be removed in a
future version of this plugin.
ADDPRINTER — Install a
printer on the local machine.
Syntax:
ADDPRINTER printername drivername /A:address /C:comment /D /I:filename /L:location /O /P:port /Q:queue /R:filename /T
| printername | the name to give the new printer |
| drivername | as listed in the printer’s installation .INF file |
/A:address | a dotted-quad IP address or hostname; a TCP/IP port will be created |
/C:comment | an optional comment, 255 characters max |
/D | make the new printer the default |
/I:filename | filename of the printer’s installation .INF file |
/L:location | the printer’s physical location; 255 characters max |
/O | only install if the named printer doesn’t already exist |
/P:port | name of an existing printer port |
/Q:queue | the queue name for an LPR port |
/R:filename | read printer settings from a data file |
/T | send a test page after installing |
You must supply both the printername and
drivername parameters. /I:filename
might not be necessary if Windows includes support for the printer, or if
the driver is already installed on the local computer.
Specify either /A:address or
/P:port, but not both. /P
will use an existing printer port; /A will automatically create
a TCP/IP port for the specified address. The new IP port will be a
raw TCP port unless /Q:queue
is specified, in which case an LPR port will be created.
If you need to specify a TCP port number, append it to the IP address
with a colon, e.g. /A:192.168.10.24:9101.
If you specify /I:, AddPrinter will search for the tag
<Win> in the filename and,
if found, replace it with a string indicating the Windows version. This
allows you to supply more than one driver, and select the appropriate one
at runtime.
<Win> | |
| XP | Windows XP, Server 2003 |
| Vista | Windows Vista, Server 2008 |
| Win7 | Windows 7, Server 2008 R2 |
| Win8 | Windows 8, Windows 8.1, Server 2012 |
| Win10 | Windows 10, Server 2016 |
| Winx.y | unknown version of Windows; major version x, minor version y |
For example, if you type /I:"Drivers\Yoyodyne 4200n\<Win>\oemsetup.inf",
the filename will be expanded at runtime to e.g.
“Drivers\Yoyodyne 4200n\XP\oemsetup.inf” or
“Drivers\Yoyodyne 4200n\Win7-x64\oemsetup.inf”. (If a driver
supports more than one operating system, consider using NTFS junctions to
map one directory to another.)
If you need to distinguish between x86 and x64 environments, you can use
<x64>. This tag is ignored in x86 environments, but replaced
with “-x64” in 64-bit
environments. For example, if you type /I:"Printers\DrizzleJet
6502<x64>\oemsetup.inf", the filename will be either
“Printers\DrizzleJet 6502\oemsetup.inf” or “Printers\DrizzleJet
6502-x64\oemsetup.inf”, as appropriate.
Case is not significant in the <Win> and
<x64> tags. Remember to quote any parameter containing
spaces, less-than or greater-than signs, or any other special characters.
If you specify /R:, ADDPRINTER will attempt to load
printer settings from the specified data file. You would create the data file
using a PRINTERDATA /S
command, saving settings from the exact same printer. Doing this allows you to
configure default options like paper trays, duplexing, secured or locked printing,
and so on, on one computer; then replicate the printer with its customizations
to other systems. The filename supports
the same tags as in /I:.
addprinter "LaserJet in Office" "HP LaserJet 4050 Series PCL6" /a:192.168.0.16
• Note: Installing printer drivers under Vista or later will require elevation (“Run as Administrator”.)
DEFAULTPRINT — Display
or change the default printer.
Syntax:
DEFAULTPRINT printername
| printername | the printer to make the default |
Only the current user will be affected. If printername is not specified, the current user’s default printer will be displayed.
DELIPPORT — Delete TCP/IP
printing ports from the local machine.
Syntax:
DELIPPORT /N /Y name…
/N | not really; don’t actually delete ports |
/Y | answer yes to all prompts |
| name | the name of the port to delete |
This command only deletes IP printing ports on the local machine. It will not delete other kinds of ports. You cannot delete any port which a printer is currently attached to.
You must provide at least one name. Quote any name which contains spaces or other special characters.
You may specify one or more name parameters
containing wildcards (inclusion masks), e.g. *.45$ to
include ports whose names end in “.45$”. Any port whose name
matches any of the inclusion masks will be deleted. You can also specify
wildcarded names to exclude; precede these with an exclamation point,
e.g. !*LASER* to exclude all ports whose names contain
the string “Laser”. Exclusion masks override inclusion masks.
Any port whose name matches any exclusion mask will not be deleted, even if
it matches one or more inclusion masks.
If a port name matches a wildcard mask, DELIPPORT will
prompt before deleting it. Use /Y to suppress the prompt. If
the port name is an exact match — character-for-character, not
just a wildcard match — you will not be prompted.
DELPRINTER — Delete
printers from the local machine.
Syntax:
DELPRINTER /K /N /Y name…
/K | for locally controlled IP printers, also remove the port |
/N | not really; don’t actually delete printers |
/Y | answer yes to all prompts |
| name | the name of the port to delete |
This command deletes printers only from the system where it is run. If a network printer is specified, the connection will be removed from the local machine, but the printer will still exist on the server.
You must provide at least one name. Quote any name which contains spaces or other special characters.
You may specify one or more name parameters
containing wildcards (inclusion masks), e.g.
*CANON* to include printers whose names contain
“Canon”. Any printer whose name matches any of the inclusion
masks will be deleted. You can also specify wildcarded names to exclude;
precede these with an exclamation point, e.g. !*OFFICE*
to exclude all printers whose names contain the string “Office”.
Exclusion masks override inclusion masks. Any printer whose name matches
any exclusion mask will not be deleted, even if it matches one or more
inclusion masks.
If a printer name matches a wildcard mask, DELPRINTER will
prompt before deleting it. Use /Y to suppress the prompt. If
the printer name is an exact match — character-for-character, not
just a wildcard match — you will not be prompted.
Syntax:
KILLJOBS /P:printer job…
/P:printer | the printer to cancel print jobs from |
| job… | names or ID numbers of jobs to cancel |
If no printer is specified, the default
printer will be assumed. The job parameters
may be document names, possibly including wildcards; or job ID numbers as
listed by the LISTJOBS command.
You may specify one or more job parameters
containing wildcards (inclusion masks), e.g. JP* to
include all jobs whose names begin with the letters JP. Any job that
matches any of the inclusion masks will be canceled. You can also specify
wildcarded names to exclude; precede these with an exclamation point,
e.g. !*.DOC to exclude all .DOC files. Exclusion
masks override inclusion masks. Any job which matches any exclusion mask
will not be deleted, even if it matches one or more inclusion masks.
Finally, jobs can be job ID numbers,
e.g. 12 or 0x0C to delete job #12. Any
print job with the specified ID number will be deleted, regardless of any
exclusion masks.
If you do not specify any job parameters,
KILLJOBS will kill the first print job queued for the specified
printer. To cancel all jobs in the queue, specify an asterisk.
killjobs /p:"laserjet 4m" *.doc !*marcia*
Syntax:
LISTJOBS /P:printer job…
/P:printer | the printer to list print jobs for |
| job… | names or ID numbers of jobs to list |
If no printer is specified, jobs for the default printer will be listed. The job parameters may be document names, possibly including wildcards; or job ID numbers.
You may specify one or more job parameters
containing wildcards (inclusion masks), e.g. JP* to
list all jobs whose names begin with the letters JP. Any job that matches
any of the inclusion masks will be included in the list. You
can also specify wildcarded names to exclude; precede these with an
exclamation point, e.g. !*.DOC to exclude all .DOC
files from the list. Exclusion masks override inclusion masks. Any job
which matches any exclusion mask will not be shown, even if it matches one
or more of the inclusion masks.
Finally, jobs can be job ID numbers,
e.g. 12 or 0x0C to list job #12. Any
print job with the specified ID number will be listed, regardless of any
exclusion masks.
If you do not specify any job parameters,
LISTJOBS will list all print jobs for the specified printer.
LISTPORTS — List local
printer ports.
Syntax:
LISTPORTS /I /N name…
/I | include IP printer ports |
/N | include non-IP printer ports |
| name… | may contain wildcards |
If neither /I nor /N is specified, both IP
and non-IP ports will be listed.
You may specify one or more name parameters
containing wildcards (inclusion masks), e.g. LPT* to
list all ports whose names begin with the letters LPT. Any port that matches
any of the inclusion masks will be included in the list. You can also
specify wildcarded names to exclude; precede these with an exclamation point,
e.g. !*IMAG* to exclude all ports whose names contain
the string “IMAG”. Exclusion masks override inclusion masks.
Any port which matches any exclusion mask will not be shown, even if it
matches one or more inclusion masks.
If you do not specify any name parameters,
LISTPORTS will list all printing ports available on the local
machine.
LISTPRINTERS — List
available printers.
Syntax:
LISTPRINTERS /I /L /N /V name…
/I | list local IP printers only |
/L | list locally-controlled printers |
/N | list network printers |
/V | verbose |
| name… | may contain wildcards |
If none of /I /L or /N is
specified, both local and network printers will be listed.
You may specify one or more name parameters
containing wildcards (inclusion masks), e.g. *LASER* to
list all ports whose names contain the string “Laser”. Any
printer whose name matches any of the inclusion masks will be included in
the list. You can also specify wildcarded names to exclude; precede these
with an exclamation point, e.g. !*DESK* to exclude
all printers whose names contain “Desk”. Exclusion masks
override inclusion masks. Any printer whose name matches any exclusion
mask will not be shown, even if it matches one or more inclusion masks.
If /V is specified, the list of printers will also include
the port name, server name, or IP address for each printer. This field
will be truncated to 25 characters.
If you do not specify any name parameters,
LISTPRINTERS will list all printers available on the local
machine.
PRINTERDATA — Save or
restore printer settings.
Syntax:
PRINTERDATA printername /S:filename /R:filename
/S:filename | save the printer’s settings to a file |
/R:filename | restore the printer’s settings from a file |
You must specify either /S: or /R:. If you do not
supply a printername, the current user’s
default printer will be used.
Printer settings can only be restored to the same printer they were saved from.
PRINTPREFS — Display or
change printing defaults.
Syntax:
PRINTPREFS /C:n /D:n /O:n /P:n printername
/C:n | set the default color mode |
| 1: black and white, 2: color | |
/D:n | set the default duplex mode |
| 1: single-sided, 2: flip on long edge, 3: flip on short edge | |
/O:n | set the default orientation |
| 1: portrait, 2: landscape | |
/P:n | set the default paper size |
| 1: letter, 5: legal | |
| printername | defaults to the user’s default printer |
PTRSTUFFHELP — Opens the
PrinterStuff plugin help file.
Syntax:
PTRSTUFFHELP topic
| topic | the page to display |
The PTRSTUFFHELP command will locate and open this
plugin’s help file. In most cases, the internal HELP
command, and the F1 and Ctrl-F1 keys, will be more convenient. The sole
advantage to this command is that it can be used to open the help file to
any desired topic, not only to the names of commands and functions.
SETPRINTER — Change a
printer’s status.
Syntax:
SETPRINTER printername /OF /ON /P /PU /R
/OF | take the printer offline |
/ON | bring the printer back online |
/P | pause the printer |
/PU | purge the print queue |
/R | restart a paused printer |
Only the first letter or two of the options are checked. You can spell
options out for clarity: /OFFLINE, /ONLINE,
/PAUSE, and so on.
Quote the printername if it contains spaces. If you do not specify a printername, the current user’s default printer will be assumed.
Syntax:
TESTPAGE printername
Quote the printername if it contains spaces or other special characters. If you do not specify a printername, a test page will be sent to the current user’s default printer.
New Functions:
@ADDIPPORT — Create a
TCP/IP printing port on the local machine.
Syntax:
%@ADDIPPORT[address,queue]
| address | most often a static IP, but you may use a hostname instead |
| queue | the queue name for an LPR port |
The address parameter is required.
The new port will be created on the local machine. The new IP port will be a raw TCP port unless
queue is specified, in which case an LPR port will be created.
If you need to specify a TCP port number, append it to the IP address with a colon, e.g.
192.168.10.24:9101.
This function returns the name of the newly created port, or ??? if an
error occurred.
set port=%@addipport[192.168.0.16]
@NUMPORTS — Returns
the number of matching printer ports.
Syntax:
%@NUMPORTS[I|N,wildspec]
I | IP printing ports only |
N | Non-IP printing ports only |
| wildspec | wildcard name to match |
If neither I nor N is specified, both IP and
non-IP printing ports will be counted. If no
wildspec is given, * will be used
by default.
@NUMPRINTERS — Returns
the number of matching printers.
Syntax:
%@NUMPRINTERS[I|L|N,wildspec]
I | local IP printers only |
L | printers controlled Locally |
N | Network printers |
| wildspec | wildcard name to match |
If none of I L or N is specified,
both local and network printers will be counted. If no
wildspec is given, * will be used
by default.
@PTRCOMMENT — Returns
the comment for the specified printer.
Syntax:
%@PTRCOMMENT[printername]
printername: if omitted, the user’s default printer
The function will return N/A if the specified printer has
no comment, or ??? on any error.
echo %@ptrcomment["LaserJet in Office"]
@PTRDRIVER — Returns
the driver name for the specified printer.
Syntax:
%@PTRDRIVER[printername]
printername: if omitted, the user’s default printer
The function will return ??? on any error.
echo %@ptrdriver["LaserJet in Office"]
@PTREXIST — Returns 1
if the specified printer exists, 0 otherwise.
Syntax:
%@PTREXIST[printername]
printername: must be specified
@PTRHOST — Returns
the hostname for the specified IP printer.
Syntax:
%@PTRHOST[printername]
printername: if omitted, the user’s default printer
In most cases, the hostname will simply be the IP address. The function
will return Not an IP printer if the specified printer is not
an IP printer, or ??? on any other error.
echo %@ptrhost["LaserJet in Office"]
@PTRIP — Returns the IP
address for the specified IP printer.
Syntax:
%@PTRIP[printername]
printername: if omitted, the user’s default printer
The function will return Not an IP printer if the specified
printer is not controlled an IP printer, or ??? on any other
error.
echo %@ptrip["LaserJet in Office"]
@PTRJOBS — Returns the
number of jobs queued for the specified printer.
Syntax:
%@PTRJOBS[printername]
printername: if omitted, the user’s default printer
The function will return ??? on any error.
echo %@ptrjobs["LaserJet in Office"]
@PTRLOC — Returns the
location string for the specified printer.
Syntax:
%@PTRLOC[printername]
printername: if omitted, the user’s default printer
The function will return N/A if the specified printer has
no location specified, or ??? on any error.
echo %@ptrloc["LaserJet in Office"]
@PTRNAME — Returns the
name of a printer.
Syntax:
%@PTRNAME[n,L|N]
| n | a nonnegative integer |
L | printers controlled Locally |
N | Network printers |
You can use this function to iterate through the names of available
printers. %@PTRNAME[0] returns the name of the first printer
on the system, %@PTRNAME[1] gives the name of the second, and
so on. When n exceeds the number of the last
printer, %@PTRNAME[n]
will return an empty string.
The index n is required. If neither
L nor N is specified, the function will return
both locally-controlled and network printers.
for /l %i in ( 0, 1, %@dec[%_numprinters] ) echo %i %@ptrname[%i]
@PTROFFLINE — Returns 1
if Windows thinks that the specified printer is offline, 0 otherwise.
Syntax:
%@PTROFFLINE[printername]
printername: if omitted, the user’s default printer
• Note: The Windows print spooler’s
notion of whether a printer is online or offline is frequently wrong.
See, for instance, KB160129. If @PTROFFLINE returns a 1, then
the printer probably is offline; but if it returns a 0, that is no guarantee
that the printer is in fact ready to receive data. User beware.
@PTRPORT — Returns the
port to which the specified printer is connected.
Syntax:
%@PTRPORT[printername]
printername: if omitted, the user’s default printer
Note that if printername is a network
printer, the name @PTRPORT returns will refer to a port on
the server, not a port on the local machine! The function will return
??? on any error.
echo %@ptrport["LaserJet in Office"]
@PTRSERVER — Returns
the server name for the specified printer.
Syntax:
%@PTRSERVER[printername]
printername: if omitted, the user’s default printer
The function returns N/A if the specified printer is
controlled locally, or ??? on any error.
echo %@ptrserver["\\JEEVES\Ricoh Copier in Room 105"]
@PTRSHARE — Returns
the share name through which the specified printer is accessed.
Syntax:
%@PTRSHARE[printername]
printername: if omitted, the user’s default printer
The function returns N/A if the specified printer is
controlled locally, or ??? on any error.
echo %@ptrshare["\\JEEVES\Ricoh Copier in Room 105"]
New Variables:
_DEFPRINTER — Returns
the name of the current user’s default printer, or N/A
if no default printer is set.
_NUMPORTS — Returns
the number of printer ports available.
See also @NUMPORTS, which
allows you to filter the count by name or port type.
_NUMPRINTERS — Returns
the number of printers available.
See also @NUMPRINTERS, which
allows you to filter the count by name or connection type.
Startup Message:
This plugin displays an informational line when it is loaded. The
message will be suppressed in transient or pipe shells. You can disable it
for all shells by defining an environment variable named NOLOADMSG,
for example:
set /e /u noloadmsg=1
Changes:
| Version | Date | Changes | |
|---|---|---|---|
| 0.70.0.4 | 2023-10-15 | Tweaked ShowCmdHelp() to include
VER_PATCH. | |
| 0.70.0.3 | 2023-10-12 | Updated the plugin’s web address. | |
| 0.70.0.2 | 2023-07-24 | Updated to the current version of NewHelp.cpp. | |
| 0.70.0 | 2021-09-02 | When creating an IP printing port, always generates a new,
unique port name. New function @ADDIPPORT to create an IP printing port, superceding
the ADDIPPORT command. Documents the LISTPRINTERS /V
option. The ADDPRINTER <Win> tag now recognizes Windows 8 and Windows 10,
and no longer appends ‘-x64’ for 64-bit Windows. (Use <x64>
to make this distinction.) Changed the .dll names; PrinterStuff.dll
is now the 64-bit build. Tweaks to the VerInfo structure. Much cleanup of the code. | |
| 0.66.1 | 2017-11-27 | Updates to the help system. | |
| 0.66.0 | 2016-05-26 | Adds PRINTPREFS command. | |
| 0.65.5 | 2016-03-09 | Reworks the help system, for systems where the documented HtmlHelp() API is broken. | |
| 0.65.4 | 2014-08-25 | Tweaks to the help system; fixes a problem with ADDPRINTER /T. |
Status and Licensing:
Consider this beta software. It may well have issues. Try it at your own risk. If you find bugs, you can report them in the JP Software support forum.
PrinterStuff is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.
Download:
You can download the current version of the plugin from http://charlesdye.net/dl/printerstuff.zip.