Skip to content

Maintain your server

Care and grooming of your Tatin server.

As packages accumulate on a registry, their configuration files can drift: tags diverge, variant spellings creep in, and conventions change. Maintenance is the process of correcting or updating those files programmatically, without touching the package ZIPs manually. Common tasks include standardising tags, removing meaningless ones, and adding new properties to existing packages.

Tatin automates this through maintenance jobs — APL function files placed in the Maintenance folder that the server detects and runs automatically.

Curate the tags

The most important maintenance job is to curate the tags.

Tags can be very useful for finding a package, but package authors may use different tags for the same thing, use legal but different spelling (UK versus US) or invalid spelling, or tags that make no sense, such as the group name or dyalog etc.

To be useful, tags need curating.

A package’s tags are defined in its configuration file. Merely changing the config file is enough: the server watches for such changes and adds the new config to the package ZIP, thus updating it.

Create and run maintenance jobs to correct problems in the package config files.

Maintenance jobs

The Maintenance Folder holds maintenance jobs in the form of APL function files (APLFs). The downloaded server includes some examples.

The purpose is to change packages managed by a Tatin server.

If a job crashes, the server

  1. reports it to the log file
  2. emails a report to the maintainer (see config)
  3. renames the file from *.aplf to *.crashed to stop it being run again

If the server finds APLFs in the Maintenance Folder during housekeeping, it loads and executes them.

Once executed, a file is renamed by adding an extension .executed, so it is not run again. That also documents what jobs were executed, and when.

For example, a file RemoveDyalogFromTags.aplf gets loaded into an unnamed namespace and called with

  • the package ID as the left argument
  • a two-element vector as the right argument:
  • The first element is the package configuration as a namespace
  • The second element is the path to the Registry

Once executed, the file is renamed to RemoveDyalogFromTags.aplf.executed.

Note that the user command ]Maintenance serves a different purpose: It can be used to adapt installed packages!

Update the server

Download the release ZIP from the Releases page into a temporary folder and unzip it.

Read the release note before doing anything else.

An update could require taking the server down for maintenance.

By default, a running Tatin server watches the workspace on disk and reloads it if it changes. This makes for an easy update if no other action is required.

The automatic update can be switched off in the INI file with [CONFIG]ReloadWS.

While reloading the workspace, the server returns error messages. Expect this to last 10 seconds or more, depending on the number of packages managed.

The INI file

The update might add or remove settings in the INI file: consult the release note.

If there are changes, follow instructions in the note.

Do not replace the INI file.

The server monitors the INI file for changes, and re-initialises if it finds them. Whether that works depends on the change: some settings are used at an early stage and cannot be changed later. Again, the release note will tell.

Assets

The release note describes what action to take, if any. Often the subfolder docs/ is to be replaced. (Contains the documentation.)

Maintenance folder

Never replace the Maintenance Folder

The folder maintenance/ documents changes made to the packages: you don’t want to lose this.

If the new folder is not empty, copy its contents over. Maintenance files can be used to carry out changes to all or some of the packages managed by the server, like adding a new property to the package config files of all packages.