Acquire plugin for Take Command / TCC / TCC/LE

Version 1.0.4.3 2024-10-04

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 command: ACQUIRE

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://`, `https://`, 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 https://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://, https://, 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://`, `https://`, 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.3	2024-10-04	Changed http:// to https:// in the `PLUGININFO` block. ParseInt() now supports octal values with a leading `0o`.
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 2024, 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 https://charlesdye.net/dl/acquire.zip.

— Quick Links —