msc.mvision database programmatic interface

118
MSC.Mvision Database Programmatic Interface User’s Guide and Reference

Upload: joshkuhlmann

Post on 17-Nov-2014

133 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: MSC.mvision Database Programmatic Interface

MSC.Mvision Database Programmatic Interface

User’s Guide and Reference

Page 2: MSC.mvision Database Programmatic Interface

CorporateMSC.Software Corporation2 MacArthur PlaceSanta Ana, CA 92707 USATelephone: (800) 345-2078Fax: (714) 784-4056

EuropeMSC.Software GmbHAm Moosfeld 1381829 Munich, GermanyTelephone: (49) (89) 43 19 87 0Fax: (49) (89) 43 61 71 6

Asia PacificMSC.Software Japan Ltd.Entsuji-Gadelius Building2-39, Akasaka 5-chomeMinato-ku, Tokyo 107-0052, JapanTelephone: (81) (3) 3505 0266Fax: (81) (3) 3505 0914

Worldwide Webwww.mscsoftware.com

Disclaimer

MSC.Software Corporation reserves the right to make changes in specifications and other information contained in this document without prior notice.

The concepts, methods, and examples presented in this text are for illustrative and educational purposes only, and are not intended to be exhaustive or to apply to any particular engineering problem or design. MSC.Software Corporation assumes no liability or responsibility to any person or company for direct or indirect damages resulting from the use of any information contained herein.

User Documentation: Copyright 2002 MSC.Software Corporation. Printed in U.S.A. All Rights Reserved.

This notice shall be marked on any reproduction of this documentation, in whole or in part. Any reproduction or distribution of this document, in whole or in part, without the prior written consent of MSC.Software Corporation is prohibited.

MSC is a registered trademark and service mark of MSC.Software Corporation. Mvision and Patran are registered trademarks of MSC.Software Corporation.

MSC.Enterprise Mvision, MSC.Mvision, MSC.Mvision Builder, MSC.Mvision Evaluator, MSC.Mvision Pro, MSC.Patran and MSC. are trademarks of MSC.Software Corporation.

NASTRAN is a registered trademark of the National Aeronautics and Space Administration. MSC.Nastran is an enhanced proprietary version developed and maintained by MSC.Software Corporation. All other products are identified by the trademarks of their respective companies or organizations.

MV*V2002*Z*Z*Z*DC-903042

Page 3: MSC.mvision Database Programmatic Interface

C O N T E N T SMSC.Mvision Builder and Evaluator 2002 Installation Guide

1Introduction ■ DPI User’s Guide and Reference, 6

■ MSC.Mvision Products, 7

■ Technical Support, 9

■ Overview of the DPI — The Object Paradigm, 10

■ DPI and Objects, 11

■ Methods of Database Access, 13❑ Typical Query Access (Navigating), 13❑ Typical Select Access (Making Tables), 14

■ A Brief Example of Select, 16

■ Code Required for All DPI Programs, 19

2Object Types, Expressions and Functions

■ Object Types, 23

■ Functions, 29

■ Access Codes for GrGetValue Function, 39

■ Expressions, 48

■ Expression Syntax and Arguments, 50

■ Forming Expressions, 53❑ Valid Characters and Number Formats, 53❑ Comparison Operators, 54❑ Logical Operators, 55❑ Expression Functions, 55❑ Iterators and “Smart” functions, 61❑ Expression Messages, 64❑ Expression Data Structure, 68

3Query - Navigating With DPI

■ Query Syntax and Function, 72

Page 4: MSC.mvision Database Programmatic Interface

■ Example - Reading A Hierarchy, 73

■ Example - Navigating A Hierarchy, 77

4Select - Making Tables With DPI

■ Select Syntax and Function, 82

■ Example - Selecting Tabular Data, 85

5Write Functions ■ Initializing DPI Write Functions, 88

■ DPI Write Data Functions, 88

■ DPI Write Schema Functions, 94

■ Example of a DPI Write Program, 101

AError Messages ■ General Error Conditions, 106

■ Mathematical Error Conditions, 114

Page 5: MSC.mvision Database Programmatic Interface

MSC.Mvision Database Programmatic Interface User’s Guide and Reference

1 Introduction

■ DPI User’s Guide and Reference

■ MSC.Mvision Products

■ Technical Support

■ Overview of the DPI — The Object Paradigm

■ DPI and Objects

■ Methods of Database Access

■ A Brief Example of Select

■ Code Required for All DPI Programs

Page 6: MSC.mvision Database Programmatic Interface

6

The MSC.Mvision Database Programmatic Interface (DPI) consists of a library of C routines which access MSC.Mvision databanks. This library can be incorporated into user-written programs. This document contains a description of the functional interface and a set of examples demonstrating how to use the DPI to access MSC.Mvision databanks.

1.1 DPI User’s Guide and ReferenceMSC.Mvision Builder and Evaluator User’s Guide and Reference contains all the information necessary to use MSC.Mvision Builder and MSC.Mvision Evaluator software products for the management of materials data. The MSC.Mvision Builder product has features and functions for building MSC.Mvision databanks. These features are described in a separate document titled, MSC.Mvision Building Databanks.

The MSC.Mvision Database Programmatic Interface User’s Guide and Reference consists of the following chapters and appendices:

• Introduction (Chapter. 1) introduces the MSC.Mvision product line and user’s manuals, provides customer support information and includes an overview of the DPI.

• Object Types, Expressions and Functions (Chapter. 2) describes the three basic components: objects, expressions, and functions. MSC.Mvision DPI programs use these three components to access different parts of a database.

• Query - Navigating With DPI (Chapter. 3) details the query syntax and function and gives examples for reading and navigating a hierarchy.

• Select - Making Tables With DPI (Chapter. 4) describes the syntax and function and gives you an example for selecting tabular data.

• Write Functions (Chapter. 5) describes how to initialize the DPI Write functions, how to write data and schema functions and gives an example of a DPI write program.

• Error Messages (Appendix. A) describes the error conditions that are generated by the error handling macro.

Page 7: MSC.mvision Database Programmatic Interface

7CHAPTER 1Introduction

1.2 MSC.Mvision Products The MSC.Mvision Materials Information System currently offers the following products.

• MSC.Mvision Builder

Easy-to-use tool enabling users to create a customized materials information system.

• MSC.Enterprise Mvision

Global web-based access to engineering knowledge.

• MSC.Mvision Evaluator

Stand-alone software to access and work with MSC.Software-supplied or user-created materials databanks.

• MSC.Patran Materials

Direct access to MSC.Mvision materials databanks for the Patran3 analysis system.

• MSC.Mvision Pro

Direct access to MSC.Mvision materials databanks for the Pro/ENGINEER CAD system.

• MSC.Mvision Database Programmatic Interface

Direct access to MSC.Mvision materials databanks for user programs.

• Standards Databanks

• MIL-HDBK-5 Databank (Metals)

• MIL-HDBK-17 Databank (Composites)

• PMC-90 Databank (Advanced Composites)

• Producer Databanks

• Plastics Databank

• Metals Databank

• Composites Databank

• Ceramics Databank

• GE Plastics Databank (FREE license)

• Plastics Design Library

• Chemical and Environmental Compatibility Databank

• The Effects of Creep Databank

• ASM Reference Library

Page 8: MSC.mvision Database Programmatic Interface

8

• Structural Steels Databank

• Stainless Steels Databank

• General Materials Properties Databank

• Materials Selector Databank (based on Machine Design magazine Material Selector Issue)

• MSC.Software Analysis Databank

MSC.Patran

Materials™

MSC.Mvision

Evaluator™

Analysis

Design andManufacturing

MSC.Mvision Pro™

CAD Design

MSC.Mvision Builder™

Overview of MSC.Mvision Product Line

ProgrammaticAccess

MSC.Mvision

DPI™

MSC.Mvision Tool-kit™

MaterialsAuthority

• Materials Test• Corp. Knowledge• Design Allowables

• Producers• Standards• Reference• CrossReference

Databanks

MSC-Supplied

Customer-

(Materials Libraries)

Page 9: MSC.mvision Database Programmatic Interface

9CHAPTER 1Introduction

1.3 Technical SupportFor help with installing or using an MSC.Software product, contact your local technical support services. Our technical support provides the following services:

• Resolution of installation problems• Advice on specific analysis capabilities• Advice on modeling techniques• Resolution of specific analysis problems (e.g., fatal messages)• Verification of code error.

If you have concerns about an analysis, we suggest that you contact us at an early stage.

You can reach technical support services on the web, by telephone, or e-mail:

Web Go to the MSC.Software website at www.mscsoftware.com, and click on Support. Here, you can find a wide variety of support resources including application examples, technical application notes, available training courses, and documentation updates at the MSC.Software Training, Technical Support, and Documentation web page.

Phone and Fax

Email Send a detailed description of the problem to [email protected] You should receive an acknowledgement

United StatesTelephone: (800) 732-7284Fax: (714) 784-4343

Frimley, CamberleySurrey, United KingdomTelephone: (44) (1276) 67 10 00Fax: (44) (1276) 69 11 11

Munich, GermanyTelephone: (49) (89) 43 19 87 0Fax: (49) (89) 43 61 71 6

Tokyo, JapanTelephone: (81) (3) 3505 02 66Fax: (81) (3) 3505 09 14

Rome, ItalyTelephone: (390) (6) 5 91 64 50Fax: (390) (6) 5 91 25 05

Paris, FranceTelephone: (33) (1) 69 36 69 36Fax: (33) (1) 69 36 45 17

Moscow, RussiaTelephone: (7) (095) 236 6177Fax: (7) (095) 236 9762

Gouda, The NetherlandsTelephone: (31) (18) 2543700Fax: (31) (18) 2543707

Madrid, SpainTelephone: (34) (91) 5560919Fax: (34) (91) 5567280

Page 10: MSC.mvision Database Programmatic Interface

0

1.4 Overview of the DPI — The Object ParadigmThe MSC.Mvision Materials Information System employs a user-defined hierarchial interface which is well suited to the display of materials information. Materials information and much general engineering information has a detailed pedigree associated with the information. Typical materials test data have a rich test history that includes the form of the test specimen (bar, sheet, laminate, etc.), the test environment, the test machinery and set-up, the number of specimens tested, and much more. A hierarchy organizes and presents this information very effectively and is a familiar concept to most engineers.

Most relational database systems offer database access through Structured Query Language (SQL). Although versatile and powerful, relational database systems and SQL are not easily mastered. SQL has many advantages and indeed much of the MSC.Mvision Database Programmatic Interface (DPI) syntax is based on standard SQL functions. However, SQL does not offer the flexibility of modern object-oriented approaches. The MSC.Mvision Materials Information System combines both the object-oriented approach and SQL.

Page 11: MSC.mvision Database Programmatic Interface

11CHAPTER 1Introduction

1.5 DPI and ObjectsThe DPI accesses MSC.Mvision databases in an object-oriented manner. The types of objects accessible though the DPI include databases, unit systems, tables, attributes, rows in tables, attribute values, etc. The object types are described in Object Types, Expressions and Functions (Chapter. 2).

Using the interface functions defined in Functions (p. 29), a user can locate objects within an MSC.Mvision database via an object handle. An object handle is represented in a user’s program by a variable declared to be of type GrData. For example, the function GrConnectToDatabase gives the user a handle on the database being connected. This is done by passing in the address of a variable declared to be of type GrData which is filled out with the handle to the database object.

Another way to obtain a handle on an object is to create an expression using the function GrExpression. The GrExpression function parses an expression string (syntax given in Functions (p. 29)) and stores the expression in a GrData variable. When the expression is evaluated, it is evaluated in the context of a particular object. For example, a query expression can be evaluated on a database or on a list that resulted from a prior query. You can think of an expression as a message sent to any object. After each evaluation an object representing the result is returned which contains the result of that evaluation. The result object can be treated as any other object in the system.

The contents of a DPI object can be moved into a user’s program variable by using the function GrGetValue or “short-cut” GrGetValue functions like GrString or GrReal. The various methods of accessing an object using GrGetValue are detailed in Functions (p. 29). GrGetValue sends a message to a GR object and the result is returned in a user’s variable.

The output of all MVISION DPI functions are declared in C as type "GrData". A "GrData" variable should be thought of as a handle to an object in the MVISION system. The types of objects in the MVISION system are list on pages 2-3 to 2-7 in the manual.

The type of object pointed to by a "GrData" variable can be accessed using the function GrType() or GrGetValue()

For example:

GrData db_handle;GrObjectType type;GrConnectToDatabase( "mil5.des", 1000, &db_handle );type = GrType(db_handle);

or

GrGetValue( db_handle, GRtype, &type );

(Note: the value of type in this example would be GR_TYPE_DATABASE)

Page 12: MSC.mvision Database Programmatic Interface

2

For objects of types GR_TYPE_REAL, GR_TYPE_STRING, and GR_TYPE_LOGICALthe data can be accessed using the functions GrReal, GrString, and GrLogical:

1. Using the function GrGetValue.

(The access codes for the function GrGetValue are defined on pages2-18 to 2-24)

2. Using the function GrExpression with the Function GrEvaluate. For example the name can be accessed out of an attribute object (i.e. type == GR_TYPE_ATTRIBUTE) in the following two ways :GrData att_handle;GrData db_handle;GrData name_expr;GrData name_handle;char *name;GrConnectToDatabase( "mil5.des", 1000, &db_handle );GrLookupAttribute( db_handle, "CNAME", &att_handle );

1... GrGetValue( att_handle, GRattributeName, &name );printf( "Attribute Name = %s\n", name );

2... GrExpression( "name", &name_expr );GrEvaluate( att_handle, name_expr, &name_handle );name = GrString( name_handle );printf( "Attribute Name = %s\n", name );

The type of expression that can be evaluated for an object are defined on pages 2-3 to 2-7 of the manual.

The element of a list object (type == GR_TYPE_LIST) can be accessed using the functionGrGetListElement.

For example :

/* List of the name of all the tables in a database */ GrData table_handle;GrData table_list;GrData db_handle;char *name;int i, n_tables;GrConnectToDatabase( "mil5.des", 1000, &db_handle );GrGetValue( db_handle, GRdatabaseTables, &table_list );n_tables = GrListSize( table_list );for( i=0; i 30 */GrExpression( "select( MATERIAL | cname, form, temp, e11t | e11t > 30 )",&select_expr );GrEvaluate( db_handle, select_expr, &select_result );n_rows = GrListSize( select_result );for( i=0; i

Page 13: MSC.mvision Database Programmatic Interface

13CHAPTER 1Introduction

1.6 Methods of Database AccessThere are two general methods of accessing a database:

• Query - Query expressions return a handle on a database structure — a piece of a hierarchy. Query is useful in applications that navigate an MSC.Mvision hierarchy.

• Select - Select expressions return a handle on a virtual table whose columns are attribute values specified by the user (form, heat_treatment, etc.) and each row contains instances of those attributes.

Typical Query Access (Navigating)A typical query involves the following steps:

1. Connecting to a database.

2. Creating a subset of that database (a list of the rows at a given hierarchical level).

3. Interrogation of the rows in the list or navigation to the next database level.

The following is an example which lists the material names whose Young’s Modulus is greater than 10.5.

A logical extension to this example would be to list all the specimens associated with a given material in the list. This is accomplished by evaluating the material row with an expression of SPECIMEN_ROWS. The result is a list of all the specimens for that material. This list would be accessed in the same manner as the MATERIAL list was accessed in the example.

Page 14: MSC.mvision Database Programmatic Interface

4

Typical Select Access (Making Tables)A typical select involves the following steps:

1. Connecting to a database.

MATERIAL

UNS CNAME

DESIGFORM TREAT

TEMP

E11TUS11T...

...SPECIMEN

ENVIRONMENT

PROPERTY

ME_METALS.DES

DPI 1

3

2

4

5

Query Access to All CNAMEs whose E11T>10.5 Create db connection

GrConnectToDatabase("ME_METALS.DES", &db_handle);db_handle

Create query expressionGrExpression("query (MATERIAL|E11T>10.5 )", &query);query

Evaluate expression for ME_METALS.DES

GrEvaluate(db_handle, query, &query_list);query_list

Get size of list

Num_Mat = GrListSize( query_list);Num_Mat

FOR( i = 0; i= Num_Mat;i++){Get MATERIAL row GrGetListElement(query_list, i, &row)Evaluate row with cname_keyGrEvaluate( row, cname_key, &cname)printf(“%s %n”,GrString( cname) }

List of MATERIAL database objects whose

List of one MATERIAL database row

Create expression to extract CNAME from material rows

GrExpression ( “CNAME”, &cname_key);

6

Page 15: MSC.mvision Database Programmatic Interface

15CHAPTER 1Introduction

2. Creating a subset of that database (a list of rows, each row containing the attributes requested in the select).

3. Interrogation of the rows in the list with the GrFetchFromSelect function.

This allows the user to create customized tables with any database attributes. The select function is “intelligent” enough to scan the hierarchy looking for pedigree data elsewhere in the hierarchy. For example, the select knows for each Elastic Modulus (E11T) the value of its Heat Treatment (TREAT).

The following is an example of a typical select.

MATERIAL

UNS CNAME

DESIGFORM TREAT

TEMP

E11TUS11T...

...SPECIMEN

ENVIRONMENT

PROPERTY

ME_METALS.DES

DPI

List of cname and E11T for all database records whose

CNAME E11T

_

_

_

_

1

3

2

4

5

Select Access to print a table of all CNAMEs and E11Ts whose E11T>10.5

Create db connection

GrConnectToDatabase("ME_METALS.DES", &db_handle);db_handle

Create select expression

GrExpression("select(MATERIAL | CNAME, E11T | E11T>10.5 )", &select);

select

Evaluate expression for ME_METALS.DES

GrEvaluate(db_handle, select, &select_list);

Get size of list

Num_Mat = GrListSize( select_list);Num_Mat

FOR( i = 0; i= Num_Mat;i++){GrFetchFromSelect( select_list, i, cname, e11t);printf(“%s %f”,GrString( cname), GrReal(e11t));}

Page 16: MSC.mvision Database Programmatic Interface

6

1.7 A Brief Example of SelectThe following example operates on a modified version of the MSC.Mvision PMC90 databank. The attributes used in this example are arranged in the schema as follows:

• MATERIAL

• desig

• SPECIMEN

• form

• sg

• ENVIRONMENT

• temp

• humid

• PROPERTY

• e11t

This example opens PMC90 and does the DPI equivalent of the SQL command:

Or, in MSC.Mvision DPI form:

Note: The select expression in the following code has the form select (input_list | attribtue_list | conditions) and in this case uses material as the input list:

SELECT m.desig, s.form, e.temp, e.humid, p.e11t, p.e11t/s.sg

FROM material m, specimen s, environment e, property p

WHERE m.id = s.material and s.id = e.specimen and

e.id = p.environment and p.e11t ex

SELECT desig, form, temp, humid, e11t, e11t/sg

CONDITIONS e11t ex

GrExpression( "select( material | desig, form, temp, humid,

e11t, e11t/sg | e11t exists", &select );

Page 17: MSC.mvision Database Programmatic Interface

17CHAPTER 1Introduction

Any table could have been used as input because the select is “intelligent” enough to find the requested attributes wherever they are in the schema. The select operates fastest with a short input list. Typically the material level (or highest hierarchical level) has the fewest entries and so the material level was used in this example. A more general method of specifying the highest level is:

The select requires a list as input. Note: Adatabase object is not a list but the message self converts the object into a list. In the previous expression, self is a message understood by the DPI to mean the highest level in the open databank hierarchy.

The following is a representative segment of code to perform a select on a me_metals.des databank.

#include “gr.h”

main(){

int i, status;int Num_Mat;

/*Declare variables M/VISION DPI*/

GrData db_handle;GrData select, select_list;GrData cname, e11t;

/*Initialize DPI*/

status = GrInitialize();if( status == GR_FAILURE ) { printf(“%s\n”,GrGetErrorMessage()); exit(1); }

/*Connect to database*/

status = GrConnectToDatabase( “/mvision/db/me_metals.des”, 200, &db_handle );

if( status == GR_FAILURE ) { printf(“%s\n”,GrGetErrorMessage()); exit(1); }

/*Create an expression to query the material relation in the database*/

GrExpression( “select( self | desig, form, temp, humid,

e11t, e11t/sg | e11t exists”, &select );

Page 18: MSC.mvision Database Programmatic Interface

8

status = GrExpression( “select( material | cname, e11t | e11t > 10.5 )”, &select );

if( status == GR_FAILURE ) { printf(“%s\n”,GrGetErrorMessage()); exit(1); }

/*Evaluate the expression for the database*/

status = GrEvaluate( db_handle, select, &select_list );if( status == GR_FAILURE ) { printf(“%s\n”,GrGetErrorMessage()); exit(1); }

/*Get the number of rows in the select structure*/

Num_Mat = GrListSize( select_list );for( i=0; i<Num_Mat; i++ ){

/*For each row print out the cname, e11t*/

GrFetchFromSelect( select_list, i, &cname, &e11t );printf( “%d) %s %f\n”, i, GrString(cname), GrReal(e11t) );

}

GrClose();}

This program produces a list of values as the result.

0) Low-Alloy Steel 29.0000001) Ti-6Al-4V 16.0000002) Ti-6Al-4V 16.0000003) Ti-6Al-4V 16.0000004) Ti-6Al-4V 16.0000005) Ti-6Al-4V 16.000000...

Page 19: MSC.mvision Database Programmatic Interface

19CHAPTER 1Introduction

1.8 Code Required for All DPI ProgramsCertain definitions and function calls are required for all DPI programs. Following is a code fragment that outlines the basic requirements.

#include “gr.h”

main()/* This fragment outlines the essentials*/{/*

Define the object handles as type GrData*/GrData db, query, row;GrData desig, form, temp, humid, e11t, specific_e11t;

int i, j, size;int retcode;char *desig_string, *form_string, *humid_string;double temp_value, e11t_value, specific_e11t_value;

/*Initialize DPI

*/ if (GrInitialize() == FAILURE) {

printf(“%s\n”, GrGetErrorMessage());return;

}/*

Connect to database and store handle in variable db*/ retcode = GrConnectToDatabase(“/mvision/db/pmc90.des”, 100, &db);

.

.

.Use expressions and functions to interrogate the database.../* Free the memory associated with expressions that are

no longer needed*/GrFreeExpression( query );

GrDisconnectFromDatabase( db );

/*Shut down the DPI

*/

Page 20: MSC.mvision Database Programmatic Interface

0

GrClose();

The DPI checks for many types of errors and returns error codes and messages when an error is encountered. However, this checking is useless unless DPI users trap the errors in their programs as they make DPI calls. Many of the examples in this document include error trapping, but for clarity much of the error trapping required by good programming practice has been omitted. Users are strongly encouraged to follow good error trapping practices to minimize programming and debugging time.

Page 21: MSC.mvision Database Programmatic Interface

MSC.Mvision Database Programmatic Interface User’s Guide and Reference

2 Object Types, Expressions and Functions

■ Object Types

■ Functions

■ Access Codes for GrGetValue Function

■ Expressions

■ Expression Syntax and Arguments

■ Forming Expressions

Page 22: MSC.mvision Database Programmatic Interface

2

The MSC.Mvision Database Programmatic Interface (DPI) has three basic components: objects, expressions, and functions. DPI programs use these three components to access different parts of a databank. The DPI object types correspond to the major aspects s of an MSC.Mvision databank: the hierarchy, tables, attributes, and the basic data types of numeric, character, and figure.

Objects respond to messages sent by the DPI functions. As function arguments often include expressions, the DPI programmer must understand the syntax of valid expressions and their use as function arguments to manipulate DPI objects effectively.

Also note that when file names are required as arguments to DPI functions the full relative path to the file must be specified. Filenames are always case senesitive on UINX platforms regardless of toher program settings

.

Note: The prefix "Gr" is MSC’s internal designation for the MSC.Mvision Database Programmatic Interface and appears in all of the DPI data types and function calls to insure uniqueness from user application data types and function calls.

Page 23: MSC.mvision Database Programmatic Interface

23CHAPTER 2Object Types, Expressions and Functions

2.1 Object TypesA complete listing of DPI objects and their definitions is presented below. These are the objects which can be interrogated with the DPI.

Object Types

Object TypesDescription

Components of this Object Type

GR_TYPE_ATTRIBUTE An object of type GR_TYPE_ATTRIBUTE is created for each attribute within a database. The memory associated with a GR_TYPE_ATTRIBUTE object is not released until either the database is disconnected or the system is shut down.

Table: Table to which the attribute belongs

Level: Level of the hierarchy at which this attribute is located

Name: Database name of attribute

Type: integer, real, string, figure, binary (image)

Description: Database description of attribute

Units: Current units label for attribute

Width: Length of string (if type string)

Bound1: Array dimension 1 (if type real)

Bound2: Array dimension 2 (if type real)

Dimensionality: 0 (scalar, string), 2 (matrix)

Precision: Number of significant digits (if type real )

DefaultUnits: Default database units label for attribute (defined when a databank is built)

Synonyms: List of Database stored attribute aliases

Page 24: MSC.mvision Database Programmatic Interface

4

GR_TYPE_DATABASE An object of type GR_TYPE_DATABASE is created each time GrConnectToDatabase is successfully called. A GR_TYPE_DATABASE object represents a MSC.Mvision databank. The memory associated with a GR_TYPE_DATABASE object is not released until either the database is disconnected or the system is shut down.

Name: Name of database

Header: Information about who created the database and when it was created.

Tables: List of all table (relation) names in the database. List elements are GR_TYPE_TABLE objects.

HierarchyTables: Ordered list of tables (relations) in the hierarchy. List elements are GR_TYPE_TABLE objects.

Attributes: List of all attributes in the databse. List elements are GR_TYPE_ATTRIBUTE objects.

SourceTable: Handle of the table used as database source level GR_TYPE_TABLE object

CurrentUnitSystem: The currently applied unit system label from the current UnitsFile

UnitsFile: The name and path of the current units conversion file.

UnitSystems: List of all unit system labels in the current UnitsFile.

NamedConditions: List of the current named query conditions in the database. List elements are GR_TYPE_NAMED_CONDITION objects.

PDAnumber: An integer identifier for MSC-supplied databanks.

PropertyTables: List of all non-hierarchical and non-source tables in the database. List elements are GR_TYPE_TABLE objects.

Object Types (continued)

Object TypesDescription

Components of this Object Type

Page 25: MSC.mvision Database Programmatic Interface

25CHAPTER 2Object Types, Expressions and Functions

GR_TYPE_CURVE An object of type GR_TYPE_CURVE represents a curve which is a component of a GR_TYPE_FIGURE object.

Points: List of points in the curve. List elements are GR_TYPE_POINT.

RunOut: Single runout point associated with curve

DisplayCode: ["solid" |"dashed"] (string)

GR_TYPE_EXPRESSION An object of type GR_TYPE_EXPRESSION results from executing the function GrExpression on expression text using the DPI expression syntax. Expressions are the messages used to communicate with objects. (SeeObject Types (p. 23))

String: The character string which defines the expression such as a query or sorted select.

Tables: List of all database tables (relations) involved in the evaluation of the expression. If several attributes in the expression are from the same relation, that relation appears only once in the list of tables. List elements are GR_TYPE_TABLE objects.

GR_TYPE_FIGURE An object of type GR_TYPE_FIGURE represents a particular figure in an MSC.Mvision table.

Curves: List of curves in the figure. List elements are GR_TYPE_CURVE.

ScatterPoints: List of elements of GR_TYPE_POINT objects.

RunOutPoints: List of elements of GR_TYPE_POINT objects.

RangeBars: List of elements of GR_TYPE_RANGE_BAR objects.

Xscale: [ "linear" | "log"] (string)

Yscale: [ "linear" | "log"] (string)

Object Types (continued)

Object TypesDescription

Components of this Object Type

Page 26: MSC.mvision Database Programmatic Interface

6

GR_TYPE_IMAGE An object of type GR_TYPE_IMAGE represents an image.

FileName: Name of the image file.

GR_TYPE_INTEGER An object of type GR_TYPE_INTEGER represents an integer result.

GR_TYPE_LIST An object of type GR_TYPE_LIST represents a list of other objects.

Size: Number of elements in list.

GR_TYPE_LOGICAL An object of type GR_TYPE_LOGICAL represents GR_TRUE or GR_FALSE.

GR_TYPE_MATH_ERROR An object of type GR_TYPE_MATH_ERROR represents a mathematical error which occurred while evaluating an expression. (See Mathematical Error Conditions (Appendix. A))

GR_TYPE_NAMED_CONDITION

An object of type GR_TYPE_NAMED_CONDITION is created for each named condition within a database. The memory associated with a GR_TYPE_NAMED_CONDITION object is not released until either the database is disconnected or the system is shut down.

Name: Name of the named condition

Condition: The character string which defines the query associated with the named condition.

GR_TYPE_POINT An object of type GR_TYPE_POINT represents a point which is a component of GR_TYPE_FIGURE or GR_TYPE_CURVE object.

X: X coordinate (double real)

Y: Y coordinate (double real)

GR_TYPE_RANGE_BAR An object of type GR_TYPE_RANGE_BAR represents a range bar which is a component of GR_TYPE_FIGURE object.

Point1: Startpoint of range bar (GR_TYPE_POINT)

Point2: Endpoint of range bar (GR_TYPE_POINT)

Object Types (continued)

Object TypesDescription

Components of this Object Type

Page 27: MSC.mvision Database Programmatic Interface

27CHAPTER 2Object Types, Expressions and Functions

GR_TYPE_REAL An object of type GR_TYPE_REAL represents a floating point result.

Precision: Number of significant digits expressed as a double (i.e. .001) or GR_PRECISION_UNKNOWN (if precision is unknown.)

GR_TYPE_STRING An object of type GR_TYPE_STRING represents a character string result.

GR_TYPE_TABLE An object of type GR_TYPE_TABLE is created for each table in a database. The memory associated with a GR_TYPE_TABLE object is not released until either the database is disconnected or the system is shut down.

Name: Name of tableType: ["hierarchy" |" source" |"prop"] (string)Level: Level in the hierarchy (if type hierarchy)

Attributes: List of attributes in the table. List elements are GR_TYPE_ATTRIBUTE objects.

GR_TYPE_TABLE_ROW An object of type GR_TYPE_TABLE_ROW represents a unique row in a MSC.Mvision databank table.

Id: Identification number of a unique row in a unique Table (GR_TYPE_TABLE). This row number is unique within it’s own table, but not in other tables.

Table: The table associated with this database (table) row.

<attribute> Value (i.e. E11T.VALUE) : result is dependent on attribute type.

<attribute> Footnote (i.e. E11T.FOOTNOTE): string value for footnote associated with referenced attribute.

<attribute> Metadata (i.e. E11T.METADATA):string value for metadata associated with referenced

attribute.

Object Types (continued)

Object TypesDescription

Components of this Object Type

Page 28: MSC.mvision Database Programmatic Interface

8

In addition to the basic DPI object types the DPI can create and manipulate specialized modifications of the basic DPI objects such as "full text" attributes review the " Building MSC.Mvision Databanks" User’s Manual for more information on specialized attribute types.

Global Unique Identifier (UID)

As of version 2002 the MSC.Mvision databank contain a UID (Global Unique Identifer) for every table row within the databank. This UID is a special property of each table row within the databank and is automatically created upon creation of the databank. The UID can be modified using the MSC.Mvision Builder or the MvBatchBuilder, but can not be assigned of modified using the DPI. Within the DPI language the UID can be used within query expressions to quickly located specific table rows. Expression functions and GrAccess codes are provided to facilitate the use of the table row UID in queries.

The UID consists of three elements; the table name, a name space , and integer row identifier (external-id), table_name-name_space-external_id (i.e. material-default-1). The table name is the name of the table for which the table row is a member. The name space is a character string not to exceed 64 characters and by default is the name of the databank file for which the database was originally created . The name space can be one of two types: a database managed name space ( default name space) or a user managed name space. A database managed name space is associated with a specifc database and is automatically generated (this is the type of name space created when a database is created using the DPI). A user managed name space is controlled by the user who specifies the identifiers assocated with the specific table rows. The row identifier is an interger value that combined with the name space is unique to the table for which the table row is a member. When the row identifiers is automatically generated they are a consequtive series of integers. The as generated row identifier is the internal_id, if a user modifies the UID then an external_id is created otherwise both the internal_id and external_id are the same. The name space and/or row identifier can be modified via the MSC.Mvision Builder or the MvBatchBuilder.

Page 29: MSC.mvision Database Programmatic Interface

29CHAPTER 2Object Types, Expressions and Functions

2.2 FunctionsThe following provides a listing of DPI functions used to access MSC.Mvision databank objects.

GrAttributeFootnote

Returns a handle on the footnote value associated with the specified attribute in the specified object (i.e. table row). The return object is of type string. The actual contents of the returned object may be retrieved with , GrString or GrGetValue.

Int GrAttributeFootnote( GrData obj_handle, GrData att_handle, GrData *result_handle )

• obj_handle A handle on a table row object.

• att_handle A handle on the attribute footnote object being accessed. The attribute be in the same table as the table row.

• result_handle A handle on the footnote value for the specified attribute.

GrAttributeMetadata

Returns a handle on the metadata value associated with the specified attribute in the specified object (i.e. table row). The return object is of type string. The actual contents of the returned object may be retrieved with GrString or GrGetValue.

Int GrAttributeMetadata( GrData obj_handle, GrData att_handle, GrData *result_handle )

• obj_handle A handle on a table row object.

• att_handle A handle on the attribute metadata object being accessed. The attribute must be in the same table as the table row.

• result_handle A handle on the metadata value for the specified attribute.

GrAttributeValue

Returns a handle on the value associated with the specified attribute in the specified table row. The return object type is dependent on the attribute object type. The actual contents of the returned object may be retrieved with GrString, GrReal, GrInteger or GrGetValue.

Int GrAttributeValue( GrData obj_handle, GrData att_handle, GrData *result_handle )

• obj_handle A handle on a table row object.

• att_handle A handle on the attribute value object to be accessed. The attribute must be in the same table as the table row.

• result_handle A handle on the attribute value for the specified attribute.

Page 30: MSC.mvision Database Programmatic Interface

0

GrBind

Binding is the precursor to evaluation where the expression is checked against the object for validity and for data type. For example, GrExpression will create an expression using the attribute name of XX25Z with no errors. It is not until binding, when the object to evaluate against is specified, that the DPI checks to see if XX25Z is in fact a valid attribute name for the active database. Thus, GrBind offers a quick check of validity before committing to an evaluation. GrBind also provides the return data type of the expression which can be used to allocate memory for the results of a subsequent evaluation.

The function GrEvaluate(see GrEvaluate (p. 31)) automatically performs a bind before it evaluates, if a bind has not already been performed. GrBind provides the capability to bind without evaluating.

Int GrBind( GrData obj_handle, GrData expr_handle,GrData *result_handle )

• obj_handle A handle on the object to be bound with the specified expression.

• expr_handle A handle on the expression (created with GrExpression (p. 32)) to be bound to the specified object.

• result_handle A handle on the results of the binding.

GrChangeUnits

Changes the unit conversion, unit system (predefined set of conversion factors) applied to the specified databank.

Int GrChangeUnits( GrData db_handle, char *system_name )

• db_handle Handle on a databank.

• system_name Name of unit system (string).

GrClose

Shuts down the DPI. Closes all of the active databanks and frees all of the associated memory and releases licenses.

Int GrClose()

GrConnectToDatabase

Returns a handle on the database. Creates a connection to a databank, obtains a databank license if necessary, allocates memory for the database buffer, reads and loads databank index (if it exists) and loads the database buffers.

Int GrConnectToDatabase( char *file_name,int db_buffer_size, GrData *db_handle)

Page 31: MSC.mvision Database Programmatic Interface

31CHAPTER 2Object Types, Expressions and Functions

• file_name File name of the databank to be opened (string).

• db_buffer_size Size, in kilobytes, of the database buffer (allocated memory) to be used with this databank for this initialization.

• db_handle A handle on the specified databank.

GrCreateIndexFile

Opens and writes an index data (binary data) to specified file for the active databank.

int GrCreateIndexFile( GrData db_handle, char *index_file_name, char *query_condition, int (*index_callback)())

• db_handle A handle on a databank

• index_file_name Name of index file to be created (stirng).

• query_condition Query condition to be applied to database to restrict which attributes are indexed. (i.e. the logial expression "true" will index the entire databank).

• index_callbackCallback function

GrCreateRowList

Returns a list of table rows for a specified table and array of row ids.

int GrCreateRowList( GrData table_handle, int n_rows,int *rows, GrData *row_list_handle )

• table_handle A handle on a table object

• n_rows Number of rows to include in list

• rows Array of table row ids

• row_list_handle A handle on the resultant list of table row objects

GrDisconnectFromDatabase

Disconnects from a MSC.Mvision Databank and removes the database from the list of open databases. Also releases all memory associated with the database, closes the database file and releases the databank license.

Int GrDisconnectFromDatabase(GrData db_handle)

• db_handle A handle on an open databank

GrEvaluate

Evaluates a previously defined expression against an object. The result of the evaluation is stored in the result object. To access the result of an evaluation use GrGetValue, GrGetListElement, or access functions GrString, GrReal, etc..

Page 32: MSC.mvision Database Programmatic Interface

2

Int GrEvaluate( GrData obj_handle, GrData expr_handle, GrData *result_handle )

• obj_handle A hanle on the object that the expression will be evaluated against

• expr_handle A handle on the expression to be evaluated (created with GrExpression).

• result_handle A handle on the result of the evaluation

GrExpression

Returns an expression which can be evaluated against a DPI object. An expression is defined by a string which is interpreted in the expression syntax. The expression syntax is described in Object Types (p. 23).

Int GrExpression( char *expression, GrData *expr_handle )

• expression An expression composed with the DPI expression syntax (string).

• expr_handle A handle on the resulting expression

Note: To free the memory associated with an expression, GrFreeExpression must be called. Once the memory has been freed for an expression, evaluation of the expression is not possible.

GrFetchFromSelect

Copies the contents of a row (element) of a select list result into a user’s program variable.

Int GrFetchFromSelect( GrData obj_handle, int index, GrData *result [, GrData *result, ...] )

• obj_handle A handle on the object (list) to be accessed.

• index The index number of the element in the list to be accessed

• result The result of the access

Note: This function is not in the function prototypes of the gr_proto.h include file because of operating system differences in the way variable length argument lists are specified. The function operates as documented except that the compiler cannot do type checking at compile-time.

GrFigureAttributeUnitsConversion

Returns the units conversion factors and offsets for a specified figure attribute.

int GrFigureAttributeUnitsConversion( GrData attribute_handle, double *x_mult,

Page 33: MSC.mvision Database Programmatic Interface

33CHAPTER 2Object Types, Expressions and Functions

double *x_offset, double *y_mult, double *y_offset )

• attribute_handle A handle on a figureattribute object.

• x_mult Units conversion factor for the x axis.

• x_offset Units conversion offset for the x axis.

• y_mult Units conversion factor for the y axis.

• y_offset Units conversion offset for the y axis.

GrFreeExpression

Releases the memory associated with an expression. Once the memory of an expression is freed, the expression is no longer available for evaluation. The results area associated with the expression is also freed.

Int GrFreeExpression( GrData expr_handle )

• expr_handle A handle on the expression to be freed

GrGetErrorMessage

Returns the current error message. The error message is an English language description of the error that occurred with the combined error type and error object.

Char * GrGetErrorMessage()

GrGetErrorObject

Returns the current error object. The error object is a string describing the source which caused the error. For example, the error object might be the name of the file which caused a GR_FILE_OPEN_ERROR.

Char * GrGetErrorObject()

GrGetErrorType

Returns the current error type. The error type is set each time an error occurs. See Error Messages (Appendix. A) for a listing of error types.

GrError GrGetErrorType()

GrGetListElement

Returns a handle on an element (row) in a list for the specified element index (row number).

Int GrGetListElement( GrData obj_handle, int index,GrData *result )

• obj_handle A handle on the list object to be accessed.

Page 34: MSC.mvision Database Programmatic Interface

4

• index Index number of the element (row) in the list to be accessed. List indexes start from 0.

• result A handle on the element in the list.

GrGetTableRow

Returns a handle on a table row for the specified table object and row id.

int GrGetTableRow( GrData table_handle, int row_id, GrData *row_handle )

• table_handle A handle on a table object.

• row_id Id of table row (row number).

• row_handle A handle on the table row object.

GrGetValue

Copies the contents of a DPI object into a user’s variable. Convienence functions to retrieve object components such as GrReal, GrString, etc. are provided in the DPI. The various types of access codes available are detailed in Access Codes for GrGetValue Function (p. 39). The GrGetValue function provides generalized access to all components and all object types.

int GrGetValue( GrData obj_handle, GrAccess access_code, void *result )

• obj_handle Handle on the object to be accessed.

• access_code Access code as defined in Access Codes for GrGetValue Function (p. 39).

• result Result of the access. Result type is dependent on access code.

GrInitialize

Sets up the DPI for use. This function must be called before any other DPI routines are called and will return Success even if the system has already been initialized.

Int GrInitialize()

GrInteger

Returns the contents of object as an intger.

Int GrInteger( GrData obj_handle )

• obj_handle A handle on an object containing an integer value.

GrListSize

Returns the number of elements (rows) in a list object as an integer.

Page 35: MSC.mvision Database Programmatic Interface

35CHAPTER 2Object Types, Expressions and Functions

Int GrListSize( GrData list_handle )

• list A handle on a list object.

GrLookupAttribute

Returns a handle on any attribute object in the databank for the specified attribute name. When searching for the attribute name, all attributes names are searched first and then all synonyms are searched.

Int GrLookupAttribute( GrData db_handle, char *attribute_name, GrData *result_handle )

• db_handle A handle on a databank.

• attribute_nameName of attribute to lookup (stirng).

• result_handle A handle on the attribute object.

GrLookupNamedCondition

Returns a handle on a named condition in the databank for the specified named_condition name. A named_condition is a predefined named query.

Int GrLookupNamedCondition( GrData db_handle, char *name_of_named_condition, GrData *result_handle )

• db_handle A handle on a databank

• name_of_named_condition Name of the named_condition for lookup (string).

• result_handle A handle on the named_condition object.

GrLookupTable

Returns a handle on any table object in the databank for the specified table name.

Int GrLookupTable( GrData db_handle, char *table_name,GrData *result_handle )

• db_handle A handle on a databank

• table_name Name of table for lookup (string).

• result_handle A handle on the table object

GrLookupRowByUid

Returns a handle on table row object indentified as table_name-name_space-external_id. Offers very fast access to a specific table row within the database.

Int GrLookupRowByUid ( GrData table_handle, const char *name_space, int external_id, GrData *result_handle )

Page 36: MSC.mvision Database Programmatic Interface

6

• table_handle A handle on a table object.

• name_space Name space of table row to lookup (stirng).

• external_id Row indentifier (number) of row to lookup.

• result_handle A handle on the table row object.

GrPrintObject

Writes the contents of an object to standard out.

Int GrPrintObject( GrData obj_handle )

• obj_handle A handle on an object

GrReadUnitsFile

Opens and reads a MSC.Mvision formatted units file which contains the definition of one or more unit systems. For each unit system in the addressed file, a Unit System object is created and added to the list of available unit systems. Only one units file may be associated with a databank at any one time. A unit system is a named set of attribute names with associated conversion factors (multiplier), offset values, and units label.

This units conversion method provides attribute specific conversion, but the unit systems and the actual converted values are dependant on the default units of the databank. A single units file may be read repeatedly and attached to several databanks if all the databanks are created with the same default units.

Int GrReadUnitsFile( GrData db_handle, char *units_file_name )

• db_handle A handle on the databank.

• units_file_name File name of the units file to be read (string).

GrReal

Returns the contents of an object as a real value.

Double GrReal( GrData obj_handle )

• obj_handle A handle on an object containing a real (numeric) value.

GrRealAttributeUnitsConversion

Returns the units conversion factor (multiplier) and offset value for an attribute of type real.

int GrRealAttributeUnitsConversion( GrData attribute_handle, double *mult, double *offset )

Page 37: MSC.mvision Database Programmatic Interface

37CHAPTER 2Object Types, Expressions and Functions

• attribute_handle A handle on a real type attribute object

• mult Units convertion factor (multiplier)

• offset Units convertion offset value

GrRegisterIndexerCallback

Register an indexer callback function to be called in a user written program to use a custom indexing function.

int GrRegisterIndexerCallback( int (*indexer_callback)(), int percentage_increment )

• indexer_callback Callback function.

• percentage_increment Index increment (percentage as an integer).

GrRegisterSecurityCallback

Register a callback function to be called in a user written program to write a message from the security/licensing system.

int GrRegisterSecurityCallback( int (*sec_callback)( char *message ) )

• sec_callback Callback function.

• message Text message to be returned (string).

GrResetUnits

Terminates any units conversion applied with the GrChangeUnits function (See GrChangeUnits (p. 30)) . All databank values retrieved after a GrResetUnits is called will be in the default (unconverted) units of the databank. The default databank units are determined by the MSC.Mvision define file used to create the databank.

Int GrResetUnits( GrData db_handle )

• db_handle A handle on the databank.

GrRowGetUId

Returns the name space value, internal_id and external_id for the specified table row object.

Int GrRowGetUid( GrData row_handle, char *name_space, int *internal_id, int *external_id)

• obj_handle A handle on a table row object.

• name_space Value of name sapce for specified table row object.

• internal_id Integer value for database generated row id.

Page 38: MSC.mvision Database Programmatic Interface

8

• external_id Integer value for user assigned row id.

GrSetCaseSensitive

Sets the DPI case sensitivity for the matching of attribute values, attribute names and table names. A "true" value sets the DPI matching to compare case. A "false" value sets the DPI matching to ignore case. The invoked state is in force until changed. By default the state of this function is "false" which ignores case for DPI matching.

Int GrSetCaseSensitive( int logical_expression )

• logical_expression A an expression that evaluates to true or false.

GrSetLockFile

Sets the location of the database lock file. For a standard MSC.Mvision installation the lock file is /install_dir/MVISION.LCK.

Int GrSetLockFile (char *file_name )

• file_name Name of the database lock file (string).

GrString

Returns the contents of an object as a string value.

Char* GrString( GrData obj_handle )

• obj_handle A handle on an object containing a string.

GrType

Returns the object type of the object. Return is enum GrObjectType.

GrObjectType GrType( GrData obj_handle )

• obj_handle A handle on an object.

GrUseIndexFile

Opens, reads and loads an existing MSC.Mvision index file (binary). Using an index file will improve the performance of access to a databank.

int GrUseIndexFile( GrData db_handle, char *index_file_name)

• db_handle A handle on a databank.

• index_file_name Name of a predifned MSC.Mvision index file (string).

Page 39: MSC.mvision Database Programmatic Interface

39CHAPTER 2Object Types, Expressions and Functions

2.3 Access Codes for GrGetValue FunctionThis section describes the Access Codes for the function GrGetValue, which copies the contents of a DPI object to a user’s program variable.

The syntax of GrGetValue is :

GrGetValue( obj_handle, access_code, *result )

• obj_handle Handle on the object to be accessed.

• access_code Access code as defined in table below.

• result Result of the access. Result type is dependent on access code.

Page 40: MSC.mvision Database Programmatic Interface

0

The following is a complete listing of DPI GrAccess codes and their definitions . Refer

Access Codes

Access Code Description

GRattributeBound1 Return the first dimension (bound1) for GR_TYPE_ATTRIBUTE object which has a non-zero dimensionality. Result is 0, if dimension is unbounded.

Result Type: int

GRattributeBound2 Return the second dimension (bound2) for GR_TYPE_ATTRIBUTE object which has a non-zero dimensionality. Result is 0, if dimension is unbounded.

Result Type: int

GRattributeDefaultUnits Return the "default units"(as created units label) for GR_TYPE_ATTRIBUTE object.

Result Type: char *

GRattributeDescription Return the "description" for GR_TYPE_ATTRIBUTE object.

Result Type: char *

GRattributeDimensionality Return the number of dimensions (dimensionality) for GR_TYPE_ATTRIBUTE object. Result is 0 for scalar and 2 for matrix.

Result Type: int

GRattributeLevel Return the table "level" in the hierarchy for GR_TYPE_ATTRIBUTE object. The top table level is 0.

Result Type: int

GRattributeName Return the "name" for GR_TYPE_ATTRIBUTE object.

Result Type: char *

GRattributePrecision Return the default (as created) "precision" for GR_TYPE_ATTRIBUTE object of type real.

Result Type: double

GRattributeStorageTable Return internal "storage id" of the attribute's table segment for GR_TYPE_ATTRIBUTE object.

Result Type : int

Page 41: MSC.mvision Database Programmatic Interface

41CHAPTER 2Object Types, Expressions and Functions

GRattributeSynonyms Return the list of "synonyms" associated with a GR_TYPE_ATTRIBUTE object.

Result Type: GrData (list)

GRattributeTable Return the GR_TYPE_TABLE object associated with GR_TYPE_ATTRIBUTE object. The table to which the attribute is assigned.

Result Type: GrData (object)

GRattributeType Return the value "type" for GR_TYPE_ATTRIBUTE object.

Result Type: char * [Integer | Real | String | Figure | Binary]

GRattributeUnits Return the current "units" label for GR_TYPE_ATTRIBUTE object.

Result Type: char *

GRattributeWidth Return the maximum number of characters (width) for GR_TYPE_ATTRIBUTE object of type string.

Result Type: int

GRcurvePoints Return a list of "points" (GR_TYPE_POINT objects) for GR_TYPE_CURVE object.

Result Type: GrData (list)

GRcurveRunOut Return a flag which indicates if the last curve point is a runout point for GR_TYPE_CURVE object. Result is 0 for a curve point and 1for a runout point.

Result Type: int [0 | 1]

GRcurveDisplayCode Return the display type (DisplayCode) for GR_TYPE_CURVE object.Result Type: char * ["SOLID" | "DASHED"]

GRdatabaseAttributes Return a list of attributes (GR_TYPE_ATTRIBUTE objects) for GR_TYPE_DATABASE object.

Result Type: GrData (list)

Access Codes (continued)

Access Code Description

Page 42: MSC.mvision Database Programmatic Interface

2

GRdatabaseCurrentUnitSystem Return the name of the active unit system (CurrentUnitSystem) for GR_TYPE_DATABASE object..

Result Type: char *

GRdatabaseDefaultNameSpace Return the value of the Default Name Space for the current database (GR_TYPE_DATABASE object).

Result Type: char *

GRdatabaseHeader Return the "header" of GR_TYPE_DATABASE object. The header is the descriptive text information for who, when and where the database was created or updated.

Result Type: char *

GRdatabaseHierarchyTables Return a list of GR_TYPE_TABLE objects for GR_TYPE_DATABASE object. This list of tables defines the database hierarchy (HierarchyTables). The list is sorted in hierarchical order.

Result Type: GrData (list)

GRdatabaseModified Return a flag for GR_TYPE_DATABASE object indicating whether a database has been modified. Result is 1 if in- memory data has been changed and not commited (saved to file). Result is 0 if no in-memory modifications exist (all data has been saved to file).

Result Type : int [0 | 1]

GRdatabaseName Return the "name" for GR_TYPE_DATABASE object.

Result Type: char *

GRdatabaseNamedConditions Return a list of GR_TYPE_NAMED_CONDITION objects for GR_TYPE_DATABASE object.

Result Type: GrData (list)

GRdatabaseNameSpaces Return a list of "all" Name Spaces for the current database ( (GR_TYPE_DATABASE object).

Result Type: GrData (list)

Access Codes (continued)

Access Code Description

Page 43: MSC.mvision Database Programmatic Interface

43CHAPTER 2Object Types, Expressions and Functions

GRdatabasePropertyTables Return a list of GR_TYPE_TABLE objects for GR_TYPE_DATABASE object This is a list of tables that are not used in the database hierarchy and are not a source table (PropertyTables).

Result Type: GrData (list)

GRdatabasePDAnumber Return the "PDA number" for GR_TYPE_DATABASE object. Valid with MSC databases only.

Result Type: int

GRdatabaseReadOnly Return a flag for GR_TYPE_DATABASE object indicating the database is opened for read-only.

Result is 1 if the database is read only.

Result Type : int [0 | 1]

GRdatabaseSourceTable Return the GR_TYPE_TABLE object for GR_TYPE_DATABASE object. The returned table object is the table used for source in the database.

Result Type: GrData (object)

GRdatabaseTables Return a list of all GR_TYPE_TABLE objects for GR_TYPE_DATABASE object.

Result Type: GrData (list)

GRdatabaseUnitsFile Return the name of the unit conversion file (UnitsFile) for GR_TYPE_DATABASE object.

Result Type: char *

GRdatabaseUnitSystems Returna list of all unit conversion system names (UnitSystems) for GR_TYPE_DATABASE object.

Result Type: GrData (list)

GRerrorValue Return the value for GR_TYPE_MATH_ERROR object. See Mathematical Error Conditions (Appendix. A).

Result Type: GrMathError (enum)

GrexpressionString Return the expression text (string) for GR_TYPE_EXPRESSION object. This text uses the DPI expression syntax.

Result Type: char *

Access Codes (continued)

Access Code Description

Page 44: MSC.mvision Database Programmatic Interface

4

GrexpressionTables Return a list of all GR_TYPE_TABLE objects (Tables) referenced by a GR_TYPE_EXPRESSION object.

Result Type: GrData (list)

GRfigureCurves Return the list of GR_TYPE_CURVE objects (Curves) for a GR_TYPE_FIGURE object.

Result Type: GrData (list)

GRfigureRunOutPoints Return the list of "run out points" (GR_TYPE_POINT objects) for a GR_TYPE_FIGURE object.

Result Type: GrData (list)

GRfigureRangeBars Return the list of "range bars" (GR_TYPE_RANGE_BAR objects) for a GR_TYPE_FIGURE object.

Result Type: GrData (list)

GRfigureScatterPoints Return the list of "scatter points" (GR_TYPE_POINT objects) for a GR_TYPE_FIGURE object.

Result Type: GrData (list)

GRfigureXscale Return the value of the "X" axis "scale type" for GR_TYPE_FIGURE object.

Result Type: char * ["LINEAR" | "LOG"]

GRfigureYscale Return the value of the "Y" axis "scale type" for GR_TYPE_FIGURE object.

Result Type: char * ["LINEAR" | "LOG"]

GRimageFileName Return the "File Name" of the image file for GR_TYPE_IMAGE object.

Result Type : char *

GRintegerValue Return the contents of an Object as an integer.

For a GR_TYPE_INTEGER object the value is returned directly. For a GR_TYPE_REAL object the value is converted to an integer.

Result Type: int

Access Codes (continued)

Access Code Description

Page 45: MSC.mvision Database Programmatic Interface

45CHAPTER 2Object Types, Expressions and Functions

GRisNull Return the status of a null object value. Returns 1 if the object value is null and 0 if the object has a value.

Result Type : int [0 | 1]

GRlistSize Return the size (number of rows) of a list object.

For GR_TYPE_LIST returns the value of "size".

Result Type: int

GrNamedConditionName Return the "name" for GR_TYPE_NAMED_CONDITION object..

Result Type: char *

GrNamedConditionCondition Return the query "condition" (text) for GR_TYPE_NAMED_CONDITION object.

Result Type: char *

GRpointX Return the "X" coordinate for a GR_TYPE_POINT object.

Result Type: double

GRpointY Return the "Y" coordinate for a GR_TYPE_POINT object.

Result Type: double

GRrangeBarPoint1 Return the "Point1" (GR_TYPE_POINT) for a GR_TYPE_RANGE_BAR object.

Result Type: GrData (object)

GRrangeBarPoint2 Return the "Point2" (GR_TYPE_POINT) for a GR_TYPE_RANGE_BAR object.

Result Type: GrData (object)

GRrealValue Return the contents of an Object as a real number.

For a GR_TYPE_REAL object the value is returned directly. For a GR_TYPE_INTEGER object the value is converted to a real number.

Result Type: double

Access Codes (continued)

Access Code Description

Page 46: MSC.mvision Database Programmatic Interface

6

GRrealPrecision Return the number of significant digits for an object. For a GR_TYPE_REAL object the"precision" is retruned. For a GR_TYPE_INTEGER object "unknown" is returned. GR_PRECISION_UNKNOWN, is returned if the precision can not be determined.

Result Type: int

GRrowId Return the "row id" of a GR_TYPE_TABLE_ROW object.

Result Type: int

GRrowTable Return the GR_TYPE_TABLE object for a GR_TYPE_TABLE_ROW object.

Result Type: GrData (object)

GRstringValue Return the the contents of an object as a character string. Returns the value of GR_TYPE_STRING object directly.

Result Type: char *

GRtableDatabase Return the "name" of the GR_TYPE_DATABASE object for a GR_TYPE_TABLE object.

Result Type: GrData (object)

GRtableName Return the "name" for a GR_TYPE_TABLE object.

Result Type: char *

GRtableType Return the table "type" for a GR_TYPE_TABLE object.

Result Type: char * ["PROP" |"HIERARCHY" | "SOURCE"]

GRtableLevel Return the table "level" in the hierarchy for a GR_TYPE_TABLE object. The top level in the hierarchy is 0.

Result Type: int

GRtableAttributes Return the list of GR_TYPE_ATTRIBUTE objects for a GR_TYPE_TABLE object.

Result Type: GrData (list)

Access Codes (continued)

Access Code Description

Page 47: MSC.mvision Database Programmatic Interface

47CHAPTER 2Object Types, Expressions and Functions

to table Object Types (p. 23) for object types and descriptions.

DPI convienence functions have been created for the most commonly used access codes. These functions provide a “short cut” to place DPI values in user variables. The syntax for these functions is:

Gr[access_type]( obj_handle )

For example,

my_string = GrString( CNAME )my_number = GrReal( E11T )

These shortened functions have been created for the following access codes:

GrIntegerGrRealGrStringGrTypeGrListSize

The DPI also contains "built-in" expression messages see Expression Messages (p. 64) for a detailed description of the available messages.

GRtype Return the type of an object as an object.

Result Type: GrObjectType (enum)

GRtypeString Return the type of an object as a string. Result is one of the object types defined in Object Types (p. 23) or one of the following; Null, Unknown, Unit_Property or Attribute _Instance.

Result Type: char *

GRlogicalValue Return the contents of a GR_TYPE_LOGICAL object.

Result of 1 is true and 0 is false.

Result Type: int [0 | 1]

Access Codes (continued)

Access Code Description

Page 48: MSC.mvision Database Programmatic Interface

8

2.4 ExpressionsThe MSC.Mvision Database Programmatic Interface is a hybred object oriented database engine. Within the DPI messages are sent to objects and answers are returned about the object type, contents, size, etc. The key to using the DPI and the object-oriented approach is to understand the types and structure of the objects that make up the system. Some of the more important DPI objects are database, attribute, table, and list. Another important part of Using the DPI is understanding the types of messages that can sent to the objects. In the DPI, these "messages"are expressions and compose the “language” with which you can communicate with the objects in the database.

The DPI functions manage the communications to the DPI objects. DPI functions are available to create, validate, and process expressions. Communicating with an object usually involves the following steps:

• Form the expression text using appropriate DPI expression functions and syntax.

• Create a DPI expression from the expression text. The syntax of the expression is checked at this time.

• Bind the expression with an object. Validate and type check the expression.

• Evaluate the expression against the object (i.e. perform the action specified in the expression text).

• Interrogate the resultant object for type, size, data values, etc. The evaluation returns the response to the expression text which is itself another object.

The following example illustrates the object communication process:

Communication with an object begins with a text string such as “query( MATERIAL | E11T > 10.) “. This expression will perform a query over all the Material table rows to find those rows whose E11T value is greater than 10.

The first step in creating this expression text is using of the DPI expression “language” which includes finctions, operators, etc. to form the statement.

The second step in performing this query is to create a formatted expression with the DPI function GrExpression. The C language statement for this query would look something like:

GrExpression( "query( MATERIAL | E11T > 10.)", &query_handle )

During this step the DPI performs syntax checking on the expression. A lexical analyzer breaks the expression text into recognized tokens, then a parser assembles the tokens into valid statements and builds a parse tree, a logic structure which incorporates all the rules of operator precedence, parenthesis, etc.

The third step is to bind the expression with the object to be evaluated. The DPI function GrEvaluate both binds and evaluates an expression, or the DPI function GrBind can be used to just bind the expression. Binding the expression to an object will

Page 49: MSC.mvision Database Programmatic Interface

49CHAPTER 2Object Types, Expressions and Functions

validate the terms used in the expression. In our example query, binding ensures that the terms MATERIAL and E11T are valid for the object being queried. This binding also verifies that the data types of MATERIAL and E11T are compatible with the operations being performed in the expression. For example, binding would detect the error of trying to add a real number and character string. Further, binding determines the data type which will result from evaluating the expression. In our example, the data type will be a list of MATERIAL table row objects whose E11T>10. Finally, the bind operation creates an evaluation tree, a logic structure which specifies all the evaluation processors required for the expression, order of execution, and their arguments.

The final stepin communications with an object is evaluation of the evaluation tree. As stated above, the function GrEvaluate can be used to bind and then evaluate an expression in one step. The syntax would be:

GrEvaluate( db_handle, query_handle, &results_handle )

GrEvaluate binds the given database (db_handle) with the given expression (query_handle), evaluates the expression against the database, and returns the resulting list of objects in the results_handle. For the above example the result would be a handle on an object containing a list of MATERIAL table row objects.

This example is a very simple case. The query, select, sort, and other DPI expressions can be evaluated against any appropriate object. For example, we could apply another query to our list of materials, or sort them, or navigate down one of them to the next level (table) of the database, or select from them, etc. All these operations use the same concepts of evaluating expressions against objects and interrogating the results.

Page 50: MSC.mvision Database Programmatic Interface

0

2.5 Expression Syntax and ArgumentsThe following section provides a detailed specification of the DPI expression syntax and arguments. Refer to Forming Expressions (p. 53) for usage and examples.

This specification uses a context free grammar for describing the argument specification and the expression syntax.

The following is a brief description of the notation:

1. The characters | [ ] { } , have special meanings when used in DPI expressions:

2. Terminal symbols are shown in the following table in bold font.

3. All terminal symbols are case insensitive

4. Non-terminal symbols are strings of alpha, numeric, and non-special characters.

5. The following table shows alternative items in description as separated by a vertical bar |, this is for clarity only.

6. The following table indicates optional items within braces {}, this is for clarity only.

7. A “*” following an item in the following table indicates one or more occurrences of that item.

| separates arguments,

[ ] indicates array indexing

{ } is used to create intervals (ranges).

Argument Description

gr_expression expression | { simple_id } ‘|‘ expression

expression and_expression { or_operator and_expression }

or_operator OR | XOR

and_expression rel_expression { AND rel_expression }

rel_expression simple_expression [ rel_operator simple_expression ] | simple_expression unary_rel_operator

rel_operator ‘<‘ | ‘>’ | ‘<=’ | ‘>=’ | ‘<>’ | ‘=’ | IN | LIKE

unary_rel_operator EXISTS | NOT EXISTS | EX | NOT EX | IS NULL | IS NOT NULL

simple_expression term { add_operator term }

Page 51: MSC.mvision Database Programmatic Interface

51CHAPTER 2Object Types, Expressions and Functions

add_operator ‘+’ | ‘-’

term factor { mult_operator factor }

factor simple_factor [ ‘**’ simple_factor ]

simple_factor qualifiable_factor { qualifier } | interval | literal | ‘(‘ expression ‘)’ | unary_operator simple_factor | query_expression | select_expression | sort_expression | aggregate_expression | unary_function_expression | binary_function_expression

unary_operator ‘+’ | ‘-’ | NOT

qualifiable_factor simple_id

qualifier ‘.’ simple_id | ‘[‘ simple_expression ‘]’

interval ‘{‘ simple_expression rel_operator simple_expression rel_operator simple_expression ‘}’

aggregate_expression aggregate_function ‘(‘ [simple_id ‘<*’] expression ‘|’ expression ‘)’

aggregate_function AVG | MAX | MIN

query_expression QUERY‘(‘ [simple_id ‘<*’] expression ‘|’ expression ‘)’

select_expression SELECT ‘(‘[simple_id’<*’] expression ‘|’ expression {, expression} ‘|’ expression ‘)’

sort_expression sort_function ‘(‘ [simple_id ‘<*’] expression ‘|’ exp_list ‘)’

sort_function DISTINCT | GROUP | SORT

expression_list expression { ‘,’ expression }

binary_function_expression binary_function ‘(‘ expression ‘,’ expression ‘)’

binary_function NVL | interp_x | interp_y

unary_function_expression unary_function ‘(‘ expression ‘)’

Argument Description

Page 52: MSC.mvision Database Programmatic Interface

2

unary_function ABS | ACOS | ASIN | ATAN | CEIL | COS | COSH | DEGTORAD | ERF | EXISTS | EXP | FLOOR | LENGTH | LOG | LOG10 | RADTODEG | ROUND | SIN | SINH | SIZEOF | SQRT | TAN | TANH

literal integer_literal | real_literal | string_literal

integer_literal [ sign ] digit { digit }

real_literal [ sign ] digit { digit } ‘.’ { digit } [ ‘E’ | ’e’ ][ sign ] digit { digit } ]

sign ‘+’ | ‘-’

string_literal ‘’’ any_letters_except_single_quote ‘’’

simple_id letter { letter | digit | ‘_’ }

letter (a-z, A-Z)

digit (0-9)

Argument Description

Page 53: MSC.mvision Database Programmatic Interface

53CHAPTER 2Object Types, Expressions and Functions

2.6 Forming ExpressionsThe expression syntax described in Expression Syntax and Arguments (p. 50) allows flexibility in creating query, select, and other expressions. The following section expands on the previous descriptions detailing valid terms, operators, and finctions. This section also presents examples using the described syntax to form DPI expressions.

Valid Characters and Number FormatsValid characters for use in attribute and relation (table) names are:

a through z

A through Z

0 through 9

_ , @, %

Note: Do not use ‘_’ as the first character in a attribute or relation (table) name. This character is reserved for internally defined variables.

Valid characters for use as operators are:

Valid number formats are, in general:

[+-]{digits}.{digits}[eE][+-]{digits}

For example:

125-125.7125e+4125E+4125.7e+45

+ Addition

- Subtraction

* Multiplication

/ Division

** Exponentiation

DIV , div Force integer division

[ ] Array index

Page 54: MSC.mvision Database Programmatic Interface

4

Comparison OperatorsComparison operators are key elements of the specification for search criteria (i.e. query, selct, etc.). A comparison formula typically has three parts:

{attribute name} {operator} {criteria}

where attribute name is a valid database attribute, operator is one of the comparison operators described in this section, and criteria is a numeric or string value. For example:

E_T > 10e+06FORM like ‘*sheet*’

Valid numerical comparison operators are:

Valid character (string) comparison operators are:

Valid existence operators are:

Valid logical values are:

< less than

> greater than

<= less than or equal to

>= greater than or equal to

= equal to

<> , != not equal

!= not exact match

= exact match

like case insensitive match with optional wildcard

not like inverse of above

EXISTS, exists, EX, ex Object has a value (is not null)

IS NULL,is null Object does not have a value

Page 55: MSC.mvision Database Programmatic Interface

55CHAPTER 2Object Types, Expressions and Functions

TRUE , trueFALSE , false

The format for indicating a range or interval is:

{ simple_expression relational_operator simple_expression relational_operator simple_expression }EXAMPLE: {5<E11T<10}

Logical OperatorsLogical operators are used to combine the effects of two or more comparisons. Parenthesis may be used to override the precedence of logical evaluations just as they do in algebraic evaluations.

Valid logical operators are:

Expression FunctionsExpression functions are used in expressions which act on objects via GrExpression. Expression functions are not stand-alone functions like the DPI functions, but are used exclusively within the context of DPI expressions. DPI functions manipulate DPI objects and handle communication with objects such as GrEvaluate and GrString. Expression functions do not manipulate objects or handle communications.

The following section describes the available expression functions, including syntax and arguments:

• ABS( number ) ; Returns absolute value of number

• ACOS( number ) ; Returns arc cosine of number

• ANY( [iterator <*] list | logical_expression ) ; Returns true if logical_expression (an expression that returns a logical value) is true for "any" member of the specified list.

Example: ANY( ENVIRONMENT | TEMP = 400 ) returns true if any TEMP attribute in the ENVIRONMENT table of the database has a value of 400.

• ASIN( number ) ; Returns arc sine of number

• ATAN( number ) ; Returns arc tangent of number

AND, and Both comparisons must be satisfied.

OR, or Either comparison must be satisfied.

XOR, xor Either, but not both comparisons must be satisfied.

NOT, not Negates a comparison or existence operator.

Page 56: MSC.mvision Database Programmatic Interface

6

• AVG ( [iterator<*] list | expression ) ; Returns the average value of the expression calculated for each element in the specified list.

Example: AVG( MECH_TABLE | (E11T+E22T)/2 ) returns the average tensile and compressive Young’s Modulus ( E11T attribute value + E22T attribute value / 2) for all the MECH_TABLE table rows in the current database.

Example: AVG( query( SPECIMEN | form like '*sheet*' ) | THICKNESS) returns the average value of THICKNESS attribute for all SPECIMEN table rows where form attribute value contains "sheet". In this example the query function is used to generate a list of SPECIMEN objects for the AVG expression function. This example assumes that the THICKNESS attribute is in the SPECIMEN table or a higher level table, because AVG (an expression function) can search up the hierarchy but not lower level tables.

• CEIL( number ) ; Returns the smallest integer not less than numberExample: CEIL( 8.3 ) = 9

• COS( number ) ; Returns cosine of number

• COSH( number ) ; Returns hyperbolic cosine of number

• DEGTORAD ( number ) ; Returns the converted value of number for degrees to radians

• DISTINCT( [iterator<*] list | expression_list ) ;Removes duplicate rows from a list using one or more expressions to determine duplicity.

Example: DISTINCT( MATERIAL | UNS, CNAME ) returns a list of MATERIAL table rows with no duplicate combinations of the attributes UNS and CNAME. This assumes UNS and CNAME are in MATERIAL table or a higher level table because DISTINCT (an expression function) can search up the hierarchy but not lower level tables.

Example: DISTINCT( ENVIRON | TEMP, (TEMP*THICKNESS)/5 ) returns a list of ENVIRON table rows with no duplicate combinations of TEMP attribute or the expression (TEMP*THICKNESS)/5. The list of ENVIRON rows will not have a “column” for (TEMP*THICKNESS)/5, but would be made distinct using this expression.

• ERF( number ) ; Returns the error function of number where:

• EXP( number ) ; Returns exponential of number (base e)

erf x( ) 2

π e t2– td0x

∫----------------------------=

Page 57: MSC.mvision Database Programmatic Interface

57CHAPTER 2Object Types, Expressions and Functions

• FLOOR( number ) ; Returns largest integer not greater than numberExample: FLOOR( 8.3 ) = 8

• GROUP( [iterator<*] list | expression_list ) ; Returns a list of elements grouped such that the members of each group will have the same value for each expression in expression_list. GROUP returns a list whose elements are a list of the members of group ( i.e. a list of lists ).

Example: GROUP( SPECIMEN | FORM, HEAT_TREAT ) returns a list whose elements are groups (lists) of SPECIMEN table rows with the same attribute values for FORM and HEAT_TREAT.

The DISTINCT function is similar to GROUP, except that DISTINCT removes duplicate rows (based on the expression list) and GROUP does not. For example, SIZEOF( GROUP( SPECIMEN | FORM, HEAT_TREAT ) ) and SIZEOF( DISTINCT (SPECIMEN | FORM, HEAT_TREAT) ) will both return the number of SPECIMEN table rows with unique combinations of FORM and HEAT_TREAT. However, the elements in the DISTINCT list will contain only the first FORM-HEAT_TREAT row encountered. The GROUP list elements are themselves lists of all of the group members, so all table rows can also be accessed. Also GROUP like DISTINCT is (an expression function) can search up the hierarchy but not lower level tables.

• IF( logical_expression , argument1 , argument2 ) ; Returns argument1 or argument2. If the logical_expression evaluates to true, then the function returns argument1. If the logical_expression evaluates to false, then the function returns argument2. Argument1 and argument2 may be of any data type, but "must" be of the same data type.

• INTERP_X( curve_object , real_expression ) ; Returns the abscissa (Y) value of curve_object by linearly interpolating at the ordinate value of real_expression. This function returns a null if the X value is beyond the endpoints of the curve.

A figure object may contain many curves, scatter points, error bars, etc. Curves may contain XY pairs, a runout point, and a plot code. However, most figures consist of a single curve with only XY pairs. As a programming aid, INTERP_X and INTERP_Y will accept a figure object instead of a curve object. The figure object will be converted to a curve object by assuming the first curve in the figure should be interpolated. This is equivalent to specifying the 0th curve element of the figure, such as SIGvsEPS.curves[0].

Example: INTERP_X( SIGvsEPS , 3000 ) returns a real number indicating the Y value of the first curve of the SIGvsEPS figure which is associated with an X value of 3000. .

• INTERP_Y( curve_object , real_expression ) ; Returns the ordinate (X) value of curve_object by linearly interpolating at the abscissa value of real_expression. This function returns a null if the Y value is beyond the endpoints of the curve. See INTERP_X for example and notes.

Page 58: MSC.mvision Database Programmatic Interface

8

• LENGTH( string_expression ) Returns the number of characters in the string specified by string_expression.

• LOG( number ) ; Returns natural logarithm of number.

• LOG10( number ) ; Returns base 10 logarithm of number.

• MAX( [iterator<*] list | expression ) ; Returns the maximum (scalar) value of the expression after the expression is evaluated for each member of the list.

Example: MAX( self | (E11T/DENS) ) returns the maximum specific stiffness (Young’s Modulus / Density) for all of the table rows in the database (self).

• MIN( [iterator<*] list | expression ) ; Returns the minimum (scalar) value of the expression after the expression is evaluated for each member of the list. See MAX function above for example.

• NVL( object1 , object2 ) ; Returns object1 or object2. If object1 is null, function returns object2. If object1 is not null, function returns object1. Object1 and object2 "must" be of the same type.

• QUERY( [iterator<*] list | comparison_expression ) ; Returns a list of objects from the specified list that satisfy the comparison_expression. The result of comparison_expression "must" be a logical true or false. “Self” may be used as a list. This indicates the object of the evaluation- is a list or the highest hierarchical table in the database. QUERY is a “smart function” that allows “inheritance” from both higher and lower tables in the hierarchy, this means that the function can search either higher or lower level tables.

Example: QUERY( MATERIAL | E11T > 10 ) returns a list of MATERIAL table rows where the value of the E11T attribute is greater than 10.

Example: QUERY( self | E11T > 10 ) returns the same list as the above example assuming that MATERIAL is the highest hierarchical table in the database.

Example: QUERY( ENVIRONMENT | E11T > 10 ) returns a list of ENVIRONMENT table rows where the value of the E11T attribute is greater than 10. The attribute E11T does not have to be in the ENVIRONMENT table because the Query function has upwards and downwards inheritance capability.

See Query Syntax and Function (p. 72) for further description.

• RADTODEG( number ) ; Returns number converted from radians to degrees.

• ROUND( number ) ; Returns number rounded up to the nearest integer if the fractional part of number exceeds .5, or rounded down to the nearest integer if the fractional part does not exceed .5

Page 59: MSC.mvision Database Programmatic Interface

59CHAPTER 2Object Types, Expressions and Functions

• SELECT( [iterator<*] list | object_expression_list [| comparison_expression] ) : Returns a list of rows that satisfy the comparison_expression. Each row returned consists of the objects in the object_expression_list. Similar to the QUERY function, the SELECT function is a "smart function" that allows inheritance from both higher and lower tables in the hierarchy. The SELECT function also contains logic to automatically “flatten out” the hierarchy into a table. For example, consider a database structure with two PROPERTY table at the bottom of the hierarchy that are differentiated with a source attribute such as statistical basis (basis A and B ) and a stress-strain curve. If the material name (from a hierarchical table), E11T (from the PROPERTY tables), and the stress-strain curve are included in a SELECT, then E11T will have two different values (the basis A and basis B values). The SELECT function will expand this single database entry into two rows. The first row will contain the basis A value of E11T and the stress-strain curve, the second row will contain the Basis B value of E11T and the stress-strain curve.

Example: SELECT( self | cname, form, temp, e11t | e11t > 10 ) returns a table whose columns are cname, form, temp, and e11t. The value of the e11t attribute for each row will be greater than 10.

Example: SELECT( self | cname, form, temp, e11t | density < .1 ) returns a table whose columns are cname, form, temp, and e11t. The value of the density attribute for each row will be less than .1.

Example: SELECT( self | cname, form, temp, e11t ) returns a table whose columns are cname, form, temp, and e11t for all rows in the database.

Example: SELECT( query( e11t > 10 ) | cname, form, temp, e11t | )

returns a table whose columns are cname, form, temp, and e11t. The value of the e11t attribute for each row will be greater than 10. Note that inthis example the query function is used to prefilter the input list instead of using the query argument of the select.

Example: SORT( SELECT( self | cname, e11t | e11t exists ) | col_1,

col_2 ) This example uses the sort function to sort the results of a select. The select provides an input list of cname and e11t rows for every occurrence of e11t in the database (e11t exists). Sort then does a primary sort on col_1 (cname) and a secondary sort on col_2 (e11t). Note that col_1 and col_2 (i.e. col_n) are understood for any select result. They are equivalent to self[0] and self[1] which indicate the first and second elements of the select rows. This is required because the select result is a custom built row — the sort function does not understand the message cname or e11t.

Page 60: MSC.mvision Database Programmatic Interface

0

Example: SELECT( self | MATERIAL, e11t ) returns a table of all the e11t attribute values from the database and the related MATERIAL table row. In this example a MATERIAL table_row object, not just an attribute value, is in the first column of each returned row. This demonstrates the heterogeneous possibilities of select tables. Also note that the conditional expression (query) has been omitted from this select thereby selecting all the MATERIAL-E11T combinations from the object being evaluated.

See Select Syntax and Function (p. 82) for further desciption.

• SIN( number ) ; Returns sine of number

• SINH( number ) ; Returns hyperbolic sine of number

• SIZEOF( list ) ; Returns the number of elements (rows) in the spefied list as an integer.

Example: SIZEOF( query( SPECIMEN | US11T > 30. ) ) returns the number of SPECIMEN table rows where ultimate longitudinal tensile strength (the value of US11T attribute ) is greater than 30.

• SORT( [iterator<*] list | expression_list ) ; Returns a list with elements of the input list in ascending order for the attributes or objects in the expression_list. The primary sort is according to the first expression in the expression_list, the secondary sort is according to the second expression in the expression_list, etc.

Example: SORT( SPECIMEN | HEAT_TREAT ) Returns a list of SPECIMEN table rows sorted by the avalue of the HEAT_TREAT attribute . This example assumes that the attribute HEAT_TREAT is in the SPECIMEN table or a higher level table. SORT is (an expression function) can search up the hierarchy but not lower level tables.

Example: SORT( SPECIMEN | (THICKNESS*LENGTH*WIDTH) ) returns a list of SPECIMEN objects sorted by their computed volume, the product of the values of the THICKNESS, LENGTH, and WIDTH attributes.

Example: SORT( query( SPECIMEN | us11t > 100. ) | HEAT_TREAT )

Returns a list of SPECIMEN table rows whose us11t attribute value is greater than 100 and is sorted in ascending order by the value of the HEAT_TREAT attribute . Note that query, is a smart function and can accept the us11t attribute which is in a table below the SPECIMEN table level. But the sort function requires the HEAT_TREAT attribute be in the SPECIMEN table or a higher level table.

Example: SORT( SELECT( self | cname, e11t | e11t exists ) | col_1,

col_2 ) This example uses the sort function to sort the results of a select. Refer to the Select Example above for a further description.

• SQRT( number ) ; Returns square root of number

• TAN( number ) ; Returns tangent of number

Page 61: MSC.mvision Database Programmatic Interface

61CHAPTER 2Object Types, Expressions and Functions

• TANH( number ) ; Returns hyperbolic tangent of number

• TRUNC( number ) ; Returns largest integer not greater than numberExample: TRUNC( 8.3 ) = 8

Iterators and “Smart” functionsMany of the expression function arguments allow, as an option, explicit iterator variables. Iterator variables allow explicit control the evaluation of an expression by assigning variables used by the evaluator as it iterates through a list. Iterator variables are assigned in an expression with the “<*” syntax. For example:

“Smart” syntax:

QUERY( SPECIMEN | DENSITY > .1 )

is actually translated to:

QUERY( a<*SPECIMEN | a.DENSITY > .1 )

before the expression is used. The above example is a simple case as the attribute DENSITY is in the SPECIMEN table and a list of SPECIMEN objects is requested in the query.

A more complex example is when attributes from different tables are used together in an expression.

“Smart” syntax:

QUERY( MATERIAL | (DENSITY/ZFACTOR) > 10 )

is actually translated to:

QUERY( a<* MATERIAL | ANY( b<* SPECIMEN_ROWS | (b.DENSITY/a.ZFACTOR) > 10 ))

before the expression is used. The iterator variables a and b are used to explicitly identify DENSITY and ZFACTOR by prefixing them with the appropriate table object. The variable a is assigned a new MATERIAL row and variable b is assigned a new SPECIMEN row as each element in the list of MATERIAL objects is evaluated by the query function.

The “smart” query and select functions automatically assign the iterator variables and perform the joins that are required in a typical SQL approach to these operations. This saves the DPI programmer time and effort, however DPI iterators can be explicitly specified to control an evaluation.

Lists

Many of the expression function arguments use lists. Lists are a powerful and versatile part of the DPI expression syntax. List element data types may be homogeneous or heterogeneous. The list processing of heterogeneous lists is limited to the SIZEOF function and access to the individual list elements.

Lists can be created by the following methods:

Page 62: MSC.mvision Database Programmatic Interface

2

• Evaluating a query or select against a database

• Evaluating a query or select against another list

• Using the GrGetValue function to list the:

• curves in a figure object

• points in a curve object

• database schema information to include: tables, attributes, hierarchical tables, synonyms, named conditions, and tables referenced by an expression.

• Matrices are a list of lists; each element of a matrix list is a list of the elements in that row.

Lists are basically a series of pointers. A query or select result does not contain a copy of the database information but rather pointers to the information in the database which are resolved as a list is interrogated. List references, however, are never more than once removed. This means that lists created from other lists reference the source information directly, not the intermediate list. For example, in the following sequence:

DATABASE =(query)=> LIST1 =(query)=> LIST2

the pointers in LIST1 reference DATABASE, and the pointers in LIST2 reference DATABASE. The destruction of LIST1 will have no effect on LIST2. These rules are true for all list operations and list sources as illustrated by the sequences:

DATABASE =(query)=> LIST1 =(sort)=> LIST2

or

LIST1 =(query)=> LIST2 =(sort)=> LIST3

behave exactly the same as the first example.

List SyntaxLIST_NAME[ index ]

where LIST_NAME is the name of the list object and index is the index number of the list element (row) to be accessed.

All DPI indices start from 0. Thus, SPECIMEN_ROW[1] is the second element of the list of specimen rows.

The following are examples for the use of lists:

Example: Query a database, then refine the search by querying the results of the first query.

GrExpression( "query( MATERIAL | E11T > 10)", &query1)GrEvaluate( db_handle, query1, &list1)GrExpression( "query( self | US11T > 100.)", &query2)GrEvaluate( list1, query2, &list2)

Page 63: MSC.mvision Database Programmatic Interface

63CHAPTER 2Object Types, Expressions and Functions

Example: Provide a handle to the first value in the first row of the results of a select (the first MATERIAL table row object listed) .

select( self | MATERIAL, E11T )[0][0]

Example: Sort on the first column of an input list.

GrExpression( "sort( input_list | self[0] )", &sort)

Example: Create a heterogeneous list.

GrExpression( "[ 'string' , 1.0 , 4 , .9 ]", &list)

Example: Create a homogeneous list of lists (an array).

GrExpression( " [ [ 1, 2, 3], [4, 5, 6], [7, 8, 9] ]", &list_of_lists)

Page 64: MSC.mvision Database Programmatic Interface

4

Expression MessagesThe DPI expression syntax can be used to form messages (instructions) to DPI objects. The DPI also contains “built-in” messages for specific types of DPI objects. These "built-in" messages and the GR object types to they apply are decribed in the following table:

Expression Messages

Object Message Result

any self IDENTITY

TABLE_ROW _row_id INTEGER

_storage_id INTEGER

_row_footnote STRING

{attribute_name} ATTRIBUTE VALUE

{attribute_name}.value ATTRIBUTE VALUE

{attribute_name}.footnote STRING

{attribute_name}.metadata STRING

{table_name} TABLE_ROW Object

_{table_name} TABLE_ROW Object (specified table must be at a higher level)

_{table_name}_rows LIST OF TABLE_ROW (specified table must be at next lower level)

_{table_name}_has_rows Table has rows at the next lower level. Returns TRUE or FALSE. This message is equivalent to the expression sizeof(_{table_name}_rows) > 0

Page 65: MSC.mvision Database Programmatic Interface

65CHAPTER 2Object Types, Expressions and Functions

{table_name}.uid STRING

{table_name}.uid_external_id INTEGER

{table_name}.uid_external_space STRING

DATABASE attributes LIST OF ATTRIBUTE OBJECTS

header STRING

pda_number INTEGER

name STRING

units_file STRING

named_conditions LIST OF NAMED_CONDITION OBJECTS

property_tables LIST OF TABLE OBJECTS

unit_systems LIST OF STRING

current_unit_system STRING

tables LIST OF TABLE OBJECTS

hierarchy_tables LIST OF TABLE OBJECTS (sorted in hierarchy order)

source_table TABLE OBJECT

{table_name} LIST OF TABLE_ROW OBJECTS

Expression Messages (continued)

Object Message Result

Page 66: MSC.mvision Database Programmatic Interface

6

TABLE name STRING

type STRING ["PROP"| "HIERARCHY"| "SOURCE"]

level INTEGER

attributes LIST OF ATTRIBUTE OBJECTS

ATTRIBUTE type STRING ["REAL"| "STRING"| "INTEGER"| "FIGURE"| "BINARY"]

level INTEGER

table TABLE OBJECT

synonyms LIST OF STRINGS

name STRING

description STRING

units STRING

default_units STRING

width INTEGER

dimensionality INTEGER

precision REAL

bound1 INTEGER

bound2 INTEGER

NAMED_CONDITION name STRING

condition STRING

POINT x REAL

y REAL

Expression Messages (continued)

Object Message Result

Page 67: MSC.mvision Database Programmatic Interface

67CHAPTER 2Object Types, Expressions and Functions

RANGE_BAR point1 POINT OBJECT

point2 POINT OBJECT

FIGURE curves LIST OF CURVE OBJECTS

scatter_points LIST OF POINT OBJECTS

run_out_points LIST OF POINT OBJECTS

range_bars LIST OF RANGE_BAR OBJECTS

x_scale STRING ["LINEAR" | "LOG"]

y_scale STRING ["LINEAR" | "LOG"]

CURVE points LIST OF POINT OBJECTS

run_out LOGICAL

display_code STRING ["SOLID" |"DASHED"]

SELECT_ROW col_1 First column in SELECT

col_2 Second column in SELECT

col_n nth column in SELECT

IMAGE file_name STRING (Name of the file containing the image.)

Expression Messages (continued)

Object Message Result

Page 68: MSC.mvision Database Programmatic Interface

8

Expression Data StructureDPI expressions are created with the function GrExpression from an expression definition string (text). The expression definition string must use the syntax and functions as previously described in this section.

The GrExpression function checks the syntax of the expression definition string and allocates a storage area (memory) for the compiled form of the expression string. The function returns a handle (pointer) to this storage area via the expression_handle argument.

The expression storage area includes space for the compiled expression string and space for the results of evaluating the expression. Thus, evaluating an expression once will fill the expression’s results area and evaluating it a second time will overwrite the results of the first evaluation.

For example:

Evaluation #1:

Expression_1 is created and used in an evaluation of object_X

GrExpression( "expression string", &expression_1)GrEvaluate( object_X, expression_1, &result_X)

The resulting memory structure is as shown below:

Evaluation #2:

Now the same expression used in evaluation #1 is reused to evaluate object_Y

GrEvaluate( object_Y, expression_1, &result_Y)

Expression_1

Structure

Space for the compiled expression string

Space for the results of the evaluation

(result_X)

Page 69: MSC.mvision Database Programmatic Interface

69CHAPTER 2Object Types, Expressions and Functions

The resulting memory structure is now:

The variables result_X and result_Y are two separate program variables. But both point to the same memory location of the Expression_1 structure. This means that result_X is lost when result_Y is created by evaluating against object_Y. To preserve result_X, the program "must" extract all the data required from result_X before evaluating object_Y or a separate expressions "must" be created to produce result_X and result_Y separate storage areas.

It is also important to note in using this memory structure that freeing the memory used by an expression automatically frees any results associated with that expression. This behavior simplifies memory management for the DPI programmer.

Expression_1

Structure

Space for the compiled expression string

Space for the results of the evaluation

(result_Y)

Page 70: MSC.mvision Database Programmatic Interface

0

Page 71: MSC.mvision Database Programmatic Interface

MSC.Mvision Database Programmatic Interface User’s Guide and Reference

3 Query - Navigating With DPI

■ Query Syntax and Function

■ Example - Reading A Hierarchy

■ Example - Navigating A Hierarchy

Page 72: MSC.mvision Database Programmatic Interface

2

3.1 Query Syntax and FunctionIt is important to note that query is actually an operator and not a separate function. The function GrExpression is used to compile an expression definition string into a valid expression. Using the term query in a GrExpression definition string creates a query expression. To apply the query to an object, such as a list or a database, you must “evaluate” the expression against the required object. The syntax for creating an expression definition string using query is as shown below:

query( InputList_Expression | conditions )

InputList_Expression - is the expression applied to an object that creates the list of inputs for the query. The expression may be a table (relation) or a queried subset of a table, when querying a database object. The InputList_Expression specifies the hierarchy level that the query will return.

conditions - is the query conditions to be applied to the object before the results list is created. Condition can be any valid query expression. For example, e11t>10 or form like '*sheet*'.

Refer to query in Expression Functions (p. 55) for additional information.

The following are the typical steps required to query a database:

1. Connect to a database:GrConnectToDatabase( "./mil5f.des", 200, &db )

2. Create the query expression:GrExpression( "query ( material | e11t > 10)", &query )

3. Evaluate the query expression against the database:GrEvaluate( db, query, &query_list )

When the query expression has been evaluated, a handle on the results is returned to a user variable, &query_list in this eaxmple, the result is of type GrData. If the query string definition, “query( material | form like '*sheet*')”, were used in the previous example, the result would be a list whose elements (rows) were material table level objects.

Query results may be used in three ways:

• Each list element may be evaluated to extract attribute data at that level of the hierarchy.

• Each list element may be evaluated to extract attribute data at a higher level of the hierarchy.

• Each list element may be evaluated to produce a list of all related objects at the next lower level of the hierarchy.

Page 73: MSC.mvision Database Programmatic Interface

73CHAPTER 3Query - Navigating With DPI

3.2 Example - Reading A Hierarchy

An important part of any general database application is the ability to access data in databanks of different schemas. The DPI enables interrogation of a databank schema (structure) as well as the data. The following program opens a MSC.Mvision databank anmed pmc90.des, prints out each table (relation) name, prints all the attribute names in each table, and the description for each attribute.

#include "gr.h"

main()

/* This program opens up a database (pmc90.des) and prints out the tables and attributes */

{

/* Declare DPI variables (object handles) */

GrData db, tables, tab, attributes, att; int i, j, ntabs, natts; int retcode;

char *tab_name; char *att_desc, *att_name;

/* Initialize DPI */

if (GrInitialize() == FAILURE) { printf("%s\n", GrGetErrorMessage()); return; }

/* Connect to pmc90 and store handle in variable db */

retcode = GrConnectToDatabase("./pmc90.des", 100, &db);

if (retcode == GR_FAILURE) {

/* Print out the Error Message */

printf("...Error : %s\n", GrGetErrorMessage()); exit(1); }

/* Get the list of tables for the database */

GrGetValue( db, GRdatabaseTables, &tables);

/* Get the number of elements in list */

Page 74: MSC.mvision Database Programmatic Interface

4

GrGetValue( tables, GRlistSize, &ntabs);

for (i = 0; i < ntabs; i++) {

/* Get the ith element in the list (i.e. the ith table in the database ) */

GrGetListElement( tables, i, &tab);

/* Get the name of the table and print*/

GrGetValue( tab, GRtableName, &tab_name); printf("\nTable : %s\n", tab_name);

/* Get the list of attributes */

GrGetValue( tab, GRtableAttributes, &attributes); GrGetValue( attributes, GRlistSize, &natts);

for (j = 0; j < natts; j++) {

/* Get the jth attribute */

GrGetListElement( attributes, j, &att);

/* Get the name and description of attribute and print*/

GrGetValue( att, GRattributeName, &att_name); GrGetValue( att, GRattributeDescription, &att_desc); printf("%16s %s\n", att_name, att_desc); }

}

/* Disconnect from the database */

GrDisconnectFromDatabase("./pmc90.des");

/* Shut down the DPI */

GrClose();}

Page 75: MSC.mvision Database Programmatic Interface

75CHAPTER 3Query - Navigating With DPI

This example program produces output simillar to the following :

Table : MATERIALESIG Manufacturer DesignationCNAME Common NamePMC Polymer Matrix Composite designationFIBER Fiber designationMATRIX Matrix designationFIBSG Fiber specific gravityMTXSG Matrix specific gravity

Table : SPECIMENFORM Construction/physical formMTXPCT Matrix content by weightFIBPCT Fiber content by volumeSG Specific gravityPLYMF Prepreg manufacturerVOLS Prepreg Volatiles Content by WeightRESINWT Prepreg Resin Content by weightFLOW Prepreg resin flowGEL Gel timeVOIDS Void content by volumePLYTH Composite ply thicknessTGDRY Glass Transition Temperature DryTGWET Glass Transition Temperature Wet

Table : ENVIRONMENTTEMP Test TemperatureHUMID Relative humiditySIGLEV Stress levelFREQ Test frequencyRATIO Stress ratioBASIS Statistical basisTESTNO Test number

Table : SOURCETABLE Source table numberFIGURE Source figure numberBOOK Source handbookAUTHOR Source author/editorPUBLSHR Source publisher

Table : PROPERTYE11T Tensile Elastic ModulusE22T Tensile Elastic ModulusE11C Compressive Elastic ModulusE22C Compressive Elastic ModulusNU12 Poisson ratioG12 Shear ModulusCTE11 Thermal Expansion Coefficient--Fiber directionCTE22 Thermal Expansion Coefficient--TransverseCTC33 Cross-ply Coefficient of Thermal ConductivityE11F Flexural ModulusE22F Flexural ModulusYS11T Tensile Yield StrengthYS22T Tensile Yield StrengthS11C Compressive Yield StrengthYS22C Compressive Yield Strength

Page 76: MSC.mvision Database Programmatic Interface

6

US11T Ultimate Tensile StrengthUS22T Ultimate Tensile StrengthUS11C Ultimate Compressive StrengthUS22C Ultimate Compressive StrengthUS11F Ultimate Flexural StrengthUS22F Ultimate Flexural StrengthUS12S Ultimate Inplane Shear StrengthUS13SB Ultimate Interlaminar Short Beam Shear StrengthUE11T Ultimate tensile strainUE22T Ultimate tensile strainUE11C Ultimate compressive strainUE22C Ultimate compressive strainCP Specific heat at constant pressureTABLE_NAME Descriptive name of tableUS45T Ultimate strength 45 deg to fiberYS45T Yield strength 45 deg to fiberE45T Elastic modulus 45 deg to fiberUE45T Ultimate elongation 45 deg to fiberNU45T Inplane Poisson ratio 45 deg to fiberCTE45 Coefficient of Thermal Expansion 45 deg to fiberCTC33T45 Cross-ply thermal conductivity coefficient for +-45

deg specimensTable : SIG11TvsEPS22

SIG11TvsEPS22 Strain in 2-Direction; Tensile Stress in 1-Direction

Table : SIG11TvsEPS11SIG11TvsEPS11 Tensile Strain in 1-Direction; Tensile Stress in

1-DirectionTable : SIG22TvsEPS22

SIG22TvsEPS22 Tensile Strain in 2-Direction; Tensile Stress in 2-Direction

Table : SIG11CvsEPS11 SIG11CvsEPS11 Compressive Strain in 1-Direction; Compressive

Stress in 1-DirectionTable : SIG22CvsEPS22

SIG22CvsEPS22 Compressive Strain in 2-Direction; Compressive Stress in 2-Direction

Table : TAU12vsGAMMA12 TAU12vsGAMMA12 Inplane Shear Strain; Inplane Stress

Table : EPS11TvsTIME EPS11TvsTIME Time; Tensile Strain in 1-Direction

Table : EPS22TvsTIMEEPS22TvsTIME Time; Tensile Strain in 2-Direction

Table : SIG11vsNSIG11vsN Cycles To Failure; Stress in 1-Direction

Table : SIG22vsNSIG22vsN Cycles To Failure; Stress in 2-Direction

Page 77: MSC.mvision Database Programmatic Interface

77CHAPTER 3Query - Navigating With DPI

3.3 Example - Navigating A HierarchyMany programs involve browsing, moving from one level of the database hierarchy to another to display the contents of a databank. The DPI query operator is well suited to this task. The “rows” at each level of the databank can exist as a list. A TABLE_ROW object will produce a list of its child objects at the next level of the hierarchy when it receives a message, the message is the table name of the next table level in the database. To move up the hierarchy, requires a message to the database the table name of the level to “move” to. This message will produce a list of all the table row objects at that level. The following example illustrates a browsing technique.

#include "gr.h"

main(){ int i, status; int Num_Mat, material_selected;

/* Declare DPI variables (object handles) */

GrData db_handle; GrData query, material_list, material; GrData specimen_key, specimen_list, specimen; GrData cname_key, cname; GrData form_key, form; GrData desig_key, desig; GrData treat_key, treat;

/* Initialize DPI */

status = GrInitialize();

/* Get and print out the error message */

if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Connect to database */

status = GrConnectToDatabase( "./me_metals.des", 200, &db_handle ); if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Create an expression to query the material table in the database */

status = GrExpression( "query( material | e11t > 10.5 )", &query ); if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Evaluate the expression for the database */

Page 78: MSC.mvision Database Programmatic Interface

8

status = GrEvaluate( db_handle, query, &material_list ); if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Create an expression to get the cname of a material */

GrExpression( "CNAME", &cname_key );

printf( "Materials in me_metal.des with e11t > 10.5\n" );

/* Get the number of materials which satisfied the query */

Num_Mat = GrListSize( material_list ); for( i=0; i<Num_Mat; i++ ) {

/* For each material print out the cname */

GrGetListElement( material_list, i, &material ); GrEvaluate( material, cname_key, &cname ); printf( "%d) %s\n", i, GrString(cname) ); }

/* List out the specimens rows for the first material. Note that this could be done for any material in the list. The program could prompt for the desired material. Here the material_selected is set to 0. */ material_selected = 0;

/* Create expressions to evaluate the specimens of a material sorted by desig, form and treat. Also create expressions to access the desig, form and treat of a specimen.*/

GrExpression( "sort( SPECIMEN_ROWS | DESIG, FORM, TREAT )", &specimen_key ); GrExpression( "DESIG", &desig_key ); GrExpression( "FORM", &form_key ); GrExpression( "TREAT", &treat_key );

/* For the material selected evaluate the cname and get the list of specimens associated with it. */

GrGetListElement( material_list, material_selected, &material ); GrEvaluate( material, cname_key, &cname ); GrEvaluate( material, specimen_key, &specimen_list );

printf( "Specimens of %s\n", GrString(cname) );

for( i=0; i<GrListSize(specimen_list); i++ ) {

/* For each specimen print the desig, form and treat */

GrGetListElement( specimen_list, i, &specimen );

Page 79: MSC.mvision Database Programmatic Interface

79CHAPTER 3Query - Navigating With DPI

GrEvaluate( specimen, desig_key, &desig ); GrEvaluate( specimen, form_key, &form ); GrEvaluate( specimen, treat_key, &treat );

printf( "%d) %s %s %s\n", i, GrString(desig), GrString(form), GrString(treat) ); }

/* Disconnect from the database */

GrDisconnectFromDatabase("./me_metals.des");

/* Shut down the DPI */

GrClose();}

This example will produce output similar to the following:

Materials in me_metal.des with e11t > 10.50) Low-Alloy Steel1) Ti-6Al-4VSpecimens of Low-Alloy Steel0) AISI 4340 All Quench and temper to 125 ksi1) AISI 4340 All Quench and temper to 150 ksi2) AISI 4340 All Quench and temper to 180 ksi3) AISI 4340 All Quench and temper to 200 ksi4) AISI 4340 All Quench and temper to 260 ksi5) AISI 4340 All products 140-ksi level6) AISI 4340 All products 180-ksi level7) AISI 4340 All products 200-ksi level8) AISI 4340 Bar 200 ksi9) AISI 4340 Bar 200 ksi10) AISI 4340 Bar 200 ksi11) AISI 4340 Bar 260 ksi12) AISI 4340 Bar 260 ksi13) AISI 4340 Bar 260 ksi14) AISI 4340 Bar 260-ksi level15) AISI 4340 Bar <=180 ksi16) AISI 4340 Bar <=180 ksi...

Page 80: MSC.mvision Database Programmatic Interface

0

Page 81: MSC.mvision Database Programmatic Interface

MSC.Mvision Database Programmatic Interface User’s Guide and Reference

4 Select - Making Tables With DPI

■ Select Syntax and Function

■ Example - Selecting Tabular Data

Page 82: MSC.mvision Database Programmatic Interface

2

4.1 Select Syntax and FunctionIt is important to note that select is actually an operator and not a separate function. The function GrExpression is used to compile an expression definition string into a vaid expression. Using the term select in a GrExpression definition string creates a select expression. which is compiled by GrExpression. The select expression can be applied to an object, such as a list or a database, to perform the action of selecting (extracting) data. To perform the action the expression must be “evaluated” agianst an object. The syntax for creating an expression definition string using select is as shown below:

select( InputList_Expression | attributes_to_select | conditions )

InputList_Expression - the expression applied to an object that creates the list of inputs for the select. The expression may be a table (relation) or a queried subset of a table when selecting from a database object. The InputList_Expression is usually the name of the table at the highest hierarchical level since that table usually has the fewest rows and select works fastest with a smal input list. If the databases highest table is named “MATERIAL” and an attribute is named E11T, the following statement would be a valid InputList_Expression.

query (material | E11T>10)

Where material equals all materials and comparison expression retruns material rows whose E11T is greater than 10.

attributes_to_select - a list of attribute names whose values will be extracted with the select. For this function, the “select” is the output of the InputList_Expression after “conditions” have been applied to the list of inputs. Any valid database attributes can be used in attributes_to_select.

conditions - a query condition to be applied to the output of InputList_Expression before the attribute values are extracted. Any valid query expression can be used as a condition. Example: e11t>10, form like ‘*sheet*’

Refer to select in Expression Functions (p. 55) for additional information.

The following are the typical steps required to perform a select for a database:

1. Connect to a database. GrConnectToDatabase( "./mil5f.des", 200, &db ).

2. Create a select expression. GrExpression( "select( material | cname, form, us11t | e11t > 10.) ", &select ).

3. Evaluate the select expression against an object (in this example, the database). GrEvaluate( db, select, &select_list ).

Page 83: MSC.mvision Database Programmatic Interface

83CHAPTER 4Select - Making Tables With DPI

When the select expression has been evaluated, a handle on the results is returned to a user variable, &select_list in this example, the resul is of type GrData. There are two methods of retrieving select data from a GrData variable: the general method and the GrFetchFromSelect function.

The general method of interrogating a GrData structure applies regardless of the means by which the structure was filled. All objects are treated the same by the DPI, whether created by querying, selecting, sorting, or any other operation. In general, an object can be interrogated for its type and then the object can be broken down into its component objects. These component objects can in turn be broken down until the resulting objects are of a base type real, string, etc.

As applied to select results, the general method of retrieving data involves interrogating the list that results from evaluating a select expression. The retrieval process using the general method for the above example requires the following steps:

1. Use the function GrListSize( select_list ) to determine the number of row objects (“rows”) in the select result.

2. Create an expression for each attribute to be retrieved from the row. These attribute names must be included in the select expression attribute list or the row object will not understand this instruction. Example: GrExpression( "cname", &cname_key)

3. Retrieve one row from the select result with the function GrGetListElement( select_list, row_number, &row ).

4. Evaluate the row result with the attribute name(s) to be retrieved. Using the function GrEvaluate ( row, cname_key, &cname ).

5. In the above example the variable cname is of type GrData and is a handle on an object. You can evaluate an expression against cname to determine its type or if the type is known, you can use GrExpression(cname, GRstringValue, &cname_string) to fill the user variable cname_string with the characters which make up the value of cname for this row.

6. Loop through the other attributes in the row to retrieve the selected data.

7. Loop through result rows to retrieve all selected data.

The general method will access all schema information and all the data in any databank. The function works regardless of data type and requires no knowledge of the database schema being interrogated.

The other method of retrieving data from a select result is the GrFetchFromSelect function. Using GrFetchFromSelect reduces programming time for simple selects, but does not provide complete access to all the data as the general method does. The retrieval process using the GrFetchFromSelect function for the above example requires the following steps:

Page 84: MSC.mvision Database Programmatic Interface

4

1. Use the function GrListSize( select_list ) to determine the number of row objects (“rows”) in the select result.

2. Use the function GrFetchFromSelect( select_list, i, &cname, &form, &us11t) to retrieve the objects from the ith row in the list.

3. Use the “shortcut” GrGetValue functions to extract data from the row objects (See Access Codes for GrGetValue Function (p. 39)). To determine which GrGetValue function to use, interrogate the object (such as cname) for its object type with GrGetValue( cname, GRtype, &type ). Use the type information to determine which GrGetValue function to use. The following are examples of GrGetValue function usage:cname_string = GrString ( cname )

us11t_real = GrReal( us11t )

4. Loop through result rows to retrieve all selected data.

Page 85: MSC.mvision Database Programmatic Interface

85CHAPTER 4Select - Making Tables With DPI

4.2 Example - Selecting Tabular DataThe following example demostrates the select technique for extracting data from a databank. The following program opens a databank and selects attributes CNAME and E11T for all databank rows whose E11T>10.5 and prints a listing of CNAME and E11T to standard output.

#include "gr.h"

main(){ int i, status; int Num_Mat;

/* Declare DPI variables (object handles) */

GrData db_handle; GrData select, select_list; GrData cname, e11t;

/* Initialize DPI */

status = GrInitialize();

/* Get and print out the error message */

if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Connect to database */

status = GrConnectToDatabase( "./me_metals.des", 200, &db_handle ); if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Create an expression to query the material relation in the database */

status = GrExpression( "select( material | cname, e11t | e11t > 10.5 )", &select ); if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Evaluate the expression for the database */

status = GrEvaluate( db_handle, select, &select_list ); if( status == GR_FAILURE ) { printf("%s\n",GrGetErrorMessage()); exit(1); }

/* Get the number of rows in the select structure */

Num_Mat = GrListSize( select_list ); for( i=0; i<Num_Mat; i++ ) {

Page 86: MSC.mvision Database Programmatic Interface

6

/* For each row print out the cname, e11t */

GrFetchFromSelect( select_list, i, &cname, &e11t ); printf( "%d) %s %f\n", i, GrString(cname), GrReal(e11t) ); }

/* Disconnect from the database */

GrDisconnectFromDatabase("./me_metals.des");

/* Shut down the DPI */

GrClose();}

This example program produces output similar to the following results:

0) Low-Alloy Steel 29.0000001) Ti-6Al-4V 16.0000002) Ti-6Al-4V 16.0000003) Ti-6Al-4V 16.0000004) Ti-6Al-4V 16.0000005) Ti-6Al-4V 16.0000006) Ti-6Al-4V 16.0000007) Ti-6Al-4V 16.0000008) Ti-6Al-4V 16.0000009) Ti-6Al-4V 16.00000010) Ti-6Al-4V 16.00000011) Ti-6Al-4V 16.00000012) Ti-6Al-4V 16.00000013) Ti-6Al-4V 16.00000014) Ti-6Al-4V 16.00000015) Ti-6Al-4V 16.00000016) Ti-6Al-4V 16.000000...

Page 87: MSC.mvision Database Programmatic Interface

MSC.Mvision Database Programmatic Interface User’s Guide and Reference

5 Write Functions

■ Initializing DPI Write Functions

■ DPI Write Data Functions

■ DPI Write Schema Functions

■ Example of a DPI Write Program

Page 88: MSC.mvision Database Programmatic Interface

8

In addition to the standard DPI functions, the DPI provides a full set of functions for creating and modifying databanks. These functions operate similar to the standard DPI functions. They are contained in the same archive library named libdpi.a which is located in the MSC.Mvision Builder installation directory in the <install_dir>/lib directory.

5.1 Initializing DPI Write FunctionsTo activate the DPI write functions the following function "must" be called:

int GrInitializeWrite( void )

The integer return from this function is either symbol SUCCESS or FAILURE. This command requires a license for the MSC.Mvision Builder product.

5.2 DPI Write Data Functions

GrCommitDatabase

Commit a database (opens and writes to an existing database file).

int GrCommitDatabase( GrData db_handle )

• db_handle - A handle on a database object.

GrCommitDatabaseTo

Commit a database to a new file (opens and writes to a newly created file).

int GrCommitDatabaseTo( GrData db_handle, char *file_name)

• db_handle - A handle on a database object.

• file_name - Name of databank file to written to.

GrConnectToDatabaseForUpdate

Connect to a database for update (open an existing databank file with write permission).

int GrConnectToDatabaseForUpdate( char *file_name, int db_buffer_size, GrData *db_handle )

• file_name - File name of databank to be opened.

• db_buffer_size - Size, in kilobytes, of the database buffer (allocated memory) to be used for this database.

• db_handle - A handle on to newly created database object.

Page 89: MSC.mvision Database Programmatic Interface

89CHAPTER 5Write Functions

GrCreateHierarchyRow

Create a row in the database hierarchy (hierarchy table row object).

int GrCreateHierarchyRow( GrData table_handle, GrData parent_row_handle, GrData *row_handle )

• table_handle - A handle on a table object.

• parent_row_handle - A handle on the parent table row object (table row to be designated as a parent of the newly created table row).

• row_handle - A handle on newly created table row object.

GrCreatePropertyRow

Create a row in a property table (property table row object).

int GrCreatePropertyRow( GrData table_handle, GrData parent_row_handle, GrData source_row_handle, GrData *row_handle )

• table_handle - A handle on a table object.

• parent_row_handle - A handle on the parent table row object (table row to be designated as a parent of the newly created table row).

• source_row_handle - A handle on the source table row object (table row to be designated as a source for the newly created table row).

• row_handle - A handle on newly created table row object.

GrCreatePropertyRowAsDuplicate

Create a row in a property table which points to the same data as an existing data row.

int GrCreatePropertyRowAsDuplicate( GrData table_handle, GrData parent_row_handle, GrData source_row_handle, int storage_id, GrData *row_handle )

• table_handle - A handle on a table object.

• parent_row_handle - A handle on the parent table row object (table row to be designated as a parent of the newly created table row).

• source_row_handle - A handle on the source table row object (table row to be designated as a source for the newly created table row).

• storage_id - Storage row id of existing table row.

• row_handle - A handle on newly created table row object

GrCreateSourceRow

Create a row in the source table (source table row object).

Page 90: MSC.mvision Database Programmatic Interface

0

int GrCreateSourceRow( GrData table_handle, GrData *row_handle )

• table_handle - handle on a source table object.

• row_handle - A handle on newly created table row object

GrCreateTopLevelRow

Create a top level row in the database (table row object in highest level table object).

int GrCreateTopLevelRow( GrData table_handle, GrData *row_handle )

• table_handle - A handle on the highest level table object.

• row_handle - A handle on newly created table row object.

GrDeleteRow

Delete a row (table row object). Note this function does not reclaim the memory allocated to the table row object. The datababse must be recreated to reclaim this memory.

int GrDeleteRow( GrData row_handle, int cascade_flag)

• row_handle - A handle on a table row object.

• cascade_flag - Flag to indicate whether to delete childless parents. These are associated table rows which will no longer have child table rows following the deletion of this table row.

GrSetAttributeFootnote

Set the footnote of an attribute object in a table row.

int GrSetAttributeFootnote( GrData row_handle, GrData attribute_handle, int location )

• row_handle - A handle on a table row object.

• attribute_handle - A handle on an attribute object

• location - Location of footnote returned from GrStoreFootnote.

GrSetAttributeMetadata

Set the metadata of an attribute object in a table row.

int GrSetAttributeMetadata( GrData row_handle, GrData attribute_handle, int location )

• row_handle - A handle on a table row object.

• attribute_handle - A handle on an attribute object.

Page 91: MSC.mvision Database Programmatic Interface

91CHAPTER 5Write Functions

• location - Location of metadata returned from GrStoreFootnote.

GrSetAttributeNull

Set the value of an attribute object in a table row to null.

int GrSetAttributeNull( GrData row_handle, GrData attribute_handle)

• row_handle - A handle on a table row object.

• attribute_handle - A handle on an attribute object.

GrStoreAttributeFigurePoint

Set the value of a point object in a figure attribute object in a table row. GrStoreAttributeFigureSize must be called prior to this function to establish the number of points in the figure object.

int GrStoreAttributeFigurePoint( GrData row_handle, GrData attribute_handle, int index, double x, double y, int plot_code)

• row_handle - A handle on a table row object..

• attribute_handle - A handle on an attribute object.

• index - Index of point in figure (starting at 0).

• x - X-coordinate value.

• y - Y-coordinate value.

• plot_codeMSC.Mvision valid plot code.

GrStoreAttributeFigureSize

Set the number of point objects in a figure attribute object in a table row.

int GrStoreAttributeFigureSize( GrData row_handle,GrData attribute_handle, int size)

• row_handle - A handle on a table row object containing a figure type attribute object.

• attribute_handle - A handle on a figure type attribute object.

• size - Number of points (pairs of xy pairs) in the figure object.

GrStoreAttributeInteger

Set the value of an integer type attribute object in a table row.

int GrStoreAttributeInteger( GrData row_handle, GrData attribute_handle, int value)

Page 92: MSC.mvision Database Programmatic Interface

2

• row_handle - A handle on a table row object containing an integer type attribute object.

• attribute_handle - A handle on an integer type attribute object.

• value - Integer value to be set for the attribute object.

GrStoreAttributeMatrixElement

Set the value of an element of a matrix attribute in a table row. The values are stored in row order.

GrStoreAttributeMatrixSize must be called prior to this function.

int GrStoreAttributeMatrixElement( GrData row_handle,GrData attribute_handle, int index, double value )

• row_handle - A handle on a table row object containing a matrixtype attribute.

• attribute_handle - A handle on a matrix type attribute.

• index - Index.

• value - Real value to be set for index of matrix type attribute.

GrStoreAttributeMatrixSize

Set the size of a matrix type attribute in a table row.

int GrStoreAttributeMatrixSize( GrData row_handle,GrData attribute_handle, int size)

• row_handle - A handle on a table row object containing a matrixtype attribute.

• attribute_handle - A handle on a matrix type attribute.

• size - Size of matrix (number of indexes).

GrStoreAttributeReal

Set the value of a real type attribute in a table row.

int GrStoreAttributeReal( GrData row_handle, GrData attribute_handle, double value )

• row_handle - A handle on a table row object containing a real type attribute object.

• attribute_handle - A handle on a real type attribute object.

• value - Real value to be set for the attribute object

Page 93: MSC.mvision Database Programmatic Interface

93CHAPTER 5Write Functions

GrStoreAttributeString

Set the value of a string (cahr) type attribute in a table row.

int GrStoreAttributeString( GrData row_handle, GrData attribute_handle, char *value)

• row_handle - A handle on a table row object containing a string type attribute object.

• attribute_handle - A handle on a string type attribute object.

• value - String value to be set for the attribute object.

GrStoreFootnote

Store a footnote or metadata in the database.

int GrStoreFootnote( GrData db_handle, char *string, int *location)

• db_handle - A handle on a database.

• string - Footnote string (text).

• location - Location of footnote in the database.

GrUpgradeLock

Upgrade the lock on a database opened read-only so that it can be modified (add write pression for current database).

int GrUpgradeLock( GrData db_handle )

• db_handle - A handle on a database.

Page 94: MSC.mvision Database Programmatic Interface

4

5.3 DPI Write Schema Functions

GrCreateDatabase

Create a new database. Opon creation the name of each hierarchy table is assigned "LEVEL_<level>", the name of the source table is assigned "SOURCE". The names of the tables can be renamed using the GrRenameTable function.

int GrCreateDatabase( char *file_name, int n_levels, int db_buffer_size, GrData *db_handle )

• file_name - Name of new database file.

• n_levels - Number of levels in database.

• db_buffer_size - Size, in kilobytes, of the database buffer (allocted memory) to be used with this database.

• db_handle - A handle on the newly created database object.

GrCreateFigureAttribute

Create a figure attribute object in a table object.

int GrCreateFigureAttribute( GrData table_handle, char *name, char *x_desc, char *y_desc, char *x_units, char *y_units, GrData *attribute_handle )

• table_handle - A handle on a table object.

• name - Name of figure attribute to be created.

• x_desc - X-axis description (text) .

• y_desc - Y-axis description (text).

• x_units - X-axis units string (label).

• y_units - X-axis units string (label).

• attribute_handle - A handle on the newly created figure attribute object.

GrCreateFullTextAttribute

Create a full text attribute in a table object.

int GrCreateFullTextAttribute( GrData table_handle, char *name, char *description, GrData *attribute_handle )

• table_handle - A handle on a table object.

• name - Name of full text attribute to be created.

• description - Description of attribute (must begin with "TEXT:").

Page 95: MSC.mvision Database Programmatic Interface

95CHAPTER 5Write Functions

• attribute_handle - A handle on the newly created full text attribute object.

GrCreateImageAttribute

Create an image attribute in a table object

int GrCreateImageAttribute( GrData table_handle, char *name, char *description, GrData *attribute_handle )

• table_handle - A handle on a table object.

• name - Name of image attribute to be created.

• description - Description of attribute (text).

• attribute_handle - A handle on the newly created image attribute object.

GrCreateIntegerAttribute

Create an integer attribute in table object.

int GrCreateIntegerAttribute( GrData table_handle, char *name, char *description, GrData *attribute_handle )

• table_handle - A handle on a table object.

• name - Name of integer attribute to be created.

• description - Description of attribute (text).

• attribute_handle - A handle on the newly created integer attribute object.

GrCreateMatrixAttribute

Create a matrix attribute in table object.

int GrCreateMatrixAttribute( GrData table_handle, char *name, char *description, char *units, double precision, int dim_1, int dim_2, GrData *attribute_handle )

• table_handle - A handle on a table object.

• name - Name of matrix attribute to be created.

• description - Description of attribute (text).

• units - Units of matrix (label).

• precision - Default precision of matrix values.

• dim1 - Number of rows in matrix.

• dim2 - Number of columns in matrix.

• attribute_handle - A handle on the newly created matrix attribute object.

Page 96: MSC.mvision Database Programmatic Interface

6

GrCreateNamedCondition

Create a named condition object in the database.

int GrCreateNamedCondition( GrData db_handle, char *name, char *condition, GrData *nc_handle )

• db_handle - A handle on a database.

• name - Name of named condition to be created.

• condition - Condition ( query expression).

• nc_handle - A handle on newly created named condition object.

GrCreatePropertyTable

Create a property table object in the database.

int GrCreatePropertyTable( GrData db_handle, char *name,GrData *table_handle )

• db_handle - A handle on a database.

• name - Name of property table to be created.

• table_handle - A handle to newly created table object.

GrCreateRealAttribute

Create a real attribute in table object.

int GrCreateRealAttribute( GrData table_handle, char *name, char *description, char *units, double precision, GrData *attribute_handle )

• table_handle - A handle on a table object.

• name - Name of real attribute to be created.

• description - Description of attribute (text).

• units - Units of attribute (label).

• precision - Default precision of attribute value.

• attribute_handle - A handle on the newly created real attribute object.

GrCreateStringAttribute

Create a string (char) attribute in table object.

int GrCreateStringAttribute( GrData table_handle, char *name, char *description, int width, GrData *attribute_handle )

• table_handle - A handle on a table object.

Page 97: MSC.mvision Database Programmatic Interface

97CHAPTER 5Write Functions

• name - Name of string attribute to be created.

• description - Description of attribute (text).

• width - Width (length) of string attribute.

• attribute_handle - A handle on the newly created string attribute object.

GrCreateSynonym

Create a synonym (alias) for an exiting attribute in the database.

int GrCreateSynonym( GrData attribute_handle, char *name)

• attribute_handle - A handle on an attribute object.

• name - Name of synonym to be created.

GrCreateTableSegment

Create a new table segment for a table. Attributes added to the table will be stored in the new table segment.

int GrCreateTableSegment( GrData table_handle )

• table_handle - handle on a table object.

GrDeleteAttribute

Delete (remove) an attribute object from the database.

int GrDeleteAttribute( GrData attribute_handle )

• attribute_handle - A handle on the attribute object to be deleted.

GrDeleteNamedCondition

Delete (remove) a named condition object from the database.

int GrDeleteNamedCondition(GrData name_condition_handle)

• attribute_handle - A handle on the named condition object to be deleted.

GrDeleteSynonym

Delete (remove) a synonym (alias) from the database.

int GrDeleteSynonym( GrData attribute_handle, char *name)

• attribute_handle - A handle on the attribute object associated with the synonym.

• name - Name of the synonym to be deleted.

Page 98: MSC.mvision Database Programmatic Interface

8

GrDeleteTable

Delete (remove) a table object from the database.

int GrDeleteTable( GrData table_handle )

• table_handle - A handle on the table object to be deleted.

GrModifyAttributeDescription

Modify (change) an attribute object description. See GrModifyFigureDescription to change the description for a figure attribute.

int GrModifyAttributeDescription( GrData attribute_handle, char *description )

• attribute_handle - A handle on the attribute object, other than a figure attribute, to be changed.

• description - New description for attribute object.

GrModifyAttributePrecision

Modify (change) an attribute object precision.

int GrModifyAttributePrecision( GrData attribute_handle, double precision)

• attribute_handle - A handle on the (real type) attribute object to be changed.

• precision - New precision for attribute object.

GrModifyAttributeUnits

Modify (change) an attribute object units label. See GrModifyFigureUnits to change the units label for a figure attribute.

int GrModifyAttributeUnits( GrData attribute_handle, char *units )

• attribute_handle - A handle on the (real type) attribute object, other than a figure attribute, to be changed.

• units - New units label for attribute object.

GrModifyAttributeWidth

Modify (change) an attribute object width (string length).

int GrModifyAttributeWidth( GrData attribute_handle, int width)

• attribute_handle - A handle on the (string type) attribute object to be changed.

Page 99: MSC.mvision Database Programmatic Interface

99CHAPTER 5Write Functions

• width - New width (string length) for attribute object.

GrModifyDatabaseHeader

Modify (add text to) the header of a database.

int GrModifyDatabaseHeader( GrData attribute_handle,char *header)

• attribute_handle - A handle on a database object

• header - Database header information (text)

GrModifyFigureAttributeDescription

Modify (change) a figure attribute object description.

int GrModifyFigureAttributeDescription( GrData attribute_handle, char *x_desc, char *y_desc)

• attribute_handle - A handle on the (figure type) attribute object to be changed.

• x_desc - Description of x-axis (text).

• y_desc - Description of y-axis (text).

GrModifyFigureAttributeUnits

Modify (change) a figure attribute object units labels.

int GrModifyFigureAttributeUnits( GrData attribute_handle, char *x_units, char *y_units)

• attribute_handle - A handle on the (figure type) attribute object to be changed.

• x_units - Units of x-axis (label).

• y_units - Units of y-axis (label).

GrRenameAttribute

Rename (change) the "name" of existing attribute object.

int GrRenameAttribute( GrData attribute_handle, char *name)

• attribute_handle - A handle on the attribute object to be changed.

• name - New name for attribute object.

Page 100: MSC.mvision Database Programmatic Interface

0

GrRenameTable

Rename (change) the "name" of existing table object.

int GrRenameTable( GrData table_handle, char *name)

• table_handle - A handle on the table object to be changed.

• name - New name for table object.

Page 101: MSC.mvision Database Programmatic Interface

10CHAPTER 5Write Functions

5.4 Example of a DPI Write ProgramThe following is an example of a DPI program that adds a new table row to a databank. This example adds a new property set at 100 deg F for an existing material, AS1 GRAPHITE FIBER (DESIG = AS1 and FORM = FIBER).

A built-in inline macro named GR_ERROR_HANDLING is provided in the DPI to handle error messages. This macro is used, in this example, to process errors from the Gr functions. The GR_ERROR_HANDLING macro is defined at the beginning of this example. Refer to Error Messages (Appendix. A) for more information regarding the error messages processed by this macro.

#include <stdio.h> #include "gr.h"

/* This example program demonstrates the usage of the DPI write library. It adds a new table row to a database named fiber.des. A new property set at 100 deg F for the existing material AS1 GRAPHITE FIBER (DESIG = AS1 AND FORM = FIBER) is added. */

#define GR_ERROR_HANDLING if( status != GR_SUCCESS ) { printf( "%s\n", GrGetErrorMessage() ); GrClose(); exit(1); }

int LicensingMessage( message )char *message;{ printf( "%s\n", message );

return( GR_SUCCESS );}

main( argc, argv )int argc;char *argv[];{

int status, n_specimens;int footnote_handle;

/* Declare DPI variables (object handles) */

GrData db, specimen_expr, specimen_list, attribute;

GrData specimen_row, environment_row, source_row, property_row;

GrData environment_table, source_table, property_table;

/* Set the security messaging callback */

GrRegisterSecurityCallback( LicensingMessage );

/* Initialize the DPI for read/write access */

status = GrInitializeWrite();GR_ERROR_HANDLING;

Page 102: MSC.mvision Database Programmatic Interface

2

/* Connect to database for read/write */

status = GrConnectToDatabaseForUpdate( "./fiber.des", 1000, &db );GR_ERROR_HANDLING;

/* Get a handle on the table row in the SPECIMEN table for DESIG = AS1 and FORM = FIBER */

status = GrExpression( "query( specimen | desig = 'AS1' AND form = 'FIBER' )", &specimen_expr );

GR_ERROR_HANDLING;

status = GrEvaluate( db, specimen_expr, &specimen_list );GR_ERROR_HANDLING;

/* Make sure one and only one specimen is found */

status = GrGetValue( specimen_list, GRlistSize, &n_specimens );

GR_ERROR_HANDLING;

if( n_specimens == 0 ){

printf( "No specimen found with DESIG = AS1 and FORM = FIBER.\n" );

GrFreeExpression( specimen_expr );GrDisconnectFromDatabase( db );

GrClose();exit(1);

}else if( n_specimens != 1 ){

printf( "More than one specimen found with DESIG = AS1 and FORM = FIBER.\n" );

GrFreeExpression( specimen_expr );GrDisconnectFromDatabase( db );

GrClose();exit(1);

}

/* Get the specimen */

status = GrGetListElement( specimen_list, 0, &specimen_row );

GR_ERROR_HANDLING;

/* Lookup the ENVIRONMENT table */

status = GrLookupTable( db, "ENVIRONMENT", &environment_table );

GR_ERROR_HANDLING;

/* Create an ENVIRONMENT table row */

Page 103: MSC.mvision Database Programmatic Interface

10CHAPTER 5Write Functions

status = GrCreateHierarchyRow( environment_table, specimen_row, &environment_row );

GR_ERROR_HANDLING;

/* Free specimen expression (No longer needed) */

GrFreeExpression( specimen_expr );

/* Add attribute values to table row*/

status = GrLookupAttribute( db, "TEMP", &attribute );GR_ERROR_HANDLING;

status = GrStoreAttributeReal( environment_row, attribute, 100.0 );

GR_ERROR_HANDLING;

/* Add a footnote to the attribute */

status = GrStoreFootnote( db, "Data added by dpi write example program", &footnote_handle );

GR_ERROR_HANDLING;

status = GrSetAttributeFootnote( environment_row, attribute, footnote_handle );

GR_ERROR_HANDLING;

/* Get the source table */

status = GrGetValue( db, GRdatabaseSourceTable, &source_table );

GR_ERROR_HANDLING;

/* Create a source table row */

status = GrCreateSourceRow( source_table, &source_row );

GR_ERROR_HANDLING;

/* Add attribute values to table row */

status = GrLookupAttribute( db, "MFDATA", &attribute );

GR_ERROR_HANDLING;

status = GrStoreAttributeString( source_row, attribute, "HERCULES" );

GR_ERROR_HANDLING;

/* Lookup the PROPERTY table */

status = GrLookupTable( db, "PROPERTY", &property_table );

Page 104: MSC.mvision Database Programmatic Interface

4

GR_ERROR_HANDLING;

/* Create a PROPERTY table row */

status = GrCreatePropertyRow( property_table, environment_row, source_row,

&property_row ); GR_ERROR_HANDLING;

/* Add attribute values to table row */

status = GrLookupAttribute( db, "E11T", &attribute );GR_ERROR_HANDLING;

status = GrStoreAttributeReal( property_row, attribute, 36.0 );

GR_ERROR_HANDLING;

status = GrLookupAttribute( db, "US11T", &attribute );GR_ERROR_HANDLING;

status = GrStoreAttributeReal( property_row, attribute, 500.0 );

GR_ERROR_HANDLING;

status = GrLookupAttribute( db, "UE11T", &attribute );GR_ERROR_HANDLING;

status = GrStoreAttributeReal( property_row, attribute, 14000.0 );

GR_ERROR_HANDLING;

/* Commit database */

status = GrCommitDatabase( db );GR_ERROR_HANDLING;

GrDisconnectFromDatabase( db );

GrClose();exit(0);

}

Page 105: MSC.mvision Database Programmatic Interface

MSC.Mvision Database Programmatic Interface User’s Guide and Reference

A Error Messages

■ General Error Conditions

■ Mathematical Error Conditions

Page 106: MSC.mvision Database Programmatic Interface

6

This section describes the error conditions that can be generated by the built-in inline macro named GR_ERROR_HANDLING.

A.1 General Error Conditionstypedef enum { GR_NO_ERROR,

GR_AMBIGUOUS_SOURCE_EXPRESSIONGR_DATABASE_INDEXING_ABORTEDGR_NAMED_CONDITION_NOT_FOUNDGR_OBJECT_TYPE_ERRORGR_NOT_INITIALIZED, GR_OUT_OF_MEMORY, GR_FILE_OPEN_ERROR,GR_FILE_READ_ERROR, GR_AUTHORIZATION_ERROR,GR_GET_VALUE_ACCESS_ERROR, GR_EXPRESSION_SYNTAX_ERROR, GR_UNITS_FILE_SYNTAX_ERROR GR_UNIT_SYSTEM_NOT_FOUNDGR_LIST_ELEMENT_NOT_FOUNDGR_ARGUMENT_TYPE_ERRORGR_UNKNOWN_OPERANDGR_ATTRIBUTE_NOT_FOUNDGR_TABLE_NOT_FOUNDGR_NO_LICENSE

} GrError;

Page 107: MSC.mvision Database Programmatic Interface

10APPENDIX AError Messages

Description of general error conditions

ERROR MESSAGE ERROR OCCURS/RETURNED BY

GR_AMBIGUOUS_SOURCE_EXPRESSION Error occurs:

When an expression refers to attributes from the source table and a single non-hierarchical (property) table, the source of the referenced non-hierarchical table is assumed. However, when an expression refers to attributes from the source table and multiple non-hierarchical tables, the source can longer be deduced reliably.

Returned by: GrExpression

The user must explicitly refer to the proper source by prefixing the source attributes. For example, “ mechanical.author like ‘*twain*’ “ refers to the source attribute author of the non-hierarchical table mechanical.

GR_ARGUMENT_TYPE_ERROR Error occurs: When the evaluation of an expression fails due to the fact that the operands are not compatible with each other or the operator. For example, this error will occur if a string is added to a number, or a database expression is evaluated against an object that is not a database.

Returned by: GrEvaluate.

The error object contains the operator that failed. The error can also occur when an object which is not an expression is evaluated or freed. This error can be returned by the functions GrExpression or GrFreeExpression. The error object contains the type of the object that caused the error.

Page 108: MSC.mvision Database Programmatic Interface

8

GR_ATTRIBUTE_EXISTS Error occurs: When an attribute already exists in a database.

Returned by:

(GrCreate*Attribute, GrCreateSynonym)

functions.

GR_ATTRIBUTE_DIMENSION_ERROR Error occurs: When invalid dimensions are given as arguments when creating an attribute.

Returned by:

(GrCreateMatrixAttribute) or

(GrCreateStringAttribute) functions.

GR_ATTRIBUTE_NOT_IN_TABLE Error occurs: When an invalid value for an attribute is added to a table row that does not contain the attribute.

Returned by: (GrSetAttribute*, or GrStoreAttribute*) functions.

GR_ATTRIBUTE_PRECISION_ERROR Error occurs: When an invalid value is given for the precision argument.

Returned by:

(GrModifyAttributePrecision, GrCreateRealAttribute, GrCreateMatrixAttribute)

GR_ATTRIBUTE_STORE_ERROR Error occurs: When the type of the value (argument) is not compatible with the attribute type to which it is applied.

Returned by:

(GrSetAttribute*, GrStoreAttribute*)

Description of general error conditions

Page 109: MSC.mvision Database Programmatic Interface

10APPENDIX AError Messages

GR_AUTHORIZATION_ERROR Error occurs: When authorization is not given to open a MSC.Mvision databank.

Returned by: GrConnectToDatabase. The error object contains the name of the unauthorized database.

GR_CANNOT_COMMIT_READ_ONLY Error occurs: When a commit write to database is called for a read-only database.

Returned by:(GrCommitDatabase)

GR_CANNOT_DELETE_TABLE Error occurs: When a hierarchy of source table is deleted.

Returned by:

(GrDeleteTable)

GR_DATABASE_INDEXING_ABORTED Error occurs: The database storage format for release 1.2 is different from that of previous releases. When the DPI attempts to connect to a database it must use the release 1.2 database format. If a database is pre-1.2 the DPI will first convert the old database form to the new form. This conversion creates an temporary index which is stored in core and may be quite time consuming.

Alternately, the indexing (or conversion) process may be performed with the MvBatchBuilder or mv_index programs to permanently convert the database and eliminate the indexing step.

Returned by: If the conversion process fails, the conversion and database connect will be aborted and this message is reported.

Description of general error conditions

Page 110: MSC.mvision Database Programmatic Interface

0

GR_EXPRESSION_SYNTAX_ERROR Error occurs: When a syntax for an expression is invalid.

Returned by: GrExpression. The error object will contain the expression producing the error.

GR_FILE_CREATION_ERROR Error occurs: When a new database file cannot be created.

Returned by:(GrCreateDatabase)

GR_FILE_EXISTS_ERROR Error occurs: When a new database file already exists.

(Returned by:GrCreateDatabase)

GR_FILE_OPEN_ERROR Error occurs: When the DPI cannot open a file.

Returned by: GrConnectToDatabase or GrReadUnitsFile. The error object contains the name of the file.

GR_FILE_READ_ERROR Error occurs: Occurs when the DPI cannot read a file.

Returned by: GrConnectToDatabase and GrReadUnitsFile. The error object contains the name of the file.

GR_GET_VALUE_ACCESS_ERROR Error occurs: When the access to a specific object fails.

Returned by: GrGetValue or GrGetListElement. The error object will contain the invalid access code.

Description of general error conditions

Page 111: MSC.mvision Database Programmatic Interface

11APPENDIX AError Messages

GR_INDEX_FILE_NOT_VALID Error occurs: When an attached index file is out of sync with a database.

Returned by: (GrUseIndexFile)

GR_MAX_HIERARCHY_TABLES_EXCEEDED

Error occurs: When a database with more than 32 levels is defined.

Returned by:(GrCreateDatabase)

GR_NAMED_CONDITION_EXISTS Error occurs: When a named condition (duplicate) already exists.

Returned by: (GrRenameNamedCondition, GrCreateNamedCondition)

GR_NAME_IS_KEYWORD_ERROR Error occurs: When a specified “name” argument is a keyword.

Returned by:(GrRenameTable, GrRenameAttribute, GrRenameNamedCondition, GrCreateSynonym, GrCreateNamedCondition, GrCreatePropertyTable, GrCreate*Attribute)

GR_NAME_LENGTH_ERROR Error occurs: When the number of characters exceeds the allocated space for a string.

Returned by: (GrRenameTable, GrRenameAttribute, GrRenameNamedCondition, GrCreateSynonym, GrCreateNamedCondition, GrCreatePropertyTable, GrCreate*Attribute)

Description of general error conditions

Page 112: MSC.mvision Database Programmatic Interface

2

GR_NAME_SYNTAX_ERROR Error occurs: Syntax error in the naming of a table or attribute.

Returned by: (GrRenameTable, GrRenameAttribute, GrRenameNamedCondition, GrCreateSynonym, GrCreateNamedCondition, GrCreatePropertyTable, GrCreate*Attribute)

GR_NO_ERROR Error occurs: When the last GR function was successful. The error object contains the string No Error.

Returned by: All Functions

GR_NO_INDEX_ON_MODIFIED_DATABASE Error occurs: When a modified database is indexed.

Returned by: (GrCreateIndexFile)

GR_NO_LICENSE Error occurs: An MSC.Mvision license is not available. DPI will first attempt to get a

Materials Builder license, and if that fails will attempt to get a Materials Evaluator license.

Returned by: GrConnectToDatabase

GR_NOT_INITIALIZED Error occurs: When a GR function is called without the DPI being initialized. The error object contains the string “Not Initialized”.

Returned by:Gr*

Description of general error conditions

Page 113: MSC.mvision Database Programmatic Interface

11APPENDIX AError Messages

GR_OBJECT_TYPE_ERROR Error occurs: When a function argument is of the wrong data type. A common error is to pass a string containing an attribute name instead of a handle on the attribute. A type of GrData is expected but a string is actually received by a function.

Returned by:Gr*

GR_OUT_OF_MEMORY Error occurs: Memory Allocation Error. Occurs when the DPI is unable to allocate memory from the operating system. The error object contains the name of the module in which the memory allocation error occurred.

Returned by:Gr*

GR_TABLE_EXISTS Error occurs: When a table (duplicate) already exists.

Returned by:(GrRenameTable, GrCreateTable)

GR_UNITS_FILE_SYNTAX_ERROR Error occurs: When a line of a units file is read and the syntax is invalid.

Returned by:GrReadUnitsFile. The error object will contain the contents of the line producing the error.

GR_UNKNOWN_OPERAND Error occurs: When a token in an expression cannot be resolved for a particular evaluation.

Returned by:

GrEvaluate. The error object contains the token which could not be resolved.

Description of general error conditions

Page 114: MSC.mvision Database Programmatic Interface

4

A.2 Mathematical Error Conditionstypedef enum {

GR_ACOS_LT_MINUS_ONE, GR_ACOS_GT_ONE, GR_ASIN_LT_MINUS_ONE, GR_ASIN_GT_ONE, GR_DIVISION_BY_ZERO, GR_LOG_LE_ZERO, GR_NEGATIVE_SQRT

} GrMathError;

GR_UNLOCK_ERROR Error occurs: When the system is unable to release a lock on a database file.

Returned by:

(GrDisconnectFromDatabase, GrClose).

GR_WRITE_LOCK_ERROR Error occurs: When a write lock cannot be obtained on a database file.

Returned by:

(GrUpgradeLocks, GrConnectToDatabaseForUpdate)

GR_WRITE_NOT_INITIALIZED Error occurs: When a DPI write function is called without first calling GrInitializeWrite.

Returned by: GR (Write Functions)

Description of general error conditions

Page 115: MSC.mvision Database Programmatic Interface

I N D E XMSC.Mvision Database Programmatic Interface User’s Guide and Reference

Ccomparison operators, 54

Ddatabase

accessing, 13hierarchy, 22tables, 22

Database Programmatic Interface, 10DPI, 10

components, 6, 22expressions, 6, 22, 48functions, 6, 22functions, write, 88objects, 6, 22, 23

DPI components, 19

Eexample

select, 14write, 101

expressionsyntax, 53

expression functions, 55expression syntax, 50expressions, 6, 22

Ffunctions, 6, 22functions, write, 88

GGR_ERROR_HANDLING macro, 101GR_TYPE_ATTRIBUTE, 23GR_TYPE_CURVE, 25GR_TYPE_DATABASE, 24GR_TYPE_EXPRESSION, 25GR_TYPE_FIGURE, 25GR_TYPE_IMAGE, 26GR_TYPE_INTEGER, 26GR_TYPE_LIST, 26GR_TYPE_LOGICAL, 26GR_TYPE_MATH_ERROR, 26GR_TYPE_NAMED_CONDITIO N, 26GR_TYPE_POINT, 26GR_TYPE_RANGE_BAR, 26GR_TYPE_REAL, 27GR_TYPE_STRING, 27GR_TYPE_TABLE, 27GR_TYPE_TABLE_ROW, 27GRattributeBound1, 40GRattributeBound2, 40GRattributeDefaultUnits, 40GRattributeDescription, 40GRattributeDimensionality, 40GrAttributeFootnote, 29GRattributeLevel, 40GrAttributeMetadata, 29GRattributeName, 40GRattributePrecision, 40GRattributeStorageTable, 40GRattributeSynonyms, 41GRattributeTable, 41GRattributeType, 41GRattributeUnits, 41GRattributeWidth, 41GrBind, 30

Page 116: MSC.mvision Database Programmatic Interface

INDEX

GrChangeUnits, 30GrClose, 30GrCommitDatabase, 88GrCommitDatabaseTo, 88GrConnectToDatabase, 11, 30GrConnectToDatabaseForUpdate, 88GrCreateDatabase, 94GrCreateFigureAttribute, 94GrCreateFullTextAttribute, 94GrCreateHierarchyRow, 89GrCreateImageAttribute, 95GrCreateIntegerAttribute, 95GrCreateMatrixAttribute, 95GrCreateNamedCondition, 96GrCreatePropertyRow, 89GrCreatePropertyRowAsDuplicate, 89GrCreatePropertyTable, 96GrCreateRealAttribute, 96GrCreateSourceRow, 90GrCreateStringAttribute, 96GrCreateSynonym, 97GrCreateTableSegment, 97GrCreateTopLevelRow, 90GRcurveDisplayCode, 41GRcurvePoints, 41GRcurveRunOut, 41GrData, 11GRdatabaseAttributes, 41GRdatabaseCurrentUnitSys tem, 42GRdatabaseHeader, 42GRdatabaseHierarchyTables, 42GRdatabaseModified, 42GRdatabaseName, 42GRdatabaseNamedConditions, 42GRdatabasePDAnumber, 43GRdatabasePropertyTables, 43GRdatabaseReadOnly, 43GRdatabaseSourceTable, 43GRdatabaseTables, 43GRdatabaseUnitsFile, 43GRdatabaseUnitSystems, 43GrDeleteAttribute, 97GrDeleteNamedCondition, 97GrDeleteRow, 90GrDeleteTable, 98GrDisconnectFromDatabase, 31

GRerrorValue, 43GrEvaluate, 32GrExpression, 11, 32GrexpressionString, 43GrexpressionTables, 44GrFetchFromSelect, 32GRfigureCurves, 44GRfigureRangeBars, 44GRfigureRunOutPoints, 44GRfigureScatterPoints, 44GRfigureXscale, 44GRfigureYscale, 44GrFreeExpression, 33GrGetErrorMessage, 33GrGetErrorObject, 33GrGetErrorType, 33GrGetListElement, 33GrGetTableRow, 34GrGetValue, 11, 34, 39

access codes, 39GrInitialize, 34GrInitializeWrite, 88GrInteger, 34GRintegerValue, 44GRisNull, 45GRlistSize, 45GrListSize, 35GRlogicalValue, 47GrLookupAttribute, 35GrLookupNamedCondition, 35GrLookupTable, 35GrModifyAttributeDescription, 98GrModifyAttributePrecision, 98GrModifyAttributeUnits, 98GrModifyAttributeWidth, 98GrModifyDatabaseHeader, 99GrModifyFigureAttributeDescription, 99GrModifyFigureAttributeUnits, 99GrNamedConditionCondition, 45GrNamedConditionName, 45GRpointX, 45GRpointY, 45GrPutArgument, 36GRrangeBarPoint1, 45GRrangeBarPoint2, 45GrReadUnitsFile, 36

Page 117: MSC.mvision Database Programmatic Interface

INDEX

GrReal, 11, 36GRrealPrecision, 46GRrealValue, 45GrRegisterSecurityCallback, 37GrRenameAttribute, 99GrRenameTable, 100GrResetUnits, 37GRrowId, 46GRrowTable, 46GrSetAttributeFootnote, 90GrSetAttributeMetadata, 90GrSetAttributeNull, 91GrSetCaseSensitive, 38GrStoreAttributeFigurePoint, 91GrStoreAttributeFigureSize, 91GrStoreAttributeInteger, 91GrStoreAttributeMatrixElement, 92GrStoreAttributeMatrixSize, 92GrStoreAttributeReal, 92GrStoreAttributeString, 93GrStoreFootnote, 93GrString, 11, 37, 38GRstringValue, 46GRtableAttributes, 46GRtableDatabase, 46GRtableLevel, 46GRtableName, 46GRtableType, 46GRtype, 47GrType, 38GRtypeString, 47GrUpgradeLock, 93GrUseIndexFile, 38

Hhierarchy

attributes, 22

Iiterator, 61

Llists, 61logical operators, 55

Mmessage

self, 64MSC.Mvision Builder, 7MSC.Mvision Databanks

Analysis, 7ASM Reference, 7GE Plastics, 7Materials Selector, 7Plastics Design Library, 7Producer, 7Standards, 7

MSC.Mvision Database Programmatic Interface, 7

MSC.Mvision Evaluator, 7MSC.Mvision Pro, 7MSC.Mvision Products, 7MSC.Patran Materials, 7MSC/MVISION Builder, 7

Oobjects, 6, 22

messages, 64ATTRIBUTE, 66CURVE, 67DATABASE, 65FIGURE, 67NAMED_CONDITION, 66POINT, 66RANGE_BAR, 67SELECT_ROW, 67TABLE, 66TABLE_ROW, 64

Rrequired functions, 19

Page 118: MSC.mvision Database Programmatic Interface

INDEX

Sselect

example, 14smart functions, 61SQL, 10Structured Query Language, 10

UUser’s Guide and Reference

content, 6

Wwrite

example, 101