/ 
EAI-Wrap-1.901
River stage zero No dependents
/ EAI::FTP

NAME

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

SYNOPSIS

removeFilesOlderX ($param)
fetchFiles ($FTP,$param)
putFile ($FTP,$param)
moveTempFile ($FTP,$param)
archiveFiles ($param)
removeFiles ($param)
login ($FTP,$setRemoteHost)
setHandle ($handle,$remoteHost)
getHandle ()

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

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

$FTP .. ref to hash with general FTP parameters:
$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
$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
$param->{firstRunSuccess} .. used to suppress fetching errors (if first run was already successful)
$param->{homedir} .. standard storage path
$param->{retrievedFiles} .. returned array with retrieved file (or files if glob was given)

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)

$FTP .. ref to hash with general FTP parameters:
$FTP->{dontUseTempFile} .. see above
$FTP->{dontMoveTempImmediately} .. see above
$FTP->{dontDoSetStat} .. see above
$FTP->{remoteDir} .. remote directory where files are located
$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 !)

$FTP .. ref to hash with general FTP parameters:
$FTP->{remoteDir} .. remote directory where files are located
$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->{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 sftp:  0||~(1|2|4|8|16|1024|2048) for Net::SFTP:Foreign or 0||1 for Net::FTP, loglevel automatically set to debug for module EAI::FTP if 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 or 21)
$FTP->{SFTP} .. to explicitly use SFTP, if not given SFTP will be derived from existence of privKey or hostkey. If neither exists, an FTP connection will be opened.
$setRemoteHost .. remote host to be set

returns 1 if login was successful, 0 on error

setHandle ($$)

sets externally created Net::SFTP:Foreign or Net::FTP handle to be further used by EAI::FTP. Additionally the RemoteHost used in the handle can be passed (used for calls to login)

$handle .. ref to handle
$remoteHost .. remote Host
getHandle

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

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.