Remote API

Remote API

The SAP2000 API can be used to start and/or connect 
 to a running instance of SAP2000 on a remote computer that is running 
 the API Service. This can be particularly useful if you need to run a 
 large number of load cases (e.g., earthquakes for performance-based design, 
 moving load cases for bridge design, etc.), and there are multiple machines 
 available for running analyses simultaneously.

Simultaneous runs can be started on multiple Remote 
 Computers using an API script or plug-in, and results can be merged to 
 the Main Computer programmatically, without user intervention, as they 
 become available. Other applications could include using distributed processing 
 to run a large parameter study or Monte Carlo simulation.

Terminology

Main 
 Computer
: Your primary computer.

Remote 
 Computer
: Any other computer that you have access to (physically or 
 over the network) and that is available for running analyses and/or API 
 scripts.

API 
 Service
: CSiAPIService.exe command line utility running on a remote 
 computer that enables Remote API.

TCP 
 Port
: A TCP (Transmission Control Protocol) port is an integer between0 
 to 65535 used to identify which service is to receive a packet/message 
 sent to a Remote Computer.

Requirements & Limitations

Depending on the type of firewall 
 installed on a Remote Computer, you may have to create a firewall exception 
 on that Remote Computer to allow the API Service to communicate on your 
 network. This is done automatically for Windows Firewall during the installation 
 of SAP2000, but it may have to be manually done for other firewalls and 
 will require administrative privileges. This is typically a one-time operation.

The 
 API Service has two modes:

Product-Specific:

Listens to 
		 connections made from SAP2000v1.dll at default TCP port 11650. (For CSiBridge1.dll , the port is 11649 )

This is the 
		 default mode and can be started using the following command:

		CSiAPIService.exe or CSiAPIService.exe --api A

Cross-Product:

Listens to 
		 connections made from CSiAPIv1.dll at default TCP port 11646.

This 
		 can be started using the following command:

		CSiAPIService.exe --api C

Multiple 
 API Service instances can be run simultaneously on a Remote Computer as 
 long as they do not use the same TCP port. In case of TCP port conflicts 
 with other programs, it is possible to assign a specific TCP port to each 
 API Service instance using the following command:

CSiAPIService.exe 
 --port [portNumber]

where 
 [portNumber] is between 1024 and 49151.

It is 
 also possible to override the default TCP port for Product-Specific and 
 Cross-Product API modes using the following Windows environment variables:

Product-Specific: 
 SAP2000v1_cOAPI_DEFAULT_PORT (For CSiBridge, use CSiBridge1_cOAPI_DEFAULT_PORT)

Cross-Product: 
 CSiAPIv1_cOAPI_DEFAULT_PORT

Procedure

Install 
 the SAP2000 on the Main and Remote Computers.

On 
 each Remote Computer, open a command prompt and run CSiAPIService.exe, 
 located in the SAP2000 installation folder, to start the API Service.

Tip
: 
 Type CSiAPIService.exe --help to view a detailed list of options where 
 you can set

The TCP 
		 port to use.

API mode: 
		 Product-specific or Cross-product.

Tip
: 
 You can set the API Service to run automatically when your computer starts 
 (see 
Change 
 which apps run automatically at startup in Windows 10
 for details).

On 
 your Main Computer, run a script, program, or SAP2000 Plug-in that uses 
 one of the following API calls to start (CreateObject) or connect to 
 (GetObject) an instance of SAP2000 on a Remote Computer:

cHelper.CreateObjectHost(

ByVal hostName As String,

ByVal fullPath As String)

cHelper.CreateObjectHostPort(

ByVal hostName As String,

ByVal portNumber As Integer,

ByVal fullPath As String)

cHelper.CreateObjectProgIDHost(

ByVal hostName As String,

ByVal progID As String)

cHelper.CreateObjectProgIDHostPort(

ByVal hostName As String,

ByVal portNumber As Integer,

ByVal progID As String)

cHelper.GetObjectHost(

ByVal hostName As String,

ByVal progID As String)

cHelper.GetObjectHostPort(

ByVal hostName As String,

ByVal portNumber As Integer,

ByVal progID As String)

The above API calls receive the name of the Remote 
 Computer (e.g. hostName = myserver), and optionally a TCP port number, 
 in addition to the arguments of the regular cHelper.CreateObject() or 
 GetObject() API calls. Upon successful instantiation at a Remote Computer, 
 subsequent calls to the returned cOAPI object will execute on the Remote 
 Computer. API calls can be used to open models, modify them, run analysis 
 and design, extract results, and/or merge results back to identical models 
 on the Main Computer.

Release Notes

Initial release in version 22.1.0