|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Internet and Network > HTP. - Command > !HTP-General - General HTTP operations and utilities > !Request-Management - Commands for preparing, executing, and inspecting HTTP requests > HTP. - HTTP Operations |
SPR Script Language
HTP.DownloadFile
Downloads a resource from a URL and saves it directly to a local file.
Intention
The HTP.DownloadFile command is the most efficient way to download files, especially large ones. It streams the response body directly to the specified file path, avoiding loading the entire content into memory. This makes it ideal for saving images, audio files, documents, or any other binary resource from the web.
The command returns the final HTTP status code (e.g., 200) on the top-of-stack (TOS), allowing for easy verification of a successful download.
Syntax
HTP.DownloadFile|$$URL|$$PTH[|$$HED|$$FLG|$$UAG|$$APM|$$RET]
Parameter Explanation
P1 - $$URL - (Variable, String, Required)
The full URL of the resource to download.
P2 - $$PTH - (Variable, String, Required)
The full local path, including the filename, where the downloaded content will be saved.
P3 - $$HED - (Variable, String, Optional)
A string of custom headers to include in the GET request. Format: "key1=value1*key2=value2".
P4 - $$FLG - (Variable, numeric, Optional)
Numeric flags to modify request behavior. See HTP.Request for values.
P5 - $$UAG - (Variable, numeric, Optional)
A number from 0 to 30 to select a User-Agent. If omitted or -1, the global default is used.
P6 - $$APM - (Variable, numeric, Optional)
Append mode. If set to 1, the downloaded data will be appended to the file if it exists. If 0 or omitted, the file will be overwritten.
P7 - $$RET - (Variable, String, Optional)
An optional variable to store the final HTTP status code.
Examples
'***********************************
' HTP.DownloadFile - Sample 1: Download an image
'***********************************
VAR.$$URL=https://httpbin.org/image/jpeg
VAR.$$PTH=?path\downloaded_image.jpg
HTP.DownloadFile|$$URL|$$PTH
' Check for success (TOS should be 200)
JIV.$$TOS!200|Lab_failed
MBX.Success:|Image downloaded successfully to $$PTH
DFI.$$PTH ' Clean up the downloaded file
END.
Remarks
- This command implicitly uses the GET HTTP method.
- It returns the final HTTP Status Code on the top-of-stack ($$TOS). A value of 0 indicates a transport-level error (e.g., DNS lookup failed, could not connect). Check HTP.GetErr for details on failure.
See also: