CtxRelTargetPath()

function CtxRelTargetPath(): string;

Returns the event-context relative target path — the VFS-relative path the file is going to be (or had been) renamed to. This function is only available in the BeforeFileRename and AfterFileRename event-handlers; in every other event it returns an empty string "".

Why this function exists — and why it matters

IMPORTANT

Always use CtxRelTargetPath() when your script needs to know the destination path of a rename. Never rely on Session.GetRelPath() or Session.GetAbsPath() for this purpose.

Syncplify Server! runs event-handler scripts asynchronously and concurrently. By the time a script begins executing, or at any point during its execution, the session's internal "current path" cursor may have already advanced to a different file — because the client has kept working. Session.GetRelPath() and Session.GetAbsPath() reflect the session's live, current-cursor state, not the file that triggered the event.

CtxRelTargetPath() is different. The path is captured at the moment the event fires and frozen into the script's execution context. It never changes while the script runs, regardless of what the client does in the background. This makes it the only reliable way to reference the rename destination.

Use it together with CtxRelPath(), which holds the source path of the rename: CtxRelPath() is the original name, CtxRelTargetPath() is the new name.

Concrete example of the race condition

t=0  Client renames /docs/draft.pdf to /docs/final.pdf  →  AfterFileRename fires, script starts running
t=1  Script calls Session.GetRelPath()
t=1  Meanwhile: client has already navigated to /inbox/ and uploaded report.xlsx
     Session.GetRelPath() returns /inbox/report.xlsx     ← WRONG FILE
t=1  CtxRelPath() returns /docs/draft.pdf                ← source, always correct
t=1  CtxRelTargetPath() returns /docs/final.pdf          ← target, always correct

Return value

Scenario	Return value
BeforeFileRename or AfterFileRename event	VFS-relative target path, e.g. /docs/final.pdf
Any other event	"" (empty string)

Example

{
  var src = CtxRelPath();
  var dst = CtxRelTargetPath();
  if (dst === "") {
    Log("This event is not a rename, or has no target file path.");
    Exit();
  }
  Log("File renamed from " + src + " to " + dst);

  // Safe to use dst with VFS operations:
  var vfs = GetCurrentVFS();
  var info = vfs.Stat(dst);
  if (info) {
    Log("File size: " + info.Size);
  }
}

See also

• CtxRelPath() — the source path of the rename (the original name)
• EventHandler() — returns the name of the event that triggered this script
• Session.GetRelPath() — session-wide cursor; not suitable for identifying the triggering file
• Session.GetAbsPath() — session-wide absolute cursor; not suitable for identifying the triggering file