NAME

EAI::FTP - wrapper for Net::SFTP::Foreign

SYNOPSIS

removeFilesOlderX ($FTP)
fetchFiles ($FTP,$execute,$param)
putFile ($FTP,$param)
moveTempFile ($FTP,$param)
archiveFiles ($FTP,$param)
login ($FTP,$execute)
setHandle ($handle)

DESCRIPTION

EAI::FTP contains all (secure) FTP related API-calls. This is for logging in to a FTP Server, getting files from a remote folder, writing files to a remote folder, archiving/deleting files from/on a remote folder (to an archive folder) and removing files on an FTP server being older than a Date X.

API

getConn

returns the net-sftp-foreign ftp-handler and the RemoteHost string to allow direct commands with the handler

removeFilesOlderX

remove files on FTP server being older than a time back (given in remove)

$param .. ref to hash with function parameters:
$param->{remove}{removeFolders} .. list of folders where files should be removed
$param->{remove}{day} .. days back to remove
$param->{remove}{mon} .. months back to remove
$param->{remove}{year} .. years back to remove
$param->{remoteDir} .. remote directory where files are located

returns 1 if ALL files were removed successfully, 0 on error (doesn't exit early)

fetchFiles

fetch files from FTP server

$param .. ref to hash with function parameters:
$param->{fileToRetrieve} .. file to retrieve. if a glob (*) is contained, then multiple files are retrieved
$param->{fileToRetrieveOptional} .. flag that file is optional

additionally following parameters from $FTP and $execute are important

$execute->{retrievedFiles} .. returned array with retrieved file (or files if glob was given)
$execute->{firstRunSuccess} .. used to suppress fetching errors (if first run was already successful)
$execute->{homedir} .. standard storage path
$FTP->{queue_size} .. queue_size for Net::SFTP::Foreign, if > 1 this causes often connection issues
$FTP->{remoteDir} .. remote directory where files are located
$FTP->{path} .. path of folder of file below remoteDir
$FTP->{localDir} .. alternative storage path, if not given then files are stored to
$FTP->{fileToRemove} .. ignore errors for a file that was either removed or is optional 
$FTP->{dontDoUtime} .. don't set time stamp of local file to that of remote file

returns 1 if ALL files were fetched successfully, 0 on error (doesn't exit early)

putFile

put file to FTP server

The file is written either directly ($FTP->{dontUseTempFile} 1) or as temp.<name> file ($FTP->{dontUseTempFile} = 0 or not set), these temp files are immediately renamed on the server (if $FTP->{dontMoveTempImmediately} = 0 or not set), when $FTP->{dontMoveTempImmediately} =1 then this waits until moveTempFile is called. This is needed to have an atomic transaction for file monitoring jobs on the FTP site! when $FTP->{dontDoSetStat} is set for Net::SFTP::Foreign handles, no setting of time stamp of remote file to that of local file is done (avoid error messages of FTP Server if it doesn't support this)

$param .. ref to hash with function parameters:
$param->{fileToWrite} .. file to upload. this has to exist in local folder
$param->{remoteDir} .. remote directory where files are located

returns 1 if ALL files were written successfully, 0 on error (exits on first error !)

moveTempFile

separately rename temp file on FTP Server to final name (atomic transaction !)

$param .. ref to hash with function parameters:
$param->{fileToWrite} ..  file to rename from temp to final
$param->{remoteDir} .. remote directory where files are located

returns 1 if ALL files were renamed successfully, 0 on error (exits on first error !)

archiveFiles

archive files on FTP server, given in $param->{filesToArchive}

$param .. ref to hash with function parameters:
$param->{filesToArchive} .. ref to array with files to be archived if a glob is given, it is being resolved and all retrieved files are archived separately
$param->{timestamp} .. timestamp to prepend to file, if undef this is done with the current datetime (YYYYMMDD_hhmmss)
$param->{remoteDir} .. remote directory where files are located
$param->{archiveDir} .. folder for archived files on the FTP server

returns 1 if ALL files were archived successfully, 0 on error (doesn't exit early), except for "No such file or directory" errors, only warning is logged here

removeFiles

delete files on FTP server, given in $param->{filesToRemove}

$param .. ref to hash with function parameters:
$param->{filesToRemove} .. ref to array with files to be deleted
$param->{remoteDir} .. remote directory where files are located

returns 1 if ALL files were deleted successfully, 0 on error (doesn't exit early), except for "No such file or directory" errors, only warning is logged here

login

log in to FTP server, stores the handle of the ftp connection

$FTP .. ref to hash with function parameters:
$FTP->{remoteHost}{Prod => "host", Test => "host",..} .. lookup hash for remote host(s) resolved by $execute->{env}
$FTP->{maxConnectionTries} ..  maximum number of tries for connecting in login procedure
$FTP->{sshInstallationPath} .. path were ssh/plink exe to be used by Net::SFTP::Foreign is located
$FTP->{user} .. for setting user directly
$FTP->{pwd} .. for setting password directly
$FTP->{dontUseQuoteSystemForPwd} .. for windows, a special quoting is used for passing passwords to Net::SFTP::Foreign that contain [()"<>& . This flag can be used to disable this quoting.
$FTP->{FTPdebugLevel} .. debug ftp: 0 or ~(1|2|4|8|16|1024|2048), loglevel is automatically set to debug for module EAI::FTP for FTPdebugLevel > 0
$FTP->{hostkey} .. hostkey to present to the server for Net::SFTP::Foreign, either directly (insecure -> visible) or via sensitive lookup
$FTP->{privKey} .. sftp key file location for Net::SFTP::Foreign, either directly (insecure -> visible) or via sensitive lookup
$FTP->{port} .. ftp/sftp port (leave empty for default ports 22)
$FTP->{SFTP} .. to explicitly use SFTP, if not given SFTP will be derived from existence of privKey or hostkey
$execute .. ref to hash with execution environment
$execute->{env} .. current environment (Prod, Test, Dev...)

returns 1 if login was successful, 0 on error

setHandle

sets externally created Net::SFTP:Foreign handle to be further used by EAI::FTP

$handle .. ref to Net::SFTP:Foreign handle

COPYRIGHT

Copyright (c) 2023 Roland Kapl

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.