User Commands - where should they go?

Overview

By default Dyalog is looking for User Commands in a sub folder Salt\Spice within the Dyalog installation folder. Therefore the easiest way to get your own User Commands recognized by Dyalog is to put put them into that directory.

Easy may it be but it also has a couple of serious disadvantages: messing up Dyalog user commands with your own user commands is not a good idea because ...

Dyalog might introduce a new user command with a name already used by you.
When a new version of Dyalog arrives you are in trouble
You need admin rights to add, change or delete files in Salt/Spice

It's certainly a much better idea to keep Dyalog's user commands separate from your own ones.

Solution

For all versions of Dyalog and all user accounts

To separate your own user commands from the Dyalog user commands is not too difficult.

For this you need a folder that hosts all your user commands. Of course that folder can have any name you like but in this document we refer to this folder as C:\MyUserCommands.

Create the folder C:\MyUserCommands.
Add that folder to the SALT search path:
1. Call "Configuration" from the "Options" menu.
2. Activate the "User Commands" tab.
3. Press the "Browse" button and browse to C:\MyUserCommands.
4. Press the "Add" button.
5. Press "OK"

Note that the forth step can be easily forgotten.

Now either restart Dyalog or execute the user command ]ureset.

For all versions of Dyalog but a specific user account (Windows)

Since this page was created Dyalog has invented a general mechanism that allows you to save any user command in a certain place because all versions of Dyalog supported at the time of writing (May 2019: 15.0 and better) scan a folder MyUCMDs which is located under %USERPROFILE%\Documents\MyUCMDs in Windows and ~ (home directory) in Linux and Mac OS.

A script file with the name setup.dyalog in this folder will be executed as part of the start-up procedure of any version of Dyalog, but any other script will be considered a user command script.

Complex User Commands

If the code which is the "real thing" is small it can and probably will go into the script which is defining the User Command as such. If it is a big thing (like ADOC) or a complete application (like Fire) than it will reside in a workspace.

That workspace can be saved along with the user command itself. Within your user command you should not use a real path to copy what it needed from that workspace. Instead you can find out what the path is by checking ##.SourceFile: that gives you the fully qualified name of the user command.

This will give you the folder name that hosts the current user command:

{⎕IO←1 ⋄ ⍵↓⍨-⌊/'\/'⍳⍨⌽⍵} ##.SourceFile

Scripts

Sometimes a user command will not contain all the code itself but use one or more scripts to perform a certain task.

Note that you cannot save such files with the extension dyalog within the folder that hosts user commands because Dyalog assumes that everything that is saved in such a file is a user command.

The solution to the problem is to give the script(s) a different extension. For example code would be just fine. You can still load such a script with the SALT commands; you just have to specify the extension explicitly.

Author: -- KaiJaeger 2015-04-04 08:50:51

Last update: 2019-05-30.