Command
	isret

Purpose
	Retrieves (gets) a file (document) from the internet.

Aliases
	isretrieve, isret, isr, isget

Syntax
	isret [ <options> ] <name> [ <server_file>
	                                   [
	                                           [ <parm_name>=<parm_value> ]
	                                           [ <parm_name>=<parm_value> ]
					           ...
	                                   
	                                   ]
	                           ]

Options
	-b	Retrieve the <server_file> (document) is binary form. Without this option, the
		server file or document is retrieved in text form.

	-w	Parameter data (in the <name=value> form) is in raw format. Without this option, the data
		will be formatted before sending it to the server. With this option,
		the data will be sent as it is.


Arguments
	<name>	This is the name of the internet session, also called session. A session
		by this name must have already started with the isstart command and connected to
		a server with the iscon command.

		This argument can be supplied using a constant, variable, expression, function call,
		inline command, or a combination of these, all resulting into a single value of type str.
		If a constant is used, it should be enclosed in double quotes.

	<server_file>	Name of the file to retrieve or get. The file needs to be relative to the root directory on
		the server. If this argument is not specified, "/" will be retrieved, which is the default
		file served by that server.

		This argument should not include "http://", "https://", "www", ".com", etc. The file location
		needs to be relative to the server's root directory.

		This argument can be supplied using a constant, variable, expression, function call,
		inline command, or a combination of these, all resulting into a single value of type str.
		If a constant is used, it should be enclosed in double quotes.

	Parameters to the server are passed as <parm_name> and <parm_value> separated by an equal sign.

	<parm_name>	Name of a parameter.

	<parm_value>	Value of the parameter.

		Each parameter (<parm_name>=<parm_value>) can be supplied using a constant,
		variable, expression, function call, inline command, or a combination of these, all resulting
		into a single value of type str. If a constant is used, it should be enclosed in double quotes.


Stream Input	
	Ignored.

Stream Output
	The document served by the server is written here.

	If the <server_file> is binary, only a text representation is written here.

Stream Error
	Any errors are listed here.

Description
	This command retrieves or gets a file or a document using an internet session. The session must have
	already been started with the isstart command, and connected to a server with the iscon command.

	The retrieved file or document can be text or binary. Examples of text files are files in the following
	formats.

	.html	Hypertext Markup Language
	.csv	Comma Separated Values
	.txt	Text
	.asp	Active Server Pages
	.css	Cascaded Style Sheet
	.js	Java Script
	.pl	Perl script
	.vbs	Visual Basic Script
	etc.

	Examples of binary files are files in the following formats.

	.jpg	Joint Photographic Experts Group
	.mpeg	Motion/Moving Picture Experts Group
	.xls	Excel
	.doc	Word
	.wav	Waveform (Audio)
	etc.

	(The above terms may be trademarks, service marks or other forms of intellectual property
	of their respective owners.)
	
	The contents of the retrieved file are written to the stream output. You can redirect these
	contents to a file, a string variable, an inline command, etc.

	If the <server_file> is binary, only a text representation is written into stream output.
	However, the binary content remains in the sessions buffers, which can be copied into
	a local binary file with the use of the issave command.

	For retrieving text documents that require no special dialog with a server, you can simply use
	the repro command, such as the following.

	repro "http://www.yourfavoritesite.com/index.html"

	The above command will retrieve file index.html from the server and show you its contents.
	When the file name supplied to the repro command begins with "http://", the repro command
	assumes that the file is on the internet. It will then connect to the internet, and acquire that
	file. In other words, the repro command will do the dialog with the server for you - you would not
	have to explicitly write the commands isstart, iscon, isret, isdiscon, and isend.


Restrictions
	Your system must be connected to the internet for this command to succeed.

Valid Examples
	isstart "mail"
	iscon "mail" "http://mail.yourfavoritesite.com"
	isret "mail" "/mymail.html"

	Will retrieve the file "mymail.html" from the server http://mail.yourfavoritesite.com.


	If the file "mymail.html" requires a language parameter, use the following.

	isstart "mail"
	iscon "mail" "http://mail.yourfavoritesite.com"
	isret "mymail.html" "language=English"


	If the file "mymail.html" requires two parameters, use the following.

	isstart "mail"
	iscon "mail" "http://mail.yourfavoritesite.com"
	isret "mail" "/mymail.html" "language=English" "location=US"


	The above isret command can also be issued as

	isret "mail" "/mymail.html?language=English&location=US"



	If the server returns a field in the format "name=value", you can extract it from
	the output of the isret command as follows.

	var str content
	isstart "mail"
	iscon "mail" "http://mail.yourfavoritesite.com" "you@yourfavoritesite.com" "yourpassword" > $content
	# Extract the field in the form "name=value".
	var str parameter
	stex -c "]^name=^" $content > null
	stex "]^\"^" $content > $parameter
	# $parameter now contains the parameter in the form "name=value".
	isret "mail" "/mymail.html" "language=English" "location=US" $parameter


Invalid Examples
	isstart "accesslog"
	isret "accesslog" 

	Will produce an error. Session "accesslog" is not connected to a server.

	
	isstart "accesslog"
	iscon "accesslog" "http://www.myserver.com"
	isret "dailylog.html"

	Will produce an error. There is no session named "dailylog.html". If the intent is to retrieve
	the file "dailylog.html" using the session "accesslog", use the following command instead.

	isret "accesslog" "dailylog.html"


See Also
IS
isstart
isend
iscon
isdiscon
issub
isheadret
isheadsub
issave
repro
stex
var