The following chapter is available only in English.

COM interface

This chapter is intended for programmers who will create extension (add-on) modules for SCIA Engineer.

Any programming language that supports COM objects can be utilised. So far the feature was tested with Visual C++ and Visual Basic.

Functions will be written using the syntax of IDL language.

The interface is put directly into two libraries.

EP_XmlProject

It is stored in module EP_XmlProject_09.dll.

It contains objects and functions for the initialisation of SCIA Engineer environment and function for handling the ESA project.

These are the following objects and their interface:

Object CLSID_ EPX_App

Interface EPX_App - initialises some important services of the program, such as module protection, languages, etc.

interface IEPX_App : IDispatch

{

[id(1)] HRESULT Initialize([in]long flag,[out]long *bOk);

// initialises the environment

// flag – type of initialisation, currently the only correct value is 0

//bOk – Boolean return value, can be 0 or 1

[id(2] HRESULT Close();

//closes the environment

};

Object CLSID_EPX_Project

Interface IEPX_Project – handles file „.esa“, such as open project, close project, create project, run calculation, etc.

interface IEPX_Project : IDispatch

{

[id(1)] HRESULT Initialize([in]BSTR TempDir);

// initialisation, must be performed every time after the creation of an object

// TempDir – path to the folder where project temporary data will be stored, NULL adjust the path to the temporary folder of ESA

[id(2)] HRESULT New([out] long *bOk);

// creates a new empty project

// bOk – Boolean return value, can be 0 or 1

[id(3)] HRESULT Open([in]BSTR fileName, [out] long *bOk);

// opens a saved project from the disk

// fileName – filename including the path

// bOk – Boolean return value, can be 0 or 1

[id(4)] HRESULT Save([out] long *bOk);

// saves the opened project into a file on the disk, cannot be used for a new project

// bOk – Boolean return value, can be 0 or 1

[id(5)] HRESULT SaveAs([in]BSTR fileName, [out] long *bOk);

// saves the opened project into a file on the disk under given name, the only way to save a new project

// fileName - filename including the path

// bOk – Boolean return value, can be 0 or 1

[id(6)] HRESULT Close();

// closes the project

[propget, id(7)] HRESULT ErrorMessage([out, retval] BSTR *pVal);

// returns the text of last generated error if the return value of any flag was equal to 1

// pVal – error text

[propget, id(8)] HRESULT DataServer([out, retval] IEPX_DataServer* *pVal);

// returns D object, the object is necessary for a direct reading and writing of project data

// pVal – interface of data server

[id(9)] HRESULT Calculate([in]BSTR type, [out] long *bOk);

// runs the calculation

// type – calculation type

LIN – linear

NEL – nonlinear

CSS – calculates the characteristics of all cross-sections

[id(10)] HRESULT Output([in]BSTR type,[in]BSTR fileName,[in]BSTR nameDoc,[out]long *bOk);

// performs the output of the document that is created in project data

// type – file type

TXT - ASCI file

HTML – file (HyperText Markup Language)

PDF – file(Acrobat reader)

RTF – file(Rich Text Format)

XML – file(eXtensible Markup Language)

// fileName – name of the file into which the output will be performed

// nameDoc – name of the document that will be used for the output, if no name is given, empty text or NULL, the default document is used

// bOk – Boolean return value, can be 0 or 1

[propget, id(11)] HRESULT FileName([out, retval] BSTR *pVal);

// returns the current name of the project

// pVal – project name

[id(12)] HRESULT RemoveResults();

// deletes the result s of the calculation

[id(13)] HRESULT UpdateFromXmlFile([in]BSTR xmlFile,[out]long *bOk);

// reads XML file in SCIA Engineer format and uses its contents to modify the data of the project

// xmlFile -name of XMLfile

// bOk – Boolean return value, can be 0 or 1

[id(14)] HRESULT NewFromXmlFile([in]BSTR xmlFile,[out]long *bOk);

// reads XML file in SCIA Engineer format and uses its contents to create a new project

// xmlFile -name of XMLfile

// bOk – Boolean return value, can be 0 or 1

[id(15)} HRESULT DlgLibManager([in]BSTR CoId);

// opens the container dialogue of library type. If the container is not of library type, nothing happens.

// the information if the container is of this type can be found in the definition file

// element „def_containr“ attribute „lib“ value „yes“

// e.g. materials, cross-sections, bolts, etc..

};

EP_XmlExchange

Located in module EP_XmlExchange_09.dll.

It contains objects and functions providing for direct handling of SCIA Engineer project database. In this chapter it will be referred to as Data server and abbreviation DS will be used.

These are the following objects and their interface:

Object CLSID_ EPX_DataServer

Interface IEPX_DataServer – system functions that configure DS,

interface IEPX_DataServer : IUnknown

{

[propget] HRESULT DsHandler([out, retval] IUnknown* *pVal);

// returns an object of the internal database that is used by developers of SCIA Engineer program

HRESULT ConnectDsHandler([in] IUnknown* newVal);

// connects an object of the internal database

HRESULT DisconnectDsHandler();

// disconnects an object of the internal database

[propput] HRESULT Event([in] IEPX_Event* newVal);

[propput] HRESULT EventDOM([in] IEPX_EventDOM* newVal);

// connects interface to obtain messages about changes to DS

only one type can be registered

// details – see description of interface IEPX_Event and IEPX_EventDOM

[propput] HRESULT EventFilter([in] VARIANT newVal);

// it is possible to limit the amount of date that will bi end through IEPX_Event.

// newVal – list of Ids of containers whose changes will be registered in event

VARIANT newVal

IUnknown* = DOM

BSTR = text

XML node under the following specification

<list_filter>

<container_F9013B7B-A5F6-4813-A986-1A699173F690 />

......

</list_filter>

[propget] HRESULT ErrorMessage([out, retval] BSTR *pVal);

// returns an error message

// pVal – error text

HRESULT RefreshEvent();

// this function enforces sending of an event

};

Interface IEPX_Event – receives the information about changes in DS in text format

interface IEPX_Event : IUnknown

{

HRESULT OnPreUpdate(IUnknown *ds,BSTR New,BSTR Modif,BSTR Delete);

// the message is sent prior to changes to DS, it is still possible to perform changes to DS

// ds –DS object

HRESULT OnPostUpdate(BSTR New,BSTR Modif,BSTR Delete);

// the message is sent after the changes to DS has been made, it is forbidden to perform changes to DS

// New = list of new objects

// Modif = list of changed objects

// Delete = list of deleted objects

// the list is in this format

<list_event>

<container_F9013B7B-A5F6-4813-A986-1A699173F690>

........

<container_F9013B7B-A5F6-4813-A986-1A699173F690>

..........

</list_event>

};

Interface IEPX_EventDOM – receives the information about changes in DS in the format of DOM object

Function interfaces have the same functionality as in interface IEPX_Event, the only difference is that the information is stored in DOM object.

interface IEPX_EventDOM : IUnknown

{

HRESULT OnPreUpdate(IUnknown *ds,IUnknown *New,IUnknown *Modif,IUnknown *Delete);

HRESULT OnPostUpdate(IUnknown *New,IUnknown *Modif,IUnknown *Delete);

};

Interface IEPX_Handler – function providing for direct reading and writing from and into ESA database.

interface IEPX_Handler : IUnknown

{

HRESULT putDefinitionURL([in]BSTR url,[in]long bRewrite,[out]long *bOk);

// reading of definition file

// url – name of definition file

// bRewrite – determines whether the previously read definition should be overwritten

// bOk – Boolean return value, can be 0 or 1

HRESULT putDefinition([in]BSTR src,[in]long bRewrite,[out]long *bOk);

// reading the definition from text

HRESULT putDefinitionDOM([in]IUnknown *src,[in]long bRewrite,[out]long *bOk);

// reading the definition from DOM object

HRESULT getBuffer([out]IEPX_Buffer **pVal);

// takes data from the stack for writing, there is just one the object of the stack

// pVal – return the object of the stack

HRESULT putBuffer([out]BSTR *res,[out]long *bOk);

// writes the contents of the stack into DS

// res – text, returns the information about new objects

// bOk – Boolean return value, can be 0 or 1

HRESULT putBufferDOM([out]IUnknown* *res,[out]long *bOk);

// writes the contents of the stack into DS

// res – DOM, returns the information about new objects

// bOk – Boolean return value, can be 0 or 1

// information about new entities is in this format

<list_new>

<container_F9013B7B-A5F6-4813-A986-1A699173F690>

......

</container_F9013B7B-A5F6-4813-A986-1A699173F690>

......

</list_new>

HRESULT getContainer([in]GUID *conId,[in]VARIANT tabId,[out]BSTR *pVal);// returns information about the whole container

// conId – container identificator

// tabId – table identification

// pVal – final information, text in XML format, the of the main element is list_obj

VARIANT tabId

VT_BSTR – text, attribute id in table definition

If the text is in XML format (begins with character ‘<’), the final XML is formatted according to the list of properties, see format list_propid

<list_propid>

<pid id="{27C6E231-AE20-487a-A920-603BB0BC9908}"/>........

</list_propid>

VT_UNKNOWN

VT_DISPATCH- DOMDocument – as list_propid

NULL , or empty list_propid , only a list of container objects is created, without properties

HRESULT getContainerDOM([in]GUID *conId,[in]VARIANT tabId,[out]IUnknown* *pVal);

/ / the difference is that the result is DOM object

HRESULT getProperties([in]GUID *conId,[in]VARIANT tabId,[in]long ObjId,[out]BSTR *pVal);

HRESULT getPropertiesDOM([in]GUID *conId,[in]VARIANT tabId,[in]long ObjId,[out]IUnknown* *pVal);

HRESULT getPropertiesNm([in]GUID *conId,[in]VARIANT tabId,[in]BSTR ObjNm,[out]BSTR *pVal);

HRESULT getPropertiesNmDOM([in]GUID *conId,[in]VARIANT tabId,[in]BSTR ObjNm,[out]IUnknown* *pVal);

// all functions getProperties return list of properties of the defined object

// functions that have „Nm“ in the name text identify the object only by its name, other functions identify by object number

// functions ending with DOM return the result in an object, other return it as text

// main element’s name is list_prop

// conId – container identifier

// tabId – table identifier, format explained in previous function

// ObjNm,ObjId – object identifier

// pVal – result value

HRESULT getProperty([in]GUID *conId,[in]BSTR tabId,[in]long ObjId,[in]short i,[out]BSTR *pVal);

HRESULT getPropertyDOM([in]GUID *conId,[in]BSTR tabId,[in]long ObjId,[in]short i,[out]IUnknown* *pVal);

HRESULT getPropertyNm([in]GUID *conId,[in]BSTR tabId,[in]BSTR ObjNm,[in]short i,[out]BSTR *pVal);

HRESULT getPropertyNmDOM([in]GUID *conId,[in]BSTR tabId,[in]BSTR ObjNm,[in]short i,[out]IUnknown* *pVal);

// all functions getProperty return the value of one property

// functions that have „Nm“ in the name text identify the object only by its name, other functions identify by object number

// functions ending with DOM return the result in an object, other return it as text

// conId – container identifier

// tabId – table identifier, format explained in previous function

// ObjNm,ObjId – object identifier

// i – index of property in the table

// pVal – result value

HRESULT getObjCLSID([in]GUID *conId,[in]long ObjId,[out]GUID *pVal);

HRESULT getObjCLSIDNm([in]GUID *conId,[in]BSTR ObjNm,[out]GUID *pVal);

// returns CLSID of the object

};

Interface IEPX_VB_Handler – this interface is optimised for use in Visual Basic and its function have the same functionality as functions in IEPX_Handler interface

Interface IEPX_Buffer – functions provide for management of stack of changes

interface IEPX_Buffer : IUnknown

{

HRESULT putProjectURL([in]BSTR prjfile,[in]long action);

HRESULT putProject([in]BSTR projectList,[in]long action);

HRESULT putProjectDOM([in]IUnknown* projectList,[in]long action);

// reads data from XML that is in the format created by ESA during the export to XML

// main element, must be „projeck“

// action – 0 performs the following action, objects are overwritten, new ones are created, the rest remains as is

// - 1the same as above, BUT objects that aro not to be changed will be deleted, valid only for containers stored in the input XML, the rest remains as is

// - 2everything that does not have the identification by name is added as new, number references must refer to existing entities only

HRESULT objDelete([in]GUID *conId,[in]long Id);

HRESULT objDeleteNm([in]GUID *conId,[in]BSTR Nm);

// deletes object

// conId – container identifier

// Id- object identifier

// Nm – object name

HRESULT objNew([in]GUID *conId,[in]BSTR tabId,[in]BSTR propList,[out]long *tempId);

HRESULT objNewDOM([in]GUID *conId,[in]BSTR tabId,[in]IUnknown *propList,[out]long *tempId);

HRESULT objNewNm([in]GUID *conId,[in]BSTR tabId,[in]BSTR propList,[in]BSTR Nm);

HRESULT objNewNmDOM([in]GUID *conId,[in]BSTR tabId,[in]IUnknown *propList,[in]BSTR Nm);

// creates a new object and writes into it values read from the element „list_prop“

<list_prop>

.......

</list_prop>

// conId – container identifier

// tabId – table identifier

// propList – initialisation values

// tempId – temporary identifier, can be used in identification of reference within one filling of the stack

// Nm – name for the new object

HRESULT objRewrite([in]GUID *conId,[in]BSTR tabId,[in]long ObjId,[in]BSTR propList);

HRESULT objRewriteDOM([in]GUID *conId,[in]BSTR tabId,[in]long ObjId,[in]IUnknown *propList);

HRESULT objRewriteNm([in]GUID *conId,[in]BSTR tabId,[in]BSTR Nm,[in]BSTR propList);

HRESULT objRewriteNmDOM([in]GUID *conId,[in]BSTR tabId,[in]BSTR Nm,[in]IUnknown *propList);

// rewrites data in the existing object

// conId – container identifier

// tabId - table identifier

// propList – new values, main element must be „list_prop“

// ObjId- object identifier

// Nm – object name

HRESULT conRewrite([in]GUID *conId,[in]BSTR tabId,[in]BSTR objList);

HRESULT conRewriteDOM([in]GUID *conId,[in]BSTR tabId,[in]IUnknown *objList);

// rewrites data in specified objects of the container

// conId – container identifier

// tabId - table identifier

// propList – new values, main element must be „list_obj“

<list_obj>

.......

</list_obj>

objects can be identified by both name and ID

};

Interface IEPX_VB_Buffer – this interface is optimised for use in Visual Basic and its function have the same functionality as functions in IEPX_Buffer interface

Object CLSID_ EPX_BufferDOM

Interface IEPX_BufferDOM – this is an object that facilitates write operation for XML in SCIA Engineer format.

Every function creates the necessary node, including attributes.

Normally used variables

// ni – node into which the information is written, if it is NULL then a new root is created on the nearest level

// nr – created node, as return value

interface IEPX_BufferDOM : IUnknown

{

[propget] HRESULT DettachDOM([out, retval] IUnknown * *pVal);

// draws object DOMDocument, this function is performed as the last operation

HRESULT XmlElement([in]IUnknown *ni,[in]BSTR name,[out]IUnknown **nr);

// creates one new XML element

// name – element name

HRESULT XmlAttribute([in]IUnknown *ni,[in]BSTR name,[in]BSTR value);

HRESULT XmlAttributeI([in]IUnknown *ni,[in]BSTR name,[in]long value);

HRESULT XmlAttributeD([in]IUnknown *ni,[in]BSTR name,[in]double value);

// creates a new attribute

// name – attribute name

// value- attribute value

HRESULT AddDOM([in]IUnknown *ni,[in]IUnknown *dom);

// adds DOMDocument object

HRESULT Project([in]BSTR uriDef,[out]IUnknown **nr);

// creates element „project“ and simultaneously adds attribute specifying path to the definition file

// uriDef – name of definition file

HRESULT Container([in]IUnknown *ni,[in]GUID *coid,[in]BSTR tabid,[in]BSTR txt,[out]IUnknown **nr);

HRESULT ContainerVB([in]IUnknown *ni,[in]BSTR coid,[in]BSTR tabid,[in]BSTR txt,[out]IUnknown **nr);

// creates element „container“ and simultaneously element „table“ including all necessary attribute

// coid – container identifier

// tabid – identification of table by name

// txt – note

HRESULT Object([in]IUnknown *ni,[in]long idobj,[in]BSTR name,[out]IUnknown **nr);

// creates element „obj“

// idobj – object identification, if equal to -1 attribute is not created

// name – object name, if NUUL or empty text,attribute is not created

HRESULT TableRow([in]IUnknown *ni,[in]long id,[out]IUnknown **nr);

// creates element „row“ as a row of internal table

// individual functions for creation of element by value type

// normally used parameters

// id – property number, defined according to definition file

// inx – index for indexed property, attribute „i“ created if its value is not zero

// other parameters as in chapter 6.Popis formátu SCIA Engineer XML

HRESULT PropString([in]IUnknown *ni,[in]long id,[in]long inx,[in]BSTR v);

HRESULT PropBool([in]IUnknown *ni,[in]long id,[in]long inx,[in]long v);

HRESULT PropEnum([in]IUnknown *ni,[in]long id,[in]long inx,[in]long v,[in]BSTR t);

HRESULT PropInteger([in]IUnknown *ni,[in]long id,[in]long inx,[in]long v);

HRESULT PropParamValue([in]IUnknown *ni,[in]long id,[in]long inx,[in]double v);

HRESULT PropParamRef([in]IUnknown *ni,[in]long id,[in]long inx,[in]long i,[in]BSTR t);

HRESULT PropRef([in]IUnknown *ni,[in]long id,[in]long inx,[in]long i,[in]BSTR t);

HRESULT PropTable([in]IUnknown *ni,[in]long id,[in]long inx,[in]BSTR t,[out]IUnknown **nr);

HRESULT PropReal([in]IUnknown *ni,[in]long id,[in]long inx,[in]double v);

HRESULT PropReal2([in]IUnknown *ni,[in]long id,[in]long inx,[in]double v1,[in]double v2);

HRESULT PropReal3([in]IUnknown *ni,[in]long id,[in]long inx,[in]double v1,[in]double v2,[in]double v3);

// creates end-nodes of data

// example PropEnum(ni,3,0,12,”hello” );

//result <p3 v=”12” t=”hello”/>

HRESULT XmlElementProp([in]IUnknown *ni,[in]long id,[in]long inx,[out]IUnknown **nr);

// creates a node for the property without attributes

};