# Administration Engine (Engine `adm`)

In the engine `adm` are functions for managing system files and some configuration tasks on the server implemented.
This engine is implemented directly by the kernel.

## Server Groups & Servers

* [adm.EnumServerGroups](adm.md#adm.EnumServerGroups)
* [adm.EnumServers](adm.md#adm.EnumServers)
* [adm.GetServerFamilyInfo](adm.md#adm.GetServerFamilyInfo)
* [adm.GetServersActivity](adm.md#adm.GetServersActivity)

## System Files

* [adm.GetSystemFile](adm.md#adm.GetSystemFile)
* [adm.StoreSystemFile](adm.md#adm.StoreSystemFile)

## Configuration Files

* [adm.CleanUpConfig](adm.md#adm.CleanUpConfig)

## Log Management

* [adm.LogdirGetInfo](adm.md#adm.LogdirGetInfo)
* [adm.LogdirDownloadFiles](adm.md#adm.LogdirDownloadFiles)
* [adm.LogdirDeleteFiles](adm.md#adm.LogdirDeleteFiles)
* [adm.CleanUpLog](adm.md#adm.CleanUpLog)

## Events

* [adm.ServerEventsRefresh](adm.md#adm.ServerEventsRefresh)

## Undocumented Endpoints

The following jobs are offered by the enaio® server but are not currently described in this documentation:

Logging::
`adm.ChangeLogFileMask`, `adm.SetLogChannelParams`

Client-side log directory::
`adm.ClientLogdirDownloadFiles`, `adm.ClientLogdirGetInfo`

Resource locking::
`adm.ResourceGetState`, `adm.ResourceLock`, `adm.ResourceUnlock`

Server events::
`adm.ServerEventsEnumJobs`

<a id="adm.CleanUpConfig"></a>

## adm.CleanUpConfig

This job searches for the specified configuration file and clears it.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |
| `Types` | INT | Yes | Type of the configuration file (bitmask): +<br>`0x00000001 (1)` = object definition file +<br>`0x00000002 (2)` = AS.cfg +<br>`0x00000004 (4)` = AsListen.dat +<br>`0x00000008 (8)` = AsImpExp.Cfg +<br>`0x00000010 (16)` = AsForm.Cfg +<br>`0x00000020 (32)` = AsCold.Cfg +<br>`0xFFFFFFFF (4294967295)` = all found |
| `Versions` | INT | Yes | Version of the file |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="adm.CleanUpLog"></a>

## adm.CleanUpLog

This job searches for the specified log files and removes them.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |
| `Type` | INT | Yes | Type of log files to be deleted (bitmask): +<br>`0x00000001 (1)` = FLW files +<br>`0x00000002 (2)` = ERR files +<br>`0x00000004 (4)` = LOG files +<br>`0x00000008 (8)` = REP files +<br>`0xFFFFFFFF (4294967295)` = all found |
| `Days` | INT | Yes | Maximum age of files to be deleted in days |
| `Path` | STRING | Yes | Path of the log directory |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="adm.EnumServerGroups"></a>

## adm.EnumServerGroups

This job returns a list of all server groups.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `0` = return value is `Group[00..nn]` +<br>`1` = return values are `Info` and `InfoType` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `[Info]` | STRING | Optional | MIME-encoded buffer with information about the server group (only when `Flags=1`) |
| `[InfoType]` | STRING | Optional | Semicolon-separated names of values returned in `Info` (only when `Flags=1`) |
| `[Group[00..nn]]` | STRING | Optional | Semicolon-separated information about the server group (only when `Flags=0`): +<br>ID of the server group; name of the server group; description of the server group |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="adm.EnumServers"></a>

## adm.EnumServers

This job returns all servers of a server group.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | `0` = return value is `Server[00..nn]` +<br>`1` = return values are `Info` and `InfoType` |
| `[GroupID]` | INT | No | ID of the server group |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `[Info]` | STRING | Optional | MIME-encoded buffer with information about the server group (only when `Flags=1`) |
| `[InfoType]` | STRING | Optional | Semicolon-separated names of values returned in `Info` (only when `Flags=1`) |
| `[Server[00..nn]]` | STRING | Optional | Semicolon-separated information about the server (only when `Flags=0`): +<br>ID of the server; name of the server; IP address; port; service name |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="adm.GetServerFamilyInfo"></a>

## adm.GetServerFamilyInfo

This job returns the ID and name of the server family.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `GUID` | STRING | — | ID of the server family |
| `Name` | STRING | — | Name of the server family |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="adm.GetServersActivity"></a>

## adm.GetServersActivity

This job returns the IDs of all servers and their corresponding status.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Server[00..nn]` | STRING | — | Semicolon-separated information about the server: +<br>ID of the server; status of the server (`1` = server running; `2` = server crashed) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="adm.GetSystemFile"></a>

## adm.GetSystemFile

The job passes the system file (e.g. `as.cfg`) to the client and locks it.
System files are in the DB table `osresources` with `resourcetype=1`.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Controls opening mode and timestamp return: +<br>`LOWORD(Flags) = 0` = system file is opened for reading +<br>`LOWORD(Flags) = 2` = system file is opened for writing +<br>If `Version != 0` or `HIWORD(Flags) != 0` or `LOWORD(Flags) != 2`: +<br>{nbsp}{nbsp}`HIWORD(Flags) = 1` → `LowDateTime` and `HighDateTime` are returned +<br>{nbsp}{nbsp}`HIWORD(Flags) = 2` → only `LowDateTime` is returned |
| `FileName` | STRING | Yes | Name of the system file |
| `Version` | INT | Yes | Version of the system file to be requested |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `[FileCount]` | INT | Optional | Number of returned files (always `1`) |
| `[LowDateTime]` | INT | Optional | Timestamp in LowDateTime format |
| `[HighDateTime]` | INT | Optional | Timestamp in HighDateTime format |

### Output Files

| Name | Description |
|---|---|
| `[File list]` | Name and path of the system file |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

See also: [adm.StoreSystemFile](adm.md#adm.StoreSystemFile)

<a id="adm.LogdirDeleteFiles"></a>

## adm.LogdirDeleteFiles

This job deletes the specified files from the server's log directory.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |
| `Files` | STRING | Yes | File names separated by `?` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Deleted` | INT | — | Number of successfully deleted files |
| `Failed` | INT | — | Number of files that could not be deleted |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

See also: [adm.LogdirGetInfo](adm.md#adm.LogdirGetInfo)

<a id="adm.LogdirDownloadFiles"></a>

## adm.LogdirDownloadFiles

This job returns the specified files from the server's log directory.
The files are returned packed.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |
| `Files` | STRING | Yes | File names separated by `?` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Files` | STRING | — | Names of the returned files |

### Output Files

| Name | Description |
|---|---|
| `File list` | Name and path of the packed file (contains all requested files) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

See also: [adm.LogdirGetInfo](adm.md#adm.LogdirGetInfo)

<a id="adm.LogdirGetInfo"></a>

## adm.LogdirGetInfo

This job returns a list of all files from the server's log directory.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `FileInformation[00000000..nnn...nnn]` | STRING | — | File information separated by `?` per file: +<br>Filename; file size in bytes; timestamp of last change |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

See also: [adm.LogdirDownloadFiles](adm.md#adm.LogdirDownloadFiles)

<a id="adm.ServerEventsRefresh"></a>

## adm.ServerEventsRefresh

Reloads the server-side OS events in the server engine so that modified or newly created events become active without restarting the server.

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

<a id="adm.StoreSystemFile"></a>

## adm.StoreSystemFile

This job saves the system file received from the client.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Controls save behavior and timestamp format: +<br>`LOWORD(Flags) = 0` = save system file and write history file +<br>`LOWORD(Flags) = 1` = unlock the file +<br>`HIWORD(Flags) = 2` = save timestamp only in LowDateTime format; otherwise both formats (LowDateTime + HighDateTime) |
| `FileName` | STRING | Yes | Name of the system file |
| `LowDateTime` | INT | Yes | Timestamp in LowDateTime format |
| `HighDateTime` | INT | Yes | Timestamp in HighDateTime format |

### Input Files

| Name | Description |
|---|---|
| `File list` | Name and path of the system file to be saved |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code.

See also: [adm.GetSystemFile](adm.md#adm.GetSystemFile)