Ascp and Ascp4 Lua functions

Ascp and Ascp4 provide Lua functions for file system operations, logging, and aborting a session.

File system functions

Note: The Lua built-in print() function, as well as any other functions that interact with SDTIN or STDOUT, must not be used because they might interfere with session data and cause transfers to fail.

The file functions perform operations on files that are stored in the native file system or cloud storage:

  • lua_stat()
  • lua_file_delete()
  • lua_rename()
Note: lua_rename() is supported for ascp, but not for ascp4.
Each of the file functions take a path name as its only parameter. If docroot is set, the path name is relative to docroot. For example,
lua_stat("tmp\myFile")

The lua_stat() function populates the stat_data[] table. The data in the table can be accessed by using the name indexes. For example, stat_data["size"] holds the file size.

stat_data[] Index Description Values
exists File exists, or not true or false
size File size filesize
blocks Number of blocks fileblocks
blocksize Block size blocksize
type File type Invalid or S_IFDIR or S_IFREG or S_IFCHR or S_IFBLK or S_IFIFO or S_IFSOCK or S_IFLNK or Blockstream or Custom or Unknown
modeformat OS file format Windowsformat or Linuxformat
mode File mode set in file system filemode (format based on OS modeformat)
uid User ID uid
gid Group ID gid
ctime Change time ctime
mtime Modify time mtime
atime Access time atime

Logging functions

The lua_log() function writes a string to the various Ascp or Ascp4 log interfaces. Formatted strings are not supported. Only simple text strings like this can be used:
lua_log("Hello from lua-land")

This lua_log() call creates the following log entry (where xxxxxx is a placeholder for time, thread ID, and so on):

xxxxxx LOG lua: Hello from lua-land

Abort functions

The lua_session_abort() aborts a transfer session. It takes a text string as its parameter, which needs to be used to define the reason for aborting. For example,

lua_session_abort("aborted session: because, because, because!")

The lua_session_set_max_wait() function sets a countdown time before it is shut down. It takes a number for count of seconds; the default is 10 seconds. The lua_session_set_max_wait() function is useful when you are working with scripts that run a long time (for example, for validation). The peer is not affected by the countdown, and might shut down (cleanly) while the Lua processing is still underway. Thus runtime information on the peer might not show the results of any Lua call to lua_session_abort() should it happen after the session ends.

Lua function usage example

This script-first checks for the existence of a file. If the file does not exist, it aborts the transfer session. If the file exists, the script renames it and logs the renaming activity.

lua_stat(env_table["file"])
if stat_data == nil then
   lua_session_abort("Unable to stat file")
else
   lua_rename(env_table["file"],"C:\tmp\new_file_name")
   lua_log("Renamed file " .. env_table["file"] .. " to C:\tmp\new_file_name")
end