Acquire plugin for Take Command / TCC / TCC/LE
Version 1.0.4.2 2023-10-15
Charles Dye
Purpose:
This plugin provides a simple way to download files from the internet. It does not require the IP*Works library, and can be used in TCC/LE.
Installation:
To use this plugin, copy Acquire.dll to
your hard drive. (If you are still using the 32-bit version of Take Command,
take Acquire-x86.dll instead of
Acquire.dll.) Load the plugin with a
PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\acquire.dll
If you copy this file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.
Plugin Features:
New variables: _ACQAGENT,
_ACQFILE, _ACQSIZE
New functions: @IFILESIZE,
@IFILETIME2
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. |
New Command:
ACQUIRE — Download a file from the internet.
Syntax:
ACQUIRE /G /N /O /Q url localname
/G | display progress during the transfer |
/N | not really; don’t actually transfer the file |
/O | overwrite the local file if it already exists |
/Q | quiet; do not display summary on success |
| url | required; must begin with http:// or ftp:// |
| localname | the filename for the local copy |
This command copies a single file from a web or FTP server. You cannot use wildcards.
The localname may include directory aliases.
If localname is a single dash -,
or if it is not specified and output is redirected, the file will be dumped to
standard output. If localname is not specified
and output is not redirected, or if localname
names a directory, ACQUIRE will make up a filename based on the URL.
acquire http://www.jpsoft.com/
See also: _ACQFILE and
_ACQSIZE, set to the local filename and
size of the downloaded file.
New Variables:
_ACQAGENT — Returns
this plugin’s user agent string.
Syntax:
%_ACQAGENT
This variable was mostly for my own use in debugging this plugin. It might also be useful to check whether the plugin is loaded, and if so, which version.
echo %_acqagent
_ACQFILE — Returns the
filename of the last local file created by ACQUIRE.
Syntax:
%_ACQFILE
If the last transfer failed, _ACQFILE returns the string
*ERROR*. If the last transfer was to standard output, the
string - will be returned.
set lastfile=%_acqfile
_ACQSIZE — Returns the
size of the last local file created by ACQUIRE.
Syntax:
%_ACQSIZE
If the last transfer failed, _ACQSIZE returns -1.
if %_acqsize == -1 echo Copy failed!
New Functions:
@IFILESIZE — Returns
the size of an internet file.
Syntax:
%@IFILESIZE[url]
The url is required; it must begin with
http:// or ftp://. The return value is
the file size in bytes, or -1 if any error occurs.
echo %@ifilesize[https://jpsoft.com/downloads/v29/tcmd.exe]
@IFILETIME2 — Returns
the time stamp of an internet file.
Syntax:
%@IFILETIME2[url,fmt]
| url | required; must begin with http:// or ftp:// |
| fmt | the format in which to return the date: |
| fmt: | Format: | Example: |
|---|---|---|
0 | the default local short date format | 10/31/23 |
1 | mm/dd/yy (USA) | 10/31/23 |
2 | dd/mm/yy (Europe) | 31/10/23 |
3 | yy/mm/dd (Japan) | 23/10/31 |
4 | yyyy-mm-dd (ISO 8601, the default) | 2023-10-31 |
5 | yyyy-Www-d (ISO 8601 week-day) | 2023-W44-2 |
6 | yyyy-ddd (ISO 8601 year-day) | 2023-304 |
16 | MS-DOS day number | +16009 |
17 | using English names | Tuesday, October 31, 2023 |
18 | T format (offset from today’s date) | |
19 | ANSI day number | A+154436 |
20 | ISO 8601, packed | 20231031 |
21 | days since 1970-01-01 | U+19661 |
32 | Windows user locale “long date” format | Tuesday, October 31, 2023 |
145 | using local names | mardi, 31 octobre 2023 |
256 | local short date format, four-digit years | 10/31/2023 |
257 | mm/dd/yyyy | 10/31/2023 |
258 | dd/mm/yyyy | 31/10/2023 |
259 | yyyy/mm/dd | 2023/10/31 |
If you do not specify fmt, it defaults to 4 (ISO 8601 format).
Dates and times returned are GMT. To convert to local time, add 1024 to fmt.
echo %@ifiletime2[https://jpsoft.com/downloads/v29/tcmd.exe]
Startup Message:
This plugin displays an informational line when it initializes. 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 |
|---|---|---|
| 1.0.4.2 | 2023-10-15 | Tweaked ShowCmdHelp() to include
VER_PATCH. |
| 1.0.4.1 | 2023-10-12 | Updated the plugin’s web address. |
| 1.0.4 | 2023-06-13 | Removed a call to QueryIsFile(), to work around an issue in TCC v30.00.20. |
| 1.0.3 | 2023-01-12 | Changes to handling of FTP files
in @IFILETIME2: you don’t need read permission to get the time stamp.
Improvements to GetErrorText(). |
| 1.0.2 | 2022-12-20 | Moved ParseArgs() out to ParseArgs.cpp. Moved date-formatting code out to DateToString.cpp. Added more date formats (from ISO6801). |
| 1.0.1 | 2022-12-16 | Added
@IFILETIME2. Removed the attempt to call
TCC’s Type_Cmd(); that hasn’t been present for many, many releases. |
| 1.0.0 | 2021-07-08 | First release.
Added @IFILESIZE, and documented
_ACQAGENT. Tweaks to the user agent string.
Switched the .DLL names; now Acquire.dll is the 64-bit
build. Much cleanup of the code and documentation. |
Status and Licensing:
This plugin is © Copyright 2023, Charles Dye. Unaltered copies of the binary and documentation files may be freely distributed without restriction. I make no guarantee and give no warranty for its operation. If you find a problem, you can report it in the JP Software support forum.
Download:
You can download the current version of the plugin from http://charlesdye.net/dl/acquire.zip.