Oda's home folder and settings files

DataMind Oda keeps the settings it saves and the caches it builds on your computer inside one home folder. This page shows how Oda chooses that folder, how it shows the location, and what keeps a settings save safe.

How Oda chooses the home folder

Oda uses the first of these that is actually set:

1. A folder path chosen for the run.
2. The home folder named in the environment Oda starts in.
3. The default: a folder inside your user folder.

• Blank values do not count. A value that is empty, or only spaces, is ignored, and Oda falls through to the next choice.
• Caches live there too. The caches Oda builds as it works sit under the chosen folder as well.

How the folder is shown

• A short form. Oda writes the home folder in a short form such as ~/<folder>, where ~ stands for your user folder. A home you set yourself is shown by the name of the setting you used.
• Never the full path. The full path on your computer is not written into what Oda shows you, so a message you copy or share does not reveal your machine's layout.

What keeps a settings save safe

When Oda saves a settings file, it does not rewrite the file in place. It works in three steps:

1. It takes the lock. Oda creates a lock file beside the settings file. The lock file records the process that is writing, so a second save waits instead of writing at the same time. If another write holds the lock, Oda waits with pauses that grow, up to about two seconds by default, and then stops waiting instead of writing.
2. It writes beside the target. Oda writes the new content to a temporary file next to the settings file, then renames it over the target. Anyone reading at that moment sees the old file or the new one, never something written halfway.
3. It cleans up. Oda removes the lock when the save ends, and removes the temporary file if the save could not finish. A failed save leaves the settings file as it was.

Two more behaviours you may meet:

• Windows retries. On Windows, a brief sharing error, such as another program holding the file open for a moment, is retried before the save gives up.
• Links and permissions. If the path is a symbolic link, Oda replaces the link itself and leaves the file it points to alone. A replacement is created with the permissions Oda sets for settings files, so a file that had wider permissions is narrowed to them.

For what the settings file contains and when you may edit it, see The profile settings file.

When a save waits too long

If the wait for the lock runs out, the save does not happen, and Oda reports that it timed out waiting for the writer lock, naming the lock file's path. Try the change again. If it keeps failing, follow Updates and troubleshooting.

What a crash leaves behind

• The settings file stays whole. The switch to the new content is a single step, so after a crash the file holds the old content or the new one, never something half-written.
• The lock can survive. A crash can leave the lock file behind, and later saves then wait for it and time out. A stale lock is removed only after checking that no writer still owns it.

• One case it does not cover. The replacement is not flushed for a sudden power loss, so the very newest save can be lost that way.

Where start values come from

Oda reads its start values from three places, in order:

1. The environment Oda is launched with.
2. A settings file in the folder Oda is launched from.
3. A settings file in the home folder.

A value from a higher place wins over one from a lower place. Oda takes this snapshot once, when it starts, so a later folder change does not affect the run in front of you.

A settings file cannot make Oda treat a run as an SSH run. Oda decides that from the environment it was launched in, never from a settings file. See SSH remote execution. The full rules for these files, including the values a file may not set, are on Startup and diagnostics.

Questions, answered

Where is Oda's home folder?

By default it is a folder inside your user folder; it can also be chosen for the run or named in the environment Oda starts in. The settings files Oda saves and the caches it builds live under it. Oda shows the location in a short form, never the full path.

Can I move Oda's home folder?

Yes. Name the folder you want in the home setting of the environment you start Oda in, and Oda uses it the next time it starts. A blank or spaces-only value is ignored, so an empty setting moves nothing. The caches Oda builds live under the folder as well.

Why does Oda shorten folder paths when it shows them?

Oda writes the home folder in a short form such as ~/<folder>, where ~ stands for your user folder, and a home you set yourself is shown by the name of the setting you used. The full path on your computer is never written into what Oda shows you.

A save timed out waiting for the writer lock. What should I do?

Another save was in progress, or a crashed writer left its lock file behind. Try the change again. If it keeps failing, do not remove the lock file yourself; follow Updates and troubleshooting.

Can a settings file be left half-written?

No. Oda writes the new content to a temporary file beside the target and renames it over the target in a single step, so a reader sees the old file or the new one. A save that fails removes its temporary file and leaves the settings file as it was.

What happens if Oda or my computer crashes during a save?

The settings file holds the old content or the new one, never something half-written. The lock file can survive the crash, and later saves then wait for it and time out until it is removed. A sudden power loss is the one case Oda does not cover: the replacement is not flushed for it, so the very newest save can be lost.

How does Oda combine values from the environment and from settings files?

It reads them in order: the environment Oda is launched with, then a settings file in the folder you launch from, then a settings file in the home folder. A value from a higher place wins over one from a lower place.

Why did changing the folder I launch Oda from not change anything?

Oda takes its snapshot of these values when it starts, so a later folder change does not affect the run in front of you. Start Oda again from the new folder to use its values.

Can a settings file make Oda treat my run as an SSH run?

No. Oda treats a run as remote only when the environment it was launched in says so; a settings file cannot establish an SSH session. See SSH remote execution.