Run-Time Applications and Components

Using Dyalog APL you may create different types of run-time applications and components. Note that the distribution of run-time applications and components requires a Dyalog APL Run-Time Agreement. Please contact Dyalog or your distributor, or see the Dyalog web page for more information.

For a list of the distributable components and their corresponding file names, for the different versions of Dyalog, see Files .

These components are referred to in hereafter by the name shown in the first column of the table. It is essential that you distribute the components that are appropriate for the Edition you are using.

Universal C Runtime DLLs

Under Windows, many of the Dyalog APL run-time components (.EXE and .DLL) are linked dynamically with the Microsoft Universal C Runtime library (the UCRT) which is supplied and installed as part of the normal Dyalog development installation.

At execution time it is important that the Dyalog runtime components bind with a version of the UCRT that is compatible with (i.e. the same as or newer than) the one with which they were built.

Windows 10

If the end-user of the Dyalog application is known to be running Windows 10, the Dyalog application will pick up the system-wide UCRT which is part of Windows 10. There is therefore no need to include the UCRT with a Dyalog run-time application.

Other Versions of Windows

The UCRT is not supplied with versions of Windows prior to Windows 10. On these platforms, it is therefore necessary to install the UCRT as part of the installation of the Dyalog run-time application. There are two ways to achieve this which are referred to herein as the VCRedist installation and App-local installation. Dyalog recommends the former.

VCRedist Installation (Recommended)

The VCRedist package, which includes the UCRT, is supplied with the Dyalog development package.

Simply copy the vc_redistx86.exe (32-bit version) or vc_redistx64.exe (64-bit version) program from the Dyalog development package into your own installation package and execute it as part of the installation of your Dyalog run-time application. This installs the UCRT into a shared Windows location; in effect the UCRT becomes part of the Windows system. The installation therefore requires Administrator privileges.

App-local Installation

An alternative is to install the UCRT components into the same directory as your Dyalog run-time application. There are two ways to obtain these files.

Either:

Install the Dyalog development package (ideally onto a separate system just for this purpose) without administrator rights. This will perform an App-local installation of Dyalog itself. Then copy the UCRT files into your installation package. These files are:

those beginning with api-ms*

ucrtbase.dll

vcruntime140.dll

Or:

Download and install the Windows 10 SDK from:
https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk, and follow the instructions in the link below.https://blogs.msdn.microsoft.com/vcblog/2015/03/03/introducing-the-universal-crt

Finally, modify your installer to add these files to the same folder as your Dyalog run-time application.

Stand-alone run-time

This is the simplest type of run-time to install. Using the File/Export menu item on the Session window, you can create a standard Windows executable program file (EXE) which contains your workspace and the Run-Time version of the Dyalog APL interpreter. To distribute your application, you need to supply and install:

your bound executable (EXE)
whatever additional files that may be required by your application

Start-up parameters may be specified on the application command line and are obtained by calling the GetCommandLine or GetCommandLineArgs methods. All command-line parameters will be ignored by the Dyalog engine unless they are preceded by the -apl option. Start-up parameters for the Dyalog engine may also be specified and bound with the EXE when you make it.

If your application uses any component of the Microsoft .NET Framework, you must distribute the Bridge DLL and DyalogNet DLLs. These DLLs must be placed in the same directory as your EXE.

Bound run-time

This option requires the separate installation of the Run-Time DLL, but compared with the stand-alone executable option, may save disk space and memory if your customer installs and runs several different Dyalog applications. Using the File/Export menu item on the Session window, you can create a standard Windows executable program file (EXE) which contains your workspace bound to the Run-Time DLL. To distribute your application, you need to supply and install:

your bound executable (EXE)
The Run-Time DLL

whatever additional files that may be required by your application

If your application uses any component of the Microsoft .NET Framework, you must distribute the Bridge DLL and DyalogNet DLLs. These DLLs must be placed in the same directory as your EXE.

Workspace based run-time

A workspace based run-time application consists of the Dyalog APL Run-Time Program (Run-Time EXE) and a separate workspace. To distribute your application, you need to supply and install:

your workspace
the Run-Time EXE
whatever additional files that may be required by your application

The command-line for your application invokes the Run-Time EXE, passing it start-up parameters required for the Run-Time EXE itself (such as MAXWS) and any start-up parameters that may be required by your application. You will need to associate your own icon with your application during its installation.

If your application uses any component of the Microsoft .NET Framework, you must distribute the Bridge DLL and DyalogNet DLLs. These DLLs must be placed in the same directory as your EXE.

Out-of-process COM Server

To make an out-of-process COM Server, you must:

establish one or more OLEServer namespaces in your workspace, populated with functions and variables that you wish to export as methods, properties and events.
use the File/Export … menu item on the Session window to register the COM Server on your computer so that it is ready for use.

The command-line for your COM Server invokes the Run-Time EXE, passing it the start-up parameters required for the Run-Time EXE itself (such as MAXWS) and any start-up parameters that may be required by your application.

To distribute an out-of-process COM Server, you need to supply and install the following files:

your workspace
the associated Type Library (.tlb) file (created by File/Export)
the Run-Time EXE
whatever additional files that may be required by your application

To install an out-of-process COM Server you must set up the appropriate Windows registry entries. See Interface Guide for details.

In-process COM Server

To make an in-process COM Server, you must:

establish one or more OLEServer namespaces in your workspace, populated with functions and variables that you wish to export as methods, properties and events.
use the File/Export … menu item on the Session window to create an in-process COM Server (DLL) which contains your workspace bound to the Run-Time DLL. This operation also registers the COM Server on your computer so that it is ready for use.

To distribute your component, you need to supply and install

Your COM Server file (DLL)

the Run-Time DLL
whatever additional files that may be required by your COM Server.

Note that you must register your COM Server on the target computer using the regsvr32.exe utility.

ActiveX Control

To make an ActiveX Control, you must:

establish an ActiveXControl namespace in your workspace, populated with functions and variables that you wish to export as methods, properties and events.
use the File/Export … menu item on the Session window to create an ActiveX Control file (OCX) which contains your workspace bound to the Run-Time DLL. This operation also registers the ActiveX Control on your computer so that it is ready for use.

To distribute your component, you need to supply and install

Your ActiveX Control file (OCX)

the Run-Time DLL
whatever additional files that may be required by your ActiveX Control.

Note that you must register your ActiveX Control on the target computer using the regsvr32.exe utility.

Microsoft .NET Assembly

A Microsoft .NET Assembly contains one or more .NET Classes. To make a Microsoft .NET Assembly, you must:

establish one or more NetType namespaces in your workspace, populated with functions and variables that you wish to export as methods, properties and events.
use the File/Export … menu item on the Session window to create a Microsoft .NET Assembly (DLL) which contains your workspace bound to the Run-Time DLL.

To distribute your .NET Classes, you need to supply and install

your Assembly file (DLL)
the Run-Time DLL
the Bridge DLL
the DyalogNet DLL
whatever additional files that may be required by your .NET Assembly.

All the DLLs and subsidiary files must be installed in the same directory as the .NET Assembly.

Additional Files for Syncfusion

Under a licensing agreement with Syncfusion, Dyalog includes the Syncfusion library of WPF controls. These may be used by Dyalog APL users to develop applications, and may be distributed with Dyalog APL run-time applications.

The Syncfusion libraries comprise a set of .NET assemblies which are supplied in the Syncfusion/4.5 sub-directory of the main Dyalog APL installation directory (for example: c:\Program Files\Dyalog\Dyalog APL-64 14.0 Unicode\Syncfusion\4.5.

If you use any of the Syncfusion controls in your runtime application, you must include the Syncfusion library.

Accessing your Application Using RIDE

If you wish to access your run-time application remotely using the RIDE, you must put a copy of the appropriate Conga DLLs (see Files) in the same directory as your .EXE or workspace. This is different from previous versions of Dyalog which had separate RIDE DLLs.

Additional Files for SQAPL

If your application uses the SQAPL/EL ODBC interface, you must distribute and install four additional components.

SQAPL INI
SQAPL ERR
SQAPL DLL
APLUNICD INI

For the names of the files corresponding to these components, see Files.

The SQAPL DLL must be installed in the user's Windows directory or be on the user's path.

Miscellaneous Other Files

DyaRes DLL

If your run-time application uses any of the bitmaps or other GUI resources that are built into the Dyalog Session, you must include the DyaRes DLL with your application.

AUXILIARY PROCESSORS

If you use any of the Auxiliary Processors (APs) included in the sub-directory xutils, you must include these with your application. Note that, like workspaces, Dyalog APL searches for APs using the WSPATH parameter. If your application uses APs, you must ensure that you specify WSPATH or that the default WSPATH is adequate for your application..

DYALOG32 and/or DYALOG64

This DLL is used by some of the functions provided in the QUADNA.DWS workspace. If you include any of these in your application this DLL must be installed in the user's Windows directory or be on the user's path.

Registry Entries for Run-Time Applications

The Run-Time DLL does not obtain any parameter values from the Windows registry. If you need to specify any Dyalog APL parameter values, they must be defined in the command line when you create an EXE.

The Run-Time EXE does obtain parameter values for the Windows registry, but does not require them to be present. If the default values of certain parameters are inappropriate, you may specify their values on the command line. There is normally no requirement to install registry entries for a run-time application that uses the Run-Time EXE.

For example, your application may require a greater or lesser maxws parameter (workspace size) than the default value. This may be done by adding the phrase MAXWS=nnnn (where nnnn is the required workspace size) after the name of your application workspace on the command line, for example:

      dyalogrt.exe MYAPP.DWS MAXWS=200M

Note that the default value of the DYALOG parameter (which specifies where it looks for various other files and sub-directories) is the directory from which the application (dyalogrt.exe) is loaded.

Nevertheless, registry entries will be required in the following circumstances.

If your Classic Edition run-time application requires that the user inputs APL characters, you will need to specify input/output tables (parameters APLK, APLT, APLKEYS and APLTRANS).

Installing Registry Entries

To specify parameters using the Registry, you must install a suitable registry folder for each user of your application. By default, Version 17.1 will use registry folders similar to:

HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 17.1 Unicode

HKEY_LOCAL_MACHINE\SOFTWARE\Dyalog\Dyalog APL/W-64 17.1

You may choose a different name for your registry folder if you wish. If so, you must tell Dyalog APL the name of this folder by specifying the INIFILE parameter on the command line. For example:

dyalogrt.exe myapp.dws INIFILE=Software\MyCo\MyApplication

You may install entries into the registry folder in one of two ways:

Using a proprietary installation program such as InstallShield
Using the REGEDIT utility. This utility program installs registry entries defined in a text file that is specified as the argument to the program. For example, if your file is called APLAPP.REG, you would install it on your user's system by executing the command:

REGEDIT APLAPP.REG
An example 5-line file that specifies the APLNID and MAXWS parameters might be as follows:
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 17.1]
"aplnid"="42"
"maxws"="8096"