CONTENTS Title Page Copyright Page Preface 1 Programming Concepts 1.1 CDD/Repository Operations 1.1.1 Order of Processing 1.1.2 Related Routines 1.2 C and VMS Bindings 1.3 Symbol and Entry Point Definition Files 1.4 Routine Entry Points 1.5 Status Return Values 1.6 Data Types 1.7 Numeric Constants 1.8 String-Valued Name Arguments 1.9 Linking Applications that Call CDD/Repository 1.10 Linking Applications Called by CDD/Repository 2 Getting Started 2.1 Basic Operations 2.2 Using Sessions 2.3 Using Transactions 2.4 Accessing Repository Databases 2.5 Manipulating a Repository 2.5.1 Reading an Instance of an Element 2.5.2 Preparing Argument Lists 2.5.3 Sending Messages 2.5.4 Analyzing Results 2.5.4.1 Possible Errors 2.5.4.2 Using Returned Information 3 Storing and Manipulating Data 3.1 Data Types 3.2 Packaging Data in Value Structures 3.2.1 Loading Data in Value Structures 3.2.2 Retrieving Data from Value Structures 3.2.3 Freeing Data in Value Structures 3.2.4 Other Operations on Value Structures 3.3 Numeric Data Types 3.4 BOOLEAN Data Type 3.5 String Data Types 3.5.1 Null-Terminated Strings 3.5.2 String Descriptors 3.6 Date and Time Data Types 3.7 Memory Block Data Type 3.8 Element ID Data Type 3.9 Scan Data Type 3.9.1 Accessing Scan Contents 3.9.2 Adding an Element 3.9.3 Accessing Relationships 3.9.4 Removing an Element 3.9.5 Initializing a New Scan 3.10 List Data Type 3.10.1 Creating and Deleting Lists 3.10.2 Retrieving a List Entry 3.10.3 Inserting, Removing, and Setting List Entries 3.10.4 Finding the List Length 3.11 Argument Lists 3.11.1 Building Argument Lists 3.11.2 Embedding Argument Lists 3.11.3 Modifying List Entries 3.12 Returned Arguments 3.12.1 Reading by Name 3.12.2 Reading by Index 4 Working with Elements 4.1 Creating Instances 4.1.1 Placing an Element Under Control 4.1.2 Reserving an Element 4.1.3 Replacing a Reserved Element 4.1.4 Canceling a Reservation 4.2 Creating Element Types 4.2.1 Reserving the Metadata Collection 4.2.2 Defining Element Types 4.2.3 Replacing the Metadata Collection 4.3 Changing Element Types 4.3.1 Using the RESERVE Method 4.3.2 Using the REPLACE Method 4.4 Compatible and Incompatible Changes 4.4.1 Element Type and Relation Type Changes 4.4.2 Property Type Changes 5 Working with Methods 5.1 Dispatching Operation 5.2 Invoking MCS_dispatch_op 5.3 Refining Methods 5.4 Validating Refined Methods 5.5 Method Categories 5.6 Refining External Code Methods 5.6.1 Method Function Calling Sequence 5.6.2 Method Functions and Transactions 5.6.3 Invoking the Supertype Method 5.6.4 Associating the Element METHOD with External Code Methods 5.7 Refining External Program Code Methods 5.7.1 Invocation Strings 5.7.2 Invocation String Syntax 5.7.3 Substituting Dispatch List Arguments 5.7.4 Substituting Property Values 5.7.5 Substituting Values from Structured Data Types 5.7.5.1 Substituting Values from Lists 5.7.5.2 Substituting Values from Scans 5.7.5.3 Substituting the Length of a Memblock 5.7.6 Representation of Substituted Values 5.7.7 Associating External Program Methods with Files 6 Defining Properties 6.1 Normal Properties 6.2 Relation and Closure Properties 6.3 Defining Computed Properties 6.3.1 Defining Computed Properties Whose Value Is a Scan 6.3.2 Coding a Scan Computation Routine 6.4 Refining the setProp and new Methods 6.4.1 Side Effects of Setting Property Values 7 Using Notices 7.1 Notice Services 7.2 When Notices Are Sent 7.3 The MCS_NOTICE_ACTION Property 7.4 Notice Actions After a Change 7.5 Notice Actions for New Elements 7.6 Notice-Processing Calls 7.7 NOTICE Data Type 8 Routine Descriptions MCS_arglist_addArg MCS_arglist_findArg MCS_arglist_getArg MCS_arglist_setIndexValue MCS_arglist_setNameValue MCS_check_notices MCS_clear_notices MCS_datatype_compare MCS_datatype_copy MCS_datatype_datatype MCS_datatype_free MCS_datatype_length MCS_datatype_new MCS_datatype_read MCS_DB_close MCS_DB_free MCS_DB_new MCS_dispatch_op MCS_dispatch_superOp MCS_element_getByName MCS_element_getName MCS_element_getSubTypeList MCS_element_getSuperTypeList MCS_element_getType MCS_elmid_copy MCS_elmid_equal MCS_elmid_export_persistent MCS_elmid_getContext MCS_elmid_getPersistentProcess MCS_elmid_getSession MCS_elmid_import_persistent MCS_elmid_isNull MCS_elmid_isSubtype MCS_errorstack_clear MCS_errorstack_clearAll MCS_errorstack_format MCS_errorstack_getCurrentSize MCS_errorstack_getMaxSize MCS_errorstack_getStatus MCS_errorstack_set MCS_errorstack_setMaxSize MCS_fileop_copy MCS_fileop_delete MCS_fileop_journal_create MCS_fileop_journal_modify MCS_fileop_mkdir MCS_fileop_rename MCS_fileop_rmdir MCS_fileop_rmlink MCS_fileop_symlink MCS_fileop_unjournal_create MCS_force_notices MCS_initiate_database MCS_list_free MCS_list_get MCS_list_getSize MCS_list_insert MCS_list_new MCS_list_remove MCS_list_set MCS_read_notice MCS_scan_dir MCS_scan_free MCS_scan_getByName MCS_scan_getCurrent MCS_scan_getFirst MCS_scan_getNext MCS_scan_insert MCS_scan_insertWithArgs MCS_scan_new MCS_scan_query MCS_scan_remove MCS_scan_reset MCS_session_initiate MCS_session_terminate MCS_session_transaction_init MCS_session_transaction_term MCS_set_default A Error Handling A.1 Format of the Error Stack A.2 Manipulating the Error Stack A.3 Errors During Message Processing A.3.1 Handling Errors A.3.2 Handling Success, Informational, and Warning Status Values A.3.3 Handling Error and Fatal Status Values A.3.4 Reading from the Error Stack A.3.5 Putting Messages on the Error Stack A.3.6 Unexpected Errors A.3.7 Setting the Status Field in an Argument List B Utility Routines CDD$TRANSLATE CDD$VERIFY CDD$VERSION CDO$CHECK_MESSAGES CDO$INTERPRET C Buffers C.1 Buffer Format C.1.1 Block Header C.1.2 Buffer Body C.1.3 Block Terminator C.2 Buffer Types C.3 Simple Literals C.4 Access Control List Buffer C.5 Dictionary Query Buffer C.5.1 All Descendants C.5.2 Specific Descendants C.5.3 Components of a Data Aggregate C.5.4 Element Owner C.6 Directory Information Buffer C.7 Edit String Buffer C.7.1 Edit String Buffer Tags C.8 Expression Buffer C.8.1 Value Expressions C.8.1.1 Arithmetic Expressions C.8.1.2 Database Key Expressions and Field Expressions C.8.1.3 From Expressions C.8.1.4 Function Expressions C.8.1.5 Literal Expressions C.8.1.6 Statistical Expressions C.8.1.7 String Expressions C.8.1.8 VIA Expressions C.8.1.9 VIA Table Expressions C.8.2 Boolean Expressions C.8.2.1 Relational Expressions C.8.2.2 Logical Expressions C.8.3 Record Selection Expressions C.8.4 Conditional Expressions C.8.5 Table Expressions C.8.6 Expression Buffer Tags D Protocol Validations D.1 CDD$AGG_ALIGN_VAL D.2 CDD$ARRAY_ORDER_VAL D.3 CDD$DATA_DIM_HIGH D.4 CDD$DATA_DIM_LOW D.5 CDD$DATATYPE_VAL D.6 CDD$DEPEND_ID_VAL D.7 CDD$DIGITS_LENGTH D.8 CDD$DTYPE_DIG_SCALE D.9 CDD$DTYPE_JUSTIFY D.10 CDD$DTYPE_LENGTH D.11 CDD$DV_ALL_NONE D.12 CDD$INPUT_PROMPT_VAL D.13 CDD$INST_PATH D.14 CDD$JUSTIFY_VAL D.15 CDD$ONE_INST_ROOT D.16 CDD$OUT_HEAD_VAL D.17 CDD$PATH_STEP_VAL D.18 CDD$REQ_DATA_VAL_EXP D.19 CDD$REQ_INIT_VALUE D.20 CDD$REQ_MISS_VALUE D.21 CDD$REQ_PTR_REF D.22 CDD$REQ_SEG_STRING D.23 CDD$SEQ_NUM_VAL D.24 CDD$UNIQ_ARRAY_ORDER D.25 CDD$UNIQ_DAC_SEQ_NUM D.26 CDD$UNIQ_DEPEND_ID D.27 CDD$UNIQ_DOAC_SEQ_NUM D.28 CDD$UNIQ_DOC_SEQ_NUM D.29 CDD$UNIQ_INST_PATH E Literal Values E.1 General-Purpose Buffer Tags E.2 Justification Flags E.3 Notice Types E.4 Notice Action Flags E.5 Protection Bits in Access Control Lists EXAMPLES 2-1 Reading an Instance 2-2 Reading a List 2-3 Reading an Argument List 5-1 Calling MCS_dispatch_superOp 6-1 Implementing a Computed Scan Property 6-2 Refining setProp to Check a Value A-1 Displaying the Contents of the Error Stack A-2 Returning an Error Status A-3 Returning a Memory Allocation Error FIGURES 1 CDD/Repository Documentation Chart 2-1 Programming Sequence 2-2 Finding an Element Type 3-1 Storing Data in Value Structures 3-2 Reading Data from a Value Structure 3-3 Scans 3-4 Getting Element and Relation IDs from Scans 5-1 Method Dispatching 5-2 External Code Methods and Entry Points A-1 The Error Stack TABLES 1 Documentation Conventions 1-1 Data Definition Files 3-1 CDD/Repository Data Types 4-1 Option Values 5-1 Invocation String Syntax Summary 7-1 Values of the MCS_NOTICE_ACTION Property B-1 Values Used with the Actions Parameter C-1 Buffer Version Numbers C-2 Purpose of Buffers C-3 Buffer Types and Tag Values C-4 Translation of CDD$K_EDIT_STR_FLOAT_0_REPLACE Characters C-5 Translation of CDD$K_EDIT_STR_LITERAL Edit Strings C-6 Translation of CDD$K_EDIT_STR_MINUS_LITERAL C-7 Edit String Buffer Tags C-8 Expression Buffer Tags E-1 Buffer Tags and Values E-2 Justification Flags E-3 Notice Types E-4 Notice Action Flag E-5 Protection Bits in Access Control Lists