Table of Contents

whereused

Free

Use -parentScope, -parentFilter, and -depth to control the parents included in the CSV export.

Lists the files that reference a starting file. By default, whereused returns direct parents. Use -parentScope all for ancestors or -parentScope top for confirmed top-level parents.

Console folder paths are relative to the connected vault root. In the desktop console, paths are subdued and bracketed file IDs have a separate color for readability. CSV folder paths remain absolute.

Syntax

whereused (-filePath <path> | -search <query>) [-parentScope direct|all|top] [-parentFilter <query>] [-depth <number>] [-csv <path.csv>]

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
-filePath -f No Starting file; absolute or relative to the current vault folder. Mutually exclusive with -search.
-search -s No Finds starting files in the current folder. Use Recursive=true to include subfolders. Does not filter parents.
-parentScope No direct (default), all, or top.
-parentFilter No Standard PDMShell search query applied to returned parents. Defaults to searching the whole vault recursively.
-depth No Positive maximum number of parent levels for all/top; default 10. Direct scope always returns level 1.
-csv No Output report path. Omit it for console output only.
-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.

Starting files versus parent filters

-search selects the files to investigate. -parentFilter selects which of their parents appear in the console and CSV results.

whereused -search "Name=%.SLDPRT;Recursive=true" -parentFilter "Name=%.SLDASM" -csv "C:\Reports\direct-assemblies.csv"

This finds parts below the current folder and exports their direct assembly parents. Parent filters use search query syntax, including % wildcards, workflow/state, lock status, and data-card variable clauses. For example:

whereused -filePath "Bracket.SLDPRT" -parentScope all -parentFilter "Name=Machine%;StateName=Released"
whereused -filePath "Bracket.SLDPRT" -parentFilter "Name=%.SLDASM;WorkflowName=Engineering"
whereused -filePath "Bracket.SLDPRT" -parentFilter "Locked=true;LockedOnComputer=PC-01"

Explicit FolderID and Recursive tokens in -parentFilter override its whole-vault/recursive defaults. It also accepts the shared search engine's CSV-query input, such as -parentFilter "<C:\Reports\parent-queries.csv>"; those are input queries, not the output report. The same CSV-query limitations as -search apply. Unknown tokens are ignored by the shared parser, so check spelling.

Filtering does not stop traversal through a nonmatching intermediate parent. Reference lookup and filter searches do not check out or check in files; Edit is rejected. If the parent-filter search fails or reaches a license limit, export is aborted rather than silently using an incomplete filter set.

Direct, all, and top

For Part -> Subassembly -> Main assembly -> Drawing:

Scope Returned parents
direct Subassembly
all Subassembly, Main assembly, Drawing
top Drawing

Top means PDM reports no file parents, regardless of file extension, for references visible to the logged-in user. It does not mean the highest ancestor that matches -parentFilter. In this example, -parentScope top -parentFilter "Name=%.SLDASM" returns nothing: the drawing above the main assembly prevents it from being top-level.

whereused -filePath "C:\Vault\Parts\Bracket.SLDPRT"
whereused -filePath "C:\Vault\Parts\Bracket.SLDPRT" -parentScope all -depth 20
whereused -filePath "C:\Vault\Parts\Bracket.SLDPRT" -parentScope top -parentFilter "Name=%.SLDASM" -depth 30 -csv "C:\Reports\top-parents.csv"

Top results are unique per starting file/folder and parent file ID. If several paths reach the same top parent, the report keeps the first encountered path. A starting file with no parents does not return itself.

The traversal includes parents referencing older child versions, not just the child's current version. PDM returns the latest referencing version of each parent. See the PDM parent enumeration API.

CSV structure

Both whereused and whereusedtree use the same report:

RootFileID,RootFileName,RootFolderPath,ChildFileID,ChildFileName,ParentFileID,ParentFileName,ParentFolderPath,Level,Chain,Circular,IsTopLevel
101,Bracket.SLDPRT,C:\Vault\Parts,205,Subassembly.SLDASM,300,Machine.SLDASM,C:\Vault\Assemblies,2,Bracket.SLDPRT -> Subassembly.SLDASM -> Machine.SLDASM,False,True
Columns Meaning
RootFileID, RootFileName, RootFolderPath Starting file and its folder.
ChildFileID, ChildFileName Immediate child referenced by this row's parent; not necessarily the starting file.
ParentFileID, ParentFileName, ParentFolderPath Returned parent. Combine folder path and filename for its path.
Level Distance from the starting file; direct parents are level 1.
Chain Complete path of names from root to parent, including intermediates excluded by the filter.
Circular True if this edge revisits a file already in its chain; otherwise False.
IsTopLevel True for a confirmed parentless ancestor, False when it has parents/is circular, or blank when the parent list could not be verified.

CSV is UTF-8, with quoting for commas, quotes, and newlines. Empty results produce a header-only CSV.

Relative output paths resolve in the current vault folder. New CSVs in a vault folder are added to PDM. Existing vault reports must be checked out by the current user on this computer before being overwritten; the command does not check them out automatically. Use an existing folder outside the vault, such as C:\Reports, for a local-only export. Local output files can be overwritten.

Incomplete results and cancellation

  • A depth limit is not proof that a parent is top-level. The boundary parent is inspected; only a confirmed leaf can have IsTopLevel=True.
  • Cycles, unresolved parents, and reference-read failures mark the command incomplete. Other accessible branches and search roots continue.
  • A root search stopped by a license limit is also incomplete.
  • Requested CSV output can contain partial results after traversal/root-search failures. Error details are in the command log, not per-row error columns. Check the command result before treating the report as complete.
  • Cancellation stops cooperatively and does not export a CSV. Existing output is left unchanged.

For the recursive-by-default variant, see whereusedtree.

Edit this page