PSProfDeveloperManualEnglish

(1)

AUTODESK

®

PRODUCTSTREAM

®

_PROFESSIONAL

2010

Developer Manual

(2)

Certain materials included in this publication are reprinted with the permission of the copyright holder.

Trademarks

The following are registered trademarks or trademarks of Autodesk, Inc., in the USA and other countries: 3DEC (design/logo), 3December, 3December.com, 3ds Max, ActiveShapes, Actrix, ADI, Alias, Alias (swirl design/logo), AliasStudio, Alias|Wavefront (design/logo), ATC, AUGI, AutoCAD, AutoCAD Learning Assistance, AutoCAD LT, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk, Autodesk Envision, Autodesk Insight, Autodesk Intent, Autodesk Inventor, Autodesk Map, Autodesk MapGuide, Autodesk Streamline, AutoLISP, AutoSnap, AutoSketch, AutoTrack, Backdraft, Built with ObjectARX (logo), Burn, Buzzsaw, CAiCE, Can You Imagine, Character Studio, Cinestream, Civil 3D, Cleaner, Cleaner Central, ClearScale, Colour Warper, Combustion, Communication Specification, Constructware, Content Explorer, Create>what's>Next> (design/logo), Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignKids, DesignProf, DesignServer, DesignStudio, Design|Studio (design/logo), Design Your World, Design Your World (design/ logo), DWF, DWG, DWG (logo), DWG TrueConvert, DWG TrueView, DXF, EditDV, Education by Design, Extending the Design Team, FBX, Filmbox, FMDesktop, Freewheel, GDX Driver, Gmax, Heads-up Design, Heidi, HOOPS, HumanIK, i-drop, iMOUT, Incinerator, IntroDV, Inventor, Inventor LT, Kaydara, Kaydara (design/logo), LocationLogic, Lustre, Maya, Mechanical Desktop, MotionBuilder, ObjectARX, ObjectDBX, Open Reality, PolarSnap, PortfolioWall, Powered with Autodesk Technology, Productstream, ProjectPoint, Reactor, RealDWG, Real-time Roto, Render Queue, Revit, Showcase, SketchBook, StudioTools, Topobase, Toxik, Visual, Visual Bridge, Visual Construction, Visual Drainage, Visual Hydro, Visual Landscape, Visual Roads, Visual Survey, Visual Syllabus, Visual Toolbox, Visual Tugboat, Visual LISP, Voice Reality, Volo, and Wiretap.

The following are registered trademarks or trademarks of Autodesk Canada Co. in the USA and/or Canada and other countries: Backburner, Discreet, Fire, Flame, Flint, Frost, Inferno, Multi-Master Editing, River, Smoke, Sparks, Stone, Wire.

All other brand names, product names or trademarks belong to their respective holders.

Disclaimer

THIS PUBLICATION AND THE INFORMATION CONTAINED HEREIN IS MADE AVAILABLE BY AUTODESK, INC. "AS IS." AUTODESK, INC. DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS.

Published by: Autodesk, Inc. 111 Mclnnis Parkway San Rafael, CA 94903, USA

(3)

Table Of Contents

i

Foreword. . . 1

Introduction ... 1

This document ... 1

Typographic conventions ... 2

User interfaces and control functions ... 2

Programming and source code ... 2

The configuration of Productstream Professional . . . 3

Configuring the permissions system... 3

Foreword ... 3

Syntax for defining permissions ... 4

Permissions at element type level ... 4

Attributes of the element types ... 5

The sub-component Rights ... 6

Permissions at system level ... 7

Functions for working with permissions ... 7

Configuration of the state management ... 7

Introduction ... 7

State objects ... 8

Configuration ... 10

Sequence in which defined actions are performed during state changes ... 10

Reading out the state definition from the configuration ... 12

Programming conventions in the standard Productstream Professional Pro installation ... 12

Configuring additional actions ... 12

Establishing the start state ... 13

Database customization . . . 14

Foreword... 14

Database model ... 14

Manipulate database objects ... 14

Adding a new Column ... 15

Adding a New Table... 15

Productstream Professional as DDE–Server . . . 16

Connection ... 16

DDE-Execute ... 16

DDE-Request ... 16

Settings for AIMKEY ... 16

Example ... 17

Productstream Professional DLL-Functions . . . 18

(4)

Table Of Contents

ii

Productstream Professional public functions from a DLLL ... 18

Procedure for registering functions in Productstream Professional ... 18

Procedure for defining a public DLL function ... 19

Prototypes ... 20

CallBack functions from pAIMFuncCTX ... 20

Functions for Productstream Professional conditions and formula ... 21

Procedure for registering these functions in Productstream Professional ... 21

Procedure for defining a DLL function for conditions and formulae ... 22

Prototypes ... 23

Parameters ... 23

Callback functions from EXPR_FUNC_CTX ... 23

Implementing functions in Visual Basic ActiveX DLLs... 25

Miscellaneous ... 25

Procedure for implementing functions in a VB ActiveX DLL ... 25

Functions of the ICAICallback interface object ... 27

Restrictions ... 27

Productstream Professional .NET Programming . . . 28

Preamble... 28

Requirements ... 28

Architecture of the .NET programming interface... 28

Infrastructure ... 28

Link a .NET DLL in the configuration ... 28

Method calls from .NET to Productstream Professional ... 28

Method calls from Productstream Professional to .NET ... 28

.NET DLL Security ... 29

Loading from a network share ... 29

Example ... 29 Debugging ... 31 Class Definitions... 31 CBaseARGWrapper class ... 31 CCustomerNetModuleBase class ... 31 CMPException class ... 32 PSPClassAttribute attribute ... 32 PSPMethodAttribute attribute ... 32 PSPMethodCondAttribute attribute ... 32 PSPMethodDefArgAttribute attribute ... 33 IEVAL_CTXWrapper interface ... 33

Connecting to remote database sources . . . 35

Foreword... 35

Definition of the login database ... 35

Definition of a remote data source ... 35

(5)

Table Of Contents

iii

Configuration ... 35

Definition of the remote data source in the configuration ... 35

User account of remote data source ... 36

Refreshing the user interface ... 36

Scenarios Oracle database ... 37

Accessing a remote schema on the login instance ... 37

Accessing a schema on a different Oracle instance ... 38

Scenarios MS SQL Server... 39

Accessing a remote database on the login server ... 39

Accessing a remote database on a remote SQL Server ... 39

API Programming Guide of the AutoCAD/MDT Integration in Productstream

Professional . . . 40

Introduction ... 40

CAI interface... 40

Calling the CAI functions ... 40

AIMDChangeAimkey ... 41 AIMDNew ... 41 AIMDOpen ... 42 AIMDOpenReadOnly ... 42 AIMDPublishDWF ... 42 AIMDQuit ... 43 AIMDRestore ... 43 AIMDUpdateTitleBlocks ... 43 COMMAND ... 44

Productstream Professional Add-In interface... 44

LISP and AutoCAD commands ... 44

AIMDDDERequest (LISP command) ... 44

AIMDDDEExec (LISP command) ... 45

AIMDCMPCall (AutoCAD command) ... 45

API Programming guide of the Inventor Integration in Productstream

Professional . . . 46

(6)

Table Of Contents

iv

CAI interface... 46

Calling the CAI functions ... 46

AIMDChangeReference ... 46 AIMDDeferUpdate ... 47 AIMDGetProp ... 47 AIMDGetProperties ... 47 AIMDInsert ... 48 AIMDIsInstalled ... 48 AIMDNew ... 48 AIMDOpen ... 48 AIMDPackAndGo ... 49 AIMDPrint ... 49 AIMDPublishDWF ... 49 AIMDQuit ... 50 AIMDSaveAs ... 50 AIMDSaveAsAttachment ... 50 AIMDSyncStruct ... 51 AIMDUpdateProps ... 51 AIMDUpdateProps2 ... 51

Productstream Professional Add-In interface... 52

AIMDAutomation class ... 52 COMPASS Property ... 52 ExportBOM function ... 52 SendBOM function ... 53 SendProperties function ... 53 SyncLocks function ... 53 SyncStructure function ... 53 TransferComponents function ... 54 UpdateProperties function ... 54 AIMDCompass class ... 54 Call function ... 54 CallEx function ... 55 GetAIMKEY function ... 55 Prepare function ... 56 PrepareEx function ... 56

DBP/COP programming . . . 57

DBP/COP compiler... 57 Parameters ... 57 Example ... 57

Structure of the DBP and COP files ... 58

DBP files ... 58

(7)

Table Of Contents

v

Preprozessor directives ... 59

Include ... 59

Define ... 60

Undef ... 60

Ifdef, Else, Endif ... 61

Rem, Comment ... 61 Echo ... 61 Break ... 62 Program elements... 62 Public ... 62 Procedure ... 63 Command statement ... 64 Compound statement ... 64

Selection Statement (if, else) ... 64

Loop statement (while, until) ... 65

Return statement ... 65

Comments ... 66

Condition (DBP file) ... 66

Condition (COP file) ... 67

Operators... 68

Formats. . . 69

Expressions and condition operators . . . 71

Operators... 71

General ... 71

#( <FieldName or Function> ) ... 71

@( <FieldName or Function> ) ... 71

$( <Variable> ) ... 72

#( ( <Expression> ) [<SubstitutionDepth>] [:<Format>] ) ... 72

#(= <Expression with FieldNames> ) ... 73

#(== <Conditions> ) ... 73 #(Tx...) ... 73 #( Symbol:<SymbolName> ) ... 74 #( RecID [:<Format>] ) ... 74 @(\n) ... 74 $(_DS) ... 74 Functions... 74

#( call <Function> [<Parameter>] [:<Format>] ) ... 74

#( KeyGen <Action> ) ... 75

#(GetMaxKey…) ... 76

(8)

Table Of Contents

vi

Strings... 78

comp ( "<String1>" , "<String2>" ) ... 78

ncomp ( "<String1>" , "<String2>" , "<Length>" ) ... 78

wcomp ( "<String1>" , "<String2>" ) ... 78

empty ( "<String>" ) ... 78

isdefined ( "<String>" ) ... 78

isknown ( "<String>" ) ... 78

eq ( "<Number1>" , "<Number2>" ) ... 78

aeq ( "<Char1>" , "<Char2>" ) ... 78

le ( "<Number1>" , "<Number2>" ) ... 78

ale ( "<Char1>" , "<Char2>" ) ... 78

lt ( "<Number1>" , "<Number2>" ) ... 78

alt ( "<Char1>" , "<Char2>" ) ... 78

ge ( "<Number1>" , "<Number2>" ) ... 79

age ( "<Char1>" , "<Char2>" ) ... 79

gt ( "<Value1>","<Value2>" ) ... 79 agt ( "<Value1>","<Value2>" ) ... 79 ne ( "<Value1>","<Value2>" ) ... 79 ane ( "<Value1>","<Value2>" ) ... 79 #(= strlen ( "<String>" ) ) ... 79 #(= strchr ( "<String>" , "<SearchCharacter>" ) ) ... 79

#(= substr ( "<String>" , <Start> , <Length> ) ) ... 79

#(= strprep ( "<String>" ) ) ... 79 #(= envprep ( "<String>" ) ) ... 79 #(= INT ( "<String>" ) ) ... 80 #(= INT ( <Number> ) ) ... 80 #(= DOUBLE ( "<String>" ) ) ... 80 #( subst: <Variable> ) ... 80 Fields ... 80

#(= field ( "<FieldName>" ) ), #( field ( <FieldNumber> ) ) ... 80

#(= fieldexist ( "<FieldName>" ) ), #(= fieldexist ( <FieldNumber> ) ) ... 80

#(= fieldlen ( "<FieldName>" ) ), #(= fieldlen ( <FieldNumber> ) ) ... 80

#(= fielddec ( "<FieldName>" ) ), #(= fielddec ( <FieldNumber> ) ) ... 80

#(= fieldtype ( "<FieldName>" ) ), #(= fieldtype ( <FieldNumber> ) ) ... 81

(9)

Table Of Contents

vi

Configuration queries... 81

#( HCLS <Registry-Key> <ValueName> [:<Formatting>] ) ... 81

#( HLOM <Registry-Key> <ValueName> [:<Formatting>] ) ... 81

#( HKCU <Registry-Key> <ValueName> [:<Formatting>] ) ... 81

#( Appl: <Attribute> ), #( Appl <Attribute> ) ... 81

#( DBView ) ... 81 #( DBNAME ) ... 82 #( DBQNAME ) ... 82 #( DBQPATH ) ... 82 #( DBQFINAME ) ... 82 #( DBQEXT ) ... 82 #( DBSIZE ) ... 82

#( DBINI: <Attribute> ), #( DBINI <Attribute> ) ... 82

#( DBI: <Attribute> ), #( DBI <Attribute> ) ... 82

#( CFGAttribute: <Attribute> [:<Formatting>] ), #( CFGAttribute <Attribute> … ) ... 82

#(CFGAttributeMap: <AttributenamePrefix>), #(CFGAttributeMap <AttributenamePrefix>) .... 83

#( DTY: <Attribute> ), #( DTY <Attribute> ) ... 83

#( DTYID: <DocumentTypeObject> : <Attribute> ), #( DTYID <DocumentTypeObject> <Attribute> ) ... 83

#( ETYPE [<Attribute>] ) ... 83

#( GUIViewExist <GUIView-Object> ) ... 84

#( GUIViewParent <Expression> ) ... 84

#( GUIViewRoot <Expression> ) ... 84

#( INI: <Section> : <Attribute> ), #( INI <Section> <Attribute> ) ... 84

#( I: <Section> : <Attribute> ), #( I <Section> <Attribute> ) ... 84

#( DBINI: <Attribute> ), #( DBINI <Attribute> ) ... 84

#( DBI: <Attribute> ), #( DBI <Attribute> ) ... 84

#( MSKNAME ) ... 84

Object relations... 85

Chkexist( "[db=<FolderObject>] <SQLWhereClause>") ... 85

chkref ( "[db=FolderObject>] <SQLWhereClause>", "<ConditionTrue>", "<ConditionFalse>" ) 85 #( where [db=<FolderObject>] <SQLWhereClause> <Expression> ) ... 86

GetPersonAttribute ( "<Expression>" ) ... 86

GetOrganisationAttribute ( "<Expression>" ) ... 86

GetContactAddressAttribute ( "<Expression>" ) ... 86

GetAllPersonAttributes ( "<Expression>" , "<Separator>") ... 86

GetAllOrganisationAttributes ( "<Expression>" , "<Separator>") ... 86

#( GetHisAt <Pos> <Expression> ) ... 87

#( GetHisTB <Pos> <MaxNum> <Expression> ) ... 87

#( LinkType <EntityType-Object> [:<Formatting>] ) ... 88

#( NextPos <ParentAIMKEY> <Intervals> [<StartPos>] [<RelationshipID>] ) ... 88

#( NewRevision <ParentAIMKEY> <Intervals> <Start> ) ... 88

(10)

Table Of Contents

vi

Status ... 89

#( Status [: [icon|desc|id|onchange|onenter] ] ) ... 89

#( statusnext ) ... 89

#( statusdesc: <StatusKey> ) ... 89

#( StatusUID <UID> [<Parameter>] [:<Format>] ) ... 89

#( StatusNextUID [{backward|forward}] [:<Formatting>] ) ... 90

#( ReplState [: [icon|desc|id] ] ) ... 91

Selections ... 91

#( numsele ) ... 91

#( numdisp ) ... 91

#( nummark ) ... 91

#( selectioninfo: <Selection>: <Expression> ) ... 91

#( selection: <Selection> ) ... 91

Applications ... 92

taskrunning ( "[EXE:]<Exe-Name>" ) ... 92

taskrunning ( "DDE:<DDE-Server-Name>" ) ... 92

taskrunning ( "TIT:<WindowTitle MainWindow>" ) ... 92

LastCreatedProcessRunning () ... 92

LastCreatedProcessWait ( <TimeOut> ) ... 93

GetLicence ( "<ProductLicenseKey>" , "<ReservationPeriod>" ) ... 93

Files... 93

exist ( "<File>" ) ... 93

xexist ( "<FileModel>" ) ... 93

compFileSize ( "<File1>" , "<File2>" ) ... 93

compFileDate ( "<File1>" , "<File2>" ) ... 94

compFileBin ( "<File1>" , "<File2>" ) ... 94

#(= FileSize ( "<File>" ) ) ... 94 #(= FileDate ( "<File>" ) ) ... 94 FileReadAccess ( "<File>" ) ... 94 FileWriteAccess ( "<File>" ) ... 94 doc0exist () ... 94 docexist ( <n> ) ... 94 #( FileType : <FileName> ) ... 95

#( FindFile "<FileName>" "<SearchPath>" [:<Formatting>] ) ... 95

#( FileNameGen ) ... 95 #( DOCNAME<n> ) ... 95 #( PATH<n> ) ... 96 #( EXT<n> ) ... 96 #( EXTFLD<n> ) ... 96 #( LinkFld ) ... 96 #( LinkName ) ... 96 #( PATHFLD<n> ) ... 96 #( AIMKEYfromPATH <FileName> ) ... 96 #( DescfromPATH <FileName> ) ... 97

(11)

Table Of Contents

ix

Time ... 97 #(= UTCFile ( "<File>" ) ) ... 97 #(= UTCSystem ( ) ) ... 97 #(= localUTC ( <TimeValue> ) ) ... 97 #(= gmUTC ( <TimeValue> ) ) ... 97 #(= strUTC ( <TimeValue> ) ) ... 97 #(= INT ( <TimeValue> ) ) ... 97 #(= DOUBLE ( <TimeValue> ) ) ... 98 #(= UTC ( <DecimalNumber> ) ) ... 98 #(= TIME ( "<YYYYMMDDhhmmss>" ) ) ... 98 #( SYSDATE ) ... 98 #( SYSTIME ) ... 98 Rights... 99 crstatic ( "<Rights>" ) ... 99 crdynamic ( "<Rights>" ) ... 99 cr ( "<Rights>" ) ... 99 #( dynamicRights ) ... 99 #( staticRights ) ... 100 Exclusive reservation ... 100 lock () ... 100 islocked () ... 100 mylock () ... 100 #( LockUser ) ... 100

SQL queries and functions ... 101

#( XDWSFKT: <SQL-Procedure> [<Parameter>] ) ... 101

#(GetMaxKey <FieldName>=“<Value>“ <Offset> <Length>) ... 102

#( DBSpec_isNULL <FieldName> ) ... 102

#( DBSpec_Date <Date YYYYMMDD> ) ... 102

#( DBSpec_ToDay ) ... 103

(12)

Table Of Contents

x

Internal Functions . . . 104

___AskQ ... 104 ___Break_Enum ... 106 ___ChangeField ... 108 ___ChangePassword ... 109 ___ChangeStatus ... 110 ___CheckExtensionFlags ... 112 ___CloseArchiv ... 113 ___CmpUtility ... 114 ___CompassInfo ... 116 ___CopyFilesToLocal ... 117 ___DbUtils ... 120 ___DeleteRecord ... 122 ___DWFUPDATESYNC ... 123 ___EditFilter ... 124 ___EnumFields ... 125 ___EnumToken ... 126 ___Environment ... 127 ___ErrLog ... 128 ___ExecuteSQL ... 129 ___ExportCollect ... 130 ___ExportConfirm ... 132 ___ExportDataObjectDestroy ... 134 ___ExportDlg ... 136 ___ExportExecute ... 139 ___FolderBar ... 141 ___FolderStructure ... 142 ___ForceUnLock ... 143

___ForRela, ___ForRelaH, ___ForAllRela, ___ForAllRelaH ... 144

___ForTable ... 146 ___GetLicence ... 147 ___ImportCheck ... 148 ___ImportDlg ... 150 ___ImportElement ... 152 ___ImportExecute ... 153 ___InstallOption ... 155 ___JobCreate ... 157 ___LinkElement ... 159 ___Lock ... 161 ___LogWrite ... 162 ___Map, Map ... 163 ___New_Object ... 165 ___NotInstalled ... 166 ___OnePropUpdate ... 166 ___OpenArchiv ... 167 ___OpenGUIViewWindow ... 168 ___OpenHelp ... 169

(13)

Table Of Contents

xi

___Prepare ... 170 PrintReport ... 171 ___Report ... 173 ___ProfileManager ... 173 ___ReadRecInfo ... 174 ___RecordBuffer, RecordBuffer ... 177 ___ResetFolder ... 181 ___Return_0 ... 181 ___Return_1 ... 182 ___ReturnString, # ( ___ReturnString ) ... 183 ___SelectDirectory ... 184 ___Selection ... 185 ___SetFilePropsDirty ... 187 ___SetNewerVersionExists ... 188 ___SetPrinter ... 189 ___SetRights ... 190 ___Shell ... 192 ___ShowWebViewWindow ... 201 ___StartConfigurator ... 201 ___StatusBar ... 202 ___UnLock ... 203 ___WriteAimXML ... 204 ___WriteConfiguration ... 206 ___WriteRecInfo ... 207 ___WriteRegistry ... 208 ___WriteSDF ... 209 ___WriteSTD ... 210 ___WriteXMLSchema ... 211 ___XdwCmd ... 213 ___xEditDocument ... 214

Productstream Professional event procedures . . . 215

Advanced search ... 215

ExtendedSearchSave ... 215

ExtendedSearchSaveAs ... 215

Drag & drop ... 215

DragSupported ... 215 GetDropEffectIntern ... 215 GetXDropEffectIntern ... 216 OnDropIntern ... 216 OnXDropIntern ... 216 GetDropEffectExtern ... 217 GetXDropEffectExtern ... 217 OnDropExtern ... 218 OnXDropExtern ... 218

(14)

Table Of Contents

xi

Menu functions ... 218

___CheckCondition ... 218

Create new element and Edit dialog windows ... 218

m_closeOnly ... 218

ObligatoryFieldViolation ... 219

Editing fields in a data sheet / list ... 219

PreUpdateField_<FieldName> ... 219

OnUpdateField_<Feldname> ... 219

Compass bar ... 219

Environment variable ACTIVE_SECTION ... 219

Preview window ... 220

m_ShowDocFile ... 220

Internal functions executable in Productstream Professional Webserver. . 221

Not recommended functions . . . 223

(15)

Introduction

1

Chapter 1 Foreword

Introduction

Welcome to the Developer Manual of Autodesk® Productstream® Professional Pro 2010, which is aimed at Productstream Professional developers and administrators.

This document

The Productstream Professional Pro developer manual is split up into different chapters, dealing with the fol-lowing points: • "Functions • "Field functions • "Field queries • "Instructions • "Boolean operations • "Formats

• "Variables and files • "DDE actions • "ActiveX and DLL

• "Introduction to DBP programming

The developer manual gives you an idea of just how flexible Productstream Professional Pro is. It contains a complete reference work explaining all the functions, and documents the fundamental procedures and con-cepts used in DBP programming.

(16)

Typographic conventions

2 Typographic conventions

The following conventions have been used for reasons of clarity to help you to interpret the information being given.

User interfaces and control functions

Programming and source code

Format Meaning

SMALLUPPER-CASELETTERS Refers to the keys of the keyboard, e.g. ENTER, TAB. The word "key" is not used when describing key shortcuts.

Example: Press ENTER. Press ALT +TAB.

Bold Designates terms used in the program user interface. Applies for menu names, commands, buttons, etc.

Example: Select the File menu and then the command Open.

Caution!

Warning text

Warning texts alert you to errors which could have fatal consequences.

Note

i !

Note text

Notes contain more information on that particular manual text.

☞ Instruction 1 Confirm … 2 Type text …

Instructions describe a specific task you need to carry out as shown in the step-by-step guide.

Menu > Command

Shortcut menu > Command

Shorthand form of calling a command or a sequence of commands from a specific menu. The shortcut menu is opened by pressing the right mouse button.

Variable, Field, Input Describes variables, field names and input data, such as those entered in files, for example.

Format Bedeutung

Required Information which must be entered by the user.

Bold Elements which the user must enter exactly as given.

Parentheses (...) Parameters which can be repeated a number of times in a command line. Square brackets [...] Optional elements

Curly brackets {...} Group of selection options, only one of which may be selected by the user. Selection options are separated by a vertical bar ( | ). Example: { even | odd } Fixed character spacing Code or program output.

(17)

Configuring the permissions system

3

Chapter 2 The configuration of Productstream Professional

Configuring the permissions system

Foreword

This section describes how to configure the permissions system. A general introduction to the user and per-missions management functions is not included here. Details can be found in the user manual in the chapter "Configuring the permissions system".

The permissions management for elements is realised by splitting up the data in two separate locations. One part of the required information is stored in the entity type, the other part is stored in the element. Only the owner and the owner group are stored in the element. The assignment of the standard permissions and user groups, as well as the corresponding user and user group permissions, are defined and stored in the element type. To ascertain which permissions are held by a particular user, the application checks whether the user is an owner, a member of the owner group or a guest, and which permissions have been granted through mem-bership of the groups to which he has been assigned. If the user has been granted permission from a group to perform a certain action, this situation does not change even if the user also belongs to another group for which that permission does not apply.

Example:

User A belongs to the group of project leaders, design engineers and draftsmen. He has therefore been granted the following permissions:

Group Permissions

Create Read Modify Delete

Project leaders no yes no no

Design engineers yes yes no no

Draftsmen no yes yes no

(18)

4 Syntax for defining permissions

Permissions are always given in the form _C_R_W_D or _C_R_W_D_O_G_A_L. The letters stand for a par-ticular permission type.

The underscores ( _ ) are replaced by either a plus (+) or a minus (-) sign. A plus sign means that the permission is granted for the following letters. A minus sign indicates that the permission for the following letter has been revoked for the user or group. When defining permissions, the sequence in which the letters are given is im-material. The case is also irrelevant. If a letter is unintentionally duplicated in a definition, the value of the same letter to the right is applied.

Permissions at element type level

The data of the static permissions for element types is stored in the database in the table CONFIGURATION, and can be edited using the configuration editor.

How permissions can be granted and revoked based on the element types for user groups is explained in the next section. Permissions are only required for element types which can be assigned to an element. However, it is also possible to define permissions for abstract element types, as these settings can store and pass on infor-mation for element types further down in the element structure due to the inheritance schema. An exception is the attribute DefaultGroup, which must be defined directly in the component of the corresponding element type for each element type that can be assigned to an element.

Permissions at element type level

The following permissions can be granted and revoked at element type level: Letter Permission C Create R Read W Modify D Delete O Change owner

G Change owner group

A Change permissions

L Manage reservation

Permission At element type level Letter

Create Permission to create a new element of that element type C

Read Permission to read, copy and send etc. elements of that element type R Modify Permission to edit and modify elements of that element type W

Delete Permission to delete elements of that element type D

Change owner Permission to change the owner of elements of that element type O Change owner group Permission to change the owner group of elements of that element type G Modify permission Permission to change the permissions stored for elements of that element

type

A

(19)

5 Attributes of the element types

The following illustrations demonstrate that the inherent data of an element type is managed in two locations. The attributes DefaultGroup, DefaultOwner, OwnerRights, GroupRights and DefaultRights can be used di-rectly in the element type. These fields are required to determine the users, user groups and their permissions for a newly created element.

Either Productstream Professional variables, or users or user groups, can be entered for the attributes Defaul-tOwner and DefaultGroup. In the case of the attributes DefaultRights, GroupRights and OwnerRights, ho-wever, values defining the permissions need to be entered. These attributes are described in more detail in the table below.

Graphic 1: Attributes of the element types

Attribute Value Explanation Example

DefaultGroup Group name Enters the owner group which is to be entered when creating a new record of this element type. In this example, the active user group to which the user belongs is read out and entered as the owner group.

$ACTIVE_GROUP

DefaultOwner User name Enters the owner who is to be entered when crea-ting a new record of this element type.

$USERID

OwnerRights _C_R_W_D The permissions which are to be granted to an owner of an element of that element type are writ-ten in this field.

+C+R+W+D

GroupRights _C_R_W_D The permissions which are to be granted to the owner group of that element type are written in this field.

+C+R-W-D

DefaultRights _C_R_W_D The permissions which are to be granted to a user who is neither an owner nor a member of an owner group are written in this field. These permissions also apply for the guest user group.

(20)

6 The sub-component Rights

In addition to the attributes described above, which are defined directly in the element type, it is also possible to grant static permissions to individual user groups. This data is stored in the sub-component Rights. The name of the user group is entered as the attribute, and the relevant permissions are entered as the value. As both the attribute as well as the value are case-insensitive, no differentiation must be made between upper and lower-case letters in either case.

Permissions at element level

Permissions derived from the entity type can be restricted further at the level of the element of a specific ele-ment type. Productstream Professional manages the permissions for the three user categories User, Member of the owner group and Non-owner and Non-member of the owner group for each element. The latter are desi-gnated as default permissions, which also apply for the Guest user group. The information is stored directly in the table ELEMENT. In this table, the name of the owner is stored in the column OWNER, and the name of the owner group is stored in the column OWNER_GROUP. The corresponding data can be read out of the configurator, which contains the default permissions for users, owners and guests. The 32-bit numeric data type is used for the column RIGHTS. The element permissions are stored in this field. This allows permissions which are granted by default for a particular element to be individually customized as required. To do this, the 32 bits are split up into three 10-bit blocks. The last two bits are immaterial. The owner permissions are set in the first 10 bits, the next 10 bits hold the owner group permissions, and the next 10 bits hold the guest per-missions. When creating a new record, the columns are usually entered automatically in accordance with the rules which are defined in the entity type by the configurator.

Permissions for the three user categories User, Member of the owner group and Non-owner and Non-member of the owner group are managed at the level of the individual elements. At this time, permissions cannot be managed at file level. For this reason, the following rule has been laid down: If the permission exists at element level, it includes the corresponding permission at file level.

Attribute Value

Group name _C_R_W_D_O_G_A

Graphic 2: The sub-component Rights

Permission At element level At file level

Create Is actually immaterial here Permission to create a new file (new document). Read Permission to read, copy and

send etc. this element

Permission to read, copy, etc. this element.

Write protection may need to be enabled if no user catego-ries are to be allowed to modify or delete files.

Modify Permission to edit and modify this element

Permission to edit and modify this file. Remove write protection if necessary. Delete Permission to delete this

ele-ment

Permission to delete this file. Remove write protection if necessary. Reserve The element has been

reser-ved

The user who initiated the reservation becomes the owner of the element. All other users are granted read permission (if at all).

(21)

Configuration of the state management

7

Checking permissions at element level

If the user has been granted the required permission at element type level, the permission is checked at the level of the individual element. This means that although permissions which are granted at element level can be re-stricted, they cannot be extended, nor can additional permissions be granted.

If the user is the owner of the element, he has the right to permissions which have been defined for owners. The definitions of the permissions are stored in the element type, however, but in the element. If the user is a member of the owner group on the other hand, he has the right to the permissions stored for that group. If the user is neither an owner nor a member of the owner group, he only has the right to the default permissions.

Permissions at system level

In addition to the element-specific permissions, permissions granted at system level also have to be taken into consideration. In particular, this includes the right to configure the system, which covers full permission for the following:

• user management, • state management,

• for all the configuration options which can be applied using the configuration editor to apply changes to the user interfaces as default settings with the Designer tools.

Previously, the permissions for the aforementioned actions were reserved for the administrator group.

Functions for working with permissions

To control permissions at the level of the individual element, functions are required which allow permissions to be set, modified or queried, and to be assigned to owners or the owner group. It must also be possible to check which permissions already exist. The necessary functions ___SetRights(), crstatic, #(staticRights) and #(dynamicRights) are described in the chapters "Internal functions" and "Expressions and condition opera-tors".

Configuration of the state management

The processes in the Productstream Professional state management are for the most part defined in the confi-guration. Without the configuration there is (almost) no state management. This chapter describes the funda-mental principles and influence variables of the state management, as well as the fixed processes in

Productstream Professional which can be influenced by programming (Productstream Professional Pro only). The same rules apply for Productstream Professional Easy, although here the configuration information is per-manent. The component Status in the hierarchy of the Productstream Professional configuration is ignored by Productstream Professional Easy.

Further information can be found in the chapters “State management configuration” and “Internal functions” under “___ChangeStatus”.

An administrator can protocol the current state during Productstream Professional runtime by entering the following shell instruction: ___cmputility( writestatus );

Introduction

The state management in Productstream Professional Pro consists of two different types of objects: • state condition

• state change

This corresponds moreorless to the state definitions in COMPASS 4 and Productstream Professional Easy (he-re it is fixed in the “Exe”).

In Productstream Professional Pro, the state is globally stored in the configuration. This means that the state keys and state changes are the same for all Folder, Element, Document, and Application objects.

The state changes can sometimes be defined according to the element. The start state is ascertained in the nor-mal search sequence in the object model using the attribute “StartStatus”. All the functions which are to be performed once the state has changed are also sought in the hierarchies of the object model.

(22)

8 State objects

State condition

The state condition is identified by a key, which is stored for each element object in the field STATUSKEY. The state is therefore an integral component of each element object in Productstream Professional which is derived from the basic element “AIM” (this applies for element objects based on the “ELEMENT” database table).

The state condition is described by the following properties:

Note

i !

Note must be taken of the following special characteristic of the permission properties: These properties are changed irrespective of the permissions which have been granted to the user initiating the state change. This means, for ex-ample, that a user who has not been granted permission to change the permissions, owners or the Owner_Group for an element is able to trigger a state change resulting in the permissions information being changed by the state defi-nition. These permission changes take place in the Productstream Professional kernel, which does not check the user permissions.

Property Description

Key Currently a 5-character field. Attribute name in the configuration: Status.

Description This is normally defined by #TxSTATnnn (language-neutral) and stored by language in the asso-ciated file stat.tex (file name: convention for Autodesk). The key is used if no specific description has been given. Attribute name in the configuration: “Name”.

Icon file The icon file defines a graphic symbol for the state. A default icon is used unless specified otherwise. Attribute name in the configuration: “Icon”.

Start state A state also carries the key as the start state, which is entered as the state when creating a new ele-ment object. This state also applies for any eleele-ment where the state key has not been registered in the configuration of the active Productstream Professional environment. In the configuration, this property is expressed by “Default=TRUE”. If no attribute has been specified with the name “Default”, it is assumed that FALSE is to be applied. If none of the state conditions contains the attribute “Default=TRUE”, the first state which is found is used. A Productstream Professional condition expression can also be used instead of “TRUE”. Attribute name in the configuration: “Default”.

How the start state is ascertained when creating a new element is described below. The following properties for each state condition have been added in COMPASS pro 2.0:

onEnter command Action to be performed directly after the state condition has been attained. A public function can be given. This action is performed when a state is successfully changed, irrespective of the original state from which the change was initiated, when the state information has been written in the data-base. If an action has been defined for the start state, it is performed directly after the new element object has been inserted in the database. Attribute name in the configuration: “onEnter”.

onChange command Action to be performed on exiting the state condition: .

A public function can be given. This is always performed before a state change which had this state as its starting point. At this time, the element object still has its original state, which may not be changed during this action.

Attribute name in the configuration: “onChange” Permissions granted to the element

while the state applies.

The permissions owned by the element while it belongs to the state can be defined here. The same permissions as those defined in the internal public function ___SetRights can be granted. If this attribute is not defined, the permissions are not changed. Permissions are likewise not set for the start state either.

Attribute name in the configuration: "setRights". Permissions granted to the element

when changing the state.

Permissions granted to the element before the public functions for the state change are performed can be defined here. The same permissions as those defined in the internal public function ___SetRights can be granted. This therefore defines which permissions are granted to the element for each state change with this original state.

(23)

9

State change

The state change defines a possible transition from one state condition to another. A state condition is described by the following properties:

Properties Description

Original state Key of the state the element object must have before it can change to the target state. In the configuration, this state is defined by the parent component.

Target state Name of the state which the element object is to have after the state change.

Attribute name in the configuration: Status. If this attribute has not been defined, the name of the component is used instead.

Description This is normally defined by #TxSTATnnn (language-neutral) and stored by language in the associa-ted file stat.tex (file name: convention for Autodesk).

Attribute name in the configuration: “Name”.

Conditions One or more (max. 10) condition expressions are used to define whether the state change can or may be initiated. All the specified conditions must apply.

Attribute name in the configuration: “Condition0” to “Condition9”.

Action for the change A public function can be given. This function is performed using the arguments <original state key> and <target state key> with the element object as the context. In contrast to COMPASS 4, only one command per change is now performed.

Attribute name in the configuration: “Command”.

“backward” key If this attribute has the value “true” or “1”, the target state is shown to the left of the current state in a graphical view. The flag does not have any further meaning or effect.

“KeepLock” key If this attribute has the value “true” or “1”, an exclusive reservation is not affected by the state change. If this attribute has either not been defined or it has a different value, the exclusive reserva-tion is removed by this state change.

(24)

10 Configuration

The properties of the state conditions are stored globally in the configuration, together with the state changes, in a hierarchy below the component Status.

The state conditions are stored as subcomponents directly subordinate to the fixed component called Status. The properties of the state conditions are assigned to these components as attributes. The state changes are likewise indirectly assigned to these components as subcomponents. The state condition is therefore the origi-nal state, and the subcomponent is the target state of the change. The change properties are determined by the attributes of the subcomponent, i.e. target state.

The attribute Status is always used as the state key. The name of the component is used as the state key only if this attribute does not exist.

To avoid any confusion, the attribute “Status=...” is only used in the standard Productstream Professional instal-lation if using the component name would compromise the uniqueness of the component designation. The example shown in the screenshot below clarifies this principle. The values in the square brackets are op-tional (the default values are shown here).

Sequence in which defined actions are performed during state changes

When changing a state, the configured actions are initiated as follows:

Setting the environment variables

The following environment variables are set before the state change functions are called: • _ChangeStatusID: ID of the target state

• _ChangeStatusDesc: Description of the target state

• _ChangeStatusUID: Unique ID of the current change (see ___Changestatus)

• _ChangeStatusLevel: Stack level for the recursive usage of ___ChangeStatus; 1 is set for the first call, 2 is set for the next time ___Changestatus is called, etc.

Applying the rights

If onChangeRights has been defined, these permissions are applied for the current element. Here, permissions are changed irrespective of the permissions which have been granted to the current user. The permissions set here may therefore restrict the scope of the subsequent actions.

"Check on reservation”

If an exclusive reservation exists and “KeepLock” has not been enabled, the public function “StatusUnLockAp-pInstalled” is performed. If this function has a return value (the variable Errorlevel) unequal to 0, the procedure is cancelled.

(25)

11

“Action to be performed on exiting” the original state “onChange”

An optional action, which is only performed when defined. If the action given here, or the public function which has been defined as the “Action to be performed on attaining”, cannot be found, the procedure is can-celled immediately and an error message is displayed. The public function automatically receives the key of the target state as the argument. The current element is still unchanged at this time (apart from the ElementPer-missions). STATUSKEY has the original state.

If this function has a return value (the variable Errorlevel) unequal to 0, the procedure is cancelled. In this case, the public function in the environment variable “Errortext” is expected to issue a suitable error message. This is displayed to the user by the runtime system. If $Errortext is empty, the state change is cancelled without an error message.

Action which has been defined for the state change

An optional action, which is only performed when defined. If the public function given here cannot be found, the procedure is cancelled with an error message. The public function automatically receives the key of the original state as Argument 1 and the key of the new target state as Argument 2. Before the public function is called, the current record buffer is filled with the new values for STATUSKEY, STATUS_CHANGE_USER and STATUS_CHANGE_DATE.

If this public function has a return value (the variable Errorlevel) is equal to 0, the record buffer is always up-dated. If this function wants to make additional changes to the element, the field values just need to be chan-ged. These are then written to the database upon exiting the public function.

If this function has a return value (the variable Errorlevel) unequal to 0, the procedure is cancelled. In this case, the public function in the environment variable “Errortext” is expected to issue a suitable error message. This is displayed to the user by the runtime system. If $Errortext is empty, the state change is cancelled without an error message. The current record buffer is initialized with the contents of the database!

“Action to be performed on attaining” the target state (Status_onEnter_<target state>)

An update of the current data record is always triggered before this optional public function is performed. This finalizes the state change in the database. This step cannot be undone. The system does not check whether the “Action to be performed on attaining” has been successfully performed or not. The public function automati-cally receives the key of the original state as the argument.

This function is also triggered directly after a new element has been created (Insert), as the new element has received the start state! This is indicated by the fact that no argument has been handed over. In this case, there is no original state!

"Remove reservation in the application”

If “KeepLock” has been disabled, the public function “StatusUnLock” is performed. This function, if it exists, removes a reservation on the application (ForceUnlock). The return value is not evaluated.

Set the state permissions as for “setRights”.

This triggers a second write operation in the database. These permissions are set irrespective of the permissions to the user.

The following generally applies for the configured public functions: • Nobody is allowed to change the field STATUSKEY.

• The functions are called with the element as the context. This means that the implementation locations ty-pical for the Productstream Professional objects apply.

• The functions may not perform an update of the record buffer. As described above, this takes place auto-matically in the defined sequence after the change function has been performed.

• The state change is not protected by a transaction! It is therefore important to deal with resultant errors in the public functions themselves.

(26)

12 Reading out the state definition from the configuration

If the state definition as described above exists, it is read out and processed. Notice must be taken of the following special cases and characteristics. No state conditions have been defined

If the top-level configuration component STATUS is missing, or the component Status does not have any subcomponents (the state conditions) the fixed state definitions in the EXE are used. These are contained for Productstream Professional Easy in the COMPASS.EXE, and are then also used for Productstream

Professional Pro. This includes the state changes.

There is no state condition with the property “StartStatus”

The first state which is read out receives this property! A message is written to errlog.err.

Programming conventions in the standard Productstream Professional Pro

in-stallation

• Function name for the action to be performed directly after the state condition has been attained: Status_ onEnter _<state ID>

• Function name for the action to be performed after exiting the state condition : Status_onChange_<state ID>

• Function names for the state changes: Status_<brief description>

• Every state function must (should?) call the function of the parent class of the framework at the end with “super.<state function>($arg);”!

The functions are implemented both on the level of the general element functions, as well as being specifically derived on the level of the documents, for handling files during state changes.

Configuring additional actions

(applies from COMPASS 2000 2.4)

Since the introduction of Productstream Professional Jobserver, requests have been made for a feature requi-ring that certain jobs must be created when a state is changed to “Released”. In a Productstream Professional Pro environment, this is not a problem. By extending the function Status_OnEnter_00003, this can be rea-lised with ___JobCreate(...) and the subsequent super. Status_OnEnter_00003.

A different solution is used for Productstream Professional Jobserver running under Productstream Professional Easy, version 2.4 and later.

If a Productstream Professional shell instruction is applied in the configuration to the attribute

“OnStatus00003” of the EntityType, this is performed for every state change which attains the target state 00003. The same applies for the other state changes.

Example 1:

Providing the relevant conditions have been fulfilled, this job is now created additionally when the state is changed from “In Review” to “Released”. With this call, the select job dialog window is displayed if more than one job fulfils the conditions. Compare this in the command reference section with the other optional ___JobCreate arguments.

Example 2:

If the additional actions are also dependent upon the document type, the configuration must look like this:

Here, a job is only created for those documents whose document type has defined the attribute OnStatus00003. No jobs are created for all documents which inherit the attribute from “*”! EntityType AIM.DOC.ENG Attribut OnStatus00003 = ___JobCreate( “StateChangeJob“ )

EntityType AIM.DOC.ENG Attribut OnStatus00003 = #(DTY: OnStatus00003)

DocumentType * Attribut OnStatus00003 =

EntityType DOC_COMMON Attribut OnStatus00003 = ___JobCreate( “WordJob“ ) EntityType DWG_COMMON Attribut OnStatus00003 = ___JobCreate( “ACADJob“ ) EntityType INV_COMMO Attribut OnStatus00003 = ___JobCreate( “InventorJob“ )

(27)

13 Establishing the start state

(applies from COMPASS 2000 3.0)

When extending state definitions during the course of customer customizations, the problem used to arise that the default condition of existing state conditions had to be adapted for each new start state. To combat this, and if possible by taking into consideration the attributes of the current element and providing the greatest possible compatibility with existing installations, the start state is established as follows.

• This state is retained if a recognized state key has already been entered in the field STATUSKEY, the asso-ciated default condition is not empty, and its evaluation returns TRUE. The following steps are no longer evaluated. This measure usually protects any programmed customizations which have explicitly entered a default value in the field STATUSKEY.

• The following feature was introduced in COMPASS 2000 3.0. The value of the attribute “StartStatus” for the current element is retrieved from the configuration. This state is used if it is a recognized state key and the associated default condition is either empty or its evaluation returns TRUE. The following steps are no longer evaluated.

• The default condition is checked for all the available statuses. The new element is used as the context. The first state for which this condition has been defined and which returns TRUE is used (as previously). The final step is no longer evaluated if such a state key is found.

Note

i !

The same rule applies to the search sequence as for public functions. First of all, the search is run in the hierarchy of the current folder, and then (if applicable) in the applications and document types, and finally in the hierarchy of the element types. The following aspect must be taken consideration regarding elements with document types: The field STATUSKEY is usually filled before the new record dialog window is displayed. At this point, only the element’s EntityType is known. A document-typical start state cannot be established, because a document type has not yet been defined. This is only then selected during the new record dialog. When saving, the start state is established in the Function ___Recordbuffer( insert ....) using the aforementioned 4 steps.

• The first state which has been read in or defined is used (as previously). The ‘first’ state is not explicitly spe-cified.

Compatibility:

General: COMPASS 2000 2.0

Additional configured actions added: COMPASS 2000 2.4 Establishing the start state: COMPASS 2000 3.0

(28)

Foreword

14

Chapter 3 Database customization

Foreword

Adding custom content to the Productstream Professional database is a very powerful customization tool. This section will go over the supported customizations to the database schema and the intended uses for these cus-tomizations.

Supported Customizations

Productstream Professional allows you to: • Add columns to existing tables and views • Add new tables and views

• Add new stored procedures • Add new triggers

• Add new indexes

It is suggested that any new content be prefixed with your company name (ex. MyCompany_CustomTable). This insures no collisions with future Autodesk changes.

Editing existing columns, stored procedures or triggers is not recommended or supported.

Database model

The Productstream Professional database contains different objects, and just few of them are relevant for cus-tomization. If you are looking to add additional columns to you environment, then the entity specific tables are the right one for you. Here the list:

• DOCUMENT … specific columns for engineering, office or secondary documents • PROJECT … specific columns for projects

• PART … specific columns for items

• CONTACT … specific columns for persons and organizations

• XREF_ELEMENT … describes the link between elements and might contains specific columns relevant for the relation between elements

Note: each table has a row size limit of 8000 characters, 4000 if UNICODE. Pay attention by adding additi-onal columns to not exceed that limit or further inserts might be refused. If you need more columns, then it might be a good idea to add them in an additional table.

Changes in the table must be reflected in the views so that Productstream Professional can work with. Each entity mostly refers to 5 views:

• VIEW_ALL_[Entity] … contains all active and deleted elements. Relevant for number generation as you don’t want to create a number already existing maybe in the waste basket.

• VIEW_[Entity] … contains all active, not deleted, elements. This is the view the user usually works with • VIEW_HISTORY_[Entity] … contains the history entries of the element. This view exists only for

ele-ments that manages a history

• VIEW_XREF_CHILD_[Entity] … contains elements of the entity cross-referenced with parent elements • VIEW_XREF_PARENT_[Entity] … contains elements of the entity cross-referenced with child elements There might be some additional views that address specific elements for performance reasons. One example is the VIEW_DOCUMENT_EMGINEERING. All this views must be updated accordingly to the changes made for columns or tables. Some views build one on the other, so it’s relevant to update the views in the cor-rect order. For instance, the XREF views depend on the regular views. A good idea it to look at the dependen-cies.

Manipulate database objects

To apply changes on the database we strongly recommend using the query analyzer or scripting tools. Product-stream Professional uses the SQL92 standard to remain compatible between Microsoft SQL and Oracle. Ven-dor specific languages, such as Transact SQL, and those specific commands are not supported. Do not use the graphical tools coming with the Management Studio. The graphical tools optimize the database definitions into the vendor specific SQL language. This causes serious troubles.

There is another advantage by using the scripting. By saving the script, you automatically create a documen-tation of your changes. Everyone can follow the customizations and it’s pretty easy to port the script on several environments. It’ll become possible to apply the same changes on the test and real environment.

(29)

Adding a new Column

15

If after have applied changes to the database Productstream Professional can display records but you get errors by creating new ones, your views probably have been damaged. An easy check is to verify if the view definitions contain key words like INNER JOIN in the FROM statement. In that case you will have to re-update your view with the correct SQL definition. As help you can use the SQL scripts used by the installer present on the DVD.

Adding a new Column

To create your own fields on entity types, you need to start at the database level. Add your new field as a co-lumn on the appropriate table and to the appropriate views. Suitable tables and views are describe in the chap-ter above.

At this point the new field is active. The next time you start up Productstream Professional, you can use that field in code or expressions. The field can be made available in the designer by updating the configuration and adding a new component to the GUIFields section of the affected entity types.

Supported Column Data Types

If you intend to use these columns as entity type fields, these are the supported types. SQL Server: nvarchar, varchar, nchar, char, smallint, numeric, decimal, float, datetime Oracle: Nvarchar2, varchar2, char, nchar, Number, date

Note

i !

• In Oracle, NUMBER integer values get translated to 64-bit values. So values have to be between -2^63 and 2^63-1.

• Productstream Professional does not store time information along with the date. Time values will always be set to midnight for each date stored.

Adding a New Table

New tables must have and primary numeric key to be correctly managed by Productstream Professional. The easiest way to create a new table is to mimic the syntax of an existing table, like the DOCUMENT or similar. All tables delivered with Productstream Professional contains an AIMKEY column. The name is not relevant, but the properties are. To make it simple just copy that syntax into your table and keep the same name. The only other rule for columns is that they must be one of the supported types in order for that column to be a field. See previous section of the list of supported types.

Once the table is set you will have to create or extend views. For creating views, even here mimic the syntax you’ll find in the standard views. If your table extends an existing view, then add the columns to the view and remember to add the AIMKEY from your table. The view must have reference to all AIMKEYs of all views to correctly support the read and write operations.

(30)

Connection

16

Chapter 4 Productstream Professional as DDE–Server

With the DDE Server, Productstream Professional provides a means of communication standard in the Win-dows world. The description below is aimed at developers familiar with DDE. It does not deal with the basic DDE concepts. Rather, it documents how Productstream Professional handles the elements of the DDE com-munication.

Connection

DDE-Execute

The data element of the DDE Execute command is as follows:

• If Topic == "SYSTEM" and Command == "front": the Productstream Professional window receives focus. • If Topic == "SYSTEM" and Command is not empty: Command is handed over to ___Shell to be

perfor-med.

• If Topic == <AIMKEY> and Command is not empty: Command is handed over to ___Shell to be perfor-med. The data record for AIMKEY from Topic is used for the runtime.

In all other cases the command is not executed.

DDE-Request

The data element of the DDE Request command is as follows:

• If Topic = SYSTEM and Item is not empty: Item is substituted (non data record-related) and returned. • If Topic == <AIMKEY> and Item is not empty: Item is substituted (data record-related) and returned. For

the runtime environment the data record for AIMKEY from Topic is used. Otherwise, Item is not substituted.

Caution!

The syntax of item is not compatible with COMPASS 4 !!!!

Settings for AIMKEY

The ENTITY_TYPE for AIMKEY is established from the table "ELEMENT". The attribute "BaseFolder" of this ENTITY_TYPE is established from the configuration. The runtime environment is built with the data record contained in this BaseFolder with the AIMKEY of the topic. If the attribute "BaseFolder" has not been defined, DDE Execute is not per-formed and DDE Request is processed with the table "ELEMENT".

Server name Topic Remark

AIM.COMPASS5.DDE

SYSTEM Refers in general to Productstream Professional functions / information from Productstream Professional, non database / data record-related.

<AIMKEY> Database / data record-related information. <AIMKEY> is the unique key in the Productstream Professional element table. Type Table AIM.DOC VIEW_DOCUMENT AIM.PRO VIEW_PROJECT AIM.CONTACT VIEW_CONTACT AIM.ADR VIEW_ADDRESS Other ELEMENT

(31)

Example

17 Example

MS°WINWORD-Makro

ChannelNo = DDEInitiate("AIM.COMPASS5.DDE", "System") 'Setup DDE channel UserId$ = DDERequest(ChannelNo, "$USERID")

DDETerminate ChannelNo 'Close DDE channel ...

ChannelNo = DDEInitiate("AIM.COMPASS5.DDE", AIMKEY$) ... 'Here integration of the DB-related functions DDETerminate ChannelNo

(32)

Preamble

18

Chapter 5 Productstream Professional DLL-Functions

Preamble

With Productstream Professional, the list of public functions can be extended not only by adding definitions in a DBP file, but also be registering functions in a DLL. The DLLs are registered in the configuration like DBQ modules and are loaded when the program is launched. The public functions in the DLL therefore also have a defined relationship in the object hierarchy.

Productstream Professional public functions from a DLLL

Procedure for registering functions in Productstream Professional

As far as Productstream Professional is concerned, the following actions are performed one after the other when the program is launched.

The following sequence applies for all modules designated in the configuration as Type=dll:

The specified DLL file is loaded with LoadLibrary(). The address of the function "AIM_Identify" is establis-hed, and the function is called. This function supplies the list with all the Productstream Professional functions registered in the DLL file. The corresponding address of the function is established with each of these names. These addresses are managed in Productstream Professional.

The functions all have the same prototype. They are registered as Productstream Professional public functions using the name under which they are defined in the DLL.

(33)

Productstream Professional public functions from a DLLL

19 Procedure for defining a public DLL function

The steps described below serve as a guide to show you how to generate your own DLL file with your specific functions using MS Visual C.

1 Create a new project ( type: "WIN32 Dynamic-Link Library").

2 Copy the file generic.c to the directory of your new project. Rename this file and add it to the project. Menu: "Projects" - "Add To Project" - "Files".

3 The file generic.c already contains two sample functions: "Generic1" and "Generic2". Replace the name "Generic1" with the name of the function you want to create. This function is called "NewFunction" in the rest of this description. This is done in four places:

• In the prototype definition:

DllExport AIM_EXTERN_FUNC NewFunction;

• When storing the name for passing on to Productstream Professional:

(N.B. The name is case-sensitive and must match the case used for the prototype! The case then becomes irrelevant in Productstream Professional)

Example:

static CHAR24 funcName[N_FUNC] = { "NewFunction"

,"Generic2" ....

};

• When storing a brief description of the function: static CHAR80 funcDesc[N_FUNC] =

{

"NewFunction without Arguments"

,"Generic2 (sample function of the Productstream Professional DLL interface)" ...

};

• When defining the function: int DllExport AIM_CALLBACK

NewFunction( pAIMFuncCTX a, LPSTR arg1, LPSTR arg2 ) {

int ret = 0;// // this return value is "Errorlevel" in Productstream Professional! // only as an example:

ret = aim_invoke(a,"___Shell","read()in NewFunction","NORECINFO"); // modify the code which defines your function as required. return(ret);

}

4Under "Settings", edit the search path for the header files (".h" files) so that the file ext_func.h can be found. 5 Generate the DLL.

Recommendation

Under "Project" - "Settings", select the runtime library option "Multithreaded DLL" for the category "Code Generation" in the property tab "C/C++". The COMPASS.EXE also uses this setting. The other settings have not been tested.

DLLs are published via the configuration. <Object> Modules <New Component>

ModuleName <Path and file name of the DLL>