Table of Contents

until

Free

Description

Waits until the supplied condition expression evaluates to true, or until the timeout is reached.

Use until after commands such as runtask, runtemplate, export, or any automation step that creates files asynchronously. This prevents the next command from running before the expected files, variables, or process state are ready.

Syntax

until -conditions condition_expression [-timeout seconds] [-onTimeout stop|continue] [-match all|any|one] [-filePath path | -id fileId | -search query]

Use -id as an alternative to -filePath for the same operand. A required target still needs one selector, even though each alternative is optional individually. See File IDs and paths for selection rules and command-specific exceptions.

Parameters

Parameter Alias Required Description
-conditions Yes The condition expression to evaluate. Supports and, or, nested groups, file/folder/process exists checks, comparisons, PDM variables, placeholders, and simple arithmetic comparisons.
-timeout No Maximum number of seconds to wait before the command fails. If omitted, PDMShell uses the command default.
-onTimeout No Optional timeout behavior. Use stop to stop the script after timeout, or continue to log the timeout and keep running. The default is stop.
-match No When search returns multiple files, controls how many files must satisfy the conditions. Use any when one matching file is enough, all when every matching file must pass, or one when exactly one matching file must pass.
-filePath No Optional file context used to evaluate PDM variables and file placeholders.
-search No Optional search query. When supplied, PDMShell evaluates the condition against the files returned by the search.
-directory No Optional vault folder used as the search scope. Only valid with search.
-recursive No Includes subfolders when used with search.
-id No Positive PDM file ID instead of -filePath, identifying the same file that -filePath describes (including a macro, input CSV or existing output file). Requires a connected vault. Shared files with multiple locations require an exact -filePath. Resolving the ID itself does not download, check out or check in the file; the requested command still performs its normal operation.

Examples

until -conditions "$localPath exists" -timeout 60

until -conditions "$folderPath\$fileNameWithoutExtension.pdf exists" -timeout 500

until -conditions "$folderPath\$fileNameWithoutExtension.pdf exists and $folderPath\$fileNameWithoutExtension.dxf exists" -timeout 500

until -conditions "$(Description.@) contains A" -filePath "C:\Vault\Parts\1001.sldprt" -timeout 30

until -conditions "\"$(Description.@)\" equals A" -filePath "$localPath" -timeout 600

until -conditions "1 + 3 greater than 3" -timeout 5

until -search "Name=%.sldprt;Locked=true" -conditions "$(Description.@) contains ECO" -match any -timeout 120

until -conditions "$folderPath\$fileNameWithoutExtension.pdf exists" -timeout 500 -onTimeout continue

Condition Format

The until command uses the shared PDMShell condition syntax. See Conditions for the full condition reference.

The Conditions editor accepts a text expression with autocomplete and automatic syntax validation. A condition conceptually has these parts:

Field Meaning Example
Variable / placeholder The left side of the condition. This can be a PDM variable, placeholder, path, text, or arithmetic expression. $localPath, $(Description.@), 1 + 3
Operator The operation to apply. Exists, Contains, Equal To, Greater Than
Value The right side of the condition. Hidden for Exists. A, 3, $fileName

Examples of generated conditions:

$localPath exists
"$(Description.@)" contains "A"
"$(Revision.@)" equals "A"
1 + 3 greater than 3
Note

PDM variables use $( and ), for example $(Description.@). For file data card variables, use .@ when reading the file @ tab. When writing conditions manually, quote PDM variable tokens if they appear inside a larger expression so the parser does not treat the parentheses as condition grouping.

Supported Operators

  • exists or exist
  • equals, equal, is, =, ==
  • not equals, !=, <>
  • contains
  • starts with
  • ends with
  • matches or regex
  • less than, <
  • less than or equal, <=
  • greater than, >
  • greater than or equal, >=

Exists Conditions

Use exists when the condition should wait for a file or folder path.

$localPath exists
$folderPath\ready.txt exists
file exists "$folderPath\ready.txt"
folder exists "$folderPath"
process exists "notepad"

When the left side is not explicitly file, folder, or process, PDMShell treats the condition as a file exists check by default. If the value looks like a folder path, PDMShell evaluates it as a folder check.

Grouping Conditions

Use and, or, and parentheses to combine checks.

$folderPath\ready.pdf exists and $folderPath\ready.dxf exists

($folderPath\ready.pdf exists or $folderPath\ready.dxf exists) and "$(Description.@)" contains "Released"

Placeholders

The until command supports placeholders in conditions. The most commonly used placeholders are:

Placeholder Meaning
$localPath / $filePath Local path of the current file, or folder path when the context is a folder.
$folderPath / $directory Local path of the file folder or current folder.
$fileName / $filename / $name File name with extension.
$fileNameWithoutExtension File name without extension.
$extension File extension.
$id File or folder ID.
$version Current file version.
$revision Current file revision.
$folderName Folder name.
$folderID Folder ID.
$vaultName / $vaultname Vault name.
$vaultRootFolder / $vaultrootfolder Local path of the vault root folder.
$GUID / $guid Script or task GUID context when available.
$taskName Task name context when available.
$tempFolder / $TempFolder Windows temporary folder.
$machineName / $computerName Current machine name.
$userName / $username Logged-in PDM user name.
$username.firstName / $username.lastName PDM logged-in user's first and last name when available.
$username.FullName PDM logged-in user's full name when available.
$username.email PDM logged-in user's email address when available.
$windowsUser Windows user name.
$userDomain / $domain Windows user domain.
$configuration Current configuration context when available.
$value Current value context when available.
$completefilename Legacy complete file path placeholder.
$completefoldername Legacy complete folder path placeholder.

Date and time placeholders:

Placeholder Meaning
$yyyy / $year Four-digit year.
$yy Two-digit year.
$MM / $mm Two-digit month number.
$M Month number.
$dd Two-digit day of month.
$d Day of month.
$month Full month name.
$mon Short month name.
$day Full day name.
$dayShort Short day name.
$HH / $hh 24-hour hour.
$mi Minutes.
$ss Seconds.
$tt AM/PM designator.
$timestamp Timestamp in yyyyMMdd_HHmmss format.
$date Date in yyyy-MM-dd format.
$time Time in HH-mm-ss format.
Note

Placeholder names are evaluated case-insensitively in until conditions.

PDM Variables

Use $(VariableName.ConfigurationName) to read a PDM variable from the file context. Use .@ for the file @ tab. Folder variables can use $(VariableName) because folders do not use file configurations.

"$(Description.@)" contains "ECO"
"$(Revision.@)" equals "A"

For file data card variables, the .@ suffix is required when reading the file @ tab, for example $(Description.@). Bracketed text is literal and is not evaluated as a PDM variable.

When until waits on a PDM variable, PDMShell evaluates the variable each time the command checks the condition. This lets the condition detect a variable that changes while the command is waiting.

In the visual editor and in runscript, until -conditions is preserved until the until command runs. Target parameters such as -filePath "$localPath" are still resolved for the current file or folder.

Arithmetic Comparisons

Numeric expressions can be used on either side of a comparison.

1 + 3 greater than 3
2 * 5 equals 10
"$(Quantity.@)" greater than 0

Arithmetic is evaluated only for simple numeric expressions containing numbers, parentheses, and arithmetic operators.

Remarks

  • Use filePath when you need placeholders or PDM variables to be evaluated against one specific file.
  • Use search and match when the same condition should be evaluated across multiple matching files.
  • By default, a timeout stops the script and skips later workflow commands. Final cleanup commands such as dump and quit can still run.
  • Use onTimeout continue only when later script commands are safe to run even if the condition was not satisfied.
  • exists does not need a value in the visual editor.
  • For generated PDF/DXF workflows, use placeholders such as $folderPath, $fileNameWithoutExtension, and $extension to avoid hard-coded output paths.

Search results report

Add -csv "C:\Reports\results.csv" when using -search to save operation results. The first columns are file ID, parent folder ID, file name and output, followed by status and error details. The report folder must exist. New vault reports are added to PDM; existing vault reports must be checked out by you on this computer and remain checked out. External reports are replaced. See CSV operation reports for command-specific outcomes.