1<html>
2<head>
3<title>ftp Library Package 2.2 for Tcl/Tk help file</title>
4</head>
5<body bgcolor="#ffffff" text="#000000">
6<body>
7
8<p>
9<dl>
10  <dd>
11    <p><font face="Arial,Helvetica" color="#526e9c" size="+2"><b>ftp Library Package 2.1 for Tcl/Tk Manual Pages</b></font></p>
12  </dd>
13
14  <dd><font face="Arial,Helvetica" size="+1"><b>COMMAND</b></font></dd>
15  <dd><dl>  
16    <dd><b>ftp::Open</b>&nbsp; <em>server&nbsp; user&nbsp; passwd&nbsp; ?options?</em></dd>
17    <dd>&nbsp;</dd>
18    <dd>
19	The <b>ftp::Open</b> command is used to start the FTP session by 
20	establishing a control connection to the FTP server. If no 
21	options are specified, then the defaults are used. 
22
23	<p>The <b>ftp::Open</b> command takes a host name <em>server</em>, a user name
24	<em>user</em> and a password <em>password</em> as its parameters and returns
25	a session handle that is an integer greater than or equal to 0 if the
26        connection is successfully established, otherwise it returns "-1".<br>
27	The <em>server</em> parameter must be the name or internet address (in dotted decimal
28	notation) of the ftp server. The <em>user</em> and <em>passwd</em> parameters must contain a
29	valid user name and password to complete the login process.</p>
30
31	The options overwrite some default values or set special 
32	abilities:
33
34	<p><b>-blocksize size</b><dl><dd>
35	The blocksize is used during data transfer. At most <em>size</em>
36	bytes are transfered at once. After each block, a call 	to the "-progress callback" is made.
37	The default value for this option is 4096.</dd></dl></p>
38
39	<p><b>-timeout seconds</b><dl><dd>
40	If <em>seconds</em> is non-zero, then <b>ftp::Open</b> sets up a timeout
41	to occur after the specified number of seconds. The default value is 600.</dd></dl></p>
42
43	<p><b>-port number</b><dl><dd>
44	The <em>port number</em> specifies an alternative remote port on
45	the ftp server on which the ftp service resides. Most 
46	ftp services listen for connection requests on default
47	port 21. Sometimes, usually for security reasons, port
48	numbers other than 21 are used for ftp connections.</dd></dl></p>
49		
50	<p><b>-mode mode</b><dl><dd>
51	The <em>transfer mode</em> option determines if a file transfer 
52	occurs in an active or passive way. In passive mode the
53	client session may want to request the ftp Server to
54	listen for a data port and wait for the connection 
55	rather than initiate the process when a data transfer
56	request comes in. Passive mode is normally a requirement
57	when accessing sites via a firewall. The default mode is active.</dd></dl></p>
58		
59	<p><b>-progress callback</b><dl><dd>
60	The <em>callback</em> is made after each transfer of a data 
61	block specified	in blocksize.  The callback gets as
62	additional argument the current	number of bytes transferred so far. 
63	Here is a template for the progress callback:<br>
64
65	<pre>proc Progress {total} {
66	puts "$total bytes transfered!"
67}</pre></dd></dl></p>
68
69	<p><b>-command callback</b><dl><dd>
70	Specifying this option puts the connection in asynchronous mode.
71	The <em>callback</em> is made after each operation has been
72	completed.  The callback gets as an additional argument
73	a keyword of the operation that has completed plus
74	additional arguments specific to the operation.
75	If an error occurs the callback is made with the keyword
76	"error".  When an operation, such as "Cd", "Get", and so on,
77	has been started no further operations should be started
78	until a callback has been received for the current
79	operation.
80	A template for the callback is:<br>
81
82	<pre>proc Callback {what args} {
83    puts "Operation $what $args completed"
84}</pre></dd></dl></p>
85
86    </dd>
87  </dl></dd>
88
89  <dd><font face="Arial,Helvetica" size="+1"><b>EXAMPLE</b></font></dd>
90  <dd><dl>
91    <dd>
92	<pre>set server "ftp.server.com"
93set user "anonymous"
94set passwd "mist@foo.com"
95
96# define callback
97proc Progress {total} {
98	puts "$total bytes transfered!"
99}
100
101# open a new connection
102if {[set conn [ftp::Open $server $user $passwd -progress Progress -blocksize 1024 -mode passive]] == -1} {
103	puts "Connection refused!"
104	exit 1
105}
106
107# get a file
108ftp::Get $conn index.html
109
110# close connection
111ftp::Close $conn
112	</pre>
113		
114    </dd> 
115  </dl></dd> 
116
117</dl>
118</p>
119<p>
120[<a href="index.html">Contents</a>]&nbsp;
121[<b>Next:</b> <a href="fhelp2.html">ftp::Close</a>]
122</p>
123
124<p align="left"><hr noshade size="1"><font face="Arial,Helvetica" size="-1">&copy; 1999 <a href="mailto:Steffen.Traeger@t-online.de">Steffen Traeger</a></font></p>
125</body>
126</html>
127