ANSYS Mechanical APDL as a Server User's

Guide

ANSYS, Inc.
Southpointe
2600 ANSYS Drive
Canonsburg, PA 15317
ansysinfo@ansys.com
http://www.ansys.com

Release 17.2
August 2016
ANSYS, Inc. is
certified to ISO
9001:2008.

(T) 724-746-3304
(F) 724-514-9494

Copyright and Trademark Information

2016 SAS IP, Inc. All rights reserved. Unauthorized use, distribution or duplication is prohibited.
ANSYS, ANSYS Workbench, Ansoft, AUTODYN, EKM, Engineering Knowledge Manager, CFX, FLUENT, HFSS, AIM
and any and all ANSYS, Inc. brand, product, service and feature names, logos and slogans are registered trademarks
or trademarks of ANSYS, Inc. or its subsidiaries in the United States or other countries. ICEM CFD is a trademark
used by ANSYS, Inc. under license. CFX is a trademark of Sony Corporation in Japan. All other brand, product,
service and feature names or trademarks are the property of their respective owners.

Disclaimer Notice
THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFIDENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.
ANSYS, Inc. is certified to ISO 9001:2008.

U.S. Government Rights

For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,
duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.
software license agreement and FAR 12.212 (for non-DOD licenses).

Third-Party Software
See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software
and third-party software. If you are unable to access the Legal Notice, Contact ANSYS, Inc.
Published in the U.S.A.

Table of Contents
1. Introduction ............................................................................................................................................ 1
1.1. Overview .......................................................................................................................................... 1
1.2. Limitations ....................................................................................................................................... 2
1.3. Installation Requirements ................................................................................................................. 2
1.3.1. Server Machine ........................................................................................................................ 2
1.3.2. Client Machine ......................................................................................................................... 2
2. Mechanical APDL as a Server Session Management .............................................................................. 3
2.1. Mechanical APDL as a Server Sessions ............................................................................................... 3
2.1.1. Starting Mechanical APDL in Server Mode ................................................................................ 3
2.1.1.1. Starting Server Mode from the Mechanical APDL Product Launcher ................................. 3
2.1.1.2. Starting Server Mode from the Command Line ................................................................. 3
2.1.2. Mechanical APDL as a Server Keyfile ......................................................................................... 4
2.2. Connecting to Mechanical APDL in Server Mode ............................................................................... 4
3. Mechanical APDL as a Server Software Development Kit (SDK) ............................................................ 5
3.1. Requirements ................................................................................................................................... 5
3.2. Mechanical APDL as a Server CORBA Interfaces ................................................................................. 5
3.2.1. ICoMapdlUnit .......................................................................................................................... 5
3.2.2. Exceptions ............................................................................................................................... 6
3.2.3. Using the CORBA Interface ....................................................................................................... 7

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

vi

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Chapter 1: Introduction
ANSYS Mechanical APDL as a Server is a set of tools and functionality that allows local or remote client
applications to access and interact with a running session of Mechanical APDL. A client application can
perform case setup, initialization, iteration, and intermediate and final result reporting using the
Mechanical APDL as a Server interface. This function is different from batch mode in that commands
can be issued to the running session at any time in addition to a predefined file. This allows for solution
steering and other manipulation without exiting from the running simulation. Client applications can
be built using the Mechanical APDL as a Server Software Development Kit (SDK) (p. 5).
The follow are some examples of how Mechanical APDL as a Server functionality could be used to manipulate Mechanical APDL remotely and provide information of interest from a running simulation:
A company with offices in several locations designs a remote console program for issuing commands to
Mechanical APDL as a Server. Users at this company run all their simulations with the Mechanical APDL as
a Server functionality turned on. When a user requires assistance from a subject-matter expert in a different
office, the expert can run the remote console and issue commands to examine results, change settings, and
assist the user in obtaining a solution.
A user would like to have remote monitoring capability for long-running simulations. The user writes a
program which can query the running simulation using the Mechanical APDL as a Server functionality. This
program delivers information about the solve process to a website, which the user can monitor. The site
can also pass commands to the simulation process, or remotely terminate the simulation.

1.1. Overview
The following elements, provided with ANSYS Mechanical APDL, make up the Mechanical APDL as a
Server capability:
The ANSYS Mechanical APDL application with built-in Internet Inter-ORB Protocol (IIOP) interface.
The Mechanical APDL as a Server Software Development Kit (SDK) (p. 5) which enables you to build custom
client applications.
The Mechanical APDL as a Server interface exists alongside the graphical user interface and the batch
mode interface. It is made available by starting Mechanical APDL in server mode, as described in Starting
Mechanical APDL in Server Mode (p. 3). A client connected to the Mechanical APDL as a Server interface
can then be used to issue commands remotely to the running Mechanical APDL session.
The information necessary to connect to the Mechanical APDL as a Server session is stored as an Interoperable Object Reference (IOR) string in a text file on the server machine when the session is started.
This IOR string is unique to the session and can be used by a client application to read all necessary
information to connect to the Mechanical APDL as a Server session (for example, hostname, port number,
protocol). For further details, see Mechanical APDL as a Server Session Management (p. 3).
You can use the Mechanical APDL as a Server Software Development Kit (SDK) (p. 5) to build your
own custom client application in any programming language which supports the Common Object Request
Broker Architecture (CORBA). The SDK comprises a set of Interface Definition Language (IDL) files which,
Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Introduction
when compiled with a 3rd party CORBA compiler, provide a set of libraries which you can include in
your application to enable communication with Mechanical APDL as a Server. For further details, see
Mechanical APDL as a Server Software Development Kit (SDK) (p. 5).

1.2. Limitations
Mechanical APDL as a Server has the following limitations:
Commands issued to the Mechanical APDL as a Server instance are not executed until Mechanical APDL is
idle or has reached a stable point. For example, Mechanical APDL is not stable while solving during an
equilibrium iteration, but at the beginning of the equilibrium iteration there is a stable point. This means
that there may be a lag between when the client program enters a command and when a response is issued
from Mechanical APDL.

1.3. Installation Requirements

The following installation topics are available:
1.3.1. Server Machine
1.3.2. Client Machine

1.3.1. Server Machine

A standard ANSYS Mechanical APDL installation is all that is required on the server machine to start a
Mechanical APDL as a Server session that can listen to commands from clients. For more information,
see Mechanical APDL as a Server Session Management (p. 3).

1.3.2. Client Machine

You can connect from a client machine using applications built with the Mechanical APDL as a Server
Software Development Kit (SDK) (p. 5) in any CORBA-compliant programming language. These client
applications will have varying installation procedures and system requirements depending on how they
are built and the amount of system resources required to execute them.

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Chapter 2: Mechanical APDL as a Server Session Management

The following topics are available for starting and managing Mechanical APDL as a Server sessions to
be accessed by remote client applications.
2.1. Mechanical APDL as a Server Sessions
2.2. Connecting to Mechanical APDL in Server Mode

2.1. Mechanical APDL as a Server Sessions

A Mechanical APDL as a Server session is similar to a conventional Mechanical APDL session, with the
addition of an Internet Inter-ORB Protocol (IIOP) interface that accepts connections from suitable client
applications. This function is different from batch mode in that commands can be issued to the running
session at any time in addition to a predefined file. This allows for solution steering and other manipulation without exiting from the running simulation.

2.1.1. Starting Mechanical APDL in Server Mode

You can start Mechanical APDL in Server Mode in two ways:
2.1.1.1. Starting Server Mode from the Mechanical APDL Product Launcher
2.1.1.2. Starting Server Mode from the Command Line
In either case, the Mechanical APDL as a Server session generates a keyfile in the session working directory with the information necessary for a client to connect to the session. For more information, see
Mechanical APDL as a Server Keyfile (p. 4) and Connecting to Mechanical APDL in Server Mode (p. 4).

2.1.1.1. Starting Server Mode from the Mechanical APDL Product Launcher
From the Customization/Preferences tab, add -aas to the Additional Parameters.

2.1.1.2. Starting Server Mode from the Command Line

Use the following commands to start Mechanical APDL in server mode:
On Windows platforms:
C:\> ansys172 <options> -aas

On Linux platforms:
> ansys172 <options> -aas

These commands assume that the Mechanical APDL executable is refered to in your PATH environment
variable.
For more information on command line options in Mechanical APDL, see Starting a Mechanical APDL
Session from the Command Level in the Operations Guide.

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Mechanical APDL as a Server Session Management

2.1.2. Mechanical APDL as a Server Keyfile

As described in Starting Mechanical APDL in Server Mode (p. 3), when you start a Mechanical APDL
as a Server session, a keyfile is created in the session working directory that contains the information
required for a client application to connect to the session. The keyfile is a text file containing in Interoperable Object Reference (IOR) string that contains information about the host, port number, and
protocol for connecting to the Mechanical APDL as a Server session.
You can use the -iorFile keyfilename command line argument to specify the name of the keyfile.
If you do not provide this argument, the file is named aas_MapdlID.txt by default.
If a keyfile already exists that refers to a running Mechanical APDL as a Server session, the new Mechanical APDL as a Server session will fail to start. This behavior prevents inadvertently overwriting a
keyfile.

2.2. Connecting to Mechanical APDL in Server Mode

Once a Mechanical APDL as a Server session is running, it is available for connections from local or remote
client applications that have network access to the server machine.
In order to connect to the Mechanical APDL as a Server session, you need access to the IOR string
contained in the keyfile generated by the session (Mechanical APDL as a Server Keyfile (p. 4)). Because
the keyfile is a text file, any means of copying the file or its contents to a location accessible to the client
machine can be used.
You can connect to Mechanical APDL as a Server using clients built with the Mechanical APDL as a
Server CORBA interfaces that are supplied as part of the Mechanical APDL as a Server Software Development Kit (SDK) (p. 5).

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Chapter 3: Mechanical APDL as a Server Software Development Kit

(SDK)
The Mechanical APDL as a Server Software Development Kit (SDK) is included with the standard installation of ANSYS Mechanical APDL and allows you to create your own client applications to connect to
and communicate with Mechanical APDL as a Server sessions. Using the SDK, you can extend or create
a client application to provide control or monitoring of Mechanical APDL simulations.
The following topics are available:
3.1. Requirements
3.2. Mechanical APDL as a Server CORBA Interfaces

3.1. Requirements
In order to use the Mechanical APDL as a Server SDK to create client applications that connect to
Mechanical APDL as a Server sessions, you will need a development environment with native or 3rd
party support for the Common Object Request Broker Architecture (CORBA) and a suitable CORBA IDL
compiler. The following widely-used programming languages have native or 3rd party CORBA support:
C and C++
COBOL
Ruby
Python
Java

3.2. Mechanical APDL as a Server CORBA Interfaces

The central element of the Mechanical APDL as a Server SDK is a CORBA interface you can use in
building a client application. This interface is included in the standard installation of Mechanical APDL.
The following topics describe the CORBA interface and its use:
3.2.1. ICoMapdlUnit
3.2.2. Exceptions
3.2.3. Using the CORBA Interface

3.2.1. ICoMapdlUnit
The ICoMapdlUnit interface provides a set of functions that perform typical commands in ANSYS
Mechanical for solving a simulation.

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Mechanical APDL as a Server Software Development Kit (SDK)

Interface ICoMapdlUnit
string getComponentName();
Returns the name of the connected component.
void setComponentName(in string name);
Sets the name of the component to name.
string getComponentDescription();
Returns the description of the connected component.
void setComponentDescription(in string desc);
Sets the description of the connected component to desc.
void uploadFileFromBuffer(in string p_szFileName, in CoOctetBuffer p_pFileContent);
Writes a file named p_szFileName in the remote Mechanical APDL session working directory with
the contents of p_pFileContent. If p_szFileName exists, it is overwritten.
CoOctetBuffer downloadFileFromBuffer(in string p_szFileName);
Returns the contents of the file name p_szFileName in the remote Mechanical APDL session working
directory.
void executeCommand(in string p_stringCommand);
Issues a command to the connected Mechanical APDL session. Output from the command is not returned.
string executeCommandToString (in string p_stringCommand);
Issues a command to the connected Mechanical APDL session and returns the output as a string.
void terminate();
Terminates the connected Mechanical APDL as a Server session.

3.2.2. Exceptions
The following exceptions can be generated by a Mechanical APDL as a Server session, and should be
appropriately handled by client applications:
exception EAnsysUnknown {
long code;

Code for the exception

string description;

Short description of the exception

string scope;

Area from where the exception has been thrown

string interfaceName;

Interface generating the exception (currently only

ICoMapdlUnit)

string operation;

Method called

string moreInfo;

Additional information about the exception

}
exception EAnsysInvalidArgument {
long code;

Code for the exception

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Mechanical APDL as a Server CORBA Interfaces

string description;

Short description of the exception

string scope;

Area from where the exception has been thrown

string interfaceName;

Interface generating the exception (currently only

ICoMapdlUnit)

string operation;

Method called

string moreInfo;

Additional information about the exception

short position;

Position of the invalid argument

3.2.3. Using the CORBA Interface

In order to use the CORBA interface for your client application, you must build the interface modules
for your development environment by compiling the supplied Interface Definition Language (IDL) file
using a suitable IDL compiler.
In a standard installation, the Mechanical APDL as a Server IDL file is located in the directory C:\Program Files\ANSYS Inc\v172\ansys\customize\user.
Refer to the documentation for your CORBA implementation and development environment for details
on how to compile the IDL file and including the resulting modules in your application.

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.

Release 17.2 - SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.