CONTENTS Title Page Copyright Page Preface 1 Introduction 1.1 The BASEstar Open Application Programming Interface 1.2 The Permanent and Volatile Object Databases 1.3 Requesting BASEstar Open Services 1.4 Configuring BASEstar Open 1.5 C Language Application Portability PART I General Purpose Services 2 General Purpose Procedures 2.1 Invoking API Procedures 2.1.1 Synchronous and Non-Blocking Procedure Invocation 2.1.2 Request Control Block 2.1.2.1 Setting Request Control Block Fields with Default Values 2.1.2.2 Setting Request Control Block Fields with User-supplied Values 2.1.3 Synchronizing with Non-Blocking Service Requests 2.1.4 Error Stack Handling 2.1.5 Examples 2.2 Use of General Purpose Procedures 2.2.1 BASEstar Open Environment Initialization and Release 2.2.2 Object References 2.2.2.1 Setting and Unsetting Object References 2.2.2.2 Making a Copy of a Reference 2.2.2.3 Getting Reference Information 2.2.3 Sequence Handling 2.2.3.1 Making a Copy of a Sequence 2.2.3.2 An Example 2.2.4 Setting the Database Scope 2.2.5 Setting the Context 2.2.6 Status Codes and Messages 2.2.7 BASEstar Open Time Handling 3 General Purpose Procedures Reference bstr_asynchronous_request_wait bstr_context_get_default bstr_context_set_default bstr_database_get_scope bstr_database_set_scope bstr_error_stack_allocate bstr_error_stack_clear bstr_error_stack_free bstr_error_stack_pop bstr_error_stack_push bstr_finish bstr_get_message bstr_get_time bstr_initialize bstr_references_are_equal bstr_reference_copy bstr_reference_get_info bstr_reference_set bstr_reference_unset bstr_sequence_append_elements bstr_sequence_copy bstr_sequence_create bstr_sequence_discard bstr_sequence_get_element_by_key bstr_sequence_get_elements bstr_sequence_get_info bstr_sequence_insert_elements bstr_sequences_are_equal bstr_time_compare bstr_time_convert bstr_time_to_string PART II Common Services 4 Common Services Procedures 4.1 Operations on Objects 4.1.1 Creating an Object 4.1.2 Deleting an Object 4.1.3 Obtaining Object Attributes 4.1.4 Setting Object Attributes 4.1.5 Getting Object Status 4.2 Operations on Composites 4.3 Operations on Collections 4.4 Datatypes 4.4.1 Mapping Simple_Datatypes into C Language Types 4.4.2 Array_Datatypes and Structure_Datatypes 4.4.3 Variable Length Array_Datatypes 4.5 Object Names 4.6 Managing Object Statistics 4.6.1 Getting Object Statistics 4.6.2 Program Preparation 5 Common Services Procedures Reference bstr_collection_get_children bstr_composite_get_components bstr_object_create bstr_object_delete bstr_object_disable_statistics bstr_object_enable_statistics bstr_object_get_attributes bstr_object_get_statistics bstr_object_get_status bstr_object_reset_statistics bstr_object_set_attributes PART III Event Services 6 Event Services Procedures 6.1 Creating and Deleting an Event_subscription 6.2 Declaring an Event 6.3 Connecting to an Enbox 6.3.1 Flushing a System Buffering Enbox 6.4 Receiving Event Notifications 6.5 Getting Enbox Information 6.6 Discarding API Resources Associated with a Notification 7 Event Services Procedures Reference bstr_enbox_connect bstr_enbox_disconnect bstr_enbox_get_info bstr_enbox_receive_notification bstr_event_add_subscription bstr_event_declare bstr_event_disable_subscription bstr_event_enable_subscription bstr_event_get_subscriptions bstr_event_notification_discard bstr_event_remove_subscription PART IV Packet Services 8 Packet Services Procedures 8.1 Sending a Packet 8.2 Connecting to a Port 8.2.1 Flushing a SYSTEM_BUFFERING Port 8.3 Discarding API Resources Associated with a Notification 8.4 Code Example 8.5 Managing Packet Notifications Requiring a reply 8.6 Getting Port Information 9 Packet Services Procedures Reference bstr_packet_notification_discard bstr_port_connect bstr_port_disconnect bstr_port_get_info bstr_port_receive_packet bstr_port_reply_packet bstr_port_send_packet PART V Data Services 10 Data Services Procedures 10.1 Operations on Data_Points 10.1.1 Reading and Writing Data_Point Values 10.1.2 Locking and Unlocking Data_Points or Data_Point_Sets 10.1.3 Getting Data_Point Status 10.1.4 Linking and Unlinking Data_Points 10.1.5 Device_Data_Points 10.2 Operations on Triggers 10.2.1 Enabling and Disabling Triggers 10.2.2 An Event Notification Generated by Writing a Data_Point 10.3 Versioning 11 Data Services Procedures Reference bstr_data_point_get_cached_val bstr_data_point_get_value bstr_data_point_link bstr_data_point_lock bstr_data_point_put_value bstr_data_point_reset_cache bstr_data_point_unlink bstr_data_point_unlock bstr_trigger_disable bstr_trigger_enable PART VI Device Services 12 Device Services Procedures 12.1 The MMS-Modeled Device Connectivity API 12.2 Installing the Protocol Support 12.3 Loading Definitions 12.4 Using the DEComni API 12.5 Device Services Server Specific Features 12.6 Programming Notes 13 Device Services Procedures Reference bstr_vmd_load_definitions PART VII Application Services 14 Application Services Procedures 14.1 Application Services-Compliant and Encapsulated Applications 14.2 The Application Services Procedures 14.3 Application Services-Compliant Applications 14.3.1 Application Structure 14.3.2 Program Execution Startup and Shutdown 14.3.3 Program Execution Flow 14.3.3.1 Activity Execution Startup 14.3.3.2 Activity Execution Shutdown 14.3.3.3 Program Execution Termination 14.3.4 Activity Execution Flow 14.3.5 Program Execution Template 14.4 Encapsulated Applications 14.5 Application Manager Procedures 14.5.1 Getting Activity and Actor Information 14.5.2 Execute 14.5.3 Terminate 14.5.4 Suspending the Component Activities 14.5.5 Resuming the Component Activities 14.6 Specifying Pathnames with Global Variables 15 Application Services Procedures Reference bstr_activity_begin bstr_activity_break bstr_activity_end bstr_activity_get_info bstr_actor_get_info bstr_actor_execute bstr_actor_resume bstr_actor_suspend bstr_actor_terminate bstr_program_receive_request PART VIII Program Preparation and Programming Tools 16 Program Preparation 16.1 BASEstar Open Application Structure Requirements 16.2 "OSF/1 Only" Program Preparation 16.2.1 Compiling and Linking an Application 16.2.2 Running an Application 16.2.2.1 Debugging an Application Executed Through Application Services 16.2.3 Application Programming Tips 16.3 "OpenVMS Only" Program Preparation 16.3.1 Compiling and Linking an Application 16.3.2 Running an Application 16.3.2.1 Debugging an Application Executed Through Application Services 16.3.3 Application Programming Tips 16.3.4 User Account Privileges and Quotas 16.3.5 Getting Message Text 16.4 "MS Windows Only" Program Preparation 16.4.1 Compiling and Linking an Application 16.4.2 Running an Application 16.4.3 Application Programming Tips 16.4.4 Visual Basic Binding File 17 The Source Trace Manager 17.1 Multiplatform Information 17.2 Configuration Database and Process_Selectors 17.3 Trace Application Programming Interface Procedures 17.3.1 Structure of the Trace Record 17.3.2 Program Preparation and Activation 17.4 STM Command Language Interpreter 17.4.1 Entering and Exiting the CLI 17.4.2 General Purpose Commands 17.4.3 Operating on Configuration Databases 17.4.4 Operating on Process_Selectors 17.4.4.1 General Purpose Process_Selector Commands 17.4.4.2 Enabling and Disabling Trace Generation 17.4.4.3 Adding and Removing Devices 17.4.4.4 Adding and Removing Tracepoint_Sets 17.5 A Complete Example 18 Source Trace Manager Procedures Reference bstr_trc_finish bstr_trc_initialize bstr_trc_trace 19 Source Trace Manager Commands Reference ADD DEVICE PROCESS_SELECTOR ADD TRACEPOINT_SET PROCESS_SELECTOR CREATE DATABASE CREATE PROCESS_SELECTOR DELETE DATABASE DELETE PROCESS_SELECTOR DISABLE PROCESS_SELECTOR ENABLE PROCESS_SELECTOR EXIT HELP PURGE PROCESS_SELECTOR REMOVE DEVICE PROCESS_SELECTOR REMOVE TRACEPOINT_SET PROCESS_SELECTOR SET DATABASE SHOW DATABASE SHOW DEVICE SHOW PROCESS_SELECTOR PART IX Appendices A Constants for Object Classes and Attributes A.1 BASEstar Open Service Classes and Constant Names A.2 C Language Constants and Types for BASEstar Open Common Services Attributes A.3 C Language Constants and Types for BASEstar Open Event Services Attributes A.4 C Language Constants and Types for BASEstar Open Packet Services Attributes A.5 C Language Constants and Types for BASEstar Open Data Services Attributes A.6 C Language Constants and Types for BASEstar Open Device Services Attributes A.7 C Language Constants and Types for BASEstar Open Application Services Attributes B Attributes Specified During Object Creation B.1 Valid Values for BASEstar Open Common Services Attributes B.2 Valid Values for BASEstar Open Event Services Attributes B.3 Valid Values for BASEstar Open Packet Services Attributes B.4 Valid Values for BASEstar Open Data Services Attributes B.5 Valid Values for BASEstar Open Device Services Attributes B.6 Valid Values for BASEstar Open Application Services Attributes C API Data Structures Reference bstr_t_activation_info bstr_t_activity_info bstr_t_callback bstr_t_descriptor bstr_t_enbox_info bstr_t_event_subscription bstr_t_link_policy bstr_t_named_value bstr_t_event_notification bstr_t_object_attribute bstr_t_packet_notification bstr_t_port_info bstr_t_process_info bstr_t_program_request bstr_t_rcb bstr_t_reference_info bstr_t_sequence_element D Mapping BASEstar Open Types D.1 BASEstar Open to MMS Types E Miscellaneous Procedures bstr_type_get_field_offset bstr_type_get_size EXAMPLES 2-1 Status Returned by the API Procedures 2-2 Invoking a Procedure in Synchronous Mode and Handling the Error Stack 2-3 Invoking a Procedure in Non-Blocking Mode and Handling the Error Stack 2-4 Sample Callback Routine 2-5 BASEstar Open Environment Initialization and Release 2-6 Setting and Unsetting the Reference to a Data_Point 2-7 Operations on Sequences 2-8 Use of the Default Context 4-1 Creating an Object 4-2 Reading Object Attributes 4-3 Setting Object Attributes 6-1 Receiving Event notifications 6-2 Handling Received Event Notifications 8-1 Sending a Packet to a Port 8-2 Receiving and Handling a Packet Notification 8-3 Sending a Packet Notification with Reply Requested 8-4 Receiving and Handling a Packet Notification with Reply Requested 10-1 Writing a Data_Point and Managing the Associated Notification 10-2 Managing the Notification Associated with a Data_Point 14-1 Program Execution Template 16-1 Visual Basic Binding 17-1 Inserting API Procedure Calls into the Program Flow 17-2 Creating STM Definitions FIGURES 1-1 Accessing BASEstar Open Services through the API 1-2 BASEstar Open API and Databases 1-3 Requesting BASEstar Services through the API 2-1 Request Control Block Fields 14-1 Program execution and Activity execution Relationship TABLES 1 Documentation Conventions 2-1 Procedures for Error Stack Handling 2-2 Procedures for BASEstar Open Environment Initialization and Release 2-3 Procedures for Object Reference Handling 2-4 Procedures for Sequence Handling 2-5 Procedures for Database Scope Management 2-6 Procedures for Context Operations 2-7 Procedures for Time Handling 4-1 Common Services Procedures 4-2 Common Services Procedures and Corresponding Messages and Classes 4-3 Procedure for Operations on Composites 4-4 Procedures for Operations on Collections 4-5 BASEstar Open Data Types and C Language Types Mapping 4-6 Statistics Procedures 4-7 Statistics Procedures and Corresponding Messages and Classes 5-1 Constraints when Creating Objects 5-2 Conditions for Deleting Objects or Object Definitions 5-3 Class-Specific Statistics Data Structures 5-4 Conditions for Modifying Objects Referred to by Another Object 6-1 Event Services Procedures 6-2 Event Services Procedures and Corresponding Messages and Classes 8-1 Packet Services Procedures 8-2 Packet Services Procedures and Corresponding Messages and Classes 10-1 Data Services Procedures 10-2 Data Services Procedures and Corresponding Messages and Classes 14-1 Application Services 14-2 Application Services Procedures and Corresponding Messages and Classes 14-3 Program Request Type 15-1 Application Services-defined breakpoints 17-1 Source Trace Manager Procedures 17-2 General Purpose Commands 17-3 Configuration Database Commands 17-4 Process_Selector Commands A-1 BASEstar Open Service Classes and Constant Names A-2 C Language Constants and Types for BASEstar Open Common Services Attributes A-3 C Language Constants and Types for BASEstar Open Event Services Attributes A-4 C Language Constants and Types for BASEstar Open Packet Services Attributes A-5 C Language Constants and Types for BASEstar Open Data Services Attributes A-6 C Language Constants and Types for BASEstar Open Device Services Attributes A-7 C Language Constants and Types for BASEstar Open Application Services Attributes B-1 Common Services: Required and Optional Object Attributes B-2 Event Services: Required and Optional Object Attributes B-3 Packet Services: Required and Optional Object Attributes B-4 Data Services: Required and Optional Object Attributes B-5 Device Services: Required and Optional Object Attributes B-6 Application Services: Required and Optional Object Attributes D-1 BASEstar Open to MMS Types