You can create your functions using any of the API functions described in //ansys_inc/v242/ansys/customize/include/cAnsInterface.h, cAnsQuery.h, and cAnsPick.h. 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 it that the C program interface is an integer function that has one argument (a char pointer).

#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); 
    }

Once you have written the source code for your functions, you can create a Makefile (using the gen_share utility) to build a shared library. The utility creates the Makefile in the current directory. The Makefile incorporates all the interdependencies of the C source files it encounters in that current directory. The gen_share utility is meant to setup the basic build. The user may need to make modifications to the Makefile depending on the situation.

The gen_share utility has the following syntax:

gen_share [-h] [-64] shared_object_name

where

As gen_share is executing, you may see one or more "No match" messages. This is normal. The script is searching for .c, .f, and .F file types in the current directory and returns this message if it cannot locate any files matching one of those types.

To create a shared library called mylibrary.so, you would issue the following command:

% gen_share mylibrary.so

The utility will produce a Makefile in the current directory. You will be able to generate the shared library by issuing the following command:

make

For example, to create the shared library for mylibrary.so, you would issue the following command:

% make

You will then find the specified shared library file in the current directory. You may also see warnings from the make process, and you may need to modify the Makefile or your source code.

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 to allow Mechanical APDL to access. There is no limit to the number of entries. The file entries have the following format:

/shared/library/path/library.so ~cm_name function_name

where:

For example, the following entry references the /home/mydir/mylibs/myobject.so shared library and the myobject_ function. It specifies ~myobj as the related command:

/home/mydir/mylibs/myobject.so ~myobj myobject_

Mechanical APDL also makes use of external commands, and places its own shared libraries and the associated external table file in the /ansys_inc/v242/ansys/lib/<platform> directory (where <platform> is the directory specific to your computing platform, such as /linx64).

Mechanical APDL loads external commands as follows:

If you designate a command name that has the same first four characters as a command listed in the /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 /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, first set the ANSYS_EXTERNAL_PATH to point to the directory containing the external table file. (For convenience, if you distribute your new functionality to other users they should set their .login or .cshrc files so that it is persistent from session to session.) For example, the following sets the environment variable to point to the /home/mydir directory.

setenv ANSYS_EXTERNAL_PATH /home/mydir

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

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      

In this example, the output lists the command, the related shared library, the function, and if the command has been accessed.

You can

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

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