Ascp and Ascp4 Lua Functions

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

Filesystem Functions

The file functions perform operations on files 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 pathname as its only parameter. If docroot is set, the pathname 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 indices. 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 filesystem filemode (format based on OS modeformat, above)
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 should 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 shutting 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 could shut down (cleanly) while the Lua processing is still underway. Thus runtime information on the peer may not show the results of any Lua call to lua_session_abort() should it happen after the session terminates.

Encryption-at-Rest

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 re-naming 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