ACMSDI Gateway Version 5.5-0Q

ACMS (Application Control and Management System) is a powerful and sophisticated transaction processing monitor software system for OpenVMS that was originally developed by Digital Equipment Corporation in the early 1980s and remains popular with many large OpenVMS users to this day, most of whom rely on it to run key business-critical applications. Traditional methods of interacting with ACMS-based applications are via green-screen user interfaces (typically TDMS or DECforms) or using the TPware family of products to facilitate remote access to ACMS applications in a client-server fashion. However, TPware has to date only been available for the Windows platform. TPware has also not been updated for many years, and it cannot be used safely by modern multi-threaded Windows applications. For many ACMS users this lack of good integration options can be a serious issue as it becomes increasingly necessary for these business-critical ACMS applications to interact with non-OpenVMS application environments across the enterprise in an efficient manner.

To help ACMS customers address these challenges and to allow customers to get the most out of their legacy ACMS-based applications, VMS Software Inc. (VSI) has recently updated the original TPware and ACMSDI gateway products to provide new and improved facilities for interacting with ACMS applications in a secure and reliable fashion from multiple client operating systems using modern programming languages such as C, Java, Python, C#, PHP, and Lua. This document briefly describes these updates and provides simple examples of how the new and updated features can be used. The updated software is freely available to all ACMS customers, and VMS Software Inc. can provide services to help customers make the best possible use of the updated ACMSDI software package?.

It is assumed that the reader is familiar with OpenVMS, ACMS, and TPware. It is also assumed that the reader is familiar with developing applications in C/C++ on OpenVMS, Microsoft Windows, or Linux or has some familiarity with the other programming languages mentioned above.

The current release of ACMSDI gateway introduces the following new features, enhancements, and bug fixes.

Detection and Reporting of Expired Passwords

Previous versions of the ACMSDI gateway did not detect and report expired OpenVMS user passwords correctly in certain circumstances, such as when the user password was pre-expired. This issue has been resolved.

SSL/TLS Bug Fixes and Enhancements

Enhanced logging of various events

New Ping Function

The client API now includes the new ping function acmsdi_ping() that can be used by client applications to verify gateway connectivity and as a heartbeat to prevent network components from dropping client connections during extended periods of client inactivity. This function accepts two arguments – the first one is a pointer to a submitter ID returned by acmsdi_sign_in(), and the second one may be either NULL or a pointer to a byte array that is at least 4 bytes in length. If the second parameter is not NULL, acmsdi_ping() will copy the 4-byte response message received from the ACMSDI gateway (that should contain the letters PONG) into the supply array. If the return status of acmsdi_ping() is any value other than 0, it should be assumed that an error has occurred and there is a problem with the gateway connection. The example programs "ping01.c" and "ping02.c" included in the kits illustrate using the new ping function in conjunction with an OpenVMS timer (ping02.c) and with UNIX-style alarms (ping01.c).

It is also possible to call the function from a separate thread, however care should be taken to ensure that calls to the ping function do not overlap with task calls being executed on another thread. Note that the ping function can only be used in blocking mode.

New Logical Name to Specify Location of Log Files

The logical name ACMSDI$LOGDIR can be used to specify the location (directory) where gateway log files will be written. This logical name may be defined at any level that is visible when starting the gateway using ACMSDI$STARTUP.COM or when using the management CLI, however it would typically be defined at the system level. The logical name must translate to a valid directory specification and gateway processes must have write access to the directory in question. It is also possible to specify the location of log files using the /LOGDIR qualifier when starting gateway instances using the management CLI (see example below) and specifying the log file location in this way takes precedence over a location specified by the ACMSDI$LOGDIR logical name. As noted previously, for gateway instances started using the management CLI, log file names include the OpenVMS node name and the port number used by the gateway instance.

Enhanced Handling of TCP/IP Keepalive

Handling of TCP/IP keepalive functionality has been enhanced in both gateway and client to ensure prompt detection of failed connections and to reduce the chances of connections being dropped due to inactivity.

Support for SHOW VERSION Command

The ACMSDI.EXE CLI utility now supports a SHOW VERSION command that can be used to show the version number and build date/time of the gateway.

The list below summarises the new and updated features that were introduced in the previous versions of the new VSI ACMSDI package, starting with version 5.5-0A.

Removal of DECnet and AppleTalk Protocols

The TPware and ACMSDI gateway code historically supported multiple network communications protocols, including TCP/IP, DECnet, and AppleTalk. The AppleTalk protocol was discontinued over a decade ago, and DECnet, even though it is still used by many OpenVMS users for communications between OpenVMS systems, is no longer used for interactions between OpenVMS and other operating systems. For these reasons, the support for both protocols has been removed from TPware and ACMSDI gateway, and the only supported network protocol now is TCP/IP.

Changes to ACMSDI Gateway Logging

The ACMSDI gateway process historically logged operational and error messages to the ACMS SWLUP facility via the SWLUP mailbox. However, due to the manner in which this logging interface was implemented, there was a definite risk that under a heavy operational load, the gateway process would hang in a RWAST state after attempting to log a large number of messages within a very short time period. To avoid this situation, the logging mechanism has been changed to log all operational and error messages to a gateway log file. Logged messages are timestamped to allow them to be correlated with other events that may have occurred on the OpenVMS system or on client systems during the same period. Client connection and identification details (such as usernames and client host details) are also included in logged messages where possible. When starting gateway instances, it is possible (via either the ACMSDI CLI utility or using the ACMSDI$LOGDIR logical name) to specify the location of these log files.

32-bit and 64-bit Windows DLLs

Previous versions of the ACMSDI Windows client DLL were 32-bit only (used 32-bit pointers) and could not be used with some modern 64-bit-only programming language environments. The new ACMSDI kit for Windows includes both 32-bit and 64-bit versions of the client DLL. Windows client applications must be linked with the appropriate version of the ACMSDI client DLL. The DLL must be installed on all systems that will run client applications and must be found in the application PATH.

Support for SSL/TLS

The updated ACMSDI software includes optional support for SSL/TLS encryption of all network traffic. Previous versions of the software provided only a very basic algorithm for encrypting messages, which is not considered secure by modern standards. Support for SSL/TLS is provided via OpenSSL and allows the software to take full advantage of the latest ciphers and encryption standards. Both 32-bit and 64-bit versions of the OpenSSL libraries are included with the ACMSDI for Windows kit. Note that these libraries must be installed along with the appropriate ACMSDI DLL (32-bit or 64-bit) on all Windows client systems that will use the ACMSDI interface.

Support for Multiple Connections

Previous versions of the ACMSDI client API did not permit the creation of multiple connections to the same ACMSDI gateway but would instead multiplex a single connection to support multiple sessions. Thus, each session would equate to a separate connection by the gateway to ACMS, but all TCP/IP network traffic for every such session would utilize the same common TCP/IP connection. This approach has some merit and was presumably taken to help conserve network resources when the software was originally developed; however, this is much less of a concern today, and having the ability to create and use multiple connections to the gateway can provide significant advantages in certain situations (particularly for multi-threaded applications in which it can often be desirable for each thread to have its own distinct connection).

The maximum number of concurrent connections that an instance of the ACMSDI gateway will allow can be specified by defining the logical name ACMSDI$MAX_CONN to the desired value or by using the -c command line option? for ACMSDI$GATEWAY.EXE. ACMSDI$MAX_CONN can be defined at any level visible to the ACMSDI gateway process instance but is typically defined at either the system or the process level. The supplied value for the maximum number of concurrent connections must be between 200 and 400. If the specified value is outside this range, it will be adjusted as appropriate to one or the other of these two values.

Support for Linux and HP-UX

In addition to providing 32-bit and 64-bit client support for Windows, a client kit is also provided for Linux and HP-UX (IA-64) that can be used to develop Linux-based and HP-UX-based client applications in a variety of programming languages that can call into ACMS applications. On Linux, C/C++, Java, PHP, and Python are currently supported. On HP-UX, only C/C++ is currently supported.

Alternative Language Bindings

In addition to C/C++, the updated software also provides the facilities for the development of client applications in Java, Python, PHP, Lua, and C#. Support for these languages is provided via SWIG (http://www.swig.org/) and a new tool (Twiddle) that generates a SWIG-compliant interface definition for the ACMS application from a supplied STDL file for the programming language of choice?. The generated interface is linked with ACMSDI client library to facilitate communication with the ACMSDI gateway and exchange data with the target ACMS application.

Interface Code Generation Facilities

As mentioned above, the updated ACMSDI client kit includes code generation facilities to generate client interfaces for a variety of programming languages based on a supplied STDL input file, which completely defines the ACMS application in terms of the tasks and workspaces. The supplied STDL file is parsed by the Twiddle tool to generate a SWIG-compliant interface that can then be compiled and linked with the ACMSDI client library and client language runtime.

It is not uncommon for ACMS applications to implement large numbers of tasks and use many different workspaces. If you do not wish to generate interface code for all ACMS tasks and workspaces, you can edit the STDL file to include only those tasks and workspaces that are specifically required.

PCSI Installation Kit

The ACMSDI gateway software is now provided as an easily installed PCSI kit, bringing it in line with most other OpenVMS software kits provided by VMS Software, Inc. The kit includes the ACMSDI gateway software, client API, example client code for various programming languages, and a simple example ACMS application that can be used in conjunction with the example client programs.

Generic Microsoft .NET Wrapper

The ACMSDI client kit also includes a generic .NET wrapper that provides direct access from .NET application code to the core ACMSDI client API (acmsdi-x64.dll). The wrapper (provided by the two 64-bit DLLs TpwareClient.DLL and TPware.DLL) provides a .NET class library that can be called from any C# or Visual Basic .NET application.

Support for External Authentication (via ACME LDAP)

The ACMSDI gateway can optionally authenticate users via ACME LDAP, using the supplied LDAP credentials for user authentication at the OpenVMS level, and the local username determined from the ACME LDAP mapping file for at ACMS level.

Management CLI

The ACMSDI OpenVMS kit includes a simple command line utility (ACMSDI.EXE) that can be used to start, stop, and list ACMSDI gateway instances (started on different TCP/IP ports), as well as to view various metrics (user connection details, number of concurrent connections, number of successful and failed logins, and so on). The command line utility can be found in the directory ACMS$ROOT:[BIN] and can be run only by suitably privileged accounts, such as SYSTEM. A detailed description of the utility and the functions it provides can be found in the Help section of the utility (which can be accessed via the HELP command).

Aside from being useful when performing general gateway administrative and monitoring functions, a common use of the CLI utility is to implement customised startup and shutdown procedures to start and stop multiple ACMSDI gateway instances, as described elsewhere in this document.

This section briefly describes the installation of the updated ACMSDI gateway and client API software on OpenVMS, Microsoft Windows, and Ubuntu Linux. As noted previously, the OpenVMS installation has been updated to be a PCSI kit. The Windows kit is provided as a standard Windows MSI installer package. The Linux kit is provided as a compressed tar file that can be unpacked and installed locally (single user) or system-wide.

The ACMSDI client kits for Linux and Windows are bundled with the OpenVMS ACMSDI kit and can be found after the installation in the ACMSDI$ROOT:[KITS] directory. These kits can be copied via SFTP or otherwise to Windows and Linux systems and installed as described below.

$ PRODUCT INSTALL ACMSDI

Performing product kit validation of signed kits ...

The following product has been selected:
    VSI I64VMS ACMSDI V5.5-0Q              Layered Product

Do you want to continue? [YES]

Configuration phase starting ...

You will be asked to choose options, if any, for each selected product and
for any products that may be installed to satisfy software dependency
requirements.

Configuring VSI I64VMS ACMSDI V5.5-0Q: ACMSDI gateway for OpenVMS

    © Copyright 2025 VMS Software Inc.

    VSI Software Inc.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
    VSI I64VMS ACMSDI V5.5-0Q              DISK$I64SYS:[VMS$COMMON.]

Portion done: 0%...10%...50%...90%...100%

The following product has been installed:
    VSI I64VMS ACMSDI V5.5-0Q              Layered Product

VSI I64VMS ACMSDI V5.5-0Q: ACMSDI gateway for OpenVMS

    Post-installation tasks are required.

    To start the ACMSDI gateway at system boot time, add the
    following lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

        $ file := SYS$STARTUP:ACMSDI$STARTUP.COM
        $ if f$search("''file'") .nes. "" then @'file'

    To shutdown the ACMSDI gateway at system shutdown, add the
    following lines to SYS$MANAGER:SYSHUTDWN.COM:

        $ file := SYS$STARTUP:ACMSDI$SHUTDOWN.COM
        $ if f$search("''file'") .nes. "" then @'file'

Maxjobs:         0  Fillm:       256  Bytlm:       128000
Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0
Maxdetach:       0  BIOlm:       150  JTquota:       4096
Prclm:          50  DIOlm:       150  WSdef:         4096
Prio:            4  ASTlm:       300  WSquo:         8192
Queprio:         4  TQElm:       100  WSextent:     16384
CPU:        (none)  Enqlm:      4000  Pgflquo:     256000

The ACMSDI gateway and client software enables TCP/IP keepalives for all connections. As of version ACMSDI V5.5-0P, it is possible to control the behaviour of these keepalive settings with regard to how quickly the gateway and client will initiate keepalive checking to detect stale connections and (perhaps more importantly) to help prevent inactivity from disconnecting the channel. For example, it can be a common issue for applications running behind a NAT proxy or a firewall to be disconnected without a reason. This behaviour is often caused by the connection tracking procedures implemented in proxies and firewalls, which keep track of all connections that pass through them. Because of the physical limits of these systems, they can only keep a finite number of connections in their memory. The most common and logical policy is to keep newest connections and to discard old and seemingly inactive connections first.

By default, the ACMSDI gateway and client will start to check connections after 300 seconds (5 minutes), however this threshold can be controlled via the logical name ACMSDI$TCP_KEEPIDLE on OpenVMS or the environment variable ACMSDI_KEEP_IDLE on Windows and Linux/UNIX, with the specified value being an integer in the range from 120 to 7200, representing the number of seconds before the first keepalive probe is issued. From an OpenVMS perspective, the logical name may be defined at any level, however it will typically need to be defined the system level.

Support for end-to-end SSL/TLS encryption of all network traffic between client applications and the OpenVMS-based ACMSDI gateway process is provided by OpenSSL. The use of SSL/TLS encryption is optional and is enabled on the gateway by the definition of the logical name ACMSDI$SSL_ENABLE and logical names that specify the location of key and certificate files and whether client certificates are to be verified or not. C client support for SSL/TLS encryption is provided via the new options that can be specified when calling acmsdi_sign_in() to connect to the ACMSDI gateway; for other client languages, the new methods are provided to specify key and certificate file details and to connect to the gateway via SSL/TLS. For details, see the section called “Logical Names”, the section called “New C Client Options”, and the section called “Other Client Languages” below.

Logical Names

New C Client Options

The following table lists the new client option codes that can be used in C/C++ client code to enable SSL/TLS encryption for all communication with the ADMSDI gateway and to specify the locations of client certificate and key files. It should be noted that the specification of client certificate and key files is optional and is only required if the ADMSDI gateway has been configured to verify client certificates.

The following code fragment illustrates the use of these new option codes to enable encryption and to specify values for the locations of the key and certificate files, using the new structures (ssl, ssl_cert, and ssl_key) that have been added to the ACMSDI_OPTION union to support the new SSL/TLS options. As noted previously, the specification of key and certificate files is only required if the ACMSDI gateway has been configured to verify client certificates.

ACMSDI_OPTION opts[4];

opts[0].ssl.option = ACMSDI_OPT_SSL_ENABLE;
opts[0].ssl.enable = 1;

opts[1].ssl_cert.option = ACMSDI_OPT_SSL_CERT;
opts[1].ssl_cert.path = "../cert.crt";
opts[2].ssl_key.option = ACMSDI_OPT_SSL_KEY;
opts[2].ssl_key.path = "../cert.key";

opts[3].option = ACMSDI_OPT_END_LIST;

Other Client Languages

For other programming languages, the methods acmsSetSslCert() and acmsSignInSSL() are provided in the client interface code generated by the Twiddle utility. The acmsSetSslCert() method allows developers to specify client key and certificate details, and the acmsSignInSSL() method can then subsequently be used to connect to the ACMSDI gateway using SSL/TLS encryption.

The following code fragment illustrates the use of these two methods with the Lua programming language:

emp = require("emp")

emp.acmsSetSslCert("../cert.crt", "../cert.key")
h = emp.acmsSignInSSL("BIGGLES", "BIGGLES1234", "10.10.100.11")

if h == -1 then
   print("Could not login to ACMS")
   os.exit()
end

As noted in the introduction, the ACMSDI gateway can be configured to authenticate users via ACME LDAP, such that the supplied LDAP username/password credentials are used for authentication at the OpenVMS level, and access to ACMS uses the corresponding local OpenVMS username determined from the ACME LDAP username mapping file, which will be loaded by ACMSDI on startup if ACME LDAP authentication has been enabled. Assuming that ACME LDAP is configured and enabled on the OpenVMS system in question, configuring the ACMSDI gateway to use it involves the following steps:

Assuming that the above two logical names are appropriately defined, the ACMDI gateway will attempt to authenticate users via ACME LDAP and connect to ACMS using the corresponding local OpenVMS username read from the mapping file. If no username mapping exists for the supplied LDAP username, ACMSDI will attempt to connect to ACMS using the LDAP username (which in most cases will fail).

By default, the ACMSDI gateway startup procedure SYS$STARTUP:ACMSDI$STARTUP.COM will start a single instance of the gateway, and the process ACMSDI$GATEWAY will be listening on TCP/IP port 1023; on shutdown, the procedure ACMSDI$SHUTDOWN.COM will stop this process. It is possible to define an alternative port for the gateway using the logical name ACMSDI$TCPIP_PORT, but otherwise, there is little flexibility provided by the default startup and shutdown procedures.

For various reasons, it is sometimes desirable to run multiple gateway instances, listening on different ports and with potentially different operational characteristics. For example, it may be desirable to use different port numbers for development and testing, or it may be necessary to run multiple instances of the gateway in production to support large numbers of users or to provide some level of separation between different groups of users. To facilitate these and other such requirements, the ACMSDI gateway software provides a simple means of customising the gateway startup and shutdown procedures.

On startup, the ACMSDI$STARTUP.COM procedure looks for the site-specific startup file SYS$STARTUP:ACMSDI$CUSTOM_STARTUP.COM and, if it is present, uses it instead of performing the default gateway startup. Likewise, on shutdown, the ACMSDI$SHUTDOWN.COM procedure looks for the site-specific script SYS$STARTUP:ACMSDI$CUSTOM_SHUTDOWN.COM and; if found, runs it instead of performing the default shutdown sequence. In this way, system administrators can implement their own site-specific startup and shutdown procedures without the need to modify the standard startup and shutdown procedures provided by the ACMSDI product.

The following site-specific startup and shutdown scripts illustrate the use of this customisation facility. The ACMSDI CLI tool is used to start and stop three gateway instances, listening on different ports, and writing logs to DKA100:[LOGS] instead of the default log directory?.

$! acmsdi$custom_startup.com
$
$ run acmsdi$root:[bin]acmsdi.exe
start gateway/port=3320/logdir=dka100:[logs]
start gateway/port=3321/logdir=dka100:[logs]
start gateway/port=3322/logdir=dka100:[logs]
exit
$ 
$ exit

The above site-specific command procedure will start three instances of the ACMSDI, listening on ports 3320, 3321, and 3322. The following site-specific shutdown procedure will shut down all active gateway instances.

$! acmsdi$custom_startup.com
$
$ run acmsdi$root:[bin]acmsdi.exe
stop gateway/all
exit
$ 
$ exit

The following diagram illustrates some of the key new features of the updated solution, including support for SSL/TLS encryption and the ability to implement client applications using a variety of programming languages on either Windows or Linux.

In summary, the ACMSDI gateway and TPware client components have been extensively updated to better address the integration of ACMS applications with non-OpenVMS application environments through the inclusion of support for multiple popular modern programming languages and the addition of various new features such as support for SSL/TLS encryption of all data transmitted over network links, better support for multi-threaded client application environments, and support for both Windows and Linux as client platforms, including support for both 32-bit and 64-bit Windows code. These enhancements provide users with considerably flexibility in terms of client development and integration options, and it is anticipated that additional functionality will be included in future releases of the product.