AUTODESK®

PRODUCTSTREAM® PROFESSIONAL
2010

Developer Manual

March 2009
© 2009 Autodesk, Inc. All Rights Reserved. Except as otherwise permitted by Autodesk, Inc., this publication, or parts thereof, may not be
reproduced in any form, by any method, for any purpose.

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
 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
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

Preamble.............................................................................................................................................. 18
 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
Objects required in the remote data source ............................................................................... 35
 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
Introduction ......................................................................................................................................... 46
 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
COP files .................................................................................................................................... 58
 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
ObligatoryField ........................................................................................................................... 77
 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
#( FieldDesc <FieldName> ) ...................................................................................................... 81
 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
#( NextNumber <ParentAIMKEY> <Intervals> [<StartPos>] [<RelationshipID>] ) .................... 88
 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
 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
#( DBSpec_YesterDay ) .......................................................................................................... 103
 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
 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
 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

Suspended functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

 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.
 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

Format Meaning
SMALL UPPER-CASE LETTERS 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.
Warning texts alert you to errors which could have fatal consequences.
Caution!
Warning text

Notes contain more information on that particular manual text.

Note
Note text i !

☞ Instruction Instructions describe a specific task you need to carry out as shown in the step-by-step
1 Confirm … guide.
2 Type text …
Menu > Command Shorthand form of calling a command or a sequence of commands from a specific menu.
Shortcut menu > Command 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.

Programming and source code

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.
 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:
Permissions
Group
Create Read Modify Delete
Project leaders no yes no no
Design engineers yes yes no no
Draftsmen no yes yes no
User A therefore holds the following permissions yes yes yes no
 Configuring the permissions system 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.

Letter Permission
C Create
R Read
W Modify
D Delete
O Change owner
G Change owner group
A Change permissions
L Manage reservation

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:

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 A
type
Manage reservation Permission to manage reservations for elements of that element type L
 Configuring the permissions system 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.

Graphic 1: Attributes of the element types

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.

Attribute Value Explanation Example

DefaultGroup Group name Enters the owner group which is to be entered $ACTIVE_GROUP
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.
DefaultOwner User name Enters the owner who is to be entered when crea- $USERID
ting a new record of this element type.
OwnerRights _C_R_W_D The permissions which are to be granted to an +C+R+W+D
owner of an element of that element type are writ-
ten in this field.
GroupRights _C_R_W_D The permissions which are to be granted to the +C+R-W-D
owner group of that element type are written in this
field.
DefaultRights _C_R_W_D The permissions which are to be granted to a user -C+R-W-D
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.
 Configuring the permissions system 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.

Attribute Value
Group name _C_R_W_D_O_G_A

Graphic 2: The sub-component Rights

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.

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 Permission to read, copy, etc. this element.
send 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 Permission to edit and modify this file.
modify this element Remove write protection if necessary.
Delete Permission to delete this ele- Permission to delete this file.
ment Remove write protection if necessary.
Reserve The element has been reser- The user who initiated the reservation becomes the owner
ved of the element. All other users are granted read permission
(if at all).
 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.
 Configuration of the state management 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:

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 element 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 The permissions owned by the element while it belongs to the state can be defined here. The same
while the state applies. 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 Permissions granted to the element before the public functions for the state change are performed
when changing the state. 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.
Attribute name in the configuration: “onChangeRights”.

Note
Note must be taken of thei 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.
 Configuration of the state management 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.
 Configuration of the state management 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).

Graphic 3: Example of the state configuration

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.
 Configuration of the state management 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.
 Configuration of the state management 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:
EntityType AIM.DOC.ENG Attribut OnStatus00003 = ___JobCreate( “StateChangeJob“ )

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:
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“ )

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 “*”!
 Configuration of the state management 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 ! search sequence as for public functions. First of all, the search is run in the hierarchy of
The same rule applies to the
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
Check when reserving: COMPASS 2000 4.2
 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.
 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 !values get translated to 64-bit values. So values have to be between -2^63 and 2^63-1.
• In Oracle, NUMBER integer
• 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.
 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
Server name Topic Remark
SYSTEM Refers in general to Productstream Professional functions /
information from Productstream Professional, non database
/ data record-related.
AIM.COMPASS5.DDE
<AIMKEY> Database / data record-related information. <AIMKEY> is
the unique key in the Productstream Professional element
table.

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".

Type Table
AIM.DOC VIEW_DOCUMENT
AIM.PRO VIEW_PROJECT
AIM.CONTACT VIEW_CONTACT
AIM.ADR VIEW_ADDRESS
Other ELEMENT
 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
 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.
DLL files are released again before the program is terminated.
 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);
}
4 Under "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>
Type dll
 Productstream Professional public functions from a DLLL 20

Prototypes
Your function always has the following prototype:
int DllExport AIM_CALLBACK Generic1( pAIMFuncCTX a, LPSTR arg1, LPSTR arg2 )
The following applies for arguments:
pAIMFuncCTX a
This is the context for this function. Always pass on this argument unchanged to the callback functions. The
callback functions are described later on.
LPSTR arg1
This is the character string, which is passed on to the command as the argument in a command statement in
a procedure. The string contains all the characters between the parentheses in the command statement. If this
argument is an empty string, NULL may be passed on.
LPSTR arg2
This is the character string, which begins as text after the closing parenthesis and ends at the closing semi-colon
in a command statement in a procedure. If this text is empty, NULL is passed on.
Return value
The return value is an ErrorReturn value (type: int). A return value equal to 0 means that no error has occurred.
The return value is automatically assigned to the environment variable "Errorlevel".

CallBack functions from pAIMFuncCTX

The following callback functions are available::
• int aim_invoke(pAIMFuncCTX a, char *name, char *arg1, char *arg2);
• int aim_err_txt(pAIMFuncCTX a, char *text1, char *text2);
• int aim_ask(pAIMFuncCTX a, char *lbl_dflt, char *lbl2, char *lbl3, char *text);
• int aim_envprep(pAIMFuncCTX a, char *out, char *in);
• int aim_envscan(pAIMFuncCTX a, char *in);
• int aim_utexget(pAIMFuncCTX a, char *idstr, char *buffer, int buflen);
• char *aim_prepalloc(pAIMFuncCTX a, char *template)
• int aim_prepfree(pAIMFuncCTX a, char *toFree)
int aim_invoke(pAIMFuncCTX a, char *name, char *arg, char *txt);
This function is used to call a public defined function in Productstream Professional. Compare this with the
description of a command statement for procedures in the developer documentation. Public defined functions
also include all the internal Productstream Professional functions and all the functions defined in the DLLs!
The arguments:
char *name
Name of the function. It is not case-sensitive.
char *arg
The character string holding the argument.
char *txt
The character string holding the text.
Note
i !
The function defined by "name" is found in the object hierarchy due to the current context.

int aim_err_txt(pAIMFuncCTX a, char *text1, char *text2);

Function for writing an output text to the file errlog.err. Both texts, separated by a space, are shown in the
message window.
int aim_ask(pAIMFuncCTX a, char *lbl_dflt, char *lbl2, char *lbl3, char *text);
Compare this with description of ___ASKQ in the developer documentation. Here, the return value is retur-
ned directly as an integer.
int aim_envprep(pAIMFuncCTX a, char *out, char *in);
Establishes the value of an environment variable. Important: The buffer out must be large enough to accept
the value! The argument in is the name of the environment variable. The return value states how many cha-
racters have been interpreted by in.
 Functions for Productstream Professional conditions and formula 21

int aim_envscan(pAIMFuncCTX a, char *in);

Function for filling an environment variable. in is a string formed as follows:
"variable name=value"
int aim_utexget(pAIMFuncCTX a, char *idstr, char *buffer, int buflen);
This function allows texts from Productstream Professional ".tex" files to be used in the DLL.
The arguments:
char *idstr
idstr always has the form "NAMEnnn". "NAME" stands for the four-character file name of the ".tex" file, and
"nnn" stands for the text number (max. 3 digits) in this file. The file is sought in the same location where
Productstream Professional searches for its text files.
char *buffer, int buflen
buffer receives the text. buflen defines the maximum permitted length of buffer.
char *aim_prepalloc(pAIMFuncCTX a, char *template);
This function is used to substitute an arbitrary Productstream Professional expression. The return value is al-
located and must be released again using the function aim_prepfree()! The length of the substituted string may
not exceed approx. 16,000 characters!
int aim_prepfree(pAIMFuncCTX a, char *toFree);
This function is used to solely release the return value of the function aim_prepalloc().
Example
MyFunc( pAIMFuncCTX a, char *arg1, char *arg2 )
{
int ret = 0;
char *note = aim_prepalloc( a, “#(BEZ) $(USERID) @(DOCNAME0)“ );
if( note != NULL )
{
...//other statements
aim_prepfree( a, note );
}
return(ret);
}

Functions for Productstream Professional conditions and formula

The functions defined here can be used in Productstream Professional conditions and as functions in the for-
mula interpreter.
These functions are supported from Productstream Professional Exe version 4.14c (December 1st 1998).
The number of arguments in this function must be between 0 and 3. The argument type can be established
when the argument is run. The function can react accordingly, and e.g. perform conversions.
The return value and type are determined by certain following functions.

Procedure for registering these functions in Productstream Professional

The procedure complies to the one for public functions described above. However, the condition functions in
Productstream Professional are global, regardless to which object the DLL is registered as a module.
 Functions for Productstream Professional conditions and formula 22

Procedure for defining a DLL function for conditions and formulae

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 generic2.c to the directory of your new project. Rename this file and add it to the project.
Menu: "Projects" - "Add To Project" - "Files"
Note
This file also contains thei functions
! described in the previous chapter

3 The file generic2.c already contains a sample function: "isStringArg" (in addition to the two public functions
also included in generic.c). Replace the name "isStringArg" with the name of the function you want to create.
This function is called "isNewFunction" in the rest of this description. This is done in four places:
• In the prototype definition
DllExport EXPR_FUNC_1 isNewFunction;

Note
i ! of arguments, use EXPR_FUNC_0 if no arguments are expected, EXPR_FUNC_1 for
Depending upon the number
one argument, EXPR_FUNC_2 for two arguments and EXPR_FUNC_3 for three arguments.

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

Note
The name is case-sensitivei and
! must match the case used for the prototype! The case then becomes irrelevant in
Productstream Professional)

static CHAR24 funcName[N_FUNC] = {

"Generic1"
,"Generic2"
," isNewFunction"
....
};
• When storing a brief description of the function:
static CHAR80 funcDesc[N_FUNC] =
{
"Generic1 (Productstream Professional DLL Interface Sample) "
,"Generic1 (Productstream Professional DLL Interface Sample) "
,"isNewFunction(arg1) (insert description)"
...
};
• When specifying the flag value corresponding to the number of arguments
static long funcflags[N_FUNC] = {
0L
,0L
,AIM_FLAG_EXPRFUNC_1ARG
};
• When defining the function:
int DllExport AIM_CALLBACK
isNewFunction(pEXPR_FUNC_CTX ev, EXPR_FUNC_ARG arg1 )
{
int ret = 0; //return value != 0 cancels evaluation of the formula!
// modify the code which defines your function as required.
// only as an example:
if( ev->is_string( ev, arg1 ) )
ev->retboolean(ev, 1);
else
ev->retboolean(ev, 0);
return(ret);
}
4 Under "Settings", edit the search path for the header files (".h" files) so that the file ext_expr.h can be found.
5 Generate the DLL.
 Functions for Productstream Professional conditions and formula 23

Note
i !select the runtime library option "Multithreaded DLL" for the category "Code Generation" in the
• Under "Project" - "Settings",
property tab "C/C++". The COMPASS.EXE also uses this setting.
• You can use this function after adding the DLL file in the configuration and relaunching Productstream Professional.
It is called by entering @(= isNewFunction( " " ) ) in the formula interpreter.
• Further functions can be defined in this DLL using the same model. Please note that the value of the constants
"N_FUNC" must be raised accordingly.

Prototypes
Depending upon the number of arguments, the functions for Productstream Professional conditions and for-
mulae always have the following prototypes:
• int DllExport AIM_CALLBACK isStringArg( pEXPR_FUNC_CTX ev );
• int DllExport AIM_CALLBACK isStringArg( pEXPR_FUNC_CTX ev, EXPR_FUNC_ARG arg1 );
• int DllExport AIM_CALLBACK isStringArg( pEXPR_FUNC_CTX ev, EXPR_FUNC_ARG arg1,
EXPR_FUNC_ARG arg2 );
• int DllExport AIM_CALLBACK isStringArg( pEXPR_FUNC_CTX ev, EXPR_FUNC_ARG arg1,
EXPR_FUNC_ARG arg2, EXPR_FUNC_ARG arg3 );

Parameters
pEXPR_FUNC_CTX ev
This is the context for this function. Always pass on this argument unchanged to the callback functions. The
callback functions are described later on.
EXPR_FUNC_ARG arg
The arguments are encapsulated with this type, and can only access the actual values of the arguments using
the appropriate access functions. These access functions are contained in the structure pEXPR_FUNC_CTX
ev as callback functions. The callback functions are described later on.
Return value
The return value is an ErrorReturn value. A return value equal to 0 means that no error has occurred, and that
a result from the function has been stored using the callback functions ev->ret*().

Callback functions from EXPR_FUNC_CTX

The callback functions form the interface to the COMPASS.EXE file, and as service functions serve to handle
the arguments.
The functions are contained in the structure of the context, and can always be called together with it. The ex-
amples below provide more details.
Functions for establishing the argument type:
int (AIM_DLLCALL *is_int)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
int (AIM_DLLCALL *is_long)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
int (AIM_DLLCALL *is_double)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
int (AIM_DLLCALL *is_string)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
int (AIM_DLLCALL *is_boolean)(struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
int (AIM_DLLCALL *is_time)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
These functions return 1 if the argument is of the corresponding type.
Example:
if( ev->is_string(ev, arg1) )
...// how a string argument is handled!
 Functions for Productstream Professional conditions and formula 24

Functions for getting the arguments according to type:

int (AIM_DLLCALL *getint)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
long (AIM_DLLCALL *getlong)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
double (AIM_DLLCALL *getdouble)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
char *(AIM_DLLCALL *getstring)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
int (AIM_DLLCALL *getboolean)(struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
time_t (AIM_DLLCALL *gettime)( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
The argument arg corresponding to the given type is returned.
Caution!
getstring supplies a pointer to the original character string of the one in arg. This may not be changed!

The routines getint(), getlong() and getdouble() convert the types int, long, double, string and boolean into
the rquired format. All the other get*() functions expect the correct argument type to be specified. Otherwise,
getstring() returns NULL; getboolean returns FALSE (==0); gettime() returns (time_t)0.
Example
int DllExport AIM_CALLBACK
myCalculation( pEXPR_FUNC_CTX ev, EXPR_FUNC_ARG arg1, EXPR_FUNC_ARG arg2 )
{
double d1,d2, result;
d1 = ev->getdouble(ev, arg1);
d2 = ev->getdouble(ev, arg2);
... // process values d1 and d2 for result
ev->retdouble(ev, result);
return(0);
}

Functions for returning the result:

int (AIM_DLLCALL *retint)( struct tag_expr_func_CTX *ctx, int i);
int (AIM_DLLCALL *retlong)( struct tag_expr_func_CTX *ctx, long l );
int (AIM_DLLCALL *retdouble)( struct tag_expr_func_CTX *ctx, double d );
int (AIM_DLLCALL *retstring)( struct tag_expr_func_CTX *ctx, char *str, int len);
int (AIM_DLLCALL *retboolean)(struct tag_expr_func_CTX *ctx, int b);
int (AIM_DLLCALL *rettime)( struct tag_expr_func_CTX *ctx, time_t t);
These functions store the result of the function for further processing in the context.
Example
Returning the value 9 (type int ):
nextCalculation( pEXPR_FUNC_CTX ev, EXPR_FUNC_ARG arg1 )
{
...
ev->retint( ev, 9 );
return 0;
}

Functions for handling Productstream Professional expressions in string arguments:

The following functions must always be called in pairs. Reason: The first function (prep()) allocates memory
for the result. This must be freed again with the second function (free()).
char *(AIM_DLLCALL *prep )( struct tag_expr_func_CTX *ctx, EXPR_FUNC_ARG arg );
void (AIM_DLLCALL *free )( struct tag_expr_func_CTX *ctx, char *x );
Example:
...
char *tmp;
...
tmp = ev->prep(ev, arg1);
if( tmp != NULL )
{
... // process tmp
ev->free( ev, tmp );
}
...
All the other elements in the structure EXPR_FUNC_CTX cannot (may not) be handled in a DLL.
 Implementing functions in Visual Basic ActiveX DLLs 25

Implementing functions in Visual Basic ActiveX DLLs

The DLL CAI_CALL.DLL supplied by Autodesk since COMPASS 4.20.1 allows functions to be implemen-
ted in Microsoft Visual Basic (VB 6.0). The cai_CALL.dll and the VB DLL are linked using the Microsoft
ActiveX mechanisms.

Miscellaneous
To call a function in a VB DLL, the function CAI_CALL must always be called by Productstream Professional.
This function is implemented in cai_call.dll. The call is as follows:
CAI_CALL <ProgId> <Befehl> [<Argumente>]

<ProgId>
This key identifies the VB ActiveX DLL in the operating system registry. It is defined in the VB development
environment
<Command>
This command name is passed as an argument to the VB function "Run" in the VB implementation. This
allows the function to differentiate between multiple commands and perform them.
<Arguments> (optional)
The arguments are also passed to the VB function "Run".

Procedure for implementing functions in a VB ActiveX DLL

The steps described below serve as a guide to show you how to generate your own VB ActiveX DLL file with
your specific functions using MS Visual Basic.
1 The file CAI_CALL.DLL (located in the directory /bin in the Productstream Professional Client installation)
must be registered. To do this, go to the DOS command prompt, navigate to this directory and enter regsvr32
CAI_CALL.DLL. A message is displayed when the file has been successfully registered.
2 The project must first be renamed. Launch the Project Explorer from the View menu. The project properties
can also be opened here using the right mouse button. The settings in the Project Properties menu are as fol-
lows:
• ProjectName: Arbitrary (no convention defined to date)
• ProjectType: ActiveX DLL
• StartupObject: none
3 The class name can also be edited in the Project Explorer using the right mouse button. The class properties
are as follows:
• Class Name: Arbitrary (no convention defined to date)
• DataBindingBehavior: 0
• DataSourceBehavior: 0
• Instancing: 5 MultiUse
• MTSTransactionMode: 0
• Persistable: 0
4 Set a reference to CAI_CALL.DLL. To do this, select the option "Reference ..." in the Project menu. In the
list box, place a check mark next to "CAI DLL 1.0 Type Library".
 Implementing functions in Visual Basic ActiveX DLLs 26

5 Write the following text in the class source text (or copy it into the text using the clipboard):
Implements ICAI_Call

Public Function ICAI_Call_Run(ByVal Callback As Object, ByVal args As Variant) As Variant

Dim Cb As ICAICallback

' This instruction checks whether the

' correct object has been passed in the callback
Set Cb = Callback

'Branches corresponding to the command (arguments from CAI_CALL …)

Select Case args(0)
Case "Funcname1"
Cb.Err_Txt "Func1 called"
MsgBox "Func1 called"

Case "Funcname2"
Cb.Err_Txt "Func2 called"
MsgBox "Func2 called"

Case Else
Cb.Err_Txt "Invalid function name"
MsgBox "Invalid function name"

End Select

'Return value
ICAI_Call_Run = 0

End Function

'Only dummy functions from here

Public Property Get ICAI_Call_FuncNames() As Variant
ICAI_Call_FuncNames = "Execute"
End Property

Public Property Get ICAI_Call_Documentation() As String

ICAI_Call_Documentation = "Test documentation"
End Property

Public Function ICAI_Call_GetMenuText(ByVal ICB As Object, ByVal Fname As String) As

String
ICAI_Call_GetMenuText = "Test menu text"
End Function

' end of file

6 Save everything.
7 To acquire a finished DLL, select the option "Generate <project name>.dll" in the File menu. The output path
can then be specified in the file selection box..

The following call must be used to access a function from the new DLL:
cai_call ProjectName.ClassName Command Argument1 Argument2 ...
In the first version of the CAI_CALL.DLL, this calls the function "Run" in the VB DLL. This function is
assigned the following parameters:
• an object reference back to Productstream Professional (the callback argument)
• a variant array (the argument args), in which the arguments:
- Command
- Argument1
- Argument2
are available.
Convention: args(0) is the command which is to be performed in the "Run" function. In the current version,
this function should return an integer value. This is a current value in Productstream Professional but cannot
be evaluated further.
The callback object in the "Run" function allows you to call further Productstream Professional functions from
the VB-DLL. The functions available for the ICAICallback object are presented for selection by the Intellisen-
se feature in the development environment.
 Implementing functions in Visual Basic ActiveX DLLs 27

Functions of the ICAICallback interface object

In these examples, it is assumed that the "Run" function is implemented as follows:
Public Function ICAI_Call_Run(ByVal Callback As Object, ByVal args As Variant) As Variant
Dim Cb As ICAICallback
Set Cb = Callback
...
The examples below are formed with the variables Cb as given here.
Function Call(Name As String, Arg1 As String, Arg2 As String ) As Long
This function allows all the other public functions to be called in Productstream Professional.
Example:
ret = Cb.Call (“___Changefield“, “IDENT=$(EnvVar1)“, ““)

Function Envprep( Name As String) As String

This function is used to query the contents of an environment variable.
Example:
userid = Cb.Envprep ( “USERID“ )

Function Envscan( Expr As String) As Long

This function is used to fill an environment variable.
Example:
Cb.Envscan ( “EnvVar=$(USERID:a)“)
The value may itself contain an environment expression.
Function Err_Txt( Text As String ) As Long
A text given here is displayed in the Productstream Professional message window.
Function Prep( Expr As String) As String
This function substitutes Expr for all the available Productstream Professional expressions!
Example:
Cb.Envscan ( Cb.Prep("EnvVar=#(IDENT) @(BEZ:t) $(USERID) @a->(IDENT)") )

Function Utex( Id As String) As String

Id is a string in the format "NAMEnnn". The function then gives the text. The number nnn is returned from
the text file NAME.tex!

Restrictions
The ICAICallback InterfaceObject only exists for the runtime of the function Cai_Call. This means that only
non-status functions can be implemented with VB. Non-modal dialogs and the passing of ICAICallback In-
terfaceObjects to other applications are not supported.
 Preamble 28

Chapter 6 Productstream Professional .NET Programming

Preamble
Productstream Professional allows you to make modifications using the .NET programming interface. You can
create your own DLL files that are installed on the Productstream Professional Client.

Requirements
• Good .NET programming skills.
• You must be very skilled in configuring and adapting Productstream Professional in order to use its func-
tions.
• The development environment Visual Studio is required to create the .NET DLLs. All you need is Visual
Studio 2005 or higher Express Edition, which Microsoft provides free of charge.

Architecture of the .NET programming interface

Infrastructure
The infrastructure for the .NET programming of Productstream Professional includes the file NetModule.dll,
which you can find in the bin directory of the Client. A reference to this DLL must be created in the .NET
project.

Link a .NET DLL in the configuration

Productstream Professional loads a .Net DLL like a menu or DBP module. A component in the configuration
must be created under Modules to an object (Entity, Folder, Document or Application). In our example below
the new component will be called Module_test. The attributes of the created components provides informati-
on about location (ModuleName) and type (Type) of the new module. With Productstream Professional
2010 an additional attribute (AssemblyName) provides information about the full assembly name. This per-
mits to save the .NET DLL on the server.
Note
i !
With Productstream Professional 2009 the .NET DLL must be located on the client. With Productstream
Professional 2010 the DLL might be located on the server. Having the DLL on the server avoids additional deploy-
ment effort.

Method calls from .NET to Productstream Professional

NetModule.dll provides the methods CallFunction and Substitute. A .NET class must be derived from the
base class CCustomerNetModuleBase defined in NetModule.dll.
public int CallFunction(<FunctionNameString>, <ArgumentString>)
CallFunction is used to call internal and public functions. The first parameter is the function you like to call.
The second parameter describes the arguments you like to pass to the function. Both parameters are strings.
public in Substitute(<ExpressionString>)
Substitute is used for calling Productstream Professional expressions. The argument ist the expression you like
to substitute. The return value is the substituted string.

Method calls from Productstream Professional to .NET

Attributes are used to expose a method for use by Productstream Professional. First, the class that contains the
method must be public and must have the PSPClass attribute with a value of "Exposed PSP class"
([PSPClassAttribute("Exposed PSP class")]).
Exposed methods must be declared public and they must contain the PSPMethod attribute. The value for the
attribute should be “PSP Method” ([PSPMethodAttribute("PSP Method")]) for methods or “PSP Expression”
([PSPMethodAttribute("PSP Expression")]) for expression handlers.
 Example 29

PSP Methods are used to perform an action. They must take a single string as is argument and must return
either an int, void, or string. If an int is returned, that value becomes the return code for the function. If a
void is returned, then a 0 is returned to the system and CMPException objects should be used for errors. If a
string is returned, the value becomes the return string (0 is the error code).
PSP Expressions are used to compute a value, but they can also perform an action as a side effect. They must
be declared static as well as public. The return type should be an int or void, and the first input should be of
type IEVAL_CTXWrapper. The function can also have up to 3 additional arguments of type
CBaseARGWrapper. The IEVAL_CTXWrapper object is used to make calls into Productstream Professional
and to set the result of the expression. If the return type is int, its value is the return code for the function. If
a void is returned, then a 0 is returned to the system and CMPException objects should be used for errors.
The optional attribute PSPMethodcondAttribute ([PSPMethodCondAttribute("<Accessibility>", "<Visibili-
ty>", "<Flag>", "<Rights>")]) controls the visibility and accessibility of the method. The first 3 conditions are
boolean expressions (TRUE|FALSE), while the fourth condition describes the needed rights (CRWD), and all
four conditions are optional.

.NET DLL Security

To insure that the DLLs haven’t been tampered with, .NET modules must have a strong name, and the full
assembly name must be specified in the Productstream Professional configuration. For this purpose the new
attribute AssemblyName has been introduced with Productstream Professional 2010. At runtime, the loaded
assembly is checked against the full assembly name. If the information doesn't line up or there is missing in-
formation, the module does not load.
Creating a module with a strong name is easy in Visual Studio 2005. Under the project properties, go to the
Signing section. There, you can specify the key file or Visual Studio can create one. Let Visual Studio create
one for you. The key file is then used to sign the assembly at compile-time.
Note
The behavior described ini !this chapter applies only to Productstream Professional 2010. For earlier versions of
Productstream Professional the .NET DLL does not require a strong name and must reside on the client. The addi-
tional attribute AssemblyName is not required.

The new attribute AssemblyName only applies to .NET modules. The syntax of AssemblyName is the stan-
dard .NET syntax defined by Microsoft. (eg. AssemblyName=NetZip, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=9a0c674cc64c03a3). Productstream Professional will check the Name, Version and Pu-
blicKeyToken properties. Other information, such as Culture, is not checked. The PublicKeyToken can be
found by using the sn.exe command line tool provided with Visual Studio. (eg. sn.exe –T <YourDllName>.dll)

Loading from a network share

Previously .NET DLLs had to reside in the client’s bin directory. This was an issue for administrators since it
required each client install to be updated. The ideal solution is to allow .NET modules to be loaded from a
network share. That way there is only 1 file to worry about.

Example
This example shows the basic results you can achieve with the .NET programming for Productstream
Professional. The following new functions are generated in Productstream Professional.
• A "New menu entry" menu option is created in the shortcut menu of the office documents folderer. Calling
this mean command opens a message box displaying the name of the data record. The menu entry is not
active if the office document has been assigned the status "Frozen".
• If the title (SHORT_DESC) in the new entry message box contains the expression "Do not close", the new
entry message box cannot be closed.
To do this, the following steps are necessary:
1 Create the menu file
2 Create the .NET DLL
3 Define the save folder for the DLL and the menu file in the configuration
 Example 30

☞ Creating the menu file

1 Create a menu file demo.mnu in the directory etc of the server installation with the following contents
[rmt_OfficeDocument_List]
Info_150=
Type_150=INCMENU
Func_150=
Arg__150=super.rmt_OfficeDocument_List

Info_151=New menu Entry

Type_151=COMMAND
Func_151=NewCommand
Arg__151=

☞ Creating the .NET-DLL

The .NET-DLL is created in the Visual Studio development environment from Microsoft. Very good skills in
.NET programming are required to do this.

☞ How to create the sample DLL

1 In Visual Studio, create a new project called demo using the Class library template.
2 Create a reference to the file NetModule.dll in the bin directory of the Productstream Professional Client in-
stallation.
3 Add the following source text to the class Class 1:
{
using System;
using System.Collections.Generic;
using System.Text;
using CMPNetModule;
using System.Windows.Forms;
namespace demo
{
[PSPClassAttribute("Exposed PSP class")]
public class Class1 : CCustomerNetModuleBase
{
[PSPMethodCondAttribute("TRUE", "TRUE", "", "CW")]
[PSPMethodAttribute("PSP Method")]
public void NewCommand(string arg)
{
MessageBox.Show(Substitute("#SHORT_DESC"));
}

[PSPMethodAttribute("PSP Method")]
public int PreOnInsertNew(string arg)
{
string sdesc = Substitute("#SHORT_DESC");
if (sdesc.Contains("Do not close"))
return 1;
else
return CallFunction("super.PreOnInsertNew", arg);
}
}
4 Generate the DLL. Move the DLL to a convinient folder, like the Productstream Professional Client folder or
the Server folder (Productstream Professional 2010 only).
Note
i !
In this example the first function has been declared as void without a return. This is new with PSP2010 and is the
preferred way. However, the second function shows how to work with return values. In case you overload an existing
Productstream Professional functionality, like in the second example, returing a vaue might be more appropriate as
the passed argument value must be returned as well to the overloaded function.

☞ Defining the DLL and menu file in the configuration

1 Start the Productstream Professional Configuration Editor
2 Select the profile CUSTOMER:SYSTEM
3 Select the component AIM.DOC.OFF (in Entity_Types)
4 Create a sub-component Modules
 Debugging 31

5 In Modules, create the sub-component Module_mnu

6 In Module_mnu create the attribute ModuleName with the value $(CMPETC:|+)demo.mnu
7 In Module_mnu create the attribute Type with the value mnu
8 In Modules, create the sub-component Module_test
9 In Module_test, create the attribute ModulName with the value $(CMPEXE:|+)demo.dll
10 In Module_test, create the attribute Type with the attribute value net
11 In Module_test, create the attribute AssemblyName with the attribute value NetZip, Version=1.0.0.0, Cul-
ture=neutral, PublicKeyToken=<PublicKeyOfYourDLL>.The public key of your DLL must be retrieved
via sn.exe as described above.
Note
Step 11 is necessary only ifor! Productstream Professional 2010.

Debugging
For debugging your functionality your Visual Studio must be configured accordingly to start Productstream
Professional:
• In the project properties, change the option Start external program in the Debug property tab to ($CM-
PEXE:|+COMPASS.EXE).
• Enter -pro as the command line argument.
• Specify the Productstream Professional working directory.
Note
i !
For debugging with Productstream Professional 2010 the module must reside in the same folder as the compass.exe.

Class Definitions
This documentation represents the official .NET API. Anything not documented here is “use at your own
risk”. Autodesk makes no guarantees about future compatibility or support availability of undocumented
functions and classes.

CBaseARGWrapper class
This class is a wrapper for arguments passed in to expressions. The class itself has no exposed methods or pro-
perties. IEVAL_CTXWrapper has methods that can extract data from these objects.

CCustomerNetModuleBase class
Classes which expose methods to Productstream Professional should be derived from this class.
public CCustomerNetModuleBase()
Default constructor
public int Substitute(string TextIn, ref string TextOut)
Execute a text substitution from Productstream Professional
• TextIn – The string to be substituted.
• TextOut – The result of the substitution.
• Returns - The error code
public string Substitute(string TextIn)
Execute a text substitution from Productstream Professional
• TextIn – The string to be substituted.
• Returns – The result of the substitution.
public int CallFunction(string FuncName, string Arg)
Execute functions from Productstream Professional
• FuncName – The name of the function to call.
• Arg – The arguments to the function.
• Returns – The error code.
 Class Definitions 32

CMPException class
Used for handling exceptions. This class is derived from Exception.
public int ErrorCode {get}
Gets the error code for the function.

public string DisplayText {get, set}

Gets or sets the text to be display to the user.
public CMPException(int errorCode)
public CMPException(int errorCode, string message)
public CMPException(int errorCode, string message, Exception innerException)
public CMPException(int errorCode, string message, string displayText)
public CMPException(int errorCode, string message, string displayText,
Exception innerException)
Constructors for Productstream Professional exceptions.
• errorCode – The error code.
• message – The message to write to the error log.
• displayText – The text to display to the user.
• innerException – The original exception.

PSPClassAttribute attribute
Identifies the class with exposed methods.
public PSPClassAttribute(string str)
The constructor.
str – Value must be “Exposed PSP class”.

PSPMethodAttribute attribute
Identifies the exposed methods
public PSPClassAttribute(string str)
The constructor.
str – Value must be “PSP Method” or “PSP Expression”.

PSPMethodCondAttribute attribute
Adds conditions to exposed methods
public PSPMethodCondAttribute(string strCon1, string strCon2, string strCon3, string strRight)
The constructor.
• strCon1- The condition is referred to as a static condition as it is evaluated once when Productstream Pro-
fessional is launched. If FALSE is returned by the condition, the respective option is not shown in the menu
or toolbar.
• strCon2 - The condition is referred to as a dynamic condition as it is re-evaluated each time the highlight
bar is repositioned. If FALSE is returned by the condition, the respective option is disabled in the menu or
toolbar, but is grayed out and remains visible.
• strCon3 - This condition can relate to the object. In menus, the option has a check mark if TRUE is returned
by the condition. In a toolbar (toggle button), this is shown pressed down if TRUE is returned by the con-
dition.
• strRight - The function can only be performed if the rights listed below are given. 4 letters can be used to
define these rights:
•R Read rights must have been granted
•W Write rights must have been granted
•D Delete rights must have been granted
•C The right to create new records must have been granted
 Class Definitions 33

PSPMethodDefArgAttribute attribute
Sets the default arguments to an exposed function.

public PSPMethodDefArgAttribute(string strarg)

The constructor.
• strarg - The default parameters, which are only handed over to the function if no parameters passed in.

IEVAL_CTXWrapper interface
The interface for the context of expression functions.
public int Call(string name, string arg1, string arg2)
This function is used to call a public defined function
• name – The name of the function.
• arg1 – The arguments to the function.
• arg2 – Reserved for future use.
• Returns – The error code.
public int getboolean(CBaseARGWrapper arg)
Gets the boolean value of an input argument
• arg – The input argument
• Returns – The boolean value. 0 is a FALSE value. All other values are TRUE.
public int getdouble(CBaseARGWrapper arg)
Gets the double value of an input argument
• arg – The input argument
• Returns – The double value
public int getint(CBaseARGWrapper arg)
Gets the integer value of an input argument
• arg – The input argument
• Returns – The integer value
public Int64 getlong(CBaseARGWrapper arg)
Gets the long integer value of an input argument
• arg – The input argument
• Returns – The long integer value
public string getstring(CBaseARGWrapper arg)
Gets the string value of an input argument
• arg – The input argument
• Returns – The string value
public Int64 gettime(CBaseARGWrapper arg)
Gets the time value of an input argument
• arg – The input argument
• Returns – The time value represented as a long integer
public int is_boolean(CBaseARGWrapper arg)
Tells if the input argument is a boolean.
• arg – The input argument
• Returns – If the argument is a boolean a non-zero value is returned.
public int is_double(CBaseARGWrapper arg)
Tells if the input argument is a double.
• arg – The input argument
• Returns – If the argument is a double a non-zero value is returned.
 Class Definitions 34

public int is_int(CBaseARGWrapper arg)

Tells if the input argument is an integer.
• arg – The input argument
• Returns – If the argument is an integer a non-zero value is returned.
public int is_long(CBaseARGWrapper arg)
Tells if the input argument is a long integer.
• arg – The input argument
• Returns – If the argument is a long integer a non-zero value is returned.
public int is_string(CBaseARGWrapper arg)
Tells if the input argument is a string.
• arg – The input argument
• Returns – If the argument is a string a non-zero value is returned.
public int is_time(CBaseARGWrapper arg)
Tells if the input argument is a time value.
• arg – The input argument
• Returns – If the argument is a time value a non-zero value is returned.
public string prep(CBaseARGWrapper pfk)
Gets the value of the input argument.
• pfk – The input argument.
• Returns – The argument value.
public string prepalloc(string name)
Execute a text substitution from Productstream Professional
• name – The string to be substituted.
• Returns – The result of the substitution.
public int retboolean(int b)
Sets the boolean result of the expression.
• b – The result of the expression. A value of 0 means FALSE. All other values mean TRUE.
• Returns – The error code.
public int retdouble(double d)
Sets the double result of the expression.
• d – The result of the expression
• Returns – The error code.
public int retint(int i)
Sets the integer result of the expression.
• i – The result of the expression
• Returns – The error code.
public int retlong(long l)
Sets the long integer result of the expression.
• l – The result of the expression
• Returns – The error code.
public int retstring(string str, int len)
Sets the string result of the expression.
• str – The result of the expression.
• len – The string length.
• Returns – The error code.
public int rettime(Int64 t)
Sets the time result of the expression.
• t – The result of the expression. A time value converted to a long integer.
• Returns – The error code.
 Foreword 35

Chapter 7 Connecting to remote database sources

Foreword
Productstream Professional Pro allows access to various data sources. A data source can be an Oracle or an MS-
SQL Server database object.
The database objects can also be located in different schemas (Oracle) or databases (MS-SQL), or on different
entities (servers).
The most straight-forward case is directly following the installation. All objects are located in a schema or da-
tabase. This database serves as the login database.

Definition of the login database

A login database is defined by the connect string, which is in the section [CONNECT] of the COMPASS.INI
file.
The user account (DBUSER und DBPASSWORD) used for the login database is in the section [_cmpusr_].
All the objects in the login database do not have to be entered as fully qualified records (although they can be).

Definition of a remote data source

A remote data source differs from the login database in that the database objects which are accessed are in a
different schema (Oracle) and a different database (MS-SQL) respectively in the same instance or on a different
entity to the login database.

Objects required in the remote data source

To allow Productstream Professional write access to the remote data source, it must contain the following ob-
jects:
• the procedure aim_generate_aimkey and the table AIMKEY
• the table DML_LOG
• the procedure aim_dml_exec and the table DML_TEMP (MS-SQL only)
• the procedure aim_create_key

Configuration
Definition of the remote data source in the configuration
Remote data sources are always configured in the configuration of the login database or schema, whereby the
data source is always assigned to a folder in Productstream Professional. The data source is defined in the at-
tribute DBView of the respective folder. This attribute must be adapted. The attribute DBVIEW of the re-
quired folder is entered as a fully qualified record using the configurator.
Example
[MY-SERVER-XXYZ].database.dbo.VIEW_PROJECT
Note
i ! name <database> is replaced by the fixed value "oracle"
Under Oracle, the database
 Configuration 36

User account of remote data source

If the user account of a remote data source is not exactly the same as that of the login database, the login in-
formation must be stored in a section of the COMPASS.INI file
The section name is defined as follows: <server name>.<database name>. Only the enclosing square brackets
may be used. Nesting is not permitted.
DBUSER and DBPASSWORD must be defined as attributes in the section, otherwise Productstream
Professional attempts to set up a connection using the login account (DBUSER/DBPASSWORD in the sec-
tion [_cmpusr_].
A connect string can be specified. If this is missing, Productstream Professional attempts to set up a connection
based on the information in the section header.
Example
Data source [MY-SERVER-XYZ].database4711.dbo.VIEW_PROJECT
Entry in COMPASS.INI:
#######
[MY-SERVER-XXYZ.database4711]
DBUSER=COMPASS
DBPASSWORD=CCRYzuerterewturtewr9824732894701843fejeshfie3
CONNECTSTRING=Server=MY-SERVER-XXYZ;Database=database4711
#######

Refreshing the user interface

External data is NOT refreshed in the user interface.
The function key F5 should be assigned to perform this task manually.
Example
global.mnu, Section Tools:
###########
Func_81=-
Info_82=Update
Type_82=COMMAND
Func_82=___DBUtils
Arg__82=sync;all
Accelerator_82=F5
##########
 Scenarios Oracle database 37

Scenarios Oracle database

Accessing a remote schema on the login instance
Scenario:
The Productstream Professional schema has been installed in the Oracle entity under the name
"LOGIN_SCHEMA". However, the data for the office documents is required by the schema
"REMOTE_SCHEMA.

Graphic 4: Shared data storage on an Oracle entity

Configuration:
The office documents are managed by the folder Folder_OfficeDocument. All that is required is to add the
schema to the object name using the Productstream Professional configurator tool by changing the attribute
DBVIEW of the folder Folder_OfficeDocument from VIEW_DOCUMENT_OFFICE to
REMOTE_SCHEMA.VIEW_DOCUMENT_OFFICE.

Graphic 5: Configuring a folder whose database objects are in a foreign schema

 Scenarios Oracle database 38

Accessing a schema on a different Oracle instance

Scenario
The Productstream Professional schema has been installed on the Oracle Instance1 (name
„LOGIN_SCHEMA“) but the data of the item master are required by the „REMOTE_SCHEMA“ schema
on the Oracle Instance2.

Graphic 6: Shared data storage on multiple Oracle entities

Configuration
The products are managed by the folder Folder_Part. It is necessary to specify on which Oracle entity the sche-
ma with the master product data is stored using the Productstream Professional configurator tool.
The attribute DBVIEW of the folder VIEW_PART is qualified as follows:
DBVIEW=ORCL2.oracle.REMOTE_SCHEMA.VIEW_PART
Explanation:
ORCL2: Name of the instance
oracle: Default placeholder as Oracle does not recognize catalogs (databases)
Remote_Schema: Schema / user name
VIEW_PART: Name of the database object
As a new remote entity needs to be opened, Productstream Professional requires the connection details.
The following section needs to be added to the COMPASS.INI file:
[ORCL2.oracle]
DBUSER=REMOTE_SCHEMA
DBPASSWORD=<encrypted password of the user REMOTE_SCHEMA>
CONNECTSTRING=provider=msdaora;data source=orcl2
Encryption of the password:
The password can be encrypted in the shell as follows:
set passwd=#(=mkPassWord("MYPASSWORD"))
The environment variable can then be read out ("___cmputility writesyspar") and entered in the
COMPASS.INI.
Note
i ! first be configured for the Oracle client.
The Net8 alias ORCL2 must
 Scenarios MS SQL Server 39

Scenarios MS SQL Server

Accessing a remote database on the login server
Scenario
The Productstream Professional schema has been installed on the MS-SQL Server MSSQL1 in the database
"Login_Database". However, the master product data is required by the database "Remote_Database".

Graphic 7: Shared data storage on an MS-SQL Server entity

Configuration:
The items are managed by the folder Folder_Part. It is necessary to specify in which database the master pro-
duct data is stored using the Productstream Professional configurator tool.
The attribute DBVIEW of the folder VIEW_PART is qualified as follows:
DBVIEW=[MSSQL1].Remote_Database.dbo.VIEW_PART
Explanation:
MSSQL1: Server name (or the alias)
Remote_Database: Database name (catalog)
dbo: The default user (schema) dbo is always used.
VIEW_PART: Name of the database object
As a new connection to the database needs to be opened, Productstream Professional requires the connection
details.
The following section needs to be added to the COMPASS.INI file:
[MSSQL1.Remote_Database]
DBUSER=COMPASS
DBPASSWORD=<encrypted password of the user COMPASS>
CONNECTSTRING=provider=sqloledb;Database=Remote_Database;Server=MSSQL1

Accessing a remote database on a remote SQL Server

The configuration corresponds to the configuration described in the previous section, i.e. the appropriate ent-
ries need to be made in the configuration and COMPASS.INI for each remote database (irrespective of the
entity).
 Introduction 40

Chapter 8 API Programming Guide of the AutoCAD/MDT

Integration in Productstream Professional
Introduction
The programming interfaces described here are available for all the AutoCAD-based integrations in
Productstream Professional (AutoCAD Integration, Autodesk Mechanical Integration and Autodesk MDT
Integration).

CAI interface
The functions of the CAI interface are described in this section. These functions can be called using DBP pro-
cedures, in Productstream Professional Jobserver and from the Productstream Professional shell.

Calling the CAI functions

General syntax for calling the CAI functions
CAI_CALL <CAI class name> <function name> [<Arg1> <Arg2> <Arg3>]
The class name can be established using #(Appl:CAI_Name). However, an application context is required to
do so. This is not the case when using Productstream Professional Jobserver or the Productstream Professional
shell. The class name of the AutoCAD-based application is AIMDAcad[version].CAI_Call, where [version]
stand for the CAD version (e.g. 16, 17 or 17x for 64Bit). When using the class name directly, remember that
some CAI functions in turn require an application context (e.g. AIMDOpen to launch AutoCAD).
Absolute file name:
The absolute file name of an AutoCAD document is required as an argument for some of the functions, which
means that the path, file name and the extension must be given.
 CAI interface 41

AIMDChangeAimkey
Brief description
Replaces the existing AIMKEY of a title field block in the currently open drawing with another AIMKEY. This
function searches the entire drawing (model area and layouts) for title field blocks with the specified AIMKEY,
replaces it with the new AIMKEY and then updates the title field.
Title fields that are managed by Productstream Professional usually have one AIMKEY. This refers to a local
drawing (DLA) in Productstream Professional, and the title field attributes are filled with the corresponding
data for this entry. If the AIMKEY is empty, the data from the document record is used.
Arguments
Arg1: <existing AIMKEY>
AIMKEY for a title field block that is to be replaced. Must always be given. Can also have the value "*" (see
Remarks).
Arg2: <new AIMKEY>
New AIMKEY for the title field block. Can also be empty (see Remarks).
Return values
None. Messages or errors are written to the log file ac16log.err.
Remarks
• Before this function can be run, it is necessary to launch an AutoCAD-based application and open a docu-
ment using Productstream Professional.
• If "*" is given for the existing AIMKEY, all the title field blocks in the drawing that are being managed by
Productstream Professional are given the new AIMKEY.
• If the new AIMKEY is empty, the link with the record in Productstream Professional is "deleted" and the
title field is filled with the data for the document record.
• The function is run automatically in Productstream Professional after the function "Copy engineering do-
cument" as soon as the copied document is opened for the first time. This ensures that the title fields in the
copied drawing are linked with the copied local drawings (DLA).
Note
The AIMKEY for a title ifield
! block can be checked using the AutoCAD command AIMDGetTitleInfo.

AIMDNew
Brief description
Function for creating an AutoCAD document.
Arguments
Arg1: <File>
The absolute file name of the new AutoCAD document.
Return values
None. Error messages are displayed on the screen where applicable. Messages or errors are written to the log
file ac16log.err.
Remarks
• The corresponding AutoCAD application is launched if necessary (AutoCAD, Mechanical or MDT depen-
ding upon the configuration).
• User input is expected when the function is run (e.g. selection of a template, depending upon the configu-
ration).
• In the case of MDT documents, component or assembly files are created according to the document type in
Productstream Professional.
 CAI interface 42

AIMDOpen
Brief description
Function for opening an AutoCAD document.
Arguments
Arg1: <File>
The absolute file name of the AutoCAD document to be opened.
Return values
None. Messages or errors are written to the log file ac16log.err.
Remarks
• The corresponding AutoCAD application is launched if necessary (AutoCAD, Mechanical or MDT depen-
ding upon the configuration).
• If the AutoCAD document is already open, it is just activated.
• If necessary the AIMKEYs for the title field blocks are substituted (after the function Copy engineering do-
cument). See AIMDChangeAimkey.
• If the document is a local drawing (DLA), the corresponding title field is displayed after it has been opened.

AIMDOpenReadOnly
Brief description
Function for opening an AutoCAD document in write-protected mode.
Arguments
Arg1: <File>
The absolute file name of the AutoCAD document to be opened.
Return values
None. Messages or errors are written to the log file ac16log.err.
Remarks
• See AIMDOpen

AIMDPublishDWF
Function for creating the DWF secondary file for an AutoCAD document.
Arguments
Arg1: <File>
The absolute file name of the AutoCAD document for which a DWF secondary file is to be created.
Return values
No direct return values. The Productstream Professional environment variable ARXErrorCode is filled with
the following values:
0: No errors creating the DWF file.
1: General error creating the DWF file
Remarks
• The corresponding AutoCAD application is launched if necessary (AutoCAD, Mechanical or MDT depen-
ding upon the configuration).
• The currently configured DWF options for creating the DWF file.
• The name and path of the DWF file to be created is determined by #(ContainerAutoDWF).
• The AutoCAD document is closed after the DWF file has been created.
 CAI interface 43

AIMDQuit
Brief description
Function for closing an AutoCAD application (AutoCAD, Mechanical or MDT, determined by the applica-
tion context).
Arguments
None
Return values
None. Messages or errors are written to the log file ac16log.err..
Remarks
The AutoCAD application is only shut down when no more documents are open.

AIMDRestore
Brief description
Switches the focus to the AutoCAD application (AutoCAD, Mechanical or MDT, determined by the appli-
cation context).
Arguments
None
Return values
None. Messages or errors are written to the log file ac16log.err.

AIMDUpdateTitleBlocks
Brief description
Function for updating the title block fields of an AutoCAD document using the defined values from
Productstream Professional. The attributes are assigned to the Productstream Professional fields in the INI file
amdtitle.ini (refer to the AutoCAD Integration manual).
Arguments
Arg1: <File>
The absolute file name of the AutoCAD document in which the title block fields are to be updated.
Return values
No direct return values. The Productstream Professional environment variable ARXErrorCode is filled with
the following values:
0: No errors updating the title block fields.
1: General error updating the title block fields.
2: No available title block fields managed by Productstream Professional.
3: File amdtitle.ini does not hold any definitions for a title block field
Messages or errors are also written to the log file ac16log.err.
Remarks
• The corresponding AutoCAD application is launched if necessary (AutoCAD, Mechanical or MDT depen-
ding upon the configuration).
• Write permission must be set for the document in order to run the function.
• The document is saved and closed after it has been updated.
 Productstream Professional Add-In interface 44

COMMAND
Brief description
Function for executing any AutoCAD commands in an AutoCAD application (AutoCAD, Mechanical or
MDT, determined by the application context).
Arguments
Arg1: <AutoCAD command>
Name of the AutoCAD command including all the parameters separated by space characters.
Caution!
The command and all the arguments must be enclosed in quotation marks when calling the command using
CAI_CALL.

Return values
None. Messages or errors are written to the log file ac16log.err.
Remarks
• Before this function can be run, it is necessary to launch an AutoCAD-based application and open a docu-
ment using Productstream Professional.
• If AutoCAD is not ready (e.g. because another function is still being performed), the user is asked whether
the active function is to be cancelled. The active function is always cancelled if COMMAND is called using
Productstream Professional Jobserver. A corresponding message is written to the log file ac16log.err.

Productstream Professional Add-In interface

The AutoCAD add-in interface is described in this section. A callback object is available for each document
that is opened using Productstream Professional. The following functions use this object to communicate with
Productstream Professional. This means that called procedures and queries are always run in the context of the
Productstream Professional record for the active document.

LISP and AutoCAD commands

• The following two commands are available in LISP programs. The function names of older versions of
Productstream Professional have been retained for reasons of compatibility. However, the functions are not
called via DDE, but use the saved callback object. The first two arguments (Service, Topic) are ignored.
• The AutoCAD command can be used, for example, to integrate the call for a Productstream Professional
procedure in an AutoCAD menu.

AIMDDDERequest (LISP command)

Brief description
Evaluates the given Productstream Professional expression. Corresponds to the CAI callback function Prep().
Arguments
Arg1: <Service>
Is ignored.
Arg2: <Topic>
Is ignored.
Arg3: <Productstream Professional expression>
Expression which is to be evaluated by Productstream Professional.
Return values
Evaluated value as a string.
Example
Specify Productstream Professional working directory.
(aimddderequest "" "" "$(WSPATH)")
 Productstream Professional Add-In interface 45

AIMDDDEExec (LISP command)

Brief description
Performs the given Productstream Professional function with the given arguments.
Arguments
Arg1: <Service>
Is ignored.
Arg2: <Topic>
Is ignored.
Arg3: <Productstream Professional function>
Name of an internal Productstream Professional function or a Productstream Professional procedure including
all arguments.
Return values
Error code from the Productstream Professional function.
Example
Productstream Professional function "Edit links".
(aimdddeexec "" "" "ShowElementDetails")

AIMDCMPCall (AutoCAD command)

Brief description
Performs the given Productstream Professional function with the given arguments.
Arguments
Arg1: <Name of the Productstream Professional procedure>
Name of an internal Productstream Professional function or procedure. Can be closed with <return> or a space
character.
Arg2: <Arguments for the procedure>
List of arguments, separated by space characters. Can only be closed with <return>.
Return values
Error code from the Productstream Professional function.
Example
Sample entry in an AutoCAD menu file *.mns:
BOM_to_COMPASS [Assign BOM file in Productstream Professional]^C^CAIMDCMPCALL NewExtern-
Bom "bom.xls"^M
 Introduction 46

Chapter 9 API Programming guide of the Inventor Integra-

tion in Productstream Professional
Introduction
Two programming interfaces are provided in Inventor-Integration. The functions of the CAI interface can be
called from Productstream Professional. The Productstream Professional Add-In interface can be used in In-
ventor.

CAI interface
The functions of the CAI interface are described in this section. These functions can be called using DBP pro-
cedures, in Productstream Professional Jobserver and from the Productstream Professional-Shell.
They usually require Autodesk Inventor. However, some of the functions only require Inventor Apprentice.
Inventor Apprentice can be used to read information out of Inventor documents, and then to edit them to a
limited extent. It is installed automatically with Inventor. Inventor Apprentice is also available free of charge
in conjunction with the product Autodesk Inventor Design Tracking.

Calling the CAI functions

General syntax for calling the CAI functions::
CAI_CALL class name> <function name> [<Arg1> <Arg2> <Arg3>]
The class name can be established using #(Appl:CAI_Name). However, an application context is required to
do so. This is not the case when using Productstream Professional Jobserver or the Productstream Professional-
Shell. The class name of the application Inventor is aimdinv.CAI_Call. When using the class name directly,
remember that some CAI functions require an application context (e.g. AIMDOpen to start Inventor).
For this reason, the procedure ApplCall is provided for Inventor. This ensures that an application context is
always available.
Inventor-specific syntax for calling the CAI functions:
ApplCall <function name> [<Arg1> <Arg2> <Arg3>]
The absolute file name of an Inventor document is required as an argument for almost all of the functions,
which means that the path, file name and the extension are given.

AIMDChangeReference
This function is for substituting an existing reference in an Inventor document with another one.
Arguments
Arg1: <File>
The absolute file name of the Inventor document in which the reference is to be substituted.
Arg2: <Old Reference>=<New Reference>
<Old Reference>: The absolute file name of the existing reference.
<New Reference>: The absolute file name of the new reference.
Return values
None. Messages or errors are written to the log file invlog.err.
Remarks
• The function is performed in Inventor Apprentice.
• Write permissions must be set for the document in Productstream Professional in order to perform the func-
tion.
• When the reference has been successfully substituted, the document is saved and the structure is synchroni-
zed.
 CAI interface 47

AIMDDeferUpdate
This function is used to set the Inventor property DeferUpdate for Inventor drawings (IDWs). This is practical
if a drawing is not to be updated as soon as it is opened.
Arguments
Arg1: <File>
The absolute file name of the Inventor derived drawing in which this property is to be set.
Arg2: 0 | 1
0: Deactivate DeferUpdate
1: Activate DeferUpdate
Return values
None
Remarks
• The function is performed in Inventor Apprentice.

AIMDGetProp
This function is used to read out the value of a specified Inventor property, and to set this value in a specified
Productstream Professional field.
Arguments
Arg1: <File>
The absolute file name of the Inventor document from which the property is to be read out.
Arg2: <Productstream Professional field>=<Inventor property>|
ENVIRONMENT.<Environment variable>=<Inventor-property>
<Productstream Professional field>: Name of the Productstream Professional field.
<Environment variable>: Name of the environment variable
<Inventor property> Designation of the Inventor property..
Return values
None. Messages or errors are written to the log file invlog.err.
Remarks
• The function is performed in Inventor Apprentice.
• The same syntax is used to specify the Productstream Professional field and the Inventor property as is used
for the definitions in the INI files aimdprop_xxx.ini.
Example
ApplCall AIMDGetProp "#(DOCNAME0" "SHORT_DESC =<Design Tracking Properties.Description>"

AIMDGetProperties
This function is used to read out the Inventor properties and to hand over the values to the Productstream
Professional fields as defined in the INI files aimdprop_xxx.ini .
Arguments
Arg1: <File>
The absolute file name of the Inventor document from which the properties are to be read out
Arg2: [<Section name>]
<Section Name>: Optional. The section name in the INI file. If this argument is empty, the section name Pro-
pertiesToCompass is used.
Return values
None. Messages or errors are written to the log file invlog.err.
Remarks
• The function is performed in Inventor Apprentice.
 CAI interface 48

AIMDInsert
This function is used to insert an Inventor document into the active Inventor application document.
Arguments
Arg1: <File>
The absolute file name of the Inventor document to be inserted.
Return values
None. Error messages are displayed on the screen where applicable.
Remarks
• This function requires an instance of Autodesk Inventor.
• User input is expected when this function is performed.

AIMDIsInstalled
This function is used to check whether Inventor Apprentice (or a specified version of it) has been installed.
Arguments
Arg1: [<Version Number>]
Optional. The Inventor version number.
Return values
0: Apprentice is not installed..
1: Inventor Apprentice is installed.

AIMDNew
This function is used to create an Inventor document.
Arguments
Arg1: <File>
The absolute file name of the new Inventor document.
Return values
None. Error messages are displayed on the screen where applicable.
Remarks
• This function requires an instance of Autodesk Inventor. Autodesk Inventor is launched if necessary.
• User input is expected when this function is performed.
• When the new document has been created, the properties are updated with the defined values from
Productstream Professional (dependent upon the settings in the configuration).
• In the case of new component documents, a sketch is generated according to the Inventor settings and then
activated if there are none in the template.

AIMDOpen
This function is used to open an Inventor document.
Arguments
Arg1: <File>
The absolute file name of the Inventor document to be opened.
Return values
None
Remarks
• This function requires an instance of Autodesk Inventor. Autodesk Inventor is launched if necessary.
• When the new document has been opened, the properties are updated with the defined values from
Productstream Professional (dependent upon the settings in the configuration).
 CAI interface 49

AIMDPackAndGo
This function is used to launch the Inventor Pack and Go tools.
Arguments
Arg1: <File>
The absolute file name of the Inventor document for which the Pack and Go tool is to be launched.
Return values
None
Remarks
• The function is performed in Inventor Apprentice.

AIMDPrint
This function is used to print an Inventor document.
Arguments
Arg1: <File>
The absolute file name of the Inventor document which is to be printed.
Arg2: <Configuration File>
The absolute file name of the configuration file. Refer to the Inventor Integration manual or aimdprint.ini, for
example, for details about the syntax used in the configuration file.
Return values
None
Remarks
• This function requires an instance of Autodesk Inventor. Autodesk Inventor is launched if necessary.
• When the new document has been opened, the properties are updated with the defined values from
Productstream Professional (dependent upon the settings in the configuration).
• When the document has been printed, it is closed without being saved.

AIMDPublishDWF
Function for creating the DWF secondary file for an Inventor document.
Arguments
Arg1: <File>
The absolute file name of the Inventor document for which a DWF secondary file is to be created.
Return values
None. Messages or errors are written to the log file invlog.err.
Remarks
• This function requires an instance of Autodesk Inventor. Autodesk Inventor is launched if necessary.
• When the new document is opened, the properties are updated with the defined values from Productstream
Professional (dependent upon the settings in the configuration).
• The currently configured DWF options for creating the DWF file.
• The name and path of the DWF file to be created is determined by #(ContainerAutoDWF).
• The Inventor document is closed after the DWF file has been created.
 CAI interface 50

AIMDQuit
This function is used to shut down Inventor.
Arguments
None
Return values
None
Remarks
• Autodesk Inventor is only shut down when no more documents are open.

AIMDSaveAs
This function is used to save an Inventor document in a different format.
Arguments
Arg1: <File>
The absolute file name of the Inventor document which is to be saved in a different format.
Arg2: <New File Name> | <Extension>
<New File Name>: The absolute file name (incl. the extension) of the new file.
<Extension>: Extension (file type: e.g. DWF) of the new file. In this case, the same file name is used. This
means that the new file is located next to the original file.
Return values
None. Messages or errors are written to the log file invlog.err.
Remarks
• This function requires an instance of Autodesk Inventor. Autodesk Inventor is launched if necessary.
• When the new document has been opened, the properties are updated with the defined values from
Productstream Professional (dependent upon the settings in the configuration).
• When the document has been saved, it is closed without the original document being saved.

AIMDSaveAsAttachment
This function is used to save an Inventor document in a different format and to automatically generate a
Productstream Professional secondary document for the new file.
Arguments
Arg1: <File>
The absolute file name of the Inventor document which is to be saved in a different format.
Arg2: <Extension>
Extension (file type: e.g. DWF) of the new file.
Arg3: 0 | 1
Optional. 0 if no value is given.
0: Generate a secondary document without the new record dialog window
1: Generate a secondary document with the new record dialog window
Return values
None. Messages or errors are written to the log file invlog.err.
Remarks
• This function requires an instance of Autodesk Inventor. Autodesk Inventor is launched if necessary.
• When the new document has been opened, the properties are updated with the defined values from
Productstream Professional (dependent upon the settings in the configuration).
• When the document has been saved, it is closed without the original document being saved.
 CAI interface 51

AIMDSyncStruct
This function is used to manually perform the structure synchronization.
Arguments
Arg1: <File>
The absolute file name of the Inventor document for which a structure synchronization is to be performed.
Return values
None. Messages or errors are written to the log file invlog.err.
Remarks
• The function is performed in Inventor Apprentice.

AIMDUpdateProps
This function is used to update the properties of an Inventor document using the defined values from
Productstream Professional. The Inventor properties are assigned to the Productstream Professional fields in
the document-specific INI files aimdprop_xxx.ini. They are updated using Inventor.
Arguments
Arg1: <File>
The absolute file name of the Inventor document for which the properties are to be updated.
Arg2: 1 | 2
1: Only the properties of the document are updated.
2: The properties of all the referenced documents are updated as well (recursively).
Return values
None
Remarks
• This function requires an instance of Autodesk Inventor. Autodesk Inventor is launched if necessary.
• Write permissions must be set for the document in Productstream Professional in order to perform the func-
tion.
• The document is saved after it has been updated (only if it has been edited) and then closed.

AIMDUpdateProps2
This function is used to update the properties of an Inventor document using the defined values from
Productstream Professional. The Inventor properties are assigned to the Productstream Professional fields in
the document-specific INI files aimdprop_xxx.ini (refer to the Inventor Integration manual). They are up-
dated using Inventor Apprentice.
Arguments
Arg1: <File>
The absolute file name of the Inventor document for which the properties are to be updated.
Arg2: 1 | 2
1: Only the properties of the document are updated.
2: The properties of all referenced documents are updated as well (recursively).
Return values
None
Remarks
• The function is performed in Inventor Apprentice.
• Write permissions must be set for the document in Productstream Professional in order to perform the func-
tion.
• The document is saved if it has been modified.
• Only the properties are updated, which means that changes in drawings are not applied accordingly in the
title field. In this case, it is necessary to use the function AIMDUpdateProps.
 Productstream Professional Add-In interface 52

Productstream Professional Add-In interface

The Add-In interface is described in this section. This is an ActiveX interface which can be run using a VBA
macro, for example.

AIMDAutomation class
An Inventor add-in (ApplicationAddIn class ) can provide a so-called 'automation interface' using the property
Automation.
In the case of the Productstream Professional Add-In, an object from the class AIMDAutomation is returned
using this property. The add-in interface can then be addressed using the object.
Procedure to obtain an object of this class:
• First of all, in the case of VBA for example, the AIMDAddIn X.x Type Library must be added to the project
using references (see table below).
• The Productstream Professional Add-In must be located using the list of loaded add-ins. It is more practical
to search for it using the unique CLSID instead of the add-in name (see table below).
• A class AIMDAutomation object can now be accessed using the add-in property Automation.
Type Library und CLSID
The following Type Libraries and CLSIDs are required for the different versions of Inventor:

Inventor Version Type Library CLSID

Autodesk Inventor 2008 AIMDAddIn 12.0 Type Library {FBDA760E-8918-418D-811D-372AF486C28E}
Autodesk Inventor 2009 AIMDAddIn 13.0 Type Library {8E5FBC18-B86C-49B6-B8D8-654FF82A5AD5}
Autodesk Inventor 2010 AIMDAddIn 14.0 Type Library {0DE69463-F721-4FBE-BD4E-6A393D1CD1A0}

Example:
…
Dim oAIMDAddIn As ApplicationAddIn
Dim oAIMDAutomation As AIMDAutomation
…
'Locate Productstream Professional Add-In
…
Set oAIMDAutomation = oAIMDAddIn.Automation

COMPASS Property
Provides an object of the AIMDCompass class.
Arguments
None
Return values
A class AIMDCompass object.

ExportBOM function
Performs the Productstream Professional Add-In function for exporting the bill of materials to a file, which
can then be recorded in Productstream Professional as a secondary document.
Arguments
None
Return values
None
Remarks
• This function is only available for drawings (IDWs).
• The Productstream Professional new record dialog window for the secondary document now opens.
 Productstream Professional Add-In interface 53

SendBOM function
Performs the Productstream Professional Add-In function for handing over the bill of materials to
Productstream Professional for the active document.
Arguments
None
Return values
None

SendProperties function
Performs the Productstream Professional Add-In function for handing over the Inventor properties to
Productstream Professional for the active document. The properties are handed over to the document-specific
INI file aimdprop_xxx.ini according to the definitions in the section PropertiesToCompass.
Arguments
None
Return values
None

SyncLocks function
Performs the Productstream Professional Add-In function for synchronizing the reservations with
Productstream Professional for the active document and all the referenced documents contained in it (recur-
sively).
Arguments
None
Return values
None

SyncStructure function
Performs the Productstream Professional Add-In function for synchronizing the structure with Productstream
Professional for the active document.
Arguments
None
Return values
None
 Productstream Professional Add-In interface 54

TransferComponents function
Performs the Productstream Professional Add-In function for handing over (unknown) components to
Productstream Professional for the active document.
Arguments
None
Return values
None
Remarks
• This function is only available for assemblies (IAMs).
• Productstream Professional new record dialog windows for the new components are opened.

UpdateProperties function
Performs the Productstream Professional Add-In function for updating the Inventor properties using
Productstream Professional values. The properties are updated according to the definitions in the document-
specific INI file aimdprop_xxx.ini.
Arguments
Recursive As Boolean
True - The properties of all the referenced documents are updated as well.
False - Only the properties of the active document are updated.
Return values
None

AIMDCompass class
Productstream Professional can be accessed using an object from this class.

Call function
Performs the given Productstream Professional function with the given arguments.
Arguments
Name As String
Name of an internal Productstream Professional function or procedure.
Arg As String
Arguments which are handed over to the function. Multiple arguments are separated by spaces.
Return values
Result As Long
Error code from the Productstream Professional function.
Remarks
The context used to perform this function does not necessarily have to be the same as the associated
Productstream Professional record of the active document. The context of the last document opened using
Productstream Professional is always used. This means that if the function is to refer to a particular
Productstream Professional element, this function is not suitable. The function CallEx should be used instead.
Example
Setting the Productstream Professional environment variables MYTEST:T
Dim oAIMDAutomation As AIMDAutomation
Acquire Productstream Professional Automation Object:
Dim result As Long
result = oAIMDAutomation.Compass.Call("___Environment", "MYTEST=hello")
 Productstream Professional Add-In interface 55

CallEx function
Executes the given Productstream Professional function with the given arguments. The function is performed
for the Productstream Professional element of the given Productstream Professional function or procedure.
Arguments
Aimkey As String
AIMKEY of the Productstream Professional element for which the function is being performed.
Name As String
Name of an internal Productstream Professional function or a Productstream Professional procedure.
Arg As String
Arguments which are handed over to the function. Multiple arguments are separated by spaces.
Return values
Result As Long
Error code from the Productstream Professional function.
Example
Opens the Productstream Professional window Edit links for the active document.
Dim oAIMDAutomation As AIMDAutomation
Acquire Productstream Professional Automation Object
Dim result As Long
Dim sAimkey As String
sAimkey = oAIMDAutomation.Compass.GetAIMKEY(ThisApplication.ActiveDocument)
result = oAIMDAutomation.Compass.CallEx(sAimkey, "ShowElementDetails", "")

GetAIMKEY function
Returns the AIMKEY of the given Inventor document.
Arguments
Document As Unknown
A Document type object is expected here.
Return values
Aimkey As String
The AIMKEY is returned if a Productstream Professional record exists for the document. Otherwise an empty
string is returned.
 Productstream Professional Add-In interface 56

Prepare function
Evaluates the given Productstream Professional expression.
Arguments
Expr As String
The expression which is to be evaluated by Productstream Professional.
Return values
Value As String
Evaluated value.
Remarks
The context used to evaluate values does not necessarily have to be the same as the associated Productstream
Professional record of the active document. The context of the last document opened using Productstream
Professional is always used. This means that if the expression for a particular Productstream Professional ele-
ment is to be evaluated, this function is not suitable. The function PrepareEx should be used instead.
Example
Specify Productstream Professional working directory.
Dim oAIMDAutomation As AIMDAutomation
Acquire Productstream Professional Automation Object
Dim sValue As String
sValue = oAIMDAutomation.Compass.Prepare("$(WSPATH)")

PrepareEx function
Evaluates the given Productstream Professional expression for the Productstream Professional element in the
given AIMKEY.
Arguments
Aimkey As String
AIMKEY of the Productstream Professional element for which the expression is to be evaluated.
Expr As String
The expression which is to be evaluated by Productstream Professional.
Return values
Value As String
Evaluated value.
Example
Specify the designation of the active document.
Dim oAIMDAutomation As AIMDAutomation
Acquire Productstream Professional Automation Object
Dim sValue As String
Dim sAimkey As String
sAimkey = oAIMDAutomation.Compass.GetAIMKEY(oApp.ActiveDocument)
sValue = oAIMDAutomation.Compass.PrepareEx(sAimkey, "#(SHORT_DESC)")
 DBP/COP compiler 57

Chapter 10 DBP/COP programming

DBP/COP compiler
The programs defined in DBP or COP files are not evaluated directly during runtime, but are translated into
a byte code prior to use by the DBP/COP compiler. The results are files with the extension ".DBQ" or
".COQ".
The compiler p2q_2000.exe is part of the SDK of Productstream Professional in the Compiler folder.
The translation is performed in two stages. The file is first processed by the pre-processor, and then by the
actual compiler.

Parameters
The compiler command line options described in the following sections are available in P2q_2000.
The text file infile is read and the file outfile is created. If the outfile is not defined, the same file name with
the extension ".dbq" or ".coq" is used.
Optional parameters always begin with '-'.

Format Description
-tTestoutput Test - an additional test output file is created. This is written to both stderr and outfile.
-s Silent - no information messages are returned.
-l[Listfile] Listfile - the location of the new list file can be defined. A temporary file is created unless stated
otherwise. If only -l is defined, the file name infile with the extension .lst is used. Otherwise the spe-
cified file is used.
[-oOutfile] Outfile - the location of the new output file can be defined. If this is not defined, the pre-processor
directive out file is used. Otherwise, the file name infile with the extension .dbq or .coq is used.
-denv=val The variable env is set to the value val in the symbol table of the pre-processor.

Example
p2q_2000.exe doceng.dbp –s –l "–o..\etc\cmpcad.dbq"
 Structure of the DBP and COP files 58

Structure of the DBP and COP files

DBP files
The DBP file is a simple text file which can contain an arbitrary text. Only texts with special flags are handled.
All other text is ignored.
Special flags are pre-processor directives and program element flags.

COP files
The COP file is a simple text file which can contain an arbitrary text. Only texts with special flags are handled.
All other text is ignored.
Special flags are pre-processor directives and program element flags.
COP files are named and loaded in the configuration of the Productstream Professional object model analog
to DBP files. However, the conditions of these files do not relate to the object model, but are always managed
in a global list.
Search sequence
If the condition in a DBP file is used, the DBP file is searched first to ascertain whether a condition of this
name has been defined (condition Name=…). If this is not the case, a condition of this name is sought in the
global list of conditions from the COP files.
Program elements
When the file has been processed by the pre-processor, the contents are processed. The entire contents of the
file are treated as an expression. Comments must therefore always be given in parentheses with </*> and <*/>.
There are no special elements. The following model is recognized:
<ConditionName> = <ConditionExpression>;
The condition expression can have a length of several lines. The end of a definition is indicated by the closing
semi-colon.
Example
/* Conditions for the Workflow */
/* */
Part_Workflow = isEtype("AIM.PART");
SkipToBeChecked = eq("1","#(ETYPE SkipToBeChecked)");
Part_Workflow_Small = Part_Workflow && SkipToBeChecked;
Part_Workflow_Large = Part_Workflow && !SkipToBeChecked;

DocEng_Workflow = isEtype("AIM.DOC.ENG") ;
islocal = comp("DL","@(FILE_TYPE:tA)");
/* islocal is also used in status.dbp ! */
 Preprozessor directives 59

Preprozessor directives
Pre-processor directives always have the following structure:
• #<Identifier>
10 identifiers are used:
• #include
• #define
• #undef
• #ifdef
• #else
• #endif
• #rem
• #comment
• #echo
• #break

Include
A file is inserted here.
Syntax
# include <File name>
# include "File name"
The specified file is inserted here. The result can be controlled in the list file. The path can be defined together
with the file. If it is not found directly, the value of the symbol INCLUDE is used as the search path. The
symbol can be set in the DBP file.
Note
If multiple definitions of INCLUDE are defined, all the given paths are searched.
Example
...
#define INCLUDE=../allgdbp
#define INCLUDE=./subdbps
#include "sonderfunc.inc"
...
 Preprozessor directives 60

Define
Variables are defined solely for the pre-processor.
Syntax
#define <Variables>
#define <Variables>=<Values>
Value is treated as a character string. The variables are always globally visible, and they can be directly used as
arguments for the control word ifdef. They are also replaced by the value anywhere in the text if they are de-
signated as follows:
\{VariableName}
This string is replaced by <Value> in the outfile. Value is the character string which begins directly after the
"=" sign and finishes at the end of the line.
Note
The following variables are pre-defined by the pre-processor:
\{__DBPFILE__}: File name without extension of top-level source file
\{__DBPEXT__}: Extension of toplevel source file
\{__DBPNAME__}: Full Pathname of toplevel source file
\{__DBPPATH__}: Full Path without Filename of toplevel source file (no / at end)
\{__FILE__}: Filename without Extension of current source file (included file)
\{__EXT__}: Extension of current source file (included file)
\{__NAME__}: Full Pathname of current source file (included file)
\{__PATH__}: Full Path without Filename of current source file (included file) (no / at end)
Examples
...
# define MitCAD
# define _INSERT=insert
# define OneLine = this line begins with a space !
...
The two lines in infile
the command is "\{_INSERT}"
OneLine has the value : "\{OneLine}"
turn in outfile into:
...
the command is "insert"
OneLine has the value : " this line begins with a space !"
...

Undef
A variable is deleted from the list of all internal variables.
Syntax
#undef <Variable>
The given variable is deleted from the list of all internal variables.
 Preprozessor directives 61

Ifdef, Else, Endif

These control words are used just as they are usually used in programming languages.
Syntax
#ifdef <Variable>
#else
#endif
Up to 31 "IF levels" are allowed. If and endif must always be present in pairs. A warning is given if there is an
imbalance in a file. If there is an imbalance at the end of infile, an error message is issued and the program is
terminated.
If multiple variables have been specified, only one of them needs to be defined (OR link). Whether the variable
has a value or not is irrelevant. It just needs to be defined. Texts after else and endif are ignored.
Example
#define ABC=a common line
# ifdef ABC
# define ABCalt=\{ABC}
# endif
#define ABC=is used differently here !
This line is copied to outfile first !
#ifdef ABC
\{ABC}
#endif
#ifdef ABCalt
# define ABC=\{ABCalt}
# undef ABCalt
#else
# undef ABC
#endif

TEST has the value: "\{TEST}"

ABC has the value: "\{ABC}"
#undef ABC
ABC has the value: "\{ABC}" <--- produces an error message at stderr !
The result in outfile is as follows:
This line is copied to outfile first !
is used differently here !
TEST has the value: ""
ABC has the value: "a common line"
ABC has the value: ""

Rem, Comment
Single-line comments can be inserted. This is only necessary in a function (between procedure and endproc)..
Syntax
#rem <Comment>
#comment <Comment>
<Comment> is not copied to outfile. Otherwise, this line is ignored.

Echo
Text is returned in outfile.
Syntax
#echo <Text>
<Text> is returned to stdout. Text is not returned if the option -s (silent) is used. The text is prefixed with the
file name and line.
 Program elements 62

Break
The compiler process terminates with a message.
Syntax
The following message:
"<FileName>" break at Line <nn> : <Text>
is returned at stderr. The program is terminated.

Program elements
When the file has been processed by the pre-processor, the contents are processed line by line. Normally, all
the lines are ignored. A line is only subjected to special treatment if one of the keywords is found at the begin-
ning of it. The keywords are:
condition
public
procedure
Only spaces or tab characters may be used between the beginning of the line and the keyword, which must be
followed by a space or tab character. Keywords are always lower-case, which identifies them as such. The asso-
ciated definitions can have a length of several lines. The end of the definition is stated in the respective descrip-
tions.

Public
The public definition gives function implementations a public name, and are provided for use in menus, tool-
bars, function keys and other call methods.
Syntax
public <PublicName> [(<Conditions>)],<Function name> [<Parameter>]
<Conditions> = [<Static>] [; [<Dynamic>] [; [<State>] [; [<Rights>] ] ] ]
< PublicName>
Function name under which this method can be addressed in the object model.
<FunctionName>
Name of another PublicFunction or a Procedure. This indicates how the method is actually implemented.
<Parameter>
The specified parameters are only handed over to the public function or procedure which is to be called if no
parameters were handed over when <PublicName> was called.
<Static>
The condition is referred to as a static condition as it is evaluated once when Productstream Professional is
launched. If FALSE is returned by the condition, the respective option is not shown in the menu or toolbar.
<Dynamic>
The condition is referred to as a dynamic condition as it is re-evaluated each time the highlight bar is reposi-
tioned. If FALSE is returned by the condition, the respective option is disabled in the menu or toolbar, but is
grayed out and remains visible.
<Status>
This condition can relate to the object. In menus, the option has a check mark if TRUE is returned by the
condition. In a toolbar (toggle button), this is shown pressed down if TRUE is returned by the condition.
 Program elements 63

<Rights>
The function can only be performed if the rights listed below are given. 4 letters can be used to define these
rights:
R: Read rights must have been granted
W: Write rights must have been granted
D: Delete rights must have been granted
C: The right to create new records must have been granted
X: This function cannot be executed in Productstream Professional Webserver,
e.g. if a function that is not mentioned in the chapter “Executable internal functions for Productstream
Professional Webserver” is used there.
Example
public MyFunction(TRUE;isAdministrator;;RW),proc_MyFunction

Procedure
Procedures are identified by the procedure name and are only visible in a DBP file. Before a procedure can be
called, it must either be made known to the "outside world" using a public definition, or be called in another
procedure in the same file.
Syntax
procedure <ProcedureName>
<StatementListe>
endproc
The keyword endproc must be lower-case like procedure and stand at the beginning of the line. procedure and
<ProcedureName> must stand alone in the same line. Everything in between complies with the syntax used in
procedures.
Parameters
<StatementListe>
The <StatementList> is a series of several <Statements>:
<Statement_1>
<Statement_2>
…
<Statement_N>

<Statement>
The different statement types listed below can be used (see Statements)
• Command statement
• Compound statement
• Selection statement
• Loop statement
• Return statement
 Program elements 64

Command statement
<Command> ;
<Command> ();
<Command> ( <Parameter> );
<Command> ()<Text>;
<Command> ( <Parameter> )<Text>;
Parameters
<Command>
The following functions can be called as <Command>:
• Public function,
• Internal Productstream Professional function
• A procedure defined in the same DBP file
The semi-colon at the end of the command statement is always expected and closes this statement.
The command name is not case-sensitive!
<Parameter>
The parameter may contain parentheses. Opening and closing parentheses must be balanced, or they must be
given in quotation marks. <Parameter> can be empty. The parentheses are not required if <Text> does not
follow.
<Text>
The text must be quoted if it contains a semi-colon.
Example
Commands as statements:
___Environment( New=$(old:|+);#(PATH0:|+) );
___ChangeStatus( $(NewStatus) ) select new status for #IDENT;
___Shell( read(envvar) redefine "envvar":)

Compound statement
A compound statement combines a series of 1 or more statements in braces {...}. It is not closed by a semi-
colon. Only the braces are required.
{ <StatementList> }
<StatementList>
List of one or more statements (see Command Statement)

Selection Statement (if, else)

The selection statements if and else (lower-case), just as in other programming languages, can be used to form
conditional branch structures. The branch structure condition can be an entire condition expression (and not
just a condition name).
Syntax
if ( <condition> ) <TRUEStatement> [ else <FALSEStatement2> ]
Example
When the conditions have been fulfilled, the document must be opened otherwise the following message is
displayed:
if( exist( "#DOCNAME0" ) && StatusAllowChanges )
OpenDoc0();
else
___Shell ( read()Error );
 Program elements 65

Loop statement (while, until)

while ( <condition> ) <TRUEStatement>
while (lower-case) is a head loop, i.e. the statements it contains always continue to be executed as long as the
condition is TRUE. condition can be an entire condition expression (and not just a condition name).
until ( <condition> ) <TRUEStatement>
until (lower-case) is a foot loop, i.e. the statements it contains are only executed once. The statement then con-
tinues to be executed until the condition is TRUE.

Return statement
The following statements must all be lower-case.
return[( <Errorlevel>) ];
return immediately exits the current procedure. The variable Errorlevel is assigned the specified value by defi-
ning errorlevel in return( <errorlevel> );. Only integer values are allowed. If only return; is used, the variable
remains unchanged. The variable can be evaluated in the calling routine
Example
procedure BspProc
Proc1();
Proc2();
if( ge("$ErrorLevel","1") )
return;
/* continue only if $Errorlevel <= 0 is */
Proc3();
Proc4();
endproc

exit
exit terminates the entire procedure call at all levels right up to the highest calling public function. No further
statements are executed. The variable Errorlevel is set to the value 255!
break
break cancels the next loop statement. The procedure continues with the statement which follows the cancelled
loop statement. break only takes effect within a procedure. A break outside of a statement has no effect.
Example
while( COND1 )
{
DoForEach();
if( COND2 )
break;
}
If COND2 is TRUE, the procedure continues with the statement CMD().
 Program elements 66

continue
continue causes the procedure to branch to the next loop statement. The loop condition is then re-evaluated
and the loop is re-run or the procedure moves to the next statement accordingly. continue only takes effect
within a procedure. A continue outside of a loop statement has no effect.
while( cond1 )
{
DoForEach1();
if( COND2 )
continue;
DoForEach2();
}
cmd();
If cond2 is true, DoForEach2 is no longer executed. Instead, the procedure immediately continues by checking
cond1. Depending upon the result, the loop is continued or the procedure branches to the statement cmd().

Comments
Within a procedure, comments begin with two successive characters </*> and end with the character <*/>.

Condition (DBP file)

The condition definition gives condition implementations a name and can then be used in public definitions
and procedures..
condition <ConditionName>=<ConditionExpression>;
<ConditionName>
A unique identifier for the defined condition. Condition names are case-sensitive! Therefore, „istADS“ and
„IstAds“ are two independent condition names.
<ConditionExpression>
Conditions are defined in a condition expression. To do this, Productstream Professional provides numerous
condition functions, which can be linked with operators. Previously defined conditions can be used with logi-
cal operators in condition expressions.
 Program elements 67

Condition (COP file)

The condition definition gives condition implementations a name and can then be used in public definitions
and procedures.
<ConditionName> =<ConditionExpression>;
ConditionExpression = LogicalOR
= ( condition expression )
LogicalOR = Comparison [ ANDOperator LogicalAND]
OROperator = "||"
LogicalAND = Comparison [ ANDOperator LogicalAND]
ANDOperator = "&&"
Comparison = Sum [ComparisonOperator Sum]
ComparisonOperator = "==", "!=", "<=", ">=", ">", "<"
Sum = Product [ OperatorPlusMinus Sum]
OperatorPlusMinus = "+", "-"
Product = [ OperatorUnaer ] PostfixExpr [ OperatorProduct Product ]
OperatorUnary = "+", "-", "!"
OperatorProduct = "*", "/", "%"
PostfixExpr = FunctionName ( Parameter )
= "CharacterString"
= TRUE
= FALSE
= Integer value
= Double value
FunctionName = < character string from A-Z,a-z,_,0-9 first character from A-Z,a-z,_ >
Parameter = ArgumentExpression [ , ArgumentExpression … ]
ArgumentExpression = Argument expression
 Operators 68

Operators
When using operators, it must be noted that a && link has a higher priority then ||; it may be necessary to use
parentheses to achieve the required interpretation.
||: OR
&&: AND
!: NOT
These operators can be used to combine condition names and Boolean condition functions to form an expres-
sion. Condition functions are described in the chapter "Substitution and condition functions".
Example
A condition definition in the COP file:
condition FILE0=exist(#PATH0#FILEN.#EXT0);
condition Edit0File=FILE0 && (comp(#EDIT,$USERID)
|| comp("GROUP1",$GRPID)
|| comp($USERID,"MILLER") );
condition isCanAll= isdefined(USERID)
&& comp("supervisor","$USERID);
condition EditAllowed=FILE0 && (Edit0File||isCanAll);
Usage of conditions within the DBP file:
Condition Testcond3 = !comp( $(Testvar3)", Teststring3")
procedure CMP-Test_Proc
___Environment ( Testvar3 = 1);
___Environment ( Teststring3 = 0);
while(!comp( $(Testvar1)", Teststring1") && comp( $(Testvar2)", Teststring2"))
{
___Shell ( read() Now executing the while loop!);
___AskQ ("Do you want to continue the loop?" ans Yes" No" );
if ( eq ( $ans", 0")) ;/*Yes*/
else if (eq ( $ans", 0"))/*No*/
{
___Environment ( Teststring3 = 1);
}
if (Testcond3)
{
___Shell ( read() Now cancelling the while loop!);
break;
}
}
endproc
The "while" loop is executed as long as the condition expression given in parentheses returns TRUE. Each time
the loop is executed, a dialog window is displayed in which it can be cancelled. If No is selected, the condition
Testcond3 defined outside of the procedure = TRUE and the "while" loop is cancelled with a break within the
if branch.
Note
i ! used in procedures to control the process, the compiler translates these into an internal
If condition expressions are
condition name "?P2Q<ID>", whereby <ID> is a 4-figure number.
 69

Chapter 11 Formats
Expressions, field values or variables can be formatted as soon as they are used. The variable, field name or
expression must be placed in parentheses to be formatted. Multiple formats are allowed and are listed in se-
quence without spaces.
Only the changed value of the formatted field or variable is returned. The value itself is not changed.

Syntax
#(<FieldName or Function> : <Format> )
@(<FieldName or Function> : <Format> )
$(<Variable> : <Format> )

Format Description Example

-<Default> Defines the default entry if the variable has no value or is not definied. Format valid $(VAR:-default)
only with Variables.
/- All the directory separators are replaced by a slash in this field or variable. This for- c: \aa/xx\
mat ensures there is no directory separators at the end. results in
c:/aa/xx
/+ All the directory separators are replaced by a slash in this field or variable. This for- c: \aa/xx
mat ensures a directory separators at the end. results in
c:/aa/xx/
\- All the directory separators are replaced by a backslash in this field or variable. This c: \aa/xx\
format ensures there is no directory separators at the end. results in
c: \aa\xx
\+ All the directory separators are replaced by a backslash in this field or variable. This c: \aa/xx
format ensures a directory separators at the end. results in
c: \aa\xx\
|- All the directory separators are replaced by the operating system separator in this c: \aa/xx\
field or variable. This format ensures there is no directory separators at the end. results in
c: \aa\xx
|+ All the directory separators are replaced by the operating system separator in this c: \aa/xx/
field or variable. This format ensures a directory separators at the end. results in
c: \aa\xx\
A The value of the field or variable is returned in upper-case letters. <UPPER CASE>
a The value of the field or variable is returned in lower-case letters. <lower case>
B The value of the field or variable is returned in upper-case letters. (Windows Cha- <UPPER CASE>
racter Set)
b The value of the field or variable is returned in lower-case letters. (Windows Cha- <lower case>
racter Set)
D10 A date is returned in 10-character format. DD.MM.YYYY
D8 A date is returned in 8-character format. DD.MM.YY
T8 A time value is returned in 8-character format. HH:MM:SS
T5 A time is returned in 5-character format. HH:MM
e Only the extension is returned from a field or variable containing the path, file <Ext>
name and extension.
F Only the file name is returned from a field or variable containing the path, file <File>
name and extension.
f Only file name an extension is returned from a field or variable containing the <File>.<Ext>
path, file name and extension.
P Only the path and file name are returned from a field or variable containing the <Path>\<File>
path, file name and extension.
p Only the path with the closing directory separator is returned from a field or vari- <Path>\
able containing the path, file name and extension.
 70

Format Description Example

Q RETURN is changed into character string \r\n
r All the spaces on the right are trimmed.
l All the spaces on the left are trimmed.
t All the spaces on the left and right are trimmed.
s:<Start>.<Length> Only the part string from the position <Start> in the length <Length> is to be
returned from the field or variable.
n[0]<L>.<D> Format for numerical Fields and Variables. The number gets the length <L> inclu- Var=1.966
ding <D> decimal characters. “$(Var:n07.2)“
If necessary the number is rounded to fit <D> decimals and <L> is enlagered if the results in
number is too big. “0001.97“t
If <L> has a leading '0' chartacter, the number is filled with left-hand Zeros, other-
wise with space characters
v0 The value of the field or variable is split into space separated strings Strings in par-
entheses (), inverted commas '...' or quotation marks "..." are interpreted as conti-
guous. The Return value is the number of these substrings.
v<n> The value of the field or variable is split into space separated strings Strings in par- Var=AAA BBB
or entheses (), inverted commas '...' or quotation marks "..." are interpreted as conti- $(Var:v0)
guous. results in 2
V<n>
The returnvalue is the number <n> substrings. $(Var:v2)
Format v<n> removes surrounding inverted commas or quotation marks, format results in
V<n> does not. BBB
++ The variable is incremented by 1. 0 ◊ +1
-- The variable is decremented by 1. +1 ◊ 0
 Operators 71

Chapter 12 Expressions and condition operators

Operators
When using operators, it must be noted that a && link has a higher priority than ||. It may be necessary to
use parentheses to achieve the required interpretation.
|| = Or
&& = And
! = Not
The new functions which do not exclusively return TRUE or FALSE can also be used in loops.
Examples
If loop where the status is Released or the group Administrator:
If ( comp ("00003","#(STATUSKEY)") || wcomp("ADMINISTRATORS","$(ALL_GROUPS)") )
{
<Sourcecode: TRUE>
}
If loop; whether Field1 and Field2 exist:
If ( fieldexist ("FELD1") || fieldexist ("FELD2") )
{
<Sourcecode: TRUE>
}
While loop; as long as fields are found, they are read out to a text file:
___Environment ( Num=0 );
while ( fieldexist( INT("$Num") ) )
{
___Shell ( wr(fields.txt:a)@(=field( INT("$Num"))) @(=fieldtype ( INT("$Num"))) );
___Environment ( Num=$(Num:++) );
}

General
#( <FieldName or Function> )
Returns the value of a field or a function. The case used for the field names must be compliant (always UPPER-
CASE by default).
Example
IDENT query using a field length of 15:
"@(IDENT)"= "ENG-0000001 "
"@(IDENT:t)"= "ENG-0000001"
"#(IDENT)"= "ENG-0000001"

@( <FieldName or Function> )
Same as '#'. However, here all the field contents are returned, and are therefore complemented with spaces if
necessary.
 General 72

$( <Variable> )
All expressions including a $ sign are variables. These have no relationship to the actual context. Variable values
never end with a space. These are trimmed automatically.
The following variables are available by default when Productstream Professional is launched:
ALL_GROUPS: All the assigned groups of the current user
ACTIVE_GROUP: Active group of the current user
FULL_USERNAME: Full name of the current user
USERID: Login name of the current user
All variables from COMPASS.INI [Path]>
<All environment variables of the operating system>
(See also: ___CmpUtility WriteSyspar)

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

Version 5.3.0
The character string between the inner round parentheses is substituted as an expression.
The general syntax used previously was:
#(<Expression> [<Affix>] [:<Format>] )
A new, slightly differently phrased handle is now used: (...). The syntax in this case is now:
#(( <Expression> ) [<SubstitutionDepth>] [:<Format>] )
@ or $ together with the appropriate characteristics can always be used in place of #. In particular: $((...)) only
substitutes $ variables, but not # or @ variables.
Parameters
<SubstitutionDepth>
A number between 1 and 16 is given here. This represents the maximum number of substitutions performed
with the respective result returned the expression. 16 is entered by default unless given otherwise. The expres-
sion is not interpreted if it no longer contains the character #, @ or $, or if it has not changed as a result of the
substitution.
<Format>
The same format definition used for all expressions applies.
Example
An object contains the following fields::
DES = designation for the number #IDENT
IDENT=47110815
The following substitutions are performed on this object:
"#(DES)" returns"Designation for the number #IDENT"
"#((#(DES)))"returns"Designation for the number 47110815"
 General 73

#(= <Expression with FieldNames> )

All functions which return field or variable values can be given here. These have already been described in the
documentation.
Expressions can also be arithmetic operations. The supported operations are:
+: Addition
-: Subtraction
*: Multiplication
/: Division
Example
Addition of fixed values:
#(= 2 + 5)
Addition of variables:
___Environment ( Number1 = 5 );
___Environment ( Number2 = 2 );
#(= strprep("$(Number1)") + strprep("$(Number2)") )

#(== <Conditions> )
Conditions which are interpreted immediately can be given here. This allows the result of a condition to be
saved in a variable.
Example
Information about whether a primary document (#DOCNAME0) exists is saved in a variable.
___Environment ( DocExist=#(== docexist(0) ) );

#(Tx.....)
Text variables
This form can be used as soon as a string is given. If a language identifier is used in the variable LangPostFix
(configurable in COMPASS.INI), the corresponding language text files are loaded from the different directo-
ries.
If multiple languages are to be used, the appropriate files containing valid line IDs must be provided in each
directory.
All texts in Productstream Professional are language-neutral. This means that variables which are interpreted
during runtime are used instead of definitive texts. These variables are stored in text files in the directory <Prg-
Path>\etc\txt.<LangPostFix> (<PrgPath>=server directory; <LangPostFix>=language).
Parameters
#Tx<TexFile><LineID>
#Tx: Fixed handle
<TexFile>: File name, four characters (extension is always *.tex)
<LineID>: Number at the beginning of the line (1 to 3 figures)
These are ASCII files, and the lines are numbered from 1-999. Only one line may be used for each variable.
Each line begins with a number.
Example
Content of the myFi.tex file in the <PrgPath>\etc\txt.<LangPostFix> folder:
000 Version 1.0.1
002 Folder name
003 Logged on as: "$(USERID)" on "#(SYSDATE:D10)"
Usage and output of text
#Txmyfi000 = Version 1.0.1
#Txmyfi002 = Folder name
#Txmyfi003 = Logged on as: "Administrator" on "05.07.2004"
 Functions 74

#( Symbol:<SymbolName> )
Symbols can be defined for the record buffer of the current context. They are handled as virtual fields, allowing
freely defined virtual fields to be appended to a record buffer. They are addressed just like normal fields. It is
only necessary to give the key word Symbol: as well. Symbols do not have any effect on operations performed
directly on the database, either.
Example
Redefining a symbol for a current record buffer:
___Recordbuffer ( set __CURRENT__ Symbol:myFunc="New record" );
Reading out a symbol from a current record buffer:
___Recordbuffer ( call __CURRENT__ ___Environment Func=#(Symbol:myFunc) );

#( RecID [:<Format>] )
In Productstream Professional, RecID is used to unambiguously identify an object within a Folder object. This
internal number only applies during the Productstream Professional runtime.

@(\n)
Contains an ENTER (carriage return). Is used for texts in messages and dialogs.

$(_DS)
Contains a backslash ("\"). Is used for texts in messages and dialogs, as well as when compiling directories.

Functions
#( call <Function> [<Parameter>] [:<Format>] )
This function starts <Function> and returns the value last saved in <Function> using ___ReturnString. The
parameters given here are substituted for the current context and passed on to the <Function>. The product
can be formatted using<Format>.
Example
Calling a function which builds up a Where clause according to a switch set by the user:
Public myWhere,AIM_myWhere
Procedure AIM_myWhere
If ( !empty("$(arg)") )
{
___ReturnString ( ENTITY_TYPE='AIM.DOC.ENG' AND CATEGORY='$(arg)');
}
Else
{
___ReturnString ( ENTITY_TYPE='AIM.DOC.ENG' );
}
Endproc
The following expressions can now be used in this context:
#(call myWhere Buch)
−> ENTITY_TYPE='AIM.DOC.ENG' AND CATEGORY='$(arg)'
#(call myWhere)
−> ENTITY_TYPE='AIM.DOC.ENG'
 Functions 75

#( KeyGen <Action> )
Generates keys.
An unique value is generated for the field given. The colon does not have to be entered. Quotation marks
("..."), as well as single inverted commas ('...') can be used for the values.
Syntax
#( KeyGen[:]<GenField>="<StartValue>"[,<GenType>]
[<Field>="<Value1>"][<Field2>="<Value2>"])

Parameters
<GenField>
A unique value is sought for the field and returned.
<StartValue>
<StartValue> can be used to define the number to be started with. If the start value is already unambiguous, it
is returned again.
[, <GenType>]
How a key is generated can be influenced using the parameter <GenType>. Valid values are:
A: Upper-case letters only from A-Z
a: Letters from a-z only
X: Only upper-case letters from A-Z and numbers from 0-9
x: All letters from a-z and numbers from 0-9 (= default value unless stated otherwise)
0: Numbers from 0-9 only
D: Only figures from 0-9 (is used for the variable generation of the incrementation; syntax see below)
Specifying the generating type defines how the incrementation continues. The start value is therefore not con-
verted as an overall value.
Example
StartValue = ENG-0000001
GenType = 0
Generated value = ENG-0000012 ("ENG-..." is retained)
[<Field1>="<Value1>"]
If <Field1> is given as well, the unambiguity is determined using the generating field <GenField> and
<Field1>.
[<Field2>="<Value2>"]
If <Field2> is given as well, the unambiguity is determined using the generating field <GenField> and <Field1>
and <Field2>.
Note
• Keys can be generated usingia !maximum of 3 fields (generating field and 2 offset fields). Temporary fields are necessary if a key
has to be generated using more than 3 fields.
• Errors are documented in the file errlog.err with the error number 02082.
• The function #(FileNameGen) can be used for the file name (field FILE_NAME).
 Functions 76

Example
Generating a document number taking into account the page (new field PAGE):
#(KeyGen IDENT=#(IDENT),0 BLATT="00") )

Variable generation of the incrementation

The value D has been added to the parameter <GenTyp> for the variable generation of the incrementation.
The following syntax is used for this type:
D[0][:Offset[:Length[:Increment]]]
0 Optional and describes whether leading zeros are to be retained (0) or omitted (no entry).
This is only of significance with purely numerical fields, and not with classified fields. In the
case of classified fields, the value together with the length represent the field that is to be
filled. Missing significant positions are always padded with zeros (left padding)
Call options:
: Leading zeros are neither taken into consideration nor returned
0: Leading zeros are returned up to the defined length
Offset Starting point (index) of the prefix. Index is a so-called 0 index, i.e. it starts with 0.
Length Length of the variable numerical sub-character string that is to be generated
Increment Incrementation for the generation (only positive integer values are allowed)

Examples:
D Generation over the entire field without leading zeros and an incrementation of 1.
Internal: :0:0:0 Positions are carried over and expanded if necessary.
D0 Generation over the entire field with leading zeros and an incrementation of 1. The
Internal: 0:0:0:0 entire field is padded with leading zeros if any are missing.
D0:3 Generation over the entire field from position 4 to the end of the field with leading
Internal 0:3:0:0 zeros and an incrementation of 1.
D0:4:6 Generation over the entire field from position 5 to length 6 with leading zeros and an
Internal 0:4:6:0 incrementation of 1.
D0:4:4:10 Generation over the entire field from position 5 to length 4 with leading zeros and an
Internal 0:4:4:10 incrementation of 10.

From these examples, it can be seen that a key can only be generated without leading zeros in the first example
with a purely numerical value as it is not possible to define how positions are expanded dynamically. Here, the
numerical sub-string must always be completely filled, as otherwise there will be a conflict with the length.
Example of a function call:
NewElementKeyGen= "IDENT=#(KeyGen:IDENT='DOC-00000',D0:4:5:10 REVISION='A')" […]
The next number is generated from position 4 over 5 characters with an incrementation of 10. The next value
would therefore be DOC-00010.

#(GetMaxKey…)
Optimized performance for generating keys
The DBP function #(GetMaxKey…) for generating keys #(KeyGen…) allows an optimized value to be deter-
mined when generating keys. The search for an optimized value supports classified keys (with prefix/postfix).
This is controlled using the parameters Offset and Length.
General Syntax for generating keys:
#(KeyGen[:] <GenField>="<Start value>"[,<GenType>] [<Field>="<Value1>"]
[<Field2>="<Value2>"])

Syntax for the determination of the ideal start value:

#(GetMaxKey Fieldname="<Value>" "<Offset>" "<Length>")

Syntax for the combined call:

#(KeyGen[:] <GenField>=#(GetMaxKey Fieldname="<Value>" "<Offset>" "<Length>")[…]
 Functions 77

ObligatoryField
Obligatory fields (mandatory fields) can be defined in the configuration of the list view and the datasheet. This
document describes the procedures and whether the attribute ObligatoryField was filled in or not at the time
the check was run.
The function ObligatoryFieldViolation() is always called by the ListView object or the DataSheetView object
if the user leaves a field defined as a mandatory field empty after editing it. 3 arguments are handed over to the
function:
• CaptionName: this value is used from the configuration
• FieldName: field name of the field left empty after editing.
• OldValue: the value in the field prior to editing. The field can also have been empty if the attribute Obliga-
toryField was only changed subsequently.

Caution!
This function must not change the program's input focus! The only action which can be performed is to write
error messages to a file or in the status bar. A message dialog may not be used either, as this would also change
the input focus!

Chkobligatory() function
This function can be called in the in Save function of the New record dialog window. It triggers a check of all
the editable fields in the dialog to determine whether there have been any violations of the ObligatoryField
condition. If no violation is detected, the value 0 is returned instead of >0.
If this check does detect a violation of the ObligatoryField condition, the function ObligatoryFieldViolation()
is called within the function chkobligatory(). This enables the field name (or other permitted information) to
be stored in global variables following the interpretation of chkobligatory() as well allowing an error message
to be issued.
Example
If ( chkobligatory() > 0 )
{
___Shell ( read()#TxMSG1610 );
Return ( 100 );
}
...
Public ObligatoryFieldViolation, AIM_ObligatoryFieldViolation
Procedure AIM_ObligatoryFieldViolation
___Environment ( OFV_Caption=$(arg:v1) );
___Environment ( OFV_Field=$(arg:v2) );
___Environment ( OFV_OldValue=$(arg:v3) );
___StatusBar ( #TxSTBA200 );
Endproc
 Strings 78

Strings
comp ( "<String1>" , "<String2>" )
String comparison: The result is TRUE if the two specified strings within a comparison length are identical.
The comparison length is the length of <String1>. All the other characters in <String 2> are not compared.
Important: The strings are case-sensitive!
Caution!
The condition is always TRUE if <String1> is empty.

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

String comparison of the length: The result is TRUE if <String1> is identical to <String2> regarding the length
<Length> of the strings

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

Part string comparison: The result is TRUE if <String1> is contained in <String2>. The strings are funda-
mentally case-sensitive. Lower-case letters in <String1> are an exception. They are regarded as identical to the
upper and lower-case letters in <String2>.

empty ( "<String>" )
String comparison: The result is TRUE if <String> is empty, i.e. the length is either 0 or is made up of spaces
only.

isdefined ( "<String>" )
The result is TRUE if <String> is an environment variable which is not empty.

isknown ( "<String>" )
The result is TRUE if <String> is a known condition name.

eq ( "<Number1>" , "<Number2>" )
Comparison of two numerical values: The result is TRUE if <Number1> is equal to <Number2>.

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

Like eq, but an ASCII comparison is performed. The given values are compared on the basis of their ASCII
codes, therefore making comparisons of letters also possible, e.g. "a" = "a".

le ( "<Number1>" , "<Number2>" )
Comparison of two numerical values: The result is TRUE if <Number1> <= <Number2> (less than or equal
to).

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

Like le, but a ASCII comparison is performed. The given values are compared on the basis of their ASCII co-
des, therefore making comparisons of letters also possible, e.g. "a" <= "s".

lt ( "<Number1>" , "<Number2>" )
Comparison of two numerical values: The result is TRUE if <Number1> < <Number2> (less than).

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

Like lt, but an ASCII comparison is performed. The given values are compared on the basis of their ASCII
codes, therefore making comparisons of letters also possible, e.g. "a" < "s".
 Strings 79

ge ( "<Number1>" , "<Number2>" )
Comparison of two numerical values: The result is TRUE if <Number1> >= <Number2> (greater than or
equal to).

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

Like ge, but an ASCII comparison is performed. The given values are compared on the basis of their ASCII
codes, therefore making comparisons of letters also possible, e.g. "s" >= "a"..

gt ( "<Value1>","<Value2>" )
Comparison of two numerical values: The result is TRUE if Value1 > Value2 (greater than).

agt ( "<Value1>","<Value2>" )
Like gt, but an ASCII comparison is performed. See the condition function aeq for details.

ne ( "<Value1>","<Value2>" )
The opposite of eq (not equal). See the condition function eq for details.

ane ( "<Value1>","<Value2>" )
Like ne, but an ASCII comparison is performed. See the condition function aeq for details.

#(= strlen ( "<String>" ) )

Returns the string length as an integer.
The expressions are not substituted!

#(= strchr ( "<String>" , "<SearchCharacter>" ) )

Searches for the <SearchCharacter> in the <String> and returns the <String> from the <SearchCharacter>.
Parameters
<String>: Character string in which the search is run
<SearchCharacter>: Character string whose first character is being sought in <String>
Return value
<Sub-String>:Character string <String> from (incl.) the found first character of <SearchCharacter>. The return
value is an empty string ("") if the search character cannot be found.
The expressions are not substituted!

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

Returns the part of <String> from the position <Start> in the length <Length>.
Parameters
<String>: Character string whose part string is to be returned
<Start>: Value is returned from the defined position (1st character = 0)
<Length>: Length, how many values are to be returned
The expressions are not substituted!

#(= strprep ( "<String>" ) )

Substitutes all the expressions ($, #, @) contained in the given <String>.

#(= envprep ( "<String>" ) )

Substitutes all the variables ($) contained in the given <String>.
 Fields 80

#(= INT ( "<String>" ) )

The given string is converted into an integer (actually a long integer).
The expressions are substituted!

#(= INT ( <Number> ) )

The given number is converted into an integer (actually a long integer). The number can also be a condition.
The expressions are substituted!

#(= DOUBLE ( "<String>" ) )

The given string is converted into a double.
The expressions are substituted!

#( subst: <Variable> )
A second substitution of the given variables is forced. This is given without the character $. The return value
is the substituted content of the variable.
Example
___Environment ( MyVar=Designation = $tempDesignation );
The substituted value is now given in the variable MyVar. If the variable $tempDesignation in turn contains
a variable, the content of this variable is not substituted.
___Environment ( MyVarNew=#(subst: MyVar) );
The content of the variable MyVar is now given in the variable MyVarNew. Even the content of $tempDesi-
gnation is substituted.

Fields
#(= field ( "<FieldName>" ) ), #( field ( <FieldNumber> ) )
The field number or field name is returned.
Return value
"<FieldName>": Name of the field or an empty string ("") if the field number does not exist
<FieldNumber>: Number of the field, or -1 if the field does not exist

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

Condition whether <FieldName> or <FieldNumber> exists.
Return value
TRUE: Field name or field number exists
FALSE: Field name or field number does not exist

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

The field length is returned as an integer.
Return value
<Integer>: Field length of the given field
-1: Field name or field number does not exist

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

The decimal positions are returned as integers.
Return value
<Integer>: Decimal positions of the given field
0: Field name or the field number does not exist, or does not have any decimal positions
 Configuration queries 81

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

The field type is returned.
Return value
C: Field is a character field
D: Field is a date field
N: Field is a numerical field
<empty>: FieldName or FieldNumber does not exist, or type can not be determined, or is not supported.

#( FieldDesc <FieldName> )
A descriptive text for the given database field name is substituted.
Procedure
The EntityType object of the current object is determined. The given field name for this EntityType object is
sought in the configuration in the sub-component GUIFields. The value of the attribute Caption (or Descrip-
tion if it is empty) is substituted from this field name. If this fails, the field name itself is returned. If the field
name in the current context is unknown, an empty string is substituted. An error message is not issued.
At least one valid Folder object is required for the evaluation. In this case, the EntityType object of the Folder
object is used (it is normally assumed that a valid record buffer containing an EntityType object exists).
The character string is substituted according to the handle FieldDesc.

Configuration queries
This query must always be placed in parentheses.

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

Reads out information from the registry in the subtree HKEY_CLASSES_ROOT. The <RegistryKey> is en-
tered as a directory using backslashes as separators.
Example:
Reading out the path for WinZip:
#(HCLS "Winzip\shell\open\command" "" :v1 )
An empty string is returned if WinZip is not installed on the workstation. The first argument is resolved by
quotation marks "..." using the format :v1.

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

Reads out information from the registry in the subtree HKEY_LOCAL_MACHINE.
Example ' see #(HCLS ...).

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

Reads out information from the registry in the subtree HKEY_CURRENT_USER.
Example ' see #(HCLS ...).

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

This function returns the value of the Attribute for the current Application object. It is only practical if a func-
tion has been called for the Application object (this is why the developer is not given a value when attempting
to read out such a value using ___Shell(read() ..., for example).
As soon as a function has been called for the Application object (e.g. Open), and the application has been iden-
tified by CheckFuncSupported, the Attributes of this Application object are also determined.

#( DBView )
The name of the database view (SQLView) of the Folder object is substituted for the current context.
An empty string is returned in the event of an error.
 Configuration queries 82

#( DBNAME )
Name of the current Folder object.

#( DBQNAME )
Name of the database parameter file with the directory and file extension.

#( DBQPATH )
Directory of the database parameter file.

#( DBQFINAME )
Name of the database parameter file without the directory and file extension.

#( DBQEXT )
File extension of the database parameter file.

#( DBSIZE )
Number of records in the database table

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

The value of the given parameter is determined in the folder-related section of the file COMPASS.INI. The
parameter can also be stated using environment variables. If the value cannot be determined, the error is re-
corded in the error log errlog.err.

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

Corresponds to the variables #(DBINI: <Attribute>). However, errors are not recorded in the error log. This
query must always be placed in parentheses!

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

This function returns the value of the given Attribute from the configuration. <Attribute> can be an expressi-
on. Recursive definitions are not allowed!
The object model is searched for the relevant record in the following sequence:
• Folder object: The attribute is sought in the Folder object of the current context taking FolderStructure into
consideration. The search is stopped when the attribute has been found.
• DocumentType object: The search is only run in the DocumentType object if the current context knows a
record buffer (Object), and this contains the field FILE_TYPE. The <Attribute> is then sought taking Do-
cumentTypeStructure into consideration. This search is stopped when the attribute has been found.
• EntityType object: Finally, the attribute is sought taking EntityTypeStructure into consideration.
The found return value is always substituted and then returned. If the attribute could not be found, an empty
string is returned and the error is recorded in the file errlog.err.
Version 5.4.0
 Configuration queries 83

#(CFGAttributeMap: <AttributenamePrefix>), #(CFGAttributeMap <Attributena-

mePrefix>)
This function collates all the attributes in a newly created map (see ___Map and #(Map )), whose name begins
with <AttributeNamePrefix>, and returns the name of the new map. The map contains all the attributes that
have been found. The attribute name is the key and the attribute value is the value from the configuration.
<AttributeNamePrefix> can be a Productstream Professional expression, e.g. #(Symbol:ActivatedBy). Recur-
sive definitions are not allowed!
The object model is searched for the suitable records in the following sequence:
• Folder object: All attributes beginning with AttributeNamePrefix are added to the map. The FolderStruc-
ture is taken into consideration.
• DocumentType object: The search is only run in the DocumentType object if the current context knows a
record buffer (Object), and this contains the field FILE_TYPE. The attributes are then added taking the
DocumentTypeStructure into consideration. Attributes already present in the map are ignored. If the field
FILE_TYPE for the current context is empty, the attributes of the document type * are used.
• EntityType object: Finally, the attributes are filled into the map taking the EntityTypeStructure into consi-
deration. Attributes already present in the map are ignored.
If an attribute matching the parameter cannot be found, an empty map is created and its name is returned.
Iteration is possible with ___Map(enum MapName function) using the attributes.
The created map then has to be deleted again (___Map(destroy <MapName>)).
Version 5.6.0
Example
Generic function for iteration using attributes:
/* arg1: Attribute name begins with
arg2: public function name for the iteration */
public ProcessConfigAttributes, AIM_ ProcessConfigAttributes
procedure AIM_ ProcessConfigAttributes
___Environment (cfgMapName=#(CFGAttributeMap:$(arg:v1)));
___Map (enum $cfgMapName $(arg :v2));
___Map (destroy $cfgMapName);
endproc

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

Queries an attribute <Attribute> from the definition DocumentType object. The value of this attribute relates
to the DocumentType object of the current object.
Here, the attribute is sought from the current DocumentType object. Attributes in objects which have not
been specifically defined as DocumentType objects are also found.
Example
Query for an AutoCAD drawing:
#(DTY:Template0)
Result = 2d-drawing.dwg
Query for an engineering document:
#(DTY:Icon)
Result = icon0006.ico

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

#( DTYID <DocumentTypeObject> <Attribute> )
Queries a parameter from the definition of the DocumentType objects. The value of this attribute relates to
the given DocumentType object.

#( ETYPE [<Attribute>] )
Queries an attribute from the definition of the EntityType objects. The value of this attribute relates to the
given EntityType object.
If <Attribute> is not defined, the EntityType of the current element is returned.
 Configuration queries 84

#( GUIViewExist <GUIView-Object> )
This condition checks whether the given GUIView object actually exists.
Return value
TRUE: if a GUIView object with the given name exists
FALSE: if a GUIView object with the given name does not exist

#( GUIViewParent <Expression> )
Substitutes the <Expression> given using the identifier GUIViewParent. The record with the focus of the pa-
rent GUIView object of the current context is used as the context.
Return value
"" If a current dialog is not contained in the context
If the current dialog does not possess a parent GUIView object
If the <Expression> returns an empty result
If the parent GUIView object does not contain an object with focus

Example
Return value for the Folder object, GUIView object and EntityType object of the parent element:
#(GUIViewParent #(DBNAME) - #(MSKNAME) - #(ETYPE) )

#( GUIViewRoot <Expression> )
As #(GUIViewParent ...), but here the highest ranking GUIView object is used as the current context.
In a standard display window, this function finds the active AIM.FOLDER element of the folder structure.
In a New record dialog window, this context contains the object belonging to the record buffer.
In the advanced search, this is the AIM.FOLDER element, which is integrated into the folder structure.
Version 5.2.3.1

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

This function searches for the <Attribute> in the configuration and in the file compas.ini from the component
<Section>. The name of the component can be any object or element.
Example
Returning the BaseFolder object of an engineering document:
#(INI:AIM.DOC.ENG:BaseFolder)

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

Synonymous to #( INI:...) from COMPASS.INI. Here, an error is not recorded in the file errlog.err if the at-
tribute can not be found.

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

Starting at the current folder object, this function searches for <Attribute> and returns its value.

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

Synonymous to #( INI:...) from COMPASS.INI. Here, an error is not recorded in the file errlog.err if the at-
tribute cannot be found.

#( MSKNAME )
Returns the GUIView object of the current context.
 Object relations 85

Object relations
Chkexist( "[db=<FolderObject>] <SQLWhereClause>")
Checks the existence of an object using a relational identifier.
Parameters
<FolderObject>
Selection which is to be checked. Here, the following parameters can be given: "[db=<FolderObject>] <SQL-
WhereClause>" <FolderObject> and <SQLWhereClause> can contain expressions, which are substituted for
the current object. If the db parameter is not used, the current folder is used.
Return value
TRUE: if <SQLWhereClause> finds at least 1 object.
FALSE: if <SQLWhereClause> finds no objects.

chkref ( "[db=FolderObject>] <SQLWhereClause>", "<ConditionTrue>",

"<ConditionFalse>" )
Checks whether an object can be found using a relational identifier. Further conditions can be returned for the
results TRUE and FALSE.
Parameters
<FolderObject>
Selection which is to be checked. Here, the following parameters can be given:
"[db=<FolderObject>] <SQLWhereClause>"
<FolderObject> and <SQLWhereClause> can contain expressions, which are substituted for the current ob-
ject.
<ConditionTrue>
Condition expression which is to be checked for each object found. If FALSE is returned once for this condi-
tion, chkref() is terminated with FALSE.
<ConditionFalse>
Condition expression which is to be checked for each object found. This check is only run if the selection from
<ConditionTrue> does not return a hit.
Return value
TRUE: if <ConditionTrue> returns TRUE for all objects.
FALSE: if at least one FALSE is returned for <ConditionTrue>.
Example
If ( chkref ("db=XREF_ELEMENT CHILD_AIMKEY=#PARENT_AIMKEY", "isPublicFolder", "FALSE") )
{
<Source code: TRUE is run >
}
Else
{
<Source code: FALSE is run >
}

Note
NOTE: For performancei reasons,
! chkexist should be used in cases where a simple existence check is being done. For
example: chkexist("db=Folder_All_Document AIMKEY>0") should be used instead of ch-
kref("db=Folder_All_Document AIMKEY>0","TRUE","FALSE")
 Object relations 86

#( where [db=<FolderObject>] <SQLWhereClause> <Expression> )

This function returns an <Expression> for a specific <FolderObject> from the given object <SQLWhereClau-
se>.
Parameters
[db=<Folder-Object>]
If this parameter is defined, the <SQLWhereClause> is run in <FolderObject>. This can be a Folder object,
an SQL table or an SQL view. If the parameter is not defined, the <SQLWhereClause> is run in the current
context.
<SQL-Where-Clause>
The SQLWhereClause is the filter criterion for the Folder object. When searching for multiple objects, the
first returned value is used. If multiple conditions are defined, the entire parameter must be placed in paren-
theses ( ... ), quotation marks " ... ", or in single inverted commas ' ... '. If no object is found, an empty string
("") is returned.
<Expression>
Everything following the 2nd parameter in the <SQLWhereClause> is substituted for the object found as an
expression.
Examples
Reading out the description of the current user from the user database:
#(where db=Folder_UserAdministration USERID='$(USERID)' #(LONG_DESC) )
Using nesting to determine the project leader (the person with the function Project Leader '
X_SHORT_DESC='ProjectLeader') of a project, and then from here the organization (with a defined mail
address ' X_IS_MAIL_ADDRESS=1; field LONG_DESC):
#(where _
db=Folder_Xref_Parent_Person _
(X_CHILD_AIMKEY=#AIMKEY AND X_SHORT_DESC='ProjectLeader') _
#(where _
db=Folder_Xref_Child_Organisation _
(X_PARENT_AIMKEY=#AIMKEY AND X_IS_MAIL_ADDRESS=1) _
#(LONG_DESC) _
) _
)
Another #where function is used here instead of giving a field name as the expression. This allows multi-layer
branching from the hit. Note: As more than one 1 search criterion can be defined, SQLWhereClauses are
placed in parentheses.

GetPersonAttribute ( "<Expression>" )
This function returns the substituted <Expression> for the linked person (marked as the recipient ->
X_IS_MAIL_ADDRESS=1).

GetOrganisationAttribute ( "<Expression>" )
This function returns the substituted <Expression> for the linked organization (marked as the recipient ->
X_IS_MAIL_ADDRESS=1)..

GetContactAddressAttribute ( "<Expression>" )
This function returns the substituted <Expression> for the linked address (marked as the recipient ->
X_IS_MAIL_ADDRESS=1).

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

This function returns the substituted <Expression> for all the linked persons. The values are returned in one
string separated by the character <Separator>.

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

This function returns the substituted <Expression> for all the linked organizations. The values are returned in
one string separated by the character <Separator>.
 Object relations 87

#( GetHisAt <Pos> <Expression> )

This function returns the substituted <Expression> for all the history. <Pos> defines which history record is to
be used. All the history records matching the current AIMKEY are found.
Parameters
<Pos>
0: <Expression> is returned as an empty string ("")
1: Substitution using the latest history record
2: Substitution using the latest history record +1
3: etc.
An empty string is returned if no history record can be found for the given <Pos>.
<Expression>
Expression which is to be substituted
Example
Function returning the revision (field REVISION) and designation (field SHORT_DESC) for the latest his-
tory record:
@(GetHisAt 1 #(REVISION) #(SHORT_DESC) )

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

This function returns the substituted <Expression> for all the history. <Pos> defines which history record is to
be used. All the history records matching the current AIMKEY are found. <MaxNum> can be used to define
the area to be addressed by <Pos>.
Parameters
<Pos>
0: <Expression> is substituted for the current object
1: Substitution using the latest history record 1 (if <MaxNum> >= 1)
2: Substitution using the latest history record +1 (if <MaxNum> >= 2)
3: etc.
An empty string is returned if no history record can be found for the given <Pos>. Value must be
>= 1 and <= <MaxNum>
<MaxNum>
Maximum number of recent history records addressed by <Pos>
<Expression>
Expression which is to be substituted
Note
i ! <Pos> = 0 or <Pos> , the <Expression> is substituted for the current object.
If <MaxNum> is given for

Example
Function always returns the version (field REVISION) and designation (field SHORT_DESC) for the 3 most
recent history records:
@(GetHisTB 1 3 @(REVISION:t) @(SHORT_DESC:t) )
@(GetHisTB 3 3 @(REVISION:t) @(SHORT_DESC:t) )
@(GetHisTB 3 3 @(REVISION:t) @(SHORT_DESC:t) )
 Object relations 88

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

Substitution for the list of all possible/permitted RelationshipIDs (link types) with which the current object
and an object containing the specified EntityType object can be linked.
The parameters are expected as standalone objects separated by spaces. Round parentheses are obligatory. The
formatting corresponds to the normal convention used for expressions.
Example
Link with a project (EntityType = AIM.PRO):
@(LinkType "AIM.DOC.ENG" )
Result −> AIM.XREF.DOC.PRO.ENG

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

Returns the next item in the BOM.
Parameters
<ParentAIMKEY>
The ParentAIMKEY or an expression which can be substituted for the AIMKEY of the Parent object.
<Interval>
Defines the interval between two items in the bill of materials. This is not necessarily the incrementation. Ex-
ample: If an interval of 10 items has been specified, and the current last item is 14, 20 is returned for the next
item as opposed to 24. The next item in the series is therefore calculated instead of simply adding the incre-
mentation.
[<StartPos>]
The start item used to calculate the next item. This parameter is optional. The start value is 1 unless defined
otherwise. The specified start item is checked with the help of the parameter <Interval>, and then incremented
if necessary to the next item matching the interval.
[<RelationshipID>]
A RelationshipID can be defined here. This parameter is optional. AIM.XREF.PART is used unless defined
otherwise.
Example
Determining the next available item in the bill of materials:.
#(NextPos #AIMKEY $(Interval:-1) $(StartPos:-1) )

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

Returns the next revision. Synonymous with #(NextPos ...).

#( NextNumber <ParentAIMKEY> <Intervals> [<StartPos>] [<RelationshipID>] )

Returns the next item in the bill of materials. Synonymous with #(NextPos ...).
 Status 89

Status
#( Status [: [icon|desc|id|onchange|onenter] ] )
Information is substituted for the current status. If no parameter is given, the parameter :desc is used.
Parameters
:icon
Returns the icon file name and the extension for the current status
:desc (:bez is still available for compatibility reasons)
Returns the status designation of the current status
:id
Returns the status ID of the current status (corresponds to the field STATUSKEY)
:onchange
Returns the attribute onChange of the current status (corresponds to the field STATUSKEY)
:onenter
Returns the attribute onEnter of the current status (corresponds to the field STATUSKEY)

#( statusnext )
Returns all the currently available statuses (i.e. those which would be shown in the selection!). They are retur-
ned in sequence in quotation marks and separated by spaces.
Example
Result: "00001" "00003" "00004"
-> the number is shown using #(statusnext:v0)
-> the first status is shown using #(statusnext:v1), etc.

#( statusdesc: <StatusKey> )
Returns the description for the specified <StatusKey>.
Example
Description of the designation of the first available status:
#( statusdesc: #(statusnext:v1) )

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

Substitutes information about the status change identified with <UID>.
Parameters
<UID>
The UID is returned by calling #(StatusNextUID …). This is a unique identifier for a status change. It is only
valid for as long as the current user is logged in. Other unique UIDs are used the next time the user logs in.
[<Parameter>]
This governs which value is to be returned. Id is used by default unless defined otherwise. The following <Pa-
rameters> are defined:
• Id (default): Returns the status ID of the target status available using this UID.
• Desc: Returns the description of the status change.
• Icon: Returns the name of the icon file assigned to the target status available using this UID.
• Backward: 1 is returned if the attribute Backward has been defined as 1 or TRUE for the status change.
Otherwise 0 is returned.
• Forward: 0 is returned if the attribute Backward has been defined as 1 or TRUE for the status change. Other-
wise 1 is returned.
[:<Formatting>]
The format is applied to the result.
 Status 90

Examples
The <UID> here is 23
Determining the StatusKey:
#(StatusUID 23 id )
Result -> 00002
Determining the text for the status change:
#(StatusUID 23 desc )
Result -> Send document to be checked
Determining the icon file (upper-case letters):
#(StatusUID 23 icon :A)
Result -> STA00002.ICO
Determining Backward:
#(StatusUID 23 Backward )
Result -> 0

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

Returns the <UID> of the status changes possible from the status of the current object.
Parameters
Backward
If this parameter is defined with spaces as separators, only those changes where the attribute Backward has been
defined with 1 or TRUE are listed.
Forward
If this parameter is defined with spaces as separators, only those changes where the attribute Backward has not
been defined at all or not with 1 or TRUE are listed.
Note
If neither Backward nor iForward
! is defined, all the status changes are listed.

Example
Returning the UIDs with spaces as separators as a character string:
#(StatusNextUID :v0)
Result -> 5
#(StatusNextUID Forward :v0)
Result -> 3
#(StatusNextUID Backward :v0)
Result -> 2
 Selections 91

#( ReplState [: [icon|desc|id] ] )
Information is substituted for the current replication status. If no parameter is given, the parameter :desc is
used.
Parameters
:icon
Returns the corresponding icon file name and the extension for the current replication status.
:desc
Returns the designation for the current replication status.
:id
Returns the ID for the current replication status.
Replication statuses
The following replication statuses (these are checked in the order given here) exist for the primary files (not for
secondary files):

ID Name Icon
0 Original #TxRepl400 Replstate0.ico
1 No replica #TxRepl401 Replstate1.ico
2 Current #TxRepl402 Replstate2.ico
3 Transfer active #TxRepl403 Replstate3.ico
4 Outdated #TxRepl404 Replstate4.ico

Selections
#( numsele )
Number of selected objects.

#( numdisp )
Number of displayed objects.

#( nummark )
Number of marked objects.

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

<Expression> is substituted for the first object in the <Selection> .
(See: ___Selection.)

#( selection: <Selection> )
Number of objects in the specified selection.
 Applications 92

Applications
taskrunning ( "[EXE:]<Exe-Name>" )
Checks whether the defined WINDOWS application is active (shown in the Windows taskbar = TRUE). The
name of the EXE file, without the path but with the extension, is given as the parameter (optionally, the key-
word EXE: can be given before the file name).
Example
NotePad is running:
taskrunning ( "EXE:notepad.exe" )

Return value
TRUE: The defined application has been found in the Windows taskbar
FALSE: The defined application has not been found in the Windows taskbar

taskrunning ( "DDE:<DDE-Server-Name>" )
Checks whether the defined WINDOWS application is already active (accessible via DDE = TRUE). The key-
word DDE: followed by the corresponding DDE server name is given here.
Example
ACADLT is running:
taskrunning ( "DDE:AutoCADLT.DDE" )

Return value
TRUE: The defined DDE server of an application is accessible
FALSE: The defined DDE server of an application is not accessible

taskrunning ( "TIT:<WindowTitle MainWindow>" )

An application with the specified dialog window title is searched for. Wildcards can be used in the text entered
here.
Example
ACADLT is running:
taskrunning ( "TIT:Auto*LT" )

Return value
TRUE: An application with the specified title has been found
FALSE: An application with the specified title has not been found

LastCreatedProcessRunning ()
Checks whether the last program to have been started from Productstream Professional using ShellExecute(..)
is still running or if it has already been terminated.
Return value
TRUE: If the program is still running
FALSE: If the program is no longer running
Version 5.2.2.12
 Files 93

LastCreatedProcessWait ( <TimeOut> )
Waits either until the last program to have been started from Productstream Professional using ShellExecute(..)
is terminated or for the <TimeOut> depending upon which event takes place first.
Return value
TRUE: if the program is closed.
FALSE: if the TimeOut is expired; i.e. the program is still running.
<TimeOut> specified in milliseconds. If TimeOut is set to -1, the function infinitely waits for the end of the
program.
Version 5.2.2.12

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

Reserves a license and returns whether the reservation was successful. This function can be used in condition
expressions. The default time is used if the reservation period is defined with the value <=0.
Return value
TRUE: License reservation successful
FALSE: License reservation failed
Example
Attempting to reserve a license for COMPASS 2000 pro 5.4.x:
If ( !GetLicence("@(GetLicence AIMPROF540)","-1") )
{
<Sourcecode:License reservation failed>
}
Else
{
<Sourcecode: License reservation successful>
}
See also "___GetLicense" function description.

Files
exist ( "<File>" )
Checks whether a file actually exists. The result is TRUE if the file <File> exists. The file information comprises
the directory name, file name and the extension. Wildcards (*,?) may not be used.

xexist ( "<FileModel>" )
Checks whether a file actually exists. The result is TRUE if the file exists. The <FileModel> comprises the di-
rectory name, file name and the extension. Wildcards (*,?) can be used in the file name and the extension.

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

Compares the size of two specified files. The return value is an integer value.
Return value
0: The two files are the same size
1: The two files are not the same size
2: <File1> does not exist
4: <File2> does not exist
8: The name of <File1> could not be determined (possibly empty)
16: The name of <File2> could not be determined (possibly empty)
32: <File1> could not be opened for reading
64: <File2> could not be opened for reading
 Files 94

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

Compares the date of two specified files. The return value is an integer value.
(Return values ' see compFileSize)

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

Compares the binary contents of two specified files. The return value is an integer value.
(Return values ' see compFileSize)

#(= FileSize ( "<File>" ) )

Function for determining the file size. The return value is an integer value.
Return value
>0 File size
<0 Error

#(= FileDate ( "<File>" ) )

Function for determining the file date. This function returns the date on which the file was last modified. The
time zone and summer/winter time are taken into account. The function UTCFile( file ) returns a date without
any conversion. The return value is a string.
Return value
"YYYYMMDDhhmmss": File date
"": Error

FileReadAccess ( "<File>" )
Queries the read rights for the specified file.
Return value
TRUE: Read access is available
FALSE: Read access is not available

FileWriteAccess ( "<File>" )
Queries the write rights for the specified file.
Return value
TRUE: Write access is available
FALSE: Write access is not available

doc0exist ()
Checks whether #(DOCNAME0) exists. Corresponds to exist("#DOCNAME0") but is faster!
Return value
TRUE: File #(DOCNAME0) exists
FALSE: File #(DOCNAME0) does not exist

docexist ( <n> )
Checks whether #(DOCNAME<n>) exists. The document identifier is entered in place of <n> (example: 0 for
#(DOCNAME0)). Corresponds to exist("#DOCNAME<n>")but is faster!
Return value
TRUE: File #(DOCNAME<n>) exists
FALSE: File #(DOCNAME<n>) does not exist
 Files 95

#( FileType : <FileName> )
This function returns the version of the existing AutoCAD drawing DWG. 0000 is always returned if the file
is not a DWG.
Return values
0000: File is not a DWG or it could not be found
ACAD: DWG was created using AutoCAD up to and including version 10 or from 2002
AC11: DWG was creating using AutoCAD 11
AC12: DWG was creating using AutoCAD 12
AC13: DWG was creating using AutoCAD 13
AC14: DWG was creating using AutoCAD 14
AC15: DWG was creating using AutoCAD 2000 or 2000i

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

Searches for a file in multiple search paths and returns the name of the directory in which it was found.
Parameters
<FileName>
The file name is defined together with the extension. The characters "*" and "?" may not be used. This file
must exist. The search is stopped when the file is found. If the specified file does not exist, the path to <File-
Name> is cut off if necessary and the file is sought in the directories defined in <SearchPaths>.
Note
If <FileName> does not icontain
! a path, priority is always given to a file in the active working directory!

<SearchPaths>
Multiple directories separated by semi-colons can be defined here. The file <FileName> is then sought in the
specified sequence in these directories.
<Formatting>
All the format details defined for Productstream Professional expressions can be given here in order to influ-
ence the return value.
Return value
<Directory>: File has been found in this directory
"": File has not been found
Examples
#(FindFile "aimtitle.txt" "$(CaiPath:|+)acad$(_DS)mdt4; $(CAIPATH: |+)acad; $(CAIPATH)"
)
#(FindFile "aimtitle.txt" "#(DTYAppl #(DTYGetValidAppl EDIT0) FileSearchPath)" )

#( FileNameGen )
Generates a unique file name (field FILE_NAME) which is returned

#( DOCNAME<n> )
The directory, file name and extension of the current object.
The following values can be used for <n>:
0: Primary document
1: Secondary document - PDF (version 5.4 and higher)
2: Secondary document (freely definable)
3: Secondary document (freely definable)
4: Secondary document (freely definable)
5: Secondary document (freely definable)
 Files 96

#( PATH<n> )
Internal access path to the documents of the current object.
The following values can be used for <n>:
0: Primary document
1: Secondary document - PDF (version 5.4 and higher)
2: Secondary document (freely definable)
3: Secondary document (freely definable)
4: Secondary document (freely definable)
5: Secondary document (freely definable)

#( EXT<n> )
File extension of the document of the current object.
The following values can be used for <n>:
0: Primary document
1: Secondary document - PDF (version 5.4 and higher)
2: Secondary document (freely definable)
3: Secondary document (freely definable)
4: Secondary document (freely definable)
5: Secondary document (freely definable)

#( EXTFLD<n> )
Name of the fields in which Productstream Professional enters the file extension of the document files as soon
as the corresponding document has been created.
The following values can be used for <n>:
0: Primary document
1: Secondary document - PDF (version 5.4 and higher)
2: Secondary document (freely definable)
3: Secondary document (freely definable)
4: Secondary document (freely definable)
5: Secondary document (freely definable)

#( LinkFld )
Name of the field in which the directories, file names and file extensions of primary documents are entered
which are not managed by Productstream Professional, but by using external references (default =
FILE_LINKNAME).

#( LinkName )
Directory, file name and extension of an external reference, i.e. of a primary document which is only managed
using a reference link and not directly by Productstream Professional. This information is stored in the data-
base in the field with the name determined by LINKFLD.

#( PATHFLD<n> )
Name of the field in which the access path to one of the 6 or more documents in a binder can be optionally
defined.

#( AIMKEYfromPATH <FileName> )
Here, the file name is used to find the corresponding AIMKEY. The path must be given in quotation marks
if the path name itself contains spaces.
Example:
#( AIMKEYfromPATH "$(myFile)" )
#( AIMKEYfromPATH "C::\All drawings\dwg\abc00000.dwg" )
 Time 97

#( DescfromPATH <FileName> )
Here, the file name is used to find the corresponding description. The path must be given in quotation marks
if the path name itself contains spaces.
Example:
#( DESCromPATH "$(myFile)" )
#( DESCromPATH "C:\All drawings\dwg\abc00000.dwg" )

Time
Functions which return a time zone-neutral value always begin with the 3 upper-case letters "UTC". The re-
turn value is a special time value, which cannot be compared with character springs. Time calculations cannot
be performed, either.
The earliest possible time is January 1st, 1970, 0:00; the latest possible time is January 18th, 2038, 19:14:07.

#(= UTCFile ( "<File>" ) )

Function for determining the file date of the specified file. The return value is a time value.
Return value
Time value: File date
-1: Error

#(= UTCSystem ( ) )
Function for determining the current system time. The return value is a time value..
Return value
Time value: File date
-1: Error

#(= localUTC ( <TimeValue> ) )

This function returns the string produced by the time value.
Return value
"YYYYMMDDhhmmss: "Converted time value
-1: Error

#(= gmUTC ( <TimeValue> ) )

This function returns the string produced by the time value. Coordinated universal time is used here.
Return value
"YYYYMMDDhhmmss: "Converted time value
-1: Error

#(= strUTC ( <TimeValue> ) )

This function returns a decimal figure produced by the time value.
Return value
>0: Converted time value
-1: Error

#(= INT ( <TimeValue> ) )

This function returns an integer figure produced by the time value.
Return value
>0: Integer value from the converted time value
-1: Error
 Time 98

#(= DOUBLE ( <TimeValue> ) )

This function returns a floating decimal point figure produced by the time value.
Return value
>0 Floating decimal point figure from the converted time value
-1 Error

#(= UTC ( <DecimalNumber> ) )

This function returns a time value produced by the decimal figure. The decimal figure can also be defined as
a string.
Return value
>0: Time value
-1: Error

#(= TIME ( "<YYYYMMDDhhmmss>" ) )

This function returns a time value produced by the string.
Caution!
The function TIME() converts the time from the character string taking into account the time zone or summer/
winter time!

Return value
>0 Time value
-1 Error

#( SYSDATE )
Return value is the current system date in the format YYYYMMDD. The following variations can be used:
#( SYSDATE ): YYYYMMDD (same as localUTCSystem())
#(SYSDATE10): DD.MM.YYYY
#(SYSDATE:D10): DD.MM.YYYY
#(SYSDATE8): DD.MM.YY
#(SYSDATE:D8): DD.MM.YY

#( SYSTIME )
Return value is the current system time in the format HHMMSS. The following variations can be used:
#( SYSTIME ): HHMMSS
#(SYSTIME8): HH:MM:SS
#(SYSTIME5): HH:MM
Caution!
The hour is filled with a space when defining times between 0-9. This space is deleted when the time is saved in
a variable. The time then contains just 5 figures.
 Rights 99

Rights
crstatic ( "<Rights>" )
Checks whether the current user has been granted the specified rights for the EntityType object of the current
object (this cannot always be achieved using the 4th parameter in the function declaration, as in some cases,
e.g. with GetDropEffectFunctions, the function always has to be called, but its behavior has to vary according
to the access rights).
This function is required if crdynamic cannot be used (e.g. when creating a new record).
The following characters can be defined as a character string:
C = Create
D = Delete
R = Read
W = Write (Edit)
Return values
TRUE: The user has been granted all the access rights defined in <Rights> for the global EntityType object of
the current object
FALSE: The user has not been granted all the access rights defined in <Rights> for the global EntityType object
of the current object
Example
crstatic ( "C" )

crdynamic ( "<Rights>" )
Checks whether the current user has been granted the specified right for the current object.
The following characters can be defined as a character string:
C = Create
D = Delete
R = Read
W = Write (Edit)
Return value
TRUE: The user has been granted all the access rights defined in <Rights> for the current object
FALSE: The user has not been granted all the access rights defined in <Rights> for the current object
Example
crdynamic ( "RW" )

cr ( "<Rights>" )
Synonymous with the condition function crdynamic.

#( dynamicRights )
This function returns the dynamic rights for the current object:
C = Create (is always static)
D = Delete
R = Read (is always given)
W = Write (Edit)
 Exclusive reservation 100

#( staticRights )
This function globally returns the static rights for the current object as defined in the configuration:
C = Create
D = Delete
R = Read
W = Write (Edit)
G = Group right
O = Owner right
A = Default right

Exclusive reservation
lock ()
Exclusively reserves an object. The user is notified immediately as to whether the reservation was successful.
Identical behavior to the function ___Lock.
Return value
TRUE: Reservation successful
FALSE: Reservation failed

islocked ()
This condition checks whether the current object has been exclusively reserved. It is irrelevant for which user
the object has been reserved.
Return value
TRUE: Element has been reserved
FALSE: Element has not been reserved

mylock ()
This condition checks whether the current object has been exclusively reserved for the current user.
Return value
TRUE: Element has been reserved by the current user
FALSE: Element has been reserved by the current user

#( LockUser )
Returns the user name of the user for whom the object has been exclusively reserved.
Return value
<Username>: Name of the user for whom the object has been reserved
<empty>: The object has not been reserved
 SQL queries and functions 101

SQL queries and functions

#( XDWSFKT: <SQL-Procedure> [<Parameter>] )
With this function, it is possible to execute a stored procedure in the SQL database. The syntax has to be ad-
apted to the respective DB system.
The following environment variables are set when the statements have been run:
CMD_ERROR_NO
CMD_ERROR_MESSAGE
CMD_ERROR_SOURCE
CMD_ERROR_DESCRIPTION
Parameters
<SQL-Procedure>
The specified SQL stored procedure is executed.
[<Parameter>]
Any given parameters are passed on to the function.
Return value
This function returns a character string with a maximum length of 256 characters as the return value.
Example
The MS-SQL function sumstl looks like this:
CREATE PROCEDURE sumstl @stlid varchar(80) OUTPUT,@AIMKEY varchar(50),@MAX int AS
Begin
declare @akey numeric(17,5)
declare @errno int
declare @startpos int
select @stlid = REPLACE(REPLACE(CONVERT(varchar(80), GETDATE(),21), ' ', '_'), ':', '.')
set @errno = 0
set @startpos = 1
set @akey = CAST(@AIMKEY AS numeric(17,5))
BEGIN TRANSACTION
Exec @errno = sumstl_rekursiv @stlid, @akey, 0, @MAX, 1.0, @startpos
If ( @errno <> 0 )
begin
set @stlid = NULL;
ROLLBACK
End
Else
Begin
COMMIT
End
End
Executing the procedure on the current object:
___Environment ( StlId=#(XDWSFKT:sumstl ( ,#AIMKEY,$(arg:v1) ) ) );

Caution!
The first argument for sumstl is not defined. It is implicitly used in Productstream Professional as a return cha-
racter string. This can be tracked in the associated stored procedure.

(See also: ___XdwCmd )

 SQL queries and functions 102

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

The current maximum value in the column <FieldName> is determined. The range in <Value> for which the
maximum value is being searched for is determined using Offset and Length.
Parameters
<FieldName>
Name of the column in which the maximum value is being searched.
<Value>
Value that is being used to search for the maximum value.
<Offset>
The first <Offset> number of characters in the value is used as a prefix for searching for the maximum value.
<Length>
The maximum value is searched for the range in <Value> defined by <Offset> and <Length>.
Return value
This function returns the maximum value that is found as a character string.
Example
#(GetMaxKey IDENT="ENG-000000-ABCD" 4 6)
The largest Ident that begins with "ENG-" and ends with
"-ABCD" is searched for.
Offset = 4 and Length = 6 exactly describe the range "000000".

#( DBSpec_isNULL <FieldName> )
A SQL function which sets a definitive value for NULL values is performed on the field name for handling
NULL values in the database.
The substitution function can be used to form an SQL Where clause to be used directly with the database. The
result varies according to the connected database, i.e. this SQL function is dependent upon the DB provider.
Example
#(DBSPEC_isNULL AIMKEY)
MS-SQL -> ISNULL(AIMKEY,0)
ORACLE-> NVL(AIMKEY,0)
Version 5.2.5

#( DBSpec_Date <Date YYYYMMDD> )

The date value is prepared so that it can be used so in an SQL statement to create the SQL Where clause. The
result is dependent upon the DB provider..
Example
#(DBSPEC_Date 20020721)
MS-SQL −> '20020721'
ORACLE -> TO_DATE('20020721','YYYY/MM/DD')
Alternative calls:
#(DBSpec_Date <Date:YYYYMMDD> )
#(DBSpec_Date "<Date:YYYYMMDD>" )
#(DBSpec_Date '<Date:YYYYMMDD>' )
#(DBSpec_Date <Expression as YYYYMMDD> )
Version 5.2.5
 SQL queries and functions 103

#( DBSpec_ToDay )
A part string is substituted to create an SQL Where clause, which is used for a query with the special date today.
Special feature: This part string contains the operator!
Example
#(DBSPEC_ToDay)
MS-SQL -> GETDATE()
ORACLE-> TRUNC(SYSDATE,'DD')
Version 5.2.5

#( DBSpec_YesterDay )
A part string is substituted to create an SQL Where clause, which is used for a query with the special date yes-
terday. Special feature: This part string contains the operator!
Example
#(DBSPEC_YesterDay)
MS-SQL -> GETDATE(-1)
ORACLE -> TRUNC(SYSDATE-1,'DD')
Version 5.2.5
 104

Chapter 13 Internal Functions

___AskQ
This function opens a dialog window with a control question and up to 3 freely definable buttons.

Syntax
___AskQ ("<Text>" <Variable> <Button 1> [<Button 2> [<Button 3>]] );

Parameters
"<Text>"
Text which is displayed to the user. Any spaces in the text must be given in quotation marks (").
<Variable>
Name of the variable in which the return value for the selected button is to be saved.
<Button 1>
Text for the 1st button. Any spaces in the text must be given in quotation marks (").
[<Button 2>]
Text for the 2nd button if it is to be used. Any spaces in the text must be given in quotation marks (").
[<Button 3>]
Text for the 3rd button if it is to be used. Any spaces in the text must be given in quotation marks (").

Return Values
Value Description
0 Button 1 is used or Enter
1 Button 2 is used
2 Button 3 is used or the window is closed by pressing Escape
-1 Error: One of the texts has not been returned (error message in the file errlog.err)

Notes
• The entire string is substituted in the current object before it is executed.
• The value 2 is returned if the window is closed by pressing Escape. This return value must therefore always
be intercepted even if Button 3 has not been used!
• <Variable> has the same value as the internal error level.
• It is advisable to use all texts with the function #(Tx ...) to maintain language neutrality

Examples
The following function is used as an example:
___Environment ( Text=Do you really want to perform this function? );
___AskQ ( "$(Text)" Response "Yes" "No" );
If { eq("0","$(Response)") )
< Perform source code for Yes >
}
Else If { eq("1","$(Response)") )
< Perform source code for No >
}
Else If { eq("2","$(Response)") )
< Perform source code for Cancel >
}
In this case, 2 buttons have been defined (Yes and No) and the response has been saved to the variable Re-
sponse. A cancellation is also intercepted as the window can be closed by pressing ESC.
 105

See also
"#(Tx.....)" on page 73
"Formats" on page 69
 106

___Break_Enum
This function is used to prematurely terminate a loop (enumeration). This affects the functions
___ForAllRela, ___ForAllRelaH and ___Selection enumerate. ___Break_Enum terminates the loop.

Syntax
___Break_Enum ();
___Break_Enum([<option>] <arg>);

Parameters
Stating <arg> opens a message box showing the progress of the respective selection/enumeration with <arg> as
progress indicator.
The stating of one or more [<option>] is optional. If no options are stated, Productstream Professional sets the
default values for the message box.
The following options are available:

Option Description
headline= Message box title.
text1= Displays a status message at the top of the message box.
text2= Shows the text that is to be displayed when the “Cancel” button is clicked.
desc= Description of the status of the message box.
btn= Text on the “Cancel” button.

Return values
Value Description
0 Command executed successfully (no further details for the error given, error message in the
file errlog.err).
1 If “Cancel” was clicked in the ___Break_Enum dialog.

Notes
• The function completely cancels the commands ___ForAllRela and ___Selection enumerate.
• If the message box is open, it is closed if the function is called without any parameters.

Example
___Selection ( create list );
___Selection ( add list mark );
___Selection ( enumerate list DoFileExist );
Public DoFileExist,AIM_DoFileExist
Procedure AIM_DoFileExist
If ( !exist("#(DOCNAME0)") )
{
...
___Break_Enum ();
}
< Source code: File exists >
Endproc
In this example, a list of all the selected data records is defined and the function DoFileExist is run on each
record. ___Selection enumerate is terminated as soon as no file is assigned to the object. The remaining objects
are not processed.
 107

Extensions
Two query functions are available that can be used to query the status of the Cancel button and the existence
of the Break_Enum message box.
• isBreakEnum() returns TRUE if a user has clicked the “Cancel” button.
• isBreakEnumDialogVisible() returns “TRUE” if the message box is open.

See also
"DBP/COP programming" on page 57
"___ForRela, ___ForRelaH, ___ForAllRela, ___ForAllRelaH" on page 144
"___Selection" on page 185
 108

___ChangeField
Changes the value of fields of the active element in the Productstream Professional database. Multiple fields
can be changed simultaneously.

Syntax
___ChangeField (["]<FieldName 1>=<FieldValue 1>["] ["<FieldName 2>=<FieldValue 2>"] ... );

Parameters
<FieldName N>
Name of a field. The names are case-sensitive (all field names are upper-case by default).
<FieldValue N>
New value for a field (Productstream Professional expressions can be used).
The entire expression "<FieldName>=<FieldValue>" must be given in double quotation marks (") if multiple
fields are to be changed simultaneously.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
• The entire string is substituted in the current element before it is executed.
• If the user has not been granted the right to edit data records (+w), the command does not take effect and
the return value is ?0.

Examples
The following syntax is used to change the value for the designation (field = SHORT_DESC):
___ChangeField ( SHORT_DESC=New #(SHORT_DESC) );
The content of the designation (field = SHORT_DESC) is supplemented at the beginning with the text New.
The current value is then entered. If the designation contains the word Bolt, the new value would be New Bolt.
The following syntax is used to simultaneously change the value for the designation and the cre-
ator:
___ChangeField ( "SHORT_DESC= Designation" "CREATE_USER=$(USERID)" );
The designation field (field = SHORT_DESC) is updated with Designation and the creator
(field=CREATE_USER) is updated with the current login name

See also
"Formats" on page 69
Variables
 109

___ChangePassword
Opens the dialog window for changing the password. The user who is currently logged on can change his pass-
word here. The password for logging on to the Productstream Professional database can also be changed here.

Syntax
___ChangePassword ( {__USER__|__DB__} );

Parameters
__USER__
Change the password of the logged-on user
__DB__
Change the password for logging on to the Productstream Professional database

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entries DBUSER and DBPASSWORD in the section __cmpusr__ in the COMPASS.INI are evaluated
when logging on to the Productstream Professional database. If the password is changed in the dialog window,
the file dbpw.ini is created with the new __cmpusr__-section. This is then read out the next time
Productstream Professional is launched. Passwords are encrypted for security reasons.
Caution!
Only the administrator may be logged on to Productstream Professional when the database password is changed,
as otherwise the other users will be disconnected from the database server. A warning message is displayed in this
case.
 110

___ChangeStatus
Function for changing a status. It either opens the change status dialog window in which a target status can be
selected, or a target status is specified and the status is changed directly.

Syntax
___ChangeStatus ( <Parameters> <Arguments> );

Parameters
Parameter Arguments Description
[-next] <TargetStatusID> Changes the status to the target status if this can be done so unambiguously (-
next does not have to be entered).
-auto If only one status can be attained from the start status, the status is changed auto-
matically. If multiple status conditions can be chosen, the standard dialog win-
dow opens.
-silent Errors are not displayed to the user. They are only written in the file Errlog.err
in the active working directory.
-sele: <Variable> Status can only be selected, but not changed. The target status selected by the
user is saved with the unique System ID in the variable <VariableName>_UID
and can be used with -UID:<VariableName>_UID. The selected target status is
also saved in the variable <VariableName>.
-UID: <Variable> Changes the status to the target status previously saved in the variable <Variable>
using -sele:<Variable>.

Return Values
Value Description
0 Command executed successfully
-10 Status has been explicitly defined using the switch -auto (target status or UID) but
could not be attained.
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The current object is synchronized before the status is changed (corresponds to ___DbUtils ( sync current )).
The following variables are set before the status change functions are called:
• _ChangeStatusID: ID of the target status
• _ChangeStatusDesc: Description of the target status
• _ChangeStatusUID: Unique ID of the current transition
• _ChangeStatusLevel: Stack level for the recursive use of ___ChangeStatus
The following fields are updated if they exist:
• STATUSKEY -> target status
• STATUS_CHG_USER -> $USERID (current user)
• STATUS_CHG_DATE -> #SYSDATE (current date)
A message is not displayed if these fields do not exist! The fields are permanently defined in the
COMPASS.EXE and cannot be configured!
This function is not performed if one of the following conditions applies:
• A status management has not been defined or the field STATUSKEY does not exist.
• The EntityType object cannot be located.
• Productstream Professional is being used with an Office license and the element is an engineering element
(AIM.DOC.ENG, AIM.PART or any derived element types).
• Productstream Professional Replicator has been installed and the document is not the original document
(applies only for DocumentType objects).
• The document has been exclusively reserved by another user (product version 5.4.1.6 or later).
For a full description of the procedure for changing the status ' see Changing status
 111

Examples
Changing the status by specifying the target status:
___ChangeStatus ( 00002 );
The selection dialog window for the target status is displayed if the target status 00002 cannot be attained.
Otherwise, the status is changed. The dialog window for selecting the correct status change is also opened if
multiple transitions have been defined for 00002 (e.g. with and without e-mail).
Changing the status after previously querying the target status:
___ChangeStatus ( -sele:Target );
...
___ChangeStatus ( -UID:Target_UID –auto –silent );
First of all, the dialog window for selecting a target status is displayed. The selected target status is then saved
in the variable Target and Target_UID. The status is now changed. The switches -auto and -silent can be used
if the window is not to be displayed.

See also
"The configuration of Productstream Professional" on page 3
 112

___CheckExtensionFlags
This function checks a document record to ascertain whether any assigned files exist corresponding to the Do-
cumentType object definitions. The fields FILE_EXT (file extension), FILE_UTC (file date) and FILE_SIZE
(file size) for the current object in the Productstream Professional database are filled with the current values for
the file attributes (or emptied where applicable). If the Attribute EXTFLD1 is filled this also works for assigned
secondary files.

Syntax
___CheckExtensionFlags ( [NoUpdate] );

Parameters
[NoUpdate]
If this argument is set, the data record in the database is not updated. It is designed to be used together with
the command ___RecordBuffer.

Return Values
Value Description
0 Command executed successfully, no changes made
<0 Command executed successfully, changes have been saved.
-1 Error (no further details given, error message in the file errlog.err)

Notes
If the condition AutoCheckExtensionFlags =TRUE, or the condition has not been defined, the function is per-
formed on ___RecordBuffer or the database. Otherwise, no changes can be made.

Examples
Updating the file information for the current object:
___CheckExtensionFlags ();
The currently selected record is updated if it contains the fields FILE_EXT, FILE_UTC and FILE_SIZE and
the corresponding file can be found.
Changing the record buffer:
___RecordBuffer ( create Data );
___RecordBuffer ( load Data );
___RecordBuffer ( call Data ___CheckExtensionFlags NoUpdate );
A record buffer called Data is generated and the currently selected object is loaded. The fields FILE_EXT,
FILE_UTC und FILE_SIZE are only updated in the record buffer Data (if they exist). The record in the da-
tabase is not affected.

See also
"___RecordBuffer, RecordBuffer" on page 177
 113

___CloseArchiv
The active Productstream Professional dialog window is closes and the function is terminated. If this is the last
dialog window (the main Productstream Professional window), Productstream Professional is terminated wi-
thout an acknowledgement.

Syntax
___CloseArchiv ();

Parameters
<None>

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
All the functions are terminated when the dialog window is closed. The subsequent functions are no longer
performed.

Examples
The dialog window showing a record buffer is to be terminated:
___RecordBuffer ( create Data );
___RecordBuffer ( load Data );
___RecordBuffer ( edit Data Create_Dialog_EngineeringDocument );
...
___CloseArchiv ();
___Shell ( read()Window has been closed again! );
In this example, an object has been generated and opened in the dialog window. The dialog window is closed
again using the function ___CloseArchive . Productstream Professional then automatically terminates all the
subsequent functions.
The last instruction to display a message to the user is therefore no longer given.

See also
"___RecordBuffer, RecordBuffer" on page 177
 114

___CmpUtility
A collection of utility functions for logging or issuing internal information and for performing system tests du-
ring modifications such as the output of assigned variables, available functions, configured status changes and
permissions, used selections and texts from TEX files, as well as for testing conditions and DBP functions.

Syntax
___CmpUtility ( <Parameter> [ <Arguments> ] );

Parameters

Parameter Arguments Description

__EditFile__ [<FileName>] Calls notepad.exe with the file syspar.h0 (= list of all variables with the current
values). The file must exist.
If <FileName> has been specified, the editor notepad.exe is launched with the file
<FileName>. The file must exist.
__TestCondition__ Dialog with the list of all conditions for testing.
__TestProc [{On|Off}] Activates, deactivates or switches the trace mode (step-by-step processing of a func-
tion).
Trace [{On|Off}] Activates, deactivates or switches the trace mode (step-by-step processing of a func-
tion).
__WriteLinks__ [<FileName>] Saves all the configured link types (RelationshipType) to the specified file. If a file is
not specified, the data is written to the file cmplinks.tmp.
WriteLinks Saves all the configured link types (RelationshipType) to the file cmplinks.tmp and
opens it using notepad.exe.
__WritePublic__ [<FileName>] Saves all the known functions (internal and public) to the specified file. If a file is not
specified, the data is written to the file func.tmp.
WritePublic Saves all the known functions (internal and public) to the file func.tmp and opens it
using notepad.exe.
__WriteRights__ [<FileName>] Saves all the rights for the current user to the specified file. If a file is not specified, the
data is written to the file cmpright.tmp.
WriteRights Saves all the rights for the current user to the file cmpright.tmp and opens it using
notepad.exe.
__WriteSelection__ [<FileName>] Saves all the currently known selections in the specified file. If a file is not specified,
the data is written to the file sele.tmp.
WriteSelection Saves all the currently known selections to the file sele.tmp and opens it using note-
pad.exe.
__WriteStatus__ [<FileName>] Saves all the configured status changes and status definitions to the specified file. If a
file is not specified, the data is written to the file status.tmp.
WriteStatus Saves all the configured status changes and status definitions to the file status.tmp and
opens it using notepad.exe.
__WriteSyspar__ [<FileName>] Saves all the known variables and their current values to the specified file. If a file is
not specified, the data is written to the file syspar.h0.
Additionally following parameters are allowed to define the Unicode format [-ansi|-
utf8|-utf16|-utf16_be|-utf16_le]
WriteSyspar Saves all the known variables and their current values to the specified file and opens it
using notepad.exe.
__WriteUTex__ [<FileName>] Saves all the file names, and the number of texts in TEX files (#Tx...) they contain, to
the specified file (incl. the search paths to these files). If a file is not specified, the data
is written to the file utex_log.tmp.
WriteUTex Saves all the file names, and the number of texts in TEX files (#Tx...) they contain, to
the file utex_log.tmp (incl. the search paths to these files) and opens them using note-
pad.exe.
__WriteUTexAll__ [<FileName>] Saves all the file names (incl. the contents), and the number of texts in TEX files
(#Tx...) they contain, to the specified file (incl. the search paths to these files). If a file
is not specified, the data is written to the file utex_log.tmp.
 115

Parameter Arguments Description

WriteUTexAll Saves all the file names (incl. the contents), and the number of texts in TEX files
(#Tx...) they contain, to the file utex_log.tmp (incl. the search paths to these files)
and opens them using notepad.exe.
WriteCompass_Ini [<FileName>] Saves the contents of the file COMPASS.INI (incl. all the overlayed values) to the
specified file. If a file is not specified, the data is written to the file cmp_ini.tmp and
then opened using notepad.exe.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Examples
Displaying all the values in the file COMPASS.INI:
___CmpUtility ( WriteCompass_Ini );
notepad.exe is launched and cmp_ini.tmp is opened with all the values.
 116

___CompassInfo
Displays the Productstream Professional Info dialog window and the Client version number.

Syntax
___CompassInfo ();

Parameters
<None>

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The command can be found by default in the menu Help > About.
 117

___CopyFilesToLocal
This function creates a copy of one or more files in a directory on the local workstation.
In contrast to the function ___ExportExecute, this function does not create copies of entire trees in an export
directory on the server, but only local copies of selected files on the workstation.
When the function is called, a dialog window opens where the user can select a local directory. If only a single
file is passed on to the function and the parameter -Prefix is not set, the file name can also be given. The selec-
ted directory is noted for the duration of the Productstream Professional session and saved in the environment
variable $SaveAsDefaultDirectory. As this must be entered in a dialog window, this function is not suitable for
use in a background process.
The one or more files are then copied from the server to this directory. The parameter -Prefix can be used to
simultaneously copy the directory tree, as well.
A transaction is not carried out, i.e. copy or overwrite actions performed on existing files cannot be undone by
means of a rollback.
This function is implemented in different ways on the Windows and Web clients (see below under Notes).

Syntax
___CopyFilesToLocal ( [-Prefix="<Directory>"] [-NoConfirm] [-Silent] [-Ext] [-AdditionalFile="<FileNa-
me>"]<SourceFiles>);

Parameters
[-Prefix=“<Directory>“]
If this parameter is given, the directory tree is copied as well outgoing from the specified path. The source files
must then be handed over by specifying the path relative to this path.
A copy of the folder tree is generated in the local target directory. Missing directories are automatically gene-
rated at the same time. If a source file is located elsewhere and not in the specified directory, the full path to
this file is mapped subordinate to the selected target directory. In the case of source files, the operator for scrol-
ling to a higher hierarchy level ("..\") is not supported.
When handing over a single source file, stating this parameter means that it is only possible to select a directory
in the dialog window, and not a file name, and that a directory tree is created for just this one file.
If this parameter is not given and multiple files are being handed over, the files are copied next to one another
to the selected directory.
[-NoConfirm]
Suppresses the acknowledge dialog for overwriting files if the target directory already contains a file of the same
name. Files of the same name in the target directory are then overwritten without requiring user confirmation.
[-Silent]
Flag for suppressing the success message at the end of the copy routine. Error messages issued upon completion
of the copy routine are not suppressed by this flag.
[-Ext]
If this flag is set, files of the same name, but with a different extension, are copied as well while retaining the
extensions (analog to ___Shell (cpext …) ).
[-AdditionalFiles=“<FileName>“]
This flag can be used to specify an additional file (e.g. export log). This file is not included in the number of
copied files, nor is the user prompted for confirmation when it is overwritten.
<SourceFiles>
A single file or multiple files separated by a space. File names which contain a space or begin with one of the
keywords -Prefix, NoConfirm or -Silent must be given in quotation marks.

Return Values
Value Description
0 Command was run successfully and all files were copied
 118

Value Description
+1 Command was run successfully, but not all files were copied (only if -NoConfirm has
not been set and the user has selected the option "do not overwrite". If an error -3, -4
or -5 occurs with one of the files, +1 is not returned). This value is also returned if all
of the files have been copied, but the export summary (where the flag -Log has been
set) could not be written.
-1 File names are missing or the parameters are incorrect (e.g. a keyword is missing or
has an invalid value)
-2 Cancel selected in the dialog window
-4 Source files do not exist or cannot be read
-5 Target files cannot be written
-6 Target directory does not exist or cannot be generated
-7 Source and target files are identical
-8 Invalid format for a target or source file name
-10 Several -4, -5, -6 or -7 errors have occurred
-11 No arguments specified
<0 Error (no further details given, error message in the file errlog.err)

Notes
Multiple file names must be separated by spaces when they are handed over. Any of these file names which
contain spaces must be given in quotation marks. Quotation marks are also required if a file name begins with
the keywords Prefix, NoConfirm, -Ext or Silent (the keywords are not case-sensitive, which means that this
requirement also applies where such names are lower-case).
The function also checks whether the source and target files are identical. In such cases, the file concerned is
not copied. This check is performed by means of a string comparison. Physically identical files with a different
drive alias are therefore not recognized as being identical.
This function is not suitable for use in background processes as dialog input is mandatory.
The default title of the dialog window is "Save file locally" or "Save files locally" (in the case of multiple files).
When used in the Web client, a compressed file is created for downloading. Here, the parameters Confirm,
Silent and -Prefix refer to the compression routine.
The restriction in DBP programming (254 characters) also applies to the parameter length. Multiple files
should therefore be handed over using a substitution function (see Examples).
 119

Examples
Selected files are to be copied to a directory, whereby identical file names with a different extension are to be
copied as well and an export summary is to be created:
___Environment ( MapName=#(Map create) );
___Selection ( enumerate __Mark__ AddDataToMap $MapName );
___CopyFilesToLocal ( #(Map ValuesAsListQ $MapName ) –Ext );

public AddDataToMap, AIM_AddDataToMap

Procedure AIM_AddDataToMap
___Map ( set $(arg:v1) $(Map size $(arg:v1))=#(DOCNAME0) );
endproc;
The function ___Selection is used to call the function AddDataToMap for each marked object in
Productstream Professional after a map MapName has been created. As the index of the map is null-based, the
map size (0) can be handed over as the key the first time the function is called. Every subsequent call increments
the map size by 1, so that each record is assigned a different key. Finally, a character string is generated from
the map records usingValuesAsListQ, in which each file name is given in quotation marks and the file names
are separated by spaces. This character string is then handed over to the function CopyFilesToLocal.
Copying selected files and the directory tree:
___Environment ( MapName=#(Map create) );;
___Environment ( len1=#(= strlen(strprep(“$(DATPATH)“))) );
___Selection ( enumerate __Mark__ AddDataToMap $MapName );
___CopyFilesToLocal ( -Prefix=”$(DATPATH:t)” #(Map ValuesAsListQ $MapName ) );
Public AddDataToMap, AIM_AddDataToMap
Procedure AIM_AddDataToMap
___Environment ( len2=#(= strlen(strprep(“#(DOCNAME0)”))) ) ;
if( comp(“$(DATPATH:At)”, “#(DOCNAME0:At)”) )
___Map ( $(Arg:v1) $(Map size $(arg:v1))=#(= substr(strprep(“#(DOCNAME0:t)”), $len1, #(=
$len2 – $len1)) ) );
else
___Map ( set $(Arg:v1) $(Map size $(arg:v1))=#(DOCNAME0) );
Endproc;

See also
"___Map, Map" on page 163
"___Shell" on page 192
 120

___DbUtils
Collection of utility functions for updating and synchronizing databases, internal program buffers and the
Productstream Professional GUI.

Syntax
___DbUtils ( <Parameter> <Arguments> );

Parameters

Parameter Argument Description

Sync Current The current object is updated. The number 4 can be used instead.
App All the objects in the opened context are updated. The number 5 can be
used instead.
Version 5.2.1.2
All All the objects in the current context are updated. The number 3 can be
used instead.
Sele [<DbViewName>] The caches of all the selections are purged. If DbViewName is defined,
only those selections which have been defined for this view are purged.
The number 11 can be used instead.
Version 5.4.0.7
NoSync The objects are no longer updated. Updating can be reactivated using
Sync App
View Refresh The currently displayed context is updated.
Regen The update routine for the current context is run, whereby the database is
reselected.
RegenAll The update routine for the parent context is run. All the contexts are
updated, whereby the database is reselected.
Invalidate The current parent context is initialized. A context is not updated.
Mark {AllOff|AllClear|FiltOff|FiltClear} [Show] Marks every object. All the displayed(!) objects are now marked (all the
specified flags are identical). If Show is given as well, the current marking
for the context is also displayed.
{AllOff|AllClear|FiltOff|FiltClear} [Show] Removes the markings for the objects. None of the objects are now mar-
ked (all the specified flags are identical). If Show is given as well, the cur-
rent marking for the context is also displayed.
{AllToggle|FiltToggle} [Show] Inverts the marking. All the objects which were previously not marked are
now marked (or vice-versa) (all the specified flags are identical). If Show is
given as well, the current marking for the context is also displayed.
{On|Set} [Show] Marks the current object (all the specified flags are identical). If Show is
given as well, the current marking for the context is also displayed.
{Off|Clear} [Show] Removes the marking for the current object (all the specified flags are
identical). If Show is given as well, the current marking for the context is
also displayed.
Toggle [Show] Switches the marking for the current object. If Show is given as well, the
current marking for the context is also displayed.
Tab First Activates the first property tab for the current context (see also:
___RecordBuffer __GUIViewParent__).
Version 5.2.1.4
Last Activates the last property tab for the current context (see also:
___RecordBuffer __GUIViewParent__).
Version 5.2.1.4
Next Activates the next property tab for the current context. If the last property
tab is already active, no changes are made (see also: ___RecordBuffer
__GUIViewParent__).
Version 5.2.1.4
 121

Parameter Argument Description

Prev Activates the previous property tab for the current context. If the first pro-
perty tab is already active, no changes are made (see also: ___RecordBuffer
__GUIViewParent__).
Version 5.2.1.4

Return values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
A semi-colon ";" can also be used between the arguments. However, it is advisable to use spaces as separators.

Examples
Updating the current RecordBuffer
___RecordBuffer ( call __CURRENT__ ___DbUtils Sync Current );
As this function is performed directly on the record buffer, the modified data is updated directly in its window.
Marking all data records and displaying the markings immediately
___DbUtils ( Mark AllOn Show );
All the visible data records are marked and the markings are displayed.

See also
"___RecordBuffer, RecordBuffer" on page 177
 122

___DeleteRecord
Used to physically delete an object and all the associated files belonging to DocumentType objects. The
logged-on user must have delete rights for the object to run this function.

Syntax
___DeleteRecord ( [2] [;<ShellCommand>] );

Parameters
[2]
The data record is deleted without acknowledgement. If a flag is not defined, the user is required to acknow-
ledge that the file is to be deleted.
[;<ShellCommand>]
ShellCommand is substituted in relationship to the data record and then run once the record has been success-
fully deleted.

Return Values
Value Description
0 Command executed successfully
1 Command failed due to a read error
2 Command failed as the object is locked
3 User has selected Do not delete in the dialog window
4 User has clicked Escape in the dialog window
5 Command failed as the record has already been deleted
6 Command failed as the object has been modified in the meantime
7 Command failed (another error)
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
• When an objects is deleted, all the assigned files are deleted as well. This also applies to secondary files
(#DOCNAME1 - 9).
• Multiple files can be deleted using ___Selection.

Examples
Deleting the current object incl. all the associated files:
___DeleteRecord ( 2 );
The current object is deleted without user acknowledgement. Any errors which may occur are logged in the
file Errlog.err in the current working directory.

See also
"___Selection" on page 185
 123

___DWFUPDATESYNC
Updating the DWF file of the primary document. Missing or outdated DWF files are created. This function
allows DWF files to be updated concurrently at multiple client workstations.

Syntax
___DWFUPDATESYNC ( [<ConflictReturnValue>] );

Parameters
< ConflictReturnValue> (optional).
The number given here is used as a return value if the update function is being used by another workstation.
0 is used unless specified otherwise.

Return values

Value Description
? Return value for the function CreateDWF. This function is called in
or ___DWFUPDATESYNC

< ConflictReturnValue> If the update function is being run from another workstation.
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
This function uses a semaphore file for synchronizing with concurrent updates. The path name of the DWF
file to be created is used as the file name with the extension “.semdwf”.
This function determines the name of the DWF file to be created by substituting con #(DTY:ContainerAu-
toDWF). In the current context.

See also
"Formats" on page 69
 124

___EditFilter
Calls the Advanced search function.

Syntax
___EditFilter ( [-p] [<GUIViewObject>] );

Parameters
[-p]
If -p is given as well, the GUIView object is opened and the Save button is activated. This allows the Advanced
Search criteria to be modified. Otherwise, only one new Advanced Search can be saved.
[<GUIViewObject>]
If <GUIViewObject> is defined, the Advanced Search dialog window is opened with the specified GUIView
object. Otherwise, the GUIView object ExtendedSearch is used.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The Advanced Search handles a record buffer for the EntityType object AIM.FOLDER.
If the current object in the runtime environment has not been assigned to this EntityType object, a new record
buffer is generated for the FolderType object. This is filled with ENTITY_TYPE = AIM.FOLDER and used
at the start of the dialog. If the current object in the runtime environment is a type AIM.FOLDER object, it
is used to open the Advanced Search dialog window without further handling.
This behavior is used to display the contents of saved Advanced Searches for processing.
 125

___EnumFields
Calls a function for each field in an object, whereby all the configured fields in the EntityType object and/or
Folder object and/or GUIView object apply.

Syntax
___EnumFields ( <FunctionName> );

Parameters
<FunctionName>
Function which is to be run for each field in the current object. Productstream Professional expressions may
not be used.
The function is started with the following arguments:

No. Argument Note

1 Field name
2 Field type
3 Field length
4 Decimal positions
5 Field type (from COMPASS 2000 always 0 -> compatibility with COMPASS 4)

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
If the function <FunctionName> returns the value ?0 after being run, the function ___EnumFields is also pre-
maturely terminated with the return value ?0.

Examples
Displaying all the field values in an object:
Public DataView,AIM_DataView
Procedure AIM_DataView
___Environment ( Info=$(Info)$(arg:v1) = #($arg:v1)) );
___Environment ( Info=$(Info)@(\n) );
Endproc
...
___Environment ( Info= );
___EnumFields ( DataView );
___Shell ( read()$Info );
In the top part, a function has been defined which saves <FieldName>=<FieldValue> with a closing <Return>
in the variable Info. Before the function is actually called, the variable Info is emptied. This function is then
run for each field and the value of Info is displayed using ___Shell read().
 126

___EnumToken
Checks a string using a freely definable function. The string is disassembled into tokens (values up to the
spaces), and the function is run for each token.

Syntax
___EnumToken ("<String>" <FunctionName> );

Parameters
"<String>"
String which is to be checked. Productstream Professional expressions may be used.
<FunctionName>
Function which is to perform the check. Productstream Professional expressions may not be used.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
If the function <FunctionName> returns the value ?0 after being run, the function ___EnumToken is also
prematurely terminated with the return value ?0.

Examples
Checking the description (field LONG_DESC) for the word "New":
Public DataCheck,AIM_DataCheck
Procedure AIM_DataCheck
If ( comp("New","$(arg)") )
Return (-1);
Else
Return (0);
Endproc
...
___EnumToken ( "#(LONG_DESC)" DataCheck );
If ( eq("0","$Errorlevel") )
{
<Source code: New not included>
}
Else
{
<Source code: New included>
}
In the first part, a function is defined in which the argument is checked for the word New. Further down, the
function is then started and every single word in the field LONG_DESC is checked by the Check function.
If the field contains the word New, the return value -1 is defined and the function is prematurely terminated.
 127

___Environment
Fills variables with values, whereby field values or functions can be used.

Syntax
___Environment ( <Parameters> <Arguments> );

Parameters

Parameter Arguments Description

[set] <Variable>=<Value> Fills the variable <Variable> with the value <Value>. Multiple variables can be filled by
separating them with semi-colons. The parameter set does not have to be specified.
ReadOnly <Variable> Sets the given variable to write-protected. This variable can now no longer be changed.
Export <Variable> The specified variable is passed on to the DOS shell, where it is recognized (this only
applies if the DOS shell is opened from within Productstream Professional).
Write <FileName> All the filled variables are written to the specified file. If a path is not given, the field is cre-
ated in the current working directory.
xWrite <FileName> All the filled variables are written to the specified file. If a path is not given, the field is cre-
ated in the current working directory (synonymous with Write <FileName>).

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
Caution!
Since version 5.2.1.0, variable names are no longer case-sensitive.

Examples
Filling variables:
___Environment ( aktIdent=#IDENT; aktRevision=#REVISION );
The two variables aktIdent and aktRevision are filled with the field values using a single command.
Writing all the known variables to a single file:
___Environment ( Write "$(WsPath:|+)current.txt" );
___Environment ( Write "current.txt" );
Both commands save all the variables and their values to the file current.txt. WsPath is used automatically if a
folder is not specified (as in the second case)..

See also
"Formats" on page 69
 128

___ErrLog
Adds a specified text to the file errlog.err in the current working directory.

Syntax
___ErrLog ( <Text> );

Parameters
<Text>
The specified text is entered in the file errlog.err with the flag 99999 and the name of the current Folder object.
The entire string is substituted in the current object before it is executed.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The actual date and time, together with the flag 99999, are always entered.

Examples
Entry in the file errlog.err:
___ErrLog ( This is a message in errlog.err for _ #IDENT:#SHORT_DESC );
The text is entered in the file errlog.err.

See also
"Formats" on page 69
 129

___ExecuteSQL
Executes a saved SQL script in the current database. A file is selected from a selection dialog window, substi-
tuted and then executed.

Syntax
___ExecuteSQL ( [<FileName>] );

Parameters
[<FileName>]
If a file name has been specified, it is proposed in the selection dialog window and the given path is entered by
default.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The contents of the file is read into the many. All the lines up to a GO are substituted and executed using the
function ___XdwCmd. Then the next lines up to the GO are read.
The rights defined in Productstream Professional are not taken into consideration when performing the SQL
statement.
The dialog window for selecting the file is always opened and cannot be suppressed.
The entire string is substituted in the current element before it is executed.
The command can also be called as standard using the keyboard shortcut <Ctrl>+<F11>.

Example
Executing an external SQL file:
___Environment ( SqlFile="$(PrgPath:|+)update.sql" );
___ExecuteSQL ( $(SqlFile) );
The SQL file is defined in the variable $(SqlFile) and the selection dialog window is displayed with this file.
The user can then execute the SQL file by selecting Open.

See also
"Formats" on page 69
"___XdwCmd" on page 213
 130

___ExportCollect
This function combs the database and collates all the objects, relationship types and history records. This is
usually done using rules and instructions defined in ExportDataObject. This object is filled using the function
___ExportDlg. Unless prevented from doing so by special parameters, the function ___ExportConfirm is
called once all the data has been collated.

Syntax
___ExportCollect ( <ExportDataObject> [-NoConfirm] [<OptionalParameters>] );

Parameters
<ExportDataObject>
The ExportDataObject is assigned to this name.
See "___ExportDlg" on page 136
[-NoConfirm]
If this parameter has been defined, only the data which complies with the settings in ExportDataObject is
collated and appended to this object. If it has not been defined, the function ___ExportConfirm is called. All
the <OptionalParameters> are passed on to this function.
[<OptionalParameters>]
All other optional parameters are handed over as parameters in addition to ExportDataObject when the func-
tion ___ExportConfirm is called. This parameter is only practical if -NoConfirm has not been defined.

Return Values
Value Description
0 The function was performed successfully. This includes the call for ___ExportDlg if -
Sele was not defined for ___ExportDlg.
1 The dialog window was closed with Cancel
2 The selection is empty (does not contain any objects)
3 ExportDataObject is incomplete
10 Insufficient parameters have been defined
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The sequence of the parameters must be adhered to.
The command is used in the following command chain:
___ExportDlg
___ExportCollect
___ExportConfirm
___ExportExecute
___ExportPack
___ExportDataObjectDestroy
 131

Examples
Calling the standard function for the export:
___ExportDlg ( __MARK__ NewExport );
___ExportDataObjectDestroy ( NewExport );
The standard function is started. The function ___ExportDlg calls the next required function if completed
successfully.
Explicit call of the single function for exporting the marked objects:
___ExportDlg ( __MARK__ NewExport –Sele );
If ( eq("0","$Errorlevel") )
/* Cancel */
Return ( $Errorlevel );
___ExportCollect ( NewExport –NoConfirm );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportConfirm ( NewExport –NoExecute );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportExecute ( NewExport –NoPack );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportPack ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportDataObjectDestroy ( NewExport );
Initially, the dialog is started for all the marked objects and then processed step by step. Everything is saved in
the ExportData object NewExport.

See also
"___Map, Map" on page 163
"___ExportDlg" on page 136
"___ExportCollect" on page 130
"___ExportConfirm" on page 132
"___ExportExecute" on page 139
___ExportPack (no longer supported, see "Suspended functions" on page 224)
"___ExportDataObjectDestroy" on page 134
 132

___ExportConfirm
Generates an acknowledgement dialog window with all the information from the ExportDataObject. The
command ___ExportExecute is run if OK is selected by the user.

Syntax
___ExportConfirm ( <ExportDataObject> [-NoExecute] [<OptionalParameters>] );

Parameters
<ExportDataObject>
The ExportDataObject is assigned to this name.
Siehe "___ExportDlg" on page 136
[-NoExecute]
If this parameter is defined, the dialog window is closed by clicking OK. Otherwise, the function
___ExportExecute is called. All the <OptionalParameters> are passed on to this function.
[<OptionalParameters>]
All other optional parameters are handed over as parameters in addition to ExportDataObject when the func-
tion ___ExportExecute is called. This parameter is only practical if -NoExecute has not been defined.

Return Values
Value Description
0 The function was performed successfully. This includes the call for ___ExportDlg if -
sele was not defined for ___ExportDlg.
1 The dialog window was closed with Cancel
2 The selection is empty (does not contain any elements)
3 ExportDataObject is incomplete
10 Insufficient arguments have been defined
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The sequence of the arguments must be adhered to.
The command is used in the following command chain:
• ___ExportDlg
• ___ExportCollect
• ___ExportConfirm
• ___ExportExecute
• ___ExportPack
• ___ExportDataObjectDestroy
 133

Examples
Calling the standard function for the export:
___ExportDlg ( __MARK__ NewExport );
___ExportDataObjectDestroy ( NewExport );
The standard function is started. The function ___ExportDlg calls the next required function if completed
successfully.
Explicit call of the single function for exporting the marked objects:
___ExportDlg ( __MARK__ NewExport –Sele );
If ( eq("0","$Errorlevel") )
/* Abbruch */
Return ( $Errorlevel );
___ExportCollect ( NewExport –NoConfirm );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportConfirm ( NewExport –NoExecute );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportExecute ( NewExport –NoPack );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportPack ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportDataObjectDestroy ( NewExport );
Initially, the dialog is started for all the marked objects and then processed step by step. Everything is saved in
the ExportData object NewExport.

See also
"___Map, Map" on page 163
"___ExportDlg" on page 136
"___ExportCollect" on page 130
"___ExportConfirm" on page 132
"___ExportExecute" on page 139
___ExportPack (no longer supported, see "Suspended functions" on page 224)
"___ExportDataObjectDestroy" on page 134
 134

___ExportDataObjectDestroy
The ExportDataObject of the specified name is deleted from the memory.

Syntax
___ExportDataObjectDestroy ( <ExportDataObject> );

Parameters
<ExportDataObject>
The given ExportDataObject is deleted from the memory.
See ___ExportDlg

Return Values
Value Description
0 Command concluded successfully
3 ExportDataObject is incomplete
4 ExportDataObject is invalid
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The sequence of the arguments must be adhered to.
The command is used in the following command chain:
• ___ExportDlg
• ___ExportCollect
• ___ExportConfirm
• ___ExportExecute
• ___ExportPack
• ___ExportDataObjectDestroy

Examples
Explicit call of the single function for exporting the marked objects:
___ExportDlg ( __MARK__ NewExport -Sele);
If ( eq("0","$Errorlevel") )
/* Cancel */
Return ( $Errorlevel );
___ExportCollect ( NewExport –NoConfirm );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportConfirm ( NewExport –NoExecute );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportExecute ( NewExport –NoPack );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportPack ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportDataObjectDestroy ( NewExport );
Initially, the dialog is started for all the marked objects and then processed step by step. Everything is saved in
the ExportData object NewExport. Finally, the ExportData object NewExport is deleted from the memory.
 135

See also
"___Map, Map" on page 163
"___ExportDlg" on page 136
"___ExportCollect" on page 130
"___ExportConfirm" on page 132
"___ExportExecute" on page 139
___ExportPack (no longer supported, see "Suspended functions" on page 224)
"___ExportDataObjectDestroy" on page 134
 136

___ExportDlg
The Export dialog window is made available to the user for the marked data records or a named selection. The
name of the ExportDataObject, the export directory and the export name, as well as any remarks and links
which are to be exported, are defined here.

Syntax
___ExportDlg ( {<SelectionName>|__MARK__} <ExportDataObject> [-Sele] [<OptionalParameters>] );

Parameters
Note
i !
Parameters are case-sensitive!

{<SelectionName>|__MARK__}
If a selection name is defined, the entries are used for the export process. The flag __MARK__ can be used for
the currently marked objects.
<ExportDataObject>
ExportDataObject is generated as a map with this name (see ___Map or #(Map ...)).
The following fixed key values are defined in this map:

Key Description Affected functions

SelectedElements Name of the selection with selected data records ___ExportDlg,
___ExportCollect,
___ExportExecute
XrefTypes Name of a map with the RelationshipType selected in the dialog win- ___ExportDlg,
dow ___ExportCollect
EntityTypes Name of a map with the EntityType object selected in the dialog win- ___ExportDlg,
dow ___ExportCollect
<EntityType> = {0|1} (1 = incl. structure)
EntityTypesAll Name of a map with the general EntityType object selected in the dia- ___ExportDlg,
log window ___ExportCollect
<EntityType> = {0|1} (1 = incl. structure)
ExportElementCount Number of objects to be exported. Is established in ___ExportCollect ___ExportCollect,
and shown in ___ExportConfirm ___ExportConfirm
ExportFilesCount Number of files to be exported. Is established in ___ExportCollect and ___ExportCollect,
shown in ___ExportConfirm ___ExportConfirm
ExportFilesSize Total size of the files to be exported. Is established in ___ExportCollect ___ExportCollect,
and shown in ___ExportConfirm ___ExportConfirm
OutputDirectory Name of the export directory ___ExportDlg,
___ExportConfirm,
___ExportExecute,
___ExportPack
OutputFileName Name of the export directory, export file and extension ___ExportDlg,
___ExportConfirm,
___ExportPack
ExportDesc Export description entered in the dialog window ___ExportDlg,
___ExportExecute
AllElementFolders All the affected Folder objects in the collated objects. Is established in ___ExportCollect,
___ExportCollect and evaluated in ___ExportExecute. ___ExportExecute
AllHistoryFolders All the affected HistoryFolder objects in the collated objects. Is establis- ___ExportCollect,
hed in ___ExportCollect and evaluated in ___ExportExecute. ___ExportExecute
AllElements Name of the map containing all the objects. Is established in ___ExportCollect,
___ExportCollect, shown in ___ExportConfirm and evaluated in ___ExportExecute
___ExportExecute.
 137

Key Description Affected functions

AllXrefs Name of the map containing all the RelationshipTypes. Is established ___ExportCollect,
in ___ExportCollect, shown in ___ExportConfirm and evaluated in ___ExportExecute
___ExportExecute.
AllHistory Name of the map containing all the history records. Is established in ___ExportCollect,
___ExportCollect, shown in ___ExportConfirm and evaluated in ___ExportExecute
___ExportExecute.

Other key values also exist, but these are only used internally. ___Map or #(Map ...) can be used to display all
the key values.
[-Sele]
If this parameter is defined, the dialog window is closed by clicking OK. Otherwise, the function
___ExportExecute is called. All the parameters are passed on to this function.
[<OptionalParameters>]
All other optional parameters are handed over as arguments in addition to ExportDataObject when the func-
tion ___ExportExecute is called. The parameters are ignored if the flag -Sele has been defined.

Return Values
Value Description
0 The function was performed successfully. This includes the call for ___ExportDlg if -
Sele was not defined for ___ExportDlg.
1 The dialog window was closed with Cancel
2 The selection is empty (does not contain any objects)
3 ExportDataObject is incomplete
10 Insufficient parameters have been defined
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The sequence of the parameters must be adhered to.
The command is used in the following command chain:
• ___ExportDlg
• ___ExportCollect
• ___ExportConfirm
• ___ExportExecute
• ___ExportPack
• ___ExportDataObjectDestroy

Examples
Calling the standard function for the export:
___ExportDlg ( __MARK__ NewExport );
___ExportDataObjectDestroy ( NewExport );
The standard function is started. The function ___ExportDlg calls the next required function if completed
successfully.
 138

Explicit call of the single function for exporting the marked objects:
___ExportDlg ( __MARK__ NewExport –Sele );
If ( eq("0","$Errorlevel") )
/* Cancel */
Return ( $Errorlevel );
___ExportCollect ( NewExport –NoConfirm );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportConfirm ( NewExport –NoExecute );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportExecute ( NewExport –NoPack );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportPack ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportDataObjectDestroy ( NewExport );
Initially, the dialog is started for all the marked objects and then processed step by step. Everything is saved in
the ExportData object NewExport.

See also
"___Map, Map" on page 163
"___ExportDlg" on page 136
"___ExportCollect" on page 130
"___ExportConfirm" on page 132
"___ExportExecute" on page 139
___ExportPack (no longer supported, see "Suspended functions" on page 224)
"___ExportDataObjectDestroy" on page 134
 139

___ExportExecute
The data records and files from the ExportDataObject are copied to the export directory, whereby the file
COMPASS_Export.ini is created.

Syntax
___ExportExecute ( <ExportDataObject> [-NoPack] [<OptionalParameters>] );

Parameters
<ExportDataObject>
This name identifies the export data object.
See "___ExportDlg" on page 136
[-NoPack]
If this parameter has been defined, the function is terminated once the objects and files have been successfully
collated. Otherwise, the function ___ExportPack is called. All the <OptionalParameters> are passed on to this
function.
[<OptionalParameters>]
All other optional parameters are handed over as parameters in addition to ExportDataObject when the func-
tion ___ExportPack is called. This parameter is only practical if -NoPack has not been defined.

Return Values
Value Description
0 The function was performed successfully. This includes the call for ___ExportDlg if -
sele was not defined for ___ExportDlg.
1 The dialog window was closed with Cancel
2 The selection is empty (does not contain any objects)
3 ExportDataObject is incomplete
10 Insufficient parameters have been defined
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The sequence of the parameters must be adhered to.
The command is used in the following command chain:
• ___ExportDlg
• ___ExportCollect
• ___ExportConfirm
• ___ExportExecute
• ___ExportPack
• ___ExportDataObjectDestroy

Examples
Calling the standard function for the export:
___ExportDlg ( __MARK__ NewExport );
___ExportDataObjectDestroy ( NewExport );
The standard function is started. The function ___ExportDlg calls the next required function if completed
successfully.
 140

Explicit call of the single function for exporting the marked objects:
___ExportDlg ( __MARK__ NewExport -Sele);
If ( eq("0","$Errorlevel") )
/* Cancel */
Return ( $Errorlevel );
___ExportCollect ( NewExport –NoConfirm );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportConfirm ( NewExport –NoExecute );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportExecute ( NewExport –NoPack );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportPack ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ExportDataObjectDestroy ( NewExport );
Initially, the dialog is started for all the marked objects and then processed step by step. Everything is saved in
the ExportData object NewExport.

See also
"___Map, Map" on page 163
"___ExportDlg" on page 136
"___ExportCollect" on page 130
"___ExportConfirm" on page 132
"___ExportExecute" on page 139
___ExportPack (no longer supported, see "Suspended functions" on page 224)
"___ExportDataObjectDestroy" on page 134
 141

___FolderBar
The Productstream Professional status bar is displayed or hidden. This function can only be used if the default
configuration is used for the GUIView hierarchy.

Syntax
___FolderBar ( [0|1|2|3] );

Parameters
0
The Productstream Professional bar is switched over. This parameter is also used if a flag has not been given.
1
The Productstream Professional bar is displayed
2
The Productstream Professional bar is hidden
3
The Productstream Professional bar is not changed. This parameter is only used to query the current status
using the return value 1 or 0.

Return Values
Value Description
0 Productstream Professional bar is activated (visible)
1 Productstream Professional bar is deactivated (hidden)

Notes
The function evaluates the flag condition itself. If this is shown in the menu, no further conditions are defined
for displaying the check mark.

Examples
Switching over the Productstream Professional status bar:
___FolderBar ();
Querying the current status of the Productstream Professional status bar:
___FolderBar ( 3 );
If ( eq("0","$Errorlevel") )
{
<Source code: Productstream Professional bar is visible>
}
Else
{
<Source code: Productstream Professional bar is hidden>
}
The command is run without changing the current status, followed by an evaluation of the return value.

See also
 142

___FolderStructure
The folder structure is displayed or hidden. This function can only be used if the default configuration is used
for the GUIView hierarchy.

Syntax
___FolderStructure ( [0|1|2|3] );

Parameters
Parameter Description
0 The folder structure is switched over. This parameter is also used if a flag has not been
given.
1 The folder structure is activated
2 The folder structure is hidden
3 The folder structure is not changed. This parameter is only used to query the current
status using the return value 1 or 0.

Return Values
Value
0 Folder structure is deactivated (hidden)
1 Folder structure is activated (visible)

Notes
The function evaluates the flag condition itself. If this is shown in the menu, no further conditions are defined
for displaying the check mark.

Examples
Switching the folder structure:
___FolderStructure ();
Querying the current status of the folder structure:
___FolderStructure ( 3 );
If ( eq("0","$Errorlevel") )
{
<Source code: Folder structure is visible>
}
Else
{
<Source code: Folder structure is hidden>
}
The command is executed without changing the current status. Afterwards, the return value is evaluated.
 143

___ForceUnLock
This function is used to revoke the exclusive reservation of an element in Productstream Professional, even if
the reservation has been set by and for another user. As a result, the current element can be accessed again by
all other users (according to their permissions).
If Productstream Professional Access Control Manager (ACM) is installed, this also applies to the rights to tho-
se files dependent on a type AIM.DOC object.

Syntax
___ForceUnLock();

Parameters
(None)

Return Values
Value Description
0 UnLock has been successful. The element is no longer exclusively reserved. This return value is also
valid if the element has not been reserved prior to executing this function.
2 The user currently logged on does not have the permission to perform this function.
Precise: the condition function isForceUnLockGrpMember returns the value FALSE.
3 Revoking the reservation by the application is not possible or has not been successful.
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
This internal function itself evaluates the dynamic condition. If the function is shown in the menu, it deacti-
vates the menu according to the current object.

Programming:
The behavior can be influenced by the public function PreForceUnLock.
___ForceUnlock checks whether this function is defined for the current element. If this public function has
been defined it is performed before the lock is actually removed, but not until all other rights have been che-
cked. This function is called without any arguments.
If the return value is 0 or 1, the lock can be removed. If the return value is 2, the lock is not removed. If the
return value is unequal to 0, ___ForceUnlock itself sets the return value to 3 (see Return Values). In this case,
it is assumed that an error message has been issued for the environment variable ApplLockErrMsg in the func-
tion PreForceUnlock.

Examples
Revoking the reservation with a subsequent feedback:
...
___ForceUnLock ();
If ( eq("0","$ErrorLevel") )
___Shell ( read()Lock has been successfully removed! );
Else
___Shell ( read()Lock could not be removed! );

See also
"___Lock" on page 161
"___UnLock" on page 203
 144

___ForRela, ___ForRelaH, ___ForAllRela, ___ForAllRelaH

This arbitrary function is run on a single object or a selection of objects, whereby the selection criteria for these
objects can be defined as required. Only those objects for which the user has the dynamic Read (+R) right are
taken into consideration.

Function Description
___ForRela Only processes a found object. If multiple objects are found, the first one is used.
___ForRelaH As ___ForRela
Before the function is run, it checks whether any objects without the write right R have been found. If this
is the case, the function terminates with the return value -1.
___ForAllRela Processes all the objects found.
___ForAllRelaH As ___ForAllRela
Before the function is run, it checks whether any objects without the write right R have been found. If this
is the case, the function terminates with the return value -1.

Syntax
___ForRela ( [db=<FolderObject>] <SQLWhereCondition> <Function> [<Parameter>] );
___ForRelaH ( [db=<FolderObject>] <SQLWhereCondition> <Function> [<Parameter>] );
___ForAllRela ( [db=<FolderObject>] <SQLWhereCondition> <Function> [<Parameter>] );
___ForAllRelaH ( [db=<FolderObject>] <SQLWhereCondition> <Function> [<Parameter>] );

Parameters
[db=<FolderObject>]
The folder object name as defined in the configuration is specified. Herein, the SQL Where condition is exe-
cuted. The SQL view or SQL table can also be directly specified. If no folder object is specified, the current
context with the related condition is used.
<SQLWhereCondition>
The SQLWhereCondition is entered as a Where clause analog to SQL. The string must be enclosed by single
quotation marks <'>.
If multiple SQLWhereConditions are to be given, these must be enclosed in parentheses ( ... ) or double quo-
tation marks " ... ".
<Function>
The specified function is performed on the found object.
If multiple objects have been found, the function is only performed on the first object returned by SQL when
used for ___ForRela and ___ForRelaH.
[<Parameter>]
The given parameters are passed on to the function.

Return Values
Value Description
? The return value of the function is returned
0 Only those objects which are also visible due to the assigned right R are taken into
consideration. An object without read rights cannot be processed using this function.
-1 An object without the read right R has also been found, or <Function> returns this
value.

Notes
The entire string is substituted in the current object before it is executed.
 145

Only those objects which are also visible due to the assigned right R are taken into consideration. An object
without read rights cannot be processed using this function.
If the found objects are not to be processed if hidden objects are found (read rights R not present), the function
___ForRelaH or ___ForAllRelaH must be used.

Examples
Updates the associated History object by adding a default text to the description:
___ForRela ( db=Folder_History (IDENT='#(IDENT)' AND REVISION='#(REVISION)')
___ChangeField SHORT_DESC=Change);
The function searches for the history record for the currently selected engineering document in the Folder ob-
ject (db=Folder_History) using the unique ID (IDENT='#(IDENT)' AND REVISION='#(REVISION)')
and updates the field there with the new text Change (SHORT_DESC=Change).
Copying all the AutoCAD files in the elements in a project to the working directory:
___ForAllRela ( db=Folder_Xref_Parent_EngineeringDocument
(X_CHILD_AIMKEY=#AIMKEY AND FILE_TYPE='A') ___Shell cp("#(DOCNAME0)"
"$(WsPath:|+)#(DOCNAME0:f)") );
The function searches for those objects in the Folder object for the currently selected project
(db=Folder_Xref_Parent_EngineeringDocument) which have been assigned to that project
(X_CHILD_AIMKEY=#AIMKEY) and which are AutoCAD data records (FILE_TYPE='A'). The command
Copy (cp("...")) is then run in the shell for each of these hits.
Checking whether all the derived drawings of the parts used have been released:
If ( comp("IAM","#(FILE_TYPE)") )
{
___Environment ( CheckIdw=0 );
___ForAllRelaH ( db=Folder_Xref_Child_EngineeringDocument (X_PARENT_AIMKEY=#AIMKEY AND
FILE_TYPE in ('IPT', 'IAM'))
___ForAllRelaH db=Folder_Xref_Parent_EngineeringDocument (X_CHILD_AIMKEY=#AIMKEY AND
FILE_TYPE 'IDW') CheckIdw );
}
If ( eq("-1","$(ErrorLevel)") )
{
<Sourcecode: Hidden data records found!>
}
If ( lt("0","$(CheckIdw)") )
{
<Sourcecode: Data records found which have not been released!>
}
...
Public CheckIdw, AIM_CheckIdw
Procedure AIM_CheckIdw
If ( !comp("00003","#(STATUSKEY)") )
___Environment ( CheckIdw=$(CheckIdw:++) );
Endproc
The check function is started if the object is an Inventor assembly. The derived drawing is checked
(X_CHILD_AIMKEY=#AIMKEY AND FILE_TYPE 'IDW') in the Component property tab
(db=Folder_Xref_Child_EngineeringDocument) for all the parts and assemblies
(X_PARENT_AIMKEY=#AIMKEY AND FILE_TYPE in ('IPT', 'IAM') and how they are being used
(db=Folder_Xref_Parent_EngineeringDocument) using the function CheckIdw. If a found object is not
00003 (= released), the variable CheckIdw is incremented by 1. The variable is evaluated when the function
has been completed. If it is greater than 0 (lt("0","$(CheckIdw)")), this means that derived drawings which
have not been released have been found. If the return value is ¬ 1 (eq("-1","$(ErrorLevel)")), this means that
objects without read rights have been found.

See also
"___Break_Enum" on page 106
"___ForTable" on page 146
Chkref auf page 85
#where auf page 86
Field queries
Formatting
 146

___ForTable
An arbitrary function is run for a particular folder and unrelated to an object.

Syntax
___ForTable ( db=<FolderName> <Function> [<Parameter>] );

Parameters
db=<FolderName>
The Folder object name as defined in the configuration is specified. The SQL view or SQL table can also be
directly specified.
<Function>
The specified function is run in the given context.
[<Parameter>]
Any given parameters are passed on to the function, whereby the parameters are substituted for the current
object.

Return Values
Value Description
? The return value of the function is returned
0 The called function has returned this value, or no hits were found for the search crite-
ria and the Folder object name
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
The function is not performed on a particular object, but is run globally in the given context and unrelated to
an object.

Examples
Starting a new record in the Folder object Folder_Part (= product folder):
___ForTable ( db=Folder_Part New );
New is a public function and is run unrelated to an object.

See also
"___ForRela, ___ForRelaH, ___ForAllRela, ___ForAllRelaH" on page 144
"___Break_Enum" on page 106
___ForRecordCallFunc (not recommended)
"___ForTable" on page 146
Field queries
Formatting
 147

___GetLicence
This function reserves a license for the specified product license key.

Syntax
___GetLicence ( <ProductLicenseKey> [<ReservationPeriod>] );

Parameters
<ProductLicenseKey>
A license is reserved for this product (field = PRODUCT, table = SWP).
<ReservationPeriod>
A license is reserved once for the time given in seconds. If a specific period is not defined, the license is reserved
for 600 seconds (= 10 minutes).

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
A reservation is a one-off action. A repeat reservation is not triggered when the initial reservation period has
expired.
This function does not need to be used for Productstream Professional versions and their modules as licenses
are reserved automatically.
Note
With version 5.5.2 and thei ! introduction of the Network Licensing Server (FLEXlm/FLEXnet) the behaviour of the
function ___GetLicence has changed. The reservation time is not considerered any more. The parameter <Reserva-
tionPeriod> kann be declared further on but will not be interpreted any more. The licenses will be reserved until the
program is terminated. If a license with the same product license key has already been reserved, there is no reservation
of a new license. The so far reserved license will be reserved further on.

Examples
Reserving a license for COMPASS 2000 V4.1:
___GetLicense ( AIMPROF540 );
A license for COMPASS 2000 V5.4.x is reserved for 600 seconds (= 10 minutes).
Reserve a license for Autodesk Productstream COMPASS 2005 V5.2:
___GetLicense ( AIMEASY550 );
A license for Productstream Compass 2005 Pro V5.5.x is reserved until program is terminated.
 148

___ImportCheck
Checks the entire import procedure. All the objects to be imported are checked to make sure they can be taken
over without any problems arising, and to detect any conflicts with the current data.

Syntax
___ImportCheck ( [<ImportDataObject>] [-Silent] );

Parameters
[<ImportDataObject>]
This name defines the existing ImportDataObject in which all the required information is stored.
See ___ExportDlg for all the keywords in the ImportDataObject.
This parameter is only used if the entire table is to be checked directly following the execution of the function
___ImportExecute. ImportDataObject can only be called if this is the case. This parameter may not be defined
if the function is called from the menu with a single object in the temporary table as the context. In this case,
only that single object is checked for conflicts.
[-Silent]
No message windows or error messages are displayed. Errors are only commented in the file errlog.err.

Return Values
Value Description
0 Command executed successfully
1 A dialog window was closed with Cancel
2 Conflicts detected
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The check is performed in two stages:
• On the database side, the entire import procedure is checked (each generated temporary table is opened
individually).
• The Public function CheckImportElement is called for each element in the Import table.
Link elements are not taken into consideration!
The function ___ImportCheck is also called from the menu to allow individual elements to be rechecked by
the user following correction of the data.
The function ImportCheckElement is called in the EntityType hierarchy corresponding to the EntityType ob-
ject of the element to be imported. This allows the conflict check to be refined according to the particular cha-
racteristics of an EntityType object.
The context when this function is called is the element in the temporary table. The target is the folder defined
for the EntityType by the attribute IdentityFolder.
In this function, EntityTypes which manage files must take these files into account in the check.
The arguments in ___ImportCheck are passed on. The results of the check are stored in the fields
AIM_IMP_STATUS (as an identification number) and AIM_CONFLICT_DESC. Specific identification
numbers are used:

Identifier Description
0 Finished (the object has been imported using ___ImportElement)
1 Einfügen (Objekt ist neu und kann eingefügt werden)
2 Insert (the object is new and can be inserted)
<0 Negative values indicate a conflict (the object cannot be imported without being
modified)
 149

Examples
Checking the current object from the Import window:
___ImportCheck ();

See also
"___Map, Map" on page 163
"___ImportDlg" on page 150
___ImportUnPack (not supported anymore)
"___ImportExecute" on page 153
"___ImportCheck" on page 148
"___ImportElement" on page 152
"___ImportDlg" on page 150
 150

___ImportDlg
Makes the Import dialog window available to the user. The name of the ImportDataObject, the import direc-
tory and the import name, as well as any remarks and links, are defined here by selecting the import file. The
import file was created during the export routine.

Syntax
___ImportDlg ( <ImportDataObject> [-NounPack|-NoExec] [<Parameter>] );

Parameters
<ImportDataObject>
The ImportDataObject is generated as a map (see ___Map or #(Map ...)), and the keywords saved from the
import file, with this name. These keywords were previously saved to this file during the export.
At least the following keywords are given:

Key Description Betroffene Funktionen

OutputDirectory Name of the export directory ___ExportDlg,
___ExportConfirm,
___ExportExecute,
___ExportPack
OutputFileName Name of the export directory, export file and extension ___ExportDlg,
___ExportConfirm,
___ExportPack

See ___ExportDlg for all the keywords in the ImportDataObject.

[-NounPack]
The import dialog window is displayed and all the information in the dialog window is saved in the Import-
DataObject. The function is terminated if the dialog window is closed by clicking OK. The information in
the ImportDataObject is retained.
The function ___ImportUnPack is performed if the parameter is not defined.
[-NoExec]
The import dialog window is displayed and all the information in the dialog window is saved in the Import-
DataObject. If the dialog window is closed by clicking OK, the function ___ImportUnPack is called. If the
function was concluded successfully, the function ___ImportExecute is called.
The function ___ImportExecute is then performed if the parameter is not defined.
[<Parameter>]
All the given parameters are passed on to the following function.

Return Values
Value Description
0 Command executed successfully. This also includes the subsequent functions.
1 The dialog window was closed with Cancel
unequal to 0 Error (no further details given, error message in the file errlog.err)
 151

Notes
The sequence of the arguments must be adhered to.
The command is used in the following command chain:
• ___ImportDlg
• ___ImportUnPack
• ___ImportExecute
• ___ImportCheck
• ___ImportElement

Examples
Calling the standard function for the import:
___ImportDlg ( ImportData );
The standard function is started. The function ___ImportDlg calls the next required function if completed
successfully.
Explicit call of the individual functions for the import:
___ImportDlg ( ImportData -NounPack );
If ( eq("0","$Errorlevel") )
/* Cancel */
Return ( $Errorlevel );
___ImportUnPack ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ImportExecute ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
Once the dialog window has been opened, the subsequent functions are only called following successful pro-
cessing.

See also
#(Map ...)
___Map
___ImportDlg
___ImportUnPack
___ImportExecute
___ImportCheck
___ImportElement
___ExportDlg
 152

___ImportElement
Takes over the current objects from the temporary table into the Productstream Professional data inventory.

Syntax
___ImportElement ( [-Silent] );

Parameters
[-Silent]
No message windows or error messages are displayed. Errors are only commented in the file errlog.err..

Return Values
Value Description
0 Command executed successfully
1 Error in the database
unequal to 0 Error (no further details given, error message in the file errlog.err). If the error has not
occured within the database, the error belongs to the function ImportElement.

Notes
All the field contents of all the known fields in the temporary table are taken over in the Productstream
Professional tables. This function runs the commands Insert or Update according to the location of the file. If
the field AIM_IMP_STATUS has been assigned the value 1, the element is inserted; if the value 2 has been
assigned, this record already exists and it is updated. Further details about AIM_IMP_STATUS can be found
in the chapter Table description for the Import tables.
When the database part has been successfully concluded, the Public function ImportElement is called. The
function ImportElement is called in the EntityType hierarchy corresponding to the EntityType of the element
to be imported. This allows follow-on tasks to be refined according to the particular characteristics of an En-
tityType object. One of these follow-on tasks is the copying of files when the appropriate objects exist.
The context when the function ImportElement is called is the object to be imported in the temporary table.
The first parameter is the name of the corresponding target record buffer in the Productstream Professional
data inventory.

See also
#(Map ...)
___Map
___ImportDlg
___ImportUnPack
___ImportExecute
___ImportCheck
___ImportElement
___ExportDlg
 153

___ImportExecute
This function adds the objects as they are defined in the control file to the corresponding temporary tables to
be generated in the register database.

Syntax
___ImportExecute ( <ImportDataObject> [-NoShow] [-Silent] );

Parameters
<ImportDataObject>
This name defines the existing ImportDataObject in which all the required information is stored.
See ___ExportDlg for all the keywords in the ImportDataObject.
[-NoShow]
Once the data has been successfully read in, the Import folder is not displayed as a separate dialog window after
the temporary tables have been filled and any conflicts have been resolved.
[-Silent]
No message windows or error messages are displayed. Errors are only commented in the file errlog.err.

Return Values
Value Description
0 Command executed successfully
1 A dialog window was closed with Cancel
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The SQL scripts for generating the temporary tables are also included in the temporary import directory.
The function ___ImportCheck for identifying any conflicts is automatically triggered.
The configuration information for displaying the temporary tables is automatically handled.
A folder is created below the Personal Folder containing identification information about this import data.
This allows the user to display the Import folder whenever required.
Unless otherwise prevented by the use of special parameters, the temporary tables in the Import folder are
shown in a separate Productstream Professional window immediately after they have been read in. This corre-
sponds to selecting the menu option View in separate window for this Import folder.
The command is used in the following command chain:
• ___ImportDlg
• ___ImportUnPack
• ___ImportExecute
• ___ImportCheck
• ___ImportElement

Examples
Explicit call of the individual functions for the import:
___ImportDlg ( ImportData -NounPack );
If ( eq("0","$Errorlevel") )
/* Cancel */
Return ( $Errorlevel );
___ImportUnPack ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
___ImportExecute ( NewExport );
If ( eq("0","$Errorlevel") )
/* Error */
Return ( $Errorlevel );
 154

Once the dialog window has been opened, the subsequent functions are only called following successful pro-
cessing.

See also
#(Map ...)
___Map
___ImportDlg
___ImportUnPack
___ImportExecute
___ImportCheck
___ImportElement
___ExportDlg
 155

___InstallOption
Updates the current Productstream Professional environment using a specially prepared update package.
Productstream Professional is terminated automatically.

Syntax
___InstallOption ( [<DefaultPathAndFileSettings>] );

Parameters
[ <DefaultPathAndFileSettings> ]
If a default path has been specified, Productstream Professional opens the dialog window with the update pa-
ckage in this path. The extension VOR is always used. It is always added if a default file has been specified.
*.vor is always used automatically if a default file has not been specified.
If the default path and file settings contain spaces, the specified parameters must be given in quotation marks.

Return Values
Value Description
0 Command executed successfully and the current Productstream Professional windows
is closed
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
Productstream Professional is terminated once the installation program has started successfully. This enables
the installation program to overwrite those EXE and DLL files which are used by Productstream Professional.
However, users are not automatically disconnected from the system, as they could be using some of the files.
Only the current Productstream Professional dialog window is closed. The update may fail if another dialog
window is still open.

Programming
The exact function procedure is as follows:
• Message: Productstream Professional will be terminated if the installation program starts correctly. Do you
want to continue with the installation (Y/N)? (Text from the file cmp4.tex, text number 981). No ' Cancel-
lation
• Open file - dialog window for selecting a *.VOR FILE. The function is terminated if a file is not selected or
the user clicks Cancel. (Text in the Open file dialog window from the file cmp4.tex, text number 980).
• The variable $(InstOptVor) is filled with the path name of the selected file.
• The file $(InstOptVor) is read and its contents are substituted to $(WsPath:|+)InstOpt.env. This enables
the entire current environment to be handed over to this file as information. In particular, the variables Prg-
Path, DatPath, CmpExe, CmpEtc and all the other variables named in COMPASS.INI in the section [Path]
are made available.
• The program adjacent to the selected file and with the same name is then launched. This program must be
of the type EXE, CMD or BAT.
• The argument $(InstOpt) is handed over (without an extension or path!). However, this file is located in the
current program system directory.
• The current directory for executing the program is $(WsPath).
• COMPASS.EXE terminates itself when this program has been launched successfully.
 156

Examples
Updating a DLL (new.dll) in the current Client directory:
Contents of the file setup.vor:
@echo souoff
@echo.
@echo The file "new.dll" is being installed in the Client
@echo.
@echo $(CMPEXE: \- p \+)cai\aim_dlls
@echo.
@echo directory!
@echo.
@echo Please wait until Productstream Professional has quit completely.
@Pause
rem -------------------------------------------
rem Copying the file to the local directory
@copy "$(InstOptVor:p\+)new.dll" "$(CmpExe:\-p)cai\aim_dlls\new.dll"
rem -------------------------------------------
rem Registering the copied file
@regsvr32 "$(CmpExe:\-p)cai\aim_dlls\new.dll"
rem -------------------------------------------
@echo finished
@pause
@exit
Contents of the file setup.bat:
@echo off
@copy "%1.env" "%1.bat"
@clear
@call "%1.bat"
@echo. The installation has failed!
@Pause
The following files must be situated next to one another in the same folder in order for this example to function
correctly:
Setup.vor
Setup.bat
new.dll

See also
Formatting
Variables
___Prepare
 157

___JobCreate
Generates a job for Productstream Professional Jobserver for the current object (this function is only made
available if a valid Productstream Professional Jobserver license is found).

Syntax
___JobCreate ( [<JobTypeId>] [-Silent] [-Auto] [-SeleOnly -Selected=<Variable>] [-Selected=<Variable>] )
[<Title>];

Parameters
[<JobTypeId>]
If a JobType ID is specified, the job is created immediately for the current object provided it is a valid job for
this object. If the specified JobType ID cannot be found, the selection dialog window opens.
[-Silent]
Error messages are not displayed to the user. They are only documented in the file errlog.err.
[-Auto]
If only one valid job is found for the current object, it is created immediately and the selection dialog window
is not opened.
[-SeleOnly -Selected=<Variable>]
The selection dialog window opens and is closed again once the user has made a valid selection. The selected
job is saved in the variable <Variable> and is not created.
[-Selected=<Variable>]
The selection dialog window opens and is closed again once the user has made a valid selection. The selected
job is saved in the variable <Variable> and is created.
[<Title>]
If a title is specified, this text is shown in the selection dialog window as the dialog title. Otherwise, the title
Select job to be run is displayed.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The list of possible jobs (JobTypes) for the current object is compiled and presented to the user for selection.
When the JobType has been selected, a job is created for the current object and placed in the queue.
The user is only able to choose a JobType in which the database field COND_CREATE_JOB is empty, or
where the contents return TRUE when interpreted as a condition with the current object.
The following additional features are made available by using arguments:
• A JobType can be defined to be selected automatically
• A JobType can be defined to be selected automatically when only one is available
• A JobType can be selected without creating a job
• All user interaction can be suppressed
The generation of the Ident value for a job that is to be performed can be influenced using the environment
variable $JobIdentPostfix. The first 3 characters are added to the job number. If $JobIdentPostfix is not po-
pulated in a replicated environment, the value of $LOCATION is used automatically. Each location in a re-
plicated environment requires a unique postfix. This is achieved with $LOCATION and can be influenced
using $JobIdentPostfix if required.
 158

Examples
Executing a job immediately using the ID JOBTYPE-00001:
___JobCreate ( JOBTYPE-00001 –Silent –Auto );
The job is generated for the current object. If the job is not suitable for the current object (e.g. because "DWG"
is given in the condition but the current object is an IDW), a job is not created and the program code is con-
tinued. A dialog is not displayed.
Automatically generating a job according to the document type (if available):
The following jobs are defined:
JOBTYPE-001-DWG -> For AutoCAD drawings
JOBTYPE-001-IDW -> Inventor derived drawings
JOBTYPE-001-DOC -> For WinWord
JOBTYPE-001-XLS -> For Excel
Markings of multiple objects in the folder Engineering folder___Selection ( enumerate
__MARK__ ___JobCreate JOBTYPEID-001-#(DOCNAME0:Ae) -Silent -Auto );
In the case of the jobs listed above, the suitable job is generated automatically for each object (if available). The
flag #(DOCNAME0:Ae) is used to identify the extension of the primary document and to attach the job name.

See also
Formattings
___Selection
 159

___LinkElement
Two objects are linked using the XREF_ELEMENT table providing the link has been defined.

Syntax
___LinkElement ( {<Recordname> | AIMKEY=<Aimkey>} [ID=<RelationshipId>] ["<Fieldname>=<Va-
lue>"] ["<other <FieldsN>=<ValueN>>"] );

Parameters
<Recordname>
The defined object is linked with the current object by specifying the parameter <Recordname>.
AIMKEY=<Aimkey>
The defined object is linked with the current object by specifying the parameter <Aimkey>.
[ID=<RelationshipId>]
This flag is only required if multiple RelationsType objects (Relationship_Type table) have been defined for
the two objects to be linked. The defined <RelationshipId> must always be suitable for both objects. If the
parameter is not defined, the suitable RelationsType object is ascertained automatically. An error is returned
if no unique RelationsType object can be found.
["<Fieldname>=<Value>"] ["<other <FieldN>=<ValueN>>"]
If a link is successful, the defined field <Field> is filled with the value <Value>, whereby multiple fields can be
specified if they (incl. the value) can be enclosed in quotation marks. A field name ID cannot be given as this
flag is already being used.

Return values
0 Command executed successfully
1 The link already exists (the value can be treated as a successful value if necessary)
2 No valid RelationsType object (RelationshipId) found
3 Multiple valid RelationsType objects (RelationshipId) found (here the flag ID=<RelationshipId> is manda-
tory)
4 The object is linked to itself
5 Parameters <Recordname> or AIMKEY=<Aimkey> contain errors or the objects could not be found
6 An existing link spanning several levels found during the recursion check. A direct link is therefore not pos-
sible
unequal to 0Error (no further details given, error message in the file errlog.err)
Notes
The entire string is substituted in the current object before it is executed.
The EntityType object is always used as the reference for a valid RelationsType object.
#(LinkType <EntityType>) is used to ascertain the list of possible RelationsType objects for combining the
current object with the specified ElementType object <EntityType>.
 160

Examples
Automatic links:
___Environment ( FirstAimkey=#(AIMKEY) );
...
___LinkElement ( AIMKEY=$(FirstAimkey) );
Productstream Professional searches for the suitable RelationsType object for the link.
Linking with automatic recipient recognition (person to office document):
/* searching for an office document */
___Environment ( FirstAimkey=#(AIMKEY) );
...
/* searching for a person */
___LinkElement ( AIMKEY=$(FirstAimkey) "X_IS_MAIL_ADDRESS=1" );
The selected person is immediately identified to the document as the recipient when the objects are linked.

See also
LinkType
 161

___Lock
Exclusively reserves an object for the current user. All other users are only granted read rights for the current
object.

Syntax
___Lock ( );

Parameters
<None>

Return Values
Value Description
0 Command executed successfully
1 The user currently logged on does not have the right to run this function.
2 No dynamic rights available: R (read)
3 No dynamic rights available: W (write)
4 No dynamic rights available: L (reserve)
5 The original is located elsewhere. Document objects can only be exclusively reserved at the original
location.
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
If Productstream Professional Access Control Manager (ACM) is installed, the change also applies to the rights
to those files dependent on a type AIM.DOC object.
The function evaluates the dynamic rights. If the function is shown in the menu, it deactivates the menu ac-
cording to the current object.

See also
___Lock
___UnLock
___ForceUnLock
 162

___LogWrite
This function records significant events that take place in the Productstream Professional system. User-defined
events can also be logged or recorded.
Logs are used to monitor the system, and to track actions such as login / logout and access to the database.
Logged information is saved in a table and can be accessed by the administrator for analysis purposes.

Syntax
___LogWrite ( <Event>, <Data> );

Parameters
<Event>
This identifier is used to identify the log entry. Enter a unique event identifier.
This can consist of the characters A-Z, 0-9 and _, and is not case-sensitive. The length may not exceed 30 cha-
racters.
As a convention, the first 3 characters should reference your installation. All the following characters are then
used as the description.
Logging of a particular identifier is enabled and disabled in the configuration (refer to the component "LogE-
vent" in the configuration for details). The attribute "Default" defines whether logging of identifiers which are
not explicitly configured is enabled or disabled.
The following event identifiers are predefined by Productstream Professional and are handled internally:
• CMP_EXPORT
• CMP_IMPORT
• CMP_LOGIN // is always activated, independently from the the attribute under LogEvent
• CMP_LOGOUT
• CMP_F_DOWNLOAD
• CMP_F_SAVEAS
• CMP_DB_INSERT
• CMP_DB_UPDATE
• CMP_DB_DELETE
• CMP_CHANGESTATUS
<Data>
Additional logging information is stated here (a more detailed description, file names, etc.).

Return Values
0 Logging successful, started.
1 Logging disabled.
otherwise error
Notes
A unique designation of the first three letters has to be used for self-defined event identifiers!
Example: ___LogWrite( "XXX_Action", "Any action");
All internal Productstream Professional event identifiers begin with "CMP".
Logging of the login function cannot be disabled. Refer to the definitions in the configuration under "LogE-
vents" for a comparison.

Examples
Logging is triggered with the call
___LogWrite( XXX_Action “Additional Log Information“ );
For events to be recorded in the log, it is necessary to either define the attribute "Default=true" or enter an
attribute "XXX_Action=true" in the configuration under "LogEvents".

See also
 163

___Map, Map
Makes available lists or maps (similar to ___RecordBuffer ). The key values can be defined as required.

Syntax
___Map (Create <Name> [<Number>] Set <Name> <Key>=<Value> Load <Name> <Name2>
Enum <Name> <Function> Remove <Name> <Key> Destroy <Name>);
#(Map Get <Name> <Key> KeysAsCsv <Name> KeysAsCsvQ <Name> KeysAsList <Name> KeysAsListQ
<Name> ValuesAsCsv <Name> ValuesAsCsvQ <Name> ValuesAsList <Name> ValuesAsListQ <Name>
Create [<Number>] Size <Name> );

Parameters
___Map
Create [<Name>] [<Number>]
Generates a map with the name <Name>. If the name <Name> already exists, the existing map is emptied. If
a large number of files (>50) is to be saved, the expected quantity should be defined using <Number>.
Set <Name> <Key>=<Value>
The key <Key> with the value <Value> is added to the map <Name>. The key is updated if it already exists in
the map. The same conditions as those for variable names apply for the names of keys. Spaces at the end of the
Value are always deleted. Defined quotation marks are retained, however.
Load <Name> <Name2>
The existing map <Name2> is added to the map <Name>. In the case of duplicate keys, the key for the map
<Name> is updated with the values from <Name2>.
Enum <Name> <Function>
The function <Function> is performed for each entry in the map <Name>, whereby the following values are
passed on to the specified function:
• Key
• Value
The arguments can be called within the function using $(Arg:v1) and $(Arg:v2). They are handed over with
quotation marks. Empty keys are handed over as an empty string.
Keys cannot be added or removed within the function to be performed, nor can the map be changed in any
manner. Modifying keys is the only action permitted.
Remove <Name> <Key>
The key <Key> is deleted from the map <Name>.
Destroy <Name>
The map <Name> is deleted.
#Map
Get <Name> <Key>
The value for the key <Key> is returned from the map <Name>.
KeysAsCsv <Name>
All the keys in the map <Name> are returned separated by commas.
KeysAsCsvq <Name>
All the keys in the map <Name> are returned separated by commas. The values are enclosed in single quotation
marks.
KeysAsList <Name>
All the keys in the map <Name> are returned separated by spaces.
KeysAsListq <Name>
All the keys in the map <Name> are returned separated by spaces. The values are enclosed in single quotation
marks.
 164

ValuesAsCsv <Name>
All the values in the map <Name> are returned separated by commas.
ValuesAsCsvQ <Name>
All the values in the map <Name> are returned separated by commas. The values are enclosed in single quo-
tation marks.
ValuesAsList <Name>
All the values in the map <Name> are returned separated by spaces.
ValuesAsListQ <Name>
All the values in the map <Name> are returned separated by spaces. The values are enclosed in single quotation
marks.
Create [<Number>]
A map is created and the name is returned. If a large number of files (>50) is to be saved, the expected quantity
should be defined using <Number>.
Size <Name>
The number of keys in the map <Name> is returned.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
A map should only contain keys which have been created. No keys are defined automatically as is the case with
___RecordBuffer.

Examples
Creating a map and saving the file name and document number for all the marked objects:
___Map ( create myMap );
___Environment ( counter=0 );
___Selection ( enumerate __MARK__ AddDataToMap myMap );
...
Public AddDataToMap, AIM_AddDataToMap
Procedure AIM_AddDataToMap
___Environment ( counter=$(counter:++) );
___Map ( set $(Arg:v1) Ident$(counter)=#(IDENT) );
___Map ( set $(Arg:v1) File$(counter)=#(DOCNAME0) );
Endproc
After the map myMap has been created, a variable $(counter) is defined as 0. This serves as a numerator. The
function ___Selection is used to call the function AddDataToMap for each marked object in Productstream
Professional and for handing over the name of the map myMap to this function. The function increments the
numerator $(counter) by 1 and then assigns the numerator to the key names Ident and File. This action gene-
rates the keys Ident1 und File1, Ident2 and File2, etc., and the values are saved accordingly.
/* saves the number of keys from "myMap" */
___Environment ( Size=#(Map size myMap) );
/* query for a key "Ident1" and "File1" from "myMap" */
___Environment ( Ident=#(Map myMap Ident1) );
___Environment ( File=#(Map myMap File1) );
/* saves all the keys and values from "myMap" */
___Environment ( AllKeys=#(Map KeysAsList myMap) );
___Environment ( AllValues=#(Map ValuesAsList myMap) );

See also
___RecordBuffer
Variable names
 165

___New_Object
Opens the New record dialog window for a freely definable EntityType.

Syntax
___New_Object ( <EntityTypeObject> );

Parameters
<EntityTypeObject>
The New record dialog window for this EntityType object is opened. Productstream Professional expressions
may be used.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The rights for the given EntityType object are checked. The condition only returns TRUE and can be executed
if Create and Write rights have been granted.
If Productstream Professional Easy is being used, the valid EntityType objects are also checked.
The specified EntityType object must have been correctly entered in the configuration.
The function itself does not perform any further actions, but only calls the public function New_Object with
the same parameters which must be found using the object model. This is where the call function for the New
record dialog window is implemented.
The function is usually launched directly from the menu! It is therefore regarded as an exception as far as the
convention that all functions used in menu files should begin with m_ is concerned.

Examples
Opening the New record dialog window for a product:
___New_Object ( AIM.PART );

See also
Formatting
Variables
 166

___NotInstalled
No function.

Syntax
___NotInstalled ();

Parameters
<None>

Return Values
Value Description
1 Command executed successfully

Notes
This is just a dummy function.

___OnePropUpdate
Updates the file behind the current object. Write protection and rights are temporarily disabled.

Syntax
___OnePropUpdate ( [<Parameter>] );

Parameters
[<Parameter>]
The given parameters are passed on to the public function OnePropUpdate . Productstream Professional ex-
pressions may be used.

Return Values
? Return value for the function OnePropUpdate
or
0: Command executed successfully
-1: No RecordBuffer or DocumentType object context
-3: No file names available (no DocumentType object)
-4: No file available
-5: Untreated exception in the public function OnePropUpdate
unequal to 0: Error (no further details given, error message in the file errlog.err)
Notes
Any write-protection flag on the file is disabled for the duration of the function call. Write rights are also as-
signed. The Access Control List is modified by an existing Productstream Professional Access Control
Manager. These changes are cancelled when the function finishes.

See also
Formatting
Variables
 167

___OpenArchiv
Opens a new Productstream Professional dialog window. This must be a GUIView object as a Folder element.

Syntax
___OpenArchiv ( <GUIViewObject> );

Parameters
<GUIViewObject>
The new dialog window is opened in the GUIView <GUIViewObject>. The specified GUIView object must
be compatible with the current object and it must be a Folder element.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
With many GUIView objects, the attribute DBWHERE is substituted for the object of the parent GUIView
object. The object current at the time ___OpenArchive is called becomes the object of this parent GUIView
object.
___RecordBuffer or ___OpenGUIViewWindows must be used to open a window for a GUIView object of
element type CreateDialog.
Example
Opening the detail dialog window for the current object, type Engineering Document:
___OpenArchive (FolderEngineeringDocument_Detail );

See also
Formatting
Variables
 168

___OpenGUIViewWindow
Opens a new Productstream Professional dialog window showing the current object. It must be a GUIView
object as a CreateDialogElement and be compatible with the current object.

Syntax
___OpenGUIViewWindows ( [-modal] <GUIViewObject> );

Parameters
[-modal]
The dialog window is opened modally, i.e. it remains the only window which can be controlled until it is
closed.
<GUIViewObject>
The current object is opened in the GUIView object <GUIViewObject>. The specified GUIView object must
be compatible with the current object.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
With many GUIView objects, the attribute DBWHERE is substituted for the object of the parent GUIView
object. The object current at the time ___OpenGUIViewWindow is called becomes the object of this parent
GUIView object.
___OpenArchive must be used to open a dialog window for a GUIView object of type Folder.

Examples
Opening the New record dialog window for the current office document:
___OpenGUIViewWindow ( Create_Dialog_OfficeDocument );

See also
Formatting
Variables
 169

___OpenHelp
Opens the online help as defined under HelpFile.

Syntax
___OpenHelp ();

Parameters
<None>

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given). The message text is documented in the local working directory in
the file errlog.err

Notes
The help file is defined under HelpFile in the file COMPASS.INI in the section [Path].
 170

___Prepare
This function substitutes a template file in ASCII format (all expressions and variables with "#" "@" and "$")
and writes a target file with the substituted values.

Syntax
___Prepare ("<TemplateFile>""<TargetFile>" [-a] [-c] [-ansi|-utf8|-utf16|-utf16_be|-utf16_le]);

Parameters
"<TemplateFile>"
The path, file name and extension of the template which is to be substituted.
"<TargetFile>"
The path, file name and extension of the target file which is to be substituted.
[-a]
Mode: append. Either append it to the existing target file or generate a new one.
[-c]
Mode: convert. Convert the target file from ASCII to ANSI.
[-ansi|-utf8|-utf16|-utf16_be|-utf16_le]
Mode: define the prefered Unicode format

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The expressions and variables are substituted for the current object and context and written to the target file.
The target directory is not created.

Examples
File: copy.vor with the following contents:
xcopy "#(DOCNAME0)" "$(USERPROFILE)\My documents\Productstream Professional" /d /y ↵
The following syntax is used to substitute a template file and to append it to the target file:
___Prepare ( "$(TEMPLATEPATH:|+)copy.vor" "$(WSPATH:|+)copy.bat" –a );
The template file called copy.vor in the folder $(TEMPLATEPATH:|+) is read out, substituted for the current
object, and then written to the folder "\Documents and Settings\All Users\Application Data\Autodesk\Pro-
ductstream Professional 2009" as copy.bat. If this file already exists, the new contents are appended. If the
command is started in this form for multiple objects, a batch file is created which copies all the primary docu-
ments to the local directory ...\My Documents\ one after the other.

See also
Formatting
Variables
 171

PrintReport
Prints data using the Report Generator. This function forms the basis for the Report Generators included as
standard in Productstream Professional.

Syntax

PrintReport ([{__BOM__|__STRBOM__|__SUMBOM__}] [<MaxLevel>]

{Report|Preview|Layout|Export} <LayoutFile> [Silent] [Keep=<File>]
[Fixed=<RecordBuffer>]);

Parameters
__BOM__
The simple BOM in the first level of the current object is processed.
__STRBOM__
The BOM is processed as a multi-level bill of materials.
__SUMBOM__
The BOM is processed as a summarized bill of materials.
<MaxLevel>
Maximum depth of resolution.
Report
The report printout is sent to the printer.
Preview
The report printout is shown in the preview.
Layout
Launches the layout editor (ie. The Windows application associated with the .rdlc extension)
Export
The report is written to a file. Here the switch Keep=<File> is evaluated.
<LayoutFile>
The layout file <LayoutFile> is used for data output.
[Silent]
No UI is displayed.
[Keep=<File>]
For Export only: The preview is saved to a file. The specified file name <File> must be given with the extension
XLS, XLSX, PDF or TIFF
[Fixed=<RecordBuffer>]
All the fields in the record buffer or object named here can be used by the Report Generator as variables in
addition to those of the current object. These variables have a definitive prefix Fixed followed by the database
field name (Fixed_<DB-FieldName>). This option cannot be used for BOM reports, since they automatically
set the “Fixed_” variables based on the root part of the BOM.

Syntax
LocalizeReportTemplate(<LayoutFile> <OutputFile>] );
This function helps to localize reports. In case you like to work with localized reports or you have written your
power-reporting functionality that will use the localized reports, this function helps you to quickly localize
your reports.
 172

Parameters:
<LayoutFile>
The layout file <LayoutFile> contains the non-localized report template.
<OutputFile>
The output file <OutputFile> is where the localized report template should be written.
Note
i ! the Webserver it must be used in silent mode.
If PrintReport is used with
 173

___Report
Syntax
___Report(add <name> <entityType> <reportType> <path>)
___Report(enumerate <entityType> <reportType> <function>)

Parameters:
<Add>
Adds a report entry in the configuration
<Enumerate>
Enumerates through the report entries in the configuration
<EntityType>
The entity type of the report (ex. AIM.DOC.ENG)
<ReportType>
The type of the report (ex. List)
<Path>
The path to the report. Only valid for add operations.
<Function>
The function that gets called while enumerating through the configuration. For each iteration, the $Report-
Name and $ReportPath variables hold the report name and path respectively. Only valid for enumeration ope-
rations.

___ProfileManager
Launches the profile manager.

Syntax
___ProfileManager ();

Parameters
<None>

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
If any changes are made in the Profile Manager, Productstream Professional is terminated and a message is
displayed.
 174

___ReadRecInfo
Objects are read out of a file (see ___WriteRecInfo) and taken over in Productstream Professional. Files are
not taken into consideration.

Syntax
___ReadRecInfo ( <ShellCommand> ;<FileName> <Type> [<Conversion>];
{<Overwrite> ; <Append> ; <Generate> | <Delete> };
[<Before>] ; [<After>] ; [<Meantime>] );

Parameters

Parameter Arguments Description

<ShellCommand> nul() Shell commands (see ___Shell) are defined here. The success of the parameter is
not checked. The command may not include any semi-colons (;). If a command is
not required, the dummy command nul() must be given.
<FileName> The objects are read out of the specified file.
<Type <empty> The internal RecInfo2 format is expected. In this format, <Field>=<Value> is
given in each line. Individual elements are separated by lines containing just one 1
semi-colon (;).
SDF [<STDFile>] One object is contained in each line in the file. The fields in the object are listed
and separated by commas. If a STD file <STDFile> is not defined, the objects are
taken over 1:1 in the current database. The sequence of the SQL view or SQL
table being used applies.
If a file <STDFile> is defined, the object is structured according to this STD file,
and only those fields of the same name are added to the database.
Format of the STD file:
<FieldName> {C|D|N} <Length> <DecimalPositions>
CDF [<STDFile>] In der Datei ist je Zeile ein Objekt enthalten. Die Felder innerhalb des Objekts
sind mit einem Komma getrennt aufgelistet. Ist keine STD-Datei <STD-Datei>
angegeben, werden die Objekte in die aktuelle Datenbank 1:1 übernommen.
Dabei gilt die Reihenfolge des verwendeten SQL-Views oder SQL-Tabelle.
Wird eine Datei <STD-Datei> angegeben, wird das Objekt entsprechend dieser
STD-Datei strukturiert und nur Felder gleichen Namens in die Datenbank
übernommen.
Format der STD-Datei:
<Feldname> {C|D|N} <Länge> <Dezimalstellen>
[<Conversion>] <empty> Entries are taken over without being converted.
-c Converts an ASCII character set into an ANSI character set.
<Overwrite> 0 An existing object is not overwritten.
1 An existing object is overwritten.
<Append> 0 An existing object is not appended.
1 An existing object is appended.
<Generate> 0 Unique key fields are not generated.
1 Unique key fields are generated.
<Delete> __DELETE__ Existing objects matching the read object are deleted.
If __DELETE__ is defined, the parameters for <Overwrite, <Append> and
<Generate> may not be given.
 175

Parameter Arguments Description

[<Before>] [Pre=<Function>] The defined <Function> is called from the text file after the file is read and before
each individual object is processed. The context is the currently read object. Addi-
tional default entries can be specified here.
Return values are taken into consideration as follows:
0: Processing of the currently read object continues (update, insert, delete or
Do=<Function>)
1: Processing of the currently read object is cancelled (update, insert, delete or
Do=<Function>) and the next object is read
2: Processing of the function ___ReadRecInfo is cancelled completely.
[<After>] [Post=<Function>] The defined <Function> is called from the text file after each individual object is
processed (update, insert, delete or Do=<Function). The context is the currently
read object.
Return values are not taken into consideration.
[<Meantime>] [Do=<Function>] The defined <Function> is called from the text file while each individual object is
being processed (update, insert, delete or Do=<Function). The context is the cur-
rently read object.
Return values are not taken into consideration.

Return Values
Value Description
0 Command executed successfully
1 Processing of the currently read object is cancelled (update, insert, delete or
Do=<Function>) and the next object is read (applies only for return values for the
function Pre=<Function>
2 Processing of the function ___ReadRecInfo is cancelled completely (applies only for
return values for the function Pre=<Function>)
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
• When a file is read in, only objects, but no files, are processed.
• All the semi-colons must be specified.

Caution!
The key generating function does not create valid numbers for document numbers or file names. these have to be
manually generated using the functions Pre=<Function> or Do=<Function>.
 176

Examples
Reading in a previously created standard file:
___WriteRecInfo ( "$(WsPath:|+)RecData.rec" -o –one );
...
___ReadRecInfo ( nul() "$(WsPath:|+)RecData.rec" SDF 0;1;1; );
This is the simplest method of reading in data. The object which was previously written out is read in further
below. This triggers the generation of a key.
Reading in a file and performing the check functions:
___ReadRecInfo ( nul() "$(WsPath:|+)RecData.rec" SDF 0;1;1;Pre=CheckData;Post=GetFile;;
);
Here, the check function CheckData is performed on each object read, and the function GetFile is run if the
object is inserted successfully.
Read-in objects should be deleted in the Productstream Professional database:
___ReadRecInfo ( nul() "$(WsPath:|+)RecData.rec" SDF __DELETE__ );
Here, every read object found in the database is deleted.

See also
___WriteRecInfo
Formatierung
 177

___RecordBuffer, RecordBuffer
A virtual object is provided which contains all fields of the used folder object. The object is managed by a name
and can be used for subsequent processing.

Syntax
___RecordBuffer ( Create <RecordBufferName>
Destroy <RecordBufferName>
Call <RecordBufferName> <Function> [<Parameter>]
Set <RecordBufferName> <FieldName>=<Value> ["<FieldName>=<Value>"]
Load <RecordBufferName>
Merge <RecordBufferName>
Init <RecordBufferName>
Insert <RecordBufferName>
Update <RecordBufferName>
Edit <RecordBufferName> <GUIView-Object>
ModalEdit <RecordBufferName> <GUIView-Object>
Duplicate <RecordBufferName>
KeyGen <RecordBufferName> <Identifier>
WriteXml <RecordBufferName>
WriteXmlBase <RecordBufferName>
ExportfFiles <RecordBufferName>
ImportFiles <RecordBufferName> );

#(RecordBuffer<RecordBufferName> <SubstitutionExpression>)

Parameters
___RecordBuffer

Parameter Arguments Description

Create <RecordBufferName> Generates the record buffer with the specified name. An existing record buffer of
the same name is deleted. The generated record buffer contains all the fields defi-
ned for the current object (table or view).
A record buffer can only be inserted in the context in which it was created.
Destroy <RecordBufferName> The given record buffer is deleted from the memory.
Call <RecordBufferName> The function <Function> is performed for the given record buffer. All the given
<Function> [<Parameter>] <Parameters> are passed on to this function.
Set <RecordBufferName> Fields are filled with the values for the given record buffer. New fields can also be
<FieldName>=<Value> created. They must begin with the flag Symbol:<SymbolName>. These fields are
["<FieldName>=<Value>"] ignored when data is later added to the database and are only used for temporary
storage.
Load <RecordBufferName> Loads the current object into the given record buffer. The fields OWNER,
OWNER_GROUP, WORLD_GROUP and RIGHTS are not taken over in the
record buffer. All the existing values are overwritten, even if the object fields are
empty.
Version 5.4.0
Merge <RecordBufferName> Loads the current object into the given record buffer. The fields OWNER,
OWNER_GROUP, WORLD_GROUP and RIGHTS are not taken over in the
record buffer. Only the field values which are not empty are taken over. Existing
empty object values are not taken over.
Init <RecordBufferName> Initializes the given record buffer. All the fields are emptied.
 178

Parameter Arguments Description

Insert <RecordBufferName> The given record buffer is added to the database, whereby the context (table or
view) in which the record buffer was generated is always used. The fields
OWNER, OWNER_GROUP, WORLD_GROUP and RIGHTS are automati-
cally filled from the configuration.
Update <RecordBufferName> The given record buffer overwrites the previously loaded (Load or Merge) object
with the current values from the record buffer. The function is terminated if the
object meanwhile no longer exists.
Edit <RecordBufferName> The given record buffer is opened with the specified GUIView object. The func-
<GUIViewObject> tion is finished when the dialog window opens. It does not wait until the user
closes the dialog window (exception: ModalEdit).
ModalEdit <RecordBufferName> The given record buffer is opened with the specified GUIView object. The func-
<GUIViewObject> tion is not finished when the dialog window opens. It waits until the dialog win-
dow is closed again. No further functions can be started, nor can another dialog
window be opened, as long as this dialog window remains open.
Duplicate <RecordBufferName> The current object is fully duplicated and assigned to the specified record buffer.
The Folder object information is also duplicated. The Folder object current at
the time the Create action was performed is then irrelevant.
KeyGen <RecordBufferName> Searches for the attribute <Flag>KeyGen for the EntityType object being used.
<Identifier> Structure:
<Flag>Keygen = "<FieldName1>=<Value>" "<FieldName2>=<Value>"
The variable Generated_Fields contains the list of changed field names (separated
by spaces). #(FieldDesc $(Generated_Fields:v1)) returns the field name of the
first field. The key is generated for the EntityType object using the folder defined
by BaseFolder.
WriteXml <RecordBufferName> The current object is written to the XML file defined by ___WriteAimXml. The
[<ExtraAttributes>] field contents are written to the record buffer together with the column names
from the SQL view or the SQL table of the Folder object. Optional extra attribu-
tes are given in the following form: "<Name>=<Value>".
These are then added to the XML file in the ROW element in the form
"<Name>Value</Name>"
(refer also to the description of ___WriteAimXml).
Version 5.4.0
WriteXmlBase <RecordBufferName> The current object is written to the XML file defined by ___WriteAimXml. The
[<ExtraAttributes>] field contents are written to the record buffer together with the column names
from the SQL view or the SQL table of the Folder object. Optional extra attribu-
tes are given in the following form: "<Name>=<Value>".
These are then added to the XML file in the ROW object in the form
"<Name>Value</Name>"
(refer also to the description of ___WriteAimXml).
ExportfFiles <RecordBufferName> If this record buffer contains a DocumentType object (the field FILE_TYPE
exists), the document files are copied to the target directory <TargetDirectory>
(must already exist). The directory structure shown below is created subordinate
to the target directory: ...\<DocumentType>\<SecondaryFi-
leNo>\<#(FILE_NAME)>.<#(EXTn)>. The sub-directories are created as
required.
Important: Files which are normally referenced using FILE_LINKNAME are
renamed in the target directory into #FILE_NAME!
If this record buffer does not contain a DocumentType object, the routine is ter-
minated with the return value 0 (analog to a success).
Version 5.4.0
 179

Parameter Arguments Description

ImportFiles <RecordBufferName> If this record buffer contains a DocumentType object (the field FILE_TYPE
exists), the document files are copied to from the source directory. The parameter
expects to find a directory structure subordinate to the source directory as genera-
ted by the action ExportFiles.
If the optional source DocumentType object has been defined, this source path
structure is used; otherwise the DocumentType object of the current object is
used. A meaningful source file name is used. Only those files which have been
defined in the DocumentType object of the target (for the current object) are
taken over.
This function must use the already imported object in the current context. The
relationship to the source files is only defined by the parameters given here.
If this record buffer does not contain a DocumentType object, the routine is ter-
minated with the return value 0 (analog to a success).
Version 5.4.0
<RecordBufferName> __CURRENT__ for the current record buffer, and __GUIViewParent__ for the
parent GUIView object, can also be used as RecordBufferName. This only
applies if these are known. This is not the case with Create, Destroy and Dupli-
cate and they may not be known. Here the name must be explicitly stated.
Version 5.2.1

Return Values
Value Description
0 Command executed successfully
<0 Error (no further details given). The message text is documented in the local working directory in
the file errlog.err (KeyGen only
>0 Position of the generated field (KeyGen only)
unequal to 0 Error (no further details given, error message in the file errlog.err)

#(RecordBuffer<RecordBufferName> <SubstitutionExpression>)
The <SustitutionExpression> is substituted at the record buffer with the name <RecordBufferName> and the
result is returned.
If the record buffer <RecordBufferName> is not present, an empty string is returned and an error message is
written to errlog.err.

Notes
A record buffer offers access to the contents of a virtual object in a database table. A record buffer is therefore
always assigned to the context (SQLTable or SQLView database object) in which it was created, even if it can
be addressed from other GUIView objects. All the fields in the context are automatically stored in the record
buffer when it is created.
If a record buffer is defined in a context composed of multiple tables, it is also performed in those tables when
Insert is run. To avoid this, the record buffer must be generated for the correct context using the function
___ForTable:
___ForTable ( db=<FolderObject> ___RecordBuffer Create <RecordBufferName> );
 180

Examples
Simple function for making changes to a office document:
___RecordBuffer ( Create Change );
___RecordBuffer ( Load Change );
___RecordBuffer ( Edit Change Create_Dialog_OfficeDocument );
___RecordBuffer ( Destroy Change );
...

Button: <Save and close>

___Recordbuffer( Update __CURRENT__ );
In the first section, the record buffer Change is generated and the current object is loaded into it. The dialog
window is then opened with this object. As it is then in the dialog window, it can be deleted immediately. Save
and close writes back the record buffer again. It can always be addressed in the dialog window using
__CURRENT__.
Creating a new record for an engineering document while copying the current object:
___ForTable ( db=Folder_EngineeringDocument ___RecordBuffer Create New );
___RecordBuffer ( Load New);
___RecordBuffer ( Set New AIMKEY= );
___RecordBuffer ( Set New REVISION= );
___RecordBuffer ( Edit New Create_Dialog_OfficeDocument );
___RecordBuffer ( Destroy New);
...

Button: <Save and close>

___Recordbuffer( Insert __CURRENT__ );
In the first section, the record buffer is explicitly generated in the context of the engineering documents. The
current object is then loaded and AIMKEY and REVISION are emptied. The dialog window is opened and
the record buffer is deleted (with Save and close, a valid number is generated in the standard version).

See also
Symbol
___WriteAimXml
 181

___ResetFolder
This function resets the internal structures of the client program for a Folder object (folder, DB table) and
refills them with the current values from the database.

Syntax
___ResetFolder ( <FolderObject> [local=true] );

Parameters
<FolderObject>
Name of the Folder object to be reset.
[local=true]
Other workstations are not informed that they have to update their structures for the folder <FolderObject>.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
At present this function can only be used in association with the Productstream Professional classification. He-
re, columns are also added to database tables when creating new characteristic definitions. This information
must then be updated on the client as well.
Example
Call for characteristics:
___ResetFolder ( "XREFCRCLIST" );

___Return_0
Function which only returns the value 0.

Syntax
___Return_0 ();

Parameters
<None>

Return Values
Value Description
0 Command executed successfully

See also
___Return_1
 182

___Return_1
Function which only returns the value 1.

Syntax
___Return_1 ();

Parameters
<None>

Return Values
Value Description
1 Command executed successfully

See also
___Return_0
 183

___ReturnString, # ( ___ReturnString )
Function to store a value which can then be called by an expression.

Syntax
___ReturnString ( <Value> );
#( ___ReturnString );

Parameters
<Value>
Stores a value which can then be called via #(___ReturnString).

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
With #(___ReturnString) only the most recently stored value can be called. Therefore, it is not possible to ac-
cess more than one stored value. The advantage in comparison with the usage of a variable by ___Environment
is the ability to store a value without having to know the name of the variable. Using #(Call ...) can thus launch
a function which delivers a return value.
Example
If ( EType("AIM.DOC.ENG") )
___ReturnString ( AND ENTITY_TYPE='AIM.DOC.ENG' );
Else
___ReturnString ( AND ENTITY_TYPE='AIM.DOC.OFF' );
...
___ForAllRela ( db=Folder_All_Document _
"CATEGORY='BUCH' #(___ReturnString)" _
Print );
First, the return string is filled depending on the EntityType object. Subsequently, ___ForAllRela is used to
add exactly this return string to the Where clause. If the string remains empty, the Where clause still remains
valid but without the restriction of the EntityType object.

See also
#(Call ...)
 184

___SelectDirectory
Allows a directory to be selected from the file system in a dialog window. The result is saved in a variable.

Syntax
___SelectDirectory ( <Variable> [<StartDirectory>] ) [<DialogTitle>];

Parameters
<Variable>
The selected directory is saved in this variable. The variable is not written to if an error occurs.
[<StartDirectory>]
The dialog is started using this start directory. If a start directory is not specified, the current working directory
($(WsPath)) is used. The workstation can be used as the start directory by entering a full-stop ".".
[<DialogTitle>]
The text entered here is displayed in the dialog window as a title. It may not include any semi-colons.

Return Values
Value Description
0 Command executed successfully
-1 Start directory not specified
-2 Cancel selected in the dialog window
-11 No arguments specified
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
A specified dialog title may not include any semi-colons.

Examples
Copy the file to a selected directory:
___SelectDirectory ( myPath . )Please select directory;
If ( !empty("$(myPath)") )
{
___Shell ( cp("#(DOCNAME0)" "$(myPath:|+)#(DOCNAME0:f)") );
}
The dialog is displayed and the workstation is selected. If a directory is selected, the file is copied to that direc-
tory for the current data record.

See also
Formatting
 185

___Selection
This function is used to collate objects to edit them in sequence in a loop. The objects are recorded in an in-
ternal list in the selection and the required function is performed on them.

Syntax
___Selection ( Create <SelectionName>
Add <SelectionName 1> [Mark|Filt|Sele <SelectionName 2>]
[Enumerate {<SelectionName>|__MARK__} <Function> [<Parameter>]
EnumStructure {<SelectionName>|__MARK__} [Pre=<Function1>]
[Down=<Function2>] [Post=<Function3>] <Function4> [<Argument>]
Remove <SelectionName1> [All|Mark|Filt|Sele <SelectionName 2>]
Destroy <SelectionName> );

Parameters
Create <SelectionName>
Creates a selection under the specified name. It does not yet contain any elements. An existing selection with
this name is deleted first. Selection names are unique throughout the program.
Add <SelectionName1> [<blank>|Mark|Filt|Sele <SelectionName2>]
Objects are added to the selection <SelectionName1>:
<blank> The current object is added
Mark: All the marked objects are added
Filt All the visible objects (filters) are added
Sele <SelectionName2> The selection <SelectionName2> is added

Enumerate {<SelectionName>|__MARK__} <Function> [<Argument>]

The function <Function> is called for all the objects marked in the selection. The parameters <Parameter> are
substituted once when the function is called and handed over to it. They are substituted again if the function
is run in the loop. Two escape symbols @@ or ## must be used to allow access to the field values in the respec-
tive object.
The designator __MARK__ can be used instead of a selection name. All the marked objects are then processed
using the function.
Loop processing is stopped by calling ___Break_Enum in the function to prevent any further objects from
being processed.
EnumStructure {<SelectionName>|__MARK__} [Pre=<Function1>] [Down=<Function2>]
[Post=<Function3>] <Function4> [<Argument>]
This function handles all the objects in the specified selection as well as all objects whose structure has the same
element type.
<Function1> is called before the objects are handled.
<Function2> is called for each object that is to be handled. It states whether subordinate sibling objects are to
be handled. If this is not given or it returns 1, an attempt is made to find the sibling objects of the object cur-
rently being handled using the XREF_ELEMENT table. Any sibling objects that are found must have the
same or a derived element type. The same routine is repeated for this through the structure.
<Function4> is called when all of the sibling objects have been handled for an object. If this has an error level
that is unequal to 0, the entire handling routine is canceled and <Function3> is called.
The designator __MARK__ can be used instead of a selection name. The current marking is then used as the
selection.
Calling ___Break_Enum in <Function4> cancels the current structure handling routine, which can be conti-
nued by running <Function4> on the parent object.
When all the objects have been processed, <Function3> is called.
 186

Remove <SelectionName1> [<blank>|All|Mark|Filt|Sele <SelectionName2>]

Objects are removed from the specified selection:
<blank> The current object is removed
All objects are removed (corresponds to Create)
Mark: All marked objects are removed if present
Filt All the visible objects (filters) are removed
Sele <SelectionName2> Objects in the selection <SelectionName2> are removed

Destroy <SelectionName>
The specified selection is deleted.

Return values
Value Description
0 Command executed successfully (return value for the function)
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
References to objects are saved in a selection. If the objects no longer exist when processing the selection, the
function may return an error.

Examples
All marked entries are to be assigned the Custom Date 1 (field: CUSTOM_1_DATE) with the current date:
___Selection ( Enumerate __MARK__ ___ChangeField CUSTOM_1_DATE=#(SYSDATE) );
All visible objects are to be assigned the value 0 in the field Custom Number 1 (field: CUSTOM_1_NUM) if the
document does not exist or 1 if it does exist:
...
___Selection ( Create List );
___Selection ( Add List Filt );
___Environment ( ListAll=#(selection:List) );
___Environment ( ListFile=0 );
___Selection ( Enumerate List CheckFile );
___Selection ( Destroy List );
___Shell ( read()All entries: $ListAll of which processed: $ListFile );
...
Public CheckFile,AIM_CheckFile
Procedure AIM_CheckFile
If ( exist("#(DOCNAME0)") )
{
___ChangeField ( CUSTOM_1_NUM=1 );
___Envrionment ( ListFile=$(ListFile:++) );
}
Else
___ChangeField ( CUSTOM_1_NUM=0 );
Endproc
In the first section, a selection is defined in which all the visible objects are noted. The size of the selection is
saved in $ListAll. The function CheckFile is then run for all the noted objects. This checks whether the pri-
mary document exists and modifies the field CUSTOM_1_NUM accordingly. If present, the variable $List-
File is incremented by 1. Finally, a summary is displayed with ___Shell read().

See also
___Break_Enum
selection
 187

___SetFilePropsDirty
Switches the DIRTY flag for the active document in the Productstream Professional database on or off. A set
DIRTY flag states that a document that has been released has not yet been updated, i.e. it may have properties
(bills of materials, office fields, etc.) which do not contain up-to-date information.

Syntax
___SetFilePropsDirty (<flag>);

Parameters
<flag>
Truth value stating whether the flag is to be set or not. The parameters "true" or "1" respectively "false" or "0"
are accepted (these are not case-sensitive).

Return Values
Value Description
0 Command executed successfully
<0 Error (no further details given)
1 DIRTY flag not defined in the database
2 Invalid parameters handed over

Notes
By default, the flag is set to "released" when changing the status, and then reset to "Update document" when
performing the function.

Examples
The DIRTY flag is set for the active document with the call
___SetFilePropsDirty(true);
and is reset with the call
___SetFilePropsDirty(false);
 188

___SetNewerVersionExists
Switches the NEWER_VERSION_EXISTS flag of the active document in the Productstream Professional da-
tabase on or off. A set flag (value 1) states that a newer version of a document exists, i.e. the document being
viewed is an "old version".

Syntax
___SetNewerVersionExists (<flag>);

Parameters
<flag>
Truth value stating whether the flag is to be set or not. The parameters "true" or "1" respectively "false" or "0"
are accepted (these are not case-sensitive).

Return Values
Value Description
0 Command executed successfully
<0 Error (no further details given)
1 NEWER_VERSION_EXISTS flag not defined in the database
2 Invalid parameters handed over

Examples
The flag is set for the active document with the call
___SetNewerVersionExists(true);
and is reset with the call
___SetNewerVersionExists(false);
 189

___SetPrinter
The default printer in Windows is applied for the user currently logged on.

Syntax
___SetPrinter ( <PrinterName> );

Parameters
<PrinterName>
The specified printer is defined as the default printer. The name of the printer . must be given in quotation
marks if it contains spaces. If the printer cannot be found, the default printer is not applied.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
When the printer has been successfully applied, all the active Windows applications are notified accordingly
using WM_SETTINGCHANGE.

Examples
Applying the printer "HP DesignJet 800":
___SetPrinter ( “HP DesignJet 800” );

See also
Formatting
 190

___SetRights
Rights relating to an object or record buffer can be changed. To do this, the required rights must have been
assigned on a global basis.

Syntax
___SetRights ( Owner=<UserName>
Group=<GroupName>
World=<GroupName>
OwnerRights=[+r|–r] [+w|–w] [+d|–d] [+c|–c] [+l|–l]
GroupRights=[+r|–r] [+w|–w] [+d|–d] [+c|–c] [+l|–l]
DefaultRights=[+r|–r] [+w|–w] [+d|–d] [+c|–c] [+l|–l] );

Parameters
Owner=<UserName>
The specified user name is entered in the field OWNER. The current user must have been granted the global
right O for the object to do this.
Group=<GroupName>
The specified group name is entered in the field OWNER_GROUP. The current user must have been granted
the global right G for the object to do this.
World=<GroupName>
The specified group name is entered in the field WORLD_GROUP.
The current user must have been granted the global right A for the object to do this.
OwnerRights
The dynamic rights are entered in the field RIGHTS for the user given in the field OWNER. The current user
must have been granted the global right O for the object to do this.
GroupRights
The dynamic rights are entered in the field RIGHTS for the group given in the field OWNER_GROUP. The
current user must have been granted the global right G for the object to do this.
DefaultRights
The dynamic rights are entered in the field RIGHTS for the default right (applies also to WorldRights). The
current user must have been granted the global right A for the object to do this.
r
Read = read right ('+' = set / '-' = delete)
w
Write = write rights ('+' = set / '-' = delete)
d
Delete = delete rights ('+' = set / '-' = delete)
c
Create = new entry right ('+' = set / '-' = delete)
l
Lock = for the current user ('+' = set / '-' = delete)
 191

Return Values
Value Description
0 Command executed successfully
1 A field which is to be modified cannot be found
2 The static right is not sufficient (O, G or A is required)
3 The specified user name does not exist in the Productstream Professional database
4 The specified group name does not exist in the Productstream Professional database
5 Syntax error - the message text is documented in the local working directory in the file errlog.err
6 Other error - the message text is documented in the local working directory in the file errlog.err
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The rights to modify permissions are checked in this function. If these rights have not been granted, no chan-
ges are made at database level. It is sufficient if the right for the specified optional parameters exist. However,
if a right for a specified parameter has not been granted, the entire function is cancelled.
Rights can be revoked or granted additionally based on the current status of the rights (contents of the fields).
Rights cannot be "stamped" (set absolutely).

Examples
Applying the current object to the group ADMINISTRATORS:
___SetRights ( Group=ADMINISTRATORS );
Applying the object to all rights of a group:
___SetRights ( GroupRights=+r +w +d +c );

See also
"___RecordBuffer, RecordBuffer" on page 177
Rights system
Variable
Formatting
 192

___Shell
This is used for running Productstream Professional functions and numerous internal Productstream
Professional commands, as well as programs and commands at operating system level.

Syntax
___Shell ( <Command> [;<Command>] );

Command Action
Cp Copies the source file to the target file
CpExt Copies all source files of the same name with any extension to the target file, whereby the extension is retained
CpWild Copies all source files of the same name with any extension to a target directory
Mv Moves the source file to the target file
MvExt Moves all source files of the same name with any extension to the target file, whereby the extension is retained
MvWild Moves all source files of the same name with any extension to a target directory
Rm Deletes the specified file
RmExt Deletes all source files of the same name with any extension
RmWild Deletes all files with names which correspond to a particular pattern
Md Creates directories
Read Reads out variables
Set Sets variables
Wr Writes a text file
DDEExec Sends DDE commands and instructions to applications
ShellExecute Executes programs
DlgOpen Displays the "Open file" dialog
DlgSaveAs Displays the "Save file as" dialog
Selefile Displays the "Select file" dialog
Find Reads lines out of a file
PopM Generates and displays a selection list
Sleep Halts the Productstream Professional program for a specific period of time
ChMod Sets or removes file attributes (e.g. write protection)
Cat Copies the entire contents of multiple files into a single target file
Nul No action is performed (dummy command)
SendKey Sends individual letters to another window
System Runs an operating system command (Productstream Professional waits until it has been completed). The
command is passed on to cmd.exe.
SystemX Runs an operating system command (Productstream Professional waits until it has been completed). Up to 30
arguments are supported
DDERequest Sends a request to another application using DDE

Productstream Professional commands

Cp ( "<SourceFile>" "<TargetFile>" [<blank>|1|2] )
Copies <SourceFile> to <TargetFile>. The file information includes the directory name, file name and exten-
sion. Variables and field queries can be used. Stating the code is optional:

Parameter Meaning
<blank> If the code is not given, the source file is always copied if it exists.
1 The file is only copied if the target file does not yet exist. An existing target file is not overwritten.
2 An error message is displayed if the file cannot be copied (e.g. because the source file does not
exist). This flag does not imply the flag 1; the target file may therefore be overwritten.
 193

Example
Copying the primary document into the working directory under the same name:
___Shell ( cp("#(DOCNAME0)" "$(WsPath:|+)#(DOCNAME0:f)" 1) );

CpExt ( "<SourceFile>" "<TargetFile>" )

Copies the <SourceFile>.* to <TargetFile>.*; however, all the source files of the same name with any extension
are copied using a different name and the extension is retained. The file information includes the directory
name and file name. Any specified extensions are ignored.
Example
Copying all the files from \\Server\share_name\log_folder\logfile.* to the working directory under the old file
name and date:
___Shell ( cpext("\\server\share_name\log_folder\logfile"
"$(WsPath:|+)Logfile_#(SYSDATE)") );

CpWild ( "<SourceFile(s)>" "<TargetDirectory>" )

Copies files with a particular name pattern to a target directory. The wildcards ? or * can be used in the name
pattern. Variables and field queries can be used for the target name and the target directory.
Example
Copying all the AutoCAD files from \\server\share_name\collect_folder\*.dwg to the working directory under
the same file name:
___Shell ( cpwild("\\server\share_name\collect_folder\*.dwg" "$(WsPath:|-)") );

Mv ( "<SourceFile>" "<TargetFile>" [<blank>|1|2] )

Moves the <SourceFile> to the <TargetFile>. Wildcards (*,?) are not supported. This means that only one file
can be addressed at any one time. The file information includes the directory name, file name and extension.
Variables and field queries can be used. Stating the code is optional:

Parameter Meaning
<blank> If the code is not given, the source file is always moved if it exists.
1 The file is only moved if the target file does not yet exist. An existing target file is not overwritten.
2 An error message is displayed if the file cannot be moved (e.g. because the source file does not exist). This flag does not
imply the flag 1; the target file may therefore be overwritten.

Example
Moving the primary document into the working directory under the same name:
___Shell ( mv("#(DOCNAME0)" "$(WsPath:|+)#(DOCNAME0:f)" 1) );

MvExt ( "<SourceFile>" "<TargetFile>" )

Moves the <SourceFile>.* to the <TargetFile>.*, i.e. the specified file, irrespective of its extension. The file in-
formation includes the directory name and the file name; any specified extensions are ignored. Variables and
field queries can be used, but no wildcards (?,*).
Example
Moving all the files from \\server\share_name\log_folder\logfile.* to the working directory under the old file
name and date:
___Shell ( mvext("("\\server\share_name\log_folder\Logfile" "$(WsPath:|+)Logfile_#(SYS-
DATE)") );

MvWild ( "<SourceFile(s)>" "<TargetDirectory>" )

Moves the specified <source file(s) to the <target directory>. The source files are specified by stating the direc-
tory name, file name and extension. Variables, field queries and (providing the file name and extension are
specified) wildcards (?,*) can be used.
The target directory may not contain any file names and may not end with a directory separator ("\", "/"). It
can be described with the help of variables and field queries, but not by using wildcards (?,*).
Example
Moving all the files from \\server\share_name\log_folder\logfile.* to the working directory under the old file
name and date:
___Shell ( cpwild("\\server\share_name\collect_folder\*.dwg" "$(WsPath:|-)") );
 194

Rm ( "<FileName>" )
Deletes the specified file. Wildcards (*,?) are not supported, which means that only one file can be addressed
at any one time. The file information includes the directory name, file name and extension. Variables and field
queries can be used..
Example
Deletes the BAK file automatically generated by AutoCAD for an engineering document::
___Shell ( rm("#(DOCNAME0:F).bak") );

RmExt ( "<FileName>" )
Deletes <FileName>, i.e. the specified file, irrespective of its extension. The file information includes the di-
rectory name and the file name; any specified extensions are ignored. Variables and field queries can be used,
but no wildcards (?,*).
Example
Deletes all the files Logfile.* from the working directory:
___Shell ( rmext("$(WsPath:|+)Logfile") );

RmWild ( "<FileName(s)>" )
Deletes the specified files. The files are specified by stating the directory name, file name and extension. Vari-
ables, field queries and (providing the file name and extension are specified) wildcards (?,*) can be used.
Example
Deletes all the files Log.* from the working directory:
___Shell ( rmwild("$(WsPath:|+)*log*.*") );

Md ( "<DirectoryName>" )
Creates a directory or (if necessary) an entire directory structure. The directory must end with a separator ("\"
or "/"). A name following the last separator is interpreted as a file name and ignored. Variables and field queries
can be used.
Example
Creating a folder for the primary document in the current data record.
___Shell ( md("#(DOCNAME0:p)") );

Read ( [<Variable>] ) <MessageText>

This command can be used to generate a message or dialog window:
A message window is generated if an environment variable has not been specified. In this case, the message text
is displayed. Variables and field queries can be used in the message text.
A dialog window is generated if an environment variable <Variable> has been specified. The message text is
displayed. The variable entered by the user is applied by clicking OK. If the user clicks Cancel, the variable is
not applied or remains unchanged.
Example
Issuing a message with the path and file name of the document managed by Productstream Professional:
___Shell ( read()#(DOCNAME0) );
The user query is saved in a variable. The number of expressions should be saved in the variable Number:
___Shell ( read(Number)Please enter the number of expressions: );
 195

Set <Variable>=<Value>
An environment variable is set or applied. Both the name of the environment variable as well as its value can
be specified using variables and field queries.
Example
Stating the working directory in the variable LogPath:
___Shell ( set LogPath=$(WsPath:|-) );

Wr ( "<FileName>"[:a] [-ansi|-utf8|-utf16|-utf16_be|-utf16_le]) <Text>

Writes a line in a text file. Both the text as well as the file can be specified using variables and field queries. If
the switch :a is given after the file name, it is attached to the existing file. Otherwise it is overwritten. If the file
does not exist, a new one is always created.
[-ansi|-utf8|-utf16|-utf16_be|-utf16_le] defines the Unicode format.
Example
Writing the information 'user name' and 'group membership' to the file Info.txt :
___Shell ( wr("$(WsPath:|+)Info.txt":a)Username=$(UserId) – Groups = $(All_Groups) );

DDEExec ( <AppDDEName> <Topic> ) <CommandString>

Under Windows, the DDEExec command allows commands and instructions to be sent to applications which
are made available as DDE servers.

Parameter Meaning
<AppDDEName> DDE application name of the application to be addressed.
<Topic> DDE topic (application-related), e.g.: general system reference or file name.
<CommandString> Command or instruction in the syntax used by the application.

The parameter values vary according to the application. It is therefore necessary to refer to the application do-
cumentation for details. Field queries and Productstream Professional variables can be used to formulate the
expressions.
Example
Printing an active loaded Word document:
___Shell ( ddeexec(WinWord System)[PrintOut] );
 196

ShellExecute ( <Operation> <Program> <Parameter> <WorkingDirectory> <Window> )

The ShellExecute command is used to open MS Windows applications. It is usually added to the file SYS-
PAR.TXT if a document needs to be processed when the appropriate program is not loaded.

Argument Value Description

<Operation> Controls the action which is to be triggered by calling the function.
Open Opens the application for processing the file.
Print Only triggers the Print command.
<Program> States the command for launching the application. The program and the path and file name must be speci-
fied here if it cannot be found using the search path.
<Parameter> Designates the arguments which are to be passed on to the application. Multiple arguments are separated by
spaces. However, they have to be enclosed by double quotation marks. If no arguments are to be passed on, it
is only necessary to enter two double quotation marks.
<WorkingDirectory> Designates the directory which is to be opened when the application is called. It must already exist and may
not end with a directory separator ("\" or "/").
<Window> This parameter can be used to configure the program window. It is optional, and does not have to be speci-
fied. In this case, however, a space must be entered in its place.
The following flags can be used for <Window>:
<blank> The flag SH_SHOW is used if the window is not configured.
SH_SHOW The window is shown with the same configuration used the last
time the program was called. The window takes the focus.
SH_HIDE The window is hidden and takes the focus.
SH_MINIMIZE The window is displayed as a symbol.
SH_RESTORE The window is restored in the previous size and position.
SH_SHOWMAXIMIZED The window is maximized with focus.
SH_SHOWMINIMIZED The window is displayed as a symbol with focus.
SH_SHOWMINNOAKTIV The window is displayed as a symbol. The currently active window
remains active.
SH_SHOWNA The window is displayed. The currently active window remains
active.
SH_SHOWNOAKTIVATE The window is displayed. The currently active window remains
active.
SH_SHOWNORMAL The window is restored in the previous size and position. The cur-
rently active window remains active.

Field queries and Productstream Professional variables can be used to formulate the command.
Example
To launch Notepad and open the file Errlog.err:
___Shell ( ShellExecute ( open "$(SystemRoot:|+)system32\notepad.exe"
"$(WsPath:|+)Errlog.err") );

DlgOpen ( <Variable> <FileName> ) <Text>

The "Open file" dialog is displayed.

Argument Description
<Variable> The variable <Variable> is given the selected file name or is blank (if Cancel is clicked).
<FileName> The file name is used as the default entry.
<Text> The output line produces the query text.

Example
The "Open file" dialog window is opened for selecting a file which is to be assigned to a document record in
Productstream Professional (the working directory is the start directory):
___Shell ( DlgOpen ( TargetFile "$(WsPath:|+)*.#(DOCNAME0:e)" )Please select file: );
 197

DlgSaveAs ( <Variable> <FileName> [<Flag>] ) <QueryText>

The "Save file as" dialog window is displayed.

Argument Value Description

<Variable> The variable <Variable> is given the selected file name or is blank (if Cancel is clicked).
<FileName> The file name is used as the default entry.
<Flag> This argument controls the overwrite mode:
<blank> or 0 If the file exists, an acknowledgement window is not opened
1 If the file exists, an acknowledgement window is opened
<QueryText> The output line produces the query text.

SeleFile ( <Variable> <ModelPathName> <ReturnFlag> ) <QueryText>

The "Select file" dialog window is displayed.

Argument Value Description

<Variable> The successfully selected result is assigned to the variables <Variable>.
<ModelPathName> When the dialog window opens, it shows the contents of the directory specified here using the
given default file extension.
<ReturnFlag> The return flag specifies the return type:
F File name without an extension
FE File name with an extension
D Path with closing / or \
DF Path and file name without an extension
DFE Path and file name with an extension
<QueryText> The output line produces the query text.

Example
The "Select file" dialog window is opened for selecting a file which is to be assigned to a document record in
Productstream Professional:
___Shell ( SeleFile ( TargetFile "$(WsPath:|+)*.#(DOCNAME0:e)" DF)Select a drawing );;
 198

Find ( "<FileName>" <Pattern> <Variable> <Flag> ) <OutputLine>

The file <FileName> is read out line by line. Each line which fits the pattern is disassembled and composed in
compliance with the output line. The figure 1 is added to <Variable> for the first line found and assigned to
the output line as the variable. 2, 3 etc. are added correspondingly for the next lines found, producing variables
in the form <Variable>1,<Variable>2 etc. The variable <Variable>0 contains the number of lines found. If no
line has been found (or the file could not be read), 0 is returned for the number of lines found.

Argument Value Description

<FileName> Path and name of the file to be read.
<Pattern> The pattern can be enclosed in quotation marks ("). Patterns may not contain quotation marks (") or semi-
colons (;).
<Variable> The variable is used as the root name of the ensuing variables.
<Flag> This argument controls the search format:
0 Compares the pattern with the beginning of the line
1 Substring search (using wildcards * and ?)
2 As 0 but IgnoreCase (no differentiation is made between upper and lower-case)
<OutputLine> The output line may contain the variables $1 ... $9. These correspond to the words separated by spaces in the
lines found. $0 contains the entire line (incl. the closing line break "\n")

Example
Searching the file Info.txt for values beginning with IDENT = and saving the values in IdentExtern:
Contents of the file Info.txt:
IDENT=32-1914
SHORT_DESC=striker
IDENT=33-1915
SHORT_DESC=nut
IDENT=34-6368
SHORT_DESC=bolt
Searching for IDENT = and saving it in IdentExtern:
___Shell ( find("$(WsPath:|+)Info.txt" "IDENT=" IdentExtern 2)$$1 );
Result:
IdentExtern0=3
IdentExtern1=IDENT=32-1914
IdentExtern2=IDENT=33-1915
IdentExtern3=IDENT=34-6368
 199

PopM (<BodyVariable> <ResultVariable> <Flag> )<QueryLine>

This function can be used to create a selection dialog window with preselected selection elements, whose se-
lected value is passed on to the variable <ResultVariable>.

Argument Value Description

<BodyVariable> The variable $<BodyVariable">0 specifies the number of menu items. The variables $<BodyVariable">1 to
$<BodyVariable"><Number> define the selection list of the menu.
<ResultVariable> The <ResultVariable> contains the result of the selection. The <ResultVariable> is either empty (nothing selec-
ted) or contains the string of the selection, or is 0, or contains the number of the selection.
<Flag> Controls the allocation of the environment variable <ResultVariable>
<blank> or 0 <ResultVariable> = <Selection number>
1 <ResultVariable> = $(<BodyVariable><Selection number>)
<QueryLine> The query line produces the query text.

Example
Creating a selection list of 3 printers:
Contents of the variable $PrinterX:
Printer0=3
Printer1=Printer A2 – A0
Printer2=Printer A3
Printer3=Printer A4
Creating a selection list and saving the selection in the variable TargetPrinter:
___Shell ( popm(Printer TargetPrinter 0)Please select a printer: );
Result (selection: Printer2=Printer A3 and flag 0)
TargetPrinter=3
Result (selection: Printer2=Printer A3 and flag 1)
TargetPrinter=Printer A3

Sleep ( <Milliseconds> )
Productstream Professional waits for the specified time before the program is continued. The processor is not
put under load.
ChMod ( [+|-]w <FileName> )
Applies write protection for the specified file.

Argument Value Description

<Flag> Controls the attribute ReadOnly for a file:
+w Deletes the file attribute R (the file is not write-protected)
-w Sets the file attribute R (the file is write-protected)
<FileName> The attribute is applied for this file.

Example
Explicitly setting write protection for the file:
___Shell ( ChMod (-w "#(DOCNAME0)") );

Cat ( "<TargetFile>"[:a] ) "<SourceFile1>" "<SourceFileN>"

The source file 1 is copied to the target file. The source file 2 etc. is then attached to the target file. If the pa-
rameter :a is given, the source file 1 is attached to an existing target file. Otherwise, the target file is overwritten.
Nul()
No action is performed. This switch can be specified if a Shell command is mandatory, but is not to be defined.
 200

SendKey ( <WindowClassName> <WindowName> <Paramete> ) <Text>

A text message is sent to a Windows window.

Argument Description
<WindowClassName> Specifies the window class name.
<WindowName> Specifies the window name.
<Parameter>The specified Multiple actions can be performed if the parameters are added together.
text is sent. 0 Send and wait
1 Send and continue
2 Send and send a KeyDown after each character
4 Send and send a KeyUp after each character
<Text> The specified text is sent

System ( <Command> )
The specified command is passed on to cmd.exe. Productstream Professional waits until cmd.exe has been quit
and then continues.
SystemX
The specified command is passed on to Windows. Productstream Professional waits until the command has
been completed and then continues.
DDERequest
Like #(DDERequest ...). This should be used as a return value is expected.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

See also
Formatting
 201

___ShowWebViewWindow
Displays the specified document in an Internet Explorer window.

Syntax
___ShowWebViewWindow (<FileName>);

Parameters
<FileName>
Absolute path and file name of the document which is to be viewed.

Return Values
Value Description
0 Command executed successfully
<0 Error (no further details given)

Notes
This function is currently only available for the Web client. It is practical to specify a file in a neutral format
(e.g. PDF or DWF). A new Internet Explorer window is opened each time the function is called.

Examples
The document defined in the document type by the attribute can be viewed with the call
___ShowWebViewWindow(#(DTY:WebPreviewFile))

___StartConfigurator
This launches the Productstream Professional Configuration Editor.

Syntax
___StartConfigurator ();

Parameters
<None>

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The program defined in the section [PATH] of the file COMPASS.INI using CONFIGTOOL= is launched.
 202

___StatusBar
Function for handling the status bar in the active Productstream Professional dialog window, whereby a text
is shown in the status bar. The alternative parameters are used to activate, deactivate or switch the status bar,
or to return the current display status.

Syntax
___StatusBar ( {"<Text>"|0|1|2|3} );

Parameters
<Text>
The given text is shown in the status bar. Productstream Professional expressions can be used.
0
Deactivate the status bar
1
Activate the status bar.
2
Switch the status bar
3
Query whether the status bar is to be displayed

Return Values
Value Description
0 Command executed successfully, status bar is visible
1 Status bar is hidden
10 The given text cannot be displayed as the status is hidden
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
This internal function evaluates the flag condition itself. If this is shown in the menu, no further conditions
are defined for displaying the check mark.

Examples
Displaying a text in the status bar:
___StatusBar ( 1 );
___StatusBar ( "Processing #(IDENT) : $(akt) of $(all)" );
The status bar is first activated and then the text is returned, whereby the text is substituted and then displayed.

See also
Formatting
Variable
 203

___UnLock
Revokes the exclusive reservation of an object. The current object can now be accessed by all other users ac-
cording to the rights configuration.

Syntax
___UnLock ( );

Parameters
<None>

Return Values
Value Description
0 Command executed successfully
1 The user currently logged on does not have the right to run this function
6 Reservations cannot be revoked by the application, which is usually not installed
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
If Productstream Professional Access Control Manager (ACM) is installed, the change also applies to the rights
to those files dependent on a type AIM.DOC data record.
The function evaluates the dynamic rights. If the function is shown in the menu, it deactivates the menu ac-
cording to the current data record.
Programming
The behavior can be influenced by a public function:
PreUnLock
___UnLock checks whether this function has been defined for the current element. If this public function has
been defined, it is performed before the lock is actually removed, but not until all the other rights have been
checked. The function is called without any arguments.
The lock can only be removed if the return value is 0. If the return value is not 0, ___Unlock itself sets the
return value to 6 (see Return values). In this case, it is assumed that an error message has been issued for the
environment variable ApplLockErrMsg in the function PreUnLock.
Version 5.4.1.6

See also
___Lock
___UnLock
___ForceUnLock
 204

___WriteAimXML
This function controls how elements are exported from Productstream Professional. First of all, it writes the
header of a Productstream Professional XML data file and then calls the hand-over function for each object
which is to be exported. This function performs the export routine for each individual element. Finally, the
compatible footer of the XML file is written to the header.

Syntax
___WriteAimXML ( <MapName> <XMLFileName> <Function> [<Parameter>] );

Parameters
<Mapname>
Name of a map from <Key>=<Value> pairs. The structure of this map is as follows:
<Key>
Record ID (internal Productstream Professional unique flag of an object within a context). This Record ID
can be ascertained using #(RECID).
<Value>
EntityType object of the record. If this is an object (a master object) directly selected for export, the number
1 follows separated by a space. If these are linked objects which are to be exported, the number 0 is given.

Example
12345=AIM.DOC.ENG 1
98765=AIM.CONTACT.PERSON 0
…

XMLFileName
XML data is written to this file..
Function
Name of a Productstream Professional function being sought in the Productstream Professional object model.
This enables the user to individually define for each object how its information is provided for exporting. For
example, an object with documents (a document record) can ensure that the files are exported as well. This
function is automatically assigned the number 1 as the first argument if it is a directly selected object, and a 0
if it is not.
[<Parameter>]
Optional parameters are handed over to the function as the second and subsequent parameters.

Return Values
Value Description
0 Command executed successfully
1 Copying has been terminated by selecting Cancel
2 The selection is empty (does not contain any objects)
3 The arguments are incomplete
4 The function has been recursively called, which is not permitted
unequal to 0 Error (no further details given, error message in the file errlog.err)
 205

Notes
This function uses a special, internal program XML file object in Productstream Professional. It is initialized
here and used in the function defined by <Function>. As there is only one such XML file object,
___WriteAimXml may not be called as a nested function..

Examples
Writing an XML header file using the objects in a map:
___WriteAimXml ( "#(MAP get AllElements)" "#(MAP get outputFileName)" "WriteXMLRecord"
"#(MAP get outputDirectory)" );

See also
#(Map ...)
___Map
___ImportDlg
___ImportUnPack
___ImportExecute
___ImportCheck
___ImportElement
___ExportDlg
 206

___WriteConfiguration
Allows data to be written directly to the Productstream Professional configuration. New and existing attributes
can be entered or changed for the element types DocumentTypes, ApplicationTypes, Folders and EntityTypes
in the Productstream Professional object model. Unless stated otherwise, any changes are made in the confi-
guration profile of the user logged on at that time.

Syntax
___WriteConfiguration ( [-publish] <Component> <Attribute> <Value> );

Parameters
[-publish]
The component from the current user profile is published to the parent profile Customer:System. Entered va-
lues are ignored.
<Component>
Component of which an attribute is to be modified or a new one added. The component must exist.
<Attribute>
The specified attribute is modified. The attribute is created if it does not already exist.
<Value>
The specified value is assigned to the attribute.

Return Values
Value Description
0 Command executed successfully
-1 Incorrect number of parameters or unknown error
-2 Invalid component or attribute specified

Notes
The entire string is substituted in the current object before it is executed.
Attributes can only be directly modified or added for the element types DocumentTypes, ApplicationTypes,
Folders or EntityTypes.
The following attributes cannot be modified:
• Super
• DefaultOwner
• DefaultRights
• GroupRights
• OwnerRights
Example
Changing the start value when creating a new attribute:
___WriteConfiguration ( #(DBNAME) StartKey 00-00001 );
The start value for the current folder object (#(DBNAME)) is set to 00-00001.

See also
Variables
Formatting
 207

___WriteRecInfo
Objects are written to a file (see ___ReadRecInfo). Files are not taken into consideration.

Syntax
___WriteRecInfo ( <FileName> <FileMode> [<ElementMode>] [<UnicodeFormat>]);

Parameters

Parameter Arguments Description

<FileName> The object is written to the specified file.
<FileMode> -o If the file <FileName> exists, it is overwritten with the new data.
[<ElementMode>] <blank> If no parameters are defined, all the selected objects are processed. If no object has
been selected, the current object is used.
-one The current object is written out.
-all All the objects in the active folder object are written out.
[<UnicodeFor- [-ansi|- Defines the Unicode format
mat>] utf8|-
utf16|-
utf16_be|-
utf16_le]

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
Examples
Reading in a previously created standard file:
___WriteRecInfo ( "$(WsPath:|+)RecData.rec" -o –one );
___ReadRecInfo ( nul() "$(WsPath:|+)RecData.rec" SDF 0;1;1; );
This is the simplest method of reading in data. The object which was previously written out is read in further
below. This triggers the generation of a key.

See also
___ReadRecInfo
Formatting
 208

___WriteRegistry
Writes values to the Windows registry.s

Syntax
___WriteRegistry ( <Tree> <Key> <Attribute> <Value> );

Parameters
<Tree>
Defines the tree where the key is to be entered. The following values are permitted:
• HKEY_CLASSES_ROOT
• HKEY_LOCAL_MACHINE
• HKEY_CURRENT_USER
<Key>
The attribute is created for the specified key. The key is not created if it does not exist. Backslashes "\" are used
as separators in the key structure analog to folder structures.
<Attribute>
The specified attribute is created or modified for the defined key. If a value is not given here, the value of the
Default subkey in <Key> is changed.
<Value>
The specified value is entered. The types REG_SZ und REG_DWORD are supported for this attribute. With
REG_DWORD, the system attempts to convert the argument <Value> into a DWORD. The value is then
written.
If <Attribute> does not exist, it is created using the type REG_SZ.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
If the user has not been granted the appropriate rights to write the key, the function is terminated without an
error message.
The values are not case-sensitive.
The entire string is substituted in the current object before it is executed.

Examples
Changing the Productstream Professional path details using the registry:
___WriteRegistry (HKEY_LOCAL_MACHINE "Software\Autodesk\Productstream Professional\7.0"
"PRGPATH" "X:\Productstream Professional\Server" );
The Productstream Professional server directory is written for this workstation.
Associating the file extension ZIP with WinZip:
___WriteRegistry ( HKEY_CLASSES_ROOT ".zip" "" "WinZip" );
The extension .zip is explicitly associated with WinZip. If the key .zip does not exist, the file extension is not
associated.
 209

___WriteSDF
All the field values for all or a single data record are written to a specified file.

Syntax
___WriteSDF ( <FileName> [<Type>] <FileMode> [<ElementMode>] [<Fields>] [<UnicodeFormat>]);

Parameters

Parameter Arguments Description

<FileName> The elements are written to the specified file.
[<Type>] <blank> -sdf is always used if no output type is defined.
-cdf or cdf One element is written in each line in the file. The fields in the element are separated by com-
mas and directly follow one another.
-sdf or sdf One element is written in each line in the file. The fields in the element directly follow one ano-
ther without separators.
-tab or tab One data record is written in each line in the file. The fields in the data record are separated by
tabs and directly follow one another.
<FileMode> -o If the file <FileName> exists, it is overwritten with the new data.
[<ElementMode>] <blank> If no parameters are defined, all the selected data records are processed. If no element has been
selected, the current element is used.
-one The current element is written out.
-all All the elements in the active folder object are written out.
[<Fields>] Only any specified field names are processed in the given sequence.
[<UnicodeFor- -ansi, -utf8, Specifies the Unicode format to use
mat>] -utf16,
utf16_be,
-utf16_le

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The entire string is substituted in the current object before it is executed.
With ___ForAllRela, a specific selection can be written out using the parameters -o and -one.

Examples
The current object is returned separately and separated by a comma:
___WriteSDF( "$(WSPATH:|+)Rec_Cdf.txt" –cdf –o –one );
All the objects in the current context are returned:
___WriteSDF( "$(WSPATH:|+)Rec_Cdf.txt" –sdf –o –all );
All the AutoCAD elements in the engineering folder are returned:
___ForAllRela ( db=Folder_EngineeringDocument FILE_TYPE='A'___WriteSDF
"$(WSPATH:|+)Rec_Cdf.txt" –sdf –o –one );

See also
___ReadRecInfo
 210

___WriteSTD
This function writes a structure file for the current context.

Syntax
___WriteSTD ( <FileName> [-o] [-ansi|-utf8|-utf16|-utf16_be|-utf16_le]);

Parameters
<FileName>
The field structure is written to the specified file.
[-o]
If this flag is used, no acknowledgement is required to overwrite the file if it already exists.
[-ansi|-utf8|-utf16|-utf16_be|-utf16_le]
Specifies the Unicode format to use

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
The file is generated using the following format:
<FieldName> {C|D|N} <Length> <DecimalPositions>
Auszug:
AIMKEY N 17 5
ENTITY_TYPE C 80 0
COPY_OF_AIMKEY N 17 5
OLD_DOC_AIMKEY N 17 5
SHORT_DESC C 80 0
...

Examples
Writing the structure file for the active folder:
___WriteSTD ( "$(WsPath:|+)AktStd.txt" –o );
The parameter -o means that no acknowledgement is required to overwrite the file if it already exists..

See also
___WriteSDF
___ReadRecInfo
 211

___WriteXMLSchema
A function for writing the schema files for exporting Productstream Professional data. An XML schema file is
written.

Syntax
___WriteXMLSchema ( <FileName> <SQLTable or View> <FolderName> [<FolderObject>] );

Parameters
<FileName>
File name in the XML schema file. This file is generated using the information from the specified folders.
<SQLTable or View>
Name of the table stored in the schema file. Required for generating the table in the database..
<FolderObject>
Name of one or more Folder objects, whose column names must be included in the schema and SQL script.
The field names of the basis tables with the field definitions are collated from all the folders specified here and
are used for generating the files.

Return Values
Value Description
0 Command executed successfully
unequal to 0 DocumentTypes, ApplicationTypes, Folders and EntityTypes

Notes
The files are written in a form which can be read by ___ImportExecute.
All the fields from all the specified <FolderNames> are listed In the schema file. The field names of the basis
tables are also written.
The following fields are not taken into consideration:
• Fields in the table XREF_ELEMENT
The following fields are not required by the target system, as all the rights have to be reassessed and evaluated
following import::
• RIGHTS
• OWNER
• OWNER_GROUP
• WORLD_GROUP
• FILE_ORIG_AT
• FILE_ORIG_TO
• DELETE_DATE
• DELETE_INITIATOR
 212

Examples
Generating an XML schema from the current context:
___WriteXMLSchema ( "$(WsPath:|+)Export.xml" #(DBI:DBVIEW) #(DBNAME) );
The format of the current context is written in Export.xml.

See also
#(Map ...)
___Map
___ImportDlg
___ImportUnPack
___ImportExecute
___ImportCheck
___ImportElement
___ExportDlg
 213

___XdwCmd
SQL statements are performed directly on the database currently being used by Productstream Professional.

Syntax
___XdwCmd ( {"<SQLStatement>"|<SQLFunction> [<Parameter>]} );

Parameters
"<SQLStatement>"
The SQL statement is directly performed on the database. The statement must be a valid SQL statement. The
SQL statement is substituted on the current object.
<SQLFunction> [<Parameter>]
The specified SQL function (Stored Procedures) is performed on the database. The given parameters are sub-
stituted and passed on to the function. It is advisable to use the function #(xdwsfkt), as the value returned by
the function can be directly saved.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
Caution!
The SQL statement does not relate directly to the current data record when it is performed. It must be ensured
that a valid WHERE clause is sent together with the statement.

In addition, the following variables are available for evaluation purposes once the statement has been run:
• CMD_ERROR_NO
• CMD_ERROR_MESSAGE
• CMD_ERROR_SOURCE
• CMD_ERROR_DESCRIPTION

Examples
Changing the designation (field SHORT_DESC) of a released data record (no write permission):
___XdwCmd ( "update #(DBI:DBVIEW) set SHORT_DESC='New text' where AIMKEY=#(AIMKEY)" );
The designation is changed to "New text" for the current object (because AIMKEY=#AIMKEY).
Performing an SQL function:
___XdwCmd ( aim_xdwcmd_test 'AIMKEY = ', 4711.99999 );
The function aim_xdwcmd_test is performed and the listed function parameters are passed on.

See also
#(xdwsfkt)
 214

___xEditDocument
Used to edit a document with a template.

Syntax
___xEditDocument ( <InquiryMode>; <Inquiry>; <File>; <FileNumber>; <Command> );

Parameters
<InquiryMode>
Controls the usage of a template:
0: query only, if file does not exist
1: query always
2: always use existing template file
<Inquiry>
Here, the query text is defined. If <InquiryMode> = 0 or 1. If <InquiryMode> = 2: Query if already a file exists
in conjunction with the document number.
<File>
Path and file name of the template file, or the default setting of the dialog.
<FileNumber>
Defines which file is to be used to check the existence of a file. The permitted values are 0 - 5. These correspond
to the values for Path0 to Path5 stored in the configuration.
<Command>
The defined shell command is run. nul() must be entered if a shell command is not to be run.

Return Values
Value Description
0 Command executed successfully
unequal to 0 Error (no further details given, error message in the file errlog.err)

Notes
A query is displayed asking whether an additional file is to be used (e.g. Use CAD geometry?) If the response
is Yes, a file can be specified by giving the path, file name and extension. This file must exist. Parameters can
be set for the default setting. The path, file name and extension are then attached to the parameterized com-
mand as independent parameters.

See also
___Shell
___Execute
___xExecute
 Advanced search 215

Chapter 14 Productstream Professional event procedures

Advanced search
ExtendedSearchSave
Called from the Advanced Search dialog window with the button Save.
Parameters
None
Context
Dialog window data record.

ExtendedSearchSaveAs
Called from the Advanced Search dialog window with the button Save as.
Parameters
None
Context
Dialog window data record.

Drag & drop

DragSupported
Is called during drag & drop when beginning to drag a file.
Parameters
Number of dragged entries (#nummark).
Context
Folder from where the data records are being dragged.
Important: No element context!
Return value
0: If drag & drop is not permitted from this context
1: If drag & drop is permitted from this context
If 0 is returned, drag & drop is fundamentally not permitted from this context.

GetDropEffectIntern
This function is called when internal Productstream Professional elements are dragged onto another internal
Productstream Professional element.
Parameters
Common element type of the dragged elements
If AIM.DOC.ENG and AIM.DOC.OFF are dragged together, this value is AIM.DOC
Required drop effect
DEFAULT: if no key is pressed while dragging
MOVE: if the Shift key is pressed while dragging
COPY: if the CTRL key is pressed while dragging
LINK: if the Shift and CTRL keys are pressed while dragging
 Drag & drop 216

Return value
The following values must be returned according to the required effect:
0: If Drop here is not permitted
1: If Copy
2: If Move
4: If Link

GetXDropEffectIntern
This function is called when internal Productstream Professional elements are dragged onto an empty area or
the Productstream Professional title bar..
Parameters
Common element type of the dragged elements
If AIM.DOC.ENG and AIM.DOC.OFF are dragged together, this value is AIM.DOC
Drop effect:
• DEFAULT: If no key is pressed while dragging
• MOVE: If the Shift key is pressed while dragging
• COPY: If the CTRL key is pressed while dragging
• LINK: If the Shift and CTRL keys are pressed while dragging
Return value
The following values must be returned according to the required effect:
0: If Drop here is not permitted
1: If Copy
2: If Move
4: If Link

OnDropIntern
This function is called when Productstream Professional elements are dropped onto a record. The parameters
and return values are analog to OnXDropIntern.

OnXDropIntern
This function is called when Productstream Professional elements are dropped onto an empty area or the folder
title bar.
Parameters
Common element type of the dragged elements
If AIM.DOC.ENG and AIM.DOC.OFF are dragged together, this value is AIM.DOC
Required drop effect:
• DEFAULT: If no key is pressed while dragging
• MOVE: If the Shift key is pressed while dragging
• COPY: If the CTRL key is pressed while dragging
• LINK: If the Shift and CTRL keys are pressed while dragging
Name of the selection containing the dragged element.
This can be addressed using ___Selection enumerate.
Return value
None
 Drag & drop 217

GetDropEffectExtern
Files and the Outlook elements Tasks, Message, Contact and Note can be dragged into Productstream
Professional.
This function is called when files or Outlook elements are dragged onto an internal Productstream Professional
element.
Parameters
Required drop effect:
• DEFAULT: If no key is pressed while dragging
• MOVE: If the Shift key is pressed while dragging
• COPY: If the CTRL key is pressed while dragging
• LINK: If the Shift and CTRL keys are pressed while dragging
Type of the dragged elements
• „FileName“: If files are being dragged
• „Outlook“: If Outlook elements are being dragged
Number of elements that can be moved by drag & drop.
File name
If the parameter is 2 FileName and only one file has been moved, this parameter is the file name of the dragged
file.
Return value
The following values must be returned according to the required effect:
0: If Drop here is not permitted
1: If Copy
2: If Move
4: If Link

GetXDropEffectExtern
Files and the Outlook elements Tasks, Message, Contact and Note can be dragged into Productstream
Professional.
This function is called when files or Outlook elements are dragged onto an empty area or the folder title bar.
Parameters and return values, see
 Menu functions 218

OnDropExtern
Files and the Outlook elements Tasks, Message, Contact and Note can be dragged into Productstream
Professional.
This function is called when files or Outlook elements are dragged onto an internal Productstream Professional
element.
Parameters
Required drop effect
DEFAULT: If no key is pressed while dragging
MOVE: If the Shift key is pressed while dragging
COPY: If the CTRL key is pressed while dragging
LINK: If the Shift and CTRL keys are pressed while dragging
Type of the dragged elements
"FileName: "If files are being dragged
"Outlook: "If Outlook elements are being dragged
File names of the dropped files/Outlook elements
File names of the dropped files/Outlook elements in a list. Note: Dragged Outlook elements (type "Outlook")
are stored in a Windows temporary folder. These files are no longer automatically deleted. This must be done
using DBP code.
Return value
Is not evaluated.

OnXDropExtern
Files and the Outlook elements Tasks, Message, Contact and Note can be dragged into Productstream
Professional.
This function is called when files or Outlook elements are dragged onto an empty area or the folder title bar.
Parameters and return values see Parameters and return values, see Menu functions

Menu functions
___CheckCondition
This function is used for graying out menu options.
Parameters
Name of the condition.
Context
Active data record.

Create new element and Edit dialog windows

m_closeOnly
This function is called when the Create new / Edit dialog windows are closed from the system menu.
Parameters
None
Context
Current data record.
Return value
Is not evaluated by the EXE file.
 Editing fields in a data sheet / list 219

ObligatoryFieldViolation
Is used to display a message when an obligatory field is left empty and the user tries to save the element.
Parameters
• Field designation as given in the configuration.
• Name of the field.
• Original contents of the field.
Context
Current data record.
Return value
Is not evaluated by the EXE file.

Editing fields in a data sheet / list

PreUpdateField_<FieldName>
This function verifies whether a field can be edited. If the function returns 0, the value in the interface cannot
be changed. This applies for all interface elements, including Create new/Edit dialog windows.
Parameters
None
Context
Current data record.
Return value
1: The field may be edited
0: The field may not be edited

OnUpdateField_<Feldname>
This function is used to perform special checks or changes after a field in an element has been edited.
It is called when editing fields directly in the list or data sheet prior to actually saving the element. It is not
called when editing fields in the Edit dialog window.
Parameters
New value for the field.
Context
Active data record.
Return values
0 The change may not be applied
1 The change may be applied
2 The change has already been applied to the field:
(per ___RecordBuffer(set…))
Productstream Professional must update this element.
4 The change has already been applied in the procedure:
(per ___ChangeField)
Productstream Professional does not have to update this element.

Compass bar
Environment variable ACTIVE_SECTION
The COMPASS bar sets the environment variable ACTIVE_SECTION. It contains the AIMKEY of the ac-
tive open section.
 Preview window 220

Preview window
m_ShowDocFile
This function is triggered when the menu option "View in external viewer" is selected in the internal preview
window.
Parameters: None
Context: Current data record
Return value: Is not evaluated by the EXE file
 221

Chapter 15 Internal functions executable in Productstream

Professional Webserver

Function Description
___AskQ
___Break_Enum
___ChangeField
___ChangePassWord
___ChangeStatus
___CheckExtensionFlags
___CloseArchiv
___CmpUtility These functions are allowed for Productstream Professional Webserver __WriteLinks__,
__WritePublic__, __WriteRights__, __WriteSelection__, __WriteStatus__,
__WriteSyspar__, __WriteUtex__, __WriteUtexAll__
___CompassInfo
___DBUtils Allowed Functionn: Sync (with parameter Current, App, All, Sele)
___DeleteRecord
___EnumFields
___EnumToken
___Environment
___ErrLog
___ExportCollect
___ExportDataObjectDestroy
___ExportExecute
___FolderBar
___FolderStructure
___ForAllRela
___ForAllRelaH
___ForRela
___ForRelaH
___ForTable
___ImportCheck
___ImportElement
___ImportExecute
___JobCreate
___LinkElement
___Lock
___LogWrite
___Map
___New_Object
___NotInstalled
___OpenArchiv
___OpenGUIViewWindow
___OpenHelp
___Prepare
___Print
___PrintStl
 222

Function Description
___RecordBuffer
___ResetFolder
___Return_0
___Return_1
___ReturnString
___Selection
___SetRights
___Shell
___UnLock
___WriteAimXml
___WriteCOnfiguration
___WriteXmlSchema
___XDWCmd
___xEditDocument
 223

Chapter 16 Not recommended functions

The functions listed below are not recommended to be used anymore. They have been mostly replaced by
functions of higher performance and remain only because of compatibility reasons.

Old function New function Description

___Ask ___AskQ Dialog window with custom text and up to three buttons.
___ChkCondition #(== ...) or <direct Check condition and react accordingly
use of the condi-
tion>
___Compare wcomp Checks if String 2 contains String 1
___EditDocument Public Open Editing the document of the current data record
___Execute ___Shell Executes an operating system command
___Exist Exist Checks if the file exists
___ForRecordCallFunc ___ForRela, Executes functions for a specific data record.
___ForRelaH
___PerfLog
___Print PrintReport Report printing functionality
___PrintStl PrintReport Report printing functionality
___ShellnoSubst ___Shell Shell-Function without substitution
___StartJobserver Starts Productstream Professional Jobserver
(starts only on Productstream Professional launch with -jobserver)
___xExecute ___Shell Executes an operating system command
calldbpproc #(call) Executes a function with a return value
 224

Chapter 17 Suspended functions

The functions listed below cannot be used anymore. They are no longer supported

Suspended Functions
___ExportCleanOutputDirectory
___ExportPack
___ForSelected
___Print
___PrintSTL
___ImportUnPack
#(DTYAppl...)
#(DTYGetValidAppl ...)
#(DTYNAME)
#(MNUNAME)
#(TBXNAME)
#(acadsession)
#(acadsessiontype)
#(acadsessiontypes)
#(acadsessions)
#(acadsessionThreadId)
#(CMPOS)
#(CMPFLAGS)
#( NEWPATH<n> )
dbshown
dbopen