You can create your functions using any of the API functions described in Program Files\ANSYS Inc\V242\ansys\customize\include\cAnsInterface.h, cAnsQuery.h, and cAnspick.h. You can then execute these functions via the "external command" feature within Mechanical APDL. In addition, the program provides special commands that list all available external commands and allow you to reset all currently referenced external commands. The following code segment demonstrates, at a minimal level, how to create functions that can be used as an entry point into a custom coded shared library.

The most important point in the following example is:

#include <windows.h>
#include "cAnsInterface.h" 
#include "CAnsQuery.h"

/*
------------------------------  Function Description -----------------------
extfnc
  int extfnc(uecmd)
  char *uecmd;

Purpose:

     Demonstrate C API entry function for an external command.

Parameters:

     Input
     -----------------------------
       uecmd
         The ANSYS external command string.

     Output
     -----------------------------

Return Value:
     The return value is ignored by the calling function;

----------------------------- End Function  Description --------------------

*/ 
int extfnc(char* uecmd)
{ 
   /* Note: uecmd is the entire command given to invoke this function */ 
    char* cmdsend = {"/COM, COMMAND SENT FROM EXTERNAL COMMAND"}; 
    char* querystr = {"NODE,,NUM,MAX"}; 
        char strrtn[32]; 
    int i, itype; 
    double dblrtn; 

    /* Send a simple command to be executed */ 
    i = cAnsSendCommand(cmdsend); 

    /* Perform a simple query */ 
    i = cAnsGetValue(querystr,&dblrtn,strrtn,&itype); 

    /* Display the value retrieved */ 
    cAns_printf("Max Node Number = %g\n",dblrtn); 

    return (i); 
    }

The steps for building a Visual Studio project are demonstrated in the example at the end of this appendix. See Example: Creating an External Command Using Visual Studio 2019 Professional.

For each external function, you must declare it in the external definition file. The naming convention for this file is the name of your project with the .def extension; it must be located in your project directory. This file consists of the word EXPORTS on the first line, and the name(s) of the functions to be exported on each successive line. For the example function above:

EXPORTS

extfunc

Once all of the necessary files have been incorporated into your project, simply compile (Ctrl+F7) and build (F7) the project. In your project directory, Developer Studio will create a Debug directory and will place the library in that directory (projname.dll).

The external table file (ans_ext.tbl) can reside in any directory (but you must specify that directory in the ANSYS_EXTERNAL_PATH environment variable). The file contains an entry for each shared library function you wish Mechanical APDL to access. There is no limit to the number of entries. The file entries have the following format:

C:\shared\library\path\projname.dll ~cm_name function_name

where:

For example, the following entry references the C:\home\mydir\mylibs\myobject.dll shared library and the myobject function, and specifies ~myobj as the related command:

C:\home\mydir\mylibs\myobject.dll ~myobj myobject

Mechanical APDL also makes use of external commands, and places its own shared libraries and the associated external table file in the C:\Program Files\ANSYS Inc\V242\ansys\lib\<platform> directory (where <platform> is the directory specific to your computing platform, such as \winx64). The program loads external commands in the following order:

If you designate a command name that has the same first four characters as a command listed in the C:\Program Files\ANSYS Inc\V242\ansys\lib\<platform>\ans_ext.tbl file, you will not be able to access your command. Therefore, it is a good practice to check the external table file to make sure you have no external command name conflicts. Do not modify the C:\Program Files\ANSYS Inc\V242\ansys\lib\<platform>\ans_ext.tbl file. You can also use the ~DEBUG command to verify that no external command name conflicts exist.

Before launching Mechanical APDL, you must first set the ANSYS_EXTERNAL_PATH to point to the directory containing the external table file. In Windows NT, the environment variables are in System Properties, which can be accessed through the Control Panel. For example, the following string sets the environment variable to point to the C:\home\mydir directory.

set ANSYS_EXTERNAL_PATH=C:\home\mydir

To call an external command, issue it as you would any other Mechanical APDL command. You can also call external commands through either an APDL macro or UIDL routine.

You can check what shared libraries are currently accessible by entering the ~DEBUG command in the command input window. The following figure shows an example of ~DEBUG command output.

External Command Mappings:
 Command   Library                             Function         Accessed?
  *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
 ~excmd    /home/mydir/mycode/mycommand.so     excmd            YES      

Note that the output lists the command, the related shared library, the function, and whether or not the command has been accessed.

You can

by issuing the ~RESET command. This command issues the following message to confirm that the reset operation is complete.

~RESET was processed: The external command buffers have been cleared.   

An example for setting up an external command using Microsoft Visual Studio 2019 Professional is provided on the installation media. To run this example, perform the following steps.