# GSA COM API

GSA COM API allows other programs and scripts to programmatically access to GSA functionality. The API is implemented using Microsoft’s COM (opens new window) technology. It allows GSA models to be created, edited, analysed, and enable results to be queried.

The GSA API uses COM automation to allow other programs to access to GSA operations by creating an instance of GSA class ComAuto and calling the exported functions of this class. GSA COM API can be invoked by any programming language or scripting environment that can work with COM and ActiveX. Examples include .NET (C# and VB), Python, VBA, C++, and MATLAB. We recommended the use of .NET – this environment is closely compatible with the API, and there are several code samples get your started. Python is also a good alternative.

All the API is exposed via the type library file Gsa.tlb which is installed in the GSA program files folder. The library exports a single object: ComAuto and several structs and enums. These are listed in the API reference section in the later part of this document.

Note: Function names are case sensitive. A log file is created in the same directory as the GSA model file to record the execution of each of the functions.

The COM interface is versioned, i.e. each minor and major release of GSA has COM classes specific to that release. Instantiating these classes will specifically invoke the version of GSA they correspond to. Whilst this gives the flexibility to bind to a particular release of GSA, it is also possible to always bind to the latest release. The choice of whether a programmer wants to bind to a version specific COM class or version independent COM depends on how they invoke GSA COM (see the section Early and late binding).

# Getting started

The API can be thought of as made up of families of functions for ease of understanding. This is reflected in the way it is documented in the reference.

A good way to start using the API is by using one of the several code samples as a starting point. The rest of this section demonstrates a basic sample in two languages: VB.NET and Python.

There are samples for .net, Excel/VBA and C++ in the GSA / COM API section in the Oasys API samples repository, found at https://github.com/arup-group/oasys-api-samples (opens new window). Each sample demonstrates the use of a section of the API. The files and their functions are listed in the various README.md files in each section of the above repository.

The first step in using the APIs is to import the type library or the interop dll into your programming environment. The COM interface is ‘versioned’, i.e., each minor and major release of GSA has COM classes specific to that release. As an example, for using the GSA 10.2 COM API in vb.NET, import < C:\Program Files\Oasys\GSA 10.2\Gsa.tlb> and then instantiate the object as follows:

Dim gsaObj As Gsa_10_2.ComAuto

Set gsaObj = New Gsa_10_2.ComAuto

Once you instantiate the objects, you can proceed to view the available functions in the Object browser (if using Visual Studio) and call them.

This basic sample creates the object, opens the GSA file, deletes the results, and runs all analysis tasks in the file.

# VB.NET

Dim gsa As New ComAuto
' Write out the version of GSA that has been invoked
Console.WriteLine(gsa.VersionString())
' Open GSA file. (Ensure that the file exists at this path)
gsa.Open("c:\temp\stair.gwb")
' delete any analysis results in the file
gsa.Delete("RESULTS")
' analyse all tasks
gsa.Analyse()
' save the analysed model with a different file name
gsa.SaveAs("c:\temp\stair_analysed.gwb")
gsa.Close()
gsa = Nothing

# Python

# For a description of each line, see comments in the vb.net sample
import win32com.client
import pythoncom
gsaobj = win32com.client.Dispatch("Gsa_10_1.ComAuto")
gsaobj.VersionString()
gsaobj.Open("C:\\\temp\\\Stair.gwb")
gsaobj.Delete("RESULTS")
gsaobj.Analyse()
gsaobj.SaveAs("c:\\\temp\\\stair_analysed.gwb")
gsaobj.Close()
gsaobj = None

# Excel

When using GSA COM from Excel you may need to add a reference to GSA. From the Tools menu select References and browse to the GSA installation to find the GSA.tlb file.

# Limitations

COM APIs may not run your scripts successfully if there is an active GSA window when invoking your script. This style of execution is not supported and can lead to unpredictable behaviour including crashes.

# Changes to previous version

We have updated some terminology in the Enums to remove inappropriate references. Existing programs may need updating to suit.

Old	New
JOINT_SLAVE	JOINT_CONSTRAINED_NODE
JOINT_MASTER	JOINT_PRIMARY_NODE
RIGID_CONSTR_MASTER	RIGID_CONSTR_PRIMARY_NODE
CONST_EQN_SLAVE	CONST_EQN_CONSTRAINED_NODE
TIED_INTER_SLAVE	TIED_INTER_CONSTRAINED_ENTITIES
TIED_INTER_MASTER	TIED_INTER_PRIMARY_ELEMENTS

# API function reference

GSA COM API functions are grouped as families of functions. This classification is purely for ease of documentation and understanding – in reality all the functions below are offered by the ComAuto object. The families are:

Core functions
View functions
GwaCommand function
Data functions
Output functions
Case and Task functions
List functions
Tool functions
Utility functions

# Core functions

# NewFile

integer NewFile()

Open a new model.

Returns status

0 – OK

1 – Failed to open

# Open

integer Open(filename)

Open a GWB, GWA or CSV file.

Returns status

0 – OK

1 – Failed to open

Argument

filename – The name of the file to be opened, including path and extension.

# Save

integer Save()

Save the data to the default file (i.e. overwriting the file that was opened or last saved).

Returns status

0 – OK

1 – No GSA file is open

2 – No default path is available; use SaveAs

3 – Failed to save

# SaveAs

integer SaveAs(filename)

Save the data to GWB, GWA or CSV file.

Returns status

0 – OK

1 – No GSA file is open

2 – Invalid file extension

3 – Failed to save

Arguments

filename – The name of the file to be saved, including path and extension.

# Close

integer Close()

Close the current file.

Returns status

0 – OK

1 – No GSA file is open

# CreateElementsFromMembers

integer CreateElementsFromMembers(string memberList)

Create elements from the members in the given list. If elements already exist for members in the list, these will be re-created from the current member definition.

Returns status

0 – OK, elements create for all members

1 – No GSA file is open

2 – Terminated because model already has results

3 – Invalid member list

4 – Completed, but some members had meshing errors (open in GSA for details)

Arguments

memberList – List of members to create elements from. E.g. all for all members.

# Analyse

integer Analyse(integer task)

Analyse the tasks in GSA.

Where the task is greater than zero then analyse that task. If the task is zero or less, and no analysis tasks exist then do linear static analysis of each specified load case. If the task is zero or less, and the analysis tasks exist then analyse all analysis tasks that have not been analysed.

Returns status

0 – OK, analysis attempted

(Use CaseResultsExist or TaskStatus to establish whether the analysis succeeded in producing results)

1 – No GSA file is open

2 – Failed to attempt analysis

Arguments

Task – Analysis task number. Set to -1 (default) to run all analysis tasks.

# Delete

integer Delete(string option)

Deletes results.

Returns status

0 – OK

1 – No GSA file is open

2 – Invalid option

3 – Data is not present; no action taken

Arguments

Option – valid settings are:

RESULTS – Delete all analysis results but not analysis cases.

DESIGN_RESULTS – Delete all design task results.

RESULTS_AND_CASES – Delete all results and analysis cases.

# Design

integer Design(integer task, enum DesignOption option)

Runs the specified design task.

Returns status

1 – No GSA file open

2 – Design task does not exist

3 – Design task has results

Arguments

Task – The reference of the design task to be executed. A value of 0 indicates all tasks.

Option – enum of the type DesignOption that specifies if the task will run as a design or as a check.

# VersionString

string VersionString()

Returns the version information of the installed GSA instance and its component as a string.

# DisplayGsaWindow

DisplayGsaWindow(bool display)

Displays or hides the window of the running GSA instance.

Argument

Display – True to show the window and False to hide it.

# View functions

# UpdateViews

UpdateViews()

Refreshes all GSA views currently displayed.

# PrintView

integer PrintView(string option)

Print saved or preferred graphic views or output views. Returns a status, as follows:

0 – OK

1 – No GSA file is open

2 – Invalid argument

Arguments

Option – Valid settings are:

ALL_PGV – Print all preferred graphic views.

ALL_SGV – Print all saved graphic views.

ALL_POV – Print all preferred output views.

ALL_SOV – Print all saved output views.

ALL_LST – Print all View Lists.

TAGGED_PGV – Print tagged preferred graphic views.

TAGGED_SGV – Print tagged saved graphic views.

TAGGED_POV – Print tagged preferred output views.

TAGGED_SOV – Print tagged saved output views.

TAGGED_LST – Print tagged View Lists.

<name> – Print the first view or view list found with the specified name.

# SaveViewToFile

integer SaveViewToFile(string option, string filetype)

Add saved or preferred graphic views or output views to file. Returns a status, as follows:

0 – OK

1 – No GSA file is open

2 – Invalid argument

Arguments

Option – Valid settings are:

ALL_PGV – Save all preferred graphic views.

ALL_SGV – Save all saved graphic views.

ALL_POV – Save all preferred output views.

ALL_SOV – Save all saved output views.

ALL_LST – Save all view lists.

TAGGED_PGV – Save tagged preferred graphic views.

TAGGED_SGV – Save tagged saved graphic views.

TAGGED_POV – Save tagged preferred output views.

TAGGED_SOV – Save tagged saved output views.

TAGGED_LST – Save tagged view lists.

<name> – Save the first view or view list found with the specified name.

filetype – valid settings are:

PNG – Save graphic views to PNG file.

JPG – Save graphic views to Jpeg file.

TXT – Save Output view to tab delimited TXT file.

CSV – Save Output view to comma delimited CSV file.

HTM – Save Output view to HTML file.

# HighestView

integer HighestView(string option)

Return the highest numbered saved or preferred Graphic view or Output view.

Option – valid settings are:

PGV – Highest numbered preferred Graphic view.

SGV – Highest numbered saved Graphic view.

POV – Highest numbered preferred Output view.

SOV – Highest numbered saved Output view.

LST – Highest numbered saved view list.

# ViewExist

integer ViewExist(string option, integer ref)

Returns 1 if the saved or preferred Graphic view or Output view exists.

Option – Valid settings are:

PGV – Preferred Graphic view.

SGV – Saved Graphic view.

POV – Preferred Output view.

SOV – Saved Output view.

LST – Saved view list.

Ref – View number (1 based)

# ViewName

string ViewName(string option, string ref)

Returns the name of the saved or preferred Graphic view or Output view.

# Arguments

Option – Valid settings are:

PGV – Preferred Graphic view.

SGV – Saved Graphic view.

POV – Preferred Output view.

SOV – Saved Output view.

LST – Saved view list.

Ref – View number (1 based)

# ViewRefFromName

integer ViewRefFromName(string option, string name)

Returns the saved Graphic view or Output view reference from its name.

Option – Valid values are:

SGV – Saved Output view

SOV – Saved Output view

Name – The name of the saved view.

# CreateNewView

integer CreateNewView(string name)

Creates a new saved Graphic view and returns its index.

Name – The intended name of the created Graphic view.

# SetViewBaseSettings

integer SetViewBaseSettings(integer id, string SavedViewGwa)

Applies base view settings from the saved view template provided onto the given saved view referenced by id.

Returns status

1 – No file is open

2 – Saved Graphic view with id does not exist

3 – SavedViewGwa string is empty or invalid

4 – Could not read a valid saved view from SavedViewGwa

0 - OK

Arguments

id – The index of the saved view to which you want to apply the template.

SavedViewGwa – the GWA record of a saved view that is to be used as a template for the contouring settings that you want to apply to the above view.

Note

See the documentation to SetViewContour for an explanation of the template and for the general use/workflow of this function.

# SetViewContour

integer SetViewContour(integer id, integer dataref, string SavedViewGwa)

Applies the contour settings from the saved view template provided onto a given saved view referenced by id. Then sets the output component that is contoured to dataref.

Returns status

1 – No file is open

2 – Saved Graphic view with id does not exist

3 – SavedViewGwa string is empty or invalid

4 – Could not read a valid saved view from SavedViewGwa

0 - OK

Arguments

id – The index of the saved view to which you want to apply the template.

Dataref – The dataref of the result component that you want to contour. See Output_Init for an explanation of how datarefs work.

SavedViewGwa – The GWA record of a saved view that is to be used as a template for the contouring settings that you want to apply to the above view.

Note

The SetViewContour, SetViewDiagram, SetViewLabels, and SetViewBaseSettings functions allow settings to be applied based on previously created saved views that are used as templates. The templates do not need to be in the same GSA file – all that’s needed is the GWA record of the template. These could be generated in one of two ways:

Create a saved view with all the settings you would like to see in your final view and save the file as GWA. Open in text editor and copy the relevant GR_VIEW record and paste in your code as a string constant.
Alternatively, create and save a GSA model with view templates as above. At runtime, use your program to open this GSA file, and get the GWA record of the appropriate template using the GwaCommand function.

The following VB.NET code demonstrates the above workflow.

Dim gsa As New ComAuto

' this is the GSA file that has our view templates

gsa.Open("viewtemplates.gwb")

Dim ref_template_contour = gsa.ViewRefFromName("SGV",
"template-contour")

Dim ref_template_labels = gsa.ViewRefFromName("SGV", "template-labels")

Dim contour_template As String = gsa.GwaCommand("GET, GR_VIEW," &
ref_template_contour)

Dim label_template As String = gsa.GwaCommand("GET, GR_VIEW," &
ref_template_labels)

gsa.Close()

gsa.Open("steel_design_medium.gwb")

' Create a new saved view that will display a contour

Dim viewRef As Integer = gsa.CreateNewView("contour")

' Now "apply" contour_template to this view and set

' the result component to nodal displacement, z

gsa.SetViewContour(viewRef, 12001003, contour_template)

' Turn labels on by apply the labels template

gsa.SetViewLabels(viewRef, label_template)

# SetViewLabels

integer SetViewLabels(integer id, string SavedViewGwa)

Applies labels settings from the supplied view template onto the saved view with the given reference.

Returns status

1 – No file is open

2 – Saved Graphic view with id does not exist

3 – SavedViewGwa string is empty or invalid

4 – Could not read a valid saved view from SavedViewGwa

0 - OK

Arguments

id – the index of the saved view to which you want to apply the template.

SavedViewGwa – the GWA record of a saved view that is to be used as a template for the contouring settings that you want to apply to the above view.

Note

See the documentation to SetViewContour for an explanation of the template and for the general use/workflow of this function.

# SetViewDiagram

integer SetViewDiagram(integer id, integer dataref, string SavedViewGwa)

Applies the diagram settings from the saved view template provided onto a given saved view referenced by id. Then draws the diagram for the output component represented by dataref.

Returns status

1 – No file is open

2 – Saved Graphic view with id does not exist

3 – SavedViewGwa string is empty or invalid

4 – Could not read a valid saved view from SavedViewGwa

0 - OK

Arguments

id – The index of the saved view to which you want to apply the template.

dataref – The dataref of the result component that you want to contour. See Output_Init for an explanation of how datarefs work.

SavedViewGwa – The GWA record of a saved view that is to be used as a template for the contouring settings that you want to apply to the above view.

Note

See the documentation to SetViewContour for an explanation of the template and for the general use/workflow of this function.

# GetViewOrientation

integer GetViewOrientation(integer id, ref GsaViewOrientation orientation)

Returns the view orientation settings of a saved Graphic view in the form of a GsaViewOrientation object (see struct GsaViewOrientation).

Returns status

1 – No file is open

2 – Saved Graphic view with id does not exist

Arguments

id – The index of the saved view to which you want to apply the template.

Orientation – An object of struct GsaViewOrientation.

The GsaViewOrientation struct contains fields that correspond to the settings from the Graphics settings > Orientation dialog in an interactive session.

SetViewOrientation

integer SetViewOrientation(integer id, GsaViewOrientation orientation)

Sets the view orientation settings of a saved Graphic view as supplied in the GsaViewOrientation object.

Returns status

1 – No file is open

2 – Saved Graphic view with id does not exist

3 – Error in the definition of orientation object: one of orientation or MidPoint or ObjectPoint are null.

0 - OK

Arguments

id – The index of the saved view to which you want to apply the template.

Orientation – An object of struct GsaViewOrientation.

The GsaViewOrientation struct contains fields that correspond to the settings from the Graphics settings > Orientation dialog in an interactive session.

# RescaleViewToFit

integer RescaleViewToFit(integer id)

Rescales the saved Graphic view associated with the supplied id.

Returns status

1 - No file is open

2 - Saved Graphic view with id does not exist

Arguments

id - The index of the saved view that you want to rescale.

Note

This function has the same effect as the Scale to fit command in an interactive session.

# RescaleViewData

integer RescaleViewData(integer id)

Rescales the contour and diagram data (i.e. recalculates extents, etc.) for the Graphic view associated with the supplied id.

Returns status

1 - No file is open

2 - Saved Graphic view with id does not exist

Arguments

id - The index of the saved view that you want to rescale.

Note

This function has the same effect as the Rescale data command in an interactive session.

# GwaCommand function

GWA commands are commands that interact directly with the data in a GSA session. This allows the user to modify any of the data in a GSA file. GSA data is stored in modules that are one of the following types:

Specification – Single record module (e.g. General specification)
Ordered table modules – Multi-record but can include gaps in the records (e.g. Nodes)
Collection table modules – Multi-record without gaps in the records (e.g. Beam loads)

Generally, collection table modules are those that are not cross referenced with other modules, so, for example, switching a couple of load records does not affect the data integrity while switching a couple of node records does.

The syntax of the command is based on GWA syntax and the units follow the GWA unit syntax; – refer to the GSA Keywords (opens new window) document for details.

# GwaCommand

variant GwaCommand(string command)

Issue a GWA command to GSA.

Argument

Command – A command in GWA format with fields separated by a tab or the list separator (typically a comma or semi-colon). The commands that can be used are:

key_word, {data} – This is used to insert a record of data (e.g. writing a complete set of data to a GSA model).

SET, key_word, {data} – This is similar to the previous command and inserts a record of data (for specification and ordered table modules). For a node this will overwrite the node (if it is already defined) as the node number is part of the data – but for a load it will simply append to the module as the load records do not have a record number).

SET_AT, record, key_word, {data} – Set a particular data record (for collection table modules) this allows, for example, load records to be modified and overwritten as the record number is specified.

ADD, key_word, {data} – Add a data record at the end of the module (for collection table modules).

GET, key_word, {data} – Return a record of data.

GET_ALL, key_word – Return all records for the given keyword.

HIGHEST, key_word – Return the number of the highest record number.

BLANK, key_word, low_record [, high_record] – Blank a record or a range of records (without reordering subsequent records).

DELETE, key_word, low_record [, high_record] – Delete a record or a range of records (reordering subsequent records to close the gap).

EXIST, key_word, record – Return true if the record exists.

LOCKED, key_word, record – Return true if the record is locked.

– Where items in [ ] are optional and items in { } represent a list of values.

Examples of command:

To create a node 25 at (10,4.5,8)

SET, NODE, 25, 10, 4.5, 8

UNIT_DATA, LENGTH , cm, 100

NODE, 25, 1000, 450, 800

To set beam load 1 to be a UDL of −1000 in z on elements 1 to 10 for case10 in global axes

SET, 1, LOAD_BEAM, 1 to 10, 10, GLOBAL, NO, Z, -1000

or to append this beam load

ADD, , LOAD_BEAM, 1 to 10, 10, GLOBAL, NO, Z, -1000

To check if element 11 exists

EXIST, EL, 11

To create a beam element 11 with property 1, group 101 and nodes 12 and 22 and orientation node 3

SET, EL_BEAM, 11, 1, 101, 12, 22, 3

To return the data for material 3

GET, MAT, 3

To get the displacements for node 25 in case 4

GET, DISP, 25, 4

To check the highest node

HIGHEST, NODE

To see if an axis 4 is locked

LOCKED, AXIS, 4

To blank element 40

BLANK, EL, 40

or to delete the element

DELETE, EL, 40

# Notes on using GwaCommand:

The GwaCommand fully exposes the GSA data structure, so care should be taken to ensure that the data is not corrupted.
When creating elements the entity type is specified in the keyword, so to create a beam element the keyword is EL_BEAM but when inquiring about an element the keyword is simply EL.
To check the highest user module or to delete a user module refer to the respective user module title record. E.g.

HIGHEST, USER_MOD_NODE_TITLE

DELETE, USER_MOD_ELEM_TITLE, 3

# String IDs (sIDs) and GwaCommand:

The model sID is accessed by using the SID key_word.

SET, SID, {tag1:value1}{tag2:value2}

Object sIDs are appended to the object key_word.

SET, EL_BEAM:{tag1:value1}{tag2:value2}, 11, 1, 101, 12, 22, 3

Refer to Working with GSA > String IDs in the GSA help file for Information on sID formatting.

# Data functions

# NodeCoor

integer NodeCoor(integer id, double x, double y, double z)

Retrieves the position of a node in global coordinates.

Returns status

0 – OK

1 – Node not found

Arguments

Ref – Node reference

x – x coordinate of the node (double*)

y – y coordinate of the node (double*)

z – z coordinate of the node (double*)

# Gen_NodeAt

integer Gen_NodeAt(double x, double y, double z, double tol)

Returns the node number of the newly generated node or the existing node for the given coordinate (x, y, z).

Arguments

x – x coordinate of the node

y – y coordinate of the node

z – z coordinate of the node

tol – tolerance to use existing node

# Gen_SectionMatchDesc

string Gen_SectionMatchDesc(string sectdesc, integer flags)

Returns valid GSA section description from the given tentative section description (sectdesc)

Sectdesc – Tentative section description

Flags – compound flag; valid settings are:

Enum Gen_SectionMatchDesc_Flags

SEC_INCL_SS = &H1 include superseded sections in search

SEC_ATTEMPT_STD = &H2 attempt to assemble a standard section from tentative section description (sectdesc)

End Enum

# MembNumElem

integer MembNumElem(integer id)

Returns the number of elements associated with the given member.

Argument

id – member number

# MembElemNum

integer MembElemNum(integer id, integer index)

Returns the element number for the given member and element index.

Arguments

id – Member number

index – Element index for the member (zero based)

# ElemMembNum

integer ElemMembNum(integer id)

Returns the member number of associated with the given element.

Argument

Ref – Element number

# Nodes

integer Nodes(array nodeRefs, ref array nodes)

Fetches an array of GsaNode objects given an array of node references.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

nodeRefs – Integer array of valid node references

nodes – Array of GsaNode objects associated with the node references

As an example, the following VB.NET snippet retrieves all nodes in the GSA model

Dim nodeRefs() As Integer

s = gsaObj.EntitiesInList("all", GsaEntity.NODE, nodeRefs)

Debug.Assert(Not s.Equals(0) And Not (nodeRefs Is Nothing))

Dim nodes() As GsaNode

s = gsaObj.Nodes(nodeRefs, nodes)

# SetNodes

integer SetNodes(array nodes, bool overwrite)

Sets an array of GsaNodes into the GSA model data.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

nodes – Array of GsaNode objects

Overwrite – Boolean flag to indicate if existing nodes, if any, are to be overwritten

# Elements

integer Elements(array elemRefs, ref array elems)

Fetches an array of GsaElement objects given an array of element references.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

elemRefs – Integer array of valid element references

elems – Array of GsaElement objects associated with the element references

Note

For an example, see documentation for the function Nodes.

# SetElements

integer SetElements(array elems, bool overwrite)

Sets an array of GsaElement objects into the GSA model data.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

nodes – SAFEARRAY of GsaElement objects.

Overwrite – Boolean flag to indicate if existing elements, if any, are to be overwritten

# Sections

integer Sections(array sectRefs, ref array sections)

Fetches an array of GsaSection objects given an array of section references.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

sectRefs – Integer array of valid section references

sections – Array of GsaSection objects associated with the section references

Note

For an example, see documentation for the function Nodes.

# SetSections

integer SetSections(array sections, bool overwrite)

Sets an array of GsaSection objects into the GSA model data.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

sections – array of GsaSection objects.

Overwrite – Boolean flag to indicate if existing elements, if any, are to be overwritten

# Members

integer Members(array memberRefs, ref array Members)

Fetches an array of GsaMember objects given an array of member references.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

sectRefs – Integer array of valid member references

sections – Array of GsaMember objects associated with the section references

Note

For an example, see documentation for the function Nodes.

# SetMember

integer SetMember(array members, bool overwrite)

Sets an array of GsaMember objects into the GSA model data.

Returns status

0 – OK

1 – No file open or invalid input

Arguments

members – Array of GsaMember objects.

Overwrite – Boolean flag to indicate if existing elements, if any, are to be overwritten

# NodeConnectedEnt

integer NodeConnectedEnt(GsaEntity entityType, integer nodeRef,ref array entRefs)

Fetches the indices of elements or members connected to a node.

Returns status

0 – OK

1 – No file open or invalid input

2 – Node does not exist

Arguments

entityType – enum of type GsaEntity. Has to be ELEMENT or MEMBER.

nodeRef – Reference of the node to query for

entRefs – Array holding the references to connected entities. (Output)

# Output functions

The following functions are for extracting processed data, for example, derived enveloped stresses.

# Output_Init

integer Output_Init(integer flags, string axis, string case, integer dataref, integer num1dpos)

Initialises the output functions. Call this before calling any other Output_ functions.

Returns status

0 – OK

1 – No GSA file is open

3 – Invalid axis

4 – Invalid case

5 – Invalid dataref

Arguments

Flags – Compound flag; valid settings are:

Enum Output_Init_Flags

OP_INIT_2D_BOTTOM = &H1 output 2D stresses at bottom layer

OP_INIT_2D_MIDDLE = &H2 output 2D stresses at middle layer

OP_INIT_2D_TOP = &H4 output 2D stresses at top layer

OP_INIT_2D_BENDING = &H8 output 2D stresses at bending layer

OP_INIT_2D_AVGE = &H10 average 2D element stresses at nodes

OP_INIT_1D_AUTO_PTS = &H20 calculate 1D results at interesting points

End Enum

E.g. OP_INIT_2D_TOP Or OP_INIT_2D_AVGE 2D stresses at top layer, averaged at nodes

Axis – Output axis; enter the name of a standard axis or the number of a user defined axis; examples of valid entries:

default – the default for the data being extracted

global

local

Case – The output case, ignored if not relevant; CasePermString may

be used to collate this string; examples of valid entries:

L1

A3

C3

C4max – Assumes C4 is an envelope

C4min – <ditto>

C4abs – <ditto>

C4signabs – <ditto>

C4p3 – <ditto>

dataref – An integer data reference; refer to

Output_DataRef file for available options; for Example:

14003001 refers to beam element axial stress

num1dpos – The number of equidistant internal positions along the 1D

elements to be considered for 1D element results, in addition to the automatic interesting positions if specified in flags

Note

The dataref field is determined by looking at the Output_DataRef file. First locate the result header that you are interested (for e.g. for Nodal displacement in y direction the header is REF_DISP). Then add the offset of the position of the result you seek. In the case of nodal displacement in y this corresponds to REF_DISP_DY, which is at an offset of 2 from REF_DISP, therefore the right value of dataref for REF_DISP_DY is 12001000+2 = 12001002.

The output worksheet in the https://github.com/arup-group/oasys-api-samples/blob/main/GSA/COM API/VBA/GsaComGwaSample.xls (opens new window) file demonstrates the use of the output family of functions. In particular, it can also been used to validate if you are working with the right value of the dataref argument. To validate, enter appropriate values for the file name, node/element ids and the dataref. Then click the Output button. The Title field should be populated with the name of the output quantity that the dataref corresponds to.

# Output_SetStage

integer Output_SetStage(integer stage)

Returns status

0 – OK

1 – No GSA file is open

2 – Output_Init not called

Argument

Stage – The analysis stage to be considered; only relevant for input data (e.g. properties) since results are for the stage that was analysed; use 0 for whole model

# Output_DataTitle

string Output_DataTitle(integer flags)

Returns the title of the data specified in the last call to Output_Init, as a string.

Argument

Flags – Compound flag; valid settings are:

1 – Full title (otherwise the abbreviated title is returned)

# Output_IsDataRef

integer Output_IsDataRef(integer flags)

Returns 1 if the flags condition applies to the data specified in the last call to Output_Init.

Argument

flags – Compound flag; valid settings are:

Enum Output_IsDataRef_Flags

OP_IS_AND = &H1 otherwise OR

OP_IS_PER_REC = &H2

OP_IS_PER_NODE = &H4

OP_IS_PER_ELEM = &H8

OP_IS_PER_MEMB = &H10

OP_IS_PER_1D_DISP = &H20

OP_IS_PER_1D_FRC = &H40

OP_IS_PER_TOPO = &H80

OP_IS_AT_CENTRE = &H100

End Enum

E.g. OP_IS_PER_1D_DISP Or OP_IS_PER_1D_FRC – data is reported at 1D element internal displacement OR internal force positions.

E.g. OP_IS_AND Or OP_IS_PER_ELEM Or OP_IS_PER_TOPO – data is reported per element AND per node per element.

# Output_UnitString

string Output_UnitString()

Returns the units of the data specified in the last call to Output_Init, as a string.

# Output_UnitFactor

float Output_UnitFactor()

Returns the factor to convert the data specified in the last call to Output_Init from SI to the current model units.

# Output_DataExist

integer Output_DataExist(integer id)

Returns 1 if the data specified in the last call to Output_Init exists for the specified item.

Argument

id – the record or node or element or member number to be considered

# Output_NumElemPos

integer Output_NumElemPos(integer id)

Returns the number of positions on the element or member for which the data specified in the last call to Output_Init are available. For 1D elements this will be the end positions plus the internal positions, based on the arguments supplied in the last call to Output_Init. For 2D elements this will be the number of nodal positions on the element plus, for some data options, the centre value.

Argument

id – the element or member number to be considered

Important:

This function must be called before Output_1DElemPos and Output_Extract for 1D element results.

# Output_1DElemPos

float Output_1DElemPos(integer pos)

Returns the position along a 1D element as a proportion of the element length for specified position number.

Argument

pos – the position number to be considered; zero based (i.e. 0 is the first position and Output_NumElemPos − 1 is the last)

Note

Call Output_NumElemPos before calling this and after calling Output_Init.

# Output_Extract

variant Output_Extract(integer ref, integer pos)

Returns the requested data for the specified axis and case in the current model units. Output_NumElemPos should be called before calling this for 1D element data, and after calling Output_Init.

Argument

ref – The record or node or element or member number to be considered

pos – The position number to be considered; zero based (i.e. 0 is the first position and Output_NumElemPos − 1 is the last)

# Output_Extract_CurPerm

integer Output_Extract_CurPerm()

Returns the envelope permutation that gave the data returned by the last Output_Extract call. This is only relevant if the current case, set in Output_Init, is a Cnmax, Cnmin, Cnabs or Cnsignabs case.

# Output_Init_Arr

integer Output_Init_Arr(integer flags, string axis, string case, enum ResHeader header, integer num1dpos)

Initializes the output array API for a specified case, axis, header and flags.

Returns status

0 – OK

1 – No GSA file is open

3 – Invalid axis

4 – Invalid case

5 – Invalid dataref

Arguments

Flags – Compound flag; valid settings are:

Enum Output_Init_Flags

OP_INIT_2D_BOTTOM = &H1 ' output 2D stresses at bottom layer

OP_INIT_2D_MIDDLE = &H2 ' output 2D stresses at middle layer

OP_INIT_2D_TOP = &H4 ‘ output 2D stresses at top layer

OP_INIT_2D_BENDING = &H8 ' output 2D stresses at bending layer

OP_INIT_2D_AVGE = &H10 ' average 2D element stresses at nodes

OP_INIT_1D_AUTO_PTS = &H20 ' calculate 1D results at interesting points

OP_INIT_INFINITY = &H40 ' return infinity and NaN values as such, else as zero

OP_INIT_1D_WALL_RES_SECONDARY = &H80 ' output secondary stick of wall equivalent beam results, else primary

End Enum

E.g. OP_INIT_2D_TOP Or OP_INIT_2D_AVGE ' 2D stresses at top layer, averaged at nodes

Axis – output axis; enter the name of a standard axis or the number of a user defined axis; examples of valid entries:

Default – The default for the data being extracted

Global

Local

Case – The output case, ignored if not relevant; CasePermString may be used to collate this string; examples of valid entries:

L1

A3

C3

C4max – Assumes C4 is an envelope

C4min – <ditto>

C4abs – <ditto>

C4signabs – <ditto>

C4p3 – <ditto>

Header -- enum of the type, defined by ResHeader

num1dpos – the number of equidistant internal positions along the 1D elements to be considered for 1D element results, in addition to the automatic interesting positions if specified in flags

Note

The Output_Init_Arr and Output_Extract_Arr offer faster, array-based alternatives to the Output family of functions. The difference between the two is that array-based functions work with result headers, and therefore return all components of the requested result type in a single function call. For example, initialising Output_Init_Arr with ResHeader.REF_DISP returns all components of nodal displacements. When working with elements, the array-based functions will retrieve all components along all points along an element.

# Output_Extract_Arr

`integer Output_Extract_Arr(integer id, array results, integer numComponents)'

Returns the output data for a node, element, or member, as an array.

Arguments

id – The entity reference to return results for

Results – Array of struct GsaResults (Output)

numComponents – Number of result components for the header in question (Output)

Note

The function Output_Extract_Arr returns an array of results for the element or node in question. For an element, the results array consists of an array of GsaResults objects. The number of objects returned is equal to one of the following:

Number of intermediate points on 1D elements
Topology points on 2D elements
1 if the entity in question is a node

Each GsaResults object has 2 members

A dynamically allocated array called dynaResults. This contains double values corresponding to results for each component for the given header (as specified in the Output_Init_Arr function).

An integer member NumComponents that contains the number of components in dynaResults.

For e.g. the call

gsaObj.Output_Set_Init(Output_Init_Flags.OP_INIT_1D_AUTO_PTS, "default", "A1", ResHeader.REF_DISP, 2)

Initialises the results API with REF_DISP, the nodal displacements.

From the file Output_DataRef.txt, note that REF_DISP has the following components:

REF_DISP_DX
REF_DISP_DY
REF_DISP_DZ
REF_DISP_TRANS
REF_DISP_RXX
REF_DISP_RYY
REF_DISP_RZZ
REF_DISP_ROT
REF_DISP_DXY

Then, the call

gsaObj.Output_Extract_Arr(iNode, arrRes, numComp)

Populates arrRes with a single struct that contains dynaResults of length 9 and value of NumComponents is set to 9.

The order of components in dynaResults is the same as their order in the DataRef enums.

# Output_Extract_CutAssembly

integer Output_Extract_CutAssembly(integer ref, bool Avg2DStress, string case, string axis, array results)

Fetches Cut section forces results for a given assembly. See documentation for the Cut section forces for more explanation of the parameters.

Arguments

Ref – The assembly reference to extract forces for

Avg2DStress – Use averaged 2D stresses

Disp – if true then displacements are returned, otherwise forces and moments

Case – Case description

Axis – Axis definition

Results – array of GsaResults object where:

For forces and moments, GsaResults.dynaResults stores the Fx, Fy, Fz, |Fyz|, Mxx, Myy, Mzz, |Myz| results in that order.
For displacements, GsaResults.dynaResults stores the Ux, Uy, Uz, |U|, Rxx, Ryy, Rzz, |R| results in that order.
GsaResults.Pos stores the position of the cut.

Note

For example, to extract assembly forces and moments:

Dim results() As GsaResults

gsa.Output_Extract_CutAssembly(1, False, False, "A1", "1", results)

# Case and Task functions

The following functions are for extracting information on GSA load, analysis and combination cases.

# HighestCase

integer HighestCase(string caseop)

Returns the highest numbered case.

Argument

caseop – The type of case; valid entries are:

L – load case

A – analysis case

C – combination case

# CaseExist

integer CaseExist(string caseop, integer id)

Returns 1 if the case exists.

Argument

caseop – The type of case; valid entries are:

L – Load case

A – Analysis case

C – Combination case

id – Case number

# CaseName

string CaseName(string caseop, integer id)

Returns the name of the case as a string.

Argument

caseop – The type of case; valid entries are:

L – Load case

A – Analysis case

C – Combination case

id – Case number

# CaseNumPerm

integer CaseNumPerm(string caseop, integer id)

Returns the number of permutations in the case or 0 if the case is not an enveloping case.

Argument

caseop – The type of case; valid entries are:

A – Analysis case

C – Combination case

ref – Case number

# CasePermDesc

string CasePermDesc(string caseop, integer id, integer perm)

Returns the case description of the case as a string.

Argument

caseop – The type of case; valid entries are:

A – Analysis case

C – Combination case

id – Case number

perm – permutation number or 0

# CasePermString

string CasePermString(string caseop, integer id, integer perm)

Returns the case reference as a string, e.g. C4p3.

Argument

caseop – The type of case; valid entries are:

L – Load case

A – Analysis case

C – Combination case

id – Case number

perm – Permutation number or 0

# CasePermAnalFactor

float CasePermAnalFactor(string caseop, integer id, integer perm, integer analref)

Returns the factor of the specified analysis case that contributes to the specified case reference as a string, e.g. C4p3.

Argument

caseop – The type of case; valid entries are:

A – Analysis case

C – Combination case

id – Case number

perm – Permutation number or 0

analref – The analysis case number; the returned factor of this analysis case contributes to the case specified by caseop, id and perm

# CaseResultsExist

integer CaseResultsExist(string caseop, integer id, integer perm)

Returns 1 if results exist for the case.

Argument

caseop – The type of case; valid entries are:

A – Analysis case

C – Combination case

ref – Case number

perm – Permutation number or 0

# CaseTask

integer CaseTask(integer id)

Returns the reference number of the analysis task that is parent to the analysis case.

id – Analysis case number

# TaskStatus

integer TaskStatus(integer id)

Returns the status of the analysis task.

Returns status

0 – Task exists and has been analysed

1 – No GSA file is open

2 – Task does not exist

3 – Task exists but has not been analysed

Arguments

ref – Analysis task number

# DesignTaskStatus

integer DesignTaskStatus(integer id)

Returns the status of a design task.

Returns status

1 – No file open

2 – Design task does not exist

3 – Design task has results

4 – Design task has not been designed or checked

Argument

id – Design task reference

# List functions

# IsItemIncluded

integer IsItemIncluded(string option, integer id, string list)

Returns 1 is the item reference is included in the list

Arguments

option – Valid settings are:

ITEM – A general list.

NODE – List is a list of nodes.

ELEM – List is a list of elements.

MEMBER – List is a list of members.

CASE – List is a list of cases.

GRID_PT – List is a list of grid points.

ref – Item to be checked for inclusion

list – The list represented by a string (e.g. 1 3 5 or 1 to 10 not 7)

# EntitiesInList

integer EntitiesInList(string lst, ref enum GsaEntity listType, array entities)

Retrieves entities from a list description or a saved list.

Returns status

0 – OK

1 – No GSA file open

2 – Saved list does not exist

3 – No items in the list

Arguments

lst – List description or saved list reference (passed as a string)

listType – input or output parameter of type GsaEntity depending on whether lst is a list description or a saved list.

If lst is a simple description (e.g. 1 to 10), listType is an input parameter specifying the type of list
If lst is a saved list reference (e.g. "1"), listType is an output parameter returning the type of the saved list

arrayEntities – The array of all valid entities in the list. (Output)

# Tool Functions

# Tool_UpdateElemSections

integer Tool_UpdateElemSections()

Returns true if successful

Call this function to update element section properties according to corresponding member’s section properties.

# Tool_ResetMemberSections

integer Tool_ResetMemberSections()

Returns true if successful

Call this function to reset member section properties according to associated elements’ section properties.

# Tool_GetEntLength

double Tool_GetEntLength(integer id, GsaEntity type)

Returns the length of the entity.

Arguments

ref – Entity reference

type – An enum variable of type GsaEntity

# Utility functions

# SetLocale

short SetLocale(Locale locale)

Set the locale for Decimal and List Separators for use by the GwaCommand function.

Arguments

option – enum of type Locale. Valid options are:

LOC_SYSTEM – Use the system default setting.

LOC_EN_GB – Use English.(‘,’ and ‘.’)

Returns status

0 – OK

1 – Invalid Locale

The Locale setting is culture and language dependent and varies from one machine to the other. GwaCommand strings use decimal and list separators for input and output. Call this function to set GwaCommand to operator in a locale independent way.

# NumArg

integer NumArg(string line)

Returns the number of arguments in a line

Argument

line – A string of comma separated arguments

For example NODE, 25, 10, 4.5, 8 would return 5

# Arg

string Arg(integer index, string line)

Returns as a string the argument at the index position in the line

Argument

index – Index in line (zero based)

line – The line to be decoded

For example, the third argument from NODE, 25, 10, 4.5, 8 would return 4.5

# sID functions

Sid for each module record can be set and read though the GwaCommand using their format in GWA files. But this requires a lot of string parsing and hence the following functions are provided to set and get sIDs directly for each valid module record. For more information on sIDs, refer to String IDs

# WriteSidTagValue

integer WriteSidTagValue(string key, integer record, string tag, string value)

Writes a Tag-Value pair to the sid of the module record specified.

Returns status

0 – OK, successfully written

1 – Otherwise

Arguments

key – The keyword of the module

record – The index of the record

tag – The tag to be written to the sid

value – The value associated with the above tag

This function writes a tag-value pair if none exists inside the sid of the record. If there’s already a tag present, the associated value is overwritten with the new value: e.g.(VB .NET)

Dim iSuccess as Integer = gsaObj.WriteSidTagValue("SEC_BEAM", 12, "RVT", "Structural Framing - W44x285")

# GetSidTagValue

string GetSidTagValue(string key, integer record, string tag)

Returns the value for a tag stored inside the sid of the module record specified

Arguments

key – The keyword of the module

record – The index of the record

tag – The tag for which value is to be retrieved from the sid

An example of usage (VB .NET)

Dim sValue as String = gsaObj.GetSidTagValue("MEMBER", 3, "RVT")

Note

The WriteSidTagValue function sets the sid in the standard format specified in the documentation. Consequently the GetSidTagValue retrieves a value from sid only if it is in the same format.

Keyword for model sid is SID.

An authoring application using the sid feature must write a model sid. Otherwise sids written to module records will not persist.

It’s the authoring application’s responsibility to ensure that the record exists for the module on which it is being called – otherwise GSA might throw an exception.

# ExportToCsv

integer ExportToCsv(string pathname, integer numPoint, bool interestingPoints, bool combinations, string delimiter)

Exports model and results (if present) as a series of csv files.

Returns status

0 – OK, successfully written

1 – No GSA file

2 – Failure to export

Arguments

pathname – The path to the GSA file

numPoint – The number of result point along beams (2 for just end points)

interestingPoints – Export interesting points along beams

combinations – Export combination cases

delimiter – The field delimiter (normally a comma)

Note

The ExportToCsv function creates a csv file for each table. This is documented in the GSA Export manual (opens new window).

# Structs

These structs are used as arguments by various functions. The text in the brackets after each field provides an explanation of the field.

# GsaViewOrientation

Latitude (Direction of view – Latitute)

Longitude (Direction of view - Longitude)

EyeDistance (Eye to object distance)

ObjectPoint (Object point coordinates as array of doubles)

MidPoint (Mid-point coordinates as array of doubles)

PictureRotation (Picture rotation)

# GsaResults

NumComponents (Number of components available)

dynaResults() (Dynamic array of doubles)

Pos (Position of the cut -- applicable to Cut Section results only)

# GsaElement

Ref (Reference)

Name

Color

eType (Element type)

Property (Property reference)

Group (Group reference)

NumTopo (Number of topology nodes)

Topo() (Topology as an array of node references)

Beta (Orientation angle)

OrientNode (Orientation node)

Dummy (Dummy status)

# GsaNode

Ref (Reference)

Name

Color

Coor() (Coordinates X, Y and Z as array of doubles)

Restraint (Nodal restraints as integer values)

Stiffness() (Stiffnesses in X, Y, Z, XX, YY, ZZ as array of doubles)

# GsaSection

Ref (Reference)

Name

Color

SectDesc (Section description string)

Material (Analysis material)

eMatType (Material type – read-only)

MaterialGrade (Design material)

Props() (Properties – read-only)

# GsaMember

Ref (Reference)

Name

Color

Property (Property reference)

Group (Group)

Pool (Pool)

NumTopo (Number of topology nodes)

Topo() (Topology as an array of node references)

Beta (Orientation angle)

OrientNode (Orientation node)

MemberEnd_1 (Member end condition End 1)

MemberEnd_2 (Member end condition End 2)

# Early and Late Binding

In simplest terms, early and late binding refer to when COM programmers choose to let the compiler know that the object created is of type Gsa.ComAuto.

In early binding, the object is declared to be of type Gsa.ComAuto and then invoked . Early binders will always need to refer to a version specific COM class.

Dim gsaObj As Gsa_10_1.ComAuto  
Set gsaObj = New Gsa_10_1.ComAuto

In late binding, the object is simply declared to be of the type Object and it’s only when the code is run does the compiler know that it belongs to the type Gsa.ComAuto.

To invoke the current version of GSA:

Dim gsaObj As Object  
Set gsaObj = CreateObject("Gsa.ComAuto")

To invoke a verson specific class:

Dim gsaObj As Object
Set gsaObj = CreateObject("Gsa_8_4.ComAuto.1")

When a particular approach is to be adopted over the other depends on particular needs (see reference 2) but broadly late binding allows for the code to be set up and prototyped quickly and is recommended if the programmer doesn’t want to be bothered with the version of GSA being used. Early binding on the other hand lets the code run faster and gives a better handle on the version of class being invoked.

(To make an older version current, simply run the GSA.exe in the program files folder of the particular version.)

References:

https://docs.microsoft.com/en-us/dotnet/visual-basic/programming-guide/language-features/early-late-binding/ (opens new window)

http://support.microsoft.com/kb/245115 (opens new window)

: Compiler/interpreter. In case of Excel, it’s VBA.

: In VBA, this must be preceded by adding a reference to Gsa.tlb, from Tools > References. Gsa.tlb can be found in the GSA program files folder. Other IDE’s have equivalent methods.

# Enums

For details of the COM API enums see the GSA Output Data Reference.

# Samples

# Excel/VBA

The following is an example of invoking the GSA API from VBA script.

Sub RunGsa2()  
Dim iName0, iName1, iName2 As String  
 Dim GsaAuto As Object  
 Set GsaAuto = CreateObject("Gsa.ComAuto")  
iName0 = "C:\Temp\gsa_com0.gwa"  
iName1 = "C:\Temp\gsa_com1.gwa"  
iName2 = "C:\Temp\gsa_com2.gwb"  
GsaAuto.Open (iName0)  
GsaAuto.Analyse  
GsaAuto.Save  
GsaAuto.PrintView ("TAGGED_SGV")  
GsaAuto.Delete ("RESULTS")  
GsaAuto.SaveAs (iName1)  
GsaAuto.Delete ("RESULTS_AND_CASES")  
GsaAuto.SaveAs (iName2)  
GsaAuto.Close  
 Set GsaAuto = Nothing  
End Sub

# COM C++ Example

The following is an example C++ code to run GSA remotely.

if(FAILED(CoInitializeEx(0, COINIT_APARTMENTTHREADED)))
    return;

IComAutoPtr pObj(\_\_uuidof(ComAuto));
short ret_code = 0;

\_bstr_t bsFileName = (LPCTSTR)filename;
ret_code = pObj-\>Open(bsFileName);
if(ret_code ==1)
    return;

\_bstr_t bsContent(\_T("RESULTS"));
ret_code = pObj-\>Delete(bsContent);
ASSERT(ret_code != 1); // file not open!

\_variant_t vCase(0L);
ret_code = pObj-\>Analyse(vCase);
ASSERT(ret_code ==0);
\_bstr_t bsAnalysedFileName = (LPCTSTR)analysed_filename;
ret_code = pObj-\>SaveAs(bsAnalysedFileName);
ASSERT(ret_code ==0);
pObj-\>Close();

For other samples see https://github.com/arup-group/oasys-api-samples (opens new window)

← Tab and Comma Separated Files GSA COM Output Data Reference →