FTPClient (Use FTP, or FTPS, or SFTP to Manage Files)
FTPClient is used to manage files on a server using FTP
Syntax
Variable = FTPClient ( IPAddress, User, Password, LocalFileName, RemoteFileName, PutGetOption, NumRecs/TimeIntoInterval [optional], Interval [optional], IntervalUnits [optional], FileOption, [optional], TimeOut [optional] )
Example
Example #1
The following is an example of streaming data from a table and from only one field. There are examples of auto appending of numbering and .dat like tablefile, and also not auto numbering and using Public.Timestamp to append a date/time. This example also shows streaming based on time and based on number of new records.
Public PTemp, BattV
Public Result(7)
Public TStamp As String * 22
Const Server = "server.com"
Const User = "user"
Const Pass = "pass"
DataTable (Test,1,1000)
DataInterval (0,1,Min,10)
Minimum (1,BattV,FP2,0,False)
Sample (1,PTemp,FP2)
EndTable
BeginProg
Scan (5,Sec,0,0)
Battery (BattV)
CallTable Test
NextScan
SlowSequence
Scan (30,Sec,3,0)
'get filename friendly timestamp; get at top of scan so we don't have fractional seconds in result
TStamp = Public.Timestamp(5,1)
'Stream data from the "Test" table every 5 minutes into a file named "Ex1_YYYY-MM-DD_HH-MM-SS.FS.dat"
Result(1) = FTPClient (Server,User,Pass,"Test","Ex1_" & TStamp & ".dat",2,0,5,Min,-1008)
'Stream data from the "Test" table every 5 minutes into a file named "Ex2_n.dat"
Result(2) = FTPClient (Server,User,Pass,"Test","Ex2_",2,0,5,Min,8)
'Stream data from the "BattV_Min" data field of the "Test" table every 5 minutes into a file named "Ex3_n.dat"
Result(3) = FTPClient (Server,User,Pass,"Test.BattV_Min","Ex3_",2,0,5,Min,8)
'Stream data from the "Test" table, each time it records 5 new records, into a file named "Ex4_n.dat"
Result(4) = FTPClient (Server,User,Pass,"Test","Ex4_",2,5,0,Min,8)
'Every 1 minute stream 5 minutes of data from the "Test" table into a file named "Ex5_n.dat"
If IfTime(0,1,Min) Then
Result(5) = FTPClient (Server,User,Pass,"Test","Ex5_",2,0,-5,Min,8)
EndIf
'Every 1 minute stream 2 records of data from the "Test" table into a file named "Ex6_n.dat"
If IfTime(0,1,Min) Then
Result(6) = FTPClient (Server,User,Pass,"Test","Ex6_",2,-2,0,Min,8)
EndIf
'Every 10 minutes send 2 files, each containing 5 minutes of data from the "Test" table into files named "Ex7_n.dat"
If IfTime(0,10,Min) Then
Result(7) = FTPClient (Server,User,Pass,"Test","Ex7_",2,0,5,Min,8)
EndIf
NextScan
EndSequence
EndProg
Example #2
The following CRBasic program provides an example of streaming data to an FTP server, using a static file name and appending new data to the existing file.
'Measurement Variables
Public Bat, RefTemp, Temp, FTPResult
Public Flag(2) As Boolean
'FTP parameter strings (as constants), Message String & Result Variable
Const IPAddress="192.168.14.69"
Const UserName="anonymous"
Const Password=""
DataTable (FTPTest,True,-1)
DataInterval (0,10,Sec,10)
Sample (1,Bat,FP2)
Sample (1,Temp,FP2)
EndTable
BeginProg
Scan (1,Sec,3,0)
Battery(Bat)
TCDiff (Temp,1,mv34,1,TypeT,RefTemp,True,0,4000,1.0,0)
CDM_TCDiff (VOLT116,CPI_BusB + 1,Temp,1,mv34,1,TypeT,RefTemp,True,0,4000,1.0,0)
CallTable (FTPTest)
NextScan
SlowSequence
Scan (1,Sec,3,0)
If Flag(1) 'Flag(1) triggers FTP
'Create file named GRANITE6data.txt and append data to the file
'File format is TOA5 with header & record number
'The header is written to the file with the first write of the file
'subsequent writes will not include header info unless the file has been
'deleted (8 is the file format option; 1000 indicates static file name;
'negating value means do not write header with each write of new data)
FTPResult=FTPClient (IPAddress,UserName,Password,"FTPTest","GRANITE6data.txt",9,0,0,Min,-1008)
Flag(1) = False
EndIf
NextScan
EndProg
Example #3
The slow sequence in the following example program shows the use of FTPClient to send a file generated by the TableFile instruction to an FTP site. In the main scan, option 6 of FTPClient is used to retrieve a directory of files from that FTP site into a text file on the datalogger's
'Measurement Variables
Public Bat, RefTemp, Temp, FTPResult, FTPResult2
Public Flag(2) As Boolean
'TableFile variables
Public OutStat As Boolean, OutStatTrig As Boolean, LastFileName As String * 30
'FTP parameter strings (as constants), Message String & Result Variable
Const IPAddress="192.168.7.76"
Const UserName="anonymous"
Const Password=""
DataTable (Test,True,-1)
DataInterval (0,15,Sec,10)
Sample (1,Bat,FP2)
Sample (1,Temp,FP2)
Sample (1,LastFileName,String)
TableFile ("
EndTable
BeginProg
Scan (1,Sec,3,0)
Battery(Bat)
TCDiff (Temp,1,mv34,1,TypeT,RefTemp,True,0,4000,1.0,0)
CDM_TCDiff (VOLT116,CPI_BusB + 1,Temp,1,mv34,1,TypeT,RefTemp,True,0,4000,1.0,0)
CallTable (Test)
If OutStat Then OutStatTrig=True
'If Flag(1) is high, retrieve a directory listing from the FTP server
If Flag(1)
FTPResult2=FTPClient (IPAddress,UserName,Password,"
Flag(1) = False 'Set flag to False so directory is retrieved only once
EndIf
NextScan
SlowSequence
Scan (1,Sec,3,0)
If OutStatTrig
'When a new file is written by TableFile, send that file to the FTP server
'Mid
is used because otherwise, the datalogger tries to save a file called
'and the computer doesn't know what the do with "
FTPResult=FTPClient (IPAddress,UserName,Password,lastfilename,Mid(LastFileName,5,20),0)
OutStatTrig=False
EndIf
NextScan
EndProg
Example #4
The following example program uses the FileWrite function to write a simple HTML file to the datalogger's
Public BatteryVoltage, AirTemperature, Count as LONG
Public FileWriteFailed as Boolean, FTPSuccess
Dim filehandle as long
Dim BytesWritten as long
Public CloseFailed as Boolean
DataTable(TenthSec,true,400)
Sample(1,count,LONG)
Sample(1,AirTemperature,IEEE4)
Sample(1,BatteryVoltage,FP2)
Sample(1,FileWriteFailed,Boolean)
Sample(1,FTPSuccess,Boolean)
EndTable
BeginProg
Scan(100,msec,10,0)
Battery(BatteryVoltage)
If count = 100 then
count = 0
filehandle = FileOpen("
BytesWritten = FileWrite(filehandle,"The current temperature is " + AirTemperature + " ",0)
BytesWritten = BytesWritten + FileWrite(filehandle,"The current battery voltage is " + BatteryVoltage + " ",0)
BytesWritten = BytesWritten + FileWrite(filehandle,"The sample time is " + Public.TimeStamp(0,1) + " ",0)
if BytesWritten = 0 then FileWriteFailed = TRUE
CloseFailed = FileClose(filehandle)
FTPsuccess = FTPClient("192.168.4.229","JohnDoe","MyPassword","
EndIf
CallTable TenthSec
count = count+1
NextScan
EndProg
Remarks
The FTPClient function opens an FTP socket to a remote machine. The remote machine can be either a datalogger or a computer, but it must have an FTP server running. FTPClient can be used to monitor the success/failure of transferring a file.
Most commonly, FTPClient is used to send data or image files from the datalogger’s local file system to a remote FTP server hosted by a computer or another datalogger. These files are commonly created by TableFile, custom File I/O routines, or collected from a Campbell Scientific camera. FTPClient can also be used to manage these files.
FTPClient can be used to stream data directly from a data table to the server, eliminating the need to first write the data to a local file prior to transfer. This is accomplished using the last four parameters, which are optional and used only for this streaming functionality.
When multiple IP interfaces (for example, Ethernet port, CS I/O port, Wi-Fi, PPP) are active, the IPRoute() instruction is used to direct outgoing IP traffic.
The datalogger waits up to 75 seconds for FTPClient to return a result; thus, it can hold up the scan. Because of this, it should generally be run in a SlowSequence so that it does not hold up the main program scan while waiting for the transaction to be completed.
This function returns -1 if successful, 0 if it fails, or -2 if execution did not occur when the instruction was called (for instance, when using the optional parameters to stream data from a table and the number of records or time into interval conditions are not met).
For more information on using the FTPClient instruction for streaming data see the Data Streaming application note. For more information on troublshooting, see the FTP Troubleshooting application note.
Parameters
IPAddress (IP Address)
The IP address for the device you are trying to send a file to or retrieve a file from. This is a string expression, which can be entered as a numeric address (for example, "xxx.xxx.xxx.xxx", with each xxx being a value of 0 to 255) or a fully-qualified domain name (for example, "computer-name.domain.com"). FTP URL syntax (for example, ftp://server.com) should not be used. The default port number used is 21. If a different port number is required, follow the IPAddress with a colon and enter the port number (for example, 192.168.3.45:35).
Type: String expression
User (FTP User Name)
The User Name that must be entered to gain access to the FTP functions of the remote device.
Type: Constant string (enclosed in quotes) or variable string
Password
The password that must be entered to gain access to the FTP functions of the remote device.
Type: Constant string (enclosed in quotes) or variable string
LocalFileName (Local File Name)
A string expression containing a local file name, comma separated list of local file names, data table name, or data table field name. Multiple files can be specified by separating their names with a comma (note that you cannot use multiple file names when streaming data). Make sure to include the file directory along with the file name. To stream all data tables, specify the optional parameters necessary for streaming and specifiy the source parameter as an empty string (“”).
If a directory listing is retrieved with this function, LocalFileName will specify a file name in which to write the results, or an array in which to write the results, where the name of each file will be written into its own array element. CR/LF characters are replaced with null. If an array element exists beyond the number of files listed, a null is written into that element.
If retrieving a file, this parameter is the filename to use when writing the file on the datalogger’s drive; alternately, if the parameter is a string variable that does not specify a drive (i.e., the fourth character is not “:”), the results will be written to the variable directly. If using the delete action, this parameter will often be an empty string (“”). If using the rename action, this parameter should contain the name of the remote file(s) to be renamed. If streaming data directly from a data table or table field to a file on the FTP server, this parameter should specify the table name (for example, “TableOne”) or table field name (for example, “TableOne.BattV_Min”) that will be used as the data source. Note that when specifying a fieldname, if Tablename.Fieldname is a variable, the length of the Tablename.fieldname is limited to 63 characters.
Type: Constant string (enclosed in quotes) or variable string
RemoteFileName (Remote File Names)
This parameter specifies the remote file name or a comma-separated list of file names for sending, retrieving, or deleting data, or for listing directory contents. For renaming, it indicates the new file name(s). Include the directory and file name (e.g., “/Data/file01.dat”). Multiple files should be listed as “file01.dat,/Data/file02.dat”. Use forward slashes (/) for directories, suitable for all operating systems. If no directory is specified, the root directory is assumed. The specified directory must pre-exist on the server.
To add a timestamp to the remote file name, include this exact string of characters “YYYY-MM-DD_HH-MM-SS” in the RemoteFileName parameter (For example “tabledata_YYYY-MM-DD_HH-MM-SS.xml”). When the file is written, a timestamp will be put into the remote file name in place of “YYYY-MM-DD_HH-MM-SS”.
If streaming data, the timestamp of the first record streamed is used in the remote file name. If data streaming is not used, the current datalogger clock time is used.
Other methods to include a timestamp in the remote file name involve using string concatenation to insert the return value of tablename.timestamp(5, 1) into the file name. See Example Program 1 for an example of including a timestamp in the remote file name using this method.
When streaming data, the remote file name is automatically appended with an incrementing file number and a “.dat” file extension unless 1000 is added to the format option. For example, if the FileOption is 8 (TOA5, Header, Timestamp, Record#) and 1000 is added (1008), the data logger will not automatically append the incrementing number or “.dat” extension to the uploaded file.
Also, if the RemoteFileName parameter contains the exact string “YYYY-MM-DD_HH-MM-SS” for the addition of a timestamp, as described above, the incrementing file number and “.dat” extension will not automatically be appended.
If the automatically appended incrementing file number and “.dat” extension are desired along with having a timestamp in the filename, use a method other than “YYYY-MM-DD_HH-MM-SS”, like the concatenation method in Example Program 1.
Type: Constant string (enclosed in quotes) or variable string
PutGetOption (Send or Receive a File)
Determines 1) whether the datalogger will send or retrieve a file, 2) whether active or passive mode is used, and 3) whether FTP
Passive mode is not applicable with SFTP.
Active vs. Passive mode
In active mode, the client initiates contact with the server and the server must connect back to the client on the port specified by the client. This response from the server may be blocked by the client’s firewall. Passive mode resolves the issue of firewalls by having the client issue a PASV command that opens two random unprivileged ports to the server. In response to the PASV command from the client, the server sends a random port number back to the client. Finally, the client initiates a connection from the server via the port specified by the server. Not all servers support passive mode.
FTPS
The default server port for implicit FTPS is 990. Otherwise, explicit security is used. Implicit security automatically begins with an SSL connection as soon as the FTP client connects to an FTP server, whereas with explicit security, the client and server negotiate the level of protection used.
SFTP
The default server port for SFTP is 22. In order to utilize SFTP, an SFTP Public Key and SFTP Private Key must be set in the datalogger's advanced settings (see the Settings Editor). If these two settings are set and if the server advertises that it can authenticate with a Public/Private key pair, then authentication is attempted using this setting along with the user name and password parameters. Note a limitation with this: if more than one SFTP server is used in the program and if they require the public/private key pair authentication method, then the same public/private key pair must work for each server.
Right-click the parameter to display a list with the options:
| Option Code | Description |
|---|---|
| 0 | FTP - Store file to server, active mode |
| 1 | FTP - Retrieve file from server, active mode |
| 2 | FTP - Store file to server, passive mode |
| 3 | FTP - Retrieve file from server, passive mode |
| 4 | FTP - Delete file on server |
| 5 | FTP - Rename file on server |
| 6 | FTP - Directory listing, active mode. Returns a directory listing (instead of a file) into LocalFileName. The path to the directory of the FTP server from which to return the directory listing is specified in the RemoteFileName parameter. This is similar to the FTP LIST command. -6 returns file names only (similar to NLST) |
| 7 | FTP - Directory listing, passive mode. Returns a directory listing (instead of a file) into LocalFileName. The path to the directory of the FTP server from which to return the directory listing is specified in the RemoteFileName parameter. This is similar to the FTP LIST command.-7 returns file names only (similar to NLST) |
| 8 | FTP - Append data to end of file, active mode (creates a file if it does not already exist) |
| 9 | FTP - Append data to end of file, passive mode (creates a file if it does not already exist) |
| 10 | FTPS - Store file to server, active mode |
| 11 | FTPS - Retrieve file from server, active mode |
| 12 | FTPS - Store file to server, passive mode |
| 13 | FTPS - Retrieve file from server, passive mode |
| 14 | FTPS - Delete file on server |
| 15 | FTPS - Rename file on server |
| 16 | FTPS - Directory listing, active mode. Returns a directory listing (instead of a file) into LocalFileName. The path to the directory of the FTP server from which to return the directory listing is specified in the RemoteFileName parameter. This is similar to the FTPS LIST command. -16 returns file names only (similar to NLST) |
| 17 | FTPS - Directory listing, passive mode. Returns a directory listing (instead of a file) into LocalFileName. The path to the directory of the FTP server from which to return the directory listing is specified in the RemoteFileName parameter. This is similar to the FTPS LIST command.-17 returns file names only (similar to NLST) |
| 18 | FTPS - Append data to end of file, active mode (creates a file if it does not already exist) |
| 19 | FTPS - Append data to end of file, passive mode (creates a file if it does not already exist) |
| 20 | SFTP - Store file to server, active mode |
| 21 | SFTP - Retrieve file from server, active mode |
| 24 | SFTP - Delete file on server |
| 25 | SFTP - Rename file on server |
| 26 | SFTP - Directory listing, active mode. Returns a directory listing (instead of a file) into LocalFileName. The path to the directory of the FTP server from which to return the directory listing is specified in the RemoteFileName parameter. This is similar to the SFTP LIST command. -26 returns file names only (similar to NLST) |
| 27 | SFTP - Directory listing, passive mode. Returns a directory listing (instead of a file) into LocalFileName. The path to the directory of the FTP server from which to return the directory listing is specified in the RemoteFileName parameter. This is similar to the SFTP LIST command.-27 returns file names only (similar to NLST) |
| 28 | SFTP - Append data to end of file, active mode (creates a file if it does not already exist) |
FTPS(TLS)
Type: Variable
Optional Parameters For Data Streaming
NumRecs/TimeIntoInterval (Time into Interval to Write the Number of Records)
Used only when streaming data directly from a data table or data table field.
For more details, see the Data Streaming document.
If Interval is greater than 0, the NumRecs/TimeIntoInterval parameter specifies the time into the interval at which previously unsent records should be written to file on the server.
If Interval is equal to 0, the NumRecs/TimeIntoInterval parameters specifies the number of previously unsent records that will be written to file on the server. If Interval is equal to 0, a negative NumRecs/TimeIntoInterval parameter will specify the number of records that will be written to file on the server each time the function is called.
Type: Constant, optional parameter
Interval
Used only when streaming data directly from a data table or data table field. If greater than 0, the Interval parameter determines the interval at which previously unsent data will be written to file. If equal to zero, the NumRecs parameter will control when data is written. A negative Interval will cause the datalogger to write the most recent records within this time interval each time the function is called.
| NumRecs/ TimeIntoInterval |
Interval | Sent |
|---|---|---|
| 0 | 0 | All new (unsent) data in the data table is sent. |
| >=0 | >0 | Interval’s worth of previously unsent records. Only previously unsent data will be sent. If multiple intervals have passed between calls to this function, multiple files will be written to the server and each file will contain interval’s worth of records. |
| >0 | 0 | Number of previously unsent records. Only previously unsent data will be sent. If multiples of NumRecs have been recorded between calls to this function, multiple files will be written to the server and each file will contain NumRecs of records. |
| <0 | 0 | Each time this function is called, the most recent records up to NumRecs will be sent. |
| 0 | <0 | Each time this function is called, the most recent records within this time interval will be sent. |
Type: Constant
The datalogger keeps track of the last record sent within the FTPClient instruction. This information is maintained even through power-downs, as long at the data table in datalogger memory is intact.
Units
Used only when streaming data directly from a data table or data table field. It is used to specify the units on which the TimeIntoInterval and Interval parameters will be based. The options are microseconds, milliseconds, seconds, minutes, hours, or days.
Type: Constant
FileOption (File Format)
Used only when streaming data directly from a data table or data table field. It specifies the format used when writing data to the server. The file created on the server will automatically be appended with an incrementing file number and a “.dat” file extension. If 1000 is added to the format (for example, 1008), the datalogger will not automatically append the incrementing number or “.dat” extension to the uploaded file. If the FileOption parameter is entered as a negative value (for example, -1008), if a file of the same name is already present, no additional header will be appended to the file. Instead, only new records are appended so that data records are contiguous. Options 0, 8, 16, and 32 correspond to Campbell Scientific's defined formats for TOB1, TOA5, CSIXML, and CSIJSON, respectively.
| Code | Description |
|---|---|
| 0 | TOB1, Header, TimeStamp, Record# |
| 1 | TOB1, Header, TimeStamp |
| 2 | TOB1, Header, Record# |
| 3 | TOB1, Header |
| 4 | TOB1, TimeStamp, Record# |
| 5 | TOB1, TimeStamp |
| 6 | TOB1, Record# |
| 7 | TOB1 |
| 8 | TOA5, Header, TimeStamp, Record# |
| 9 | TOA5, Header, TimeStamp |
| 10 | TOA5, Header, Record# |
| 11 | TOA5, Header |
| 12 | TOA5, TimeStamp, Record# |
| 13 | TOA5, TimeStamp |
| 14 | TOA5, Record# |
| 15 | TOA5 |
| 16 | CSIXML, TimeStamp, Record# |
| 17 | CSIXML, TimeStamp |
| 18 | CSIXML, Record# |
| 19 | CSIXML |
| 32 | CSIJSON, TimeStamp, Record# |
| 33 | CSIJSON, TimeStamp |
| 34 | CSIJSON, Record# |
| 35 | CSIJSON |
Type: Constant, optional parameter
TimeOut (Response Wait Time)
Specifies a time period, in 0.01 seconds, that the datalogger will wait for input after a connection is made, before considering the attempt failed and incrementing Result. The default TimeOut in the absence of this parameter is 7500 (i.e., 75 seconds).
Type: Constant