vasont application program interface guide version 2017.1 confidential------------------------©...

Vasont Application Program InterfaceGuide

Version 2017.1

CONFIDENTIAL------------------------

© 2017 TransPerfect Translations International Inc.All rights reserved. No part of this document may be

reproduced or transmitted in any form or by anymeans, electronic or mechanical, including

photocopying, recording, or any information storageand retrieval system without permission in writing

from the publisher.

Vasont SystemsA TransPerfect Company

221 W. Philadelphia St., Suite 114York, PA 17401717-764-9720

www.vasont.com

© 2017 TransPerfect Translations International Inc.

Document Number: VAPIG-2017.1

TRADEMARKS

Trademarked names appear throughout this book. Rather than list the names and entities that own the trademarks orinsert a trademark symbol with each mention of the trademarked name, the author states that it is using the namesonly for editorial purposes and to the benefit of the trademark owner with no intention of infringing upon that trade-mark.

Table of ContentsOverview of Vasont APIs ..................................................................................................................... 1

Configuration Alterations ............................................................................................................. 1Using the Low-Level Application Program Interface .................................................................................. 3

Key Concepts of the Low-Level API ............................................................................................... 3Variables ................................................................................................................................... 6Finding Arguments in Vasont ........................................................................................................ 7

List of Low-Level API Functions by Groups ........................................................................................... 11API Functional Groups ................................................................................................................ 11

Attributes ......................................................................................................................... 11Batch and Daemon Operations .............................................................................................. 11Children, Descendants and Ancestors ..................................................................................... 11Clone ............................................................................................................................... 12Component Manipulation and Information .............................................................................. 12Extracts and Loads ............................................................................................................. 12Filters, Finds, Bookmarks, Content Types, Collections and Products ............................................ 13Global Change and Shadow History ....................................................................................... 13Pointers ............................................................................................................................ 13Primaries .......................................................................................................................... 14Processing Options ............................................................................................................. 14Raw Material .................................................................................................................... 14User Info, Access Rights and LogIn ....................................................................................... 14Workflow ......................................................................................................................... 15

Frequently Used API Calls ........................................................................................................... 15Attributes ......................................................................................................................... 15Children, Descendants and Ancestors ..................................................................................... 15Component Manipulation and Information .............................................................................. 16Extracts and Loads ............................................................................................................. 16Filters, Finds, Bookmarks, Content Types, Collections and Products ............................................ 16Pointers ............................................................................................................................ 16Primaries .......................................................................................................................... 17Processing Options ............................................................................................................. 17Raw Material .................................................................................................................... 17User Info, Access Rights and LogIn ....................................................................................... 17

List of Low-Level API Functions .......................................................................................................... 19f_allow_add .............................................................................................................................. 19f_allow_approve ........................................................................................................................ 19f_allow_check_in_override .......................................................................................................... 20f_allow_delete ........................................................................................................................... 20f_allow_edit .............................................................................................................................. 20f_allow_project_filter ................................................................................................................. 21f_allow_raw_material_view ......................................................................................................... 21f_allow_reassign_task ................................................................................................................. 21f_allow_reinstate_shadow ............................................................................................................ 22f_allow_workflow_scheduling_override ......................................................................................... 22f_analyze_component ................................................................................................................. 22f_approve_component ................................................................................................................. 23f_approve_descendants ............................................................................................................... 23f_batch_extract .......................................................................................................................... 24f_batch_load ............................................................................................................................. 24f_batch_run ............................................................................................................................... 25f_bookmark .............................................................................................................................. 25

Vasont Application Program Interface Guide

VAPIG-2017.1 CONFIDENTIAL © 2017 TransPerfect Translations International Inc. iii

f_change_expired_password ......................................................................................................... 26f_check_connection .................................................................................................................... 26f_check_in ................................................................................................................................ 27f_check_out .............................................................................................................................. 27f_check_out_status ..................................................................................................................... 28f_check_out_status_component .................................................................................................... 28f_checkout_redirect .................................................................................................................... 29f_checkout_redirect_user_select .................................................................................................... 29f_children_allowed ..................................................................................................................... 30f_clone_component .................................................................................................................... 30f_clone_component_overwrite ...................................................................................................... 31f_clone_primary ........................................................................................................................ 31f_complete_review_editing .......................................................................................................... 32f_complete_reviewer_session ....................................................................................................... 32f_complete_task ......................................................................................................................... 33f_conditional_extract_file ............................................................................................................ 33f_connect_to_database ................................................................................................................ 34f_connect_using_ini ................................................................................................................... 35f_connect_using_profile .............................................................................................................. 36f_count_children ........................................................................................................................ 36f_create_from_template_prod_list ................................................................................................. 37f_create_new_from_template ....................................................................................................... 37f_create_ptr_from_pointee ........................................................................................................... 38f_create_variants ........................................................................................................................ 39f_del_batch_extract_queue ........................................................................................................... 39f_del_extracted_from_batch_extract_queue ..................................................................................... 40f_delete_daemon_batch ............................................................................................................... 40f_delete_entity ........................................................................................................................... 41f_disconnect_from_database ........................................................................................................ 41f_driver_sequence_primary .......................................................................................................... 42f_drop_allowed .......................................................................................................................... 42f_dynamic_index_build ............................................................................................................... 43f_exists_entity_by_match_criteria ................................................................................................. 44f_exists_preview_setup ............................................................................................................... 44f_extract ................................................................................................................................... 45f_extract_blob ........................................................................................................................... 46f_extract_by_lang_attrib .............................................................................................................. 46f_extract_conref_file ................................................................................................................... 47f_extract_file ............................................................................................................................. 47f_extract_file_by_lang_attrib ........................................................................................................ 48f_extract_file_by_version ............................................................................................................ 49f_extract_file_with_saved_condition .............................................................................................. 49f_extract_multiple_primaries ........................................................................................................ 50f_extract_shadow ....................................................................................................................... 50f_fast_extract_build .................................................................................................................... 51f_generate_review_merge_file ...................................................................................................... 51f_get_active_daemons ................................................................................................................. 52f_get_active_tasks_for_user ......................................................................................................... 52f_get_api_version ....................................................................................................................... 53f_get_app_ini_file_path ............................................................................................................... 54f_get_app_path .......................................................................................................................... 54f_get_approved_shadow_dates ..................................................................................................... 55f_get_attribute_name .................................................................................................................. 55f_get_attribute_valid_values ......................................................................................................... 56


iv CONFIDENTIAL © 2017 TransPerfect Translations International Inc. VAPIG-2017.1

f_get_attribute_value .................................................................................................................. 57f_get_attributes_allowed .............................................................................................................. 58f_get_batch_queue ..................................................................................................................... 58f_get_batch_queue_by_id ............................................................................................................ 60f_get_bookmark_console ............................................................................................................. 61f_get_check_out_console ............................................................................................................. 62f_get_checkout_info ................................................................................................................... 62f_get_children_allowed ............................................................................................................... 63f_get_children_by_rule_relation .................................................................................................... 64f_get_client_key ........................................................................................................................ 65f_get_client_key_use .................................................................................................................. 66f_get_client_key_use_by_client_key .............................................................................................. 66f_get_component_data ................................................................................................................ 67f_get_component_from_filter ....................................................................................................... 68f_get_component_from_filter_string .............................................................................................. 72f_get_component_in_primary_from_filt_str .................................................................................... 75f_get_component_in_primary_from_filter ....................................................................................... 79f_get_component_processing_options ............................................................................................ 79f_get_components_from_find ....................................................................................................... 80f_get_components_from_find_string .............................................................................................. 82f_get_composite_extract_filename ................................................................................................ 83f_get_conref_attr_value_for_target ................................................................................................ 84f_get_content_types .................................................................................................................... 84f_get_cross_prod_components ...................................................................................................... 85f_get_daemon_batches ................................................................................................................ 87f_get_db_profiles ....................................................................................................................... 87f_get_descendant_count .............................................................................................................. 87f_get_descendant_pointers ........................................................................................................... 88f_get_descendants_by_rule .......................................................................................................... 88f_get_dw_prod_rule_relations ...................................................................................................... 89f_get_email_address ................................................................................................................... 90f_get_entities_from_prim_rr ......................................................................................................... 90f_get_entity_ancestry .................................................................................................................. 91f_get_entity_children .................................................................................................................. 91f_get_entity_children_details ........................................................................................................ 92f_get_entity_count ..................................................................................................................... 93f_get_entity_hier_key ................................................................................................................. 94f_get_entity_preview .................................................................................................................. 95f_get_entity_status_date .............................................................................................................. 96f_get_filter_definition ................................................................................................................. 97f_get_filters_cross_prod .............................................................................................................. 98f_get_filters_find ..................................................................................................................... 100f_get_filters_find_for_prod ........................................................................................................ 101f_get_filters_prod ..................................................................................................................... 102f_get_filters_raw ...................................................................................................................... 103f_get_global_change_candidates ................................................................................................. 104f_get_global_clone_candidates ................................................................................................... 105f_get_help_directory ................................................................................................................. 105f_get_href_attr_value_for_target ................................................................................................. 106f_get_image_search_names ........................................................................................................ 106f_get_incomplete_descendants .................................................................................................... 107f_get_ini_setting ...................................................................................................................... 108f_get_mm_data ........................................................................................................................ 108f_get_modular_pointees ............................................................................................................ 109


VAPIG-2017.1 CONFIDENTIAL © 2017 TransPerfect Translations International Inc. v

f_get_nav_order ....................................................................................................................... 109f_get_navigator_name ............................................................................................................... 110f_get_navigator_name_full ........................................................................................................ 110f_get_ownership_groups ............................................................................................................ 111f_get_parent_entity ................................................................................................................... 111f_get_picklist_extract_info ......................................................................................................... 111f_get_picklist_type_info ............................................................................................................ 112f_get_pointee_components ......................................................................................................... 114f_get_pointee_entity ................................................................................................................. 114f_get_pointer_components ......................................................................................................... 115f_get_preview_ancestor ............................................................................................................. 116f_get_primaries_by_attribute ...................................................................................................... 117f_get_primaries_with_sequence .................................................................................................. 118f_get_primary_entity ................................................................................................................ 119f_get_primary_entity_from_text .................................................................................................. 119f_get_primary_from_filter ......................................................................................................... 120f_get_primary_from_filter_as_is ................................................................................................. 122f_get_primary_from_filter_string ................................................................................................ 123f_get_primary_prod_entity ......................................................................................................... 124f_get_primary_rule_relation ....................................................................................................... 125f_get_processing_option_arguments ............................................................................................ 125f_get_prod_attribute_valid_values ............................................................................................... 126f_get_prod_entity_versions ........................................................................................................ 126f_get_prod_id .......................................................................................................................... 127f_get_prod_id_from_version ...................................................................................................... 127f_get_prod_list ........................................................................................................................ 127f_get_prod_name ..................................................................................................................... 128f_get_prod_primaries_by_attribute .............................................................................................. 128f_get_prod_projects .................................................................................................................. 129f_get_prods_from_projects ........................................................................................................ 130f_get_project_component_list ..................................................................................................... 131f_get_project_name .................................................................................................................. 131f_get_project_tasks ................................................................................................................... 131f_get_project_users .................................................................................................................. 132f_get_projects_by_component .................................................................................................... 132f_get_raw_attributes ................................................................................................................. 133f_get_raw_class ....................................................................................................................... 133f_get_raw_component_from_filter .............................................................................................. 134f_get_raw_component_from_filter_string ..................................................................................... 136f_get_raw_components ............................................................................................................. 137f_get_raw_desc_by_raw_id ........................................................................................................ 138f_get_raw_description ............................................................................................................... 138f_get_raw_id ........................................................................................................................... 139f_get_raw_text ........................................................................................................................ 139f_get_raw_text_from_raw_id ..................................................................................................... 139f_get_raw_type_id ................................................................................................................... 140f_get_raw_types ...................................................................................................................... 140f_get_reference_string .............................................................................................................. 141f_get_referenced_by ................................................................................................................. 141f_get_review_comment_replies .................................................................................................. 142f_get_review_comments ............................................................................................................ 143f_get_review_load_flag ............................................................................................................. 144f_get_review_merge_file ........................................................................................................... 145f_get_reviewer_info ................................................................................................................. 145


vi CONFIDENTIAL © 2017 TransPerfect Translations International Inc. VAPIG-2017.1

f_get_rightclick_processing_options ............................................................................................ 146f_get_rule_relation ................................................................................................................... 147f_get_rule_relation_from_version ............................................................................................... 147f_get_shadow .......................................................................................................................... 148f_get_shadow_attributes ............................................................................................................ 149f_get_shadow_first_lvl_children ................................................................................................. 149f_get_start_date ....................................................................................................................... 150f_get_status ............................................................................................................................. 151f_get_system_profile_value ....................................................................................................... 151f_get_task_attribute .................................................................................................................. 152f_get_task_attribute_valid .......................................................................................................... 152f_get_task_instance_attribute ..................................................................................................... 153f_get_task_list ......................................................................................................................... 153f_get_task_list_filter ................................................................................................................. 154f_get_task_project .................................................................................................................... 155f_get_task_queue ..................................................................................................................... 156f_get_task_users ...................................................................................................................... 156f_get_thumbnail_file ................................................................................................................. 157f_get_thumbnail_file_fullsize ..................................................................................................... 157f_get_translation_extract_projects ............................................................................................... 158f_get_user_prod_xml ................................................................................................................ 158f_get_user_raw_material_xml .................................................................................................... 159f_get_user_workflow_xml ......................................................................................................... 159f_get_username ....................................................................................................................... 160f_get_users ............................................................................................................................. 161f_get_valid_clone_target_prods .................................................................................................. 161f_get_valid_filter_values ........................................................................................................... 162f_get_valid_values ................................................................................................................... 162f_get_value_from_extract_info_pi ............................................................................................... 163f_get_variants .......................................................................................................................... 164f_get_version_attribute_link_proc_opts ........................................................................................ 165f_get_version_id ...................................................................................................................... 166f_get_view_processing_options .................................................................................................. 167f_get_workflow_task ................................................................................................................ 167f_get_wrapper_relation_id ......................................................................................................... 168f_get_wrapper_relation_proc_opts ............................................................................................... 168f_insert_batch_extract_queue ..................................................................................................... 169f_insert_component .................................................................................................................. 170f_insert_daemon_batch ............................................................................................................. 170f_insert_primary_component ...................................................................................................... 171f_insert_raw_material_mm ........................................................................................................ 171f_insert_raw_material_pointer .................................................................................................... 172f_insert_raw_material_text ......................................................................................................... 172f_insert_task_instance ............................................................................................................... 173f_insert_version_and_comment .................................................................................................. 173f_insert_workflow_task ............................................................................................................. 174f_leadtools_supported_filetype ................................................................................................... 174f_load .................................................................................................................................... 175f_load_file .............................................................................................................................. 176f_load_file_translation .............................................................................................................. 176f_ownership_extension_active .................................................................................................... 177f_pending_delete_entity ............................................................................................................ 177f_reassign_task_user ................................................................................................................. 178f_redline_report ....................................................................................................................... 178


VAPIG-2017.1 CONFIDENTIAL © 2017 TransPerfect Translations International Inc. vii

f_register_daemon .................................................................................................................... 179f_reinstate_shadow ................................................................................................................... 179f_remove_bookmark ................................................................................................................. 180f_resequence_non_primary ........................................................................................................ 180f_resequence_primary ............................................................................................................... 181f_review_accept_reject .............................................................................................................. 181f_review_comment_has_replies .................................................................................................. 182f_search_for_primary ................................................................................................................ 183f_sequence_primary ................................................................................................................. 183f_server_side_cancel ................................................................................................................. 184f_server_side_progress .............................................................................................................. 184f_set_attribute_value ................................................................................................................. 185f_set_batch_extract_queue_filename ............................................................................................ 185f_set_batch_extract_queue_sequence_no ...................................................................................... 186f_set_batch_extract_queue_status ................................................................................................ 186f_set_bypass_server_processing .................................................................................................. 187f_set_entity_clientkey ............................................................................................................... 187f_set_ownership_group ............................................................................................................. 187f_set_pointee_attribute .............................................................................................................. 188f_set_raw_id ........................................................................................................................... 188f_set_review_comments ............................................................................................................ 189f_set_task_comment ................................................................................................................. 190f_set_task_instance_attribute ...................................................................................................... 191f_set_username ........................................................................................................................ 191f_submit_reviewer_changes ....................................................................................................... 191f_test ..................................................................................................................................... 192f_text_allowed ......................................................................................................................... 192f_this_is_a_test ........................................................................................................................ 193f_translation_clone ................................................................................................................... 193f_undelete_entity ..................................................................................................................... 194f_unregister_daemon ................................................................................................................ 194f_update_daemon ..................................................................................................................... 195f_update_text_component .......................................................................................................... 195f_validate_required_attributes .................................................................................................... 196f_where_used .......................................................................................................................... 196

Low-Level API Sample Application .................................................................................................... 199Creating the VB.NET Solution ................................................................................................... 199Creating the User Interface ........................................................................................................ 201Adding a Reference to the Vasont Low-Level API .......................................................................... 202Instantiating the API ................................................................................................................. 203Logging In .............................................................................................................................. 204Getting a Collection List ............................................................................................................ 204Getting a List of Users .............................................................................................................. 205Creating a Class to Hold User Collections ..................................................................................... 207Populate a Collection of User Collection Objects ........................................................................... 207Displaying a List of Users for the Selected Collection ..................................................................... 208Running the Application and Programming Notes .......................................................................... 209

User Defined Processing Option Template in VB 6 ................................................................................. 211Code Template ........................................................................................................................ 211Applying the UDPO ................................................................................................................. 214

Using the High-Level Application Programming Interface ....................................................................... 217List of High-Level API Functions ....................................................................................................... 219

Extract And Load ..................................................................................................................... 219Low-level Interface Access ........................................................................................................ 219


viii CONFIDENTIAL © 2017 TransPerfect Translations International Inc. VAPIG-2017.1

LogIn and Information .............................................................................................................. 219User Interface .......................................................................................................................... 219About .................................................................................................................................... 219CheckDBConnection ................................................................................................................ 219ConnectToDB ......................................................................................................................... 220ConnectUsingProfile ................................................................................................................. 220CreateNewComponentFromTemplate .......................................................................................... 221DisconnectFromDB .................................................................................................................. 221ExtractIntoEditor ..................................................................................................................... 222ExtractToFile .......................................................................................................................... 222GetContainedInterface .............................................................................................................. 223GetUserPreference ................................................................................................................... 223GetValueFromExtractPI ............................................................................................................ 224Init ........................................................................................................................................ 224InvokeVasont .......................................................................................................................... 225OpenNavigator ........................................................................................................................ 225OpenWorkflow ........................................................................................................................ 225PickConrefIntoEditor ................................................................................................................ 226PickHrefIntoEditor ................................................................................................................... 226PickListIntoEditor .................................................................................................................... 227RegisterOpenExtractCallback ..................................................................................................... 228RegisterSaveCallback ............................................................................................................... 228RegisterVersionCallback ........................................................................................................... 229SetUserPreference .................................................................................................................... 229UpdateVasont .......................................................................................................................... 229UpdateVasontNoExtract ............................................................................................................ 230

High-Level API Sample Application .................................................................................................... 231Creating the C# Solution ........................................................................................................... 231Creating the User Interface ........................................................................................................ 233Adding a Reference to the High-Level API ................................................................................... 234Instantiating the API ................................................................................................................. 234Responding to the Button Click .................................................................................................. 235Testing the application .............................................................................................................. 236

Glossary ......................................................................................................................................... 239Index ............................................................................................................................................. 245


VAPIG-2017.1 CONFIDENTIAL © 2017 TransPerfect Translations International Inc. ix

Overview of Vasont APIsVasont has developed two Application Program Interfaces that allow clients and third party developers to extend theVasont application or create custom applications while still using the robust business logic built into Vasont.

The two APIs are a high-level API and a low-level API.

• Low-Level API Overview

The low-level interface provides a rich list of function calls. The function calls provide a wealth of informationand data about content and many ways for fine-grained manipulation of it.

• High-Level API Overview

The high-level API provides fewer, simpler function call and contains some pre-built GUI elements that allowdevelopers to perform basic Vasont tasks such as selecting content, performing extracts and loads and workflowtask completion.

This API is the same interface provided to the XML editors that are supported by the Vasont Universal Integra-tor (VUI). If a developer wished to integrate an unsupported XML editor with Vasont he/she could follow thisguide to provide the same functionality as Vasont supported third-party editors.

2 These two APIs do not scale with Web Technology. They can be scale for a Window’s desktop appli-cation that is run on a Citrix server environment. Vasont is developing a new API that is scalable withWeb Technology. Consult your Vasont support leader to get the latest information available on thenew API.

Configuration AlterationsYour Vasont system is set up based on business rules and information provided by you and then configured by aVasont analyst. This results in a customized configuration specific to your business needs. If you need to alter yourconfiguration you should first consult with your Vasont support leader to confirm that your alterations will not havean undesirable result. Any issues that result from configuration changes that were not discussed and confirmed withthe support leader are not covered under your Vasont application support agreement and assistance to repair anydamage may be billable.


VAPIG-2017.1 CONFIDENTIAL © 2017 TransPerfect Translations International Inc. 1

Overview of Vasont APIs

2 CONFIDENTIAL © 2017 TransPerfect Translations International Inc. VAPIG-2017.1

Using the Low-LevelApplication Program

InterfaceThe Low-Level Application Program Interface (API) is used to provide access to certain Vasont functions. Any pro-gramming language that can access COM objects can call Vasont functions. Some functions provide basic capabili-ties, such as establishing a connection to the database. Other functions either extract specific data from or load datainto the Vasont database.

To use the API, call the functions from any programming language that has the capability to access COM objects.This may be a language like C++, Visual Basic, Visual Basic For Applications, VB Script, Power Builder, Delphi,or active server web pages. Before using the API, become familiar with the Vasont Administrator. Many argumentsused by the API functions can be found in Vasont Administrator. Also, understanding Vasont Administrator's setupfor a collection is imperative before using the API to access it. Learn about Collections, Edit, Extract and LoadViews, Attributes, Rule Relation ID's, Version ID's, etc. The Vasont Administrator Guide goes into more detail onhow it can facilitate the use of the API.

Define any variables in the Installation's code, as appropriate, and place calls to API functions using this code. Thisdocument contains several examples for using the Vasont API. Refer to these and specific function definitions foruse in coding API calls.

Key Concepts of the Low-Level APIMost of the Vasont API functions allow you to get at specific content instances in Vasont. As a concrete example, auser goes after a complete recipe in a Recipe Collection, or one specific component in that recipe. The user may betrying to get a value of an attribute associated with a component in the recipe. A component could be Recipe De-scription, and the attribute could be named “ownership” with a value of “reusable”. The specific recipe could beBeef Stew. The recipe could have many other components, such as Ingredients, Chef etc., which are related to eachother in a hierarchical manner. In any case, from Vasont's point of view, Recipe is in a collection, and that collectioncould have many recipes. The collection in this example is a specific recipe collection. Recipes have parent-childhierarchies of components that describe how components are related to each other.

Prod_id (special Vasont number) identifies the collection of interest. There can be hundreds of collections in a us-er's Vasont database. The Recipe Collection prod_id is a unique number, such as 10361.

Entity_id (special Vasont number) identifies a specific component in a specific collection. For example, a specificrecipe description in the Beef Stew recipe would have a unique entity_id, such as 50379. The recipe component isthe top component in the Recipe collection. The Beef Stew recipe's top component is a special entity_id called pri-mary_entity_id, meaning it is the top component in the hierarchy. The content for that entity_id is Beef Stew. Ev-ery entity_id has some actual content. So, if the Beef Stew entity_id in the Recipe collection is 37666, the actualpure content has a different number associated with it called the raw_id (special Vasont number). Assuming theraw_id for this Beef Stew is 73098; then the entity_id 37666 has a raw_id of 73098. A raw_id can be used in manydifferent entity_ids. Thus, the same content can be used in many different situations.

Assume the Chef component of the Beef Stew recipe is “Julia Childs”. The entity_id of the Chef component is37671, and the Julia Childs raw_id is 2003. Then, a different Chef component (entity_id 39004) in a different recipe,



called “Dumplings” (entity_id 38692, raw_id 4922), could have the same raw_id, if Julia Childs was, indeed, theChef for both recipes. Suppose the hierarchy for the recipes is as follows:

Recipe is the primary. Ingredients is a parent of Ingredient Ref, and an Ingredient Ref can be called a child ofIngredients. A specific “Ingredients” could have a parent_entity_id, and one of its specific Ingredient Ref childrencould have a child_entity_id. They both would have the same primary_entity_id; that is the entity_id of the recipeof which they are a part.

Inside Vasont, a number defines every parent-child relationship. So, the Ingredients/Ingredient Ref relationshipmight be equal to 10583. This number is called the rule_relation_id.

There is a different rule_relation_id number for Ingredient Type_in/Ingredient Ref relationship (rule_rela-tion_id=10603) because the parent of Ingredient Ref is different in each case, as shown in the following example:

The content instance hierarchies described above can be found in Vasont Administrator. In Vasont Administrator'sContent Navigator, under a Content Type, are Collections. Each collection has an Edit View, showing componenthierarchy, rule_relation numbers and attributes attached to the components.

In the previous example, there are several collections. One is Recipe. It has three views: Edit, Load and Extract.

Using the Low-Level Application Program Interface


Following is an example of a Detailed Edit View:

In this example, Recipe is the primary component. Its rule_relation_id is 10129 and it has five associated attributes.The first attribute is called “Autocalc” and its attribute_link_id is 10147. The Recipe Description is a child compo-nent of recipe and its rule_relation_id is 10301.Notice, there are no entity_id's in Vasont Administrator. The Vasont Administrator describes content, but it is notactual content. Only actual content has entity_id's. The same is true for raw_id's. Entity_id's can be obtained usingvarious API functions, such as f_get_primary_from_filter, or f_get_primary_entity_from_text.When using the API, use the entity_id to get one component's textual content at a time, such as f_get_raw_text. Butto extract whole hierarchies of content, such as an entire encyclopedia article (or entire encyclopedia), use a ver-sion_id.The next section shows how to find various version_ids associated with a collection. When loading and extractinghierarchical data, typically with SGML or XML tagging applied, use version_id which is a unique identifier for agiven Extract or Load view associated with a collection.

The previous screen shot, from Vasont Administrator, shows that the Recipe collection has two different extracts.The last one is ‘Recipe Extract - XML’. It has a version_id of 10503.



By right-clicking on that extract view and selecting Open Detail Navigator, the Detail Extract View - Recipescreen displays:

In an extract, in addition to component hierarchy, the associated Tags or Wrappers for the component being extrac-ted are shown. For example, the recipe component has a <Recipe> tag associated with it when extracted. Number10291 is a wrapper_relation_id defining a combination of the component and its tag.

Variables• Sample function syntax: HRESULT f_load( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR

as_text, [ in, out ] VARIANTARG * as_error_text, [out, retval] VARIANT_BOOL * retval );

• Variable types are indicated in most cases by their names. The characters prefacing a variable name indicatetype:

• ad—Number (double)

• as—String

• In: Input to function

• Out: Output from function

• In, Out: Equivalent to passing variables by reference.

• Return values—specified by retval. These values may vary in data type, so no preface is used. In some cases,data is a number or a string. In other cases, data is contained within a Result Set (varying rows and columns).Data types are specified in the documentation.

• The layout of all functions is found in the file vasont_com.idl file located in the Vasont\App folder of your Vas-ont installation. Following is a portion of this file:

// ***********************************************************************************// Copyright 1997,1998 Sybase, Inc.// All Rights reserved.//// This code is generated by the PowerBuilder COM Generator.// It is provided subject to the terms of the Sybase License Agreement// for your internal use, as is, without alteration or modification.// Sybase shall have no obligation to provide support or error correction// services with respect to any altered or modified versions of this code.//// ***********************************************************// ** DO NOT MODIFY OR ALTER THIS FILE IN ANY WAY **// ***********************************************************//// Generated : Tue Jan 16 17:28:52 2001//// For use with PB COM Server: vasont_com



//// ***********************************************************************************import “unknwn.idl”;import “oaidl.idl”;[object,uuid(BA0974E5-A0D0-11D3-AD6B-005004D0E0EA),pointer_default(unique),dual,oleautomation]interface In_vasont_com : IDispatch{// methodsHRESULT f_disconnect_from_database( [out, retval] VARIANT_BOOL * retval );HRESULT f_test( [out, retval] BSTR * retval );HRESULT f_get_attribute_value( [ in ] double ad_entity_id, [ in ] double ad_attribute_link_id, [out, retval] BSTR * retval );HRESULT f_get_client_key( [ in ] double ad_entity_id, [out, retval] BSTR * retval );HRESULT f_get_entity_count( [ in ] double ad_prod_id, [out, retval] long * retval );HRESULT f_get_primary_entity( [ in ] double ad_child_entity_id, [out, retval] double * retval );HRESULT f_get_primary_rule_relation( [ in ] double ad_prod_id, [out, retval] double * retval );HRESULT f_get_prod_id( [ in ] double ad_entity_id, [out, retval] double * retval );HRESULT f_get_raw_description( [ in ] double ad_entity_id, [out, retval] BSTR * retval );HRESULT f_get_raw_id( [ in ] double ad_entity_id, [out, retval] double * retval );HRESULT f_get_raw_text( [ in ] double ad_entity_id, [out, retval] BSTR * retval );HRESULT f_get_rule_relation( [ in ] double ad_entity_id, [out, retval] double * retval );HRESULT f_get_start_date( [ in ] double ad_instance_id, [out, retval] DATE * retval );HRESULT f_get_status( [ in ] double ad_entity_id, [out, retval] BSTR * retval );HRESULT f_get_username( [out, retval] BSTR * retval );HRESULT f_get_version_id( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ] BSTR as_extract_type, [out, retval] LPDISPATCH * retval );}// typelibrary and coclass[uuid(BA0974F2-A0D0-11D3-AD6B-005004D0E0EA),lcid(0x0), version(6.1),helpstring(“”)]library vasont_comLib{[uuid(BA0974E4-A0D0-11D3-AD6B-005004D0E0EA)]coclass COClass_n_vasont_com{interface In_vasont_com;}}

Finding Arguments in VasontIn some cases, API functions require Arguments from the Vasont database. This section lists those arguments andindicates whether they can be found using Vasont or Vasont Administrator. In some cases, one function may returndata that can be used as arguments to another function.



• Attribute_link_id: The attribute_link_id is the identifier for an attribute. It can be found in the right window-pane of the Vasont Administrator when Attributes is selected from the Content Navigator (left windowpane).Attribute_link_id also can be seen in the Vasont Administrator's Detailed Edit View Navigator.

• Child_entity_id: The identifier for a child entity in Vasont. It applies to any entity other than the primary entity.It can be found in a Result Set returned by the f_get_task_list function. The f_get_entity_children function re-turns a Result Set of all the children entity_ids for a given entity parent (entire hierarchy). The function,f_get_children_by_rule_relation, returns all the children of a parent that satisfy a specified rule_relation_id.

• Child_rule_relation_id: This is the rule_relation_id for a component that is the child of another component.This may apply to any but the primary component. The id can be found using the Vasont Administrator's Ad-vanced tab on the Update window for any component displayed in an edit view. It can be seen in the DetailedEdit View Navigator and also is returned by API functions, f_get_primary_rule_relation, f_get_rule_relation,and f_get_task_list.

• Entity_id: The identifier for an entity in Vasont (specific instance of content in a collection). It can be foundusing some API functions. The f_get_primary_entity_from_text, f_get_primary_from_filter, f_get_task_list, andf_search_for_primary functions all return an entity_id.

• Filter_id: This identifies a specific filter that has been saved in Vasont. A filter is a representation of a booleanstatement that is used to perform a query against the database, typically to get a certain set of primary_entity_idsthat are associated with a collection (for example - get all encyclopedia articles written by Carl Sagan relative toTopic of Astronomy). It is found by opening a saved filter. The filter_id appears in the window showing a list ofsaved filters. This is not in Vasont Administrator, but in the main Vasont application.



First, open the Query window and click on Saved → Saved Query Properties. The Saved Query Propertieswindow displays showing information for the saved query and the corresponding filter_ids.

• Instance_id: This identifies a particular Workflow task. The f_get_task_list function is used to find the in-stance_id. It also can be found using the Vasont Administrator, (called task_id), and selecting a specific projectin the left windowpane of the Content Navigator. Both task name and id are displayed in the right windowpane.

• Prod_id: This is found on the Advanced tab of the collection update window in Vasont Administrator. It is alsoreturned by API functions f_get_prod_list and f_get_task_list.



• Raw_id: Each entity_id has an associated raw_id that defines its specific content. The f_get_raw_id provides araw_id for a given entity_id. The f_get_raw_text returns actual textual content as a string for a textual compo-nent. The f_get_raw_description obtains the textual portion of any type component, even pointers or multimedia.

• Rule_relation_id: The identifier for a parent/child relationship in Vasont. This id can be found using the VasontAdministrator's Advanced tab of the update window for any component displayed in an edit view. It can be seenin the Detailed Edit View Navigator and also is returned by the API functions f_get_primary_from_filter,f_get_primary_rule_relation, f_get_rule_relation and f_get_task_list.

• Userid: This identifies a user in Vasont. It is the name assigned to a user to logon to Vasont. It is returned by thef_get_prod_list, f_get_task_list and f_get_username functions.

• Version_id: Refers to an identifier for both load and extract views. The id can be found in the right windowpanewhen either view has been selected in the Vasont Administrator Content Navigator window. It also is returnedby the f_get_version_id function.

• Subject_id: Refers to an identifier for the content type. The “id” can be found on the Content Type update win-dow in Vasont Administrator.

• Project_id: This identifies a project in Vasont.

• Task_id: This identifies a task within a project in Vasont.

• Role_id: This identifies a role in Vasont.



List of Low-Level APIFunctions by Groups

API Functional GroupsAttributesf_get_attribute_valid_valuesf_get_attribute_valuef_get_attributes_allowedf_get_raw_attributesf_set_attribute_value

Batch and Daemon Operationsf_batch_extractf_batch_loadf_batch_runf_del_batch_extract_queuef_del_extracted_from_batch_extract_queuef_delete_daemon_batchf_dynamic_index_buildf_extract_multiple_primariesf_fast_extract_buildf_get_active_daemonsf_get_batch_queuef_get_batch_queue_by_idf_get_daemon_batchesf_insert_batch_extract_queuef_insert_daemon_batchf_register_daemonf_set_batch_extract_queue_filenamef_set_batch_extract_queue_sequence_nof_set_batch_extract_queue_statusf_unregister_daemonf_update_daemon

Children, Descendants and Ancestorsf_approve_descendantsf_children_allowedf_get_children_by_rule_relationf_get_entity_ancestryf_get_entity_countf_get_incomplete_descendants



Clonef_clone_componentf_clone_component_overwritef_clone_primaryf_create_from_template_prod_listf_create_new_from_templatef_get_valid_clone_target_prodsf_translation_clone

Component Manipulation and Informationf_analyze_componentf_approve_componentf_bookmarkf_check_inf_check_outf_check_out_statusf_check_out_status_componentf_checkout_redirectf_checkout_redirect_user_selectf_count_childrenf_delete_entityf_get_checkout_infof_get_client_keyf_get_component_dataf_get_descendant_countf_get_entity_ancestryf_get_entity_childrenf_get_entity_children_detailsf_get_entity_hier_keyf_get_nav_orderf_get_navigator_namef_get_parent_entityf_get_prod_idf_get_rule_relationf_get_shadowf_get_statusf_get_valid_valuesf_insert_componentf_insert_primary_componentf_pending_delete_entityf_resequence_non_primaryf_resequence_primaryf_set_raw_idf_text_allowedf_undelete_entityf_update_text_component

Extracts and Loadsf_extractf_extract_blobf_extract_by_lang_attrib

List of Low-Level API Functions by Groups


f_extract_filef_extract_file_by_lang_attribf_extract_file_by_versionf_extract_file_with_saved_conditionf_get_composite_extract_filenamef_get_rule_relation_from_versionf_get_value_from_extract_info_pif_get_version_idf_get_wrapper_relation_idf_loadf_load_filef_load_file_translation

Filters, Finds, Bookmarks, Content Types, Collections andProductsf_exists_entity_by_match_criteriaf_get_bookmark_consolef_get_component_from_filterf_get_component_from_filter_stringf_get_components_from_findf_get_components_from_find_stringf_get_component_in_primary_from_filt_strf_get_component_in_primary_from_filterf_get_content_typesf_get_filter_definitionf_get_filters_findf_get_filters_prodf_get_filters_rawf_get_primary_from_filterf_get_primary_from_filter_stringf_get_prod_namef_get_raw_component_from_filterf_get_raw_component_from_filter_stringf_get_user_prod_xmlf_get_valid_filter_valuesf_remove_bookmarkf_search_for_primary

Global Change and Shadow Historyf_extractf_get_approved_shadow_datesf_get_global_change_candidatesf_get_global_clone_candidatesf_get_prod_entity_versionsf_get_shadowf_get_shadow_attributesf_get_shadow_first_lvl_childrenf_reinstate_shadow

Pointersf_create_ptr_from_pointee



f_get_href_attr_value_for_targetf_get_pointee_componentsf_get_pointee_entityf_get_referenced_byf_insert_raw_material_pointerf_where_used

Primariesf_get_primaries_with_sequencef_get_primary_entityf_get_primary_entity_from_textf_get_primary_rule_relationf_get_prod_entity_versionsf_get_reference_string

Processing Optionsf_get_component_processing_optionsf_get_processing_option_argumentsf_get_rightclick_processing_optionsf_get_version_attribute_link_proc_optsf_get_view_processing_optionsf_get_wrapper_relation_proc_opts

Raw Materialf_get_mm_dataf_get_picklist_type_infof_get_raw_classf_get_raw_componentsf_get_raw_desc_by_raw_idf_get_raw_descriptionf_get_raw_idf_get_raw_textf_get_raw_type_idf_insert_raw_material_mmf_insert_raw_material_text

User Info, Access Rights and LogInf_allow_addf_allow_approvef_allow_check_in_overridef_allow_deletef_allow_editf_allow_project_filterf_allow_raw_material_viewf_allow_reassign_taskf_allow_reinstate_shadowf_allow_workflow_scheduling_overridef_change_expired_passwordf_check_connectionf_connect_to_databasef_connect_using_ini



f_connect_using_profilef_disconnect_from_databasef_drop_allowedf_get_check_out_consolef_get_children_allowedf_get_db_profilesf_get_email_addressf_get_ini_settingf_get_prod_listf_get_user_raw_material_xmlf_get_user_workflow_xmlf_get_usernamef_get_usersf_test

Workflowf_complete_taskf_get_active_tasks_for_userf_get_prod_projectsf_get_prods_from_projectsf_get_project_component_listf_get_project_namef_get_project_tasksf_get_project_usersf_get_projects_by_componentf_get_task_attributef_get_task_attribute_validf_get_task_instance_attributef_get_task_listf_get_task_list_filterf_get_task_projectf_get_task_queuef_get_task_usersf_get_workflow_taskf_insert_task_instancef_insert_workflow_taskf_reassign_task_userf_set_task_commentf_set_task_instance_attribute

Frequently Used API CallsAttributesf_get_attribute_valid_valuesf_get_attribute_valuef_get_attributes_allowedf_set_attribute_value

Children, Descendants and Ancestorsf_children_allowed



f_get_children_by_rule_relationf_get_entity_count

Component Manipulation and Informationf_analyze_componentf_approve_componentf_check_inf_check_outf_count_childrenf_delete_entityf_get_checkout_infof_get_client_keyf_get_entity_childrenf_get_entity_children_detailsf_get_entity_hier_keyf_get_prod_idf_get_rule_relationf_get_valid_valuesf_insert_componentf_pending_delete_entityf_text_allowedf_update_text_component

Extracts and Loadsf_extractf_extract_blobf_extract_filef_get_composite_extract_filenamef_loadf_load_filef_load_file_translation

Filters, Finds, Bookmarks, Content Types, Collections andProductsf_get_component_from_filterf_get_components_from_findf_get_content_typesf_get_filter_definitionf_get_filters_findf_get_filters_prodf_get_filters_rawf_get_primary_from_filterf_get_prod_namef_get_user_prod_xmlf_get_valid_filter_values

Pointersf_get_referenced_byf_where_used



Primariesf_get_primary_rule_relation

Processing Optionsf_get_component_processing_optionsf_get_processing_option_argumentsf_get_rightclick_processing_optionsf_get_version_attribute_link_proc_optsf_get_view_processing_optionsf_get_wrapper_relation_proc_opts

Raw Materialf_get_mm_dataf_get_picklist_type_infof_get_raw_classf_get_raw_descriptionf_get_raw_idf_get_raw_textf_get_raw_type_idf_insert_raw_material_mmf_insert_raw_material_text

User Info, Access Rights and LogInf_allow_addf_allow_approvef_allow_deletef_allow_editf_allow_project_filterf_connect_using_profilef_disconnect_from_databasef_drop_allowedf_get_children_allowedf_get_db_profilesf_get_ini_settingf_get_prod_listf_get_usernamef_test



List of Low-Level APIFunctions

f_allow_addHRESULT f_allow_add( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] VARIANT_BOOL* retval );

Description: This function determines whether the user has security rights to add the specified component type.

Input Parameters

Name Type Definitionad_prod_id Double Identifies collection to be added

ad_rule_relation_id Double Component type identifier

Output Parameters

Name Type Definitionretval Boolean Success or failure

f_allow_approveHRESULT f_allow_approve( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] VAR-IANT_BOOL * retval );

Description: This function determines whether the user has security rights to approve the specified component type.

Input Parameters

Name Type Definitionad_prod_id Double Identifies collection to be approved


Output Parameters




f_allow_check_in_overrideHRESULT f_allow_check_in_override( [out, retval] VARIANT_BOOL * retval );

Description: This function determines whether the user has security rights to check in any component regardless ofwho has it checked out.

Input Parameters

None

Output Parameters


f_allow_deleteHRESULT f_allow_delete( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] VAR-IANT_BOOL * retval );

Description: This function determines whether the user has security rights to delete the specified component type.

Input Parameters

Name Type Definitionad_prod_id Double Identifies collection to be deleted


Output Parameters


f_allow_editHRESULT f_allow_edit( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] VARIANT_BOOL* retval );

Description: This function determines whether the user has security rights to edit the specified component type.

Input Parameters

Name Type Definitionad_prod_id Double Identifies collection to be edited


List of Low-Level API Functions


Output Parameters


f_allow_project_filterHRESULT f_allow_project_filter( [out, retval] VARIANT_BOOL * retval );

Description: This function determines whether the user has security rights to filter for other combinations of work-flow.

Input Parameters

None

Output Parameters

Name Type Definitionretval Boolean True or False

f_allow_raw_material_viewHRESULT f_allow_raw_material_view( [out, retval] VARIANT_BOOL * retval );

Description: This function determines if the current user has permission/privileges to view raw material.

Input Parameters

None

Output Parameters

Name Type Definitionretval Boolean True if user has permission; false if user does not

f_allow_reassign_taskHRESULT f_allow_reassign_task( [out, retval] VARIANT_BOOL * retval );

Description: This function determines whether the user has security rights to reassign workflow tasks to other users.

Input Parameters

None



Output Parameters


f_allow_reinstate_shadowHRESULT f_allow_reinstate_shadow( [ in ] double ad_prod_id, [out, retval] VARIANT_BOOL * retval );

Description: This function determines whether the user has security rights to reinstate versions/snapshots for thespecified collection.

Input Parameters

Name Type Definitionad_prod_id Double Collection to have version/snapshot reinstated

Output Parameters


f_allow_workflow_scheduling_overrideHRESULT f_allow_workflow_scheduling_override( [out, retval] VARIANT_BOOL * retval );

Description: This function determines whether the user has security rights to override workflow scheduling.

Input Parameters

None

Output Parameters

Name Type Definitionretval Boolean True/False. Checks workflow schedule override security permis-

sion for current user

f_analyze_componentHRESULT f_analyze_component( [ in ] double ad_entity_id, [ in, out] VARIANTARG * ab_drill_down, [ out, re-tval ] BSTR * retval );

Description: This function analyzes a component with an incomplete status and returns the description of whythe component is incomplete. If the status of the component is not incomplete, an empty string is returned.



Input Parameters

Name Type Definitionad_entity_id Double Identifies component entity to be analyzed

ab_drill_down Boolean Reference argument for drill-down indicator

Output Parameters

Name Type Definitionab_drill_down Boolean If true, component is flagged as incomplete because it contains in-

complete descendant(s). (See NOTE below).

retval String Description of why component is incomplete; otherwise, empty

NOTE: Use f_get_incomplete_descendants for the component to locate the incomplete descendant(s).

f_approve_componentHRESULT f_approve_component( [ in ] double ad_entity_id, [out, retval] short * retval );

Description: This function approves a component. If the current status is draft, this changes the status to approved.If the current status is incomplete, no change is made. If the component is a primary, all descendants are approved aswell.

Input Parameters

Name Type Definitionad_entity_id Double Identifies component entity to be approved

Output Parameters

Name Type Definitionretval Short 1=success; 0=no action taken; −1=error occurred

f_approve_descendantsHRESULT f_approve_descendants( [ in ] double ad_prod_id, [ in ] double ad_parent_entity_id, [ in ] doublead_custom_rule_use_id, [ in, out ] VARIANTARG * as_message, [ in, out ] VARIANTARG * ad_incomplete_enti-ty_id, [out, retval] short * retval );

Description: This function implements the Vasont approve_descendants processing option through the API. It at-tempts to approve all descendants of a collection component, reporting the number of components approved andcounts for the components that could not be approved, if applicable (components checked-out to other users or flag-ged as incomplete in Vasont cannot be approved).

If the approve_descendants option has been set up to report the first incomplete descendant encountered (a flag seton one of the processing option arguments), that incomplete component's identifier is returned in the ad_incom-plete_entity_id argument.



Input Parameters

Name Type Definitionad_prod_id Double Collection identifier in which components are to be approved

ad_parent_entity_id Double Component identifier of ancestor, under which all components areto be approved

ad_custom_rule_use_id Double Custom rule use identifier used to obtain approve_descendantsprocessing option arguments. (See NOTE below).

as_message String Reference argument for approval summary

ad_incomplete_entity_id Double Reference argument for first incomplete descendant

NOTE: See API function f_get_rightclick_processing_options resultset for value.

Output Parameters

Name Type Definitionas_message String Summary of actions taken during approval process - includes num-

ber of components approved, number of incomplete componentsthat could not be approved (if applicable), and number of checked-out components that could not be approved (if applicable)

ad_incomplete_entity_id Double Component identifier for first incomplete descendant encountered -will be 0 if no incomplete components are found, or if processingoption is not set up to return first incomplete

retval Short Number of descendant components approved

f_batch_extractHRESULT f_batch_extract( [out, retval] short * retval );

Description: This function performs the batch extract process for the currently logged in user.

Input Parameters

None

Output Parameters

Name Type Definitionretval Short 1=success; −1=otherwise

ab_delete_queue_item Boolean If true, deletes successfully extracted queue items

f_batch_loadHRESULT f_batch_load( [out, retval] short * retval );

Description: This function performs the batch load process for the currently logged in user



Input Parameters

None

Output Parameters


f_batch_runHRESULT f_batch_run( [ in ] double ad_beq_id, [ in ] VARIANT_BOOL ab_delete_queue_item, [out, retval]VARIANT_BOOL * retval );

Description: This function will figure out if this queue_id is for a batch extract or a batch load, and fire the appro-priate function, f_batch_load or f_batch_extract.

Input Parameters

Name Type Definitionad_beq_id Double The Batch Queue ID

ab_delete_queue_item Boolean Set to TRUE to tell the batch function to delete the queue id recordfrom the queue after it finishes, else set to FALSE

Output Parameters

Name Type Definitionretval Boolean Returns TRUE or FALSE depending on whether the batch process

(load or extract) for the queue_id completed successfully

f_bookmarkHRESULT f_bookmark( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_error, [out, retval] short * re-tval );

Description: This function creates a bookmark for the given entity.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be bookmarked

as_error String Reason if bookmark is not accomplished

Output Parameters

Name Type Definitionas_error String Explanation for bookmark failure



Name Type Definitionretval Short 0=bookmarked

−1=failure

f_change_expired_passwordHRESULT f_change_expired_password( [ in ] BSTR as_server_name, [ in ] BSTR as_username, [ in ] BSTRas_old_password, [ in ] BSTR as_new_password, [ in, out ] VARIANTARG * as_errortext, [out, retval] VAR-IANT_BOOL * retval );

Description: This function is used to change an expired password. It can also be called to change a password at anytime.

Input Parameters

Name Type Definitionas_server_name String The servername of the database that the user connects to

as_username String The login name of the user

as_old_password String The current password that the user would like to change

as_new_password String The new password that the user would like to change to

as_errortext String Error message that is returned by reference from the database

Output Parameters

Name Type Definitionas_errortext String Error message that is returned by reference from the database

retval Boolean Returns TRUE if the password change is successful, FALSE other-wise

f_check_connectionHRESULT f_check_connection( [out, retval] VARIANT_BOOL * retval );

Description: This function checks to see if there is an active connection to the Vasont Database. The function canbe used by client applications to determine if a connection has been lost and needs to be re-established.

Input Parameters

None

Output Parameters

Name Type Definitionretval Boolean TRUE or FALSE indicating whether connection exists



f_check_inHRESULT f_check_in( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_error, [out, retval] short * re-tval ) ;

Description: This function checks in a component. It releases exclusive update rights to the component and its sub-components. The only user able to check-in the component is the user who currently has it checked out. However, inVasont Administrator, a special permission can be given to a user to “override check-out”. Applying this permissionallows a user to check-in an item that they did not initially check-out.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be checked in

as_error String Reason if check in is not accomplished

Output Parameters

Name Type Definitionas_error String Explanation for check in failure

retval Short 1=success

0=component not currently checked out

−1=component checked out to another user

f_check_outHRESULT f_check_out( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_error, [out, retval] short * re-tval );

Description: This function checks out a component to a user who is connected to the database. It gives the userexclusive update rights to the component and any of its subcomponents.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be checked out

as_error String Reason if check out is not accomplished

Output Parameters

Name Type Definitionas_error String Explanation for check out failure


0=already checked out to this user

−1=already checked out by another user



Name Type Definition −2=children component(s) are checked out

−3=ancestor checked out by another user

f_check_out_statusHRESULT f_check_out_status( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_check_out_user, [out,retval] short * retval );

Description: This function provides the username of the individual who has the specified component checked out. Ifthe component itself is not checked out, the ancestor and the descendants are searched for check out status.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be interrogated

as_check_out_user String Returns user name who has component checked out

Output Parameters

Name Type Definitionas_check_out_user String User name who has component checked out

retval Short 0=not checked out

1=component checked out

2=child(ren) checked out

3=ancestor checked out

f_check_out_status_componentHRESULT f_check_out_status_component( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_username,[out, retval] short * retval );

Description: This function returns the check out status for the specified component.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be interrogated

as_username String Returns user name who has component checked out

Output Parameters

Name Type Definitionas_username String User name who has component checked out

retval Short 0=not checked out



Name Type Definition 1=component checked out

f_checkout_redirectHRESULT f_checkout_redirect( [ in ] double ad_entity_id, [ in ] BSTR as_username, [ in ] BSTR as_workgroup,[ in, out ] VARIANTARG * as_error_msg, [out, retval] short * retval );

Description: This function changes checkout ownership for a given checked-out entity to a specified user.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be redirected

as_username String User name to which entity is redirected

as_workgroup String Workgroup to which user is assigned

as_error_msg String Error message

Output Parameters

Name Type Definitionas_error_msg String Reason redirect failed


−1=failure

f_checkout_redirect_user_selectHRESULT f_checkout_redirect_user_select( [ in ] double ad_entity_id, [ in ] double ad_custom_rule_use_id,[ in, out ] VARIANTARG * as_username, [ in, out ] VARIANTARG * ai_action_code, [ in, out ] VARIANTARG *as_message, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set of the users to whom a given checked-out entity can have checkoutownership redirected.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be redirected

ad_custom_rule_use_id Double Value obtained from f_get_rightclick_processing_options. (SeeNOTE below).

as_username String Empty string - only used if auto-redirect is employed

ai_action_code Double Empty field - unused on input

as_message String Error message

NOTE: See API function f_get_rightclick_processing_options resultset for value.



Output Parameters

Name Type Definitionas_username String Name of user if auto-redirected

ai_action_code Double Action code: −1= error; 0=success; 1=auto-redirect

as_message String Reason for failure

retval Result Set Resultset containing following data:

String work_group_user_username

String work_group_work_group_name

f_children_allowedHRESULT f_children_allowed( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] VAR-IANT_BOOL * retval );

Description: This function determines whether a component has any children components allowed in the collectiondefinition.

Input Parameters

Name Type Definitionad_prod_id Double Collection identifier for component


Output Parameters

Name Type Definitionretval Boolean Returns TRUE if children components exist; FALSE if they do not

f_clone_componentHRESULT f_clone_component( [ in ] double ad_src_entity_id, [ in ] double ad_trgt_entity_id, [ in ] doublead_rr_to_clone_as, [ in ] BSTR as_child_or_sibling, [ in ] BSTR as_before_or_after, [ in, out ] VARIANTARG *as_error_text, [out, retval] double * retval );

Description: This function is used to clone data. The f_drop_allowed function is often used prior to this function todetermine if the data is allowed to be cloned.

Input Parameters

Name Type Definitionad_src_entity_id Double Identifies source entity

ad_trgt_entity_id Double Identifies target entity

ad_rr_to_clone_as Double Rule relation to clone

as_child_or_sibling String Copy source data as child or sibling of target component



Name Type Definitionas_before_or_after String Place before or after target entity_id

as_error_text String Error text returned

Output Parameters

Name Type Definitionas_error_text String Text returned if program encounters errors

retval Double 0=success; −1=failure

f_clone_component_overwriteHRESULT f_clone_component_overwrite( [ in ] double ad_src_entity_id, [ in ] VARIANTARG * ad_tgt_entity_id,[ in, out ] VARIANTARG * as_error_text, [out, retval] short * retval );

Description: This function clones the source to one or more target components and overlays the target componentcontent.

Input Parameters

Name Type Definitionad_src_entity_id Double Source entity_id

ad_tgt_entity_id Double Array of target entity_ids

as_error_text String Passed by reference—will contain info regarding any errors

Output Parameters

Name Type Definitionas_error_text String Passed by reference—will contain information regarding any errors

retval Short Number of target entities updated

f_clone_primaryHRESULT f_clone_primary( [ in ] double ad_src_entity_id, [ in ] double ad_tgt_prim_entity_id, [ in ] doublead_trgt_prod_id, [ in ] BSTR as_placement, [ in, out ] VARIANTARG * as_error_text, [out, retval] double * re-tval );

Description: This function is used to clone a primary to another collection.

Input Parameters


ad_trgt_prim_entity_id Double Identifies target primary entity

ad_trgt_prod_id Double Identifies target collection



Name Type Definitionas_placement String Placement before or after target primary_entity_id


Output Parameters

Name Type Definitionas_error_text String Text returned if program encounters errors


f_complete_review_editingHRESULT f_complete_review_editing( [ in ] double ad_review_id, [ in ] BSTR as_filename, [ in ] VAR-IANT_BOOL ab_load, [ in, out ] VARIANTARG * as_error_message, [out, retval] short * retval );

Description: This completes the editing portion of a review. This handles both the load of the file and the comple-tion of the Review. The load process may or may not occur depending on the load flag set up in Administrator. If theload flag is set to a then the load will occur. If the load flag is set to n, then the load will not occur. If the load flag isset to pick then the Boolean argument ab_load will determine whether a load occurs.

Input Parameters

Name Type Definitionad_review_id Double The identifying value for the review.

as_filename String The full path and file name of the completed editing file.

ab_load Boolean True=load, False=do not load

Output Parameters

Name Type Definitionas_error_message String This will be populated with the error that occurred if the function

fails and return -1.

retval Integer 1 = success; -1 = failure

f_complete_reviewer_sessionHRESULT f_complete_reviewer_session( [ in ] double ad_reviewer_id, [ in, out ] VARIANTARG * as_error_mes-sage, [out, retval] short * retval );

Description: The review session related to this user (based on ad_reviewer_id) will be closed. If this is the last ac-tive review session for the review, then the status of the review will change from “reviewing” to “editing”. In thiscase, the f_generate_review_merge_file will be called to ensure that markup from all review sessions are included inthe latest merge file (stored in review_merge_files table).



Input Parameters

Name Type Definitionad_reviewer_id Double The identifying value for the reviewer.

Output Parameters




f_complete_taskHRESULT f_complete_task( [ in ] double ad_instance_id, [out, retval] short * retval);

2 Even if this function returns True (indicating the connection has been successfully established to theVasont database), the contents of as_error should be checked. This reference argument may containimportant warnings, regarding the login process, that should be presented to the user.

Description: This function determines whether the specified task has been completed.

Input Parameters

Name Type Definitionad_instance_id Double Specific workflow task identifier

Output Parameters

Name Type Definitionretval Short Success or failure (−1=failure; anything else=success)

Example:Dim li_rcDim ld_instance_id ld_instance_id=1042li_rc=targobj.f_complete_task(ld_instance_id)

f_conditional_extract_fileHRESULT f_conditional_extract_file( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR as_condi-tional_xml, [ in, out ] VARIANTARG * as_filename, [ in, out ] VARIANTARG * as_error_message, [out, retval]short * retval);

Description: This function extracts an entity and its descendants based upon conditional information.



Input Parameters

Name Type Definitionad_entity_id Double Identifies root entity to extract.

ad_version_id Double Identifies shadow version used for extract

as_conditional_xml String Conditions for extract.

as_filename String Name of file being extracted. Passed by reference.

as_error_message String Text returned if program encounters errors

Output Parameters

Name Type Definitionas_filename String Name of file

as_error_message String Reason extract failed

retval Short 1=success; −1=failure

f_connect_to_databaseHRESULT f_connect_to_database( [ in ] BSTR as_dbms, [ in ] BSTR as_servername, [ in ] BSTR as_database,[ in ] BSTR as_userid, [ in ] BSTR as_dbpass, [ in ] BSTR as_dbparm, [ in, out ] VARIANTARG * as_error, [ out,retval ] VARIANT_BOOL * retval );

Description: When a client makes a connection to the COM object, this function is necessary to establish a databaseconnection between the COM and Oracle for the user. Arguments, as_dbms and as_servername, can be found in theVasontApps.ini file.

2 This function is obsolete and should no longer be used for Vasont API client applications. For estab-lishing Vasont API connections to the Vasont Database, use one of the following methods:

f_connect_using_ini (establish connection based on the current, or default, Database Profile in Vaso-ntApps.ini)

f_connect_using_profile (establish connection using the specified Database Profile from Vaso-ntApps.ini)

Input Parameters

Name Type Definitionas_dbms String dbms (e.g., “o84 ORACLE 8.0.4”)

as_servername String Oracle service name

as_database String Database (pass empty string)

as_userid String Username

as_dbpass String Oracle password

as_dbparm String Oracle dbparm settings

as_error String If connection fails, indicates reason user was not connected to Vas-ont database



Output Parameters

Name Type Definitionas_error String Reason user was not connected to Vasont database

retval Boolean Success or failure. If failure occurs, user needs to check Input Pa-rameter, as_error, for error text


Example:

Dim Ib_connect As BooleanDim ls_user As StringDim ls_psswd As String ΄this gets the username typed in by userls_user = Text1.Text΄this gets the password typed in by userls_user = Text2.Text Set targobj = CreateObject("PB70.n_vasont_com")lb_connect = targobj.f_connect_to_database("073 ORACLEv7.3", "@target", "", ls_user, ls_psswd,"")If ib_connect ThenMsgBox ("connect success")ElseMsgBox ("connect failure")End If

f_connect_using_iniHRESULT f_connect_using_ini( [ in ] BSTR as_userid, [ in ] BSTR as_dbpass, [ in, out ] VARIANTARG * as_er-ror, [out, retval ] VARIANT_BOOL * retval );

Description: This function serves the same purpose as the f_connect_to_database function. However, this functionautomatically looks up the database connection parameters in the VasontApps.ini.file. Client programs, therefore,can simply connect to the Vasont database by passing a username and password.

Input Parameters

Name Type Definitionas_userid String Username

as_dbpass String Oracle password




Output Parameters

Name Type Definitionas_error String Reason user was not connected to Vasont database



f_connect_using_profileHRESULT f_connect_using_profile( [ in ] BSTR as_user, [ in ] BSTR as_pwd, [ in ] BSTR as_profile, [ in, out ]VARIANTARG * as_error, [out, retval] VARIANT_BOOL * retval );

Description: This function connects to the database using a particular profile.

Input Parameters

Name Type Definitionas_user String Username

as_pwd String Oracle password

as_profile String User's profile


Output Parameters

Name Type Definitionas_error String Reason user not connected to Vasont database



f_count_childrenHRESULT f_count_children( [ in ] double ad_parent_entity_id, [ in ] double ad_child_rr_id, [out, retval] short *retval );

Description: This function returns the number of children for the entity designated by a specific entity_id/rule_rela-tion_id combination.



Input Parameters

Name Type Definitionad_parent_entity_id Double Parent entity identifier

ad_child_rr_id Double Child entity rule relation identifier

Output Parameters

Name Type Definitionretval Short Number of children for specified relationship

f_create_from_template_prod_listHRESULT f_create_from_template_prod_list( [ in ] BSTR as_username, [out, retval] LPDISPATCH * retval );

Description: This function will return a list of collections that are configured with the processing option cre-ate_new_from_template. The list of collections returned will only include those that the passed user has access to. Aresult set will be returned with a row for each collection.

Input Parameters

Name Type Definitionas_username String Specifies the user name that will be shown the list of collections.

Output Parameters

Name Type Definitionprod_id Double Identifies the id of the collection.

prod_name String(50) The name of the collection.

prod_abbrev String(20) The abbreviated name of the collection.

prod_edition String(20) The edition of the collection.

subject_name String(50) The name of the Content Type the collection is within.

subject_id Double The id value of the Content Type the collection is within.

product_group String(50) The name of the collection group the collection is within. This maybe empty.

prod_group_id Double The id value of the collection group the collection is within. Thisvalue may be Null.

lang_id Double The id value of the language associated with the collection.

f_create_new_from_templateHRESULT f_create_new_from_template( [ in ] double ad_src_entity_id, [ in ] double ad_tgt_prod_id, [ in ] doublead_tgt_relation_id, [ in ] double ad_tgt_entity_id, [ in ] double ad_custom_rule_use_id, [ in, out ] VARIANTARG *as_error_text, [out, retval] double * retval );



Description: This function (used to implement Vasont's create_new_from_template Processing Option) createsnew content in a target collection based on a hierarchical template stored in a separate Vasont collection. The tem-plate can contain any mix of components (with boilerplate text, if desired) that are hierarchically valid at the targetlocation (as a peer to ad_tgt_entity_id having component type identifier ad_tgt_relation_id).

The new content is created (as a peer) immediately following the target location (ad_tgt_entity_id), unless a Vasontprocessing option (e.g., last_record, sequence_alphabetical, etc.) overrides this placement.

Input Parameters

Name Type Definitionad_src_entity_id Double Component identifier for top-most component in hierarchical tem-

plate

ad_tgt_prod_id Double Collection identifier for target collection

ad_tgt_relation_id Double Component type identifier that is used for new content's top-mostcomponent

ad_tgt_entity_id Double Component identifier of component that new content is to follow(if creating new primary component from template, can be 0 - re-quired otherwise)

ad_custom_rule_use_id Double Custom rule use identifier used to obtain create_new_from_tem-plate processing option arguments

as_error_text String Reference argument for any errors that occur

Output Parameters

Name Type Definitionas_error_text String Reason new content could not be created from template

retval Double Component identifier, in target collection, for top-most componentin new content

f_create_ptr_from_pointeeHRESULT f_create_ptr_from_pointee( [ in ] double ad_src_entity_id, [ in ] double ad_trgt_entity_id, [ in ] doublead_trgt_rr_id, [ in ] BSTR as_placement, [ in ] BSTR as_link_match_criteria, [ in ] BSTR as_child_or_sibling,[ in, out ] VARIANTARG * as_err_txt, [out, retval] short * retval );

Description: This function is used to create a pointer component that points to the source entity id.

Input Parameters



ad_trgt_rr_id Double Identifies target rule relation

as_placement String Placement-before or after target entity_id

as_link_match_criteria String Links criteria for pointer

as_child_or_sibling String Create pointer as child or sibling of target entity_id



Name Type Definitionas_err_txt String Error text returned

Output Parameters

Name Type Definitionas_err_txt String Text returned if program encounters errors


f_create_variantsHRESULT f_create_variants( [ in ] double ad_base_entity_id, [ in ] VARIANTARG * ad_target_entity_ids, [ in ]VARIANT_BOOL ab_all_combinations, [out, retval] short * retval );

Description: This function creates “Similar Component” (Variant) relationships between a given Collection compo-nent in Vasont and other Collection components (that the user has indicated are similar). If desired, Similar Content(Variant) relationships can also be created for all the different combinations of Collection components.

Typically, this function is called after presenting a Cross-Collection component Pick List—See thef_get_cross_prod_components API function.

Input Parameters

Name Type Definitionad_base_entity_id Double Component identifier of the entity for which similar Content (Var-

iant) relationships are to be created.

ad_target_entity_ids Double An array of component identifiers representing the entities thatshould be marked as having content similar to (Variants of)ad_base_entity_id.

ab_all_combinations Boolean Flag indicating whether similar content (Variant) relationshipsshould also be created for all of the ad_target_entity_ids combina-tions.

Output Parameters

Name Type Definitionretval Short 1=success; −1=failure

f_del_batch_extract_queueHRESULT f_del_batch_extract_queue( [ in ] double ad_beq_id, [out, retval] short * retval );

Description: This function deletes a row from the batch_extract_queue table.

Input Parameters

Name Type Definitionad_beq_id Double Batch extract identifier of row to be deleted



Output Parameters


f_del_extracted_from_batch_extract_queueHRESULT f_del_extracted_from_batch_extract_queue( [ in ] BSTR as_user_id, [ in, out ] VARIANTARG * ai_er-ror_code, [ in, out ] VARIANTARG * as_error_msg, [out, retval] short * retval );

Description: This function deletes all entries in the batch extract queue marked as extracted for the user id passed asan argument.

Input Parameters

Name Type Definitionas_user_id String Userid for user whose extracted entries are being deleted

ai_error_code Double Error code

as_error_msg String Indicates reason extract failed

Output Parameters

Name Type Definitionai_error_code Double Native SQL error code for any error that occurs

as_error_msg String Error message for any errors that occur

retval Short 1=success; −1=otherwise

f_delete_daemon_batchHRESULT f_delete_daemon_batch( [ in ] const short ai_daemon_batch_id, [out, retval] VARIANT_BOOL * re-tval );

Description: Deletes a row from daemon_batch table. This table stores batch jobs that daemons should run. A dae-mon queries the table for a new job.

Input Parameters

Name Type Definitionai_daemon_batch_id Short batch_id to be deleted

Output Parameters

Name Type Definitionretval Boolean Returns TRUE if the entry is deleted successfully, otherwise

FALSE



f_delete_entityHRESULT f_delete_entity( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_error_message, [out, retval]VARIANT_BOOL * retval );

Description: This function deletes an entity and all its children. In order for the function to succeed, the entity_idmust exist. A user must have security rights to delete this entity and all its children. The function fails, if the follow-ing occurs:

• Entity, or one of the children, is checked out to someone else.

• Entity, or one of its children, is referenced by a pointer component.

If the delete is successful, the parent of the deleted entity is re-analyzed for proper status.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be deleted

as_error_message String Reason if delete is not accomplished

Output Parameters

Name Type Definitionas_error_message String Reason for delete failure

retval Boolean Success or failure

Example:Dim lb_success As BooleanDim ld_entity_id As DoubleDim ld_prod_id As Double Dim ls_text As String΄try and delete the Comets articleld_prod_id = 6077ls_text = ΄Comets΄ld_entity_id = targobj.f_get_primary_entity_from_text (ld_prod_id, ls_text) MsgBox (ld_entity_id)MsgBox (ls_text) lb_success = targobj.f_delete_entity(ld_entity_id, ls_error)If lb_success ThenMsgBox ("success")ElseMsgBox ("error occurred in delete" + ls_error)End If

f_disconnect_from_databaseHRESULT f_disconnect_from_database( [out, retval] VARIANT_BOOL * retval );



Description: This function disconnects from the database. It should be used after completing all calls to the VasontAPI. The success, or failure, of the disconnect from the database is returned.

Input Parameters

None

Output Parameters


f_driver_sequence_primaryHRESULT f_driver_sequence_primary( [ in ] double ad_trgt_prod_id, [ in ] double ad_src_raw_id, [ in ] BSTRas_text, [ in, out ] VARIANTARG * ad_trgt_seq_no, [ in, out ] VARIANTARG * as_alphatag, [out, retval] short *retval );

Description: This function checks if there are any processing options that determine sequence. If so, the arguments,ad_trgt_seq_no and as_alphatag, are populated.

Input Parameters

Name Type Definitionad_trgt_prod_id Double Identifies target collection entity

ad_src_raw_id Double Identifies raw source

as_text String Text

ad_trgt_seq_no Double Target sequence number

as_alphatag String Alpha tag

Output Parameters

Name Type Definitionad_trgt_seq_no Double Target sequence number

as_alphatag String Alpha tag


f_drop_allowedHRESULT f_drop_allowed( [ in ] double ad_src_entity_id, [ in ] double ad_trgt_entity_id, [ in ] BSTR as_user-name, [ in, out ] VARIANTARG * as_err_text, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set of all possible clone choices for copying the source entity_id to thetarget entity_id. If no clone options exist, the result set is empty.



Input Parameters



as_username String Name of user

as_err_txt String Error text returned

Output Parameters

Name Type Definitionas_err_txt String Text returned if program encounters errors


Double rule_relation_id (component type identifier)

String tab_text (component name)

String child_or_sibling (of target component)

String pointer (pointer indicator - yes or no)

f_dynamic_index_buildHRESULT f_dynamic_index_build( [ in ] double ad_prod_id, [ in ] double ad_max_process_count, [ in, out ] VAR-IANTARG * as_error_message, [out, retval] long * retval );

Description: The purpose of this method is to build dynamic index records that are associated with the processingoption dynamic_index_from_attributes. This is called by the Component Library Daemon program.

Input Parameters

Name Type Definitionad_prod_id Double Identifies the collection that will be processed. This collection must

contain the processing option dynamic_index_from_attributes withan event of edit_batch.

ad_max_count Double Defines the maximum number of components that will be pro-cessed. Once the limit is reached, the function will return. Thisdoes not include components that have been previously processedand are still up-to-date.

as_error_message String (by ref-erence)

Populated if errors occur.

Output Parameters

Name Type Definitionretval Integer 1=success; −1=failure



f_exists_entity_by_match_criteriaHRESULT f_exists_entity_by_match_criteria( [ in ] double ad_trgt_prod_id, [ in ] BSTR as_clientkey, [ in ] doublead_src_raw_id, [ in, out ] VARIANTARG * as_match_criteria, [ in, out ] VARIANTARG * ad_trgt_primary_enti-ty_id, [out, retval] short * retval );

Description: This function looks for an existing component that matches the input criteria.

Input Parameters

Name Type Definitionad_trgt_prod_id Double Identifies target collection

as_clientkey String Client key data

ad_src_raw_id Double Identifies raw source

as_match_criteria String Criteria used to find match

ad_trgt_primary_entity_id Double Identifies target primary entity

Output Parameters

Name Type Definitionas_match_criteria String Matched criteria found during search

ad_trgt_primary_entity_id Double Identifies target primary entity found during search

retval Short 1=success; -1=failure

f_exists_preview_setupHRESULT f_exists_preview_setup( [ in ] double ad_prod_id, [out, retval] VARIANT_BOOL * retval );

Description: The purpose of this method is to determine if at least one preview is configured for a given collection.If at least one preview is configured for the collection passed as an argument, then this will return True. If no pre-views are set up for the collection then False will be returned.

Input Parameters

Name Type Definitionad_prod_id Double Identifying value for the collection

Output Parameters

Name Type Definitionretval Boolean True if at least one preview is configured for the collection passed

as an argument; False if no previews are set up for the collection

Example: Used within the VUI when working with a preview pane for a Navigator window. This method can beused to determine if Preview is applicable for the collection that is opened.



f_extractHRESULT f_extract( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in, out ] VARIANTARG * as_er-ror_message, [out, retval] BSTR * retval );

Description: This function extracts a component and all of its descendants using a specific extract view. The extractresult string is typically an SGML or XML tagged content.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity containing component to be extracted

ad_version_id Double Identifies version used for extraction

as_error_message String Error messages

Output Parameters

Name Type Definitionas_error_message String Reason(s) extract was not successful

retval String Extracted string

Following is a tagged XML file string that is obtained from such an extract:

<Recipe Difficulty="Average" ID="676851"Cuisine="American"><Title ID="676851">Baked Potato Soup</Title><Method ID="676853">Cook on stove over medium - high heat</Method><Servings ID="676852">12</Serv-ings><Times ID="676854"><Cook-Time ID="676856">20 - 30 minutes</Cook-Time><Prep-TimeID="676855">15 - 20 minutes</Prep-Time></Times><Ingredients ID="676857"><Ingredient ID="377832">But-ter, with salt<UOM ID="377837">1 cup<Quantity ID="676860">.66</Quantity></UOM></Ingredient><IngredientID="424770">Wheat flour, white, all-purpose, enriched, bleached<UOM ID="424775">1 cup<QuantityID="676863">.66</Quantity></UOM></Ingredient><Ingredient ID="401805">Milk, lowfat, fluid, 1% milkfat,with added vitamin A<UOM ID="401809">1 cup<Quantity ID="676866">7</Quantity></UOM></Ingredi-ent><Ingredient ID="411003">Potatoes, baked, flesh and skin, without salt<UOM ID="411007">1 potato, (2-1/3" x4-3/4")<Quantity ID="676869">4</Quantity></UOM></Ingredient><Ingredient ID="403716">Onions, spring orscallions (includes tops and bulb), raw<UOM ID="403730">1 small (3" long)<Quantity ID="676872">4</Quanti-ty></UOM></Ingredient><Ingredient ID="408571">Pork, cured, bacon, raw<UOM ID="408580">1 medium slice,packed 20/lb<Quantity ID="676875">4</Quantity></UOM></Ingredient><Ingredient ID="382927">Cheese, ched-dar<UOM ID="382953">1 cup, shredded<Quantity ID="676878">1.25</Quantity></UOM></Ingredient><Ingredi-ent ID="388965">Cream, sour, cultured<UOM ID="388970">1 cup<Quantity ID="676881">1</Quantity></UOM></Ingredient><Ingredient ID="413712">Salt, table<UOM ID="405807">1 teaspoon<QuantityID="676884">.5</Quantity></UOM></Ingredient><Ingredient ID="405800">Pepper, black<UOMID="405807">1 teaspoon<Quantity ID="676887">.5</Quantity></UOM></Ingredient></Ingredients><StepsID="676888"><Step ID="676889">Earlier in the day or the previous day, bake 4 large baking potatoes.</Step><Step ID="676890">Peel and chop potatoes.</Step><Step ID="676891">In large stockpot, melt margarine.</Step><Step ID="676892">Stir in flour. Heat and stir until smooth.</Step><Step ID="676893">Gradually add themilk, stirring constantly, until thickened.</Step><Step ID="676894">Add the potatoes and onions. Bring to a boil,stirring constantly.</Step><Step ID="676895">Reduce heat and simmer for 10 minutes.</Step><StepID="676896">Add remaining ingredients (salt and pepper to taste), stirring until cheese is melted and well com-bined.</Step><Step ID="676897">Pour into serving bowls. Top with additional shredded cheese and bacon if de-sired.</Step></Steps></Recipe>



f_extract_blobHRESULT f_extract_blob( [ in ] double ad_raw_id, [ in, out ] VARIANTARG * as_filename, [out, retval] short *retval );

Description: This function looks up the Binary Large Object (BLOB) associated with the raw_id argument. If theBLOB is not found in the file, the function returns a minus 1 (-1).

If the BLOB is found, it generates a file in the location specified by the as_filename argument. The BLOB extensionfound in the database is written to as_filename. For example, if “c:\temp\graphic” is passed and the BLOB is foundwith a GIF extension in the database, as_filename is altered to “c:\temp\graphic”. If the filename already contains anextension, it is replaced.

Input Parameters

Name Type Definitionad_raw_id Double Raw material identifier

as_filename String Fully specified path where file to be extracted is created

Output Parameters

Name Type Definitionas_filename String Value can be changed by function

retval Short 1=success; −1=BLOB not found

f_extract_by_lang_attribHRESULT f_extract_by_lang_attrib( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR as_lang_at-tribs, [ in, out ] VARIANTARG * as_error_message, [out, retval] BSTR * retval );

IMPORTANT: This function works in conjunction with the Vasont get_selected_lang_attribs Processing Option. Ifthis option is not applied to the Extract View argument to this function, the list of language attribute values providedis ignored.

Description: This function extracts a component and its descendants, limiting the extracted content based on a de-limited list of language attribute values. All components that do not have an associated language attribute in Vasontare included in the extract, along with any components that have a language attribute value matching an entry in theprovided list. The extract result string is typically SGML or XML tagged content.

For components that have the language attribute, the components are extracted in the order in which the languageattribute values are specified in the as_lang_attribs argument.

Input Parameters


ad_version_id Double Identifies version used for extract

as_lang_attribs String Pipe (“|”) delimited list of language attribute values (e.g., “en_ww|fr_ww”) - only components that have a matching language attribute



Name Type Definitionvalue (or do not have a language attribute at all) are included in ex-tract


Output Parameters


retval String Extracted string

f_extract_conref_fileHRESULT f_extract_conref_file( [ in ] BSTR as_conref_value, [ in ] BSTR as_path_and_filename, [out, retval]short * retval );

Description: This function extracs the target primary component of a DITA conref atribute value.

Input Parameters

Name Type Definitionas_conref_value String The CONREF attribute value.

as_path_and_filename String The path where you want to save the conref file, and the name ofthe file.

Output Parameters

Name Type Definitionretval Short Returns 1 if succesful, 0 if the CONREF value could not be parsed,

or -1 if an error occurs during extract.

f_extract_fileHRESULT f_extract_file( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR as_filename, [ in, out ]VARIANTARG * as_error_message, [out, retval] short * retval );

Description: This function is similar to the f_extract function, except the extract result is placed in a specified fileinstead of being returned as a string. The as_filename string should be the fully specified path, including the file-name.

Input Parameters

Name Type Definitionad_entity_id Double Entity_id of the component that is being extracted





Name Type Definitionas_error_message String Error messages

Output Parameters

Name Type Definitionas_error_message String Reason extract failed


Example:

as_filename = "c:\vasont\extract\test.sgm"

Here, the “c drive”, the Vasont directory and the extract subdirectory have been specified. The filename is test.sgm.

f_extract_file_by_lang_attribHRESULT f_extract_file_by_lang_attrib( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTRas_lang_attribs, [ in ] BSTR as_filename, [ in, out ] VARIANTARG * as_error_message, [out, retval] short * re-tval );

IMPORTANT: This function works in conjunction with the Vasont get_selected_lang_attribs Processing Option. Ifthis option is not applied to the Extract View argument to this function, the list of language attribute values providedare ignored.

Description: This function is similar to the f_extract_by_lang_attrib function, except the extract result is placed in aspecified file instead of being returned as a string. The as_filename argument should be a fully specified path, in-cluding the filename.

Input Parameters



as_lang_attribs String Pipe (“|”) delimited list of language attribute values (e.g., “en_ww|fr_ww”) - only components that have a matching language attributevalue (or do not have a language attribute at all) are included in ex-tract under specified order

as_filename String Full path and filename of file to be created by extract


Output Parameters


retval String 1=success; −1=failure



f_extract_file_by_versionHRESULT f_extract_file_by_version( [ in ] double ad_entity_id, [ in ] double ad_extract_version_id, [ in ] doublead_transaction_id, [ in, out ] VARIANTARG * as_filename, [ in, out ] VARIANTARG * as_error_message, [out,retval] short * retval );

Description: This function is similar to the f_extract_file function, except the extracted file is based on an historicalVasont version and not based on the current live content. The as_filename string should be the fully specified path,including the filename.

Input Parameters

Name Type Definitionad_entity_id Double Identifies content to be extracted

ad_extract_version_id Double Identifies id for the extract view to be used

ad_transaction_id Double Identifies the id for the version to be extracted



Output Parameters



f_extract_file_with_saved_conditionHRESULT f_extract_file_with_saved_condition( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTRas_condition_name, [ in, out ] VARIANTARG * as_filename, [ in, out ] VARIANTARG * as_error_message, [out,retval] short * retval );

Description: The purpose of this method is to perform an extract using a Saved Condition Set. The saved conditionset name is passed into the function and must be valid within the collection that relates to the root entity_id (i.e.,ad_entity_id argument) that is being extracted.

Input Parameters

Name Type Definitionad_entity_id Double Entity_id of the component that is being extracted


as_condition_name String Identifies the saved condition set

as_filename String (by ref-erence)

Fully specified path where file to be extracted is created


Error messages



Output Parameters


Example: Use this extract method in conjunction with the Auto-Publishing extract daemon process.

f_extract_multiple_primariesHRESULT f_extract_multiple_primaries( [ in ] BSTR ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR as_file-name, [ in, out ] VARIANTARG * as_error_message, [out, retval] short * retval );

Description: This function extracts multiple primaries.

Input Parameters

Name Type Definitionad_entity_id Double An array of primaries to be extracted




Output Parameters



f_extract_shadowHRESULT f_extract_shadow( [ in ] double ad_prim_entity_id, [ in ] double ad_entity_id, [ in ] double ad_ver-sion_id, [ in ] DATE adt_shadow_date, [ in ] VARIANT_BOOL ab_hierarchy, [ in, out ] VARIANTARG * as_file-name, [ in, out ] VARIANTARG * as_error_text, [out, retval] short * retval );

Description: This function extracts an entity's snapshot record for the date given to a file.

Input Parameters

Name Type Definitionad_prim_entity_id Double Identifies primary entity

ad_entity_id Double Identifies snapshot entity to be extracted

ad_version_id Double Identifies shadow version used for extract

adt_shadow_date Date Date snapshot extract is created

ab_hierarchy Boolean If true, extracts all descendants. If false, extracts component only.

as_filename String Name of file being extracted

as_error_text String Text returned if program encounters errors



Output Parameters


as_error_text String Reason extract failed


f_fast_extract_buildHRESULT f_fast_extract_build( [ in ] double ad_prod_id, [ in ] double ad_max_process_count, [ in, out ] VAR-IANTARG * as_error_message, [out, retval] long * retval );

Description: This function will build XML BLOB components for primary components. These XML BLOBs willbe used in conjunction with the Fast Extract feature in Vasont. This API call relies on the processing option fast_ex-tract_build being set up in the Vasont Administrator for the collection that is being processed.

Input Parameters

Name Type Definitionad_prod_id Double Identifies the collection to be processed.

ad_max_count Double Specifies the maximum number of primary components to process.


Reference argument that will contain error messages.

Output Parameters

Name Type Definitionretval Double The number of primaries that were processed and had child XML

BLOB component created or updated.

f_generate_review_merge_fileHRESULT f_generate_review_merge_file( [ in ] double ad_review_id, [ in, out ] VARIANTARG * as_error_mes-sage, [out, retval] short * retval );

Description: This will gather the latest version of all the review files (found in reviewer_files) related to the ad_re-view_id argument. That information will be passed to a new program being developed by Rob, which will generatea merge file. The resulting merge files will be stored in the review_merge_files table.

Input Parameters




Output Parameters




f_get_active_daemonsHRESULT f_get_active_daemons( [out, retval] LPDISPATCH * retval );

Description: Returns a resultset specifying daemon information in the current installation. A daemon is a machinerunning the Vasont COM that is available for batch processes (extracts and loads). If no records are found, this re-turns a resultset of a single record with the string ‘No Active Daemons’ in DAEMON_ID and DAEMON_NAME.

Input Parameters

None

Output Parameters

Name Type Definitionretval Result Set Resultset containing the following data:

String DAEMON_ID (usually a machine id, i.e. PC108)

String DAEMON_NAME (usually a descriptive name, i.e. Batch Extract/Load Queue on PC108)

String DAEMON_TYPE - EXTRACT, LOAD, or EXTRACT_LOAD(specifies the type of batch process that can be run by the daemon)

Date LAST_RUN (date/time that the daemon last contacted the database—this timestamp is updated when the daemon performs some ac-tion and/or updates this every EXPIRE_VALUE minutes)

Double EXPIRE_VALUE (number of minutes past the timestamp forwhich the daemon should be considered non-active—if the daemonhas a setting of 15 here and the timestamp date/time is last week,this should NOT BE CONSIDERED an active daemon)

Double ITEMS_QUEUED (number of items for load or extract the daemonhas in its job queue)

String LOAD_ROOT (network path to the daemon load directory wherethe daemon will load files from)

String EXTRACT_ROOT (network path to the daemon extract directorywhere the daemon will extract files to)

f_get_active_tasks_for_userHRESULT f_get_active_tasks_for_user( [ in ] BSTR as_username, [out, retval] LPDISPATCH * retval );



Description: This function will retrieve the active workflow tasks for the user name that is passed to the function.The return value is a result set with various columns and will contain a row for each active task.

Input Parameters

Name Type Definitionas_username Double Identifies the user whose active tasks will be returned.

Output Parameters

Name Type Definitioninstance_id Double Id for task instance.

project_name String(50) Name of workflow project.

prod_id Double Id for collection.

project_id Double Id for project definition.

task_name String(50) Name of workflow task.

task_id Double Id of task definition.

username String(30) Username associated with task.

start_date Date Date the task was started.

due_date Date Date the task is due.

complete_date Date Date the task was completed. Will be Null for active tasks.

prod_abrev String(20) Abbreviated name of collection.

workflow_id Double Id of workflow project instance.

entity_id Double Id value of component associated with workflow.

primary_desc String(4000) Description of primary component associated with workflow.

entity_desc String(4000) Description of component associated with workflow.

status String(1) “a” or “c” for active or complete.

rule_relation_id Double Id value of component definition.

assigned_by String(30) User who assigned the workflow task.

primary_entity_id Double Id value of primary associated with workflow task.

workflow_start_date Date The date the workflow project instance was started.

workflow_due_date Date The date the workflow project instance is due.

f_get_api_versionHRESULT f_get_api_version( [ in, out ] VARIANTARG * as_api_version, [ in, out ] VARIANTARG *as_api_date, [ in, out ] VARIANTARG * as_db_version, [out, retval] short * retval );

Description: Returns the API version build number, the API version build date, and the Vasont database versionbuild number. All three strings are returned by reference.



Input Parameters

Name Type Definitionas_api_version String API version build number

as_api_date String API version build date

as_db_version String Vasont database version build number

Output Parameters

Name Type Definitionas_api_version String API version build number

as_api_date String API version build date

as_db_version String Vasont database version build number

retval Short Returns 1

f_get_app_ini_file_pathHRESULT f_get_app_ini_file_path( [out, retval] BSTR * retval );

Description: This function will return the path of the vasontapps.ini file. For example, this path could be “c:\win-dows”.

Input Parameters

None

Output Parameters

Name Type Definitionretval String The path of the vasontapps.ini file.

f_get_app_pathHRESULT f_get_app_path( [out, retval] BSTR * retval );

Description: This function will return the path of the Vasont application. For example, this path could be “c:\vasont\app”.

Input Parameters

None

Output Parameters

Name Type Definitionretval String The path of the current application.



f_get_approved_shadow_datesHRESULT f_get_approved_shadow_dates( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function returns the dates for which there are snapshot records for the given entity.

Input Parameters

Name Type Definitionad_entity_id Double Entity identifier

Output Parameters

Name Type Definitionretval Result Set Resultset containing following data:

Double entity_id (entity identifier)

Datetime edit_date (date snapshot record created)

String entity_status_date (date entity placed in status reflected in enti-ty_status_flag)

String entity_username (user who made changes causing snapshot)

Double raw_id (raw identifier)

String entity_status_flag (status of entity when snapshot was created)

String entity_nav_display

String component_type

Double prod_id (the collection id of the component)

Double rule_relation_id (the rule_relation of the component)

f_get_attribute_nameHRESULT f_get_attribute_name( [ in ] double ad_attribute_link_id, [out, retval] BSTR * retval );

Description: This function will retrieve the sgml_name for an attribute_link_id or will return an empty string if aname is not found.

Input Parameters

Name Type Definitionad_attribute_link_id Double The attribute_link_id for the attribute. This id is specified in the

Vasont Administrator attribute list.



Output Parameters

Name Type Definitionretval String The sgml_name for the attribute. This name is specified in the Vas-

ont Administrator attribute list. Will be an empty string if nosgml_name is specified, or the attribute_link_id is not found.

f_get_attribute_valid_valuesHRESULT f_get_attribute_valid_values( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ] BSTRas_attribute_name, [out, retval] LPDISPATCH * retval );

Description: This function returns an array of valid values for an attribute associated with a specific component in aspecific collection. These values can also be looked up in the Vasont Administrator Edit View for a collection, asshown in the following example:

The following Detailed Edit View screen shot shows the prod_id of 10361 for the Recipe collection and rule_rela-tion_id of 10129 for the Recipe component. The attribute_link_id for the Difficulty attribute is 10062. Supplying



these parameters and calling this function returns a three-row Result Set. The first row has Easy; the second row hasAverage, and the third row has Difficult.

Input Parameters

Name Type Definitionad_prod_id Double Collection identifier


as_attribute_name String Attribute associated with specific component in specific collection

Output Parameters


Valid values (allowed for attribute)

f_get_attribute_valueHRESULT f_get_attribute_value( [ in ] double ad_entity_id, [ in ] double ad_attribute_link_id, [out, retval] BSTR *retval );

Description: This function returns the value of the attribute requested for the specified entity.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which attribute value is requested

ad_attribute_link_id Double Attribute link identifier



Output Parameters

Name Type Definitionretval String Value of attribute

f_get_attributes_allowedHRESULT f_get_attributes_allowed( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval]LPDISPATCH * retval );

Description: This function returns a Result Set which lists the definition of all attributes that are attached to a com-ponent type.

Input Parameters



Output Parameters


Double prod_id (collection identifier)


Double attribute_link_id (attribute link id identifier)

Short seq_no (sequence number defining order within other attributes forthis component)

String default_value (attribute default value, if it exists)

String sgml_name (attribute's name)

Double sgml_type_id

Double value_raw_type_id (raw_type_id defines raw type values fromwhich to pick. Optional field - rarely used)

String edit_flag (y/n field determines if value can be edited)

Double child_rule_id

f_get_batch_queueHRESULT f_get_batch_queue( [ in ] BSTR as_user_id, [ in ] BSTR as_queue_type, [ in ] BSTR as_status_to_re-trieve, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the queued Extract or Load batch jobs for the passeduser, queue type (Extract or Load) and job status. When a job is placed in the queue, it is not actually processed untilit is submitted to the extract or load engine - the status requested (as_status_to_retrieve) and reported in the ResultSet (queue_status) reflects the state of the job in the queue.



Input Parameters

Name Type Definitionas_user_id String User for which queued extract/load jobs are retrieved

as_queue_type String Queue type to be retrieved - Values: e (extract); l (load)

as_status_to_retrieve String Job status to be retrieved - Values: queue (jobs not yet submitted toextract/load engine); extract (jobs submitted to extract engine); ex-tracted (jobs completed by extract engine); load (jobs submitted toload engine)

Output Parameters


String prod_abbrev (name of collection in which extract/load componentresides)

String primary_desc (description of extract/load component's primary)

String parent_desc (description of extract/load component's parent)

String component_desc (description of extract/load component)

String client_key (client key data for extract/load component)

String version_description (name of extract or load view to use for job)

String file_name (path/filename to use for extract or load)

String arguments (any special arguments to use for extract or load)

Date queue_date (date/time job was placed in queue)

Double queue_id (unique identifier for each entry in queue)

Double prod_id (collection identifier for collection in which extract/loadcomponent resides)

Double entity_id (entity identifier for extract/load component)

Double rule_relation_id (component type identifier for extract/load compo-nent)

Double parent_entity_id (entity identifier for extract/load component's pa-rent)

Double primary_entity_id (entity identifier for extract/load component'sprimary)

Double version_id (identifier of extract or load view to use for job)

String file_extension (contains default file extension to use for extractedfiles)

String queue_type (queue type - same values as listed for as_queue_typeargument above)

String queue_status (status of job within queue - same values as listed foras_status_to_retrieve argument above)

String queue_user_id (user who placed job in queue)

String queue_message (after job completes, contains any error messagesfrom extract or load process)



Name Type Definition Double queue_sequence_no (sequence in which jobs should be processed

by extract or load engine)

f_get_batch_queue_by_idHRESULT f_get_batch_queue_by_id( [ in ] short ai_queue_id, [out, retval] LPDISPATCH * retval );

Description: Retrieves all entries in the batch queue for the specified queue_id.

Input Parameters

Name Type Definitionai_queue_id Short The queue id you would like to return records for

Output Parameters


String prod_abbrev (name of collection in which extract/load componentresides)

String primary_desc (description of extract/load component's primary)

String parent_desc (description of extract/load component's parent)

String component_desc (description of extract/load component)

String client_key (client key data for extract/load component)

String version_description (name of extract or load view to use for job)

String file_name (path/filename to use for extract or load)

String arguments (any special arguments to use for extract or load)

Date queue_date (date/time job was placed in queue)

Double queue_id (unique identifier for each entry in queue)

Double prod_id (collection identifier for collection in which extract/loadcomponent resides)

Double entity_id (entity identifier for extract/load component)

Double rule_relation_id (component type identifier for extract/load compo-nent)

Double parent_entity_id (entity identifier for extract/load component's pa-rent)

Double primary_entity_id (entity identifier for extract/load component'sprimary)

Double version_id (identifier of extract or load view to use for job)

String file_extension (contains default file extension to use for extractedfiles)

String queue_type (queue type - same values as listed for as_queue_typeargument above)



Name Type Definition String queue_status (status of job within queue - same values as listed for

as_status_to_retrieve argument above)

String queue_user_id (user who placed job in queue)

String queue_message (after job completes, contains any error messagesfrom extract or load process)

Double queue_sequence_no (sequence in which jobs should be processedby extract or load engine)

f_get_bookmark_consoleHRESULT f_get_bookmark_console( [ in ] BSTR as_user, [ in, out ] VARIANTARG * as_error_msg, [out, retval]LPDISPATCH * retval );

Description: This function returns a Result Set of all of the bookmarks for a given user.

Input Parameters

Name Type Definitionas_user String Name of user


Output Parameters

Name Type Definitionas_error_msg String Reason retrieval failed


String prod_abbrev (collection abbreviation)

String primary_desc (primary description)

String component_type (component type)

String component_desc (component description)

String client_key (client key)

String entity_status_flag (entity current status)

Datetime entity_status_date (entity status date)

String entity_username (entity user)



Double primary_entity_id (primary entity identifier)

Double parent_entity_id (parent entity identifier)

Double bookmark_id (bookmark identifier)


String username (name of user)

Datetime bookmark_date (bookmark date)



f_get_check_out_consoleHRESULT f_get_check_out_console( [ in ] BSTR as_user, [ in, out ] VARIANTARG * as_error_msg, [out, retval]LPDISPATCH * retval );

Description: This function returns a Result Set of given user's checkouts (pass all to see ‘all’ users' checkouts).

Input Parameters

Name Type Definitionas_user String Name of user


Output Parameters




String primary_desc (primary description)

String component_type (component type)

String component_desc (component description)






Datetime check_out_date (date checked out)

String additional_info (additional information)






f_get_checkout_infoHRESULT f_get_checkout_info( [ in ] double ad_entity_id, [out, retval] BSTR * retval );

Description: This function returns a message that describes the checkout information for a component that is cur-rently checked out.



Input Parameters


Output Parameters

Name Type Definitionretval String Example:

Checkout User was JOE

Checkout Date was 4/2/2002

Checkout Time was 4:30 PM

f_get_children_allowedHRESULT f_get_children_allowed( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] LPDIS-PATCH * retval );

Description: This function returns a Result Set for all the children allowed in the setup for the passed componenttype.

Input Parameters



Output Parameters



Double parent_rule_id (parent rule identifier)


Double child_rule_id (child rule identifier)

String inline_flag (inline flag)

String inline_nested_view (inline nested view)

String inline_assignment (inline assignment)

Double raw_type_id (raw type identifier)

Double wrapper_id (wrapper identifier)

String begin_tag (being tag)

String end_tag (end tag)

Double raw_class_id (raw class identifier)

String sgml_validate (sgml validate)



Name Type Definition String text_allowed (indicates if text allowed)

String pick_list (pick list)

String edit_flag (y/n field - can value be edited)

String resequence_flag (resequence flag)

String spell_check_flag (spell check flag)

String raw_default_flag (raw default flag)

String client_key_flag (client key flag)

String client_key_text (text for client key)

Double editor_tag_id (editor tag identifier)

String document_type (document type)

String editor_begin_tag (editor begin tag)

String editor_end_tag (editor end tag)

String source_table_name (source table name)

Double nav_order (navigator order number)


String match_criteria (match criteria)

String add_flag (add flag)

String delete_flag (delete flag)

String clone_flag (clone flag)

String expand_inlines (expand inlines)

String valid_value_flag (valid value flag)

String global_change_handle

String version_on_clone

String version_on_approval

String version_on_load

String version_on_update

String version_on_demand

String version_on_delete

Double global_change_work_group_id

f_get_children_by_rule_relationHRESULT f_get_children_by_rule_relation( [ in ] double ad_entity_id, [ in ] double ad_rule_relation_id, [out, re-tval] LPDISPATCH * retval );

Description: This function returns the children of the specified entity_id that have the specified rule_relation_id.This is identical to f_get_entity_children, with the addition of the rule_relation_id qualifier.



Input Parameters

Name Type Definitionad_entity_id Double Identifies entity into which data is to be loaded


Output Parameters




Double raw_id (raw data identifier)

Double entity_seq_no (sequence number for ordering)


Date entity_status_date (entity status date)




Double raw_inline_id (inline data identifier)

String client_key (client key data)

String pending_flag (pending indicator)

Date create_date (entity create date)



f_get_client_keyHRESULT f_get_client_key( [ in ] double ad_entity_id, [out, retval] BSTR * retval );

Description: This function returns the client key for the specified entity.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which client key is requested

Output Parameters

Name Type Definitionretval String Client key



f_get_client_key_useHRESULT f_get_client_key_use( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function retrieves all components that have the same key of the component whose entity_id waspassed as an argument.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity whose client key will be used to find other match-

ing components

Output Parameters


String prod_abbrev (name of collection containing component)

String primary_raw_desc (description of primary containing component)

String parent_raw_desc (description of parent for component). Will beempty if component is child of primary.

String component_type (name of component, e.g., “Author[Chapter]”)

String entity_status_flag (component's current status) - Values: a (ap-proved); d (draft); i (incomplete)

Date entity_status_date (date component was last edited)

String entity_username (user who last edited component)

String username (user who has component checked out)

Date check_out_date (date component was checked out)

String client_key (component's client key data)

Double prod_id (identifier of collection containing component)

Double entity_id (component's entity identifier)

Double rule_relation_id (component's type identifier)

Double primary_entity_id (primary's entity identifier)

Double parent_entity_id (parent's entity identifier)

Double parent_rule_relation_id (parent's entity identifier)

f_get_client_key_use_by_client_keyHRESULT f_get_client_key_use_by_client_key( [ in ] BSTR as_client_key, [out, retval] LPDISPATCH * retval );

Description: This function retrieves all components that have the same client key as that which is passed in as theargument.



Input Parameters

Name Type Definitionas_client_key String Identifies the client key that will be used to find other matching

components

Output Parameters


















f_get_component_dataHRESULT f_get_component_data( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function returns data related to the specified entity.

Input Parameters


Output Parameters




Name Type Definition Double entity_id (entity identifier)



Double entity_seq_no (sequence number for ordering)


Date entity_status_date (entity status date)







Date create_date (entity create date)


String raw_description (component description)

Double global_count: 0=entity_id does not have a record in the Glob-al_Change_Log table; 1=entity_id has a record in the Glob-al_Change_Log table)

Double mod_log_count

f_get_component_from_filterHRESULT f_get_component_from_filter( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ] doublead_rule_relation_id, [ in ] VARIANTARG * as_args, [ in, out ] VARIANTARG * as_class, [ in, out ] VARIAN-TARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing all components (of a particular type) in a collection. Astored filter can be used to further constrain the set of components returned. Because the component can belong toone of several classes, the resultset definition varies depending on that class. A reference argument to this function(as_class) indicates the class and distinguishes the resultset layout.

Input Parameters

N ame Type Definitionad_filter_id Double Unique filter number issued by Vasont when filter is created, saved

and named. Can be equal to 0. If passed as 0, all components fromcollection are retrieved.

ad_prod_id Double Collection identifier from which components are retrieved

ad_rule_relation_id Double Component type identifier - Only components of this type are re-trieved from collection

as_args String Array Array of arguments to use with filter (if one is specified). Filter cantake any number of arguments, depending on number of filter crite-



N ame Type Definitionria. The array of arguments must match up to filter criteria by countand order.

as_class String Reference argument for class of component

as_error_msg String Reference argument for any error messages

Output Parameters

Name Type Definitionas_class String Component class indicating format of returned resultset. Class val-

ues are: Primary, Text, Multimedia, and Pointer.

as_error_msg String Reason retrieval failed

retval Result Set Resultset containing following columns (based on component'sclass):

Primary

String raw_text_text (primary's text)

String entity_status_flag (current status) - Values: a (approved); d (draft);i (incomplete).

Date entity_status_date (date last edited)

String entity_username (user who last edited)


String pending_flag (indicator of pending actions) - Values: n (none);d (deleted); a (added); c (changed).

Date create_date (date created)

String alpha_tag (tag for alphabetic ordering)

String username (user who has primary checked out)

Date check_out_date (date primary was checked out)

Double entity_id (primary's entity identifier)


Double parent_entity_id (parent entity identifier - always empty)

Double primary_seq_no (sequence number for ordering)

Double raw_id (primary's raw data identifier)

Double rule_relation_id (primary's component type identifier)

Double rule_id (primary's rule identifier)

String primary_text (description of primary)

String parent_text (description of parent)

Double prod_id (component's collection identifier)

Double parent_rr_id (parent rule relation identifier)

String component_type (component's type)




Name Type Definition Double mod_log_count

Text

String raw_text_text (component's text)



String entity_status_flag (current status) - Values: a (approved); d (draft);i (incomplete)




String pending_flag (indicator of pending actions) - Values: n (none);d (deleted); a (added); c (changed)


String alpha_tag (tag, from primary, for alphabetic ordering)






Double primary_seq_no (sequence number, from primary, for ordering)



Double entity_rr_id (component rule relation identifier)


Multimedia

String mm_description (multimedia description for component)




String mm_pathname (external path/filename for component)

String file_extension (for internal BLOBs, indicates file type)

String mm_status_flag (multimedia status) - Values: a (approved);m (missing)







Name Type Definition String pending_flag (indicator of pending actions) - Values: n (none);

d (deleted); a (added); c (changed)









String component type (component's type)




Pointer

String points_to (description of pointer's “target”)





















String pointee_desc (navigator display description of pointer's target)



Name Type Definition Double pointee_entity_id

f_get_component_from_filter_stringHRESULT f_get_component_from_filter_string( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ] doublead_rule_relation_id, [ in ] BSTR as_args, [ in, out ] VARIANTARG * as_class, [ in, out ] VARIANTARG * as_er-ror_msg, [out, retval] LPDISPATCH * retval );

Description: This “stub” function is another variant of the “f_get_component_from_filter” function that substitutesa delimited string for the array of Filter arguments. This stub is used by the Vasont Universal Integrator (VUI),which has problems properly typing a string array for use with the Filters. This function takes a delimited string(delimited with a pipe (“|”)), builds an array off of the delimited string and passes the arguments on to: f_get_com-ponent_from_filter( )

Input Parameters

Name Type Definitionad_filter_id Double Stored Filter ID (no Filter used if 0)

ad_prod_id Double Collection for which Components will be retrieved

ad_rule_relation_id Double Component Type (Rule Relation ID) to retrieve

as_args String Delimited string of Values to use with Stored Filter (each value de-limited by the pipe (“|”) symbol)

as_class String Class of the Component (Primary, Text, Multimedia or Pointer)

as_error_msg String REF STRING with Error Message (if errors)

Output Parameters





Primary











Name Type Definition String username (user who has primary checked out)
















Text





















Name Type Definition Double entity_rr_id (component rule relation identifier)


Multimedia

























Pointer










Name Type Definition String client_key (client key data)















Double pointee_entity_id

f_get_component_in_primary_from_filt_strHRESULT f_get_component_in_primary_from_filt_str( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ]double ad_primary_entity_id, [ in ] double ad_rule_relation_id, [ in ] BSTR as_args, [ in, out ] VARIANTARG *as_class, [ in, out ] VARIANTARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This “stub” function is another variant of the “f_get_component_in_primary_from_filter” function thatsubstitutes a delimited string for the array of Filter arguments. This stub is used by the Vasont Universal Integrator(VUI), which has problems properly typing a string array for use with the Filters. This function takes a delimitedstring (delimited with a pipe (“|”)), builds an array off of the delimited string and passes the arguments on to:f_get_component_in_primary_from_filter( )

Input Parameters


ad_prod_id Double Collection for which Components will be retrieved

ad_primary_entity_id Double Primary Entity ID for constraining results (All Components in Col-lection are candidates if 0)

ad_rule_relation_id Double Component Type (Rule Relation ID) to retrieve


as_class String Class of the Component (Primary, Text, Multimedia or Pointer)




Output Parameters





Primary

























Text






Name Type Definition String entity_status_flag (current status) - Values: a (approved); d (draft);

i (incomplete)

















Multimedia



















Name Type Definition Double entity_id (component's entity identifier)








Pointer























Double pointee_entity_id



f_get_component_in_primary_from_filterHRESULT f_get_component_in_primary_from_filter( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ] dou-ble ad_primary_entity_id, [ in ] double ad_rule_relation_id, [ in ] VARIANTARG * as_args, [ in, out ] VARIAN-TARG * as_class, [ in, out ] VARIANTARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This function is nearly identical to f_get_component_from_filter, except that it accepts the entityidentifier of a primary (ad_primary_entity_id) to further constrain the Result Set. Only components within the speci-fied primary (and matching the filter criteria if a stored filter is used) are retrieved. This is most useful when build-ing a pick list for resolving references - certain references can only point to an entity in the same primary (e.g.,Chapter).

Input Parameters

Name Type Definitionad_filter_id Double Unique filter number issued by Vasont when filter is created, saved

and named. Can be equal to 0. If passed as 0, all components (ofspecified type) in collection are retrieved.

ad_prod_id Double Collection identifier from which components are retrieved

ad_primary_entity_id Double Primary entity identifier containing desired components

ad_rule_relation_id Double Component type identifier - Only components of this type are re-trieved from collection

as_args String Array Array of arguments to use with filter, (if one is specified). Filterscan take any number of arguments, depending on number of filtercriteria. Array of arguments must match up to filter criteria bycount and order.

as_class String Reference argument for class of component


See API function f_get_component_from_filter.

f_get_component_processing_optionsHRESULT f_get_component_processing_options( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ]BSTR as_event, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set of the processing options, associated with a specific Vasont editview event (as_event), that are applied to a specific component (ad_rule_relation_id) within a given collection(ad_prod_id).

Input Parameters

Name Type Definitionad_prod_id Double Collection identifier for which processing options are retrieved

ad_rule_relation_id Double Component type identifier for which processing options are re-trieved



Name Type Definitionas_event String Vasont edit view event, as defined in Vasont Administrator, for

which processing options are retrieved (e.g., approve_post,clone_post, navigator_display, navigator_popup, etc.)

Output Parameters


Double custom_rule_use_id (custom rule use identifier used to obtain for-mal processing option arguments)

Double prod_id (collection identifier - will always conform to ad_prod_idinput parameter)

Double rule_relation_id (component type identifier - will always conformto ad_rule_relation_id input parameter)

Double custom_rule_id (unique identifier assigned to processing option)

String use (event for processing option - will always conform to as_eventinput parameter)

Double seq_no (sequence in which processing options are processed)

String text_argument (optional text argument(s) for processing option)

String custom_rule_name (processing option name)

f_get_components_from_findHRESULT f_get_components_from_find( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ] double ad_enti-ty_id, [ in ] VARIANTARG * as_args, [ in, out ] VARIANTARG * as_hier_key, [ in, out ] VARIANTARG * as_er-ror_msg, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the components in a primary that match specific find cri-teria. A stored find (identified by ad_filter_id) and associated find criteria values (as_args) is used to retrieve thelist of “found” components in the primary. The primary in which the find is to be performed is automatically derivedfrom ad_entity_id, which contains the entity identifier for a component currently selected in the client's applicationNavigator (find operations are performed in the context of a Navigator).

Input Parameters

Name Type Definitionad_filter_id Double Unique filter number issued by Vasont when stored find is created,

saved and named

ad_prod_id Double Collection identifier for which components are found

ad_entity_id Double Identifies component for currently selected component in Naviga-tor in which find is used

as_args String Array Array of arguments to use with find. Finds can take any number ofarguments, depending on number of find criteria. Array of argu-ments must match up to find criteria by count and order.



Name Type Definitionas_hier_key String Reference argument for hierarchy key of current component in

Navigator


Output Parameters

Name Type Definitionas_hier_key String Returns Vasont hierarchy key for passed component identifier

(ad_entity_id). (See first NOTE below).


retval Result Set Resultset containing following columns for each component:

String component_type (component's name (e.g., “Author[Chapter]”))

String component_desc (component's description)

String parent_desc (parent component's description). Will be empty ifcomponent is child of primary.

String primary_desc (primary component's description). Will be uniformfor all rows in resultset.

String entity_status_flag (component's current status) - Values: a (ap-proved); d (draft); i (incomplete).




String pending_flag (indicator of component's pending actions): Values:n (none); d (deleted); a (added); c (changed).

Date create_date (date component was created)








Double parent_rule_relation_id (parent's type identifier)

Double primary_seq_no (sequence number, from primary, for ordering).Will be uniform for all rows in resultset.

String hier_key (Vasont hierarchy key for component - See first NOTEbelow).

Double sequence (sequential counter indicating order in which found com-ponents would be listed in Navigator (tree))

Double rule_relation_id

Double raw_id



Name Type Definition String mm_description

String mm_status_flag

String mm_pathname

String file_extension

See Usage section of f_get_entity_hier_key for discussion on Vasont hierarchy keys.

2 The Find API functions are normally used in conjunction with a Navigator (tree-like representation ofthe Content) in the API's client application. This f_get_components_from_find function providesthe capability to find components within a particular primary contained in the Navigator. Using theResult Set from this function, along with the Hierarchy Key for the component passed to this function(as_hier_key), the client application can locate components in relation to the current point in theNavigator and move to those components.

f_get_components_from_find_stringHRESULT f_get_components_from_find_string( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ] doublead_entity_id, [ in ] BSTR as_args, [ in, out ] VARIANTARG * as_hier_key, [ in, out ] VARIANTARG * as_er-ror_msg, [out, retval] LPDISPATCH * retval );

Description: This “stub” function is another variant of the “f_get_components_from_find” function that substitutesa delimited string for the array of Filter arguments. This stub is used by the Vasont Universal Integrator (VUI),which has problems properly typing a string array for use with the Filters. This function takes a delimited string(delimited with a pipe (“|”)), builds an array off of the delimited string and passes the arguments on to: f_get_com-ponents_from_find( )

Input Parameters

Name Type Definitionad_filter_id Double Stored Find ID

ad_prod_id Double Collection in which Find is being performed

ad_Entity_ID Double Component currently selected in Navigator


as_hier_key String REF STRING with Hierarchy Key for current Component


Output Parameters

Name Type Definitionas_hier_key String Returns Vasont hierarchy key for passed component identifier

(ad_entity_id). (See first NOTE below).


retval Result Set Resultset containing following columns for each component:




Name Type Definition String component_desc (component's description)

String parent_desc (parent component's description). Will be empty ifcomponent is child of primary.

String primary_desc (primary component's description). Will be uniformfor all rows in resultset.

String entity_status_flag (component's current status) - Values: a (ap-proved); d (draft); i (incomplete).




String pending_flag (indicator of component's pending actions): Values:n (none); d (deleted); a (added); c (changed).

Date create_date (date component was created)









Double primary_seq_no (sequence number, from primary, for ordering).Will be uniform for all rows in resultset.

String hier_key (Vasont hierarchy key for component - See first NOTEbelow).

Double sequence (sequential counter indicating order in which found com-ponents would be listed in Navigator (tree))


Double raw_id

String mm_description

String mm_status_flag

String mm_pathname

String file_extension

f_get_composite_extract_filenameHRESULT f_get_composite_extract_filename( [ in ] double ad_prod_id, [ in ] double ad_version_id, [ in ] doublead_entity_id, [out, retval] BSTR * retval );

Description: This function returns the filename, including path, for composite extracts. The filename is determinedone of two ways. First, a search is performed for a processing option with the event “comp_extract_file” (e.g. cli-



ent_key_filename, text_filename). If no option is found, the Vasont ini file is read. The value for the entry “Compo-siteFile” is used for the filename.

Assuming a filename is determined by either of the above two methods, a path is added. The path is determined bysearching the “CompositePath” entry in the Vasont ini file.

Input Parameters


ad_version_id Double Version identifier

ad_entity_id Double Entity identifier

Output Parameters

Name Type Definitionretval String File name

f_get_conref_attr_value_for_targetHRESULT f_get_conref_attr_value_for_target( [ in ] double ad_target_entity_id, [out, retval] BSTR * retval );

Description: This function generates the value, for a DITA Content Reference (conref) attribute, based on a particu-lar Vasont component that is designated as the Content Reference “target”. In DITA, the conref attribute provides amechanism for reuse of content fragments. The conref attribute stores a reference to another element and is pro-cessed to replace the referencing element with the referenced element.

Typically, this function is called after presenting a Cross-Collection Component Pick List—See thef_get_cross_prod_components API function.

Input Parameters

Name Type Definitionad_target_entity_id Double Vasont component identifier for the entity that is to be used as the

Content Reference (conref) “target”.

Output Parameters

Name Type Definitionretval String The value, based on the provided “target”, to be used for the conref

Attribute on the element that implements the Content Reference.

f_get_content_typesHRESULT f_get_content_types( [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set of the defined content type.



Input Parameters

None

Output Parameters


String subject_name (name of subject)

Double subject_id (subject identifier)

f_get_cross_prod_componentsHRESULT f_get_cross_prod_components( [ in ] VARIANTARG * ad_prod_ids, [ in ] double ad_raw_type_id,[ in ] double ad_exclude_entity_id, [ in ] double ad_filter_id, [ in ] VARIANTARG * as_args, [ in, out ] VARIAN-TARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing Collection components that reside in particular VasontCollection(s). The Collection components returned can optionally be constrained to components having a particularRaw Type and/or components that meet certain filter criteria. Typically, this function will be sued to find compo-nents across multiple Vasont Collections (a Cross-collecton Find) or to implement a Pick List for similar or relatedcontent (a Cross-Collection Component Pick List).

This function will typically utlize Vasont stored filters obtained using the f_get_filters_cross_prod API function.

Input Parameters

Name Type Definitionad_prod_ids Double An array of Collection IDs within which components are to reside

ad_raw_type_id Double Specify 0 (zero) for Cross-Collection Finds—In this case, a “mix” fCollection component types can be included in the resultset.

Specify a Raw Type identifier for Cross-Collection ComponentPick Lists—In this case, only collection components that have thespecified Raw Type will be included in the resultset.

ad_exclude_entity_id Double For a Cross-Collection Component Pick List, specify the identiferof the entity that should be excuded from the resultset. With PickLists, it is often useful to prevent the suer from cross-linking a giv-en entity (e.g., having an entity point to “itself” as a Variant)—Thisargument provides a mechanism for preventing these types of cy-clical references.

ad_filter_id Double Unique filter identifier (typically from f_get_filters_cross_prod)issued by Vasont when filter is created, saved and named. Can be 0(zero) if, and only if, the ad_raw_type_id argument is specified (inwhich case all the components having that Raw Type and residingin the specified Collection(s) are returned).

as_args String Array of arguments to use with filter (if one is specified). Filter cantake any number of arguments, depending on the number of filtercriteria. The array of arguments must match up to the filter criteriaby count and order.



Name Type Definitionas_error_msg String Reference argument in which any error messages are returned.

Output Parameters

Name Type Definitionretval Result Set Resultset, for collection components, containing the following col-

umns:

String prod_abbrev (collection in which component resides)

String entity_raw_desc (description of component)

String component_type (Collection component type (e.g., Chap-ter[Book]))










Double prod_id (collection identifier for Collection in which componentresides)





Usage: To implement a Cross-Collection find, call this function with the ad_raw_type_id argument set to 0 (zero),the ad_exclude_entity_id argument set to 0 (zero), ad_filter_id set to the identifier for a stored filter obtained fromf_get_filters_cross_prod, and the as_args array argument populated with the desired filter criteria values (conform-ing to the filter identified by ad_filter_id).

NOTE: When implementing a Cross-Collection Find (ad_raw_type_id set to 0), a stored filter must be used!

To implment a Cross-Collection Component Pick List (e.g., to provide a mechanism through which a user can pick aCollection component that has the same Raw type and optionally meets certain filter criteria), call this function withthe ad_raw_type_id argument set to the desired Raw Type identifier. Optionally, a given Vasont entity can be ex-cluded by setting the ad_exclude_entity_id argument. If a filter is to beused to further constraint the Pick List, callthe function with ad_filter_id set to the identifier for a stored filter obtained from f_get_filters_cross_prod, and theas_args array argument populated with the desired filter criteria values (conforming to the filter identified by ad_fil-ter_id). If no filter is to be used, set ad_filter_id to 0 (zero)—All components in the specified Collection(s), andhaving the specified Raw Type, will be returned in this case.



f_get_daemon_batchesHRESULT f_get_daemon_batches( [ in ] const BSTR as_daemon_id, [ in ] const VARIANT_BOOL ab_get_all,[out, retval] LPDISPATCH * retval );

Description: This function returns a resultset, of which the most important entry is a comma delimited string ofbatch queue ids for a particular daemon process id.

Input Parameters

Name Type Definitionas_daemon_id String Daemon id for which you'd like to get its batch queue ids

ab_get_all Boolean If true, returns all batches for all daemons

Output Parameters


Double DAEMON_BATCH_ID (row id of the record in the table)

String DAEMON_ID (daemon id of the daemon process)

String BATCH_IDS (comma delimited string of batch queue ids for thedaemon)

Datetime UPDATE_DATE (update date of the record in the table)

f_get_db_profilesHRESULT f_get_db_profiles( [ in, out ] VARIANTARG * as_current_profile, [out, retval] BSTR * retval );

Description: This function returns a list of all of the profiles in the VasontApps.ini.file.

Input Parameters

Name Type Definitionas_current_profile String Profile, from Vasont initialization file, currently in use

Output Parameters

Name Type Definitionas_current_profile String Returns profile, from Vasont initialization file, currently in use

retval String List of profiles

f_get_descendant_countHRESULT f_get_descendant_count( [ in ] double ad_entity_id, [out, retval] short * retval );

Description: This function returns the total number of descendants for the component.



Input Parameters


Output Parameters

Name Type Definitionretval Short Number of descendants that exist for specified entity

f_get_descendant_pointersHRESULT f_get_descendant_pointers( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the entity ids of descendat components that are of theRaw Pointer type.

Input Parameters


Output Parameters

Name Type Definitionretval Result Set Resultset containing following columns:


f_get_descendants_by_ruleHRESULT f_get_descendants_by_rule( [ in ] double ad_primary_entity_id, [ in ] double ad_rule_id, [out, retval]LPDISPATCH * retval );

Description: This function returns descendant components of a primary component of a particular rule_id (i.e.Alias). An example would be a book primary that contains Paragraphs within Chapters and Sections. The particularbook is identified by the ad_primary_entity_id. The rule_id is the rule_id of the Paragraph. This returns a separaterow in the resultset for each Paragraph with the book.

Input Parameters

Name Type Definitionad_primary_entity_id Double Identifies the primary component to search within

ad_rule_id Double Identifies the rule_id of the descendants to search for



Output Parameters




Double raw_id (component's raw data identifier)

Double entity_seq_no (entity sequence number)

String entity_status_flag (status of entity when shadowed)

Datetime entity_status_date (date entity placed in status reflected in enti-ty_status_flag)

String entity_username (user who made changes causing shadow)



Double raw_inline_id (raw inline identifier)


String pending_flag (pending flag)

Datetime create_date (date entity created)



f_get_dw_prod_rule_relationsHRESULT f_get_dw_prod_rule_relations( [ in ] double ad_prod_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the rule_relation_ids of components that are in the Col-lection. (based on the prod_id passed in.)

Input Parameters


Output Parameters




Double track

Double perform_extract

Double process_children

Double version_id



f_get_email_addressHRESULT f_get_email_address( [ in ] BSTR as_username, [out, retval] BSTR * retval );

Description: This function gets the associated email address for a specified user.

Input Parameters

Name Type Definitionas_username String Identifies user

Output Parameters

Name Type Definitionretval String Email address, or blank if none exists

f_get_entities_from_prim_rrHRESULT f_get_entities_from_prim_rr( [ in ] double ad_prim_entity_id, [ in ] double ad_rule_relation_id, [out, re-tval] LPDISPATCH * retval );

Description: This function returns descendant components of a primary component of a particular rule_relation_id.An example would be a book primary that contains Paragraphs within Sections. The particular book is identified bythe ad_primary_entity_id. The rule_relation_id argument is the identifier of the Paragraph within Section. This re-turns a separate row in the resultset for each Paragraph within a Section in the specified book.

Input Parameters

Name Type Definitionad_primary_entity_id Double Identifies the primary component to search within.

ad_rule_relation_id Double Identifies the rule_relation_id of the descendants to search for.

Output Parameters



Double rule_relation_id (component's type identifier


Double entity_seq_no_ (entity sequence number)



String entity_username (entity user name)





Name Type Definition Double raw_inline_id (inline data identifier)



Datetime create_date (entity create date)


f_get_entity_ancestryHRESULT f_get_entity_ancestry( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing all of the ancestors for the component.

Input Parameters


Output Parameters






f_get_entity_childrenHRESULT f_get_entity_children( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function returns information on the children of a specified entity. It returns one row for each childin the entire hierarchy under the parent.

Input Parameters


Output Parameters






Name Type Definition Double raw_id (raw data identifier)

Double primary_seq_no (sequence number for ordering primary)






Double raw_inline_id




Decimal nav_order


Example: In the following example, if a user asks for children for Steps in the Baked Fish Loaf recipe, seven rowsare returned in the Result Set, one for each Step. However, if a user asks for children of Baked Fish Loaf, theseseven, plus many others are returned, i.e., the entire hierarchy below the primary component for this recipe.

f_get_entity_children_detailsHRESULT f_get_entity_children_details( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing detailed information for the children of the specifiedcomponent.

Input Parameters




Output Parameters








String entity_username (entity user name)









String username (user name)

String hier_key

Datetime check_out_date

String raw_description (description of component)

Double global_count: 0=entity_id does not have a record in the Glob-al_Change_Log table; 1=entity_id has a record in the Glob-al_Change_Log table


f_get_entity_countHRESULT f_get_entity_count( [ in ] double ad_prod_id, [out, retval] long * retval );

Description: This function returns the number of entities that exist for the specified collection.

Input Parameters


Output Parameters

Name Type Definitionretval Long Number of entities that exist for specified collection



f_get_entity_hier_keyHRESULT f_get_entity_hier_key( [ in ] double ad_prod_id, [ in ] double ad_entity_id, [out, retval] BSTR * retval );

Description: This function returns the Vasont “hierarchy key” for a component in a collection. The hierarchy key isa sortable string that reflects the component's position within a primary, taking into account its ancestry, Navigatororder and sequence under its parent. When included in a simple list or resultset containing collection components,sorting on the hierarchy key presents the components in the order in which they would appear in a Vasont Navigator“tree”. By comparing the hierarchy key of components in a primary, client applications can also determine whetherother components precede, follow, are ancestors of, or are descendants of a given component. See the Usage sectionthat follows for an illustration of these concepts.

Input Parameters


ad_entity_id Double Entity identifier for component

Output Parameters

Name Type Definitionretval String Vasont hierarchy key for component

Usage: The Find API function (see f_get_components_from_find) returns a sorted Result Set with each componentin a primary matching the find criteria. These resultsets also include the hierarchy key for each component. Usingthe f_get_entity_hier_key function for any component in the same primary, comparisons can be performed againsta find resultset to determine how a found component relates to the “current” component. To illustrate this point,consider the following Vasont Navigator:

Suppose that f_get_components_from_find was called from within this primary using a stored find that locates“All Draft Components”. The resultset returned from f_get_component_from_find, in this case, would include(among other columns):

Usage

entity_id hier_key1934 0001,0001



1936 0001,0001:0002,00011941 0001,0001:0003,0002:0001,00021948 0001,0001:0003,0003:0002,0002:0001,00021949 0001,0001:0003,0003:0002,0002:0001,00031958 0001,0001:0003,0004:0001,00011973 0001,0001:0005,0004

This resultset represents the seven “Draft Components” shown in the Navigator illustration. Since the resultset issorted by the hierarchy key, it also accurately reflects the order in which the components would fall in a Navigator(tree). Note the highlighted component in the Navigator illustration - Calling f_get_entity_hier_key for this compo-nent would provide the hierarchy key:

0001,0001:0003,0003

By performing an ASCII string comparison between this hierarchy key to those in the find resultset, a client applica-tion can determine that:

1. The components with entity IDs 1934, 1936 and 1941 precede the component:

• 0001,0001 (1934) is less than 0001,0001:0003,0003

• 0001,0001:0002,0001 (1936) is less than 0001,0001:0003,0003

• 0001,0001:0003,0002:0001,0002 (1941) is less than 0001,0001:0003,0003

2. The component with entity ID 1934 is an ancestor of the component:

• 0001,0001 (1934) matches the first portion of the key 0001,0001:0003,0003

3. The components with entity IDs 1948 and 1949 are descendants of the component:

• 0001,0001:0003,0003:0002,0002:0001,0002 (1948) begins with 0001,0001:0003,0003

• 0001,0001:0003,0003:0002,0002:0001,0003 (1949) begins with 0001,0001:0003,0003

4. The components with entity IDs 1958 and 1973 follow, but are not descendants of, the component:

• 0001,0001:0003,0004:0001,0001 (1958) is greater than, but does not start with, 0001,0001:0003,0003

• 0001,0001:0005,0004 (1973) is greater than, but does not start with, 0001,0001:0003,0003

When implementing a Navigator and find capability in a client application, these techniques can be used to locate“found” components in relation to the current component in the Navigator and move to the found component.

f_get_entity_previewHRESULT f_get_entity_preview( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_filename, [ in, out ]VARIANTARG * ad_preview_id, [ in, out ] VARIANTARG * ad_root_entity_id, [ in, out ] VARIANTARG *as_information, [ in, out ] VARIANTARG * as_error_message, [out, retval] double * retval );

Description: The purpose of this method is to find and return preview data for a component. The preview may berelated directly to the component or may be related to an ancestor of the component.

Input Parameters

Name Type Definitionad_entity_id Double Entity_id of the component being previewed

as_filename String (by ref-erence)

Required argument that identifies the filename. If a path name isnot included then the path will be determined from the TempPath



Name Type Definitionsetting in the vasontapps.ini. If no extension is placed on this argu-ment then an extension of .tar will be added. This argument ispassed by reference, which means any changes made to the file-name will be available to the calling program.

ad_preview_id Double (byreference)

Identifies the preview that is configured in Administrator. If thisvalue is passed in, the logic will only search for that specific pre-view type. If this is not passed, then the default preview will besearched for and if found this argument will be populated with thatpreview id.

ad_root_entity_id Double (byreference)

Root entity_id associated with the preview. This may be the sameas ad_entity_id or an ancestor of that value.

as_information String (by ref-erence)

Holds relevant information. Examples of information include:

Preview as of 4/30/2013 11:41:27

Preview needs to be refreshed. Last preview generated 8/21/201215:11:48


Holds error information. Examples include:

A preview has never been created

Preview feature is not enabled for this component.

Output Parameters

Name Type Definitionas_error_msg String Reason redirect failed


−1=failure

Example: Use within the VUI to show preview images for components. This method may be used in conjunctionwith f_get_preview_ancestor, which will help determine whegther the selected component requires this function tobe called.

f_get_entity_status_dateHRESULT f_get_entity_status_date( [ in ] double ad_entity_id, [out, retval] DATE * retval );

Description: This function returns the specified entity status date.

Input Parameters

Name Type Definitionad_entity_id Double Specific entity identifier

Output Parameters

Name Type Definitionretval Date Entity status date



f_get_filter_definitionHRESULT f_get_filter_definition( [ in ] double ad_prod_id, [ in ] double ad_filter_id, [ in, out ] VARIANTARG *as_name, [ in, out ] VARIANTARG * as_description, [ in, out ] VARIANTARG * as_error_msg, [out, retval]LPDISPATCH * retval );

Description: This function returns a Result Set containing the filter criteria entries for a stored filter. The storedfilter's name and description are also returned as reference arguments. For each filter criteria entry in the result set,the f_get_valid_filter_values API call can be used to build a drop-down list of allowable values.

2 If the stored filter contains filter criteria that is not appropriate for the specified collection (e.g., refer-ences a component that is not used in the collection's setup), a pertinent error message is returned inthe as_error_msg reference argument.

Input Parameters

Name Type Definitionad_prod_id Double Collection identifier for which stored filter is used - If retrieving

filter definition for raw material, set to 0.

ad_filter_id Double Unique filter number issued by Vasont when filter is created, savedand named. Can be equal to 0. If passed as 0, all components (ofspecified type) in collection are retrieved.

as_name String Reference argument for stored filter's name

as_description String Reference argument for stored filter's description


Output Parameters

Name Type Definitionas_name String Name assigned to stored filter

as_description String Description assigned to stored filter


retval Result Set Resultset containing following columns:

String and_or (defines join method to preceding criteria) - Values: ANDor OR

String left_paren (optional left parenthesis for start of criteria group)

String component_text (textual description of criteria's component). Canbe used to build plain English description of Criteria

String property_text (textual description of criteria's property). Can beused to build plain English description of Criteria.

String operator_text (textual description of criteria's operator). Can beused to build plain English description of Criteria

String value_text (textual description of criteria's value). Can be used tobuild plain English description of criteria



Name Type Definition String right_paren (optional right parenthesis for start of criteria group)

String api_mode (defines how criteria's value should be handled) - Val-ues: locked (value from stored filter cannot be changed); defaulted(value is defaulted, but can be changed); empty (value is shown asempty and must be entered)

String api_instructions (Plain English instructions for entering criteria)

Double component_id (identifier for criteria's component - 999 is specialidentifier for “All” components). Use in f_get_valid_filter_valuesto get list of values for criteria (if any)

String component_type (defines criteria component's type) - Values: rule(component_id is rule identifier); rule_relation (component_id isa component type identifier); raw_type (component_id is a rawcomponent type identifier). Use in f_get_valid_filter_values to getlist of values for criteria (if any).

String property (internal representation of criteria's property). Use inf_get_valid_filter_values to get list of values for criteria (if any).

String operator (internal representation of criteria's operator)

String value (internal representation of criteria's value)

String data_type (data type of criteria's value) - Values: CHAR; DATE/DATETIME; DECIMAL; NUMBER. Can be used to build for-matting Masks when collecting criteria values.

Double limiting_mode (internal use only...)

Double limiting_id (internal use only...)

String db_column (internal use only...)

Double paren_level (internal use only...)

Double group_num (internal use only...)

String display_statement (internal use only...)

f_get_filters_cross_prodHRESULT f_get_filters_cross_prod( [ in ] double ad_raw_type_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the stored filters in Vasont that are used for either Cross-Collection Finds (where the filter criteria can be for any component tracked in Vasont) or Cross-Collection Compo-nent Pick Lists (where the filter criteria can only be for collection components that have a particular Raw Type).Only the filters that were created by the user, or flagged as shared by another user, are returned. Additionally, onlyfilters that have been flagged for use with the API are retrieved.

This function can be used, in conjunction with the f_get_cross_prod_components API function, to obtain a list ofcomponents from any collection.

NOTE: If only the stored filters created by the current user are desired (and shared filters, created by a differentuser, are not to be shown), the API's client application can utilize the ADO Recordset Filter property to hide thestored filters created by another user.



Input Parameters

Name Type Definitionad_raw_type_id Double Specify 0 (zero) to obtain stord filters that were created from Vaso-

nt's Collections toolbar option (Cross-Collection Finds). Otherwise,specify a valid Raw component type identifier to obtain the storedfilters that were created from a Cross-Collection Component PickList (e.g., Variants or conref Pick List).

Output Parameters


Double filter_id (unique identifier assigned to stored filter)

String filter_name (name assigned to stored filter)

String username (user who created stored filter)

String shared (indicates whether stored filter can be shared by other users)

Date create_date (date stored filter was created)

Double prod_id (collection identifier for which stored filter was created).Will always be 999 for Cross-Collection filters, meaning the Filtercan be used with any Collection(s).

String prod_abbrev (collection name for which stored filter was created).Will always be NULL for Cross-Collection Filters.

Double component_id (component for which stored filter was created).Will always match ad_raw_type_id provided in input parameter.

String comments (description assigned to stored filter). May be NULL, ifno description was provided when the stored filter was created.

String api_enabled (Internal Use: Will always contain y)

String filter_class (Internal Use: Will always contain w_r_filter_collec-tions)

String default_filter (Internal Use: Indicates whether this is the defaultCross-Collection Filter for the creating user)

String mru_filter (Internal Use: Will always contain n)

Double last_row_count (Internal Use: Will always contain 0 or NULL)

Usage: To implement a Cross-Collection Find, call this function with the ad_raw_type_id argument set to 0 (zero)—The stored filters returned will be those created from Vasont's Collections toolbar option (Cross-Collection Finds).One of the returned filters can then be used with the f_get_cross_prod_components API function to generate a list ofthe Cross-Collection Find results.

To implement a Cross-Collection Component Pick List (e.g., to provide a mechanism through which a user can picka Collection component that has the same Raw Type and optionally meets certain filter criteria), call this functionwith the ad_raw_type_id argument set to the desired Raw Type identifier—The stored filters returned will be thosecreated from a Vasont Cross-Collection Component Pick List (e.g., Variants or conref Pick List). One of the re-turned filters can then be used with the f_get_cross_prod_components API function to generate a list for the Cross-Collection Component Pick List.



f_get_filters_findHRESULT f_get_filters_find( [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the stored finds (a special implementation of the storedfilters) in Vasont. Only the “finds” that were created by the current user, or flagged as shared by another user, arereturned. Additionally, only finds that have been flagged for use with the API are retrieved.

2 If only the stored finds created by the current user are desired (and shared finds, created by a differentuser, are not to be shown), the API's client application can utilize the ADO Recordset Filter propertyto hide the stored finds created by another user.

By default, the stored finds for all collections will be retrieved (often, stored finds can be used inmany collections, depending on the Vasont setup). If only the stored finds for a particular collectionare desired, the API's client application can use the ADO Recordset Filter property to limit the list toa particular collection.

Input Parameters

None

Output Parameters







Double prod_id (collection identifier for which stored filter was created)

String prod_abbrev (collection name for which stored filter was created)

Double component_id (component for which stored filter was created).Older Filters are set to 0, but may still be used.

String comments (description assigned to stored filter)


String filter_class (Internal Use: Will always contain w_r_filter_prod)

String default_filter (Internal Use: Indicates whether this is the defaultstored find for the Collection and creating user)


Double last_row_count (Internal Use: If a value is present, indicates thenumber of “hits” that were obtained the last time the stored findwas executed as filter (keep in mind that stored filters and storedfinds are interchangeable))



f_get_filters_find_for_prodHRESULT f_get_filters_find_for_prod( [ in ] double ad_prod_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the stored finds in Vasont for a particular collection. On-ly the filters that were created by the current user, or flagged as shared by another user, are returned. Additionally,only filters that have been flagged for use with the API are retrieved.

2 If only the stored filters created by the current user are desired (and shared filters, created by a differ-ent user, are not to be shown), the API's client application can utilize the ADO Recordset Filterprop-erty to hide the stored filters created by another user.

By default, stored filters for the specified collection component are retrieved regardless of the collec-tion (often, stored filters can be used in many collections, depending on the Vasont setup). If only thestored filters for a particular collection are desired, the API's client application can utilize the ADORecordset Filter property to hide the stored filters created for other collections.

Input Parameters

Name Type Definitionad_prod_id Double Identifier of collection against which filter is performed

Output Parameters













String default_filter

String mru_filter

Double last_row_count



f_get_filters_prodHRESULT f_get_filters_prod( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] LPDIS-PATCH * retval );

Description: This function returns a Result Set containing the stored filters in Vasont for a particular collectioncomponent. Only the filters that were created by the current user, or flagged as shared by another user, are returned.Additionally, only filters that have been flagged for use with the API are retrieved.

2 If only the stored filters created by the current user are desired (and shared filters, created by a differ-ent user, are not to be shown), the API's client application can utilize the ADO Recordset Filter prop-erty to hide the stored filters created by another user.

By default, stored filters for the specified collection component are retrieved regardless of the collec-tion (often, stored filters can be used in many collections, depending on the Vasont setup). If only thestored filters for a particular collection are desired, the API's client application can utilize the ADORecordset Filter property to hide the stored filters created for other collections.

Input Parameters

Name Type Definitionad_prod_id Double Identifier of collection against which filter is performed

ad_rule_relation_id Double Collection component type identifier

Output Parameters













String default_filter (Internal Use: Indicates whether this is the defaultstored filter for the Collection and creating user)


Double last_row_count (Internal Use: If a value is present, indicates thenumber of “hits” that were obtained the last time the stored filter



Name Type Definitionwas excecuted “as is” (with no changes applied to the filter crite-ria)

f_get_filters_rawHRESULT f_get_filters_raw( [ in ] double ad_raw_type_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing the stored filters in Vasont for a particular raw compo-nent. Only the filters that were created by the current user, or flagged as shared by another user, are returned. Addi-tionally, only filters that have been flagged for use with the API are retrieved.

2 If only the stored filters created by the current user are desired (and shared filters, created by a differ-ent user, are not to be shown), the API's client application can utilize the ADO Recordset Filter prop-erty to hide the stored filters created by another user.

Input Parameters

Name Type Definitionad_raw_type_id Double Raw component type identifier

Output Parameters













String default_filter (Internal Use: Indicates whether this is the defaultstored filter for the Raw Type and creating user)


Double last_row_count (Internal Use: If a value is present, indicates thenumber of “hits” that were obtained the last time the stored filterwas executed “as is” (with no changes applied to the filter criteria)



f_get_global_change_candidatesHRESULT f_get_global_change_candidates( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ] dou-ble ad_entity_id, [ in ] double ad_old_raw_id, [ in ] double ad_new_raw_id, [out, retval] LPDISPATCH * retval );

Description: This function obtains a list of other components that may be affected by the update of the raw text.

Input Parameters

Name Type Definitionad_prod_id Double Collection identifier for project in which component was changed

ad_rule_relation_id Double Type identifier of component that was changed

ad_entity_id Double Entity identifier of component that was changed

ad_old_raw_id Double Raw material identifier for component that was changed

ad_new_raw_id Double Raw material identifier for component after change to raw text

Output Parameters















Double raw_id (component's raw data identifier)




String edit_flag (flag indicating if component should be automatically up-dated) - Values: y (Yes); n (No); p (Pick)



f_get_global_clone_candidatesHRESULT f_get_global_clone_candidates( [ in ] double ad_entity_id, [ in ] double ad_custom_rule_use_id, [out,retval] LPDISPATCH * retval );

Description: This function returns a resultset of global clone candidate entities.

Input Parameters

Name Type Definitionad_entity_id Double Changed component entity id

ad_custom_rule_use_id Double Processing option identifier from which collection argument is re-trieved

Output Parameters


prod_abbrev String collection abbreviation

primary_raw_desc String primary raw description

parent_raw_desc String parent raw description

component_type String component type

entity_status_flag String status flag

entity_status_date Datetime edit date

entity_username String user name

client_key String Client key

username String checkout user name

check_out_date Datetime checkout date

entity_id Double

prod_id Double

rule_relation_id Double

primary_entity_id Double

parent_entity_id Double

parent_rule_relation_id Double

f_get_help_directoryHRESULT f_get_help_directory( [out, retval] BSTR * retval );

Description: The purpose of this method is to return a string value with the directory that holds Vasont Help files. Itwill be used in <oXygen/> to find the Collaborative Review help file.



Input Parameters

None

Output Parameters

Name Type Definitionretval String Path to Vasont Help files

Example:

C:\Vasont\Help\

f_get_href_attr_value_for_targetHRESULT f_get_href_attr_value_for_target( [ in ] double ad_pointer_primary_entity_id, [ in ] double ad_target_en-tity_id, [out, retval] BSTR * retval );

Description: The purpose of this method is to be able to fill out an href attribute used within DITA. The href attrib-ute is used by DITA to specify a target element that is pointed to. For example, in DITA the cross reference tag(xref) has an href attribute that determines what the cross reference points to. The arguments to this function willidentify the primary of the pointer and the Vasont component that is the target of the pointer.

Input Parameters

Name Type Definitionad_pointer_primary_entity_id Double Identifies the primary component that the pointer is within.

ad_target_entity_id Double Specifies the target component that will be pointed to.

Output Parameters

Name Type Definitionretval String This is the value that will be placed in the href attribute.

f_get_image_search_namesHRESULT f_get_image_search_names( [ in ] double ad_entity_id, [ in ] double ad_extract_id, [ in ] VAR-IANT_BOOL ab_reuse_only, [out, retval] LPDISPATCH * retval );

Description: This function, used in conjunction with Vasont's image_search Processing Option (used on ExtractViews), returns a unique list of Graphic Names that can be used within an extracted XML document.

In the “Image Search” concept, Graphics are referenced in XML void of any format (or file extension) information -It is up to Vasont to figure out what Graphic format(s) to pull during Extract. The Graphics to pull may be located ina generic, “reusable” graphics Collection or a “project-specific” graphics Collection (containing graphics that arespecific to a publication or project, and are not “resuable” by nature). This API function fits in with this concept,allowing a Graphic Name (void of format/extension) to be picked from the list of Graphics available in the reuseand/or project-specific Collection.



Input Parameters

Name Type Definitionad_entity_id Double Entity ID of top-most Extracted Component

ad_extract_id Double Version ID for Extract View used

ad_reuse_only Boolean Indicates whether Graphic Names should be obtained from reuseCollection or the product/project specific Collection(s) (FALSE)

Output Parameters


String Graphic Name (void of format/extension)

f_get_incomplete_descendantsHRESULT f_get_incomplete_descendants( [ in ] double ad_prod_id, [ in ] double ad_parent_entity_id, [ in, out ]VARIANTARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing a list of incomplete descendants of a collection compo-nent. It is normally used in a Navigator (or other tree-like content structure), allowing the incomplete descendants tobe located in the tree.

Input Parameters

Name Type Definitionad_prod_id Double Collection identifier in which incomplete descendants are to be

found

ad_parent_entity_id Double Component identifier of ancestor, under which all incomplete de-scendants are to be found


Output Parameters

Name Type Definitionas_error_msg String Entity identifier


Double entity_id (incomplete component's entity identifier)


String hier_key (Vasont hierarchy key for incomplete component - seeNOTE below).

NOTE: See Usage section of f_get_entity_hier_key for a discussion on Vasont hierarchy keys.



f_get_ini_settingHRESULT f_get_ini_setting( [ in ] BSTR as_section, [ in ] BSTR as_key, [ in ] BSTR as_default, [out, retval]BSTR * retval );

Description: This function looks up a particular setting in the VasontApps.ini.file (e.g., Extract Directory, DatabaseConnection Parameters, etc.) before the connection is established.

Input Parameters

Name Type Definitionas_section String VasontApps.ini file section for setting

as_key String VasontApps.ini file key (within section) for setting

as_default String Default setting to be used if section and/or key not found in Vaso-ntApps.ini file

Output Parameters

Name Type Definitionretval String Result found in VasontApps.ini file

2 Unlike most other API functions, this function can be called prior to establishing a Vasont databaseconnection (using f_connect_to_database or f_connect_using_ini).

f_get_mm_dataHRESULT f_get_mm_data( [ in ] double ad_raw_id, [ in, out ] VARIANTARG * as_description, [ in, out ] VAR-IANTARG * as_external_filename, [ in, out ] VARIANTARG * as_blob_extension, [out, retval] short * retval );

Description: This function returns the multimedia information associated with a specific raw_id.

Input Parameters

Name Type Definitionad_raw_id Double Raw material identifier

as_description String Description of multimedia component - required

as_external_filename String Multimedia component filename field that references an externalfile. Optional: leave empty if none.

as_blob_extension String File extension related to BLOB being stored in database. Ifas_blob_filename is specified with an extension, it is used for thisfield.

Output Parameters

Name Type Definitionas_description String Value can be changed by function



Name Type Definitionas_external_filename String Value can be changed by function

as_blob_extension String Value can be changed by function

retval Short 1=success; −1=could not find multimedia record associated withpassed raw_id.

f_get_modular_pointeesHRESULT f_get_modular_pointees( [ in ] double ad_entity_id, [ in ] VARIANT_BOOL ab_recurse, [out, retval]LPDISPATCH * retval );

Description: This function returns a Result Set which lists the modular content components that are referenced fromwithin (are descendants of) the provided component (ad_entity_id parameter). The function can all recurse to followall modular content references, across all modular content collections, based on the value of the ab_recurse parame-ter.

Example: Consider a Chapter component that contains three (3) Sectionref descendant components, to modular Sec-tion content in another collection, and each Section contains an additional Imageref (to Image content in a 3rd mod-ular content collection). Calling this function with the Entity ID of the Chapter component and ab_recurse set tofalse will return only the Section components (directly referenced from within the Chapter component). The samecame with ab_recurse set to true, however, will return the three (3) Section components that are referenced directlyand the three (3) Image components that are referenced indirectly.

Input Parameters

Name Type Definitionad_entity_id Double Identifies the component for which modular content pointees are to

be found.

ab_recurse Double Indicates whether only modular content pointees directly refer-enced should be found (false) or whether all directly and indirectlyreferenced pointees should be returned (true).

Output Parameters

Name Type DefinitionRetval Result Set Resultset containing following data:




f_get_nav_orderHRESULT f_get_nav_order( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] short * retval );

Description: This function returns the Navigator order for the component type.



Input Parameters



Output Parameters

Name Type Definitionretval Short Navigator order

f_get_navigator_nameHRESULT f_get_navigator_name( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] BSTR *retval );

Description: This function retrieves the text shown on the Vasont Navigator window for each component.

Input Parameters



Output Parameters

Name Type Definitionretval String Navigator name

f_get_navigator_name_fullHRESULT f_get_navigator_name_full( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval]BSTR * retval );

Description: This function retrieves the Navigator Name for a specific component type. This is similar tof_get_navigator_name. The difference is that the parent component is also displayed. For example, the result of atitle component that is a child of chapter would be: title [chapter]. For primary components the value would be thenavigator name in brackets, such as [book].

Input Parameters





Output Parameters

Name Type Definitionretval String Navigator name

f_get_ownership_groupsHRESULT f_get_ownership_groups( [ in ] BSTR as_username, [out, retval] LPDISPATCH * retval );

Description: This function will return a result set list of Ownership Groups related to the username that is passed asan input parameter.

Input Parameters

Name Type Definitionas_username String The username whose list of Ownership Groups will be returned.

Output Parameters

Name Type Definitiongroup_id Double Identifying value for the ownership group.

group_name String The name of the ownership group.

f_get_parent_entityHRESULT f_get_parent_entity( [ in ] double ad_child_entity_id, [out, retval] double * retval );

Description: This function returns the entity id for the parent component.

Input Parameters

Name Type Definitionad_child_entity_id Double Child entity identifier

Output Parameters

Name Type Definitionretval Double Parent entity identifier

f_get_picklist_extract_infoHRESULT f_get_picklist_extract_info( [ in, out ] VARIANTARG * ad_extract_id, [ in ] BSTR as_parent_tags,[ in ] BSTR as_child_tag, [ in, out ] VARIANTARG * ad_prod_id, [ in, out ] VARIANTARG * ad_rule_relation_id,[ in, out ] VARIANTARG * ad_raw_type_id, [out, retval] double * retval );

Description: This function is used by external Editors (XMetaL, Arbortext Editor, FrameMaker, etc.) to determineif a Pick List is allowed for a particular Component. If so, the function returns the information needed to create an



appropriate Pick List in the external Editor. This function walks up the parent hierarchy, searching for a Ref Extractprocessing option.This function is similar to f_get_picklist_type_infoNote: This returns the extract_id that is found for a Ref Extract by referenceAn example of the as_parent_tags input parameter:"Greatgrandparent|Grandparent|Parent"

Input Parameters

Name Type Definitionad_extract_id Double Reference view in which to look for extract information

as_parent_tags String A pipe-delimited string of parent tags. This is the full hierarchy ofparents, all the way up to the root of the XML file you are workingwith.

as_child_tag String Tag assigned to component in XML instance

ad_prod_id Double Reference

ad_rule_relation_id Double Reference

ad_raw_type_id Double Reference

Output Parameters

Name Type Definitionretval Double Returns the raw_class_id of the component

ad_extract_id Double returned by Reference

ad_rule_relation_id Double returned by Reference

ad_raw_type_id Double returned by Reference

f_get_picklist_type_infoHRESULT f_get_picklist_type_info( [ in ] double ad_extract_id, [ in ] BSTR as_parent_tags, [ in ] BSTRas_child_tag, [ in, out ] VARIANTARG * ad_prod_id, [ in, out ] VARIANTARG * ad_rule_relation_id, [ in, out ]VARIANTARG * ad_raw_type_id, [out, retval] double * retval );Description: This function (typically used in an external XML Editor such as Arbortext Editor, FrameMaker orXMetaL) returns detailed information regarding a Vasont component type, based on a component tag, its parent's tagand a Vasont extract/load view identifier. The information returned by this function is typically used to determinewhat type of content is represented by the tag combination and implement a pick list for new content of that type.Vasont's embed_extract_info_pi processing option can be used to embed a Processing Instruction (PI), containingthe identifier for the selected extract view (version_id), in extracted XML Instances. After using the f_get_val-ue_from_extract_info_pi API function to obtain the extract view identifier from the PI (the “version_id” entry),this function can be used to obtain detailed component type information for any component in the instance.

2 This API call relies on an exact, case sensitive match for the tags (in the specified extract/load view).If the external application making the API call alters the tag names in any way (or if the tag nameshave been transformed using XSLT or another transformation engine), this API call will not be ableto find a match.



Input Parameters

Name Type Definitionad_extract_id Double Extract view in which to look for parent/child tag relationship

as_parent_tags String Tag assigned to parent of component in XML instance


ad_prod_id Double Reference argument for collection containing component

ad_rule_relation_id Double Reference argument for component type of component

ad_raw_type_id Double Reference argument for raw type of component

Output Parameters

Name Type Definitionad_prod_id Double Collection identifier of collection containing component

ad_rule_relation_id Double Component type identifier (rule_relation_id) for component

ad_raw_type_id Double Raw type identifier (raw_type_id) for component

retval Double Raw class identifier (raw_class_id) for component - Values: 1 -Pointer; 4 - Text; 5 - Multimedia

Usage

The Raw Class identifier (raw_class_id) returned from this function dictates how a pick list should be implemented(using the reference arguments) in the client application. For Raw Class 1 (Pointer components), a typical pick listimplementation would consist of:

1. Call the API function f_get_pointee_components (with ad_prod_idand ad_rule_relation_id) to determinethe collection/component type(s) that are valid pointer targets

2. Allow the user to select a target collection/component type

3. Optionally implement a filter selection using:

• f_get_filters_prod (passing the target collection/component type)

• f_get_filter_definition (in conjunction with f_get_valid_filter_values)

4. If the target component type is a primary component, call f_get_primary_from_filter (with optional filter cri-teria, if desired) to get resultset for the pick list; OR,

5. If the target component type must be in the same primary (same_primary=‘y’ in resultset from f_get_point-ee_components), call f_get_component_in_primary_from_filter (with optional filter criteria, if desired) toget resultset for the pick list; OTHERWISE,

6. Call f_get_component_from_filter (with optional filter criteria, if desired) to get resultset for the pick list

For Raw Class 4 (Text component) or 5 (Multimedia), a typical pick list implementation would consist of:

1. Optionally implement a Filter selection using:

• f_get_filters_raw (with ad_raw_type_id)

• f_get_filter_definition (in conjunction with f_get_valid_filter_values)

2. Call f_get_raw_component_from_filter (with ad_raw_type_id and, if desired, filter criteria) to get resultsetfor the pick list

Further implementation of the pick list (namely, what portions of the content to insert and where) vary depending onthe Vasont setup and the capabilities of the client application.



f_get_pointee_componentsHRESULT f_get_pointee_components( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval]LPDISPATCH * retval );

Description: This function is called for pointer components to determine the component(s) to which it can point.

Input Parameters



Output Parameters




Double pointee_prod_id (pointee collection identifier)

Double pointee_rule_relation_id (pointee component type identifier)

String same_primary (y/n value - pointer and destination components al-ways occur within same primary component)

String link_criteria (pointer client key field matches up with its destina-tion client key or raw text - values are “ck”-client key or “rt”-rawtext)

log_criteria String

work_group_id Double

gui_create String

for_modular_content String

f_get_pointee_entityHRESULT f_get_pointee_entity( [ in ] double ad_entity_id, [out, retval] double * retval );

Description: This function searches a pointer component for the entity_id to which it points.

Input Parameters

Name Type Definitionad_entity_id Double Identifies pointer component entity



Output Parameters

Name Type Definitionretval Double Pointed to entity_id

f_get_pointer_componentsHRESULT f_get_pointer_components( [ in ] double ad_prod_id, [ in ] double ad_rr_id, [out, retval] LPDISPATCH* retval );

Description: This function returns a list of valid pointers that can point to the passed in component rule_relation_id.

Input Parameters


ad_rr_id Double The rule_relation_id of the component that is pointed to. This isspecified on the edit view component in Vasont Administrator.

Output Parameters



Double parent_rule_id (parent rule identifier)


Double child_rule_id (child rule identifier)

String inline_flag (inline flag)

String inline_nested_view (inline nested view)

String inline_assignment (inline assignment)

Double raw_type_id (raw type identifier)

Double wrapper_id (wrapper identifier)

String begin_tag (being tag)

String end_tag (end tag)

Double raw_class_id (raw class identifier)

String sgml_validate (sgml validate)

String text_allowed (indicates if text allowed)

String pick_list (pick list)

String edit_flag (y/n field - can value be edited)

String resequence_flag (resequence flag)

String spell_check_flag (spell check flag)

String raw_default_flag (raw default flag)

String client_key_flag (client key flag)



Name Type Definition String client_key_text (text for client key)

Double editor_tag_id (editor tag identifier)


String editor_begin_tag (editor begin tag)

String editor_end_tag (editor end tag)

String source_table_name (source table name)



String match_criteria (match criteria)

String add_flag (add flag)

String delete_flag (delete flag)

String clone_flag (clone flag)

String expand_inlines (expand inlines)

String valid_value_flag (valid value flag)

String global_change_handle

String version_on_clone

String version_on_approval

String version_on_load

String version_on_update

String version_on_demand

String version_on_delete

Double global_change_work_group_id

f_get_preview_ancestorHRESULT f_get_preview_ancestor( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * ad_preview_id, [out,retval] double * retval );

Description: The purpose of this method is to determine the nearest ancestor component that has a preview config-ured. This does not interrogate whether an actual preview is built or up to date. It only looks at the setup for pre-views.

Input Parameters

Name Type Definitionad_entity_id Double Identifies component being previewed

ad_preview_id Double (byreference)

Identifies the preview that is configured in Administrator. If thisvalue is passed in, the logic will only search for that specific pre-view type. If this is not passed, then the default preview will besearched for and if found this argument will be populated with thatpreview id.



Output Parameters

Name Type Definitionretval Double Root entity_id in which the preview is defined. This may be the

same as ad_entity_id or an ancestor of that value. For example, ifad_entity_id is a paragraph component that is part of the preview ofa concept, then the return value would be for the ancestor concpetcomponent. A value of 0 will be returned if preview is not config-ured for this component or an ancestor of this component.

Example: Use when a user selects a new tree view item in the VUI. This function can be called to determine if thenewly selected tree view item is part of the same preview that is being displayed or whether the preview is different.

Note: This method may be used in conjuction with f_get_entity_preview, which will search for and return previewdata.

f_get_primaries_by_attributeHRESULT f_get_primaries_by_attribute( [ in ] BSTR as_username, [ in ] double ad_attribute_link_id, [ in ] BSTRas_attribute_value, [out, retval] LPDISPATCH * retval );

Description: This returns the list of matching primaries for all of the collections that a user has access to. The argu-ments are the Username, the Attribute Link ID, and the matching Attribute Value. Primaries in the collections thatthe user has acccess to for the entire system that have the attribute and value will be returned in a resultset.

Input Parameters

Name Type Definitionas_username String The login name of the user

ad_attribute_link_id Double The Attribute Link ID (attribute whose value must match)

as_attribute_value String The matching attribute value.

Output Parameters

Name Type Definitionretval Result Set Resultset containing following columns (based on component's

class):

Primary











Name Type Definition String username (user who has primary checked out)














Double global_count (count of records for this entity in the Global ChangeLog)

Double mod_log_count (count of records for this entity in the Pointer Log)

f_get_primaries_with_sequenceHRESULT f_get_primaries_with_sequence( [ in ] double ad_trgt_prod_id, [ in ] BSTR as_alphatag, [out, retval]LPDISPATCH * retval );

Description: This function returns the details for the destination collection.

Input Parameters

Name Type Definitionad_trgt_prod_id Double Identifies target collection

as_alphatag String Alpha tag assigned to primaries

Output Parameters



String text_key (contains first portion (e.g., first 30 characters) of textcomponent. Primary use is an index for efficiently querying textcontent).





f_get_primary_entityHRESULT f_get_primary_entity( [ in ] double ad_child_entity_id, [out, retval] double * retval );

Description: This function returns the primary entity identifier for the specified child entity.

In the previous example, if a child component is Steps, the Baked Fish Loaf displays as the primary for that child.Any component under Baked Fish Loaf returns the same result, since they all have Baked Fish Loaf as the primary.

Input Parameters

Name Type Definitionad_child_entity_id Double Identifies child entity for which primary entity is requested

Output Parameters

Name Type Definitionretval Double Primary entity identifier

f_get_primary_entity_from_textHRESULT f_get_primary_entity_from_text( [ in ] double ad_prod_id, [ in ] BSTR as_text, [out, retval] double *retval );

Description: This function retrieves the entity_id from the top-level component based on the collection and the textpassed to the function. If a text match is not found, then “0” is returned. The search is case sensitive, and a wildcardcharacter (*) can be used to expand the search. For example, ‘Euro*’ finds everything starting with “Euro”.

Input Parameters




Name Type Definitionas_text String Search text for top-level component

Output Parameters

Name Type Definitionretval Double Top-level component identifier

Example: The following example searches for a specific Article (top level component) within an Encyclopedia col-lection. The specified prod_id is 1001.dim prod_id as doubledim search_text as stringdim primary_entity_id as double ΄ prod_id 1001 is the Encyclopedia collectionprod_id = 1001΄attempting to find an Article titled Europesearch_text = "Europe"primary_entity_id = targ_com_obj.f_get_primary_entity_from_text (prod_id, search_text)΄ primary_entity_id now contains the entity_id for Europe or 0, if not found

f_get_primary_from_filterHRESULT f_get_primary_from_filter( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ] VARIANTARG *as_args, [ in, out ] VARIANTARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This function returns the primary entity, along with the related data in a Result Set, using a filter thathas been saved in Vasont. In order to run this function, the filter must be saved within Vasont. The argument, ad_fil-ter_id, is the saved filter identifier.

Input Parameters


and named. Can be equal to 0. If passed as 0, all primaries fromcollection are retrieved.

ad_prod_id Double Collection identifier

as_args String Argument to be used in filter, as an array. Filters can take any num-ber of arguments, depending on number of OR and AND state-ments in filter. Each argument must be in an array, in exact execu-tion order set up in filter.


Output Parameters

Name Type Definitionas_error_msg String Reason return failed





Name Type Definition Primary

























Example: If filter #5555 was set up to filter an Election Results collection, ID #2000:

• US States that have voted for Al Gore

• AND where the margin of victory is less than 0.5 percent

Dim querystring(1)Querystring(0) = "Al Gore"Querystring(1) = 0.5Set filter_rs = targobj.f_get_primary_from_filter(5555,2000,querystring) If filter had only one criterion, argument is still sent as an array:Dim querystring(0)Querystring(0) = "Ralph Nader"Set filter_rs = targobj.f_get_primary_from_filter(5555,2000,querystring)



f_get_primary_from_filter_as_isHRESULT f_get_primary_from_filter_as_is( [ in ] double ad_filter_id [ in ] double ad_prod_id[ in, out ] VARIAN-TARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This function returns the primary entity, along with the related data in a Result Set, using a filter thathas been saved in Vasont. In order to run this function, the filter must be saved within Vasont. The argument, ad_fil-ter_id, is the saved filter identifier. This method differs from f_get_primary_from_filter in that it uses whatever ar-guments have been saved with the filter rather than requiring them to be passed in the call.

Input Parameters

Name Type Definitionad_filter_id Double Filter identifier.

ad_prod_id Double Collection (Product) identifier.


Output Parameters



Primary




















Name Type Definition String primary_text (description of primary)







f_get_primary_from_filter_stringHRESULT f_get_primary_from_filter_string( [ in ] double ad_filter_id, [ in ] double ad_prod_id, [ in ] BSTRas_args, [ in, out ] VARIANTARG * as_error_msg, [out, retval] LPDISPATCH * retval );

Description: This “stub” function is another variant of the “f_get_primary_from_filter” function that substitutes adelimited string for the array of Filter arguments. This stub is used by the Vasont Universal Integrator (VUI), whichhas problems properly typing a string array for use with the Filters. This function takes a delimited string (delimitedwith a pipe (“|”)), builds an array off of the delimited string and passes the arguments on to: f_get_pri-mary_from_filter( )

Input Parameters

Name Type Definitionad_filter_id Double (Optional) ID of Stored Filter

ad_prod_id Double Collection for which Primaries will be retrieved



Output Parameters

Name Type Definitionas_error_msg String Reason return failed



Primary







Name Type Definition String client_key (client key data)




















f_get_primary_prod_entityHRESULT f_get_primary_prod_entity( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: The table primary_prod_entity holds high level information about each primary component. This func-tion returns information from this table for the passed primary_entity_id.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity whose client key will be used to find other match-

ing components

Output Parameters





Name Type Definition Double prod_id (identifier of collection containing component)



Double site_id (not being used)

f_get_primary_rule_relationHRESULT f_get_primary_rule_relation( [ in ] double ad_prod_id, [out, retval] double * retval );

Description: This function returns the identifier for the rule relation (parent/child relationship) for the primary (toplevel component) of the specified collection.

Input Parameters


Output Parameters

Name Type Definitionretval Double Component type identifier (rule_relation_id)

f_get_processing_option_argumentsHRESULT f_get_processing_option_arguments( [ in ] double ad_use_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set which lists the processing option arguments defined for a particular“usage” of an option.

Input Parameters

Name Type Definitionad_use_id Double Identifies an option's “usage” (normally obtained using another

API function that returns defined options)

Output Parameters


Double custom_rule_use_id (option “usage” identifier)

Double argument_id (option argument identifier)

Short arg_seq_no (sequence number defining order of option arguments)

String value (option argument value)

String argument_name (option argument name)



See Also: f_get_view_processing_options - Gets all Processing Options defined for an Extract or Load View “Head-er”

f_get_prod_attribute_valid_valuesHRESULT f_get_prod_attribute_valid_values( [ in ] double ad_prod_id, [ in ] double ad_attribute_link_id, [out, re-tval] LPDISPATCH * retval );

Description: This function retrieves a Resultset containing the valid values for a particular attribute.

Input Parameters


ad_attribute_link_id Double Attribute identifier

Output Parameters


String valid_value (the valid value for this attribute)

f_get_prod_entity_versionsHRESULT f_get_prod_entity_versions( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function retrieves a Resultset containing the rows in the prod_entity_version table for a particularcomponent entity.

Input Parameters

Name Type Definitionad_entity_id Double Component entity id

Output Parameters


Double transaction_id (transaction id for this version record—may be asso-ciated with other version records)

Double entity_id

Datetime create_date (version create date)

String create_username (user who created the version)

String version_reason (action code (reason) the version record was cre-ated)



f_get_prod_idHRESULT f_get_prod_id( [ in ] double ad_entity_id, [out, retval] double * retval );

Description: This function returns the collection ID for the specified entity.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which prod id is requested

Output Parameters

Name Type Definitionretval Double Identifies collection containing specified entity

f_get_prod_id_from_versionHRESULT f_get_prod_id_from_version( [ in ] double ad_version_id, [out, retval] double * retval );

Description: This function returns the collection ID for the specified Extract or Load View ID (ad_version_id). AllVasont Extract and Load Views are associated with a specific collection - This function returns the identifier for thatcollection.

Input Parameters

Name Type Definitionad_version_id Double Extract or Load View identifier for which the collection (ID) is to

be obtained

Output Parameters

Name Type Definitionretval Double Identifies collection for the specified Extract/Load View

f_get_prod_listHRESULT f_get_prod_list( [ in ] BSTR as_username, [out, retval] LPDISPATCH * retval );

Description: This function returns a list of collections for the specified user.

Input Parameters

Name Type Definitionas_username String Username for which list of collections is requested



Output Parameters



String prod_name (collection name)


String prod_edition (collection edition)

String subject_name (subject name containing collection)

Double subject_id (subject identifier)

String product_group (collection group)

Double prod_group_id (collection group identifier)

Double lang_id (language identifier)

f_get_prod_nameHRESULT f_get_prod_name( [ in ] double ad_prod_id, [out, retval] BSTR * retval );

Description: This function returns the passed prod_id collection name.

Input Parameters


Output Parameters

Name Type Definitionretval String Collection name for passed prod_id

f_get_prod_primaries_by_attributeHRESULT f_get_prod_primaries_by_attribute( [ in ] double ad_prod_id, [ in ] double ad_attribute_link_id, [ in ]BSTR as_attribute_value, [out, retval] LPDISPATCH * retval );

Description: This is a variant of the “f_get_primaries_by_attribute” function that returns the list of matching pri-maries for a single collection. The arguments are the Collection ID (ad_prod_id), the Attribute Link ID, and thematching Attribute Value. Primaries in the collection that have the attribute and value will be returned in a resultset.

Input Parameters

Name Type Definitionad_prod_id Double Collection for which Primaries will be retrieved

ad_attribute_link_id Double The Attribute Link ID (attribute whose value must match)

as_attribute_value String The matching attribute value.



Output Parameters

Name Type Definitionretval Result Set Resultset containing following columns (based on component's

class):

Primary























Double global_count (count of records for this entity in the Global ChangeLog)

Double mod_log_count (count of records for this entity in the Pointer Log)

f_get_prod_projectsHRESULT f_get_prod_projects( [ in ] double ad_prod_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a list of projects.



Input Parameters


Output Parameters


Double project_id (project identifier)


String proj_name (project name)

String active_flag (active flag)

String proj_desc (project description)

Double duration

String duration_flag

String collection_name

Example:Dim prod_id As DoubleDim rs As New Recordset prod_id = 1Set rs = targobj.f_get_prod_projects(prod_id)Set DataGrid1.DataSource = rs

f_get_prods_from_projectsHRESULT f_get_prods_from_projects( [out, retval] LPDISPATCH * retval );

Description: This function returns a list of collections for the specified collections/projects.

Input Parameters

None

Output Parameters





String active_flag (active flag)

String proj_desc (project description)

String duration (length of project)



Name Type Definition String duration_flag (duration flag)

String collection_name

f_get_project_component_listHRESULT f_get_project_component_list( [ in ] double ad_project_id, [out, retval] LPDISPATCH * retval );

Description: This function returns all of the components that are associated with a specific workflow project defini-tion.

Input Parameters

Name Type Definitionad_project_id Double Project identifier

Output Parameters


String comp_name (component name, e.g., para[section])

String tab_text (component Navigator name)




f_get_project_nameHRESULT f_get_project_name( [ in ] double ad_project_id, [out, retval] BSTR * retval );

Description: This function retrieves the names for all the projects related to a workflow project.

Input Parameters

Name Type Definitionad_project_id Double Workflow project identifier

Output Parameters

Name Type Definitionretval String Project names

f_get_project_tasksHRESULT f_get_project_tasks( [ in ] double ad_project_id, [out, retval] LPDISPATCH * retval );



Description: This function retrieves the definitions for all the tasks related to a workflow project.

Input Parameters


Output Parameters


Double task_id (task identifier)

String task_name (task name)


String user_assign_flag (p=pick, r=rotate, n=none)

String start_flag (y=yes, n=no)



Single task_desc (task description)

Double duration

String duration_flag

f_get_project_usersHRESULT f_get_project_users( [ in ] double ad_project_id, [out, retval] LPDISPATCH * retval );

Description: This function retrieves all the users who are allowed to perform at least one task within the specifiedproject.

Input Parameters


Output Parameters

Name Type Definitionretval Result Set Username

f_get_projects_by_componentHRESULT f_get_projects_by_component( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval]LPDISPATCH * retval );

Description: This function returns a list of projects that are defined for the specified component.



Input Parameters



Output Parameters




f_get_raw_attributesHRESULT f_get_raw_attributes( [ in ] double ad_raw_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a list (Resultset) of the Raw Attributes for a given piece of Raw Material. ALLRaw Attributes that are allowed for the Raw Type are included in the list, regardless of whether or not there are anyvalues for the Attribute (the varchar2_var column will be empty for Attributes that are not defined for the Raw Ma-terial).

Input Parameters

Name Type Definitionad_raw_id DOUBLE Raw material identifier

Output Parameters


Double raw_id

Double seq_no (sequence number)

Double attribute_link_id (raw attribute identifier)

String varchar2_var (raw attribute value)

String sgml_name (raw attribute name)

String default_value

Decimal value_raw_type_id

f_get_raw_classHRESULT f_get_raw_class( [ in ] double ad_raw_type_id, [out, retval] BSTR * retval );

Description: This function returns the raw class associated with a raw component.



Input Parameters

Name Type Definitionad_raw_type_id Double Component type identifier

Output Parameters

Name Type Definitionretval String Text, pointer, multimedia, N/A. N/A returned if invalid

raw_type_id passed to function.

f_get_raw_component_from_filterHRESULT f_get_raw_component_from_filter( [ in ] double ad_filter_id, [ in ] double ad_raw_type_id, [ in ] VAR-IANTARG * as_args, [ in, out ] VARIANTARG * as_class, [ in, out ] VARIANTARG * as_error_msg, [out, retval]LPDISPATCH * retval );

Description: This function returns a Result Set containing all raw components (raw material) of a particular type. Astored filter can be used to further constrain the set of components returned. Because the component can belong toone of several classes, the resultset definition varies depending on that class. A reference argument to this function(as_class) indicates the class and distinguishes the resultset layout.

Input Parameters


and named. Can be equal to 0. If passed as 0, all components (ofspecified type) in collection are retrieved.

ad_raw_type_id Double Raw component type identifier - Only components of this type areretrieved from raw material

as_args String Array Array of arguments to use with filter (if one is specified). Filter cantake any number of arguments, depending on number of filter crite-ria. Array of arguments must match up to filter criteria by countand order.

as_class String Reference argument for class of raw component


Output Parameters

Name Type Definitionas_class String Raw component class indicating format of returned resultset. Class

values are: Text, Multimedia, and Pointer.



Text

String raw_text_text (raw component's text)



Name Type Definition Double raw_id (raw component's data identifier)

Double raw_type_id (raw component's type identifier)

Double lang_id (language identifier assigned to raw component)

String raw_status_flag (raw component's status) - Values: a (approved);d (draft)

Date raw_status_date (date raw component was created)

String raw_username (user who created raw component)

String in_product_flag (raw component's collection usage): Values: y (yes- currently used); n (never used); r (retired - formerly, but no lon-ger, used)

Multimedia

String mm_description (raw component's multimedia description)


String mm_pathname (external path/filename for raw component)

String file_extension (for internal BLOBs; indicates file type)


Double raw_id (raw component's data identifier)







Pointer










Double entity_id (entity identifier of pointer's “target”)



Name Type Definition Double raw_inline_id (unused)

f_get_raw_component_from_filter_stringHRESULT f_get_raw_component_from_filter_string( [ in ] double ad_filter_id, [ in ] double ad_raw_type_id, [ in ]BSTR as_args, [ in, out ] VARIANTARG * as_class, [ in, out ] VARIANTARG * as_error_msg, [out, retval]LPDISPATCH * retval );

Description: This “stub” function is another variant of the “f_get_raw_component_from_filter” function that substi-tutes a delimited string for the array of Filter arguments. This stub is used by the Vasont Universal Integrator (VUI),which has problems properly typing a string array for use with the Filters. This function takes a delimited string(delimited with a pipe (“|”)), builds an array off of the delimited string and passes the arguments on to:f_get_raw_component_from_filter( )

Input Parameters


ad_raw_type_id Double Raw Type ID of Component to retrieve


as_class String Class of the Component (Text, Multimedia or Pointer)


Output Parameters

Name Type Definitionas_class String Raw component class indicating format of returned resultset. Class

values are: Text, Multimedia, and Pointer.



Text











Name Type Definition Multimedia

String mm_description (raw component's multimedia description)


String mm_pathname (external path/filename for raw component)

String file_extension (for internal BLOBs; indicates file type)









Pointer










Double entity_id (entity identifier of pointer's “target”)

Double raw_inline_id (unused)

f_get_raw_componentsHRESULT f_get_raw_components( [ in ] double ad_subject_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set of the defined raw components.



Input Parameters

Name Type Definitionad_subject_id Double Content type identifier

Output Parameters


Double raw_type_raw_type_id (raw type identifier)

Double raw_type_raw_class_id (raw class identifier)

String raw_type_generic_name (generic name for raw type)

String raw_class_class_name (class name for raw class)

f_get_raw_desc_by_raw_idHRESULT f_get_raw_desc_by_raw_id( [ in ] double ad_raw_id, [out, retval] BSTR * retval );

Description: This function returns the specified raw description associated with a raw component.

Input Parameters

Name Type Definitionad_raw_id Double Component type identifier

Output Parameters

Name Type Definitionretval String Text, pointer, multimedia, N/A. N/A returned if invalid raw_id

passed to function.

f_get_raw_descriptionHRESULT f_get_raw_description( [ in ] double ad_entity_id, [out, retval] BSTR * retval );

Description: This function returns the specified entity's raw description.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which raw description is requested

Output Parameters

Name Type Definitionretval String Raw description



f_get_raw_idHRESULT f_get_raw_id( [ in ] double ad_entity_id, [out, retval] double * retval );

Description: This function returns the raw identifier for the specified entity.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which raw id is requested

Output Parameters

Name Type Definitionretval Double Specified entity raw identifier

f_get_raw_textHRESULT f_get_raw_text( [ in ] double ad_entity_id, [out, retval] BSTR * retval );

Description: This function returns the raw text stored for the specified entity.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which raw text is requested

Output Parameters

Name Type Definitionretval String Specified entity raw text

f_get_raw_text_from_raw_idHRESULT f_get_raw_text_from_raw_id( [ in ] double ad_raw_id, [out, retval] BSTR * retval );

Description: This function returns the text associated with a particular piece of raw material.

Input Parameters

Name Type Definitionad_raw_id Double Identifies the raw material whose text will be returned

Output Parameters

Name Type Definitionretval String The text associated with the raw material component



f_get_raw_type_idHRESULT f_get_raw_type_id( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] double *retval );

Description: This function returns the raw type ID for a collection component.

Input Parameters



Output Parameters

Name Type Definitionretval Double Returns −1 if collection component not found

f_get_raw_typesHRESULT f_get_raw_types( [out, retval] LPDISPATCH * retval );

Description: This function returns a list of raw type information for all raw types currently in use in Vasont

Input Parameters

None

Output Parameters


Double raw_type_id

Double raw_class_id (1=Pointer, 4=Text, 5=Multimedia)

String generic_name

String type_flag

String use_flag (y/n)

String sgml_validate (y/n)

String global_change

String text_allowed (y/n)

retval String spell_check_flag

Double editor_tag_id

String class_name

String source_table_name



Name Type Definition String document_type

String begin_tag

String end_tag

String custom_rule_id

Double subject_id (content_type_id)

String update_flag

f_get_reference_stringHRESULT f_get_reference_string( [out, retval] BSTR * retval );

Description: This function returns the last registered error encountered by the COM object.

Input Parameters

None

Output Parameters

Name Type Definitionretval String Last registered error message

f_get_referenced_byHRESULT f_get_referenced_by( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set for all components that reference the passed entity id.

Input Parameters


Output Parameters


String prod_abbrev (name of collection containing reference)

String primary_raw_desc (description of primary containing reference)

String parent_raw_desc (description of parent for reference). Will be emp-ty if reference is child of primary.

String entity_status_flag (reference's current status) - Values: a (ap-proved); d (draft); i (incomplete)

Date entity_status_date (date reference was last edited)



Name Type Definition String entity_username (user who last edited reference)

Double entity_id (reference's entity identifier)

Double prod_id (collection identifier for collection containing reference)

Double rule_relation_id (reference's component type identifier)

Double raw_id (reference's raw data identifier)

Double raw_inline_id (unused)





String client_key

String hier_key

String descendant

f_get_review_comment_repliesHRESULT f_get_review_comment_replies( [ in ] double ad_comment_id, [ in, out ] VARIANTARG * as_com-ment_replies_xml, [ in, out ] VARIANTARG * as_error_message, [out, retval] short * retval );

Description: This method will return all replies that are related to a specific review comment. An XML string isreturned, which will contain all the reply information. This will be used in <oXygen/> to populate the user interfacerelated to a review comment thread.

Input Parameters

Name Type Definitionad_comment_id Double Identifies the comment for which the replies will be returned

Output Parameters

Name Type Definitionreply_id Double Unique identifier for each reply

comment_id Double Identifies the comment to which this reply relates

reviewer_id Double Identifies the reviewer who made the reply

username String The Vasont username associated with the reviewer who made thereply

create_date Date Time The date and time the reply was made in the format of yyyy/mm/ddhh24:mi:ss

text String The text of the reply

Sample XML returned in variable as_comment_replies_xml:<review_comments review_id=”100” comment_id=”403”> <review_replies>



<reply reply_id=”5000” comment_id=”403” reviewer_id=”99” username=”STEVE” text=”Steve reply to Deanna comment” create_date=”2015/08/01 09:11:12”/> <reply reply_id=”5001” comment_id=”403” reviewer_id=”100” username=”RICH” text=”Rich reply to Deanna comment” create_date=”2015/08/01 09:15:20”/> </review_replies></review_comments>In this sample XML, this method was called with comment_id of 403. Two reviewers, Steve and Rich, made repliesto this comment. Those replies are stored in the reply tag.

f_get_review_commentsHRESULT f_get_review_comments( [ in ] double ad_review_id, [ in, out ] VARIANTARG * as_review_com-ments_xml, [ in, out ] VARIANTARG * as_error_message, [out, retval] short * retval );

Description: This method will return all reviewer comments and replies related to a specific review. It will return anXML string, which contains all the comment and reply information. This will be used in <oXygen/> by the RefreshComments button.

Input Parameters

Name Type Definitionad_reviewer_id Double Identifies the reviewer

Output Parameters

<comment>Name Type Definitioncomment_id Double Unique identifier for each comment

reviewer_id Double Unique identifier for the reviewer

username String The Vasont username associated with the reviewer

create_date Date Time The date and time the comment was made in the format ofyyyy/mm/dd hh24:mi:ss

status String a (accepted), r (rejected), p (pending)

pi_type String Each comment has a start and end point in the XML and each ofthose will relate to a separate comment tag. This determines wheth-er the comment tag relates to the start or end processor instruction.s (start), e (end).

offset Double Offset in the XML file for the processor instruction

guid Double Unique identifier for each comment. Note that the guid value willmatch for two comment tags related to each comment.

text String The text of the comment

reason String The reason this was accepted or rejected by the editor (optional)<reply>Name Type Definitionreply_id Double Unique identifier for each reply


reviewer_id Double Identifies the reviewer who made the reply



<reply>Name Type Definitionusername String The Vasont username associated with the reviewer who made the

reply

create_date Date Time The date and time the reply was made in the format of yyyy/mm/ddhh24:mi:ss


Sample XML returned in variable as_review_comments_xml:

<all_review_comments review_id=”100”> <review_comments> <comment comment_id=”403” reviewer_id=”98” username=”deanna” create_date=”2015/05/15 10:11:12” status=”p” offset=”5” pi_type=”s” text=”COMMENT1” guid=”xx2” reason=””/> <comment comment_id=”401” reviewer_id=”99” username=”steve” create_date=”2015/05/15 08:34:12” status=”p” offset=”10” pi_type=”s” text=”User2 Comment” guid=”xx1” reason=””/> <comment comment_id=”403” reviewer_id=”98” username=”deanna” create_date=”2015/05/15 10:11:12” status=”p” offset=”12” pi_type=”e” guid=”xx2”/> <comment comment_id=”401” reviewer_id=”99” username=”steve” create_date=”2015/05/15 08:34:12” status=”p” offset=”15” pi_type=”e” guid=”xx1”/> </review_comments> <review_replies> <reply reply_id=”5000” comment_id=”403” reviewer_id=”98” username=”steve” text=”Steve reply” create_date=”2015/06/15 09:11:12”/></review_replies></all_review_comments>

In this sample XML, this method was called with review_id of 100. Two reviewers, Steve and Deanna, made com-ments related to this review. Those comments are stored in the comment tag. In addition, a reply was made by areviewer to another reviewer's comment, which is stored in the reply tag.

There are two comment tags for each comment. This is because there are two processor instructions needed in theXML for each comment. One will store the start position of the comment and the other will store the end position.

f_get_review_load_flagHRESULT f_get_review_load_flag( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] BSTR* retval );

Description: This returns the flag that determines the load flag that is associated with the review configuration for agiven edit view component, typically the primary component.

Input Parameters

Name Type Definitionad_prod_id Double The identifying value for the collection.

ad_rule_relation_id Double The identifying value for the component type.



Output Parameters

Name Type Definitionretval String a = always load, n = never load, p = user picks whether to load or

not

f_get_review_merge_fileHRESULT f_get_review_merge_file( [ in ] double ad_review_id, [ in, out ] VARIANTARG * as_merge_filename,[ in, out ] VARIANTARG * as_error_message, [out, retval] short * retval );

Description: This will first check the database to see if the merge files stored in Vasont are up to date. If not, thenlogic will be called to generate the latest merge file and store the result in the database (see f_generate_re-view_merge_file method below).

After the latest merge file is found or generated, the files will be exported to the merge directory (see DirectoryStructure section below). The argument as_merge_filename will be populated and will contain the full path and filename of the merge XML file.

Input Parameters


Output Parameters

Name Type Definitionas_merge_file String This will contain the full path and file name of the merge file that

was generated.

as_error_message String This will be populated with the error that occurred if the functionfails and return -1.


f_get_reviewer_infoHRESULT f_get_reviewer_info( [ in ] double ad_review_id, [out, retval] LPDISPATCH * retval );

Description: This function will return a list of reviewers that are related to a specific review. Each reviewer rowreturned will contain various fields (see Output Parameters below). A result set will be returned with a row for eachreviewer.

Input Parameters

Name Type Definitionad_review_id Decimal Specifies the review_id that will be used to retrieve and return the

reviewer information.



Output Parameters

Name Type Definitionreviewer_id Double Identifying value for each reviewer.

review_id Double Identifying value for the review.

reviewer_username String(30) The Reviewer's user name.

complete_date Datetime The date and time the reviewer's session was completed. This willbe Null if reviewer session is still active.

root_filename String(200) The file name associated with the reviewer's files. This does not in-clude path.

last_updated Datetime The date and time the reviewer last submitted their review to Vas-ont. This will be NULL if the reviewer has never submitted theirreview.

f_get_rightclick_processing_optionsHRESULT f_get_rightclick_processing_options( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out,retval] LPDISPATCH * retval );

Description: This function returns a Result Set of the processing options, associated with the Vasont edit view navi-gator_popup event, that are applied to a specific component (ad_rule_relation_id) within a given collection(ad_prod_id).

Input Parameters

Name Type Definitionad_prod_id Double Collection identifier for which right-click (navigator_popup) pro-

cessing options are to be retrieved

ad_rule_relation_id Double Component type identifier for which processing options are to beretrieved

Output Parameters


Double custom_rule_use_id (custom rule use identifier used to obtain for-mal processing option arguments)

Double prod_id (collection identifier - will always conform to ad_prod_idinput parameter)

Double rule_relation_id (component type identifier - will always conformto ad_rule_relation_id input parameter)

Double custom_rule_id (unique identifier assigned to processing option)

String use (event for processing option - will always be navigator_pop-up)

Double seq_no (sequence in which processing options are processed)

String text_argument (optional text argument(s) for processing option)



Name Type Definition String custom_rule_name (processing option name)

f_get_rule_relationHRESULT f_get_rule_relation( [ in ] double ad_entity_id, [out, retval] double * retval );

Description: This function gets the rule relation identifier (parent/child relationship) for the specified entity. (Seethe Key Concepts of the Low-Level API section in this guide).

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which rule relation id is requested

Output Parameters

Name Type Definitionretval Double Component type identifier (rule_relation_id)

f_get_rule_relation_from_versionHRESULT f_get_rule_relation_from_version( [ in ] double ad_version_id, [ in ] BSTR as_parent_tag, [ in ] BSTRas_child_tag, [ in, out ] VARIANTARG * ad_prod_id, [out, retval] double * retval );

Description: This function (typically used in an external XML Editor such as Arbortext Editor, FrameMaker orXMetaL) returns Vasont's component type identifier (rule_relation_id) based on a component tag, its parent's tagand a Vasont extract/load view identifier. In addition to returning the Vasont component identifier, this function alsoreturns the Vasont collection in which the component is located in the ad_prod_id reference argument.

Vasont's embed_extract_info_id processing option can be used to embed a Processing Instruction (PI), containingthe identifier for the selected extract view (version_id), in extracted XML Instances. After using the f_get_val-ue_from_extract_info_pi API function to obtain the extract view identifier from the PI (the “version_id” entry),this function can be used to obtain the component (and collection) identifiers for any component in the instance.

2 This API call relies on an exact, case sensitive match for the tags (in the specified extract/load view).If the external application making the API call alters the tag names in any way (or if the tag nameshave been transformed using XSLT or another transformation engine), this API call will not be ableto find a match.

Input Parameters

Name Type Definitionad_version_id Double Extract/load view in which to look for parent/child tag relationship

as_parent_tag String Tag assigned to parent of component in XML instance




Name Type Definitionad_prod_id Double Reference argument for collection containing component

Output Parameters

Name Type Definitionad_prod_id Double Collection identifier of collection containing component

retval Double Component type identifier (rule_relation_id) for component (0 ifnot found)

f_get_shadowHRESULT f_get_shadow( [ in ] double ad_prod_id, [ in ] double ad_prim_entity_id, [ in ] double ad_entity_id,[ in ] DATE adt_shadow_date, [ in ] VARIANT_BOOL ab_hierarchy, [out, retval] LPDISPATCH * retval );

Description: This function retrieves the entity snapshot record for a given entity as of a given date.

Input Parameters

Name Type Definitionad_prod_id Double Identifier of collection

ad_prim_entity_id Double Identifier of primary entity

ad_entity_id Double Identifier of snapshot entity

adt_shadow_date Date Date snapshot is created


Output Parameters
















Name Type Definition String pending_flag (pending flag)




String tab_text (text associated with tab)

String trigger_action (the update action associated with this version re-cord: i-insert, u-update, d-delete)

f_get_shadow_attributesHRESULT f_get_shadow_attributes( [ in ] double ad_prod_id, [ in ] double ad_prim_entity_id, [ in ] double ad_en-tity_id, [ in ] DATE adt_shadow_date, [ in ] VARIANT_BOOL ab_hierarchy, [out, retval] LPDISPATCH * retval );

Description: This function retrieves the attribute snapshot records for a given entity as of a given date.

Input Parameters


ad_prim_entity_id Double Primary entity identifier

ad_entity_id Double Snapshot entity identifier



Output Parameters



Double attribute_link_id (attribute link identifier)



String varchar2_var (value of attribute)


String varchar2_key (attribute indexed value)


f_get_shadow_first_lvl_childrenHRESULT f_get_shadow_first_lvl_children( [ in ] double ad_prod_id, [ in ] double ad_primary_entity_id, [ in ]double ad_parent_entity_id, [ in ] DATE adt_shadow_date, [out, retval] LPDISPATCH * retval );



Description: This function retrieves the snapshot records for the first-level descendants of the entity passed inad_parent_entity_id.

Input Parameters


ad_primary_entity_id Double Primary entity identifier

ad_parent_entity_id Double Parent entity identifier


Output Parameters




Double rule_relation_id (rule relation identifier)










String pending_flag (pending flag)




String tab_text (text associated with tab)


f_get_start_dateHRESULT f_get_start_date( [ in ] double ad_instance_id, [out, retval] DATE * retval );

Description: This function returns the specified instance start date.



Input Parameters

Name Type Definitionad_instance_id Double Specific workflow task identifier

Output Parameters

Name Type Definitionretval Date Task start date

Example:Dim ldt_start As Dateldt_start = targobj.f_get_start_date(1040)MsgBox (ldt_start)

f_get_statusHRESULT f_get_status( [ in ] double ad_entity_id, [out, retval] BSTR * retval );

Description: This function returns the specified entity current status.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity for which status is requested

Output Parameters

Name Type Definitionretval String Current status of entity

f_get_system_profile_valueHRESULT f_get_system_profile_value( [ in ] BSTR as_profile_id, [ in, out ] VARIANTARG * as_error_msg, [out,retval] BSTR * retval );

Description: This function, given a profile identifier, returns its value.

Input Parameters

Name Type Definitionas_profile_id String Profile identifier


Output Parameters




Name Type Definitionretval String Value of given profile_id

f_get_task_attributeHRESULT f_get_task_attribute( [ in ] double ad_task_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a resultset containing attribute information for a given task_id.

Input Parameters

Name Type Definitionad_task_id Double Task id to return attributes for

Output Parameters


Double task id

Double attribute link id

Double attribute sequence number

String default attribute value

Double attribute value raw type id

String attribute link sgml name

Double attribute link sgml type id

f_get_task_attribute_validHRESULT f_get_task_attribute_valid( [ in ] double ad_task_id, [ in ] double ad_att_link_id, [out, retval] LPDIS-PATCH * retval );

Description: This function returns a list (Resultset) of all valid_values for a given task_id and attribute_link_id.

Input Parameters

Name Type Definitionad_task_id Double Task id

ad_att_link_id Double Attribute link id of the attribute to return valid values for

Output Parameters


String valid value




f_get_task_instance_attributeHRESULT f_get_task_instance_attribute( [ in ] double ad_instance_id, [ in ] double ad_attribute_link_id, [out, re-tval] BSTR * retval );

Description: This function returns the attribute value for the specified workflow instance/attribute.

Input Parameters

Name Type Definitionad_instance_id Double Workflow instance identifier


Output Parameters

Name Type Definitionretval String Value of attribute

f_get_task_listHRESULT f_get_task_list( [ in ] BSTR as_username, [ in ] double ad_project_id, [out, retval] LPDISPATCH * re-tval );

Description: This function returns the active tasks for the specified user and project.

Input Parameters

Name Type Definitionas_username String All=all users; unassigned=tasks not assigned to a user, or specify a

specific user

ad_project_id Double Workflow project identifier

Output Parameters



String primary_desc (primary component description)

String entity_desc (component description associated with workflow—may be same as primary desc, if entity_id is primary)

Double instance_ id (task instance identifier)


Double workflow_id (instantiated project for component)

String status (a=active, c=complete)

String username (user assigned to task—may be null, if none assigned)



Name Type Definition Date start_date (task start date)

Due Date due_date (task due date)

Date complete_date (NULL, if task still active)


Single comments (comments attached to task instance)



Double primary_entity_id (primary component identifier)

String assigned_by (user who assigned this task)

Example:Dim project_id As DoubleDim rs As New RecordsetDim ldt_start As DateDim ls_entity_desc As String ΄project_id = 1001project_id = 1005 Set rs = targobj.f_get_task_list("TARGET", project_id)΄Set rs = targobj.f_get_task_list("TIPS", project_id)Set DataGrid1.DataSource = rsrs.MoveFirstDo Until rs.EOFldt_start = rs("start_date")MsgBox (ldt_start) rs.MoveNextLoop

f_get_task_list_filterHRESULT f_get_task_list_filter( [ in ] double ad_project_id, [ in ] BSTR as_username, [ in ] BSTR as_status, [ in ]double ad_entity_id, [ in ] double ad_task_id, [ in ] double ad_workflow_id, [out, retval] LPDISPATCH * retval );

Description: This function filters the workflow project tasks. The project_id is required and other arguments pro-vide a filter to define which tasks to return.

Input Parameters


as_username String All=all users; unassigned=tasks not assigned to a user, or specifyspecific user

as_status String All, complete, active

ad_entity_id Double 0=none specified, or specify entity_id on which to filter

ad_task_id Double 0=none specified, or specify task_id on which to filter



Name Type Definitionad_workflow_id Double 0=none specified, or specify workflow_id on which to filter

Output Parameters



String primary_desc (primary component description)

String entity_desc (component description associated with workflow—may be same as primary desc, if entity_id is primary)

Double instance_ id (task instance identifier)


Double workflow_id (instantiated project for component)

String status (a=active, c=complete)

String username (user assigned to task—may be null, if none assigned)

Date start_date (task start date)

Due Date due_date (task due date)

Date complete_date (NULL, if task still active)


Single comments (comments attached to task instance)



Double primary_entity_id (primary component identifier)

String assigned_by (user who assigned this task)

f_get_task_projectHRESULT f_get_task_project( [ in ] double ad_project_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing all of the tasks for the specified workflow project identi-fier.

Input Parameters


Output Parameters





Name Type Definition String task_name (task name)

Double duration (number of days within which project task must be com-pleted)

String duration_flag (flag indicating weeks(week), business days(bday),or calendar days(cday) within which project task must be comple-ted)

f_get_task_queueHRESULT f_get_task_queue( [ in ] double ad_task_id, [out, retval] LPDISPATCH * retval );

Description: This function retrieves data that defines which task, or tasks, should be initiated upon completion ofthe specified task.

Input Parameters

Name Type Definitionad_task_id Double Workflow task identifier

Output Parameters


Double task_id (identifies task being completed)

Double next_task_id (task that is queued to be created)

String optional_flag (y=optional, n=not optional (always created), o=pickone, z=pick zero or one)

f_get_task_usersHRESULT f_get_task_users( [ in ] double ad_task_id, [out, retval] LPDISPATCH * retval );

Description: This function retrieves all the users who are allowed to perform the specified task.

Input Parameters

Name Type Definitionad_task_id Double Workflow task identifier

Output Parameters



String username (user name)



f_get_thumbnail_fileHRESULT f_get_thumbnail_file( [ in ] double ad_raw_id, [out, retval] BSTR * retval );

Description: This function will generate a file containing the thumbnail view for the specified multimedia compo-nent. The component is determined by the passed argument of raw_id. The return value is the filename of thethumbnail that includes its full path. The thumbnail file will always be a JPG file.

The file will be placed in the user’s Windows temp directory. The format of the filename will be the raw_id +“.thumbnail.jpg”. For example, assume the raw_id is 1003 and your local Windows temp folder is c:\documents andsettings\myname\local settings\temp. The thumbnail file name returned would be “c:\documents and settings\my-name\local settings\temp\1003.thumbnail.jpg”.

If the thumbnail cannot be generated for the passed raw_id, then the return value will be an empty string.

Input Parameters

Name Type Definitionad_raw_id Double Specifies the raw_id of the multimedia component that will be used

to return a thumbnail file.

Output Parameters

Name Type Definitionretval String Returns the path and filename of the thumbnail file as a string..

f_get_thumbnail_file_fullsizeHRESULT f_get_thumbnail_file_fullsize( [ in ] double ad_raw_id, [out, retval] BSTR * retval );

Description: This function will generate a file containing a full size thumbnail view for the specified multimediacomponent. The component is determined by the passed argument of raw_id. The return value is the filename of thefull size thumbnail that includes its full path. The thumbnail file will always be a JPG file.

The file will be placed in the user’s Windows temp directory. The format of the filename will be the raw_id + “.full-size.jpg”. For example, assume the raw_id is 1003 and your local Windows temp folder is c:\documents and settings\myname\local settings\temp. The thumbnail file name returned would be “c:\documents and settings\myname\localsettings\temp\1003.fullsize.jpg”.

If the full size thumbnail cannot be generated for the passed raw_id, then the return value will be an empty string.

Input Parameters

Name Type Definitionad_raw_id Double Specifies the raw_id of the multimedia component that will be used

to return a thumbnail file.

Output Parameters

Name Type Definitionretval String Returns the path and filename of the thumbnail file as a string.



f_get_translation_extract_projectsHRESULT f_get_translation_extract_projects( [out, retval] LPDISPATCH * retval );

Description: This function returns a result set that contains a list of translation sub-projects that are ready to extract.It is used by the Extract Daemon.

Input Parameters

None

Output Parameters


Double sub_project_id (the ID of a translation subproject that has beencloned but not yet extracted)

Double project_id (the ID of a translation project that contains the subpro-ject)

Double entity_id (the Vasont ID of the primary content for the subproject)

String language_id (the Vasont abbreviation for the target language)

f_get_user_prod_xmlHRESULT f_get_user_prod_xml( [ in ] BSTR as_username, [out, retval] BSTR * retval );

Description: This function returns a string of XML showing a list of all collections the specified user has access toinside of Vasont.

Input Parameters

Name Type Definitionas_username String User ID

Output Parameters

Name Type Definitionretval String XML string showing list of all collections specified user has access

to inside Vasont.

XML DTD:<!- - ************************************************* - -><!- - MODULE: Vasont XML Prod DTD - -><!- - FILENAME: vasontxmlprod.dtd - -><!- - VERSION: 1.0 - -><!- - ************************************************* - -><!- - Formal Public Identifier:"-//Vasont Systems//DTD Vasont XML Prod v1.0 20070228//EN//XML" - -><!- - DATE: February 28, 2007 - ->



<!ELEMENT user.access (message, content.type*) ><!ATTLIST user.access user CDATA #IMPLIED ><!ELEMENT message (#PCDATA) ><!ELEMENT content.type (name, (product.group | product)*) ><!ATTLIST content.type id CDATA #IMPLIED ><!ELEMENT product.group (name, (product.group | product)*) ><!ATTLIST product.group id CDATA #IMPLIED ><!ELEMENT product (name, abbrev) ><!ATTLIST product id CDATA #IMPLIED ><!ELEMENT name (#PCDATA) ><!ELEMENT abbrev (#PCDATA) >

f_get_user_raw_material_xmlHRESULT f_get_user_raw_material_xml( [ in ] BSTR as_username, [out, retval] BSTR * retval );

Description: This function returns a string of XML showing a list of all raw material the specified user has access toinside of Vasont.

Input Parameters


Output Parameters

Name Type Definitionretval String XML string showing list of all raw material specified user has ac-

cess to inside Vasont

XML DTD:<!- - ********************************************* - -><!- - MODULE: Vasont XML Raw DTD - -><!- - FILENAME: vasontxmlraw.dtd - -><!- - VERSION: 1.0 - -><!- - ********************************************* - -><!- - Formal Public Identifier:"-//Vasont Systems//DTD Vasont XML Raw v1.0 20070228//EN//XML" - -><!- - DATE: February 28, 2007 - -><!ELEMENT user.access (message, content.type*) ><!ATTLIST user.access user CDATA #IMPLIED ><!ELEMENT message (#PCDATA) ><!ELEMENT content.type (name, raw.type*) ><!ATTLIST content.type id CDATA #IMPLIED ><!ELEMENT raw.type (name) ><!ATTLIST raw.type id CDATA #IMPLIEDraw.class.id CDATA #IMPLIED ><!ELEMENT name (#PCDATA) >

f_get_user_workflow_xmlHRESULT f_get_user_workflow_xml( [ in ] BSTR as_username, [out, retval] BSTR * retval );



Description: This function returns a string of XML showing a list of all workflow projects the specified user hasaccess to inside of Vasont.

Input Parameters


Output Parameters

Name Type Definitionretval String XML string showing list of all workflow projects specified user has

access to inside Vasont

XML DTD:<!- - ****************************************************************************** - -><!- - MODULE: Vasont XML Workflow DTD - -><!- - FILENAME: vasontxmlworkflow.dtd - -><!- - VERSION: 1.0 - -><!- - ****************************************************************************** - -><!- - Formal Public Identifier:"-//Vasont Systems//DTD Vasont XML Workflow v1.0 20070228//EN//XML" - -><!- - DATE: February 28, 2007 - -><!ELEMENT user.access (message, active.workflow, content.workflow, (content.type)*) ><!ATTLIST user.access user CDATA #IMPLIED ><!ELEMENT message (#PCDATA) ><!ELEMENT active.workflow (#PCDATA) ><!ELEMENT content.type (name, (product.group | product)*) ><!ATTLIST content.type id CDATA #IMPLIED ><!ELEMENT product.group (name, (product.group | product)*) ><!ATTLIST product.group id CDATA #IMPLIED ><!ELEMENT product (name, wf.project*) ><!ATTLIST product id CDATA #IMPLIED ><!ELEMENT wf.project (#PCDATA) (name) ><!ATTLIST wf.project id CDATA #IMPLIED ><!ELEMENT name (#PCDATA) >

f_get_usernameHRESULT f_get_username( [out, retval] BSTR * retval );

Description: This function returns the name of the user who is currently signed on to Vasont.

Input Parameters

None

Output Parameters

Name Type Definitionretval String username (name of user)

Example:



Dim ls_user As String ls_user = targobj.f_get_usernameMsgBox (ls_user)

f_get_usersHRESULT f_get_users( [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set containing all of the Vasont users.

Input Parameters

None

Output Parameters



Double connect_count

String email address

f_get_valid_clone_target_prodsHRESULT f_get_valid_clone_target_prods( [ in ] double ad_src_prod_id, [ in ] BSTR as_username, [out, retval]LPDISPATCH * retval );

Description: This function returns a Result Set of all valid collections that can be cloned to based on the sourcecollection and the permissions of the user.

Input Parameters

Name Type Definitionad_src_prod_id Double Source collection identifier


Output Parameters



String prod_name (collection name)



f_get_valid_filter_valuesHRESULT f_get_valid_filter_values( [ in ] double ad_prod_id, [ in ] double ad_comp_id, [ in ] BSTR as_comptype,[ in ] BSTR as_property, [ in, out ] VARIANTARG * ab_allowedit, [out, retval] LPDISPATCH * retval );

Description: This function, used in conjunction with the f_get_filter_definition API call, returns a Result Set con-taining a list of valid values for a filter criteria entry. This function can be used, when implementing filters throughthe API, to build and provide a drop-down list for certain filter criteria (e.g., Status Flags, User Names, etc.).

A reference argument (ab_allowedit) indicates whether values outside of the list provided are allowed. This is a clueto use a drop-down combo list (versus a standard drop-down list), allowing values to be entered as well as selected.With Vasont, this is normally used for usernames, where the current set of users can be provided in the list but theremay be older (removed) usernames associated with Vasont content.

If an empty result set is returned from this function, there is no list of values available for the filter criteria and thevalue to be used with the criteria should be collected as simple text.

Input Parameters

Name Type Definitionad_prod_id Double Identifier of collection against which filter is run

ad_comp_id Double Component identifier from f_get_filter_definition resultset

as_comptype String Component type from f_get_filter_definition resultset

as_property String Component property from f_get_filter_definition resultset

ab_allowedit Boolean Reference argument indicating whether values outside list are al-lowed

Output Parameters

Name Type Definitionab_allowedit Boolean Indicates whether values outside list are allowed - A clue that a

drop down combo list can (and should) be used


String display_name (display name for use in drop down list)

String data_value (data value to provide in stored filter arguments)

f_get_valid_valuesHRESULT f_get_valid_values( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [out, retval] LPDIS-PATCH * retval );



Description: This function returns valid values that are allowed for the specified component in the specified collec-tion. These values can also be manually looked up in Vasont Administrator as shown in the following:

The prod_id is 10361, the rule_relation_id is 10680 and the valid values shown are appetizers, barbecues etc. Whenusing this function, the Result Set has one row for each valid value.

Input Parameters



Output Parameters





String valid_value (allowed for specified component)

f_get_value_from_extract_info_piHRESULT f_get_value_from_extract_info_pi( [ in ] BSTR as_pi, [ in ] BSTR as_entry, [out, retval] BSTR * re-tval );

Description: This function (typically used in an external XML Editor such as Arbortext Editor, FrameMaker orXMetaL) extracts the value for a particular entry in the Vasont extract Processing Instruction (PI). The Vasont ex-



tract PI, embedded in an extracted XML Instance using the embed_extract_info_pi processing option, contains keyinformation regarding what was extracted from Vasont (and how the extract was performed). The information (en-tries) included in the Vasont Extract PI consist of:

entity_id (always present): Contains Vasont's internal identifier (Entity ID) for top-most component extracted.

version_id (alwayspresent):

Contains Vasont's internal identifier (Version ID) for the extract view used for ex-tract.

snapshot_file (optional): If create_fast_load_snapshot processing option was placed on extract view (to ena-ble fast loading of altered content), contains name of fast load “snapshot” file createdby Vasont.

selected_langs (optional): If language selection processing option was placed on extract view (e.g., get_selec-ted_lang_attribs or get_selected_lang_components), contains pipe (“|”) delimitedstring of language(s) selected for extract.

This function allows the user to obtain the value for any of these entries.

Input Parameters

Name Type Definitionas_pi String Contents of Vasont extract PI - Parameter can contain entire PI

(e.g.,<?VasontExtractInfo entity_id=“9999” version_id=“9999”?>)or just content that is obtained from data property on DOM PI.

as_entry String Entry, as defined in table in Description section above, for whichvalue is to be obtained

Output Parameters

Name Type Definitionretval String Value, from Vasont extract PI, for entry specified. If entry not

present in Vasont extract PI, empty string is returned.

f_get_variantsHRESULT f_get_variants( [ in ] double ad_entity_id, [out, retval] LPDISPATCH * retval );

Description: This function will retrieve all variants for a specified entity_id.

Input Parameters


Output Parameters


String prod_abbrev

String raw_desc



Name Type Definition String primary_raw_desc

String parent_raw_desc


String entity_status_flag

Datetime entity_status_date

String entity_username

String client_key

String username (check out user)

Datetime check_out_date

Double entity_id



Double primary_entity_id

Double parent_entity_id

String variant_action_flag

Datetime variants_create_date

String variants_create_username

String variant_type

Double variant_source_entity

Double variant_target_entity

Double parent_rule_relation_id (component type identifier)

Double raw_id

String normalize_results

f_get_version_attribute_link_proc_optsHRESULT f_get_version_attribute_link_proc_opts( [ in ] double ad_version_id, [out, retval] LPDISPATCH * re-tval );

Description: This function returns a Resultset containing all of the Processing Options currently associated with theLoad or Extract View (ad_version_id).

Input Parameters

Name Type Definitionad_version_id Double Load or extract view id

Output Parameters




Name Type Definition Double custom_rule_use_id

Double version_id

Double wrapper_relation_id

Double attribute_link_id

Double custom_rule_id

String use

Double seq_no (sequence_number)

String text_argument

String custom_rule_name

f_get_version_idHRESULT f_get_version_id( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ] BSTR as_ex-tract_type, [out, retval] LPDISPATCH * retval );

Description: This function provides a list of version(s) identifier(s) for the specified extract type.

Input Parameters



as_extract_type String Type of extract (load-ld, extract-ex, composite extract-cd)

Output Parameters


Double version_id (version identifier)


String extract_type (extract type)

String description (version description)

String use_shadow (shadowing use)


String file_extension (used for extract or expected for a load)

String is_xml

String single_file

String parse_required

String manager_use_only

String multi_level




Example:Dim ld_prod_id As DoubleDim rs As New Recordset ld_prod_id =10064 Set rs = targobj.f_get_version_id(ld_prod_id, 10404, "ex")Set DataGrid1.DataSource = rs

f_get_view_processing_optionsHRESULT f_get_view_processing_options( [ in ] double ad_version_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set which lists all of the processing options associated with an extract orload view “header”.

Input Parameters

Name Type Definitionad_version_id Double Extract or load view identifier

Output Parameters


Double custom_rule_use_id (unique identifier for processing option “us-age” - Used as handle to obtain option arguments)

Double version_id (extract or load view identifier)

Double custom_rule_id (unique identifier assigned to an option)

String use (Vasont event to which option applies)

Short seq_no (sequence number defining order in which options are to beprocessed)

String text_argument (for options that do not have formally defined argu-ments; contains string of argument names and values)

String custom_rule_name (name of option)

See Also: f_get_processing_option_arguments - Gets arguments defined for a particular Processing Options “usage”

f_get_workflow_taskHRESULT f_get_workflow_task( [ in ] double ad_workflow_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Result Set that contains all of the tasks for the specified workflow identifier.

Input Parameters

Name Type Definitionad_workflow_id Double Workflow identifier



Output Parameters


task_name (task name)

task_duration (duration of task)

task_duration_flag (optional) - flag indicating weeks(week), busi-ness days(bday), or calendar days(cday) within which task must becompleted

workflow_id (workflow identifier)

task_id (task identifier)

duration (number of days within which task must be completed)

duration_flag (flag indicating weeks(week), business days(bday),or calendar days(cday) within which task must be completed)

username (name of user)

due_date (date task must be completed)

f_get_wrapper_relation_idHRESULT f_get_wrapper_relation_id( [ in ] double ad_version_id, [ in ] double ad_rule_relation_id, [out, retval]double * retval );

Description: This function will return a wrapper_relation_id for a given load or extract view version_id and rule_re-lation_id.

Input Parameters



Output Parameters

Name Type Definitionretval Double wrapper relation identifier

f_get_wrapper_relation_proc_optsHRESULT f_get_wrapper_relation_proc_opts( [ in ] double ad_version_id, [out, retval] LPDISPATCH * retval );

Description: This function returns a Resultset containing all of the Processing Options currently associated with theLoad or Extract View (ad_version_id).



Input Parameters


Output Parameters


Double custom_rule_use_id

Double wrapper_relation_id

Double custom_rule_id

String use

Double sequence_number

String text_argument

String custom_rule_name

Double version_id

f_insert_batch_extract_queueHRESULT f_insert_batch_extract_queue( [ in ] BSTR as_user_id, [ in ] double ad_entity_id, [ in ] double ad_ver-sion_id, [ in ] BSTR as_file_name, [ in ] BSTR as_arguments, [ in ] BSTR as_type, [ in, out ] VARIANTARG *ai_error_code, [ in, out ] VARIANTARG * as_error_msg, [out, retval] short * retval );

Description: This function adds a component to the batch extract or load queue.

Input Parameters

Name Type Definitionas_user_id String Id for user having extracted entries deleted

ad_entity_id Double Entity id to add to queue

ad_version_id Double Extract or load version id to add to queue

as_file_name String File to extract to or load from-full path required

as_arguments String Any argument required for extract/load

as_type String Queue to add to; (E) extract or (L) load

ai_error_code Double Error code

as_error_msg String Indicates reason extract failed

Output Parameters

Name Type Definitionai_error_codes Double Native SQL error code for any errors that occur

as_error_msg String Error message for any errors that occur

retval Double 1=success; −1=otherwise



f_insert_componentHRESULT f_insert_component( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ] double ad_raw_id,[ in ] double ad_parent_entity_id, [ in ] double ad_seq_no, [ in ] BSTR as_client_key, [ in, out ] VARIANTARG *as_error_message, [out, retval] double * retval );

Description: This function inserts the new component into the database.

Input Parameters



ad_raw_id Double Raw material identifier

ad_parent_entity_id Double Parent entity identifier

ad_seq_no Double Component sequence number within parent

as_client_key String Client key data


Output Parameters

Name Type Definitionas_error_message String Reason insert failed

retval Double Entity id of newly inserted component. (If −1 returned for errors,check reference argument as_error_message).

f_insert_daemon_batchHRESULT f_insert_daemon_batch( [ in ] const BSTR as_daemon_id, [ in ] const BSTR as_batch_ids, [out, retval]VARIANT_BOOL * retval );

Description: This function inserts a row into the daemon_batch table.

Input Parameters

Name Type Definitionas_daemon_id String Daemon process id

as_batch_ids String Comma delimited string of batch queue job ids

Output Parameters

Name Type Definitionretval Boolean Indicates INSERT success or failure



f_insert_primary_componentHRESULT f_insert_primary_component( [ in ] double ad_prod_id, [ in ] double ad_raw_id, [ in ] BSTR as_cli-ent_key, [ in ] double ad_border_primary_entity_id, [ in ] BSTR as_placement, [ in, out ] VARIANTARG * as_er-ror_message, [out, retval] double * retval );

Description: This function inserts new primary (top-level) components into the database.

Input Parameters


ad_raw_id Double Raw material identifier

as_client_key String Client key data

ad_border_primary_entity_id Double Border primary entity identifier

as_placement String Placement - A=after or B=before ad_border_primary_entity_id


Output Parameters

Name Type Definitionas_error_message String Reason new component insert failed

retval Double Entity id of newly inserted component. (If −1 returned for errors,check reference argument as_error_message).

f_insert_raw_material_mmHRESULT f_insert_raw_material_mm( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ] BSTRas_text, [ in ] BSTR as_description, [ in ] BSTR as_external_filename, [ in ] BSTR as_blob_filename, [ in ] BSTRas_blob_extension, [out, retval] double * retval );

Description: This function builds a raw material record for a component that has a raw class of multimedia. If a rawmaterial already exists that matches the data passed, the function determines that and returns the matching raw mate-rial's raw_id.

Input Parameters



as_text String Text associated (if any) with multimedia component. Optional:leave empty, if none.

as_description String Description of multimedia component - required

as_external_filename String Multimedia component has a filename field that references an ex-ternal file. Optional: leave empty, if none.



Name Type Definitionas_blob_filename String If storing BLOB in database, specifies file that is read to get

BLOB.

as_blob_extension String File extension related to BLOB being stored in database. Ifas_blob_filename is specified with an extension, it is used for thisfield.

Output Parameters

Name Type Definitionretval Double Raw_id of raw material that is created or found

f_insert_raw_material_pointerHRESULT f_insert_raw_material_pointer( [ in ] double ad_pointer_prod_id, [ in ] double ad_pointer_rule_rela-tion_id, [ in ] double ad_pointee_entity_id, [ in ] BSTR as_text, [ in, out ] VARIANTARG * as_error, [out, retval]double * retval );

Description: This function creates a raw material record with a raw component type equal to pointer.

Input Parameters

Name Type Definitionad_pointer_prod_id Double Pointer collection identifier

ad_pointer_rule_relation_id Double Pointer component type identifier

ad_pointee_entity_id Double Pointed to entity id identifier

as_text String Text associated with raw material pointer

as_error String Error message

Output Parameters

Name Type Definitionas_error String Reason for failure

retval Double Returns identifier of newly inserted raw material

f_insert_raw_material_textHRESULT f_insert_raw_material_text( [ in ] double ad_raw_type_id, [ in ] BSTR as_text, [out, retval] double *retval );

Description: This function creates a raw material record that has a raw component type equal to text.

Input Parameters

Name Type Definitionad_raw_type_id Double Raw material type identifier



Name Type Definitionas_text String Text associated with raw material

Output Parameters

Name Type Definitionretval Double Returns identifier of newly inserted raw material

f_insert_task_instanceHRESULT f_insert_task_instance( [ in ] double ad_task_id, [ in ] double ad_workflow_id, [ in ] double ad_enti-ty_id, [ in ] BSTR as_username, [out, retval] double * retval );

Description: This function inserts a task instance record related to a specific component in the database (entity_id).It is expected that a valid username is passed (see the f_get_task_users function to determine which users are al-lowed to perform a specific task). It is allowed to send an empty string for the username if, 1) the user_assign_flagfor task is set to rotate or none, or 2) a processing option has been applied to automatically assign a user, or 3) thereis only one user assigned to the task.

Input Parameters

Name Type Definitionad_task_id Double Task identifier

ad_workflow_id Double Workflow identifier to which this task belongs


as_username String User name

Output Parameters

Name Type Definitionretval Double 1=success; −1=failure

f_insert_version_and_commentHRESULT f_insert_version_and_comment( [ in ] double ad_entity_id, [ in ] BSTR as_comment, [ in, out ] VAR-IANTARG * as_error_message, [out, retval] short * retval );

Description: This function inserts an on-demand version and comment for the selected entity.

Input Parameters

Name Type Definitionad_entity_id Double Entity_id for versioning

as_comment String Comment text

as_error_message String Passed by reference—will contain info regarding any errors



Output Parameters

Name Type Definitionas_error_message String passed by reference—will contain information regarding any errors

retval Short 0=success , -1=warning - entity is not set up for version on de-mand, -2=error - failed to get rule_relation_id, -3=error - failed toget prod_id, -4=error - could not get transaction_id, -5=error -could not insert prod_entity_version record, -6=error - could not in-sert prod_entity_version_comment record

f_insert_workflow_taskHRESULT f_insert_workflow_task( [ in ] double ad_project_id, [ in ] double ad_workflow_id, [ in ] doublead_task_id, [ in ] double ad_duration, [ in ] BSTR as_duration_flag, [ in ] BSTR as_username, [ in ] DATEadt_due_date, [ in, out ] VARIANTARG * as_error_text, [out, retval] short * retval );

Description: This function can be used to reassign a task from one user to another, or change the duration/durationflag/due date for the task.

Input Parameters


ad_workflow_id Double Workflow identifier

ad_task_id Double Task identifier

ad_duration Double [optional] Number of days within which task must be completed.Duration used with duration flag. If duration not specified, send0(zero).

ad_duration_flag String Duration flag indicating weeks(week), business days(bday), or cal-endar days(cday) within which task must be completed

as_username String Name of user assigned to task

adt_due_date Date Date task must be completed

as_error_text String Text returned if program encounters errors

Output Parameters

Name Type Definitionas_error_text String Reason task insertion failed


f_leadtools_supported_filetypeHRESULT f_leadtools_supported_filetype( [ in ] BSTR as_filetype, [out, retval] VARIANT_BOOL * retval );

Description: This function returns TRUE if the STRING as_filetype is supported in Vasont for display as a thumb-nail in the Multimedia Update window. If the as_filetype is not supported, the function returns FALSE.



Input Parameters

Name Type Definitionas_filetype String file extension of file type (.jpg, .gif, etc.)

Output Parameters

Name Type Definitionretval Boolean True if file type is supported; False if file type is not supported

f_loadHRESULT f_load( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR as_text, [ in, out ] VARIAN-TARG * as_error_text, [out, retval] VARIANT_BOOL * retval );

Description: This function loads the specified data (as_text) into the database. If a primary component is being loa-ded, the entity_id is not used and can be set to zero (0). All primary loads utilize a match criteria to link up to theexisting primaries in the database. For a sub-component load, the entity_id is required and specifies the componentto be overwritten.

If an error occurs during the load process, a message is returned in as_error_text, and the result contains the successor failure of the load.

Input Parameters


ad_version_id Double Identifies version used to perform load

as_text String Data to be loaded into file

as_error_text String For return of error or warning messages

Output Parameters

Name Type Definitionas_error_text String If load fails, reason for failure; if load succeeds, may contain warn-

ing messages from Vasont load engine.


2 Even if this function returns true (indicating the load was processed), the contents of as_error_textshould be checked - This reference argument may contain important warning information, regardingthe load process, that should be presented to the user.

Example:Dim lb_success As BooleanDim ld_version_id As DoubleDim ls_error As StringDim ls_text As String ls_text = Text2.Text



ld_version_id = 1 MsgBox (ld_prim_entity_id)MsgBox (ld_version_id)MsgBox (ls_text) lb_success = targobj.f_load(ld_prim_entity_id, ld_version_id, ls_text, ls_error)If lb_success ThenMsgBox ("success") ElseMsgBox ("error occurred in load" + ls_error)End If

f_load_fileHRESULT f_load_file( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR as_filename, [ in, out ]VARIANTARG * as_error_text, [out, retval] VARIANT_BOOL * retval );

Description: This function is similar to the f_load function, with the exception of loading a text string (as_text). Afull filepath is provided where the file to be loaded resides (as_filename). An example of as_filename is ‘c:\vasont\load\test.sgm’. This means that a user loads the file on their “c drive” in the vasont\load subdirectory. The name ofthe file is test.sgm and resembles the file shown in the example for the f_extract function, except it is being loadedinto, rather than extracted from, the database.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be loaded

ad_version_id Double Identifies version used to perform load

as_filename String Fully specified path where file to be loaded resides

as_error_text String For return of error or warning messages

Output Parameters

Name Type Definitionas_error_text String If load fails, reason for failure; if load succeeds, may contain warn-

ing messages from Vasont load engine.


2 Even if this function returns true (indicating the load was processed), the contents of as_error_textshould be checked - This reference argument may contain important warning information, regardingthe load process, that should be presented to the user.

f_load_file_translationHRESULT f_load_file_translation( [ in ] double ad_entity_id, [ in ] double ad_version_id, [ in ] BSTR as_filename,[ in ] double ad_translation_file_id, [ in, out ] VARIANTARG * as_error_text, [out, retval] VARIANT_BOOL *retval );



Description: This function is similar to the f_load_file function, except an additional argument is passed to identifythe translation_file_id. In addition to a standard load process being performed, the translation file status will also beupdated to a value of completed. This option is typically used when loading non-XML files (e.g. graphic files) backfrom a translation vendor.

Input Parameters

Name Type Definitionad_entity_id Double Identifies content in Vasont to be loaded into

ad_version_id Double Identifies id for the load view to be used

as_filename String Fully specified path and file name of file to be loaded

ad_translation_file_id Double Identifies the id for the translation_file record to be updated

as_error_text String Error messages

Output Parameters

Name Type Definitionas_error_text String Reason extract failed


f_ownership_extension_activeHRESULT f_ownership_extension_active( [out, retval] VARIANT_BOOL * retval );

Description: This function will return a “True” value if the ownership extension is enabled, which is done via aSystem Profile setting. “False” will be returned if the ownership extension is not enabled.

Input Parameters

None

Output Parameters

Name Type Definitionretval Boolean True = Ownership Extension feature is enabled; False = Ownership

Extension feature is not enabled.

f_pending_delete_entityHRESULT f_pending_delete_entity( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_error_message,[out, retval] VARIANT_BOOL * retval );

Description: This function places the given entity in pending delete status.



Input Parameters

Name Type Definitionad_entity_id Double Identifies entity awaiting delete confirmation

as_error_message String Error message returned

Output Parameters

Name Type Definitionas_error_message String Reason for failure

retval Boolean True=success; false=failure

f_reassign_task_userHRESULT f_reassign_task_user( [ in ] double ad_instance_id, [ in ] BSTR as_username, [out, retval] short * re-tval );

Description: This function reassigns an open workflow task from one user to another.

Input Parameters

Name Type Definitionad_instance_id Double Workflow task identifier

as_username String User to whom task is being assigned

Output Parameters


f_redline_reportHRESULT f_redline_report( [ in ] double ad_prod_id, [ in ] double ad_prim_entity_id, [ in ] double ad_entity_id,[ in ] DATE adt_shadow_date, [ in ] VARIANT_BOOL ab_hierarchy, [ in, out ] VARIANTARG * as_filename,[out, retval] short * retval );

Description: This function returns a RedLine Report in rich text format (rtf) that is used to zero in on specificchanges made to a component or group of components.

Input Parameters




adt_shadow_date Date Date report created



Name Type Definitionab_hierarchy Boolean If true, extracts all descendants. If false, extracts component only.

as_filename String Name of report

Output Parameters


retval Short RedLine report

f_register_daemonHRESULT f_register_daemon( [ in ] const BSTR as_daemon_id, [ in ] const BSTR as_daemon_name, [ in ] constBSTR as_daemon_type, [ in ] const short ai_expire_value, [ in ] const BSTR as_load_root, [ in ] const BSTR as_ex-tract_root, [out, retval] VARIANT_BOOL * retval );

Description: This function INSERTS a record or UPDATES a record in the active_daemon table for a given dae-mon_id.

Input Parameters

Name Type Definitionas_daemon_id String Daemon machine id, i.e. PC108

as_daemon_name String Daemon process name, i.e. Batch queue on PC108

as_daemon_type String EXTRACT, LOAD, or EXTRACT_LOAD

ai_expire_value Short Number of minutes to expire from LAST_RUN (the last datetimef_register_daemon was run)

as_load_root String Directory the daemon will load from

as_extract_root String Directory the daemon will extract to

Output Parameters

Name Type Definitionretval Boolean indicates INSERT or UPDATE success or failure—record was cre-

ated or updated if TRUE

f_reinstate_shadowHRESULT f_reinstate_shadow( [ in ] double ad_prod_id, [ in ] double ad_prim_entity_id, [ in ] double ad_entity_id,[ in ] DATE adt_shadow_date, [ in ] VARIANT_BOOL ab_hierarchy, [ in, out ] VARIANTARG * as_error_msg,[out, retval] short * retval );

Description: This function sets the entity back to how it was as represented in the referenced snapshot record.



Input Parameters




adt_shadow_date Date Date snapshot created



Output Parameters

Name Type Definitionas_error_msg String Error message


f_remove_bookmarkHRESULT f_remove_bookmark( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_message, [out, retval]short * retval );

Description: This function removes the user's bookmark for the given entity.

Input Parameters


as_message String Reason removal failed

Output Parameters

Name Type Definitionas_message String Error message

retval Short 0=success; −1=error

f_resequence_non_primaryHRESULT f_resequence_non_primary( [ in ] double ad_src_entity_id, [ in ] double ad_trgt_entity_id, [ in ] BSTRas_before_or_after, [ in, out ] VARIANTARG * as_error_text, [out, retval] short * retval );

Description: This function changes the placement of the non-primary source entity to before or after the target enti-ty.



Input Parameters

Name Type Definitionad_src_entity_id Double Source entity identifier

ad_trgt_entity_id Double Target entity identifier

as_before_or_after String Sequence before or after


Output Parameters

Name Type Definitionas_error_text String Reason resequence failed


f_resequence_primaryHRESULT f_resequence_primary( [ in ] double ad_src_entity_id, [ in ] double ad_trgt_entity_id, [ in ] BSTRas_username, [ in ] BSTR as_placement, [ in, out ] VARIANTARG * as_error_text, [out, retval] short * retval );

Description: This function changes the order of the primary source entity to before or after the target primary entity.

Input Parameters

Name Type Definitionad_src_entity_id Double Source entity identifier

ad_trgt_entity_id Double Target entity identifier


as_placement String Placement for primary - A=after; B=before


Output Parameters

Name Type Definitionas_error_text String Reason primary resequence failed


f_review_accept_rejectHRESULT f_review_accept_reject( [ in ] BSTR as_review_editing_xml, [ in, out ] VARIANTARG * as_error_mes-sage, [out, retval] short * retval );

Description: This method will be used during the review editing phase. This method will be called by the editor toupdate reviewer's comments by accepting or rejecting each one. An optional reason attribute can also be populatedfor each comment to describe the reason behind the decision. This method will receive an XML string as an argu-ment, which will contain all the required data. This will be used in <oXygen/> by the editor prior to completing thereview editing.



Input Parameters

None

Output Parameters

<comment>Name Type Definitioncomment_id Double Unique identifier for each comment.

status String a (accepted), r (rejected), p (pending)

reason String The reason this was accepted or rejected by the editor. This is op-tional and does not need to be included in the XML.

XML format expected in variable as_reviewer_editing_xml:<user_review_comments reviewer_id=”98” review_id=”100”> <review_comments> <comment offset=”5” type=”s” text=”COMMENT4” guid=”xx4”/> <comment offset=”10” type=”s” text=”COMMENT5” guid=”xx5”/> <comment offset=”12” type=”e” guid=”xx4”/> <comment offset=”43” type=”e” guid=”xx5”/> </review_comments> <review_replies> <reply comment_id=”403” text=”Dee reply to Steve reply” /> </review_replies></user_review_comments>Note: There is no requirement that this method pass in a status for all comments for the entire review, although allcomments will eventually need to be accepted or rejected before completing the review (see note below).

Note: The existing method of f_complete_review_editing will still be used to complete the actual review. This meth-od will perform the load of content into Vasont, complete the review, etc. This method will also perform a check toverify that all comments are accepted or rejected. If there are any pending comments, f_complete_review_editingwill fail and return a message explaining that there are pending comments.

f_review_comment_has_repliesHRESULT f_get_review_comment_replies( [ in ] double ad_comment_id, [ in, out ] VARIANTARG * as_com-ment_replies_xml, [ in, out ] VARIANTARG * as_error_message, [out, retval] short * retval );

Description: This method will return a Boolean (true or false) value. If there is at least one reply for the reviewcomment passed via comment_id, this method will return true. If no replies exist, this method will return false.

Input Parameters

Name Type Definitionad_comment_id Double The identifying value for the review comment

Output Parameters

Name Type Definitionretval Boolean True if replies exist for this comment, False if no replies exist for

this comment



f_search_for_primaryHRESULT f_search_for_primary( [ in ] double ad_prod_id, [ in ] BSTR as_text, [ in, out ] VARIANTARG * as_er-ror_msg, [out, retval] LPDISPATCH * retval );

Description: This function searches for a primary entity based on the specified search string which is case sensitive.

Input Parameters


as_text String Text for which to search


Output Parameters

Name Type Definitionas_error_msg String Reason search failed


Double entity_id (top level component identifier - primary)

String text (text of primary)

String alpha_tag (alpha tag primary identifier)

String primary_seq_no

Example:

Dim ls_search As StringDim ld_prod_id As DoubleDim rs As New RecordsetDim ls_error ld_prod_id = 1ls_search = Text1.Text Set rs = targobj.f_search_for_primary(ld_prod_id, ls_search, ls_error)Set DataGrid1.DataSource = rs

f_sequence_primaryHRESULT f_sequence_primary( [ in ] double ad_trgt_entity_id, [ in ] BSTR as_placement, [ in ] doublead_prod_id, [out, retval] double * retval );

Description: This function determines the sequence number for a new primary component. The ad_trgt_entity_idargument defines the primary entity_id the new primary will be adjacent to. The as_placement argument determineswhether it is placed before or after.



Input Parameters

Name Type Definitionad_trgt_entity_id Double Target entity identifier

as_placement String Placement - A=after; B=before


Output Parameters

Name Type Definitionretval Double 1=success; −1=failure

f_server_side_cancelHRESULT f_server_side_cancel( [ in ] double ad_image_id, [out, retval] short * retval );

Description: This function can be used to cancel a Server-Side Process (e.g., a Server Load or Server Clone proc-ess) running in the Oracle JVM. Cancels are then intercepted by the Vasont or Java (Server-Based) portion of theprocess.

Input Parameters

Name Type Definitionad_image_id Double Image ID of the server process being run

Output Parameters

Name Type Definitionretval integer 1=success; -1=failure

f_server_side_progressHRESULT f_server_side_progress( [ in ] double ad_image_id, [ in, out ] VARIANTARG * as_message, [out, re-tval] short * retval );

Description: This function can be used to monitor a Server-Side Process (e.g., a Server Load or Server Clone) thatis running in the Oracle JVM. The percentage completed is returned and the latest message posted by the Serverprocess is passed back by reference (as_Message).

Input Parameters

Name Type Definitionad_image_id Double Process “Image” to look up Progress

as_message String REF argument to return last posted Message



Output Parameters

Name Type Definitionas_message String Returns last posted Message

retval integer 0=Server-Side Process Failed or Cancelled, 100=Server-Side Proc-ess Successful, Other=Server-Side In Progress

f_set_attribute_valueHRESULT f_set_attribute_value( [ in ] double ad_entity_id, [ in ] double ad_attribute_link_id, [ in ] BSTR as_val-ue, [out, retval] short * retval );

Description: This function updates the component's attribute value. If the attribute already has a value, the value isupdated; otherwise it is inserted. If the value passed is blank, the attribute is deleted from the database.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be updated


as_value String Component's attribute value

Output Parameters

Name Type Definitionretval Short 1=success; −1=failure.

f_set_batch_extract_queue_filenameHRESULT f_set_batch_extract_queue_filename( [ in ] long al_beq_id, [ in ] BSTR as_filename, [ in, out ] VAR-IANTARG * as_errormsg, [out, retval] short * retval );

Description: This function modifies the filename column of an existing entry in the batch_extract_queue table.

Input Parameters

Name Type Definitional_beq_id Long Batch extract id for row to modify filename

as_filename String File to extract to or load from-full path required

as_errormsg String Error message

Output Parameters

Name Type Definitionas_errormsg String Error message for any errors that occur

retval Short 1=success; −1=otherwise



f_set_batch_extract_queue_sequence_noHRESULT f_set_batch_extract_queue_sequence_no( [ in ] VARIANTARG * al_batch_extract_id, [ in ] VARIAN-TARG * ai_sequence_num, [ in, out ] VARIANTARG * as_error_msg, [out, retval] VARIANT_BOOL * retval );

Description: This function sets the order for batch extracts. Batch extracts use the SEQUENCE_NO column in thebatch_extract_queue to provide the order for the batch extract process. Batch extracts start with the lowest SE-QUENCE_NO and move to the highest. Two parallel arrays are passed to the function, al_batch_extract_id andai_sequence_no. The al_batch_extract_id contains the batch_extract_ids of the batch extract entries to modify, andai_sequence_no contains the corresponding sequence_no for each batch extract in al_batch_extract_id. As an exam-ple:

The al_batch_extract_id parameter contains three values: 254, 256, 259. ai_sequence_no contains three values:3,2,1. In the batch_extract_queue table, the values for batch_extract_id and sequence_no will be:

• 254, 3

• 256, 2

• 259, 1

The batch_extract_id 259 will be extracted first, followed by 256, and finally 254.

Input Parameters

Name Type Definitional_batch_extract_id Long Array of batch_extract_ids

ai_sequence_num Double Array of sequence_numbers

as_error_msg String Error message passed by reference

Output Parameters

Name Type Definitionas_error_msg String Error message text; check for error message if function returns

false

retval Boolean True if function updates database; false if error occurs

f_set_batch_extract_queue_statusHRESULT f_set_batch_extract_queue_status( [ in ] double ad_beq_id, [ in ] BSTR as_status, [out, retval] short *retval );

Description: This function modifies the filename status column of an existing entry in the batch_extract_queue ta-ble.

Input Parameters

Name Type Definitionad_beq_id Double Batch extract id for row to modify status

as_status String Status to set (QUEUE, EXTRACT, EXTRACTED, LOAD)



Output Parameters


f_set_bypass_server_processingHRESULT f_set_bypass_server_processing( [ in ] VARIANT_BOOL ab_bypass );

This function sets the bypass for the optional Asynchronous Sever Processing on and off.

Input Parameters

Name Type Definitionab_bypass Boolean TRUE bypasses Asynchronous Sever Processing , FALSE does not

bypass. Asynchronous Server Processing is NOT BYPASSED bydefault for Vasont API Server Delete, Server Clone, and ServerLoad functions

Output Parameters

None

f_set_entity_clientkeyHRESULT f_set_entity_clientkey( [ in ] double ad_entity_id, [ in ] BSTR as_client_key, [out, retval] short * re-tval );

This function will set a new client key value for a specific Vasont component. The ad_entity_id argument specifiesthe Vasont component to be updated. The as_client_key argument specifies the value the client key will be changedto.

Input Parameters

Name Type Definitionad_entity_id Double Entity identifier for the component to be updated

as_client_key String Specifies the value that the client key will be changed to

Output Parameters

retval Short 1 = success; -1 = failure

f_set_ownership_groupHRESULT f_set_ownership_group( [ in ] BSTR as_group_name, [ in, out ] VARIANTARG * as_error, [out, retval]VARIANT_BOOL * retval );

Description: This function will set the active ownership group for the currently active COM session.



Input Parameters

Name Type Definitionas_group_name String The group name to be assigned to the current session.

as_error String Reference argument that will contain a value if the function returnsFalse.

Output Parameters

Name Type Definitionretval Boolean True = Ownership Group was set; False = Ownership Group was

not able to be set. As_error will explain the reason.

f_set_pointee_attributeHRESULT f_set_pointee_attribute( [ in ] double ad_custom_rule_use_id, [ in ] double ad_prod_id, [ in ] doublead_entity_id, [ in ] double ad_rule_relation_id, [out, retval] short * retval );

Description: This function attempts to edit the attribute value of a pointee component and all of it's descendantswith the value specified in the setup for processing option #1514 - set_pointee_attribute_value. The processing op-tion must be applied to the edit view component that is passed in as the prod_id/entity_id/rule_relation_id identifierfor this function to have any effect. This function is recursive, and subsequent pointer/pointee pairs are traversed.Pointees and thier descendants that have the attribute specified in the arguments of the processing option will in turnhave their attribute value set as well.

Input Parameters

Name Type Definitionad_custom_rule_use_id Double The specific custom_rule_use_id for processing option #1514 -

set_pointee_attribute_value - when applied to an edit view compo-nent. This function is used by internal Vasont processes and isprobably not useful to other users of the Vasont API. It is only in-cluded in this list in the interest of full disclosure.


ad_entity_id Double Identifies component


Output Parameters

Name Type Definitionretval Integer This function always returns 0.

f_set_raw_idHRESULT f_set_raw_id( [ in ] double ad_entity_id, [ in ] double ad_raw_id, [ in, out ] VARIANTARG * as_error,[out, retval] VARIANT_BOOL * retval );



Description: This function updates the component (specified by entity_id) with the ad_raw_id. If unable to update,FALSE is returned and as_error is filled with the failure reason.

Input Parameters

Name Type Definitionad_entity_id Double Identifies entity to be updated

ad_raw_id Double Identifies raw material to be updated

as_error String Reason if update fails

Output Parameters

Name Type Definitionas_error String Reason for update failure

retval Boolean True or False. (If error occurs, check reference argument, as_error).

f_set_review_commentsHRESULT f_set_review_comments( [ in ] BSTR as_reviewer_comments_xml, [ in, out ] VARIANTARG * as_er-ror_message, [out, retval] short * retval );

Description: This method will store a reviewer's comments and replies to the database. The tables that will be upda-ted are review_comment and review_comment_reply. This method will receive an XML string as an argument,which will contain all the comment and reply information. This will be used in <oXygen/> by the Share Commentsbutton.

Input Parameters

None

Output Parameters

<comment>Name Type Definitioncomment_id Double Unique identifier for each comment. This is optional. For new

comments, this will not be known and not included in the XML.

pi_type String Each comment has a start and end point in the XML and each ofthose will relate to a separate comment tag. This determines wheth-er the comment tag relates to the start or end processor instruction.s (start), e (end).

offset Double Offset in the XML file for the processor instruction

guid Double Unique identifier for each comment. Note that the guid value willmatch for two comment tags related to each comment.

text String The text of the comment



<reply>Name Type Definitionreply_id Double Unique identifier for each reply. This is optional. For new replies,

this will not be known and not included in the XML.



XML format expected in variable as_reviewer_comments_xml:

<user_review_comments reviewer_id=”98” review_id=”100”> <review_comments> <comment offset=”5” type=”s” text=”COMMENT4” guid=”xx4”/> <comment offset=”10” type=”s” text=”COMMENT5” guid=”xx5”/> <comment offset=”12” type=”e” guid=”xx4”/> <comment offset=”43” type=”e” guid=”xx5”/> </review_comments> <review_replies> <reply comment_id=”403” text=”Dee reply to Steve reply”/> </review_replies></user_review_comments>

In this example, the XML contained attributes to identify the reviewer (reviewer_id) and the review (review_id).This reviewer has two new comments and one reply to a comment made by another reviewer.

A reviewer may make comments or replies multiple times before completing their reviewer session. When subse-quent calls to this method are made by the same reviewer in the same review, the expectation is that all of the re-viewer comments and replies will be included. For example, assume a reviewer added three comments and thencalled this method (i.e., Share Comments button). Then the reviewer added an additional comment and again choseto Share Comments. In this case, all 4 comments would be passed.

Note: If a previously submitted comment by a reviewer does not exist in a subsequent call the assumption is that thecomment has been deleted and this method will remove it from the database.

f_set_task_commentHRESULT f_set_task_comment( [ in ] double ad_instance_id, [ in ] BSTR as_comment, [out, retval] short * re-tval );

Description: This function allows for the update of the related task instance comment field.

Input Parameters

Name Type Definitionad_instance_id Double Workflow task identifier

as_comment String Comment to update

Output Parameters




f_set_task_instance_attributeHRESULT f_set_task_instance_attribute( [ in ] double ad_instance_id, [ in ] double ad_attribute_link_id, [ in ]BSTR as_value, [out, retval] short * retval );

Description: This function sets the attribute value for the specific workflow instance/attribute.

Input Parameters

Name Type Definitionad_instance_id Double Workflow instance identifier


as_value String New value of attribute (if empty string is passed, any existing at-tribute values will be deleted from the database)

Output Parameters


f_set_usernameHRESULT f_set_username( [ in ] BSTR as_user, [out, retval] short * retval );

Description: This function sets the user name that the COM will use as the user of record in versioning. This will beused in subsequent calls to the instance of the COM object. For example, if VUI instantiates the COM, then thatspecific session of the VUI will be affected.

Input Parameters

Name Type Definitionas_user String The user name to set.

Output Parameters

Name Type Definitionretval Integer 1 = success; -1 = failure

f_submit_reviewer_changesHRESULT f_submit_reviewer_changes( [ in ] double ad_reviewer_id, [ in ] BSTR as_filename, [ in, out ] VAR-IANTARG * as_error_message, [out, retval] short * retval );

Description: This will be called from Oxygen when a reviewer wants to commit changes made to the database, butdoes not want to end their review. This may be done to allow other reviewers to view their markup or may be donesimply to save changes made to the local file to the database.



The as_filename argument will be a full path and file name. This will be the same file name as the root file namestored in the database reviewer_files table.

If any type of error occurs the reference argument of as_error_message will be populated. Examples of errors maybe bad ad_reviewer_id passed, filename not found, review is already completed, and so on.

Input Parameters

Name Type Definitionad_reviewer_id Double The identifying value for the reviewer.

as_filename String The full path and file that is being submitted.

Output Parameters




f_testHRESULT f_test( [out, retval] BSTR * retval );

Description: This function performs a communication test with the COM object and returns a simple string statingthat the communication was successful.

Input Parameters

None

Output Parameters

Name Type Definitionretval String Results of communication test

Example:

Dim ls_test As Stringls_test = targobj.f_testMsgBox (ls_test)Default URL Topic for WinHelp 2000 — do not edit

f_text_allowedHRESULT f_text_allowed( [ in ] double ad_raw_type_id, [out, retval] BSTR * retval );

Description: This function determines whether a component in the system is allowed to contain text.



Input Parameters

Name Type Definitionad_raw_type_id Double Raw material type identifier

Output Parameters

Name Type Definitionretval String o=Text is Optional

y=Text is Required

n=Text is Not Allowed

f_this_is_a_testHRESULT f_this_is_a_test( [ in ] BSTR as_test, [out, retval] BSTR * retval );

Description: This function performs a communication test with the COM object and verifies that the COM objectcan send and recieve String parameters. Whatever string is sent to it as as_text should be returned in retval.

Input Parameters

Name Type Definitionas_text String Test string sent to COM object

Output Parameters

Name Type Definitionretval String Results of communication test

Example:Dim Is_sent_string as StringDim Is_returned_string as String Is_sent_string = "This is only a test"Is_returned_string = apiobj.f_this_is_a_test( Is_sent_string)MsgBox( Is_returned_string) ' The message box should display This is only a test

f_translation_cloneHRESULT f_translation_clone( [ in ] double ad_primary_entity_id, [ in, out ] VARIANTARG * as_message, [out,retval] short * retval );

Description: The purpose of this method is to initiate the translation clone process for a component. This relies onthe called component being configured with the translation_clone processing option. This has the same effect as per-forming a translation clone in Vasont by right clicking on a component and choosing Translation Clone.



Input Parameters

Name Type Definitionad_primary_entity_id Double Identifies the Vasont component.

as_message String A textual description of the results of the process. Will include er-rors if the return value of the function is -1.

Output Parameters

Name Type Definitionretval Integer 1=success; −1=failure

f_undelete_entityHRESULT f_undelete_entity( [ in ] double ad_entity_id, [ in, out ] VARIANTARG * as_error_message, [out, re-tval] VARIANT_BOOL * retval );

Description: This function removes the pending delete status from a given entity.

Input Parameters


as_error_message String Error message

Output Parameters

Name Type Definitionas_error_message String Reason retrieval failed

retval Boolean True=success; false=failure

f_unregister_daemonHRESULT f_unregister_daemon( [ in ] const BSTR as_daemon_id, [out, retval] VARIANT_BOOL * retval );

Description: This function deletes a record (unregisters the daemon) from the active_daemon table for a given dae-mon.

Input Parameters




Output Parameters

Name Type Definitionretval Boolean indicates DELETE success or failure—record was successfully de-

leted if TRUE

f_update_daemonHRESULT f_update_daemon( [ in ] const BSTR as_daemon_id, [ in ] const short ai_items, [out, retval] VAR-IANT_BOOL * retval );

Description: This function UPDATES the active_daemon table with current SYSDATE (last_run) and addsai_items to items_queued. Note: ai_items may be negative (decrement items_queued) or positive (incrementitems_queued).

Input Parameters


ai_items Short Number of items to add or subtract from items_queued

Output Parameters

Name Type Definitionretval Boolean Indicates UPDATE success or failure

f_update_text_componentHRESULT f_update_text_component( [ in ] double ad_prod_id, [ in ] double ad_rule_relation_id, [ in ] doublead_entity_id, [ in, out ] VARIANTARG * as_text, [out, retval] double * retval );

Description: This function updates a text component, i.e., a component whose raw class is text. If inline compo-nents exist, they are automatically updated based on changes in the text. For example, if the component has inlines,and an inline has been added or deleted, the children components are updated accordingly.

Input Parameters




as_text String Updates text for component

Output Parameters

Name Type Definitionas_text String Value can be changed by function



Name Type Definitionretval Double If successful, returns raw id created and written to component.

−1=failure.

f_validate_required_attributesHRESULT f_validate_required_attributes( [ in ] double ad_instance_id, [ in, out ] VARIANTARG * as_error, [out,retval] short * retval );

Description: This function allows any required attributes for a given task_instance to be validated as populated.

Input Parameters

Name Type Definitionad_instance_id Double Task instance id

as_error String Returned by reference to the caller along with the return value

Output Parameters

Name Type Definitionretval Short 0=success; -1=failure

as_error String error message if failure occurs

f_where_usedHRESULT f_where_used( [ in ] double ad_raw_id, [out, retval] LPDISPATCH * retval );

Description: This function returns all collection uses for the specified raw_id.

Input Parameters

Name Type Definitionad_raw_id Double Identifies raw material to be checked for usage

Output Parameters









Name Type Definition Date entity_status_date (date component was last edited)













Low-Level API SampleApplication

Finding Users for a Collection in VB.NET• This sample, written in VB.NET, allows the user to log into the Vasont database, select a collection and view a

list of users who have access to it. Although this functionality exists in the Vasont Administrator application, endusers who do not have access to the administrator application might find this information useful.

• Prerequisites

1. Vasont should be installed on the development machine.

2. The developer should have a valid Vasont login with access to at least one collection for testing purposes.

Creating the VB.NET Solution1. Start Visual Studio (our sample uses Visual Studio 2005). Click the Create Project link.



2. Choose to create a Visual Basic Windows application. Name it and select a folder location. Then click OK.

3. Visual Studio creates a basic application shell.

Low-Level API Sample Application


Creating the User Interface1. If the .NET Form Designer is not already visible use the Solution Explorer to display it. Just right-click on

Form1.vb and choose View Designer.

2. Add two Label controls and two Listbox controls. Name them and position them as shown.

3. Change the Sorted property for each listbox from False to True.



Adding a Reference to the Vasont Low-Level API1. Click on the Project menu and choose Add Reference.

2. Click on the COM tab and choose PB105 typelib for: vasont_com.dll.



Instantiating the API1. On the Solution Explorer tab right-click Form_1.vb and choose View Code.

2. Add the highlighted code to the declarations section of the form. This will create a variable for referencing thelow level API.

3. Now switch back to the Form Designer. Click on the title bar of the form. From the Properties tab, click on theEvents icon.

4. Double-click on the Load event.



5. .NET will create an event handler for the Load event and open the code window to it. You just need to add thehighlighted code.

Logging InIn a real application when we wanted the user to log in we would pop-up a log in dialog and ask the user for username and password. As this is a sample application we will hard code the user name and password.

1. Add some global variables to the form that will supply login credentials.

2. Add a new Sub called Login.

For your application to function, substitute username, password and profile strings that will work for your Vas-ont installation.

3. And add a call to Login in the Form1_Load event handler you created earlier.

Getting a Collection ListOur first task is to fill in the top list box. We need to populate it with all the collections to which our logged in userhas access. The API call that does this is f_get_user_prod_xml which takes a username and returns an XML string.

2 A helpful nomenclature hint: Internally Vasont uses the word “product” when it means “collec-tion”. You will see the word “product” or its abbreviation, “prod” throughout the API and its docu-mentation.

The XML looks something like this: <user.access user="Username"> <content.type id="12345"> <name>My content type</name> <product id="55574">



<name>This is the first collection name</name> <abbrev>First</abbrev> </product> <product id="43574"> <name>This is the second collection name</name> <abbrev>Second</abbrev> </product> </content.type> </user.access>

After we call the API method, our code will use VB.NET's XML methods to parse the collection XML and populatethe list.

1. Add a function that takes a username and returns a collection of collection name strings. We make this a gener-ic function so we can reuse it later.

2. Add a subroutine that calls the function and populates the listbox.

3. Call the sub from the form load event handler.

Getting a List of UsersTo get a list of all users we use the API function f_get_users. This function returns a recordset.

2 Recordsets and the Vasont low-level API: Many API calls return Microsoft ADO recordsets. A re-cordset is a COM object that can be passed by a COM object.

1. Add a reference to Microsoft's ADO.



• Click on the Project menu and choose Add Reference.

• Click on the .NET tab and select adodb then click OK.

2. Add a member variable to the form.

3. Create a subroutine to populate the recordset.

4. Add a call to the sub in the form load event handler.



Creating a Class to Hold User CollectionsThis simple class is used to hold the data for each user. We will then create a collection of these objects which willcontain all users and all their collections.

1. In the Solution Explorer right-click on the project and choose Add/Class.

2. Name the class UserCollections and add the member variables - username and collectionlist.

Populate a Collection of User Collection Objects1. Add a member variable to the form that holds the collection of user collection objects.



2. Add a subroutine to populate the collection.

3. Add a call to the new subroutine in the form load event handler.

Displaying a List of Users for the Selected CollectionEach time our user selects a collection from the top list box, a list of valid users for the selected collection will befilled in the bottom list box.

1. Click on the form design tab and double-click on the top list box to create an event handler.



2. VB.NET will create an event handler for the CollectionsListBox SelectedIndexChanged event and open thecode window to it. Add this code to the event handler.

Running the Application and Programming Notes• The application is now completely coded. Click the run button to test it.

• This is a sample application. The focus on its design was on how to best demonstrate working with the Vasontlow-level API not on how to make a production-ready application.

Therefore many shortcuts were made that would not be chosen in a production application. It does not performerror handling. It does not take into consideration limited memory issues. In fact we are storing a lot of informa-tion in memory in a relatively expensive manner. User credentials are hard coded but in a production applicationthe user would be prompted for credentials.



User Defined ProcessingOption Template in VB 6

User Defined Processing Options (UDPOs) can be implemented via COM Objects. COM Objects can extend Vasontby making calls to native DLL's, other COM Objects, such as the Vasont API. A COM object can be implementedvia any development tool that supports COM object generation such as Visual Basic or Visual C++.

A COM Interface has been defined that allows users to create their own COM Object(s) that can be attached toevents using the Vasont Administrator. The COM Interface is defined below as well as an example of how to createa User Defined Processing Option in Microsoft Visual Basic.

For more information see the Vasont Processing Options Guide.

Code TemplateThe following example will produce a skeleton for a User Defined Processing Option. You can use the skeleton tocreate your own UDPOs.

The following code is divided up into a header and 5 functions. All should appear in a single class module.

• Header:



• SetData function

• PerformAction function

• GetData function

User Defined Processing Option Template in VB 6


• RequiresAPIObject function

• SetAPIObject function



Applying the UDPOThis example UDPO has been set to fire when a Recipe is updated. It will prompt the user with a window, which iscreated inside the UDPO, to update the “publishable” attribute on the Recipe. The following screenshots show theapplication of the UDPO to a Vasont collection. This setup is done in the Vasont Administrator.

To test in Vasont, right-click on a Recipe and select Open Update. Click on the Attribute button to display theAttributes and their current values. Notice that the “Publishable” attribute has a value of “Yes”.



Now change the content from “Baked Beans” to “Barbecue Baked Beans”.

Click on the Save button. A window will appear requesting that a value be chosen for the “Publishable” attribute.The drop-down list can be used to select Yes or No. The UDPO is generating this window.

Click on OK to dismiss the Select A Value window. The VasontUDPOExample window will appear, confirmingthat the attribute was successfully updated.

Click on the Attributes button to display the Attributes and their current values. Notice that the “Publishable” attrib-ute now has a value of “No”.



Using the High-LevelApplication Programming

InterfaceThe High-Level Application Program Interface (API) is used to provide access to certain Vasont functions. Any pro-gramming language that can access COM objects can call these functions. Some functions provide a user interfacesimilar to the UIs provided by the Vasont Universal Integrator (VUI).

2 Prerequisite: The high-level API is only available for development if one of the VUI versions is pur-chased and installed.

To use the High-Level API, call the functions from any programming language that has the capability to accessCOM objects. This may be a language like C++, Visual Basic, Visual Basic For Applications, VB Script, PowerBuilder, Delphi, or active server web pages. Before using the High-Level API, it might be advantageous to look atthe VUI guide to discover what it can do.

Also become familiar with the Vasont Administrator. Many arguments used by the API functions can be found inVasont Administrator. Understanding Vasont Administrator's setup for a collection is imperative before using theAPI to access it. Learn about Collections, Edit, Extract and Load Views, Attributes, Rule Relation ID's, VersionID's, etc. The Vasont Administrator manual goes into more detail on how it can facilitate the use of the API.

The basic methodology for the high-level API is to instantiate the Vasont Universal Integrator COM object(vsntntgrtr.dll) and then call the Init method. Finally call any other methods. Upon making the first method call, VUIwill pop-up a login dialog. If the end user successfully logs in, then the function will execute.



Using the High-Level Application Programming Interface


List of High-Level APIFunctions

Extract And LoadExtractIntoEditor( )ExtractToFile( )UpdateVasont( )UpdateVasontNoExtract( )

Low-level Interface AccessGetContainedInterface( )

LogIn and InformationAbout( )CheckDBConnection( )ConnectUsingProfile( )DisconnectFromDB( )

User InterfaceOpenNavigator( )OpenWorkflow( )

AboutHRESULT About( );

Description: This function displays an About box that includes versions of Vsntntgrtr.dll Vasont_com.dll (if loggedin) VasontLdObj.dll and the database version (if logged in). It can also display Version information from your call-ing program if that program supports the IVUIDocEditorLink interface. The function has no input or output parame-ters.

CheckDBConnectionHRESULT CheckDBConnection( [out, retval] VARIANT_BOOL* retval );

Description: This function is used to verify that we are connected to the database and successfully logged in.



Input Parameters

Name Type Definitionretval VARIANT_BOOL* Pointer to the return value

Output Parameters

Name Type Definitionretval VARIANT_BOOL* Returns VARIANT_TRUE if connected to database and

VARIANT_FALSE if not.

ConnectToDBHRESULT ConnectToDB( [out, retval] VARIANT_BOOL *vbRet );

Description: This function is used to log in to Vasont. If we are already logged in then this function just returnstrue. If we are not logged in then this function pops up a login dialog. If the user successfully logs in than the func-tion returns true.

Input Parameters

Name Type DefinitionvbRet VARIANT_BOOL* Pointer to the return value

Output Parameters

Name Type DefinitionvbRet VARIANT_BOOL* Returns VARIANT_TRUE if the user logged in successful-

ly or was already connected to database and VAR-IANT_FALSE if not.

ConnectUsingProfileHRESULT ConnectUsingProfile( [ in ] BSTR bstrUser, [ in ] BSTR bstrP, [ in ] BSTR bstrProfile );

Description: This function is used to log into the database when your program has already connected login creden-tials and does not need to popup a login dialog. There are no output parameters indicating success. Use CheckDB-Connection() to verify successful login.

Input Parameters

Name Type DefinitionbstrUser BSTR A valid Vasont username

bstrP BSTR A valid password for the username

bstrProfile BSTR User's Profile - find this in VasontApps.ini or in the Vasont logindialog.

List of High-Level API Functions


CreateNewComponentFromTemplateHRESULT CreateNewComponentFromTemplate( [ in ] VARIANT *varExtrFileName, [out, retval] int *iRet );

Description: This function (used to implement Vasont's create_new_from_template Processing Option) createsnew content in a target collection based on a hierarchical template stored in a separate Vasont collection. The tem-plate can contain any mix of components (with boilerplate text, if desired.)

This function will:

• Display a wizard and allow the user to pick a template collection.

• Call the low-level API function f_create_new_from_template which actually creates a new primary componentthat is a copy of the template.

• Display a second wizard that prompts the user to pick an extract view (if there is more than one for the collec-tion).

• Extract to a file on the file system and return its name.

Input Parameters

Name Type DefinitionvarExtrFileName VARIANT * Points to a VARIANT of type VT_BSTR that will hold the file-

name of the extracted new component

iRet int * Points to a return value.

Output Parameters

Name Type DefinitionvarExtrFileName VARIANT * Holds the filename of the extracted new component if successful or

an error message if not.

iRet int * 1 if successful. -1 if not.

DisconnectFromDBHRESULT DisconnectFromDB( [ in, out ] int *iSuccess );

Description: This function logs off from the Vasont database.

Input Parameters

Name Type DefinitioniSuccess int* Pointer to return value.

Output Parameters

Name Type DefinitioniSuccess int* Returns 1 if previously logged in and successfully disconnected.

Returns 0if not previously logged in or failed to disconnect.



ExtractIntoEditorHRESULT ExtractIntoEditor( [ in ]double dblEntityID, [ in ] double dExtractID, [out, retval] int *iRet );

Description: This function will extract a component from the Vasont database and automatically open it in the hostprogram.

2 • This function should be used when you can determine the entity ID and extract version ID pro-grammatically. Normally you would use allow the user to do an extract from the Navigator win-dow (see the OpenNavigato() function.)

• To properly extract into your host program, it must support the IVUIDocEditorLink interface.

Input Parameters

Name Type DefinitiondblEntityID double Vasont ID for the component to extract.

dblExtractID double The extract view identifier.

iRet int* Pointer to the return value

Output Parameters

Name Type DefinitioniRet int* Returns 1 if successful or -1 if failed.

ExtractToFileHRESULT ExtractToFile( [ in ]double dblEntityID, [ in ] double dExtractID, [ in ] BSTR bstrExtractPath, [out, re-tval] BSTR* pbstrError );

Description: This function will extract a component from the Vasont database, place it in the path specified andautomatically open it in the host program. This function performs the same as ExtractIntoEditor but will place theextracted fiel in a specific folder rather than Vasont's default extract folder.

2 • This function should be used when you can determine the entity ID and extract version ID pro-grammatically. Normally you would use allow the user to do an extract from the Navigator win-dow (see the OpenNavigato() function.)

• To properly extract into your host program, it must support the IVUIDocEditorLink interface.

Input Parameters

Name Type DefinitiondblEntityID double Vasont ID for the component to extract.

dblExtractID double The extract view identifier.



Name Type DefinitionbstrExtractPath BSTR The full path name for the extract location.

pbstrError BSTR* Pointer to a BSTR that will hold the any error messages.

Output Parameters

Name Type DefinitionpbstrError BSTR* Contains an error message if failed or is empty if successful.

GetContainedInterfaceHRESULT GetContainedInterface( [out, retval] IDispatch **ptrDispatch );

Description: This function retieves a pointer to the low-level API interface.

Input Parameters

Name Type DefinitionptrDispatch IDispatch** A pointer to an IDispatch interface pointer

Output Parameters

Name Type DefinitionptrDispatch IDispatch** On return contains an IDispatch interface pointer or NULL

GetUserPreferenceHRESULT GetUserPreference( [ in ] BSTR bstrPreferenceName, [ in, out ] BSTR* bstrPreferenceValue );

Description: This function, given a preference name will return a preference value. Use this function in conjunctionwith SetUserPreference() to store and retrieve and user-specific, machine-specific values that your program mayneed. User preferences are stored in the Windows Registry in the HKEY_CURRENT_USER\Software\Vasont\Pref-erences key.

Input Parameters

Name Type DefinitionbstrPreferenceName BSTR The name of the user preference to retrieve

pbstrPreferenceValue BSTR* Pointer to the return value that will hold the preference value

Output Parameters

Name Type DefinitionpbstrPreferenceValue BSTR* Returns the preference value or NULL if preference name not

found



GetValueFromExtractPIHRESULT GetValueFromExtractPI( [ in ] BSTR as_pi, [ in ] BSTR as_entry, [out, retval] BSTR* retval );

Description: This function (typically used in an external XML Editor such as Arbortext Editor, FrameMaker orXMetaL) extracts the value for a particular entry in the Vasont extract Processing Instruction (PI). The Vasont ex-tract PI, embedded in an extracted XML Instance using the embed_extract_info_pi processing option, contains keyinformation regarding what was extracted from Vasont (and how the extract was performed). The information (en-tries) included in the Vasont Extract PI consist of:

entity_id (always present): Contains Vasont's internal identifier (Entity ID) for top-most component extracted.

version_id (always present): Contains Vasont's internal identifier (Version ID) for the extract view used for ex-tract.

snapshot_file (optional): If create_fast_load_snapshot processing option was placed on extract view (to en-able fast loading of altered content), contains name of fast load “snapshot” file cre-ated by Vasont.

selected_langs (optional): If language selection processing option was placed on extract view (e.g., get_selec-ted_lang_attribs or get_selected_lang_components), contains pipe (“|”) delimitedstring of language(s) selected for extract.

This function allows the user to obtain the value for any of these entries.

Input Parameters

Name Type Definitionas_pi BSTR Contents of Vasont extract PI - Parameter can contain entire PI

(e.g.,<?VasontExtractInfo entity_id=“9999” version_id=“9999”?>)or just content that is obtained from data property on DOM PI.

as_entry BSTR Entry, as defined in table in Description section above, for whichvalue is to be obtained

retval BSTR* Return value

Output Parameters

Name Type Definitionretval BSTR* Value, from Vasont extract PI, for entry specified. If entry not

present in Vasont extract PI, empty string is returned.

InitHRESULT Init( [ in ] BSTR bstrEditor )

Description: This function should be called before other function calls to the high-level API. It is used to initiazethe API and allows the API to call your custom application to open files, paste text, and perform other specializedwork.



2 • There are two registry entries that you need to make to successfully utilize this function with yourcustom application. The entries should be added to HKEY_LOCAL_MACHINESOFTWARE\Progressive Information Technologies\VUI\{the name you called Init with}

1. WindowName - The name that appears in the titlebar of your custom application

2. Program - the COM progID of your custom application (or a COM helper application.)

Input Parameters

Name Type DefinitionbstrEditor BSTR A name for your custom application that matches a registry entry

(see above.)

InvokeVasontHRESULT InvokeVasont();

Description: This function will open the Vasont application if it is installed on the PC. It has no input or putputparameters.

OpenNavigatorHRESULT OpenNavigator();

Description: This function will open a wizard that allows the end user to choose a collection and displays that col-lection in a non-modal window that is a child of your application. The function takes no input or output parameters.

2 • The resultant navigator window allows the user to access many high-level functions such as ex-tracting content, drag and drop copy, viewing content and attributes and checking out and in con-tent.

• You may open more than one navigator at a time by calling this function multiple times. Thisgives users the ability to darg and drop between collecitons.

• This window will be closed and its memory cleaned up by the high-level API when the high-levelAPI COM object is destroyed by your program.

OpenWorkflowHRESULT OpenWorkflow();

Description: This function will open a non-modal window workflow window that is a child of your application. Thefunction takes no input or output parameters.



2 • The resultant window allows the user to access many high-level functions such as adding com-ments, completing tasks and reassigning tasks.

• You may open more than one workflow window at a time by calling this function multiple times.

• This window will be closed and its memory cleaned up by the high-level API when the high-levelAPI COM object is destroyed by your program.

PickConrefIntoEditorHRESULT PickConrefIntoEditor( [ in ]double dblEntityID, [ in ] double dExtractID, [ in ] BSTR bstrParentTags,[ in ] BSTR bstrChildTag, [ in ] BSTR bstrFilePath, [out, retval] BSTR* pbstrAttrib );

Description: This function will allow the user to choose a component of the same type as the current element, ex-tract the conref file and create a conref attribute for insertion into the element.

Input Parameters

Name Type DefinitiondblEntityID double The entity ID of the primary component. This value can be retieved

from the return value of GetValueFromExtractPI.

dblExtractID double The extract view identifier. This value can be retieved from the re-turn value of GetValueFromExtractPI.

bstrParentTags BSTR The element names of the parent heirarchy of the current element.The list of tags begins with the current element's direct parent andproceeds up the heirarchy until it reaches the root element. Elementnames must be pipe delimited.

bstrChildTag BSTR The tag name of the current element that you wish to make a conreffor.

bstrFilePath BSTR The file path to place the extracted conref XML file.

pbstrAttrib BSTR* A pointer to the BSTR that will hold the conref attribute value onsuccessful return.

Output Parameters

Name Type DefinitionpbstrAttrib BSTR* A pointer to the BSTR that holds the conref attribute value on suc-

cessful return. If this value is empty the function failed or the userchose to cancel.

PickHrefIntoEditorHRESULT PickHrefIntoEditor( [ in ] BSTR bstrOptionalExtension, [out, retval] BSTR* pbstrHREF );

Description: This function will allow the user to choose a component from Vasont, extract it, and create an hrefattribute for insertion into the element.

Here is the program flow you would use when calling this function:



1. The calling editor script determines if an href attribute is allowed at the cursor location.

2. If so then it enables the menu choice Pick DITA href link.

3. If the user pick the menu choice then the script calls PickHrefIntoEditor passing the extension to be used for thefilename if the extension is not .xml

4. The user then get a wizard similar to the conref wizard but there is no choice of list or tree - its always a treeand any component in the tree the user picks can be used so all components have check marks and once theuser picks a component the function returns with the value for the href attribute

5. We use the client key of the component and its primary to form the href in a format like this example: If thecomponent's client key is v12345 and its primary is v123 then the method returns "v123.xml#v123/v12345"

6. If the component is a primary then the href is simplified. Example: If the component's client key is v123 and itis a primary then the method returns "v123.xml"

7. There are two exceptions to the extension used in 5 and 6:

• If the component is multimedia primary then if the client key has an extension use it as the filename exten-sion otherwise use the MM extension as the filename extension

• If the editor script passed in an extension use it instead of .xml (the first exception overrides this one).

Input Parameters

Name Type DefinitionbstrOptionalExtension BSTR The file extension to use for the extracted HREF. If this parameter

is empty then .XMl is used by default.

pbstrHREF BSTR* A pointer to the BSTR that will hold the HREF attribute value onsuccessful return.

Output Parameters

Name Type DefinitionpbstrHREF BSTR* A pointer to the BSTR that holds the HREFattribute value on suc-

cessful return. If this value is empty the function failed or the userchose to cancel.

PickListIntoEditorHRESULT PickListIntoEditor( [ in ] double dEntityID, [ in ] double dExtractID, [ in ] BSTR varParentTag, [ in ]BSTR varChildTag, [ in, out ] VARIANT *varPickedXML, [out, retval] double* dRet );

Description: This function will allow the user to choose a component of the same type as the current element, createa new Vasont component and return its text for insertion into the XML. The function works differently dependingwhether the element is a Vasont text component, pointer component or multimedia component.

Input Parameters

Name Type DefinitiondEntityID double The entity ID of the primary component. This value can be retieved

from the return value of GetValueFromExtractPI.

dExtractID double The extract view identifier. This value can be retieved from the re-turn value of GetValueFromExtractPI.



Name Type DefinitionbstrParentTags BSTR The element names of the parent heirarchy of the current element.

The list of tags begins with the current element's direct parent andproceeds up the heirarchy until it reaches the root element. Elementnames must be pipe delimited.

bstrChildTag BSTR The tag name of the current element that you wish to make a conreffor.

varPickedXML VARIANT* A pointer to a VARIANT that will hold the XML for the new ele-ment.

dRet double* A pointer to a double that will contain the return value.

Output Parameters

Name Type DefinitionvarPickedXML VARIANT* A pointer to a VARIANT that will hold the XML for the new ele-

ment.

dRet double* A pointer to a double that contains the return value. Values are in-terpretted as follows - 1 = Pointer - like an HREF. 2 or 3 = Pointerto modular content - the returned XML contains multiple elements- not just text. 4 = Text - the returned XML contianed text to beplaced in the element. 5 = Multimedia - the returned XML containsthe name of the extracted multimedia file and should be placed inan attribute of the multimedia element. 0 = The cursor was on anelement that Vasont does not track. An appropriate error messageshould be displayed.

RegisterOpenExtractCallbackHRESULT RegisterOpenExtractCallback( [ in ] long ptrExtractCallback );

Description: This function will allow the developer to define a function in their code that takes a pointer to a BSTRthat the API will call when an extract has happened. The BSTR* will contain the extract text.

Input Parameters

Name Type DefinitionptrExtractCallback long Pointer to a function in your code.

RegisterSaveCallbackHRESULT RegisterSaveCallback( [ in ] long ptrSaveCallback );

Description: This function will allow the developer to define a function in their code that takes a pointer to a BSTRthat the API will call when it wishes to know the name of the document file. The BSTR* will contain the filenameand path.



Input Parameters

Name Type DefinitionptrSaveCallback long Pointer to a function in your code.

RegisterVersionCallbackHRESULT RegisterVersionCallback( [ in ] long nVersionCallbackProc );

Description: This function will allow the developer to define a function in their code that takes a pointer to a BSTRthat the API will call when it wishes to display version information. The BSTR* will contain the version informationof your application.

Input Parameters

Name Type DefinitionnVersionCallback long Pointer to a function in your code.

SetUserPreferenceHRESULT SetUserPreference( [ in ] BSTR bstrPreferenceName, [ in ] BSTR bstrPreferenceValue );

Description: This function, given a preference name and value will set it in the Windows Registry. Use in conjunc-tion with GetUserPreference() to store and retrieve and user-specific, machine-specific values that your programmay need. User preferences are stored in the Windows Registry in the HKEY_CURRENT_USER\Software\Vasont\Preferences key.

Input Parameters

Name Type DefinitionbstrPreferenceName BSTR The name of the user preference to store

bstrPreferenceValue BSTR The preference value to store

UpdateVasontHRESULT UpdateVasont( [ in ] double dEID, [ in ] VARIANT varFilename, [ in ] VARIANT *varError, [out, re-tval] int *iRet );

Description: This function will update the Vasont database with the file. It overwrites existing content with the re-vised XML file. The file must have been originally extracted from Vasont. After a successful update the functionwill prompt the user to re-extract so they can continue to edit.

Input Parameters

Name Type DefinitiondEID double The entity ID of the root element.



Name Type DefinitionvarFilename VARIANT A variant of type VT_BSTR that contains the name and path of the

file to load into Vasont.

varError VARIANT* A pointer to a variant of type VT_BSTR that will return any errormessage.

iRet int* Pointer to an int that will hold the return value.

Output Parameters

Name Type DefinitionvarError VARIANT* A pointer to a variant of type VT_BSTR that will contains any er-

ror message.

iRet int* Pointer to an int that will hold the return value. 0 indicates success.-1 indicates failure.

UpdateVasontNoExtractHRESULT UpdateVasontNoExtract( [ in ] double dEID, [ in ] VARIANT varFilename, [ in ] VARIANT *varError,[out, retval] int *iRet );

Description: This function will update the Vasont database with the file. It overwrites existing content with the re-vised XML file. The file must have been originally extracted from Vasont. This function is identical to UpdateVa-sont except that it does not perform a reextract.

Input Parameters

Name Type DefinitiondEID double The entity ID of the root element.

varFilename VARIANT A variant of type VT_BSTR that contains the name and path of thefile to load into Vasont.

varError VARIANT* A pointer to a variant of type VT_BSTR that will return any errormessage.

iRet int* Pointer to an int that will hold the return value.

Output Parameters

Name Type DefinitionvarError VARIANT* A pointer to a variant of type VT_BSTR that will contains any er-

ror message.

iRet int* Pointer to an int that will hold the return value. 0 indicates success.-1 indicates failure.



High-Level API SampleApplication

A Vasont Browser in C#• This sample, written in C#, allows the end user to select collections and display navigators. It is a simple exam-

ple of how easy the high-level API makes Vasont coding.

• Prerequisites

1. Vasont should be installed on the development machine.

2. The developer should have a valid Vasont login with access to at least one collection for testing purposes.

Creating the C# Solution1. Start Visual Studio (our sample uses Visual Studio 2005). Click the Create Project link.



2. Choose to create a C# Windows application. Name it and select a folder. Then click OK.

3. Visual Studio creates a basic application shell.

High-Level API Sample Application


Creating the User Interface1. If the .NET Form Designer is not already visible use the Solution Explorer to display it. Just right-click on

Form1.cs and choose View Designer.

2. Add a single button control, chang its text and change the text of the form.



Adding a Reference to the High-Level API1. From the Solution Explorer right-click the References item and choose Add Reference.

2. Click on the COM tab at the top of the Add Reference dialog box and find the vasont_universal_integrator 1.0Type Library. Select it and click OK.

Instantiating the API1. On the Solution Explorer tab right-click the Form1.cs file and choose View Code.

2. Add a variable to hold the instantiated API and name it vui.



3. In the Form1 constructor add code to set the variable to a new instance of the API.

Responding to the Button Click1. If its not already visible open the Form Designer.



2. Double-click on the Open a Navigator button. Visual Studio creates the event handler and opens the code win-dow.

3. Add the code to the event handler that will open a navigator.

Testing the application1. Press F5 to start the application.

2. When the application starts, click the Open a Navigator button.

3. A Vasont login dialog should appear. Enter a valid Vasont username and password.



4. The Vasont collection selection wizard starts.



5. Follow the wizard steps and a Navigator window will open. Go back to the application and click Open a Navi-gator again. This time you go straight to the wizard, bypassing the login dialog. Choose another collection.Both Navigators are available. Position the Navigator windows so they are both visible.



GlossaryActive Content The content that you see in the Vasont navigator. In the versions window, the

active content is represented as the [Current] version.

Aliases Additional names that are assigned to a raw component. For instance, Authorand Screenwriter could be aliases for a raw component named Writer. Aliasespromote content reuse since the content is stored once regardless of which aliasis used.

Analyze A right-click option that may be performed on a component in Vasont. The com-ponent is validated against the rules that have been established in the VasontAdministrator for this type of component.

Annotation Textual information and/or multimedia attachments associated with any collec-tion-level component.

Approved Status Components that are considered ready for publishing or in a final form.

Argument In the Vasont Administrator, Processing Options have arguments. Arguments al-low values to be passed to the programming code to make the processing optionbehave as desired. Arguments are also used in the Vasont API Functions.

Associate Administrator This is a privilege that the super administrator assigns to another Vasont Admin-istrator user. It allows the user to oversee and make changes to specific collec-tions in the Vasont Administrator.

attribute_link_id A special Vasont number that identifies an attribute for a component.

Attributes An additional piece of information for a component. This includes attributesfrom a DTD, but can also be metadata attributes that are strictly used by Vasontfor special behaviors.

Batch Update A utility that allows an operation to be run against to many different componentsin one pass. For example, adding a language attribute to Section, Title and Para-graph. Another example is using batch load or extract.

BLOB A data format called Binary Large Object. All Vasont multimedia componentsare stored in Vasonts BLOBs.

Bookmarks A shortcut to find information. A right-click option in Vasont navigator that al-lows a user to mark the location of a component for future reference.

Branch A copy of modular content that maintains a link to the source from which it wascreated.

Branch Label A label that is assigned to a Branch when it is created. It identifies the Branchwhen viewed in the collection navigator or the Details pane.

Branch Notice An icon that is placed on a pointer component that points to a primary that iscopied for a Branch. It signifies that the original pointee is the source of a newBranch, and that the owner of the pointer may want to review the content anddetermine the Branch that they would like their pointer to reference.

Branch Notification A special Notification that is sent when content that is owned by the user con-tains a pointer to content that is involved in a Branch.

Check In A right-click option in the Vasont navigator that allows a user to unlock contentthat they have had checked out.



Check Out A right-click option in Vasont navigator that allows a user to lock down contentthat they are currently editing or modifying. No other user can update the con-tent in the database when it is checked out.

child_entity_id A special Vasont number that identifies a component's child

child_rule_relation_id A special Vasont number that identifies the child component of another compo-nent.

Client Key Vasont's external user defined identifier for a component.

Clone A copy of content or structure.

Collaborative Review A Vasont extension program that allows content to be critiqued through the useof comments left by Reviewers. An Editor accepts or rejects the Reviewers com-ments and marks up the content as necessary. When the editorial phase is com-pleted the database is updated with the accepted changes.

Collection A group of similar content that shares the same content model.

Collection Access Collections that are available to a user.

Collection Groups A named grouping of one or more collections.

Comment Meaningful notes or text that can be added to an active workflow task or to acomponent's version. These notes help to define instructions or informationabout the task or version that they are placed on.

Component An instance of content in a content model such as a paragraph in a manual.

Composite Extracts/Loads A right-click option in the Vasont navigator that allows for the extraction orloading of content into or from XML or SGML files on a file system.

Content Model A DTD, Schema, or well formed hierarchy of content that defines how contentcomponents are structured and their rules of behavior.

Content Navigator The window in the Vasont Administrator that is used to navigate, view, create,and update collections content models for Vasont.

Content Owner A user or group of users who have been assigned exclusive permission to a pri-mary component in a collection. This ownership restricts other users from mak-ing any alterations to the component and its descendants.

Content Types A set of related Vasont collections that share the same raw components, attrib-utes and wrappers.

Create New A right-click option in the Vasont navigator that allows a user to add new com-ponents to the database.

Draft Status Components that have a yellow pencil icon. These components have been al-tered after being approved.

Dynamic Indexes Index collections that are maintained dynamically with an associated compo-nent(s) in another collection. For example, a Book collection may contain thenames of several Authors. An Index collection may be created from the Bookcollection of the Authors and the Books where they appear.

Edit View The definition for creation, display, processing, and manipulation of content orentities within the Vasont Administrator Program.

Editor A user who is assigned the responsibility of accepting or rejecting Reviewers'suggestions and comments and finalizing the edits in the Vasont CollaborativeReview.

entity_id A special Vasont number that identifes a specific instance of a component in aspecific collection.

Glossary


Events Intervals in the programming code that allow for the insertion of Vasont pro-cessing options. Vasont has over 60 defined events such as Post Load, Pre Ex-tract, Post Approval etc.

Extract View The rules for preparing and processing the content to an extracted SGML orXML file. This is done in the Vasont Administrator.

filter_id A special Vasont number that identifies a saved query.

Global Change Vasont's ability to identify all instances where a component is used, and if nee-ded, change the content for all uses, some uses, or no uses when an update oc-curs. Implicit reuse facilitates global change.

Granularity The level at which data is stored in Vasont. A very detailed configuration willstore and track a large number of the elements from the DTD, where a less de-tailed configuration would store data in larger chunks and track fewer compo-nents.

Graphic Workflow A graphical representation of a workflow project. It may also be used to create anew workflow or to add a task to an existing workflow project. It displays rec-tangles with descriptive text for each workflow task, and arrows to indicate theflow.

Helper Applications Applications that are used to view and update multimedia data that is stored inVasont. For example, Acrobat Reader, Microsoft Word, etc.

Incomplete Status A component that is flagged with a red exclamation icon. This means that thecontent does not meet the requirements as defined in the collection setup in Vas-ont Administrator.

Inline An Inline component occurs inside a component that is allowed to contain text,as well as children components. An example is a graphic inside a paragraph. Thegraphic is inline.

instance_id A special Vasont number that identifies a workflow task.

Load View The defined structure and special processing that is expected when loading con-tent into a Vasont collection. Defined in the Vasont Administrator.

Match Criteria The method that Vasont uses to determine whether a component being loaded, isnew or changed. Methods include text, Client Key, or both.

Modular Content Content that is separated into meaningful chunks and stored in separate collec-tions in Vasont. For example, sections may be stored separately from the chap-ters. Pointer components in the chapters reference the sections. When the chap-ter is extracted to an XML file, the sections are pulled and positioned in thechapter XML as indicated. This concept allows for reuse of the sections in mul-tiple chapters or documents.

Multimedia Component A component that stores data that is in a special format, see BLOB. For exam-ple, EPS, PDF, Microsoft Word, etc.

Navigator A window that allows the browsing of stored content in a collection using hier-archical tree views.

Navigator Order The order in which Vasont expects to see the components. Usually based on theDTD's content model. For example, <!ELEMENT book (frontmatter, chapter*,backmatter)>. The children of Book would be ordered as 1. Frontmatter, 2.Chapter, and 3. Backmatter.

Notification A location on the Home Page where the logged in user can quickly see informa-tion about content to which they have subscribed. For example, changes to con-



tent where Variant relationships have been created, and events related to work-flow project or tasks.

Open Update A right-click option in Vasont navigator that allows editing of the content.

Open View A right-click option in Vasont navigator that allows the viewing of content with-out the ability to edit or modify.

parent_entity_id A special Vasont number that identifies the component's parent.

Pointee Component The destination component referenced by the Pointer Component.

Pointer Component Components that reference, or link, to other components in Vasont. Pointers pro-vide explicit reuse.

Preview A tab in the Vasont Navigator's Details Pane which shows a styled view of theselected primary component. This view makes it easier to read and evaluate thecontent in Vasont. Annotations can be created and displayed from this window.

Previous Versions See Versions

Primary Component The top-level component in a Vasont collection definition. A typical collectionwill have many primaries. Just as a butterfly collection would contain many but-terflies.

primary_entity_id A special Vasont number that identifies the top level component in the collec-tion.

Privileges The specific functions that a User is allowed to perform in a collection, such asadd, delete etc.

Processing Option Reusable programming code that is used to customize client business logic inVasont. Vasont has over 600 pre-built reusable processing options that can beapplied to various events in the Vasont environment.

prod_id A special Vasont number that identifies a collection.

Project An organized assemblage of tasks that define a workflow process.

project_id A special Vasont number that identifies a specific workflow project definition.

Project Management A window that allows you to view the overall status of your workflow projects.View multiple projects at one time; view projects for specific users; viewprojects due within a range of dates; view projects for specific collections. AGantt chart provides a visual display of the progress of the projects.

Raw Class Raw components are broken into three classes, text, pointer or multimedia. Eachclass has a unique feature that allows the component to behave in a specificmanner in the system. Each component in a collection is one of the three classes.

Raw Components The basic building block of a Vasont collection. Raw components may be com-pared to elements in a DTD. They are defined in the content type and can beused to build multiple collections.

Raw Material Available components that may be utilized in the construction of one or morecollections.

raw_id A special Vasont number that identifies a specific piece of raw material.

Referenced By A right-click option in Vasont navigator that lists other components that may belinked to the current component by a pointer component. Components that arereferenced more than once are being reused.

Refine A Refine query is used after a Vasont Navigator is populated with a Retrievequery. The Refine query further reduces the number of primary components in

Glossary


the navigator by using additional query criteria. The criteria can be applied tothe same collection or a related collection.

Reinstate The process of taking a previous version of the content and reactivating it as ac-tive content. This can be done by overwriting or creating as a new primary.

Reports The presentation of the details of a collection, project, etc.

Retrieve Retrieves allow limitations on the number of primary components that are dis-played in the navigator when retrieving a collection.

Review See Collaborative Review.

Review Coordinator A user who initiates the Collaborative Review in Vasont. This user selects theReviewers, Editor and due dates for the session.

Reviewer A special Vasont user who critiques the content in a Collaborative Review.Comments and suggestions to the content are applied in an XML editor. Follow-ing the Reviewers' session, an Editor will accept or reject the Reviewers' sugges-tions and the content is updated in the database.

Role A specific type of user, based on the functions they perform. For example, Writ-er, Editor, etc.

role_id A special Vasont number that identifies a role.

Rule Relation The relationship between a component and it's parent. For example, when aPARAGRAPH occurs in a CHAPTER the rule relation would be Para-graph[Chapter] in Vasont.

rule_relation_id A special Vasont number that identifies a parent/child component relationship.

Search Search is used to locate specific items that meet the defined criteria within aVasont Navigator window for collection content.

Stranded Components Components that may have been corrected and need special processing to becancelled.

Structured data Electronic data containing tags or markers for the individual pieces of content.Some examples of structured data is SGML and XML. Since the data containstags for the individual elements, the document can be consistently composed,searched, or broken into subdocuments. The tags may also contain attributes thatprovide metadata about the content.

Style The assembly of a cascading style sheet (CSS), conversion map, and load/extract view to produce a styled preview of content in the Vasont Details Pane.

Sub-component Any component that is at a lower level than the primary.

subject_id A special Vasont number that identifies the content type.

Super Administrator This is a privilege that is assigned to the schema owner and other users with theauthority to oversee the entire configuration. The privilege allows the user fullrights and access to all collections and features in the Vasont Administrator. Thesuper administrator decides who the associate administrators will be and assignsthem the appropriate privileges to the collections that they will oversee.

task_id A special Vasont number that identifies a task definition within a workflowproject.

Tasks A defined Workflow step in a project.

Text Argument An argument and a value that is keyed directly into the processing option win-dow, unlike processing options that have the right-click option of Update Argu-ment.



Text Component The most common raw class. Text components store data, or wrap other compo-nents. For example, Paragraph or Body.

Tools See Utilities.

Translation Project Window A Vasont extension that allows you to track due dates, vendors, and status infor-mation for each language subproject. Content can be submitted for quote ortranslation directly from this window. Translation reuse is also tracked from thiswindow.

Unstructured data Electronic data without meaningful tags or markers for the individual pieces oftext. Some examples of unstructured data would be Microsoft Word or Excelfiles, and PDFs.

User A user is an assigned login and password for an individual to gain access to thesystem.

User Navigator The window in the Vasont Administrator that controls the rights and privilegesfor users in Vasont.

userid An identifier for a Vasont user (i.e. the user's login name).

Utilities Programs that provide system tasks or functions in an automatic work savingfashion.

Valid Values One or more values that are acceptable for a component or attribute. Define inthe Vasont Administrator

Variants Relationships that are maintained in Vasont between two or more separate con-tent instances.

Vasont Administrator The setup software tool for Vasont.

Version History The historical data related to a collection.

Version On Demand The process of creating a version for the selected content at a point in time that auser sees a need for saving.

version_id A special Vasont number that identifies a specific extract or load view defini-tion.

Versions A capture of the data as it existed on a specific date and time.

View A View in the Vasont Administrator describes the structure and special func-tionality of a collection. There are three types of views, Edit, Load, and Extract.

View Headers Load and extract views contain Headers. This is where specific pieces of infor-mation are placed that affect the over-all load or extract file in the Vasont Ad-ministrator.

Where Used In the Vasont Administrator, a listing of all of the locations in which a process-ing option, raw component, attribute, or wrapper may occur for a specific collec-tion or a content type. In Vasont, a list showing where the exact same content isused in multiple places.

Workflow Workflow allows users to track the progression of the work performances.

Workgroup A Workgroup is a specific group of users that can perform various tasks inworkflow.

Working Collection The collection that a user is automatically logged into in Vasont because it is setas default collection.

Wrappers Wrappers link SGML/XML tagged data to components. By having wrappers,Vasont can store a tag <p> once and reuse it thousands of times.

Glossary


AAbout, 219Access Rights, 14, 17Active Content, 239Adding, 202

reference, 202Aliases, 239Analyzing, 239Ancestors, 11, 15API, 3

how to use, 3API Calls, 15, 219, 220, 221, 222, 223, 224, 225, 226,227, 228, 229, 230

About, 219CheckDBConnection, 219ConnectToDB, 220ConnectUsingProfile, 220CreateNewComponentFromTemplate, 221DisconnectFromDB, 221extract and load, 219ExtractIntoEditor, 222ExtractToFile, 222frequently used, 15GetContainedInterface, 223GetUserPreference, 223GetValueFromExtractPI, 224Init, 224InvokeVasont, 225login and information, 219low-level interface access, 219OpenNavigator, 225OpenWorkflow, 225PickConrefIntoEditor, 226PickHrefIntoEditor, 226PickListIntoEditor, 227RegisterOpenExtractCallback, 228RegisterSaveCallback, 228RegisterVersionCallback, 229SetUserPreference, 229UpdateVasont, 229UpdateVasontNoExtract, 230User Interface, 219

Applying, 214user defined processing options, 214

Approved Status, 239Arguments, 7, 239

finding in Vasont, 7Associate Administrators, 239attribute_link_id, 3, 7, 239Attributes, 11, 15, 239

BBatch Operations, 11Batch Updates, 239BLOBs, 239Bookmarks, 13, 16, 239Branching, 239

label, 239notices, 239notification, 239

CC#, 231

samples, 231CheckDBConnection, 219Checking In, 239Checking Out, 240child_entity_id, 3, 7, 240child_rule_relation_id, 7, 240Children, 11, 15Client Keys, 240Clone, 12, 240Code Template, 211

user defined processing options, 211Collaborative Reviews, 240Collection List, 204Collections, 13, 16, 240

accessing, 240groups, 240

Comments, 240Component Manipulation, 12, 16Components, 240Composite Extracts/Loads, 240Configuration, 1

making alterations, 1ConnectToDB, 220ConnectUsingProfile, 220Content, 239

active, 239Content Models, 240Content Navigator, 240Content Owners, 240Content Types, 13, 16, 240Create New, 240CreateNewComponentFromTemplate, 221Creating, 199, 201, 207

user collections, 207user interface, 201VB.net solution, 199

DDaemon Operations, 11



Data, 243, 244structured, 243unstructured, 244

Descendants, 11, 15Disclaimer, 1

making configuration alterations, 1DisconnectFromDB, 221Displaying, 208

users list, 208Draft Status, 240Dynamic Indexes, 240

EEdit Views, 240Editors, 240entity_id, 3, 7, 240Events, 241Extract Views, 241ExtractIntoEditor, 222Extracts, 12, 16, 219ExtractToFile, 222

Ff_allow_add, 19f_allow_approve, 19f_allow_check_in_override, 20f_allow_delete, 20f_allow_edit, 20f_allow_project_filter, 21f_allow_raw_material_view, 21f_allow_reassign_task, 21f_allow_reinstate_shadow, 22f_allow_workflow_scheduling_override, 22f_analyze_component, 22f_approve_component, 23f_approve_descendants, 23f_batch_extract, 24f_batch_load, 24f_batch_run, 25f_bookmark, 25f_change_expired_password, 26f_check_connection, 26f_check_in, 27f_check_out, 27f_check_out_status, 28f_check_out_status_component, 28f_checkout_redirect, 29f_checkout_redirect_user_select, 29f_children_allowed, 30f_clone_component, 30f_clone_component_overwrite, 31f_clone_primary, 31f_complete_review_editing, 32

f_complete_reviewer_session, 32f_complete_task, 33f_conditional_extract_file, 33f_connect_to_database, 34f_connect_using_ini, 35f_connect_using_profile, 36f_count_children, 36f_create_from_template_prod_list, 37f_create_new_from_template, 37f_create_ptr_from_pointee, 38f_create_variants, 39f_del_batch_extract_queue, 39f_del_extracted_from_batch_extract_queue, 40f_delete_daemon_batch, 40f_delete_entity, 41f_disconnect_from_database, 41f_driver_sequence_primary, 42f_drop_allowed, 42f_dynamic_index_build, 43f_exists_entity_by_match_criteria, 44f_exists_preview_setup, 44f_extract, 45f_extract_blob, 46f_extract_by_lang_attrib, 46f_extract_conref_file, 47f_extract_file, 47f_extract_file_by_lang_attrib, 48f_extract_file_by_version, 49f_extract_file_with_saved_condition, 49f_extract_multiple_primaries, 50f_extract_shadow, 50f_fast_extract_build, 51f_generate_review_merge_file, 51f_get_active_daemons, 52f_get_active_tasks_for_user, 52f_get_api_version, 53f_get_app_ini_file_path, 54f_get_app_path, 54f_get_approved_shadow_dates, 55f_get_attribute_name, 55f_get_attribute_valid_values, 56f_get_attribute_value, 57f_get_attributes_allowed, 58f_get_batch_queue, 58f_get_batch_queue_by_id, 60f_get_bookmark_console, 61f_get_check_out_console, 62f_get_checkout_info, 62f_get_children_allowed, 63f_get_children_by_rule_relation, 64f_get_client_key, 65f_get_client_key_use, 66f_get_client_key_use_by_client_key, 66f_get_component_data, 67


f_get_component_from_filter, 68f_get_component_from_filter_string, 72f_get_component_in_primary_from_filt_str, 75f_get_component_in_primary_from_filter, 79f_get_component_processing_options, 79f_get_components_from_find, 80f_get_components_from_find_string, 82f_get_composite_extract_filename, 83f_get_conref_attr_value_for_target, 84f_get_content_types, 84f_get_cross_prod_components, 85f_get_daemon_batches, 87f_get_db_profiles, 87f_get_descendant_count, 87f_get_descendant_pointers, 88f_get_descendants_by_rule, 88f_get_dw_prod_rule_relations, 89f_get_email_address, 90f_get_entities_from_prim_rr, 90f_get_entity_ancestry, 91f_get_entity_children, 91f_get_entity_children_details, 92f_get_entity_count, 93f_get_entity_hier_key, 94f_get_entity_preview, 95f_get_entity_status_date, 96f_get_filter_definition, 97f_get_filters_cross_prod, 98f_get_filters_find, 100f_get_filters_find_for_prod, 101f_get_filters_prod, 102f_get_filters_raw, 103f_get_global_change_candidates, 104f_get_global_clone_candidates, 105f_get_help_directory, 105f_get_href_attr_value_for_target, 106f_get_image_search_names, 106f_get_incomplete_descendants, 107f_get_ini_setting, 108f_get_mm_data, 108f_get_modular_pointees, 109f_get_nav_order, 109f_get_navigator_name, 110f_get_navigator_name_full, 110f_get_ownership_groups, 111f_get_parent_entity, 111f_get_picklist_extract_info, 111f_get_picklist_type_info, 112f_get_pointee_components, 114f_get_pointee_entity, 114f_get_pointer_components, 115f_get_preview_ancestor, 116f_get_primaries_by_attribute, 117f_get_primaries_with_sequence, 118

f_get_primary_entity, 119f_get_primary_entity_from_text, 119f_get_primary_from_filter, 120f_get_primary_from_filter_as_is, 122f_get_primary_from_filter_string, 123f_get_primary_prod_entity, 124f_get_primary_rule_relation, 125f_get_processing_option_arguments, 125f_get_prod_attribute_valid_values, 126f_get_prod_entity_versions, 126f_get_prod_id, 127f_get_prod_id_from_version, 127f_get_prod_list, 127f_get_prod_name, 128f_get_prod_primaries_by_attribute, 128f_get_prod_projects, 129f_get_prods_from_projects, 130f_get_project_component_list, 131f_get_project_name, 131f_get_project_tasks, 131f_get_project_users, 132f_get_projects_by_component, 132f_get_raw_attributes, 133f_get_raw_class, 133f_get_raw_component_from_filter, 134f_get_raw_component_from_filter_string, 136f_get_raw_components, 137f_get_raw_desc_by_raw_id, 138f_get_raw_description, 138f_get_raw_id, 139f_get_raw_text, 139f_get_raw_text_from_raw_id, 139f_get_raw_type_id, 140f_get_raw_types, 140f_get_reference_string, 141f_get_referenced_by, 141f_get_review_comment_replies, 142f_get_review_comments, 143f_get_review_load_flag, 144f_get_review_merge_file, 145f_get_reviewer_info, 145f_get_rightclick_processing_options, 146f_get_rule_relation, 147f_get_rule_relation_from_version, 147f_get_shadow, 148f_get_shadow_attributes, 149f_get_shadow_first_lvl_children, 149f_get_start_date, 150f_get_status, 151f_get_system_profile_value, 151f_get_task_attribute, 152f_get_task_attribute_valid, 152f_get_task_instance_attribute, 153f_get_task_list, 153



f_get_task_list_filter, 154f_get_task_project, 155f_get_task_queue, 156f_get_task_users, 156f_get_thumbnail_file, 157f_get_thumbnail_file_fullsize, 157f_get_translation_extract_projects, 158f_get_user_prod_xml, 158f_get_user_raw_material_xml, 159f_get_user_workflow_xml, 159f_get_username, 160f_get_users, 161f_get_valid_clone_target_prods, 161f_get_valid_filter_values, 162f_get_valid_values, 162f_get_value_from_extract_info_pi, 163f_get_variants, 164f_get_version_attribute_link_proc_opts, 165f_get_version_id, 166f_get_view_processing_options, 167f_get_workflow_task, 167f_get_wrapper_relation_id, 168f_get_wrapper_relation_proc_opts, 168f_insert_batch_extract_queue, 169f_insert_component, 170f_insert_daemon_batch, 170f_insert_primary_component, 171f_insert_raw_material_mm, 171f_insert_raw_material_pointer, 172f_insert_raw_material_text, 172f_insert_task_instance, 173f_insert_version_and_comment, 173f_insert_workflow_task, 174f_leadtools_supported_filetype, 174f_load, 175f_load_file, 176f_load_file_translation, 176f_ownership_extension_active, 177f_pending_delete_entity, 177f_reassign_task_user, 178f_redline_report, 178f_register_daemon, 179f_reinstate_shadow, 179f_remove_bookmark, 180f_resequence_non_primary, 180f_resequence_primary, 181f_review_accept_reject, 181f_review_comment_has_replies, 182f_search_for_primary, 183f_sequence_primary, 183f_server_side_cancel, 184f_server_side_progress, 184f_set_attribute_value, 185f_set_batch_extract_queue_filename, 185

f_set_batch_extract_queue_sequence_no, 186f_set_batch_extract_queue_status, 186f_set_bypass_server_processing, 187f_set_entity_clientkey, 187f_set_ownership_group, 187f_set_pointee_attribute, 188f_set_raw_id, 188f_set_review_comments, 189f_set_task_comment, 190f_set_task_instance_attribute, 191f_set_username, 191f_submit_reviewer_changes, 191f_test, 192f_text_allowed, 192f_this_is_a_test, 193f_translation_clone, 193f_undelete_entity, 194f_unregister_daemon, 194f_update_daemon, 195f_update_text_component, 195f_validate_required_attributes, 196f_where_used, 196filter_id, 7, 241Filters, 13, 16Finds, 13, 16Functions, 11

groups, 11

GGetContainedInterface, 223GetUserPreference, 223GetValueFromExtractPI, 224Global Change, 13, 241Granularity, 241Graphic Workflows, 241

HHelper Applications, 241High-Level API, 1

overview, 1How to Use, 3, 217

API, 3, 217high-level, 217low-level, 3

IID Numbers, 3, 7

attribute_link_id, 3, 7child_entity_id, 3, 7child_rule_relation_id, 7entity_id, 3, 7filter_id, 7instance_id, 7


parent_entity_id, 3primary_entity_id, 3prod_id, 3, 7project_id, 7raw_id, 3, 7role_id, 7rule_relation_id, 3, 7subject_id, 7task_id, 7Userid, 7version_id, 3, 7wrapper_relation_id, 3

Incomplete Status, 241Information, 12, 16, 219Init, 224Inline Components, 241instance_id, 7, 241Instantiating, 203

API, 203InvokeVasont, 225

KKey Concepts, 3

low-level API, 3

LLoad Views, 241Loads, 12, 16, 219Logging In, 204LogIn, 14, 17, 219Low-Level, 3, 11

functions, 11key concepts, 3

Low-Level API, 1overview, 1

Low-Level Interface Access, 219

MMatch Criteria, 241Modular Content, 241Multimedia Components, 241

NNavigator, 241

order, 241Notifications, 241

OOpen Update, 242Open View, 242OpenNavigator, 225OpenWorkflow, 225Overview, 1

high-level API, 1low-level API, 1

PParent, 3parent_entity_id, 3, 242Parent-Child Relationship, 3PickConrefIntoEditor, 226PickHrefIntoEditor, 226PickListIntoEditor, 227Pointee Components, 242Pointer Components, 242Pointers, 13, 16Populating, 207

collection, 207Previews, 242Previous Versions, 242Primaries, 14, 17Primary, 3Primary Components, 242primary_entity_id, 3, 242Privileges, 242Processing Options, 14, 17, 242prod_id, 3, 7, 242Products, 13, 16Programming Notes, 209project_id, 7, 242Projects, 242

management, 242

RRaw Classes, 242Raw Components, 242Raw Material, 14, 17, 242raw_id, 3, 7, 242Referenced By, 242Refining, 242RegisterOpenExtractCallback, 228RegisterSaveCallback, 228RegisterVersionCallback, 229Reinstate, 243Reports, 243Retrieving, 243Reviews, 243

coordinator, 243reviewers, 243

role_id, 7, 243Roles, 243Rule Relation, 3Rule Relations, 243rule_relation_id, 3, 7, 243Running, 209

application, 209



SSamples, 199, 231

C#, 231VB.net, 199

Searching, 243SetUserPreference, 229Shadow History, 13, 244Stranded Components, 243Styles, 243Sub-components, 243subject_id, 7, 243Super Administrators, 243

Ttask_id, 7, 243Tasks, 243Text Arguments, 243Text Components, 244Tools, 244Translations, 244

UUpdateVasont, 229UpdateVasontNoExtract, 230User Defined Processing Option, 211User Info, 14, 17User Interface, 219User Navigator, 244Userid, 7userid, 244Users, 244Users List, 205Utilities, 244

VValid Values, 244Variables, 6Vasont Administrator, 1, 244

making alterations, 1VB.net, 199

samples, 199version_id, 3, 7, 244Versions, 244

on demand, 244View Headers, 244Views, 244

WWhere Used, 244Workflow, 15Workflows, 244Workgroups, 244

Working Collections, 244wrapper_relation_id, 3Wrappers, 244


vasont application program interface guide version 2017.1 confidential------------------------©...

Documents