Developer's Reference
1 AVS/Express overview
1.1 Overview 2
1.1.1 Working with AVS/Express 3
1.1.1.1 The Network Editor 3
1.1.1.2 V language 4
1.1.1.3 The NE versus V 5
1.1.1.4 Application Programming Interfaces 5
1.1.2 AVS/Express kits 6
1.1.3 Object-oriented techniques in AVS/Express 7
1.1.4 Connections and object execution 9
1.1.5 Object Manager 11
1.2 Project mechanism 13
1.3 Application components 15
1.4 Building applications and application components 18
1.4.1 Building an application using AVS/Express 18
1.4.2 Building application components with AVS/Express 18
1.4.3 Adding modules to AVS/Express 19
1.5 AVS/Express object hierarchy 20
2 Defining and manipulating objects in AVS/Express
2.1 Terms and concepts 2
2.1.1 Objects 2
2.1.2 Base types 2
2.1.3 Templates 3
2.1.4 Instances 3
2.1.5 Object-oriented paradigm 3
2.2 Object hierarchy 4
2.3 Object characteristics 7
2.3.1 Name 7
2.3.2 Derivation hierarchy 7
2.3.3 Declaring the dimensions of an array 7
2.3.4 Properties and attributes 12
2.3.5 Subobjects 12
2.3.6 Values and connections 13
2.4 Defining primitive data objects 14
2.4.1 Using ptr objects 14
2.4.2 Constraining primitive data objects 15
2.4.2.1 boolean base type 16
2.4.2.2 enum base type 16
2.4.3 Connection rules for primitive data objects 17
2.5 Defining groups, modules, and macros 19
2.6 Inheritance and the derivation hierarchy 21
2.6.1 Single and multiple inheritance 21
2.6.2 Derivation hierarchy 24
2.6.3 Modifications to templates, derived templates, and instances 25
2.7 Setting the reference mode of a group, module, or macro 27
2.8 Value expressions 31
2.8.1 Scalar expressions 33
2.8.1.1 Examples of scalar expressions 35
2.8.2 Array value expression 36
2.8.3 Dimension conversion in an array expression 39
2.8.4 Uninitialized objects have a null value 40
2.8.5 Data-type conversion 40
2.8.6 Concatenating strings 41
2.8.7 Read-only connections 41
2.9 Connecting objects by name 43
2.9.1 Connecting to a peer by name 44
2.9.2 Connecting to a peer of an ancestor 44
2.9.3 Connecting to a subobject of a peer 45
2.9.4 Resolving an ambiguous reference 45
2.9.5 Limiting connections to one-level 46
2.9.6 Connections to and from arrays 46
2.9.7 Forward references 49
2.9.8 Recursive references 49
2.10 Defining combinations of properties and attributes 50
2.10.1 The merge operation 50
2.10.2 Maintaining properties and attributes 50
2.11 Defining link objects 52
2.12 Defining arrays of groups, modules, and macros 55
2.12.1 Arrays of group references 55
2.12.2 Array of group pointers 56
2.12.3 Array of group values 56
2.12.3.1 Subobjects in the array connect to a common subobject 58
2.12.3.2 Subobjects in the array connect to a parallel array 58
2.12.3.3 An object outside of the array connects to a single element in the array 59
2.12.3.4 Treat the subobjects of the group array as an array itself 59
2.13 Instancing and de-instancing objects 60
2.13.1 Setting the instanced property 60
2.13.2 Using ScratchPad 60
2.14 Built-in functions 61
2.14.1 Mathematical functions 61
2.14.2 Logical functions 62
2.14.3 Array functions 63
2.14.4 cache function 66
2.14.5 index_of function 66
2.14.6 merge function 67
2.14.7 name_of function 68
2.14.8 str_array function 68
2.14.9 str_format function 68
2.14.10 switch function 69
3 V and the V Command Processor
3.1 Introduction 2
3.2 V Command Processor 3
3.2.1 Examples 3
3.2.2 VCP's appearance 4
3.2.3 Entering statements and commands 4
3.2.4 Navigating the object hierarchy 5
3.2.4.1 Current object 5
3.2.4.2 Navigating 5
3.2.4.3 Navigating through Applications and libraries 6
3.2.4.4 Navigation commands are really V modify statements 8
3.2.4.5 V statement rules apply 8
3.3 V comments 10
3.3.1 C-style comments 10
3.3.2 C++-style comments 10
3.3.3 Special comments 11
3.4 V statements 12
3.4.1 General coding rules 12
3.4.1.1 Clauses 12
3.4.1.2 Order of clauses 13
3.4.1.3 Operators 13
3.4.1.4 Where a statement can start 13
3.4.1.5 Separators 13
3.4.1.6 Continuation lines 14
3.4.1.7 Continuing character strings 14
3.4.1.8 Case sensitivity 14
3.4.2 Create statement 15
3.4.3 Modify statement 20
3.4.4 Delete statement 23
4 Projects, libraries, and processes
4.1 Introduction 2
4.2 Install area project 4
4.3 Creating and using your own projects 6
4.3.1 Derived projects and project chaining 6
4.3.2 Creating a project 7
4.3.3 Starting AVS/Express with a specified project 8
4.3.4 Saving a project 8
4.4 Understanding libraries 10
4.4.1 Templates and Libraries objects 10
4.4.1.1 Changing the Libraries hierarchy 11
4.4.2 Global libraries 13
4.4.3 Derived copies of objects 13
4.4.4 Defining a library that does not make derived copies 14
4.4.5 Creating a new library 15
4.4.5.1 Creating a Network Editor library 15
4.4.5.2 Creating a V language library 16
4.4.5.3 Defining libraries in the VCP 18
4.5 Understanding processes 19
4.5.1 Defining the modules in a process 20
4.5.2 Setting the process name 21
4.5.3 Defining the main process 21
4.5.4 Initializing AVS/Express 23
4.5.5 Processing Events 23
4.5.6 Defining a main for your process 24
4.5.6.1 C or C++? 24
4.5.6.2 Integrating AVS/Express objects into Motif/Xt-based applications 24
4.5.7 Adding your own event handlers 27
4.5.8 Exiting a process 28
4.6 Defining an object's process 29
4.7 Compiling a process 31
4.7.1 Shared libraries in AVS/Express 31
4.7.2 Compiling a single process 32
4.7.3 Compiling the express process 33
4.7.4 Compiling all processes 34
4.7.5 Creating a new process 34
4.7.6 Common error messages 35
4.7.7 Editing source code 36
4.8 Understanding the compile process 37
4.8.1 Marking all needed objects 37
4.8.1.1 Handling library dependencies 38
4.8.1.2 Handling dynamic object dependencies 38
4.8.2 Generating code for objects 38
4.8.2.1 Code generated for each method 39
4.8.2.2 Current build directory 39
4.8.2.3 Code generated for cxx_hdr_files and c_hdr_files 40
4.8.2.4 Code generated for cxx_src_files and c_src_files 40
4.8.2.5 Handling the src_file property 40
4.9 Project architecture 41
4.9.1 Project directory 41
4.9.2 XP_PATH and avse
nv 41
4.9.2.1 XP_PATH 41
4.9.2.2 $XP_PATH<0> 42
4.9.2.3 avsenv
42
4.9.3 templ.v 43
4.9.4 pr
oc.v 44
4.9.5 libs.v 44
4.10 Save Compiled Project 46
4.10.1 Save Compiled Project Dialog 46
4.10.1.1 Project directory name 47
4.10.1.2 Object selection mode 48
4.10.1.3 Instance objects automatically on restore 48
4.10.1.4 Include Network Editor in project 48
4.10.1.5 Build V into executable 49
4.10.1.6 Compile/Generate project modes 49
4.10.2 Dependences on the original project 50
4.10.3 Files in a compiled project 50
4.10.4 Save Compiled Project examples 51
5 Integrating user code
5.1 Introduction 2
5.1.1 Adding new modules 2
5.1.2 Manipulating instances of objects 2
5.2 Adding new AVS/Express modules 4
5.3 Module creation overview 5
5.3.1 Methods 5
5.3.2 Method naming restrictions 6
5.3.3 Calling methods for instance/de-instance 6
5.3.4 Defining parameter attributes for methods 7
5.3.4.1 Defining parameter attributes on a per-method basis 9
5.3.4.2 Setting parameter attributes on hierarchical parameters 9
5.3.4.3 Specifying the req attribute for a method 10
5.3.5 Defining the scope of an update method 11
5.3.6 Controlling method execution 12
5.3.7 Controlling method execution order 14
5.4 Code management properties for modules 16
5.5 Adding modules using the C API 17
5.6 Adding modules using the C++ API 20
5.6.1 Adding C++ methods 20
5.6.2 Specifying the location of cxxmethod source code 21
5.6.2.1 Using the src_file property 22
5.6.2.2 Using the string value to specify method source 23
5.6.2.3 Detaching cxxmethod from source generation 24
5.6.3 Example C++ module 25
5.7 Adding modules using the FORTRAN API 27
5.8 Manipulating AVS/Express objects using the C API 30
5.8.1 Understanding OM data structures 30
5.8.1.1 Object ids 30
5.8.1.2 Object name 31
5.8.2 Understanding return values 31
5.8.3 Using mode arguments 32
5.8.4 Accessing the object hierarchy 32
5.8.4.1 Accessing the root objects 32
5.8.4.2 Moving up the object hierarchy 33
5.8.4.3 Finding subobjects by name 33
5.8.4.4 Traversing subobjects as a list 35
5.8.5 Determining when a parameter has changed 36
5.8.6 Setting and getting data values 36
5.8.6.1 Scalar primitive values 38
5.8.6.2 array primitive values 40
5.8.6.3 Setting values to the "unset" state 44
5.8.7 Creating and destroying objects 44
5.8.7.1 Creating objects 44
5.8.7.2 Creating objects through V 46
5.8.7.3 Destroying objects 46
5.8.8 Manipulating connections 47
5.8.8.1 Following connections, pointers, and references 48
5.8.9 Managing arrays of groups, modules, macros 51
5.8.9.1 Accessing arrays of groups 51
5.8.9.2 Creating arrays of groups 52
5.8.9.3 Creating new array elements 54
5.8.10 Manipulating properties and attributes 55
5.8.11 Saving and restoring object descriptions 56
5.8.11.1 Save using V language 57
5.8.11.2 Reading V files 58
5.8.11.3 Save using a binary file 59
5.8.11.4 Reading binary V files 60
5.9 Manipulating AVS/Express objects using the C++ API 61
5.9.1 Getting a pointer to the C++ object 62
5.9.2 Accessing values for AVS/Express subobjects 63
5.9.3 C++ interface to scalar data 65
5.9.4 C++ interface to array data 66
5.9.5 C++ interface to group arrays 69
5.9.6 Additional C++ methods 70
5.9.7 Using OM routines 71
5.9.8 Determining when a parameter has changed 71
5.9.9 Manipulating connections 72
5.9.10 Mapping AVS/Express object names to C++ class names 73
5.9.11 Managing C++ generated files 74
5.9.12 Managing dependencies on other code 74
5.9.13 Importing existing C++ classes 76
5.9.14 Constructing user classes 78
5.9.15 Defining abstract user classes 79
5.9.16 Adding your own member variables 79
5.9.17 Exporting C++ classes 80
5.9.18 Example of generated C++ classes 83
5.10 Manipulating AVS/Express objects using the FORTRAN API 88
5.10.1 Understanding OM data structures 88
5.10.1.1 Object ids 88
5.10.1.2 Object name 88
5.10.2 Understanding return values 89
5.10.3 Using mode arguments 89
5.10.4 Accessing the object hierarchy 89
5.10.4.1 Finding subobjects by name 90
5.10.5 Determining when a parameter has changed 91
5.10.6 Setting and getting data values 91
5.10.6.1 Scalar primitive values 94
5.10.6.2 array primitive values 94
5.10.6.3 Setting values to the "unset" state 100
6 Adding status and interrupt controls
6.1 Introduction 2
6.1.1 Status information 2
6.1.2 Interrupt capabilities 2
6.2 Scheduler object 4
6.3 Connecting a user interface to Scheduler 6
6.3.1 To use the standard interface 6
6.3.2 To build your own interface 6
6.3.3 UIdynamic_toggle 7
6.4 Declaring a module's behavior 8
6.4.1 To enable or disable status information 8
6.4.2 To enable or disable interruptability 8
6.5 Setting and querying information from a function 9
6.5.1 To access Scheduler information 9
6.5.2 To set a range for percent done 9
6.5.3 Example module code 10
7 Importing data from simple files using File Access objects
7.1 Overview 2
7.2 file 4
7.3 file_obj(
file, offset, type, columns, ascii_binary [,stride]
) 5
7.4 file_obj_bin (
file, offset, type [,stride]
) 7
7.5 file_scalar_ascii (
file, offset, type
) 9
7.6 file_array_ascii(
file, offset, type, columns
) 10
7.7 file_find_expr(
file, offset, regular_expression
) 11
7.8 file_skip_lines (
file, offset, nlines
) 12
7.9 file_skip_words (
file, offset, nwords
) 12
7.10 Example of importing a file with a uniform field 13
7.11 Example of importing a simple UCD ASCII File 15
8
Debugging objects
8.1 Debugging networks 2
8.1.1 Accessing object information 2
8.1.2 Tracing method execution 3
8.1.2.1 Message for invalid methods 4
8.1.2.2 Message for methods that return 0 status 5
8.1.3 Tracing operations on specific objects 5
8.2 Debugging modules 7
8.2.1 Using a source debugger on the main process 7
8.2.2 Using a source debugger on an external process 7
8.2.3 Getting object information while debugging your module 8
8.2.3.1 Invoking the VCP from the debugger 8
8.2.3.2 Printing an object's path from the debugger 8
8.2.3.3 Problems passing OMobj_ids as arguments 9
8.2.4 Determining why a method will not execute 9
8.2.5 Finding problems with execution order 10
9 Properties, attributes, primitives, and functions
9.1 Properties and attributes 12
9.1.1 General properties and attributes 12
9.1.2 Network Editor properties and attributes 15
9.1.3 Module control properties 19
9.1.4 Code management properties 22
9.1.5 C++ interface properties 28
9.2 Base types 32
9.3 Built-in functions 34
10 Worldwide language and font support
10.1 Introduction 40
10.2 Language support 41
10.2.1 Text representations 41
10.2.2 Local character sets 42
10.3 Locales 45
10.3.1 Locale model 45
10.3.2 Levels of support 46
10.3.3 Initialization 46
10.3.4 Keyboard input 48
10.3.5 Input encoding 48
10.3.6 Output encoding 49
10.3.7 Errors 49
10.3.8 Environment information 50
10.3.9 Supported locales 51
10.3.9.1 Default locale 51
10.3.9.2 Western European languages 52
10.3.9.3 Eastern European languages 53
10.3.9.4 Cyrillic, Greek and Turkish 53
10.3.9.5 Japanese locale 54
10.3.9.6 Korean locale 55
10.3.9.7 Simplified Chinese locale 56
10.4 Text processing 58
10.4.1 Pathways 58
10.4.2 Strings in V 60
10.4.3 Hexadecimal format 62
10.4.4 V output 63
10.5 Localization 65
10.5.1 Username property 65
10.5.1.1 Object Manager interface 66
10.5.1.2 Network Editor interface 66
10.5.2 Localized projects 66
10.5.3 Examples 67
10.5.3.1 Local object name 67
10.5.3.2 Local string object value 68
10.6 Internationalization 70
10.6.1 Dictionary property 70
10.6.2 Dictionary files 71
10.6.2.1 Object Manager interface 72
10.6.2.2 Network Editor interface 72
10.6.3 Internationalized projects 73
10.6.3.1 Original text entries 75
10.6.3.2 Keyword entries 75
10.6.4 Internationalizing a localized project 76
10.6.5 Examples 77
10.6.5.1 Translation of object basename 77
10.6.5.2 Translation of string object value 78
10.7 Adding fonts to AVS/Express 81
10.7.1 fonts.v 81
A User Code Interface (UCI) reference
A.1 Encapsulating a C or C++ structure with the UCI 2
A.1.1 Encapsulating a structure without an update method 2
A.1.2 Referencing structures within a structure 4
A.1.3 Encapsulating a structure with an update method 5
A.1.4 Resolving structure pointers 8
A.1.5 Setting an object's data 9
A.2 Encapsulating an existing C or C++ function with the UCI 11
A.2.1 Calling a C function directly from the UCI 11
A.2.2 What actually happens 12
A.2.3 Data mappings and pointers 12
A.2.4 Image example 14
A.3 UCI reference 16
A.3.1 UCI properties 16
A.3.2 Table of data-type mappings 18
