ssapi reference guide (0486) - ca...

SSAPI Reference Guide

Document 0486

Customization

Titlepage


Copyright Notice

Document 0486. Copyright © 2002 - present by Aprisma Management Technologies, Inc. All rights reserved worldwide. Use, duplication, or disclosure by the United States government is subject to the restrictions set forth in DFARS 252.227-7013(c)(1)(ii) and FAR 52.227-19.

Liability Disclaimer

Aprisma Management Technologies, Inc. (“Aprisma”) reserves the right to make changes in specifications and other information contained in this document without prior notice. In all cases, the reader should contact Aprisma to inquire if any changes have been made.

The hardware, firmware, or software described in this manual is subject to change without notice.

IN NO EVENT SHALL APRISMA, ITS EMPLOYEES, OFFICERS, DIRECTORS, AGENTS, OR AFFILIATES BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS) ARISING OUT OF OR RELATED TO THIS MANUAL OR THE INFORMATION CONTAINED IN IT, EVEN IF APRISMA HAS BEEN ADVISED OF, HAS KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES.

Trademark, Service Mark, and Logo Information

SPECTRUM, IMT, and the SPECTRUM IMT/VNM logo are registered trademarks of Aprisma Management Technologies, Inc., or its affiliates. APRISMA, APRISMA MANAGEMENT TECHNOLOGIES, the APRISMA MANAGEMENT TECHNOLOGIES logo, MANAGE WHAT MATTERS, DCM, VNM, SpectroGRAPH, SpectroSERVER, Inductive Modeling Technology, Device Communications Manager, SPECTRUM Security Manager, and Virtual Network Machine are unregistered trademarks of Aprisma Management Technologies, Inc., or its affiliates. For a complete list of Aprisma trademarks, service marks, and trade names, go tohttp://www.aprisma.com/manuals/trademark-list.htm.

All referenced trademarks, service marks, and trade names identified in this document, whether registered or unregistered, are the intellectual property of their respective owners. No rights are granted by Aprisma Management Technologies, Inc., to use such marks, whether by implication, estoppel, or otherwise. If you have comments or concerns about trademark or copyright references, please send an e-mail to [email protected]; we will do our best to help.

http://www.aprisma.com/manuals/trademark-list.htm


Restricted Rights Notice

(Applicable to licenses to the United States government only.)

This software and/or user documentation is/are provided with RESTRICTED AND LIMITED RIGHTS. Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR 52.227-14 (June 1987) Alternate III(g)(3) (June 1987), FAR 52.227-19 (June 1987), or DFARS 52.227-7013(c)(1)(ii) (June 1988), and/or in similar or successor clauses in the FAR or DFARS, or in the DOD or NASA FAR Supplement, as applicable. Contractor/manufacturer is Aprisma Management Technologies, Inc. In the event the government seeks to obtain the software pursuant to standard commercial practice, this software agreement, instead of the noted regulatory clauses, shall control the terms of the government's license.

Virus Disclaimer

Aprisma makes no representations or warranties to the effect that the licensed software is virus-free.

Aprisma has tested its software with current virus-checking technologies. However, because no antivirus system is 100 percent effective, we strongly recommend that you write-protect the licensed software and verify (with an antivirus system in which you have confidence) that the licensed software, prior to installation, is virus-free.

Contact Information

Aprisma Management Technologies, Inc.

273 Corporate Drive

Portsmouth, NH 03801

Phone: 603-334-2100

U.S. toll-free: 877-468-1448

Web site: http://www.aprisma.com

http://www.aprisma.com


ContentsIntroduction 18

The SSAPI Classes ....................................................................................................18Development Environment .........................................................................................19

Asynchronous SSAPI Classes 20

CsMailService 22CsMailService ( ) ....................................................................................................25deliver ( ) .................................................................................................................25get_current_connect_error ( ) .................................................................................26get_exit_flag ( ) .......................................................................................................26get_options ( ) .........................................................................................................27is_usable ( ) ............................................................................................................27register_for_connect ( ) ..........................................................................................28set_options ( ) .........................................................................................................29shutdown_mailservice ( ) ........................................................................................29Unregister ( ) ...........................................................................................................30UnsolRegister ( ) .....................................................................................................31

CsMailServOpts 32CsMailServOpts ( ) .................................................................................................35CsMailServOpts ( ) .................................................................................................36get_async_connect_retries ( ), set_async_connect_retires ( ) ...............................37get_async_connect_wait ( ),

set_async_connect_wait ( ) .................................................................................37get_block_initial ( ),

set_block_initial ( ) ..............................................................................................38get_cache_failed_connections ( ), set_cache_failed_connections ( ) ....................38get_cif_timeout ( ),

set_cif_timeout ( ) ................................................................................................39get_connect_time_limit ( ),

set_connect_time_limit ( ) ...................................................................................39get_connection_retry_interval ( ), set_connection_retry_interval ( ) .......................40get_enable_queue_send ( ),

set_enable_queue_send ( ) ................................................................................40

Contents


get_keep_alive_batch ( ), set_keep_alive_batch ( ) .....................................................................................41

get_keep_alive_interval ( ), set_keep_alive_interval ( ) ..................................................................................41

get_keep_alive_timeout ( ), set_keep_alive_timeout ( ) ..................................................................................42

get_local_queue_size ( ), set_local_queue_size ( ) .....................................................................................43

set_login ( ), get_user_name ( ) ...............................................................................................44

get_mail_queue_size ( ), set_mail_queue_size ( ) ......................................................................................44

get_mail_timeout ( ), set_mail_timeout ( ) .............................................................................................45

get_max_send_batch_size ( ), set_max_send_batch_size ( ) .............................................................................45

get_max_unsol_reg ( ), set_max_unsol_reg ( ) ........................................................................................46

get_min_version ( ), set_min_version ( ) ..............................................................................................46

get_no_tcp_delay_flag ( ), set_no_tcp_delay_flag ( ) ....................................................................................47

get_polling_cycle ( ), set_polling_cycle ( ) ............................................................................................47

get_print_version ( ), set_print_version ( ) ............................................................................................48

get_retry_batch ( ), set_retry_batch ( ) ...............................................................................................48

get_tcp_buffer_size ( ), set_tcp_buffer_size ( ) .........................................................................................49

get_use_polling ( ), set_use_polling ...................................................................................................49

operator = ( ) ...........................................................................................................50

CsMSAppID 51CsMSAppID ( ) .......................................................................................................53CsMSAppID ( ) .......................................................................................................54get_appl_name ( ) ..................................................................................................54get_appl_ver ( ) ......................................................................................................54

Contents


get_subappl_name ( ) .............................................................................................54operator = ( ) ...........................................................................................................54

CsMailClient 55CsMailClient ( ) .......................................................................................................56CsMailClient ( ) .......................................................................................................56Notify ( ) ..................................................................................................................57Timeout ( ) ..............................................................................................................58operator = ( ) ...........................................................................................................58

CsTimer 59CsTimer ( ) ..............................................................................................................60Addtimer ( ) .............................................................................................................60Removetimer ( ) ......................................................................................................61

CsModelAncestor 62CsModelAncestor ( ) ...............................................................................................64CsModelAncestor ( ) ...............................................................................................64copy ( ) ....................................................................................................................64get_current_connect_error ( ) .................................................................................65get_current_server ( ) .............................................................................................66get_current_version ( ) ...........................................................................................66get_service_id ( ) ....................................................................................................66get_service_type ( ) ................................................................................................67get_unsol_response ( ) ...........................................................................................67is_connected ( ) ......................................................................................................68is_connection_failure ( ) .........................................................................................68is_connection_success ( ) ......................................................................................68is_current_primary ( ) .............................................................................................69is_equal_service ( ) ................................................................................................69operator = ( ) ...........................................................................................................69

CsHandleAncestor 70CsHandleAncestor ( ) .............................................................................................71CsHandleAncestor ( ) .............................................................................................71CsHandleAncestor ( ) .............................................................................................72copy ( ) ....................................................................................................................72get_vnm_handle ( ) .................................................................................................72operator = ( ) ...........................................................................................................72

Contents


Asynchronous Handle Classes 73

CsUIAlarm 75CsUIAlarm ( ) ..........................................................................................................77CsUIAlarm ( ) ..........................................................................................................77ack_alarm_async ( ),

ack_alarm ( ) .......................................................................................................78alarm_update ( ) .....................................................................................................79attach_async ( ),

attach ( ) ..............................................................................................................80clear_alarm_async ( ),

clear_alarm ( ) .....................................................................................................82copy ........................................................................................................................83detach_async ( ),

detach ( ) .............................................................................................................84replace_filter_async ( )

replace_filter ( ), ..................................................................................................85update_alarm_async ( ),

update_alarm ( ) ..................................................................................................86operator = ( ) ...........................................................................................................87

CsUIEvent 88CsUIEvent ( ) ..........................................................................................................90CsUIEvent ( ) ..........................................................................................................90attach_async ( ),

attach ( ) ..............................................................................................................92copy ( ) ....................................................................................................................94create_event_async ( ),

create_event ( ) ...................................................................................................95detach_async ( ),

detach ( ) .............................................................................................................96get_messages_async ( ),

get_messages ( ) ................................................................................................97log_message_async ( ),

log_message ( ) ..................................................................................................98replace_filter_async ( ),

replace_filter ( ) .................................................................................................100scroll_down_async ( ),

scroll_down ( ) ...................................................................................................102

Contents


scroll_to_bottom_async ( ), scroll_to_bottom ( ) ...........................................................................................103

scroll_to_date_time_async ( ), scroll_to_date_time ( ) .......................................................................................104

scroll_to_top_async ( ), scroll_to_top ( ) .................................................................................................105

scroll_up_async ( ), scroll_up ( ) .......................................................................................................106

unsol_scroll ( ) ......................................................................................................107

CsUIGlobalScapeHandle 108CsUIGlobalScapeHandle ( ) .................................................................................112CsUIGlobalScapeHandle ( ) .................................................................................112CsUIGlobalScapeHandle ( ) .................................................................................113copy ( ) ..................................................................................................................113find_all_async ( ),

find_all( ) ...........................................................................................................114find_first_async ( ),

find_first ( ) ........................................................................................................115get_failed_landscapes ( ) .....................................................................................116get_successful_landscapes ( ) .............................................................................116operator = ( ) .........................................................................................................116

CsUILandScapeHandle 117CsUILandScapeHandle ( ) ....................................................................................119CsUILandScapeHandle ( ) ....................................................................................119attr_watch_update ( ) ............................................................................................120copy ( ) ..................................................................................................................120describe_async ( ),

describe ( ) ........................................................................................................121find_async ( ),

find ( ) ................................................................................................................124model_permission_async ( ),

model_permission ( ) .........................................................................................125multi_model_request_async ( ),

multi_model_request ( ) ....................................................................................126multi_mtype_request_async ( ),

multi_mtype_request ( ) ....................................................................................127

CsUIModelHandle 128

Contents


CsUIModelHandle ( ) ............................................................................................130CsUIModelHandle ( ) ............................................................................................131action_async ( ),

action ( ) ............................................................................................................131check_permission_async ( ),

check_permission ( ) .........................................................................................132copy ( ) ..................................................................................................................133describe_async ( ),

describe ( ) ........................................................................................................134destroy_async ( ),

destroy ( ) ..........................................................................................................136find_attr_by_oid_sync ( ),

find_attr_by_oid ( ) ............................................................................................137lock_async ( ),

lock ( ) ...............................................................................................................138read2_async ( ),

read2 ( ) .............................................................................................................139read_async ( ),

read ( ) ...............................................................................................................140read_next_async ( ),

read_next ( ) ......................................................................................................141reg_attr_watch_async ( ),

reg_attr_watch ( ), attr_watch_update ( ) ........................................................................................143

test_lock_async ( ), test_lock ( ) ........................................................................................................144

unlock_async ( ), unlock ( ) ...........................................................................................................145

unreg_attr_watch_async ( ), unreg_attr_watch ( ) ..........................................................................................146

write2_async ( ), write2 ( ) ............................................................................................................147

write_async ( ), write ( ) ..............................................................................................................148

CsUIModelTypeHandle 149CsUIModelTypeHandle ( ) ....................................................................................151CsUIModelTypeHandle ( ) ....................................................................................152copy ( ) ..................................................................................................................152

Contents


create_async ( ), create ( ) ............................................................................................................153

describe_async ( ), describe ( ) ........................................................................................................154

find_attr_by_oid_async ( ), find_attr_by_oid ( ) ............................................................................................158

is_derived_from_async ( ), is_derived_from ( ) ............................................................................................158

read_async ( ), read ( ) ...............................................................................................................159

reg_activate_watch_async ( ), reg_activate_watch ( ), activate_watch_update ( ) .................................................................................160

reg_attr_watch_async ( ),reg_attr_watch ( ), attr_watch_update ( ) ........................................................................................161

reg_destroy_watch_async ( ), reg_destroy_watch, destroy_watch_update ( ) ..................................................................................162

unreg_activate_watch_async ( ), unreg_activate_watch ( ) ...................................................................................163

unreg_attr_watch_async ( ), unreg_attr_watch ( ), .........................................................................................164

unreg_destroy_watch_async ( ), unreg_destroy_watch ........................................................................................164

write_async ( ),write ( ) ..............................................................................................................165

CsUIRelationHandle 166CsUIRelationHandle ( ) .........................................................................................169CsUIRelationHandle ( ) .........................................................................................169add_async ( ),

add_async ( ), add ( ) ................................................................................................................170

copy ( ) ..................................................................................................................171count_async ( ),

count_async ( ), count ( ) .............................................................................................................172

Contents


describe_async ( ), describe_async ( ), describe ( ) ........................................................................................................173

dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel ( ), .................................................................................................175

read_async ( ), read_async ( ), read ( ) ...............................................................................................................177

read_exp_async ( ), read_exp_async ( ), read_exp ( ) .......................................................................................................178

read_exprule_async ( ), read_exprule_async ( ),read_exprule ( ) .................................................................................................179

read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq ( ) ....................................................................................................180

read_rule_async ( ), read_rule_async ( ), read_rule ( ) .......................................................................................................182

reg_rel_watch_async ( ), reg_rel_watch ( ), rel_watch_update ..............................................................................................183

remove_async ( ), remove_async ( ), remove ( ) ..........................................................................................................184

unreg_rel_watch_async ( ), unreg_rel_watch ( ) ...........................................................................................185

CsUIStat 186CsUIStat ( ) ...........................................................................................................188CsUIStat ( ) ...........................................................................................................188attach_async ( ),

attach ( ) ............................................................................................................189

Contents


copy ( ) ..................................................................................................................191detach_async ( ),

detach ( ) ...........................................................................................................192replace_filter_async ( ),

replace_filter ( ) .................................................................................................193scroll_down_async ( ),

scroll_down ( ) ...................................................................................................195scroll_to_bottom_async ( ),

scroll_to_bottom ( ) ...........................................................................................196scroll_to_date_time_async ( ),

scroll_to_date_time ( ) .......................................................................................196scroll_to_top_async ( ),

scroll_to_top ( ) .................................................................................................198scroll_up_async ( ),

scroll_up ( ) .......................................................................................................199unsol_scroll ( ) ......................................................................................................200

CsUIVLMap 202CsUIVLMap ( ) ......................................................................................................204CsUIVLMap ( ) ......................................................................................................204attach_async ( ),

attach ( ) ............................................................................................................205copy ( ) ..................................................................................................................206detach_async ( ),

detach ( ) ...........................................................................................................207get_non_secure_map_async ( ),

get_non_secure_map ( ) ...................................................................................208unsol_update ( ) ....................................................................................................209operator= ( ) ..........................................................................................................210

Synchronous SSAPI Classes 211

CsSMailService 213CsSMailService ( ) ................................................................................................215CsSMailService ( ) ................................................................................................215get_current_connect_error ( ) ...............................................................................216get_options ( ) .......................................................................................................217idle ( ) ....................................................................................................................217set_options ( ) .......................................................................................................218

Contents


status ( ) ................................................................................................................218

CsSMailServOpts 219CsSMailServOpts ( ) .............................................................................................221CsSMailServOpts ( ) .............................................................................................221get_cache_failed_connections ( ), set_cache_failed_connections ( ) ..................222get_cif_timeout ( ),

set_cif_timeout ( ) ..............................................................................................222get_connect_time_limit ( ),

set_connect_time_limit ( ) .................................................................................223get_mail_timeout ( ),

set_mail_timeout ( ) ...........................................................................................223get_min_version ( ),

set_min_version ( ) ............................................................................................224get_polling_cycle ( ),

set_polling_cycle ( ) ..........................................................................................224get_print_version ( ),

set_print_version ( ) ..........................................................................................225get_tcp_buffer_size ( ),

set_tcp_buffer_size ( ) .......................................................................................225get_use_polling ( ),

set_use_polling ( ) .............................................................................................226get_user_name ( ),

set_login ( ) .......................................................................................................226operator = ( ) .........................................................................................................227

CsSMSAppID 228CsSMSAppID ( ) ...................................................................................................229

CsSModelAncestor 230CsSModelAncestor ...............................................................................................231get_current_connect_error ( ) ...............................................................................232get_current_server ( ) ...........................................................................................232get_current_version ( ) .........................................................................................233get_service_id ( ) ..................................................................................................233get_service_type ( ) ..............................................................................................233is_connected ( ) ....................................................................................................233is_connection_success ( ),

is_connection_failure ( ) ....................................................................................234

Contents


is_current_primary ( ) ...........................................................................................234is_equal_service ( ) ..............................................................................................234

Synchronous Handle Classes 235

CsSYAlarm 237CsSYAlarm ( ) .......................................................................................................239CsSYAlarm ( ) .......................................................................................................239ack_alarm_sync ( ) ...............................................................................................240attach_sync ( ) ......................................................................................................241clear_alarm_sync ( ) .............................................................................................243detach_sync ( ) .....................................................................................................245get_unsol_alarms ( ) .............................................................................................246replace_filter_sync ( ) ...........................................................................................246update_alarm_sync ( ) ..........................................................................................247operator = ( ) .........................................................................................................248

CsSYEvent 249CsSYEvent ( ) .......................................................................................................251CsSYEvent ( ) .......................................................................................................252attach_sync ( ) ......................................................................................................253create_event_sync ( ) ...........................................................................................255detach_sync ( ) .....................................................................................................256get_messages_sync ( ) ........................................................................................257get_unsol_events ( ) .............................................................................................258log_message_sync ( ) ..........................................................................................259replace_filter_sync ( ) ...........................................................................................261scroll_down_sync ( ) .............................................................................................262scroll_to_bottom_sync ( ) .....................................................................................263scroll_to_date_time_sync ( ) .................................................................................264scroll_to_top_sync ( ) ...........................................................................................265scroll_up_sync ( ) .................................................................................................266operator = ( ) .........................................................................................................267

CsSYGlobalScapeHandle 268CsSYGlobalScapeHandle ( ) ................................................................................271CsSYGlobalScapeHandle ( ) ................................................................................272find_all_sync ( ) ....................................................................................................272find_first_sync ( ) ..................................................................................................273

Contents


get_failed_landscapes ( ) .....................................................................................273get_successful_landscapes ( ) .............................................................................273operator = ( ) .........................................................................................................274

CsSYLandScapeHandle 275CsSYLandScapeHandle ( ) ..................................................................................276CsSYLandScapeHandle ( ) ..................................................................................277describe_sync ( ) ..................................................................................................278find_sync ( ) ..........................................................................................................281model_permission_sync ( ) ...................................................................................282xmulti_model_request_sync ( ) .............................................................................283multi_mtype_request_sync ( ) ..............................................................................283operator = ( ) .........................................................................................................284

CsSYModelHandle 285CsSYModelHandle ( ) ...........................................................................................287CsSYModelHandle ( ) ...........................................................................................287action_sync ( ) ......................................................................................................288check_permission_sync ( ) ...................................................................................289describe_rels_sync ( ) ..........................................................................................290describe_sync ( ) ..................................................................................................292destroy_sync ( ) ....................................................................................................294find_attr_by_oid_sync ( ) ......................................................................................294lock_sync ( ) .........................................................................................................295read2_sync ( ) .......................................................................................................296read_sync ( ) .........................................................................................................297read_next_sync ( ) ................................................................................................299test_lock_sync ( ) ..................................................................................................301unlock_sync ( ) .....................................................................................................301write2_sync ( ) ......................................................................................................302write_sync ( ) ........................................................................................................303operator = ( ) .........................................................................................................303

CsSYModelTypeHandle 304CsSYModelTypeHandle ( ) ...................................................................................306CsSYModelTypeHandle ( ) ...................................................................................306create_sync ( ) ......................................................................................................307describe_sync ( ) ..................................................................................................308find_attr_by_oid_sync ( ) ......................................................................................312

Contents


is_derived_from_sync ( ) ......................................................................................312read_sync ( ) .........................................................................................................313write_sync ( ) ........................................................................................................314operator = ( ) .........................................................................................................315

CsSYRelationHandle 316CsSYRelationHandle ( ) .......................................................................................318CsSYRelationHandle ( ) .......................................................................................319add_sync ( ) ..........................................................................................................319count_sync ( ) .......................................................................................................320describe_sync ( ) ..................................................................................................321dofunc_mrel_sync ( ) ............................................................................................322read_exp_sync ( ) .................................................................................................323read_exprule_sync ( ) ...........................................................................................324read_mrelq_sync ( ) ..............................................................................................325read_rule_sync ( ) .................................................................................................326read_sync ( ) .........................................................................................................327remove_sync ( ) ....................................................................................................328The VnmParmBlock Reference on CsAssocCount for more information on retrieving

information from a CsAssocCount object. .........................................................328operator = ( ) .........................................................................................................329

CsSYStat 330CsSYStat ( ) ..........................................................................................................332CsSYStat ( ) ..........................................................................................................332attach_sync ( ) ......................................................................................................333detach_sync ( ) .....................................................................................................335get_unsol_stats ( ) ................................................................................................336replace_filter_sync ( ) ...........................................................................................337scroll_down_sync ( ) .............................................................................................338scroll_to_bottom_sync ( ) .....................................................................................339scroll_to_date_time_sync ( ) .................................................................................340scroll_to_top_sync ( ) ...........................................................................................341scroll_up_sync ( ) .................................................................................................342operator = ( ) .........................................................................................................343

CsSYVLMapHandle 344CsSYVLMapHandle ( ) .........................................................................................346CsSYVLMapHandle ( ) .........................................................................................346

Contents


attach_sync ( ) ......................................................................................................347detach_sync ( ) .....................................................................................................347get_non_secure_map ( ) ......................................................................................348get_unsol_updates ( ) ...........................................................................................348get_updated_map ( ) ............................................................................................349operator = ( ) .........................................................................................................349

Timing and Dispatch 350

Asynchronous Task Scheduling ...............................................................................350

CsIsolate 352Function Prototypes .................................................................................................353

add_a_timer ( ) .....................................................................................................356add_an_input ( ) ...................................................................................................357add_a_work_proc ( ) .............................................................................................358do_tasks ( ) ...........................................................................................................359display_error ( ) ....................................................................................................359get_exit_status ( ) .................................................................................................360main_loop ( ) .........................................................................................................360remove_a_timer ( ) ...............................................................................................360remove_an_input ( ) .............................................................................................361remove_a_work_proc ( ) .......................................................................................361set_exit_flag_ptr ( ) ...............................................................................................362set_exit_status ( ) .................................................................................................363

CsWorkProcess 364CsWorkProcess ( ) ...............................................................................................366Call ( ) ...................................................................................................................367

Index 368


Introduction

This section gives a brief overview of the API and the classes it implements.

This section introduces the SpectroSERVER Application Program Interface (referred to as SSAPI in the rest of this document) and the SpectroSERVER API Reference, which contains information about the C++ classes available in the Asynchronous and Synchronous SSAPI. In addition, the development environment for the Level II toolkits is briefly discussed.

The SSAPI ClassesThe SSAPI toolkit provides the communications interface between SpectroSERVER and client processes such as SpectroGRAPH. This API provides both an asynchronous interface (for interactive and windowed applications) and a synchronous interface (for query and report requests to SPECTRUM). This document provides reference information about the Asynchronous and Synchronous SSAPI classes, as well as the functions and libraries provided to handle timing and dispatch for programs written to the Asynchronous API. For more information about designing and building programs using these classes, refer to the SpectroSERVER API Developer’s Guide.

The SSAPI toolkit also includes the Global and VnmParmBlock APIs and Class Libraries. These libraries are essential to the development of C++ objects and programs that integrate with SpectroSERVER. The Global classes provide methods to create and manipulate buffers, Object IDs, messages, date and time settings, and other general data representations used throughout SPECTRUM; for more information, refer to the Global Classes Reference. The CsVnmParmBlock classes are used to define objects that allow access to specific SPECTRUM model types, attributes, aspects, and processes; for more information, refer to the VnmParmBlock Reference.

Introduction Development Environment


Development EnvironmentThe SPECTRUM Level II Developer’s Tools are designed to be used with a platform-specific version of C++ (or C, in the case of the EPI API).

Asynchronous SSAPI Classes



This section gives a synopsis of the classes and methods which control and implement the Asynchronous SSAPI.

These classes are used in conjunction with CsVnmParmBlock and the classes derived from it. The CsVnmParmBlock classes are not specific to the SSAPI and are explained in the VnmParmBlock Reference.

The Asynchronous SSAPI includes classes to structure a SpectroSERVER client application and other classes to deal with the different SPECTRUM handles, which are used to exchange information with objects within the SPECTRUM database. Table 1 provides a list of the Asynchronous SSAPI classes:

Table 1: Asynchronous SSAPI Classes

Class Purpose

CsMailService Enables information exchange with SpectroSERVER.

CsMailServOpts Sets the mail service options.

CsMSAppID Passes application information to mail service.

CsMailClient Defines an interface for SSAPI clients.

CsTimer Invokes a user-specified callback at a particular time interval.

CsModelAncestor The base class for the UIHandle classes.

CsHandleAncestor CsHandleAncestor is derived from CsModelAncestor, and all the UIHandles are derived from CsHandleAncestor.

CsUIAlarm Exchanges information about alarms.

CsUIEvent Exchanges information about events.



CsUIGlobalScapeHandle Searches across multiple landscapes.

CsUILandScapeHandle Exchanges information about the Landscape.

CsUIModelHandle Exchanges information about models.

CsUIModelTypeHandle Exchanges information about model types.

CsUIRelationHandle Exchanges information about relations.

CsUIStat Exchanges information about statistics.

CsUIVLMap Receives information about the VNM/Landscape map in a Distributed SpectroSERVER environment.

Table 1: Asynchronous SSAPI Classes (Continued)

Class Purpose

CsMailService


CsMailService

Class Hierarchy

Include FileCsMailServ.h

DescriptionThe CsMailService class provides a means of sending and receiving messages to a SpectroSERVER. Its methods deal with initiating contact with the distributed SpectroSERVER environment, and the maintenance of that connection. An instantiated CsMailService object is also referred to as the MailService. In the asynchronous mode the MailService is used to send a number of user requests to the distributed SpectroSERVER environment, the requests are made by the appropriate handle objects and passed to the MailService for delivery. The MailService returns a response identifier to the users application for future reference. Once the user method has made all of its requests and returned, the MailService deliver loop takes control. When it receives a response, it notifies the appropriate CsMailClient object in the application, which then must use the returned response identifier to obtain the message data. The CsMailService class also includes methods that are used for setting connection timeouts, determining connection usability, and exiting from the MailService. For more information on timeouts and connection management, refer to Appendix C of the SpectroSERVER API Developer’s Guide.

The MailService requires that the external function, handle_vnm_error(), be declared as a part of every SSAPI client program. This external method is used to deal with errors returned to the MailService from SpectroSERVER. The client application must define a handle_vnm_error() routine and can customize it to maintain, close, or retry connections to SpectroSERVER.

CsMailService

CsMailService


Refer to Appendix C in the SpectroSERVER API Developer’s Guide for more information on Connection Error Messages.

Note:Note:

Since the CsMailService::AddServer() method is used only with the View Applications Program Interface (VWAPI) Level II Toolkit, it is documented in the View API Reference Guide.

Note:Note:

A CsMailService object must be created prior to instantiating any SSAPI handle objects and initiating any SSAPI requests.

Note:Note:

Attribute Groups are no longer implemented as Attributes of type GROUP_ID. Now, attribute Groups are their own distinct entity in the database and Model Type Editor. Any call that returns Attributes, will no longer return Attribute Groups.

CsMailService


Public Methods

Method Description

CsMailService ( ) The default class constructor.

deliver ( ) This method is the main dispatch loop in an Asynchronous SSAPI Application.

get_current_connect_error ( ) Returns the current connection error.

get_exit_flag ( ) Retrieves current exit flag value.

get_options ( ) Retrieves CsMailService options.

is_usable ( ) Checks CsMailService object for ability to make requests.

register_for_connect ( ) Returns the response ID used to retrieve unsolicited messages.

set_options ( ) Sets CsMailService options.

shutdown_mailservice ( ) Allows a client to terminate the CsMailService's dispatch loop.

Unregister ( ) Unregister a request for the SSAPI.

UnsolRegister ( ) Registers the receiver with the SSAPI to receive unsolicited messages.

CsMailService CsMai lServ ice ( )


CsMailService ( )CsMailService ( const CsMSAppID & MS_AppID,

const CsMailServOpts & ms_options = CsMailServOpts::default_ms_options ) ;

This method constructs the CsMailService object using two parameters. All the option information is specified by first creating the CsMailServOpts object and the application ID information is specified in the CsMSAppID object.

deliver ( )void deliver ( CsTboolean destroy_cif = TRUE ) ;

This method is the main dispatch loop in an Asynchronous SSAPI Application. It uses methods within the isolation library (refer to Timing and Dispatching) to wait for a message on the socket to SpectroSERVER. When a message is received, the handle object that made the request is identified. The information in the message is unpacked into the appropriate CsVnmParmBlock object and the block is sent to the handle object. Next, the CsMailService calls the Notify() method of the subscriber that initiated the request. The Notify() can then pick up the response from the handle. The deliver() method loops until the CsMailService::shutdown() method is called.

See also:

CsMailService::CsMailService(), CsMailClient::Notify(), and the initiator/retriever calls of the handle classes.

Argument Description

MS_AppID Identifies the application constructing the mail service.

ms_options Options to control details of mail service operation.


destroy_cif This parameter is no longer used. It is retained for backward compatibility. Do not change the default value.

CsMailService get_current_connect_error ( )


get_current_connect_error ( )CsError::CsError_e get_current_connect_error

( char ** error_message = 0 ) const ;

This method returns the current connection error for this service. If the error_message parameter is not 0, then a vector duplicated copy of the corresponding error message is also returned. If there is no error message, then error_message will be set to 0. Be careful when using this method when called back for handle_vnm_error(). It is possible that the connection state has changed since the notification was queued and this method may give an error that is inconsistent with the notification error code. The error returned by this method is always the most current.

get_exit_flag ( )CsTboolean get_exit_flag ( void ) ;

This method gets the current exit_flag value. This is used to test whether the CsMailService is exiting the deliver() loop.


error_message A pointer to the current error message.

Caution:Caution:

The caller is responsible for deleting the returned error message using a C++ vector delete statement.

CsMailService get_opt ions ( )


get_options ( )void get_options ( CsMailServOpts * ms_opts ) ;

This method retrieves the options for the CsMailService in the form of the CsMailServOpts object. To get the individual options, use the CsMailServOpts get methods.

is_usable ( )CsTboolean is_usable ( void ) ;

This method returns a status of, TRUE or FALSE, indicating whether this CsMailService object is usable for making requests.


ms_opts A pointer to a CsMailServOpts object that contains the options retrieved.

Caution:Caution:

The CsMailServOpts object does not take ownership of the memory allocated to ms_opts, it is the callers responsibility to delete it.

CsMailService register_for_connect ( )


register_for_connect ( )CsTresponseid register_for_connect ( CsMailClient * receiver,

CsModelAncestor * referent ) ;

This method returns the response ID used to retrieve unsolicited messages regarding connection status, using CsModelAncestor::get_unsol_response(). This method is called to register a CsModelAncestor object so that it can receive notification of changes in connection status for its landscape. Registration for connection event notification provides a client application with a means for dealing with changes in connection status.

See also:

CsUILandScapeHandle.


receiver The subscriber registering for connection messages.

referent The Landscape in which to register an interest.

Caution:Caution:

When a connection is lost, SSAPI reports the error in several ways so an application can handle it as needed. Any outstanding requests made on the connection are cancelled and an error response is returned. The handle_vnm_error() function is called with the error code and a message. SSAPI provides a notification callback method. If the application wants to be notified when a connection changes state, the application should register the async SSAPI handle that uses the service provided over the connection. The handle is registered using this method of CsMailService:

CsTresponseid register_for_connect ( CsMailClient * receiver, CsModelAncestor * referent ) ;

The application can register all handles, or can compare the services of the handles to only register one per service.

CsMailService set_opt ions ( )


set_options ( )void set_options ( const CsMailServOpts & ms_opts ) ;

This method sets the options for the CsMailService. To see the individual options, see the class CsMailServOpts. This method would be used to change the options of the CsMailService once the CsMailService is invoked.

shutdown_mailservice ( )void shutdown_mailservice ( void ) ;

This method allows a client to terminate the CsMailService's dispatch loop, closing all sockets and breaking all communication with SpectroSERVERs and other servers.


ms_opts The options to set.

CsMailService Unregister ( )


Unregister ( )void Unregister ( CsTresponseid res_id ) ;

This method is called by a subscriber to unregister a pending request from the SSAPI. Under normal circumstances, there is no need for a subscriber to call this method — the SSAPI unregisters all pending requests made by the subscriber automatically when the subscriber is destroyed. However, if the handle that was handling a request for the subscriber is destroyed for some reason, this method should be called by the subscriber.

See also:

The initiator/retriever pairs of the Asynchronous Handle classes.


res_id The response ID that was returned to the subscriber by the initiator, when it initiated the request.

Caution:Caution:

If res_id is an illegal response ID, the method simply returns and no errors are reported or set. If res_id has a negative value, then the response ID is illegal.

CsMailService UnsolRegister ( )


UnsolRegister ( )CsTresponseid UnsolRegister ( CsMailClient * receiver,

CsModelAncestor * referent ) ;

This method is used to register the receiver with the SSAPI to receive unsolicited messages from SpectroSERVER. When the SSAPI receives a message from SpectroSERVER destined for the receiver, it hands over the contents of the message to the handle object and calls the Notify() method of the receiver to notify it that an unsolicited message was received.

This method returns a response ID, which should be retained and used by the receiver to attach to the Alarm, Event, Statistic, or V/L Map Managers for unsolicited messages or CsUIHandle classes for environmental changes.

See also:

CsMailClient::Notify() and the initiator/retriever pairs of the CsUIEvent, CsUIStat, CsUIVLMap, and CsUIAlarm.


receiver The CsMailClient to be notified on receiving unsolicited messages.

referent The handle object being registered.

CsMailServOpts UnsolRegister ( )


CsMailServOpts

Class Hierarchy

Include FileCsMSOpts.h

DescriptionThis class is used to set the Mail Service’s options. A CsMailServOpts object is created and passed as an argument in the CsMailService constructor and CsMailService::set_options method. This class contains methods to get and set individual options.

The default values are intended for an interactive application over a network with moderately high traffic. For a network with very heavy traffic, it might be worth trying higher values so that the SSAPI will wait longer for connections and responses before returning an error code.

In a network with frequent failures, it might be effective to choose a smaller value for Connection_retry_interval. By contrast, a non-time-critical application might work better with Connection_retry_interval set to a higher value (10 minutes or longer) to reduce overhead caused by frequent retries.

Send_msg_timeout should always be set to at least twice the value of Connection_retry_interval; otherwise, requests could be cancelled before any retry attempt is made.

See also:

CsMailServ.h

CsMailServOpts



Public Methods

Method Description

CsMailServOpts ( ) Class constructor.

CsMailServOpts ( ) Class copy constructor.

get_async_connect_retries ( ), set_async_connect_retires ( )

Sets and retrieves wait for connect value.

get_async_connect_wait ( ), set_async_connect_wait ( )

Sets and retrieves value limiting time to wait for connect.

get_block_initial ( ), set_block_initial ( )

Sets and retrieves whether initial connection made when the mail service is constructed, blocks.

get_cache_failed_connections ( ), set_cache_failed_connections ( )

Sets and retrieves cache_failed_connections option.

get_cif_timeout ( ), set_cif_timeout ( )

Sets and retrieves handshake timeout value.

get_connect_time_limit ( ), set_connect_time_limit ( )

Sets and retrieves TCP connect time.

get_connection_retry_interval ( ), set_connection_retry_interval ( )

Sets and retrieves retry connection value.

get_enable_queue_send ( ), set_enable_queue_send ( )

Sets and retrieves whether to queue requests.

get_keep_alive_batch ( ), set_keep_alive_batch ( )

Manages “keep alive” requests on a server.

get_keep_alive_interval ( ), set_keep_alive_interval ( )

Sets and retrieves time between “keep alive” requests.

get_keep_alive_timeout ( ), set_keep_alive_timeout ( )

Sets and retrieves time to wait for “keep alive” requests.

get_local_queue_size ( ), set_local_queue_size ( )

Retrieves queue size and sets maximum number of outstanding local requests.



set_login ( ), get_user_name ( ) Sets password and retrieves username.

get_mail_queue_size ( ), set_mail_queue_size ( )

Retrieves mail queue size and sets maximum number of outstanding requests.

get_mail_timeout ( ), set_mail_timeout ( )

Sets and retrieves time Mail Service waits for a response.

get_max_send_batch_size ( ), set_max_send_batch_size ( )

Sets and retrieves maximum number of messages sent on callback.

get_max_unsol_reg ( ), set_max_unsol_reg ( )

Sets and retrieves maximum number of unsolicited registrations allowed.

get_min_version ( ), set_min_version ( )

Sets and retrieves minimum VPAPI version needed to connect with server.

get_no_tcp_delay_flag ( ), set_no_tcp_delay_flag ( )

Sets and retrieves value of no_tcp_delay flag.

get_polling_cycle ( ), set_polling_cycle ( )

Sets and retrieves length of polling cycle.

get_print_version ( ), set_print_version ( )

Sets and retrieves whether version number of SSAPI is printed.

get_retry_batch ( ), set_retry_batch ( )

These methods retrieve and set the number of connections retried on a single callback.

get_tcp_buffer_size ( ), set_tcp_buffer_size ( )

These methods retrieve and set the size of the TCP buffer.

get_use_polling ( ), set_use_polling

Set and retrieve the value of the use_polling option flag.

operator = ( ) Class assignment operator.

Method Description

CsMailServOpts CsMai lServOpts ( )


CsMailServOpts ( )CsMailServOpts ( void ) ;

This constructor creates a CsMailServOpts object with a set of default values for each option. To set the individual options use the methods down below. The default values for the options are listed in Table 2.

Table 2: CsMailServOpts Option Defaults

Method Default Value

CsTboolean no_tcp_delay_flag FALSE

int mail_queue_size 1024

int connection_retry_interval 2000 (2 seconds in milliseconds.)

int cif_timeout 60; (1 minute in seconds)

int mail_timeout 600000; (10 minutes in milliseconds)

CsTboolean use_polling_flag FALSE

CsTulong polling_cycle 3600000 (One hour in milliseconds)

int max_unsol_reg 256

CsTboolean enable_queue_send TRUE

CsTulong max_send_batch_size 40

CsTulong tcp_buffer_size CS_NO_TCP_BUFFER_SIZE

CsTulong connect_time_limit 5000 (5 seconds in milliseconds)

CsTboolean print_version FALSE

CsTboolean block_initial TRUE

CsTboolean cache_failed_connections TRUE

CsTulong keep_alive_interval 60000 (1 minute in milliseconds)

CsTulong keep_alive_timeout 30000 (30 seconds in milliseconds)

CsTulong keep_alive_batch 5

CsMailServOpts CsMai lServOpts ( )


CsMailServOpts ( )CsMailServOpts ( const CsMailServOpts & original ) ;

Copy constructor for this class.

CsTulong retry_batch 20

CsTulong async_connect_wait 500 (microseconds)

int async_connect_retries 3

const char * user_name 0 (uses operating system user name)

const char * password 0 (no password)

CsTboolean local_queue_size 2048

CsVersionNumber min_version DEFAULT_VERSION


original Object to be copied.

Table 2: CsMailServOpts Option Defaults (Continued)

Method Default Value

CsMailServOpts get_async_connect_retr ies ( ) , set_async_connect_ret i res ( )


get_async_connect_retries ( ), set_async_connect_retires ( )

int get_async_connect_retries ( void ) const ;

void set_async_connect_retries ( int new_async_connect_retries ) ;

This pair of methods is responsible for getting and setting the value that limits how many times to wait for a connect call to finish before returning and leaving the connect to finish asynchronously.

get_async_connect_wait ( ), set_async_connect_wait ( )

CsTulong get_async_connect_wait ( void ) const ;

void set_async_connect_wait ( CsTulong new_async_connect_wait ) ;

This pair of methods is responsible for getting and setting the value that limits how long to wait for a call to finish before returning and leaving the connect to finish asynchronously.


new_async_connect_retries The new retry value.

Note:Note:This method pair is new for 6.0.


new_async_connect_wait The new connection wait value.


CsMailServOpts get_block_in it ial ( ) , set_block_ini t ia l ( )


get_block_initial ( ), set_block_initial ( )

CsTboolean get_block_initial ( void ) const ;

void set_block_initial ( CsTboolean new_block_initial ) ;

This pair of methods is responsible for getting and setting whether initial connection made, when the mail service is constructed, blocks until the connection is complete. If the option is TRUE then the initial connection blocks. If the option is FALSE, the mail service constructor will start the connection and return before the connection is complete.


static CsTboolean get_cache_failed_connections ( void ) const ;

void set_cache_failed_connections ( CsTboolean new_cache_failed_connections ) ;

This method pair gets and sets the cache_failed_connections option. If TRUE is returned then failed connections will be cached and retried independently so application calls will not be delayed. This is particularly useful with distributed finds in a network where some machines may not be pingable.


new_block_initial The new block value.


new_cache_failed_connections The new caching value.

CsMailServOpts get_ci f_t imeout ( ) , set_ci f_t imeout ( )



int get_cif_timeout ( void ) const ;

void set_cif_timeout ( int new_cif_timeout ) ;

This pair of methods retrieves and sets the current value of the handshake timeout, which is used for the creation of sockets created by the CsMailService. The returned value is in milliseconds.


CsTulong get_connect_time_limit ( void ) ;

void set_connect_time_limit ( CsTulong new_connect_time_limit ) ;

This pair of methods sets and retrieves the number of milliseconds to wait for the TCP connect.


new_cif_timeout The new timeout value.


new_connect_time_limit The new time value.

CsMailServOpts get_connect ion_retry_interval ( ) , set_connect ion_retry_interval ( )


get_connection_retry_interval ( ), set_connection_retry_interval ( )

int get_connection_retry_interval ( void ) const ;

void set_connection_retry_interval ( int new_connection_retry_interval ) ;

This pair of methods retrieves and sets the number of milliseconds SSAPI will wait before it attempts to retry a connection

get_enable_queue_send ( ), set_enable_queue_send ( )

CsTboolean get_enable_queue_send ( void ) const ;

void set_enable_queue_send ( CsTboolean new_enable_queue_send ) ;

This pair of methods returns and sets whether to queue requests. Enable this option if your application makes a lot of requests on a single callback.


new_connection_retry_interval The new retry interval.


new_enable_queue_send The new queueing value.

CsMailServOpts get_keep_al ive_batch ( ) , set_keep_al ive_batch ( )


get_keep_alive_batch ( ), set_keep_alive_batch ( )

CsTulong get_keep_alive_batch ( void ) const ;

void set_keep_alive_batch ( CsTulong new_keep_alive_batch ) ;

These methods are used to manage “keep alive” requests on a server. The “get” method retrieves the number of milliseconds between requests while the “set” method sets the number of requests sent on a single callback. Setting this number too small with a lot of connections may cause it to take longer than the “keep alive interval” to check all connections. Setting this number too large may cause the application to hang as it does too much on a single callback. Setting this value to 0 will disable batching so all "keep alive" requests will be sent on a single callback.

get_keep_alive_interval ( ), set_keep_alive_interval ( )

CsTulong get_keep_alive_interval ( void ) const ;

void set_keep_alive_timeout ( CsTulong new_keep_alive_interval ) ;

These methods retrieve and set the number of milliseconds between "keep alive" requests to a server. No "keep alive" requests will be sent if this value is 0.


new_keep_alive_batch The new time value.


new_keep_alive_interval The new interval value.

CsMailServOpts get_keep_al ive_t imeout ( ) , set_keep_al ive_t imeout ( )


get_keep_alive_timeout ( ), set_keep_alive_timeout ( )

CsTulong get_keep_alive_timeout ( void ) const ;

void set_keep_alive_timeout ( CsTulong new_keep_alive_timeout ) ;

These methods retrieve and set the number of milliseconds to wait for a response to a "keep alive" request to a server. Since these requests are so simple, the server should be able to respond more quickly than the usual mail timeout.


new_keep_alive_timeout The new timeout value.

CsMailServOpts get_local_queue_size ( ) , set_ local_queue_size ( )


get_local_queue_size ( ), set_local_queue_size ( )

int get_local_queue_size ( void ) const ;

void set_local_queue_size ( int new_local_queue_size ) ;

The “get” method of this pair retrieves the size of the local queue, while the “set” method sets the maximum number of outstanding local requests that an application can make.


new_local_queue_size The new queue size value.


CsMailServOpts set_ login ( ) , get_user_name ( )


set_login ( ), get_user_name ( )

void set_login ( const char * new_password, const char * new_user_name = 0 ) ;

const char * get_user_name ( void ) const ;

The set_login() method sets the password and optionally the user name for the user running the application. This password and user will be used to log in to all SPECTRUM servers.

The get_user_name() method gets the username of the user running the application. It may return null which indicates that the user specified by the operating system will be used.

get_mail_queue_size ( ), set_mail_queue_size ( )

int get_mail_queue_size ( void ) const ;

void set_mail_queue_size ( int new_mail_queue_size ) ;

The “get” method of this pair retrieves the size of the mail queue, while the “set” method determines the maximum number of outstanding requests that an application can make.


new_password The login password.

new_user_name The user name for logging in.

Note:Note:

The password is encrypted when set and cannot be read back in plain text, so there is no method to get the password.


new_mail_queue_size The new queue size.

CsMailServOpts get_mai l_t imeout ( ) , set_mai l_t imeout ( )



int get_mail_timeout ( void ) const ;

void set_mail_timeout ( int new_mail_timeout ) ;

These methods retrieve and set the number of milliseconds that the Mail Service waits for a response from the SpectroSERVER before the request is cancelled.

get_max_send_batch_size ( ), set_max_send_batch_size ( )

CsTulong get_max_send_batch_size ( void ) const ;

void set_max_send_batch_size ( CsTulong new_max_send_batch_size ) ;

These methods retrieve and set the maximum number of messages sent on a single callback on a connection.


new_mail_timeout The new timeout value.


new_max_send_batch_size The login password.

CsMailServOpts get_max_unsol_reg ( ) , set_max_unsol_reg ( )


get_max_unsol_reg ( ), set_max_unsol_reg ( )

Int get_max_unsol_reg ( void ) const ;

void set_max_unsol_reg ( int new_max_unsol_reg ) ;

These methods retrieve and set the maximum number of unsolicited registrations currently supported.


CsVersionNumber get_min_version ( void ) const ;

void set_min_version ( CsVersionNumber new_min_version ) ;

These methods set and retrieve the minimum VPAPI version that this application needs to communicate with a server.


new_max_unsol_regt The new max value.


new_min_version The new minimum version of VPAPI supported.

CsMailServOpts get_no_tcp_delay_f lag ( ) , set_no_tcp_delay_f lag ( )


get_no_tcp_delay_flag ( ), set_no_tcp_delay_flag ( )

CsTboolean get_no_tcp_delay_flag ( void ) const ;

void set_no_tcp_delay_flag ( CsTboolean new_no_tcp_delay_flag ) ;

These methods set and retrieve the value of no_tcp_delay_flag. If the value TRUE is returned, socket-level communications will not wait to receive an acknowledgement before the next request is sent.


CsTulong get_polling_cycle ( void ) const ;

void set_polling_cycle ( CsTulong new_polling_cycle ) ;

These methods return and set the current length of the polling cycle for server location information. The value returned is in milliseconds.


new_no_tcp_delay_flag The new flag value.


new_polling_cycle The new polling cycle length.

CsMailServOpts get_pr int_vers ion ( ) , set_pr int_version ( )



CsTboolean get_print_version ( void ) const ;

void set_print_version ( CsTboolean new_print_version ) ;

These methods return and set whether the version of SSAPI is printed when the mail service is constructed. If the option is TRUE then the version is printed to the standard output stream.

get_retry_batch ( ), set_retry_batch ( )

CsTulong get_retry_batch ( void ) const ;

void set_retry_batch ( CsTulong new_retry_batch ) ;

These methods retrieve and set the number of connections retried on a single callback. Setting this number too small with a lot of connections may cause it to take longer to reconnect to servers. Setting this number too large may cause the application to hang as it does too much on a single callback. Setting this value to 0 will disable batching so all connections will be retried on a single callback.


new_print_version The new flag value.


new_retry_batch The new batch value.

CsMailServOpts get_tcp_buf fer_size ( ) , set_tcp_buffer_size ( )



CsTulong get_tcp_buffer_size ( void ) const ;

void set_tcp_buffer_size ( CsTulong new_tcp_buffer_size ) ;

These methods retrieve and set the size of the TCP buffer.

get_use_polling ( ), set_use_polling

CsTboolean get_use_polling ( void ) const ;

void set_use_polling ( CsTboolean new_use_polling_flag ) ;

These methods set and retrieve the value of the use_polling option flag. If the option is TRUE, polling is used.

The set_use_polling() method is used to turn on the ability for the application to periodically poll the LocServer, if the LocServer is unavailable when the application is started. It should only be used if the application will be started on a system at boot time, before the LocServer is started.


new_tcp_buffer_sizet The new buffer size.


new_use_polling_flag The new flag value.

CsMailServOpts operator = ( )


operator = ( )CsMailServOpts & operator =

( const CsMailServOpts & right_hand_side ) ;

The assignment operator for this class


right_hand_side The object from which the data will be copied.

CsMSAppID operator = ( )


CsMSAppID

Class Hierarchy

Include FileCsMSAppID.h

DescriptionThis class is used to pass application information to the Mail Service. A reference to a CsMSAppID object is passed as an argument in the CsMailService constructor to set the Application ID information.

See also

CsMailServ.h

CsMSAppID

CsMSAppID operator = ( )


Public Methods

Method Description

CsMSAppID ( ) Class constructor.

CsMSAppID ( ) Class copy constructor.

get_appl_name ( ) Returns the application name.

get_appl_ver ( ) Returns the application version.

get_subappl_name ( ) Returns the sub-application name.


CsMSAppID CsMSAppID ( )


CsMSAppID ( )CsMSAppID ( const char * const new_application_name = “UNKNOWN”,

const char * const new_application_version = “0.0”,const char * const new_sub_application_name =

“UNKNOWN” ) ;

This method constructs a CsMSAppID object which is used as an argument in a CsMailService constructor to set the application ID information.


new_application_name The name of the client application establishing the connection, used by the application for identification. A list of the client’s applications attached to a SpectroSERVER may be viewed in the VNM Client View. An example would be “SpectroGRAPH.” The default value is “UNKNOWN.”

new_application_version The version number of the client application establishing the connection, used by the application (not by SpectroSERVER) for identification. An example would be “1.12.” The default value is “0.0.”

new_sub_application_name The name of the sub-application establishing the connection, used by the application (not by SpectroSERVER) for identification. An example would be “Device View.” The default value is “UNKNOWN.”

CsMSAppID CsMSAppID ( )


CsMSAppID ( )CsMSAppID ( const CsMSAppID & original ) ;

A copy constructor.

get_appl_name ( )const char * get_appl_name ( void ) const ;

This method returns the application name.

get_appl_ver ( )const char * get_appl_ver ( void ) const ;

This method returns the application version.

get_subappl_name ( )const char * get_subappl_name ( void ) const ;

This method returns the sub-application name.

operator = ( )CsMSAppID & operator = ( const CsMSAppID & right_hand_side ) ;

The class assignment operator.


original The object to be copied.



CsMailClient operator = ( )


CsMailClient

Class Hierarchy

Include FileCsMlClient.h

DescriptionCsMailClient is an abstract class that defines the interface for all Asynchronous SSAPI clients. CsMailClient should never be instantiated. Instead, derive an application client class from CsMailClient.

CsMailClient

CsMailClient CsMai lCl ient ( )


Public Methods

CsMailClient ( )CsMailClient ( void ) ;

This is the default constructor for the class.

CsMailClient ( )CsMailClient ( const CsMailClient & original ) ;

This is the copy constructor for the class.

Method Description

CsMailClient ( ) Class constructor.

CsMailClient ( ) Class copy constructor.

Notify ( ) This method is called by the CsMailService when it receives a message destined for the subscriber.

Timeout ( ) Used to take advantage of a MailClient’s built-in timed callback facilities.




CsMailClient Not i fy ( )


Notify ( )int Notify ( MessageType_e msg_type, CsTresponseid res_id,

CsModelAncestor * uihandle ) ;

This method is declared to return an integer but the return code is not checked/used by the SSAPI. This method is declared by CsMailClient but not defined. It should be defined by each subscriber that is derived from CsMailClient. It is called by the CsMailService when it receives a message destined for the subscriber.

Among other things, the Notify() method of a subscriber must be defined to include the code that calls the retriever of the handle object, passing it res_id as a parameter, to retrieve the message it has received. A simple example of this code appears in rel_test.cc and is discussed in the SpectroSERVER API Developer’s Guide.

See also:

• For unsolicited responses: CsMailService::UnSolRegister() and the initiator/retriever pairs of the Handle classes.

• For responses solicited by the subscriber: CsMailService::deliver() and the initiator/retriever pairs of the Handle classes.


msg_type The type of message being received from the SpectroSERVER. For SSAPI, this is always set to CsMTVNM, an internally defined message type.

res_id The response ID that was returned to the subscriber by the initiator. If the res_id is not the response ID, then the message is unsolicited.

uihandle A pointer to the handle object that has been given the response.

CsMailClient Timeout ( )


Timeout ( )int Timeout ( int ) ;

Timeout() is a pure virtual method declared, but not defined, by CsMailClient. It must be defined by each subscriber that is derived from CsMailClient. This method is used by Applications that wish to take advantage of a MailClient’s built-in timed callback facilities. Applications that do not need these facilities may simply define this method as doing nothing and returning 0, as shown below:

int this_mail_client::Timeout ( int ){ return 0 ;}

operator = ( ) CsMailClient & Operator =

( const CsMailClient & right_hand_side ) ;

This is the assignment operator for the class.


right_hand_side Object from which the data will be copied.

CsTimer operator = ( )


CsTimer

Include FileCsTimer.h

DescriptionThe CsTimer class provides an abstraction over the Xt intrinsics that will invoke a user-specified callback at a particular time interval. The user calls one method to add a timer for a scheduled callback and one method to remove the timer from the timer queue.

A CsTimer object, when used to add a scheduled callback timer, will register itself with a global array of CsTimer objects. The class keeps its own dynamic array of scheduled callback timers.

The CsTimer class uses the application's underlying timing and dispatch mechanism.

CsTimer CsTimer ( )


Public Methods

CsTimer ( )CsTimer ( CsMailClient * who ) ;

Constructs a CsTimer object and initializes its member variables. It takes as an argument, a pointer to the CsMailClient who owns the CsTimer object.

Addtimer ( )Addtimer ( unsigned long interval, int tag ) ;

This method is used to set a timer for a scheduled callback. The method called when the timer expires is the Timeout() method of the CsMailClient passed to the constructor.

Method Description

CsTimer ( ) Class constructor.

Addtimer ( ) Sets a timer for a scheduled callback.

Removetimer ( ) Removes a timer from the timer queue.


who The CsMailClient object to be notified on completion.


interval The number of milliseconds which should elapse before the timer expires.

tag Unique identifier to help with callbacks.

CsTimer Removet imer ( )


Removetimer ( )Removetimer ( int tag ) ;

This method is used to remove a timer for a scheduled callback from the timer queue. The tag is a user-defined identifier which should match the tag of a timer added by calling Addtimer(). If assigned tags are not unique, Removetimer() may be unable to remove the intended timer. It will search the object's list of timers and stop at the first tag matching the value of its argument.


tag Identifier of timer to be removed.

Note:Note:

If a matching tag cannot be found, an error message will not be displayed.

CsModelAncestor Removet imer ( )


CsModelAncestor

Class Hierarchy

Include FileCsMdlAnces.h

DescriptionCsModelAncestor is the base class for the set of classes called CsUIHandle, i.e., CsHandleAncestor is derived from CsModelAncestor, and all the UIHandles are derived from CsHandleAncestor.

CsModelAncestor

CsModelAncestor Removet imer ( )


Public Methods

Method Description

CsModelAncestor ( ) The default constructor.

CsModelAncestor ( ) The copy constructor.

copy ( ) Virtual copy method.

get_current_connect_error ( ) Returns the connection error for this handle.

get_current_server ( ) Sets the current server socket address to match the server where requests for this handle would be sent.

get_current_version ( ) Returns the current VPAPI version used to communicate with the current server.

get_service_id ( ) Returns a copy of this handle's service ID.

get_service_type ( ) Returns this handle's service type.

get_unsol_response ( ) Retrieves unsolicited responses.

is_connected ( ) Tests error code for connection failure.

is_connection_failure ( ) Tests the connection error code for indication of connection failure.

is_connection_success ( ) Tests error code for connection success.

is_current_primary ( ) Checks whether requests will be sent to the primary server.

is_equal_service ( ) Compares handles for use of identical service ID.

operator = ( ) Assignment operator for the class.

CsModelAncestor CsModelAncestor ( )


CsModelAncestor ( )CsModelAncestor ( void ) ;

The default constructor for the class. Stores a reference to the default SpectroSERVER.

CsModelAncestor ( )CsModelAncestor ( const CsModelAncestor & original ) ;

This is the copy constructor for this class.

copy ( )CsModelAncestor * copy ( void ) const ;

This creates a complete copy of this handle. It is virtual, so the copy will be derived as well.



Caution:Caution:

The caller is responsible for deleting memory allocated to the CsModelAncestor object returned by copy.

CsModelAncestor get_current_connect_error ( )




This method returns the current connection error for this handle. If the error_message parameter is not 0, then a vector duplicated copy of the corresponding error message is also returned. If there is no error message, then error_message will be set to 0. The error returned by this method is always the most current.


error_message Returned error message.

Caution:Caution:

The caller is responsible for deleting the returned error message using a C++ vector delete statement.

Caution:Caution:

Be careful when using this method when called back for a connection notification. It is possible that the connection state has changed since the notification was queued and this method may give an error that is inconsistent with the notification error code.

CsModelAncestor get_current_server ( )


get_current_server ( )CsTboolean get_current_server

( CsSocketAddress * current_server ) const ;

This method sets the current server socket address to match the server where requests for this handle would be sent. If there is no available server for this handle, then the socket address for the primary server is returned. In both cases TRUE is returned unless no server has data for this handle. The current server socket address is passed in by the calling method and set by this method. Using this mechanism allows the application to allocate the socket address on the stack or heap as desired and does not require the mail service to manage the memory.

get_current_version ( )CsVersionNumber get_current_version ( void ) const ;

This method returns the current VPAPI version used by this handle to communicate with the current server. If there is no current server, the default version is returned.

get_service_id ( )CsServiceID * get_service_id ( void ) const ;

This method returns a copy of this handle's service ID.


current_server The new socket address.

Caution:Caution:

The caller is responsible for deleting memory allocated to the CsServiceID object returned by get_service_id().

CsModelAncestor get_service_type ( )


get_service_type ( )CsServiceType::CsServiceType_e get_service_type ( void ) const ;

This method returns this handle's service type.

get_unsol_response ( )CsVnmParmBlock * get_unsol_response

( CsTresponseid response_id ) ;

This method is used to retrieve unsolicited responses. At the time of writing, such responses are sent when connection events occur for the CsModelAncestor's service, and the CsModelAncestor has been registered for notification of such events through the CsMailService::register_for_connect () method. The response_id is the ID returned by the register_for_connect () method. The VnmParmBlock returned by this method will contain a CsError indicating the type of connection event which occurred.


response_id Identifier of initial request.

Caution:Caution:

The caller is responsible for deleting memory allocated to the CsVnmParmBlock object returned by get_unsol_response().

CsModelAncestor is_connected ( )


is_connected ( )CsTboolean is_connected ( void ) const ;

This method returns TRUE if a connection is available to a server for this handle. If no connection is available, FALSE is returned.

is_connection_failure ( )CsTboolean is_connection_failure

( CsError::CsError_e error_code ) ;

This method is used to test a connection error code for indication of connection failure. This is used to check error codes in responses to see if they failed from a connection problem.

is_connection_success ( )CsTboolean is_connection_success

( CsError::CsError_e error_code ) ;

This method tests a connection error code for indication that a connection has been established. This is used to check connection events.

Note:Note:

The is_connection_failure (), and is_connection success () methods are new for 6.0.


error_code Error code to be checked.



CsModelAncestor is_current_pr imary ( )


is_current_primary ( )CsTboolean is_current_primary ( void ) const ;

This method checks whether requests will be sent to the primary server. It returns TRUE if requests are being sent to the primary or there is no available server for this handle. If requests are being sent to a secondary server, this method returns FALSE.

is_equal_service ( )CsTboolean is_equal_service

( const CsModelAncestor & other_handle ) const ;

This compares the other handle with this handle to test whether they use the same service ID.

operator = ( )CsModelAncestor & operator =

( const CsModelAncestor & right_hand_side ) ;

This is the assignment operator for this class.


other_handle Object for comparison.



CsHandleAncestor operator = ( )


CsHandleAncestor

Class Hierarchy

Include FileCsHndlAnces.h

DescriptionThis class provides a consistent interface to the UIHandle classes Landscape, Model, ModelType, and Relation. This class provides the methods and members necessary to send and receive messages through the mail service interface (socket). The messages are packed in a CsVnmParmBlock. There can be at most 10 messages (QUE_DEPTH) queued at any time. The responses are identified using the response id returned by the async() method.

CsModelAncestor

CsHandleAncestor

CsHandleAncestor CsHandleAncestor ( )


Public Methods

CsHandleAncestor ( )CsHandleAncestor ( unsigned long vnm_entity_handle ) ;

This is the default constructor for this class. It initializes all members that belong to this class. As the name suggests, the argument is the generic handle. This method will route requests to the default landscape of the initial VNM.

CsHandleAncestor ( )CsHandleAncestor ( unsigned long vnm_entity_handle,

unsigned long location ) ;

This is an overloaded constructor which accepts two parameters, a vnm_entity_handle which is a generic handle, and a location which is the landscape to which requests should be routed.

Method Description

CsHandleAncestor ( ) Class constructor.

CsHandleAncestor ( ) Overloaded constructor.

CsHandleAncestor ( ) Copy constructor.

copy ( ) Creates a copy of the handle.

get_vnm_handle ( ) Retrieves VNM mail handle.

operator = ( ) Assignment operator.


vnm_entity_handle A generic handle.

location The landscape to which requests should be routed.

CsHandleAncestor CsHandleAncestor ( )


CsHandleAncestor ( )CsHandleAncestor ( const CsHandleAncestor & original ) ;

The copy constructor for the class.



get_vnm_handle ( )unsigned long get_vnm_handle ( void ) const ;

Get the VNM handle for this mail handle.

operator = ( )CsHandleAncestor & operator =

( const CsHandleAncestor & right_hand_side ) ;

An assignment operator for the class.



Caution:Caution:

The caller is responsible for deleting memory allocated to the CsModelAncestor object returned by copy().



Asynchronous Handle Classes



This section outlines the handle classes which are used by MailClients to communicate with the CsMailService.

To facilitate asynchronous communications, the methods of handle classes come in pairs. The first method of each pair has the suffix “_async” and is called to initiate a request, such as read2_async(). Such a method is referred to as an initiator throughout this document. The second half of the pair, such as read(), is called to retrieve the response to the request. Such a method is referred to as a retriever in this document.

A handle exists for each major class of entity that might be found within the SPECTRUM database. For each handle method pair, the format of the synopsis section is as follows:

1 The calls are shown for the initiator and the retriever.

2 The functionality provided by the pair is described, including any CsVnmParmBlock object that is an input to the initiator.

3 The object that is returned by the retriever is described.

4 References are listed to sections of this document where other information relevant to the initiator/retriever pair can be found.

5 In all cases, an overall error code is set in the CsVnmParmBlock object returned by the retriever; it can be obtained by calling CsVnmParmBlock::get_error(). If the request was successful, this returns CsError::SUCCESS. Other error codes are listed in the file /VPAPI/include/CsError.h. In addition, each retriever can set error codes for certain parts of the request.

All Asynchronous handles (except CsUIGlobalScapeHandle) establish a connection to the landscape explicitly or implicitly specified by the constructor used to instantiate the handle. The handle first checks whether a connection to the appropriate landscape already exists, and, if



not, opens one. The connection to a landscape is closed when the last handle connected to that landscape is destroyed.

Caution:Caution:

The handle class constructors use connection resources and are not intended to be copied, assigned to, or passed by value. They can be passed by reference, or by using a pointer.If the constructor does not specify a landscape, as is the case with the constructors from previous SSAPI releases (retained for backward compatibility), the connection established is to the initial landscape (i.e., the landscape on the SpectroSERVER host specified in the CsMailService constructor). However, for applications that take advantage of the distributed SpectroSERVER capabilities, a landscape should be specified when constructing a new handle.

Caution:Caution:

The exceptions to the previous are: CsUIGlobalScapeHandle, which does not open a connection to a landscape but instead opens and closes connections through the CsUILandScapeHandle(s) used in the searches.CsUIVLMap, which does not provide a constructor that specifies a landscape, since the V/L Map information is not landscape-specific.When the CsMailService is destroyed, all means of connecting to landscapes are removed. Therefore, handles should not be created before the CsMailService has been instantiated, nor destroyed after the CsMailService is deleted.

Caution:Caution:

Most VnmParmBlock objects used as input to an initiator must be allocated memory. The CsMailService takes control of the memory and deletes it when finished. The exceptions are when the CsVnmParmBlock is passed by reference, which occurs in some methods of CsUIRelationHandle

In addition, all VnmParmBlocks returned by the retriever are allocated memory and it is the developer’s responsibility to free this memory.

CsUIAlarm


CsUIAlarm

Class Hierarchy

Include FileCsUIAlarm.h

DescriptionThe CsUIAlarm class provides methods that allow the clearing, updating, and receiving of alarms.

CsModelAncestor

CsUIAlarm

CsUIAlarm


Public Methods

Method Description

CsUIAlarm ( ) Class constructor.

CsUIAlarm ( ) Copy constructor.

ack_alarm_async ( ), ack_alarm ( )

Acknowledges and retrieves alarms.

alarm_update ( ) Retrieves unsolicited alarm messages.

attach_async ( ), attach ( ) This pair of methods is used for attaching to the SpectroSERVER Alarm Manager.

clear_alarm_async ( ), clear_alarm ( )

This pair is used to clear an alarm.

copy Creates a complete copy of the handle.

detach_async ( ), detach ( ) This pair of methods is used for detaching from the SpectroSERVER Alarm Manager.

replace_filter_async ( ) replace_filter ( ),

Changes and replaces the filter that screens alarm data.

update_alarm_async ( ), update_alarm ( )

This pair of methods is used to change the status of an alarm.


CsUIAlarm CsUIAlarm ( )


CsUIAlarm ( )CsUIAlarm ( CsLscpeHandle & my_landscape ) ;

This method constructs a CsUIAlarm object that provides a user-level interface to a particular landscape, to perform functions such as updating and clearing alarms, as well as retrieving unsolicited alarms.

See also:

CsLscpeHandle in the VnmParmBlock Reference, and the section on the Distributed SpectroSERVER in the SSAPI Developer’s Guide.

CsUIAlarm ( )CsUIAlarm ( const CsUIAlarm & original ) ;

This is the copy constructor for CsUIAlarm.


my_landscape A CsLscpeHandle object that contains the landscape handle for a specific landscape.



CsUIAlarm ack_alarm_async ( ) , ack_alarm ( )


ack_alarm_async ( ), ack_alarm ( )

CsTresponseid ack_alarm_async ( CsAlarmRegister * what, CsMailClient * who ) ;

CsVnmParmBlock * ack_alarm ( CsTresponseid r_id ) ;

This pair of methods is responsible for acknowledging alarms. The list of the alarms to be acknowledged is contained in the given AlarmRegister. Check the error code in the returned CsVnmParmBlock to indicate if the request was successful.


what A CsAlarmRegister object that contains lists of alarms to acknowledge.


r_id The response ID identifying the returned message.

CsUIAlarm alarm_update ( )


alarm_update ( )CsAlarmRegister * alarm_update ( CsTresponseid r_id ) ;

This method returns a pointer to a CsAlarmRegister object containing the new alarms. As new alarms are generated, they are sent periodically from SpectroSERVER.

A call to alarm_update() is used in retrieving an unsolicited alarm message in the following manner:

1 Message Arrives — The CsMailService receives an unsolicited message (unexpected response ID) for the subscriber from SpectroSERVER.

2 Unpack Message — The CsMailService unpacks the message, creating a CsAlarmRegister object, and passes it to the CsUIAlarm object.

3 Notify Subscriber — The CsMailService calls the client’s Notify() using the unsolicited response ID.

4 Get Pointer — Within the Notify(), the subscriber calls the alarm_update() retriever method and passes to it the response ID passed to the Notify() method.

5 Retrieve Information — The subscriber processes the information within the CsAlarmRegister, as required.

See also:

VnmParmBlock Reference on CsAlarmRegister for more information on retrieving information from an AlarmRegister.


r_id Response ID identifying the unsolicited registration.

Caution:Caution:

The Notify() method of a subscriber should be defined to include the code that calls the retriever of CsUIAlarm, passing it res_id as a parameter, to retrieve the alarm update message it has received. An example of this code appears in the AlarmDemo program, in the SpectroSERVER API Developer’s Guide.

CsUIAlarm at tach_async ( ) , at tach ( )


In addition see the CsMailService::UnSolRegister() method.

attach_async ( ), attach ( )

CsTresponseid attach_async ( CsAttachRequest * what, CsMailClient * who ) ;

CsAlarmAttachResponse * attach ( CsTresponseid r_id ) ;

This pair of methods is used for attaching to the SpectroSERVER Alarm Manager. This allows the Application to receive new alarms as they are generated. The attach process should include the following steps:

1 Register for unsolicited messages:

a Call the CsMailService method UnsolRegister() with the following parameters.

• A pointer to an instantiation of a derived class of CsMailClient with a Notify() to handle the unsolicited alarm messages.

• A pointer to an instantiation of CsUIAlarm handle.

b Save the response ID from UnsolRegister().

2 Construct a CsAttachRequest Object:

a Pass the constructor the response ID returned from UnsolRegister().

3 Attach to the CsMailService for Alarms:

a Call the attach_async() method of CsUIAlarm with the following parameters:


what A CsAttachRequest defining the attach information..



CsUIAlarm at tach_async ( ) , at tach ( )


• A pointer to the CsAttachRequest object just constructed.

• A pointer to an instantiation of a derived class of CsMailClient with a Notify() defined to handle the attach request response.

A pointer to a CsAlarmAttachResponse containing the alarm or error codes is returned. The response contains the alarms that have been generated. There also is a window ID within the response. This window ID should be saved, because it is needed to detach from SpectroSERVER Alarm Manager.

Table 3 lists the possible CsError error return codes:

See also:

The section in the VnmParmBlock Reference on CsAttachRequest for more information on constructing an AttachRequest, and the section on CsAlarmAttachResponse.

Table 3: attach_async() and attach() Error Codes

Error Meaning

INSUFFICIENT_MEMORY There was insufficient memory on the attached SpectroSERVER to accommodate the request.

CS_NULL_INPUT The CsVnmParmBlock received by the attached SpectroSERVER was NULL — causing a CsVnmParmBlock error to be returned.

SUCCESS The attach was successful.

CsUIAlarm c lear_alarm_async ( ) , c lear_alarm ( )


clear_alarm_async ( ), clear_alarm ( )

CsTresponseid clear_alarm_async ( CsAlarmRegister * what, CsMailClient * who ) ;

CsVnmParmBlock * clear_alarm ( CsTresponseid r_id ) ;

This pair is used to clear an alarm (e.g., to clear a duplicate IP address alarm). The retriever method returns a pointer to a CsVnmParmBlock object that indicates whether the action was successful.

Table 4 lists the possible CsError error return codes.


what A CsAlarmRegister object that is a list of CsAlarmListNode objects, each of which is a list of CsAlarmList objects. Each CsAlarmList object is itself a list of alarms (CsAlarmNode objects) for a particular model.



Table 4: CsUIAlarm clear_alarm_async() and clear_alarm() Error Codes

Error Meaning


CS_NULL_INPUT The CsVnmParmBlock object received by the attached SpectroSERVER was NULL — causing an error to be returned.

NULL_MESSAGE A valid CsVnmParmblock object was accepted by the interface, but an internal error resulted in no valid response being generated.

CsUIAlarm copy


See also:

The VnmParmBlock Reference sections on CsAlarmRegister, CsAlarmListNode, CsAlarmList, and CsAlarmNode for information on constructing a CsAlarmRegister and setting its member lists. Also, see the section on CsVnmParmBlock object for information on retrieving information from a CsVnmParmBlock object.

copyCsModelAncestor * copy ( void ) const ;


CIF_FAILURE Could not contact client application. This is an internal error.

NO_SUCH_ALARM An alarm with the designated model handle ID could not be found.

SUCCESS The alarm was cleared successfully.

Caution:Caution:


Table 4: CsUIAlarm clear_alarm_async() and clear_alarm() Error Codes

Error Meaning

CsUIAlarm detach_async ( ) , detach ( )


detach_async ( ), detach ( )

CsTresponseid detach_async ( CsWindowId * what, CsMailClient * who ) ;

CsVnmParmBlock * detach ( CsTresponseid r_id ) ;

This pair of methods is used for detaching from the SpectroSERVER Alarm Manager. The Application will no longer receive new alarms from SpectroSERVER. Check the error code to see if the detach was successful.

Table 5 lists the possible error return codes.

See also:

The VnmParmBlock Reference section on CsWindowId for more information on constructing a CsWindowId object.


what A CsWindowId object created from information received with the CsUIAlarm::attach() method was called.

who The CsMailClent object to be notified on completion.


Table 5: detach_async() and detach() Error Codes

Error Meaning


CS_NULL_INPUT The VnmParmBlock received by the attached SpectroSERVER was NULL — causing a VnmParmBlock error to be returned.

NO_SUCH_WINDOW_ID The referenced window_id was not valid.

SUCCESS Detach was successful.

CsUIAlarm replace_f i l ter_async ( ) replace_f i l ter ( ) ,


replace_filter_async ( ) replace_filter ( ),

CsTresponseid replace_filter_async ( CsAlarmFilterPB * what, CsMailClient * who ) ;

CsAlarmRegister * replace_filter ( CsTresponseid r_id ) ;

These methods are used to change and replace the filter that is used to screen the alarm information sent by the SpectroSERVER. It takes as an argument the response_id returned by the initiator when making the replace_filter request. The response is a list of all alarms that pass the new filter.


what The new filter to screen alarms for this application.



CsUIAlarm update_alarm_async ( ) , update_alarm ( )


update_alarm_async ( ), update_alarm ( )

CsTresponseid update_alarm_async ( CsAlarmRegister * what, CsMailClient * who ) ;

CsVnmParmBlock * update_alarm ( CsTresponseid r_id ) ;

This pair of methods is used to change the status of an alarm. The Application could, for example, change the status from “unknown” to “hardware failure”. The retriever method returns a pointer to a CsVnmParmBlock. Check the error code to see if the update request was successful.



what A CsAlarmRegister object that is a list of CsAlarmListNode objects, each of which is a list of CsAlarmList objects. Each CsAlarmList object is itself a list of alarms (CsAlarmNode objects for a particular model).



Table 6: CsUIAlarm update_alarm_async() and update_alarm Error Codes

Error Meaning


CS_NULL_INPUT The CsVnmParmBlock object received by the attached SpectroSERVER was NULL — causing an error to be returned.

CsUIAlarm operator = ( )


See also:

The VnmParmBlock Reference sections on CsAlarmRegister, CsAlarmListNode, CsAlarmList, and CsAlarmNode for information on constructing an AlarmRegister and setting its member lists. Also see the section on CsVnmParmBlock for information on retrieving information from a VnmParmBlock object.

operator = ( ) CsUIAlarm &operator = ( const CsUIAlarm & right_hand_side ) ;

This is the assignment operator for CsUIAlarm.

NULL_MESSAGE A valid CsVnmParmblock was accepted by the interface, but an internal error resulted in no valid response being generated.



SUCCESS The alarm was updated successfully.



Table 6: CsUIAlarm update_alarm_async() and update_alarm Error Codes

Error Meaning

CsUIEvent operator = ( )


CsUIEvent

Class Hierarchy

Include FileCsUIEvent.h

DescriptionThe CsUIEvent class provides methods for reading the events accessible to a single SpectroSERVER either from its internal database or the archived statistics/events database. The methods include those necessary to choose the types of events to query for, and to scroll up or down in the events database for earlier or later events in time, relative to the current position.

CsModelAncestor

CsUILogs

CsUIEvent

Note:Note:

The retriever method descriptions for this class can be found in CsUILogs.h. These methods have been included here for clarity.

CsUIEvent operator = ( )


Public Methods

Method Description

CsUIEvent ( ) Class constructor.

CsUIEvent ( ) Copy constructor.

attach_async ( ), attach ( ) This pair of methods allows the Application to attach to the EventManager.

copy ( ) Makes a complete copy of the handle.

create_event_async ( ), create_event ( )

This pair of methods logs an event into the SpectroSERVER’s Event database and triggers any alarm associated with this event in the EventDisp file.

detach_async ( ), detach ( ) This pair of methods is used to detach from the Event Manager.

get_messages_async ( ), get_messages ( )

This pair of methods is used to get the list of events for the given list of IDs.

log_message_async ( ), log_message ( )

This pair of methods logs an event into the SpectroSERVER’s Event database, and the EventDisp file is not read for possible alarm generation.

replace_filter_async ( ), replace_filter ( )

This pair of methods changes the filter used to screen the events that are sent.

scroll_down_async ( ), scroll_down ( )

Allows the Application to scroll down within the SpectroSERVER Event Log database.

scroll_to_bottom_async ( ), scroll_to_bottom ( )

Allows the Application to scroll to the bottom of the SpectroSERVER Event Log database.

scroll_to_date_time_async ( ), scroll_to_date_time ( )

Allows the Application to scroll to the first event matching the specified date and time within the SpectroSERVER Event Log database.

scroll_to_top_async ( ), scroll_to_top ( )

Allows the Application to scroll to the top of the SpectroSERVER Event Log database.

CsUIEvent CsUIEvent ( )


CsUIEvent ( )CsUIEvent ( CsLscpeHandle my_landscape ) ;

This method constructs a CsUIEvent object that provides a user-level interface to a particular landscape, to perform functions such as selecting the types of events to query, or scrolling up or down the SpectroSERVER database.

See also:

CsLscpeHandle in the VnmParmBlock Reference, and the section on Distributed SpectroSERVER in the SpectroSERVER API Developer’s Guide.

CsUIEvent ( ) CsUIEvent ( const CsUIEvent & original ) ;

scroll_up_async ( ), scroll_up ( ) Allows the Application to scroll up within the SpectroSERVER Event Log database.

unsol_scroll ( ) The retriever that should be used whenever an unsolicited event comes in from SpectroSERVER.





Method Description

CsUIEvent CsUIEvent ( )


The copy constructor for this class.

CsUIEvent at tach_async ( ) , at tach ( )



CsTresponseid attach_async ( CsIEventFilter * what, CsMailClient * who ) ;

CsAttachResponse * attach ( CsTresponseid r_id ) ;

This pair of methods allows the Application to attach to the EventManager in SpectroSERVER. Attaching allows the Application to receive new events as they are generated.

The attach process should include the following steps:


a Call the CsMailService method UnsolRegister() with the following parameters.

• A pointer to an instantiation of a derived class of CsMailClient with a Notify() to handle the unsolicited event messages.

• A pointer to an instantiation of CsUIEvent handle.


2 Construct a CsIEventFilter Object:


b Pass the constructor the number of events to filter.

c Pass the CsIEventFilter to the constructor, to filter events.

3 Attach to the CsMailService for Events:


what A CsIEventFilter that defines the types of events to be received.



CsUIEvent at tach_async ( ) , at tach ( )


a Call the attach_async() method of CsUIEvent with the following parameters:

• A pointer to the CsIEventFilter just constructed.

• A pointer to an instantiation of a derived class of CsMailClient. It must have a Notify() defined to handle the attach request response.

The retriever method returns a pointer to a CsAttachResponse object containing the events or error codes and a WindowId. This WindowId should be saved, because it is needed to detach from SpectroSERVER EventManager.

See also:

The VnmParmBlock Reference section on CsIEventFilter for more information on constructing an EventFilter. Also, see the section on CsAttachResponse.


Table 7: CsUIEvent attach_async() and attach() Error Codes

Error Meaning

NO_MORE_MESSAGES There are no messages in the event log that are applicable to the kind of filter that was used. If a datetime filter was chosen, there are no messages that match the filter, the cursor position in the database is beyond the edge of the database, or it is trying to read a message while the cursor is already on the last record. Choose a less limiting filter.

INSUFFICIENT_MEMORY There is not enough memory either to write the previous or the next record read from the database.

CsUIEvent copy ( )




NO_SUCH_WINDOW_ID The referenced window ID was not valid. Trying to scroll with an invalid ID can happen when attach fails for the client or when detach has been called with an invalid ID. The window ID should be obtained from the original attach response, AttachResponse using get_log_windowid() after verifying that the response is valid.

CS_NULL_INPUT An invalid attach_request() was sent for an attach. The request is either not known to the SpectroSERVER Event Manager or it has not been properly configured.

Caution:Caution:


Table 7: CsUIEvent attach_async() and attach() Error Codes

Error Meaning

CsUIEvent create_event_async ( ) , create_event ( )


create_event_async ( ), create_event ( )

CsTresponseid create_event_async ( CsIOEventList * what, CsMailClient * who ) ;

CsVnmParmBlock * create_event ( CsTresponseid r_id ) ;

This pair of methods is used to log an event into the SpectroSERVER’s database and, in addition, trigger any alarm that is associated with that event in the EventDisp file. A pointer to a CsVnmParmBlock object is returned, containing any error code for the create operation.

See also

See the VnmParmBlock Reference section on CsIOEventlist.


what A CsIOEventList object that contains the Event(s) to be added.



CsUIEvent detach_async ( ) , detach ( )



CsTresponseid detach_async ( CsILogWindowId * what, CsMailClient * who ) ;


This pair of methods is used to detach from the Event Manager in SpectroSERVER. Once detached, event updates cease. The Application must give the WindowId that it received when the CsUIEvent::attach() method was called.

Table 8 lists the CsError error return code.

See also

The VnmParmBlock Reference section on CsILogWindowId for more information on constructing a LogWindowId. Also refer to the section on CsVnmParmBlock for information on retrieving information from a VnmParmBlock object.


what A CsILogWindowId object created from information received when the CsUIEvent::attach() method was called..



Table 8: CsUIEvent detach_async() and detach() Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID being used to detach is invalid (there is no client with that ID). Use the WindowId received when the CsUIEvent::attach() method was called to construct the LogWindowId. Pass the LogWindowId to detach_async().

CsUIEvent get_messages_async ( ) , get_messages ( )


get_messages_async ( ), get_messages ( )

CsTresponseid get_messages_async ( CsEventIDListBlock * what, CsMailClient * who ) ;

CsEventErrorList * get_messages ( CsTresponseid r_id ) ;

This pair of methods is used to get the list of events for the given list of IDs.


what A CsEventIDListBlock object that describes the information to search for.



CsUIEvent log_message_async ( ) , log_message ( )


log_message_async ( ), log_message ( )

CsTresponseid log_message_async ( CsIOEventList * what, CsMailClient * who ) ;

CsVnmParmBlock * log_message ( CsTresponseid r_id ) ;

This pair of methods is used to record event messages for a specific model in the SpectroSERVER Event Log database. The retriever method returns a pointer to a CsVnmParmBlock. Check the error code to see if the request was successful.


See also:

See the VnmParmBlock Reference section on CsIOEventList for more information on constructing an IOEventList. Also see the section on


what A CsIOEventList object that is used to pass the Event log message to SpectroSERVER.



CsUIEvent log_message_async ( ) , log_message ( )


CsVnmParmBlock for information on retrieving information from a VnmParmBlock object.

Table 9: CsUIEvent log_message_async() and log_message() Error Codes

Error Meaning

CS_NULL_INPUT An invalid IOEventList was used to log a message. The EventList used to construct the IOEventList was corrupted, so the event nodes corresponding to the event message on the list were not properly configured. It could be from having an invalid model handle, or an improper CsVarData object carrying the event text. Check the EventMessage that was input to ensure that the EventNodes on the list have the proper values for the type of Event message being logged. For example, to log a user text message, the EventType for the Event node should be 0x10501. If it is anything else, the Event Node and Event Message are wrong. This further corrupts the CsEventList object and the CsIOEventList object.

NO_EVENT_ MESSAGE_IN_ LIST

There was no EventMessage in the IOEventList that was passed. An EventNode was not created for the message to log and consequently it was unable to create a proper CsEventList object or CsEventMessage object.

CsUIEvent replace_f i l ter_async ( ) , replace_f i l ter ( )



CsTresponseid replace_filter_async ( CsIEventFilter * what, CsMailClient * who ) ;

CsScrollResponse * replace_filter ( CsTresponseid r_id ) ;

Use this pair of methods to change the filter that screens the events that are sent. CsIEventFilter takes the window ID returned by the attach() method as one of its input parameters. Both methods return a pointer to a ScrollResponse that contains events that have passed the new filtering criteria.


See also: The VnmParmBlock Reference section on CsIEventFilter for more information on constructing an IEventFilter. Also see the section on CsScrollResponse for information about extracting the events.


what A CsIEventFilterId object that contains the filtering information to be applied.



Table 10: CsUIEvent replace_filter_async() and replace_filter() Error Codes

Error Meaning

INSUFFICIENT_MEMORY Not enough memory to create the new IEventFilter. Not enough memory was available when adding filter nodes on the EventFilter.

CsUIEvent replace_f i l ter_async ( ) , replace_f i l ter ( )


NO_MORE_MESSAGES There are no more messages in the event log that are applicable to the filter that was used. If datetime filters were chosen, there are no messages that fall between those datetime stamps. Also, the cursor position in the SpectroSERVER Event Log database is beyond the edge of the database. Choose a less limiting filter.

Table 10: CsUIEvent replace_filter_async() and replace_filter() Error Codes

Error Meaning

CsUIEvent scrol l_down_async ( ) , scrol l_down ( )



CsTresponseid scroll_down_async ( CsILogWindowId * what, CsMailClient * who ) ;

CsScrollResponse * scroll_down ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll down within the SpectroSERVER Event Log database. Scrolling down returns events that occurred later in time, relative to the current position. It takes the window ID returned from the attach() method as one of its input parameters. Both methods return a pointer to a ScrollResponse that contains the events.

See also: The VnmParmBlock Reference section on CsILogWindowId for more information on constructing one, and see the section on CsScrollResponse for more information on retrieving the events returned.



what A CsILogWindowId object that contains the window ID.



Table 11: CsUIEvent scroll_down_async() and scroll_down() Error Codes

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. The window ID should be obtained from the original AttachResponse using get_log_windowid(), after verifying that the response is valid.

NO_MORE_MESSAGES There are no more messages in the event log in the direction of scrolling (already at the bottom of the event log).

CsUIEvent scrol l_ to_bot tom_async ( ) , scrol l_to_bot tom ( )



CsTresponseid scroll_to_bottom_async ( CsILogWindowId * what, CsMailClient * who ) ;

CsScrollResponse * scroll_to_bottom ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll to the bottom of the SpectroSERVER Event Log database. Scrolling to the bottom returns the latest events in the database to the Application. It takes the window ID returned from the attach() method as one of its input parameters.

See also:

The VnmParmBlock Reference section on CsILogWindowId for more information on constructing one. Also refer to the section on CsScrollResponse for more information on retrieving the events returned.

Table 12 lists the possible CsError error return code.





Table 12: scroll_to_bottom_async() and scroll_to_bottom Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. The window ID should be obtained from the original AttachResponse using get_log_windowid() after verifying that the response is valid.

CsUIEvent scrol l_to_date_t ime_async ( ) , scrol l_to_date_t ime ( )



CsTresponseid scroll_to_date_time_async ( CsIDateTime * what, CsMailClient * who ) ;

CsScrollResponse * scroll_to_date_time ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll to the first event matching the specified date and time within the SpectroSERVER Event Log database. If there are no matching events, the Application is positioned to the closest event. The scroll_to_date_time() method takes the window ID returned from the attach() method as one of its input parameters.

See also: The VnmParmBlock Reference section on CsIDateTime or more information on constructing a CsIDateTime object. Also, refer to the section on CsScrollResponse for more information on retrieving the events returned.



what A CsIDateTime object that includes the window ID and the date and time information for scrolling.



Table 13: CsUIEvent scroll_to_date_time_async() and scroll_to_date_time() Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. The window ID should be obtained from the original attach response, CsAttachResponse, using get_log_windowid(), after verifying that the response is valid.

CsUIEvent scrol l_to_top_async ( ) , scrol l_to_top ( )



CsTresponseid scroll_to_top_async ( CsILogWindowId * what, CsMailClient * who ) ;

CsScrollResponse * scroll_to_top ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll to the top within the SpectroSERVER Event Log database. Scrolling to the top returns the earliest events in the database to the Application. The scroll_to_top_async () method takes the window ID returned from the attach() method as one of its input parameters.

See also:

The VnmParmBlock Reference section on CsILogWindowId for more information on constructing a CsILogWindowId object, and see the section on CsScrollResponse for more information on retrieving the events returned.






Table 14: CsUIEvent scroll_to_top_async() and scroll_to_top() Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. The window ID should be obtained from the original AttachResponse, using get_log_windowid(), after verifying that the response is valid.

CsUIEvent scrol l_up_async ( ) , scrol l_up ( )


scroll_up_async ( ), scroll_up ( )

CsTresponseid scroll_up_async ( CsILogWindowId * what, CsMailClient * who ) ;

CsScrollResponse * scroll_up ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll up within the SpectroSERVER Event Log database. Scrolling up returns events that occurred earlier in time, relative to the current position. It takes the window ID returned from the attach() method as one of its input parameters.

See also:

The VnmParmBlock Reference section on CsILogWindowId for more information on constructing one. Also, see the section on CsScrollResponse for more information on retrieving the events returned.



what A CsILogWindowID object that contains the window ID.



Table 15: CsUIEvent scroll_up_async() and scroll_up() Error Codes

Error Meaning


NO_MORE_MESSAGES There are no more messages in the event log in the direction of scrolling (already at the top of the event log).

CsUIEvent unsol_scrol l ( )


unsol_scroll ( )CsScrollResponse * unsol_scroll ( CsTresponseid r_id ) ;

This method is the retriever that should be used whenever an unsolicited event comes in from SpectroSERVER. The unsol_scroll() method is inherited from CsUILogs.

A call to unsol_scroll() is used to retrieve an unsolicited event message in the following manner:

1 Message Arrives — The CsMailService receives an unsolicited message (unexpected response ID) for the subscriber from SpectroSERVER.

2 Unpack Message — The CsMailService unpacks the message, creating a CsScrollResponse object, and passes it to the CsUIEvent object.

3 Notify Subscriber — The CsMailService calls the client’s Notify() using the unexpected response ID.

4 Get Pointer — Within Notify(), the subscriber calls the unsol_scroll() retriever method, passing it the response ID it received by Notify().

5 Retrieve Information — The subscriber processes the information within the ScrollResponse, as required.

See also:

The CsMailService::UnSolRegister( ) method and the VnmParmBlock Reference sections on CsScrollResponse and CsEventList for more information on retrieving events from an EventList.



Caution:Caution:

The Notify() method of a subscriber should be defined to include the code that calls the retriever of CsUIEvent, passing it res_id as a parameter, to retrieve the unsolicited message it has received.

CsUIGlobalScapeHandle unsol_scrol l ( )


CsUIGlobalScapeHandle

Class Hierarchy

Include FileCsUIGScHndl.h

DescriptionCsUIGlobalScapeHandle contains methods that provide a global view across all landscapes known to a SpectroSERVER. It provides the client with the ability to issue requests to search multiple landscapes for the information, using a CsFindSpec object to determine the search criteria.

CsUIGlobalScapeHandle uses a CsMailClient object to perform the searches. The CsMailClient object issues the specified number of requests. When responses are received for the original requests, the CsMailClient object issues additional requests until all appropriate landscapes have been searched.

When all responses have been received, the application requesting the information is notified through its CsMailClient’s Notify() method to retrieve the response to its find request. This response contains all the responses from all landscapes matching the CsFindSpec criteria.

If the number of landscapes in the landscape map exceeds the num_landscapes_per_search parameter passed to the constructor, additional requests are issued while responses to outstanding requests are received. This process continues until the search is complete, but the number of outstanding requests never exceeds the number passed for the num_landscapes_per_search parameter. (If this parameter is left blank, the default value of 10, defined in QUE_DEPTH, is used.)

CsModelAncestor

CsUIGlobalScapeHandle



For example, if the landscape map contains 25 landscapes, and the constructor is passed a parameter to search only five at a time, five requests are sent, and additional requests are sent as the responses are received, until all 25 landscapes in the map have been queried. But no more than five requests are outstanding at a given time. When all responses have been received, the client requesting the information is notified.

The find_first_async() method, however, works differently from the find_all_async() method. It returns as soon as a successful match is found. Even if all landscapes have not yet been queried. The search is considered complete at that time and the client is notified even if there are outstanding requests and/or all landscapes have not been searched.

After instantiating an object of this class, a client needs to build a CsVnmParmblock object containing a CsFindSpec specification that describes the desired information. This CsFindSpec object is then passed to the appropriate find() method.

The following is an example of how a client application can initiate a search using CsUIGlobalScapeHandle:

Create the handle to the CsUIGlobalScapeHandle object:

CsTulong num_landscapes = 5; global_scape = new CsUIGlobalScapeHandle(num_landscapes) ;

Set up a CsFindSpec object for all model types named Pingable:

char * name = “Pingable”; CsBuffer * buff = new (name, (int) 0) CsBuffer; CsFindSpec * spec = new

CsFindSpec(CsCoreAttrIds::MTYPE_NAME, buff,CsAttrDesc::TEXT_STRING) ;

Initiate the request:

CsTresponseid resp_id = global_scape->find_first_async(spec, this) ;

See also:

CsHndlAnces.h for the current value of QUE_DEPTH.



VnmParmblock Reference for a description of CsFindSpec, CsModelDescList, CsLscpeHandleList, and CsLHErrorList.

Caution:Caution:

A CsUIGlobalScapeHandle object contains no provision for queueing requests, so it should not be reused until an initiated search has completed and the information has been retrieved. If multiple, simultaneous searches are desired, a new CsUIGlobalScapeHandle object should be created for each search. The response ID returned from initiator calls indicates if errors prevented a successful search from being initiated. A response ID of -1 may indicate that the response queue is full or that a search is already in progress. The application should carefully code the handle_vnm_error() function that client applications must provide. Since individual connection errors are trapped within the use of this handle and returned through the get_failed_landscapes() method, handle_vnm_error() should ignore any such error. If this isn’t done, the search could be interrupted.

Caution:Caution:

The model description list may also contain an error indicating that a search request was unsuccessful. The get_error() method of the returned object should be used to determine if an error has occurred. Errors for connections to individual landscapes are returned in the CsLHErrorList from the get_failed_landscapes() method.



Public Methods

Method Description

CsUIGlobalScapeHandle ( ) Class constructor.

CsUIGlobalScapeHandle ( ) Constructor accepts “landscapes to be searched” as parameter.

CsUIGlobalScapeHandle ( ) Copy constructor.

copy ( ) Creates a complete copy of the handle.

find_all_async ( ), find_all( ) These methods initiate and retrieve information about all landscapes that match the desired characteristics.

find_first_async ( ), find_first ( ) These methods initiate and retrieve information about the first landscape that matches the desired characteristics.

get_failed_landscapes ( ) Returns a list of landscapes searched unsuccessfully.

get_successful_landscapes ( ) Returns a list of landscapes searched successfully.


CsUIGlobalScapeHandle CsUIGlobalScapeHandle ( )


CsUIGlobalScapeHandle ( )CsUIGlobalScapeHandle

( CsTulong number_landscapes_per_search = MAX_REQUESTS ) ;

This is the class constructor. If no value, or 0, is passed, the method uses the default QUE_DEPTH, which is currently 10. If num_landscapes_per_search is larger than QUE_DEPTH, it also defaults to QUE_DEPTH. The number of search requests at any one time is limited to prevent placing a heavy load on the system by issuing all requests at once.


( const CsUIGlobalScapeHandle & landscape_ list, CsTulong number_landscapes_per_search

= MAX_REQUESTS ) ;

This constructor uses a list of landscapes to be searched, and the number of landscapes per search to determine the number of landscapes to search.


number_landscapes_per_search The maximum landscapes to be searched in each batch of requests.


landscape_list Landscapes to be searched.

number_landscapes_per_search The maximum landscapes to be searched in each batch of requests.

CsUIGlobalScapeHandle CsUIGlobalScapeHandle ( )



( const CsUIGlobalScapeHandle & original ) ;

This is the copy constructor.





Caution:Caution:


CsUIGlobalScapeHandle f ind_al l_async ( ) , f ind_al l ( )


find_all_async ( ), find_all( )

CsTresponseid find_all_async ( CsFindSpec * what, CsMailClient * who ) ;

CsModelDescList * find_all ( CsTresponseid resp_id ) ;

The find_all_async() method is used to initiate a search across landscapes for all matches with the specified characteristics. This method takes a pointer to CsFindSpec which describes what to find, and a pointer to the client making the request. It returns a response id to be used as input to the retriever method. As with most other CsMailService handles, the CsMailService assumes responsibility for the FindSpec it is passed and the client application should not delete it.

The find_all() method is the retriever method for find_all_async(). It takes the response id from the initiator to retrieve the information found. It returns a pointer to a CsModelDescList parmblock containing information about the matches found, which can also be used to determine on which landscape each match was found. The client application is responsible for deleting the returned list.


what A CsFindSpec describing what to search for.


resp_id The response ID identifying the returned message.

CsUIGlobalScapeHandle f ind_f i rs t_async ( ) , f ind_f i rs t ( )


find_first_async ( ), find_first ( )

CsTresponseid find_first_async ( CsFindSpec * what, CsMailClient * who ) ;

CsModelDescList * find_first ( CsTresponseid resp_id ) ;

This method is used to initiate a search for the first occurrence of a model with the specified characteristics across landscapes. This method takes a pointer to a CsFindSpec object which describes what to find, and a pointer to the client making the request. It returns a response ID to be used as input to the retriever method.

When a successful match is found before all landscapes have been queried, the search is considered completed, and the client is notified, even if there are outstanding requests and/or all landscapes have not been searched.

If the landscape contained more than one model that matched the specifications, the CsModelDescList returned from the find_first() method will contain all the matches.

The find_first ( ) method takes the response ID from the initiator to retrieve the information found. It returns a pointer to a CsModelDescList containing information about the matches found, which can also be used to determine on which landscape each match was found.


what A CsFindSpec describing what to search for.



CsUIGlobalScapeHandle get_fa i led_landscapes ( )


get_failed_landscapes ( )CsLHErrorList * get_failed_landscapes ( void ) ;

This method returns a list containing landscapes that were searched unsuccessfully in the previous search request, along with an error code indicating why the search failed.

get_successful_landscapes ( )CsLscpeHandleList * get_successful_landscapes ( void ) ;

This method returns the list of landscapes that were searched successfully in the previous search request.

operator = ( )CsUIGlobalScapeHandle & operator =

( const CsUIGlobalScapeHandle & right_hand_side ) ;

This is the class assignment operator.

Caution:Caution:

The caller is responsible for deleting memory allocated to the CsLHErrorList object returned by get_failed_landscape().

Caution:Caution:

The caller is responsible for deleting memory allocated to the CsLscpeHandleList object returned by get_successful_landscapes().



CsUILandScapeHandle operator = ( )


CsUILandScapeHandle

Class Hierarchy

Include FileCsUILscHndl.h

DescriptionThe CsUILandScapeHandle class provides the methods necessary to find or describe models, relations, and attributes in a specified landscape.

CsModelAncestor

CsUIHandleAncestor

CsUILandScapeHandle

CsUILandScapeHandle operator = ( )


Public Methods

Method Description

CsUILandScapeHandle ( ) Class constructor.

CsUILandScapeHandle ( ) Copy constructor.

attr_watch_update ( ) This method is called whenever an unsolicited attribute change is received from the VNM.

copy ( ) Creates a complete copy of this handle.

describe_async ( ), describe ( ) This pair of methods is used to get a description of different aspects of the landscape.

find_async ( ), find ( ) This pair of methods is used to find models in the landscape that have an attribute with a certain value.

model_permission_async ( ), model_permission ( )

This pair of methods filters a list of models for those accessible to a particular user.

multi_model_request_async ( ), multi_model_request ( )

This pair of methods allows a user to apply one action to multiple models.

multi_mtype_request_async ( ), multi_mtype_request ( )

These methods allow you to apply actions to multiple model types.

CsUILandScapeHandle CsUILandScapeHandle ( )


CsUILandScapeHandle ( )CsUILandScapeHandle ( CsLscpeHandle & my_landscape ) ;

This method constructs a CsUILandScapeHandle, which provides a user-level interface to services such as find and describe.

See also:

The VnmParmBlock Reference for more information on CsLscpeHandle.

CsUILandScapeHandle ( )CsUILandScapeHandle ( const CsUILandScapeHandle & original ) ;

This method constructs a UILandScapeHandle which provides a user-level interface to services such as find and describe.


my_landscape A CsLscpeHandle object that identifies a landscape in SpectroSERVER



CsUILandScapeHandle a t tr_watch_update ( )


attr_watch_update ( )CsAttrWatchRsp * attr_watch_update ( CsTresponseid resp_id ) ;

This method is called whenever an unsolicited attribute change is received from the VNM. As attribute values change, these unsolicited updates are generated. The pointer to a CsAttrWatchRsp that contains these changes is returned back. This is used when a multi-model/model type request is made to register for attribute changes.




resp_id Response ID identifying the unsolicited registration.

Caution:Caution:


CsUILandScapeHandle descr ibe_async ( ) , descr ibe ( )


describe_async ( ), describe ( )

CsTresponseid describe_async ( CsAspect * what, CsMailClient * who ) ;

CsVnmParmBlock * describe ( CsTresponseid resp_id ) ;

This pair of methods is used to get a description of different aspects of the landscape.

See also:

The VnmParmBlock Reference section on CsAspect for information on constructing a CsAspect object and on setting its aspect, sub_aspect, and detail members. Also, see the sections on CsAspectCount, CsModelDescList, CsRelDescList, and CsAttrDescList for information on retrieving the information returned, and the sections on CsModelDesc, CsRelDesc, and CsAttrDesc for information on the model descriptor, the relation descriptor, and the attribute descriptor.


what A CsAspect object that describes the information to search for. The aspect to be described is specified in the CsAspect object input to the initiator by setting CsAspect::aspect to the desired value. Currently, a description can be requested for one of five aspects of the landscape. These aspects are listed in Table 16.



Table 16: describe_async() and describe() Aspects

Aspect Purpose

CS_ASPECT_MODEL_COUNT Counts all the models in the landscape.

CS_ASPECT_MTYPES Describes all the model types in the landscape.



The subaspect filters listed in Table 17 can be applied:

Table 18 lists the filters that can be applied to each aspect:

CS_ASPECT_MODELS Describes all the models in the landscape.

CS_ASPECT_ATTRS Describes all the attributes in the landscape.

CS_ASPECT_RELS Describes all the relations in the landscape.

CS_ASPECT_ENUMS Describes all the enumerations in the landscape.

Table 17: describe_async() and describe() Subaspect Filters

Subaspect Purpose

TYPE Only models or attributes of the model type specified in CsAspect::detail are counted.

SPECIFIC Only models or attributes of the model type specified in CsAspect::detail are described.

AND_FLAGS Only attributes with specific flags are described.

OR_FLAGS Only attributes with any flags are described.

Table 18: Aspect Filters

ASPECT ALL SPECIFIC TYPEAND_

FLAGSOR_

FLAGS

CS_ASPECT_MODEL_COUNT X X

CS_ASPECT_MTYPES X

CS_ASPECT_MODELS X X X

CS_ASPECT_ATTRS X X X X X

Table 16: describe_async() and describe() Aspects (Continued)

Aspect Purpose

CS_ASPECT_MODEL_COUNT Counts all the models in the landscape.



CS_ASPECT_RELS X X X

CS_ASPECT_ENUMS X X X

Caution:Caution:

The subscriber must cast the pointer returned by the retriever to the appropriate class. Example:

CsAspectCount * port_model_count = (CsAspectCount *) landscape.describe_async (port_model_count) ;

Table 18: Aspect Filters (Continued)

ASPECT ALL SPECIFIC TYPE AND_FLAGS

OR_FLAGS

CsUILandScapeHandle f ind_async ( ) , f ind ( )


find_async ( ), find ( )

CsTresponseid find_async ( CsFindSpec * what, CsMailClient * who ) ;

CsModelDescList * find ( CsTresponseid resp_id ) ;

This pair of methods is used to find models in the landscape that have an attribute with a certain value. Both methods return a CsModelDescList, which is a list of all the CsExpModelDesc objects that were found.

This attribute is specified by its ID, value, and type in the CsFindSpec object input to the initiator. If the attribute is not a SHARED attribute, the landscape is searched for models that have an attribute that matches the ID, type and value in the CsFindSpec object. If the attribute is SHARED, however, the landscape is searched for all models that share this attribute (models of a particular model type) and that have an attribute that matches the ID, type and value in the CsFindSpec object.

See also:

The section on CsFindSpec in the VnmParmBlock Reference for information on constructing a CsFindSpec object and setting its members. See the sections on CsModelDescList and CsVnmParmBlock for information on retrieving the information returned.


what A CsFindSpec object that describes the information to search for.



CsUILandScapeHandle model_permission_async ( ) , model_permission ( )


model_permission_async ( ), model_permission ( )

CsTresponseid model_permission_async ( CsPermissionList * what, CsMailClient * who ) ;

CsPermissionList * model_permission ( CsTresponseid response_id ) ;

This pair of methods filters a list of models for those accessible to a particular user, returning a CsTresponseid that is the identifier to be used as the “claim ticket” when the response arrives.

See also:

The CsSYLandScapeHandle::model_permission_sync() method.


what The list of models, the user accessing them, and the level of access.

who Object to be notified upon completion.

response_id The response_id returned from the corresponding model_permission_async call.

Caution:Caution:

A response of “NO_PERMISSION” will be returned if the user set is not the caller and the caller is not an administrator.

CsUILandScapeHandle mul t i_model_request_async ( ) , mul t i_model_request ( )


multi_model_request_async ( ), multi_model_request ( )

CsTresponseid multi_model_request_async ( CsModelActionList * request, CsMailClient * receiver ) ;

CsModelActionList * multi_model_request ( CsTresponseid r_id ) ;

This pair of methods allows a user to apply actions to multiple models. A list of model/action combinations is used as input and a list of expanded model descriptors is returned. You can check each descriptor to see if the action was successful for that particular model. Please note that the request is now owned by the SSAPI. Do not access that pointer after this method is called.


request The list of models and actions being requested.

receiver The CsMailClient object to be notified on completion.

r_id The reponse ID identifying the returned message.

CsUILandScapeHandle mul t i_mtype_request_async ( ) , mul t i_mtype_request ( )


multi_mtype_request_async ( ), multi_mtype_request ( )

CsTresponseid multi_mtype_request_async ( CsMTypeActionList * request, CsMailClient * receiver ) ;

CsMTypeActionList * multi_mtype_request ( CsTresponseid r_id ) ;

These methods allow you to apply actions to multiple model types. The multi_mtype_request() method retrieves the response from the multi_mtype_request_async() call and returns a list of expanded model type descriptors. You can check each descriptor to see if the action was successful for that particular model type. Please note that the request is now owned by the SSAPI. Do not access that pointer after this method is called.


request The list of models and actions being requested.

receiver The CsMailClient object to be notified on completion.


CsUIModelHandle mul t i_mtype_request_async ( ) , mul t i_mtype_request ( )


CsUIModelHandle

Class Hierarchy

Include FileCsUIMdlHndl.h

DescriptionThe methods of the CsUIModelHandle class provide access to models in SpectroSERVER, using the model handle to identify the models.

CsModelAncestor

CsHandleAncestor

CsUIModelHandle

CsUIModelHandle mul t i_mtype_request_async ( ) , mul t i_mtype_request ( )


Public Methods

Method Description

CsUIModelHandle ( ) Class constructor.

CsUIModelHandle ( ) Copy constructor.

action_async ( ), action ( ) Initiates an action indicated by CsAction object passed as a parameter.

check_permission_async ( ), check_permission ( )

This pair of methods is responsible for checking a user’s permissions to a specific model.

copy ( ) Makes a complete copy of this handle.

describe_async ( ), describe ( ) This pair of methods is used to get a description of different aspects of a model.

destroy_async ( ), destroy ( ) This method pair is used to remove the model from the landscape.

find_attr_by_oid_sync ( ), find_attr_by_oid ( )

This pair of methods allow the caller to find attributes for the given object identifiers.

lock_async ( ), lock ( ) This method pair is used to lock a model.

read2_async ( ), read2 ( ) This method pair reads the attributes of a model. (new)

read_async ( ), read ( ) This pair of methods is used for reading the values of attributes of a model. (old)

read_next_async ( ), read_next ( ) This method pair is used to traverse a LIST-type attribute.

reg_attr_watch_async ( ), reg_attr_watch ( ), attr_watch_update ( )

These methods are responsible for watching for changes to attribute sets.

test_lock_async ( ), test_lock ( ) This method pair is used to check if a model is locked.

CsUIModelHandle CsUIModelHandle ( )


CsUIModelHandle ( )CsUIModelHandle ( CsModelHandle my_model ) ;

This method constructs a CsUIModelHandle that provides a user-level interface to services such as read, write, describe, and destroy.

See also:

The CsModelHandle class in the VnmParmBlock Reference for more information on model handles.

unlock_async ( ), unlock ( ) This method pair is used to remove a lock from a previously locked model.

unreg_attr_watch_async ( ), unreg_attr_watch ( )

These methods are used to unregister for watching changes to the values of a set of attributes.

write2_async ( ), write2 ( ) This pair of methods is used when attributes of a model are to be modified. (new)

write_async ( ), write ( ) This pair of methods is used when attributes of a model are to be modified. (old)


my_model A CsModelHandle that identifies a model in SpectroSERVER.

Method Description

CsUIModelHandle CsUIModelHandle ( )


CsUIModelHandle ( )CsUIModelHandle ( const CsUIModelHandle & original ) ;

The class copy constructor.

action_async ( ), action ( )

CsTresponseid action_async ( CsAction * what, CsMailClient * who ) ;

CsVnmParmBlock * action ( CsTresponseid resp_id ) ;

This method pair is used to perform a function that is different from the other methods for CsUIModelHandle. The action to be performed is specified in the CsAction object that is an input to the initiator. All actions are responded to by the inference handlers attached to the model. The action codes and the inference handlers that respond to them are defined by the developer.

These methods return a pointer to a CsVnmParmBlock object that indicates whether the action was successful or not.

See also: The section in the VnmParmBlock Reference on CsAction for more information on constructing one and setting its members.

Also, see the section on CsVnmParmBlock for information on retrieving information from a CsVnmParmBlock object. Also, refer to the section on actions in the Inference Handler API Developer’s Guide.




what A CsAction object that specifies the action to be taken.



CsUIModelHandle check_permission_async ( ) , check_permission ( )


check_permission_async ( ), check_permission ( )

CsTresponseid check_permission_async ( CsSecPerm * what, CsMailClient * who ) ;

CsSecPerm * check_permission ( CsTresponseid resp_id ) ;

This pair of methods is responsible for checking a user’s permissions to a specific model. The async method returns the response ID identifying the returned message which is then passed to the CsUIModelHandle::check_permission and is used to inquire about access privileges the requestor has with this model. The CsSecPerm object may be NULL or may specify attributes whose permissions are needed. These attributes are specified within the CsSecPerm object that is passed as the *what argument. The check_permission method takes the response ID from check_permission_async () and returns a pointer to the CsSecPerm containing the response. The requestor needs to construct a VnmParmBlock (in this case a CsSecPerm object) and pass it to check_permission_async(). The CsSecPerm object allows you to check the permissions of the model and its attributes, which is simply an indexed list of attribute IDs. The check_permission() method gets the permissions of the model and its attributes, pointed to by the CsUIModelHandle, and returns a pointer to a CsSecPerm that contains the response. CsSecPerm::get_access_response() is called to return the access permission of the model encoded as an integer. CsSecPerm defines the enum CsAllowedAction_e for READ, WRITE, and NONE to represent these cases. A value is returned for the model and one for each specified attribute. CsAllowedActions_e values are:

• WRITE = 4


what The CsSecPerm object specifies the attributes to be checked.



CsUIModelHandle copy ( )


• READ = 9• NONE = 14



Note:Note:

An error of “No Such Model” may indicate that you do not have read permission.

Caution:Caution:


CsUIModelHandle descr ibe_async ( ) , descr ibe ( )




CsRelDescList * describe ( CsTresponseid resp_id ) ;

This pair of methods is used to get a description of different aspects of a model. The aspect to be described is specified in the input to the initiator, the Aspect, by setting CsAspect::aspect to the desired value.

Currently, a description can be requested of the relations in which the model is participating, by setting the CsAspect::aspect to CsAspect::CS_ASPECT_RELS. Also, full attribute descriptions can be requested by setting the CsAspect::aspect to CsAspect::CS_ASPECT_FULL_ATTRS.

Filters can be applied for each aspect by setting CsAspect::sub_aspect to the desired value. Table 19 lists the subaspect filters that can be applied.

See also:

The VnmParmBlock Reference section on CsAspect for more information on constructing an Aspect and on setting its aspect, sub_aspect, and detail members.

Also refer to the section on CsRelDescList to see how to retrieve the information returned, and the section on CsRelDesc for information on a relation descriptor.


what A CsAspect object that describes the information to search for.



CsUIModelHandle descr ibe_async ( ) , descr ibe ( )


Table 20 lists the filters that can be applied to this aspect:

Table 19: CsAspect Subaspect Filters

Subaspect Description

ALL Does not filter on anything; no details required.

TYPE Only relations that match the types specified in CsAspect::detail are described.

SPECIFIC Only relations with relation handles that match the handles specified in CsAspect::detail are described.

Table 20: CsAspect Aspect Filters

ASPECT SPECIFIC GROUP ALL SPECIFIC TYPE

AND_FLAG

S

OR_FLAG

S


CS_ASPECT_FULL_ATTRS

X X X

CsUIModelHandle destroy_async ( ) , destroy ( )


destroy_async ( ), destroy ( )

CsTresponseid destroy_async ( CsMailClient * who ) ;

CsVnmParmBlock * destroy ( CsTresponseid resp_id ) ;

This method pair is used to remove the model from the landscape. The model is removed from all the relations that associate it to other models, and all of its memory is reclaimed. The model is removed from the database after all inference handlers using the model are finished using it. None of the statistics and events pertaining to the model are removed from the respective logs. An event (CS_EVENT_MODEL_DESTROYED) is generated, indicating the destruction of the model. The retriever method returns a pointer to a CsVnmParmBlock object that indicates whether the model was destroyed or not. An error code of CsError::SUCCESS indicates that the model was successfully destroyed.

See also:

The section in the VnmParmBlock Reference on CsVnmParmBlock for more information on retrieving information from a CsVnmParmBlock object.




CsUIModelHandle f ind_at tr_by_oid_sync ( ) , f ind_att r_by_oid ( )


find_attr_by_oid_sync ( ), find_attr_by_oid ( )

CsTresponseid find_attr_by_oid_async ( CsFindByOID * what, CsMailClient * who ) ;

CsFullAttrDescList * find_attr_by_oid ( CsTresponseid resp_id ) ;

This pair of methods allows the caller to find attributes for the given object identifiers.


what The list of OID’s to be searched for.



CsUIModelHandle lock_async ( ) , lock ( )


lock_async ( ), lock ( )

CsTresponseid lock_async ( CsMailClient * who ) ;

CsVnmParmBlock * lock ( CsTresponseid resp_id ) ;

This method pair is used to lock a model to warn others, who may be attempting to edit a model, that the model is in use. Only users can lock a model: inference handlers cannot do so. A model can have only one lock in effect at a time.

The retriever method returns a pointer to a CsVnmParmBlock object that indicates whether the lock request was successful or not.

See also:

The VnmParmBlock Reference section on CsVnmParmBlock for more information on retrieving information from a CsVnmParmBlock object and the description of CsUIModelHandle::test_lock_async(), test_lock().




Caution:Caution:

Database corruption can occur if model locking is ignored. The locking mechanism maintained by the VNM is advisory. That is, it is the application’s responsibility to test the lock for the model before editing. If the test_lock_async() fails, the model is currently under edit by another user and should not be edited.

CsUIModelHandle read2_async ( ) , read2 ( )


read2_async ( ), read2 ( )

CsTresponseid read2_async ( CsAttrReadReqList * what, CsMailClient * who ) ;

CsAttrValRspList * read2 ( CsTresponseid resp_id ) ;

This pair of methods reads the attributes of a model, and may be used to ready any type of attribute including internal list attributes. The user must construct a CsAttrReadReqList which will contain the id’s of the attributes to be read.

See also: The VnmParmBlock Reference for more information on constructing, setting and retrieving information for CsAttrReadReqList and CsAttrValRspList objects.


what A CsAttrReadReqList object specifying the attributes to be read.



Note:Note:

These methods replace the read_async() and read_next_async() methods.

CsUIModelHandle read_async ( ) , read ( )


read_async ( ),read ( )

CsTresponseid read_async ( CsAttrValList * what, CsMailClient * who ) ;

CsAttrValList * read ( CsTresponseid resp_id ) ;

This pair of methods is used for reading the values of attributes of a model. The attributes that are to be read are listed only by their IDs in the CsAttrValList object, which is an input to the initiator. The read_async() method returns a pointer to a CsAttrValList object containing the appropriate values or error codes. If an OID suffix is supplied with the request, the OID suffix is returned with the value. These methods cannot be used for non-external list attributes.

See also: The VnmParmBlock Reference for more information on constructing, setting, and retrieving information from CsAttrValList. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.


what A CsAttrValList object specifying the attributes to be read.



Note:Note:

An overall error code is set in the CsVnmParmBlock object received from SpectroSERVER. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it could indicate a difficulty reading some of the attributes, and each error code must be examined on an individual basis.Error codes for individual attributes are significant only to that attribute. If a particular attribute value was not READABLE for some reason, an error code is set for that attribute, specifying the error, and the value for that attribute is set to NULL.An attribute value is valid only when the error code for that attribute is CsError::SUCCESS. Any other error code indicates an error while reading the associated attribute.

CsUIModelHandle read_next_async ( ) , read_next ( )


read_next_async ( ),read_next ( )

CsTresponseid read_next_async ( CsAttrValList * what, CsMailClient * who ) ;

CsAttrValList * read_next ( CsTresponseid resp_id ) ;

This method pair is applicable only to attributes that are both EXTERNAL and LIST. It is used to traverse a LIST-type attribute. The particular attribute that is read by this method is determined by an OID suffix (instance ID) specified in the input to the initiator. The read_next_async() operation is similar to the ”get_next” primitive of the SNMP protocol, but will not cross attribute boundaries.

The read_next_async() method returns a pointer to a CsAttrValList object containing the appropriate values and OID suffixes or error codes.

If no OID suffix was supplied with a request, the attribute value of the first entry for that OID is returned, along with its OID suffix. If a partial OID suffix was supplied with a request, the remainder of the OID suffix is treated as NULL and the attribute value for the next entry for that OID is returned, along with its OID suffix. If a complete OID suffix is supplied with a request, the attribute value for the next entry for that OID is returned, along with its OID suffix.





CsUIModelHandle read_next_async ( ) , read_next ( )


See also:

The section in the VnmParmBlock Reference on CsAttrValList for more information on constructing setting, and retrieving information. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.

Note:Note:

An overall error code is set in the VnmParmBlock received from SpectroSERVER. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it could indicate a difficulty reading some attributes, and each error code must be examined individually. Error codes for individual attributes are significant only for that attribute. If a particular attribute value was not READABLE for some reason, an error code is set for that attribute, specifying the error, and the value for that attribute is set to NULL.An attribute value is valid only when the error code for that attribute is CsError::SUCCESS. Any other error code indicates an error while reading the associated attribute.

CsUIModelHandle reg_at tr_watch_async ( ) , reg_att r_watch ( ) , a t tr_watch_update ( )



CsTresponseid reg_attr_watch_async ( CsAttrWatchReq * what, CsMailClient * who ) ;

CsAttrWatchRsp * reg_attr_watch ( CsTresponseid resp_id ) ;

CsAttrWatchRsp * attr_watch_update ( CsTresponseid resp_id ) ;

These methods are responsible for watching for changes to attribute sets for a specific model. The async method is used by the client to register for watching changes in the values of a set of attributes of a specific model. The client specifies the request using a CsAttrWatchReq object. The reg_attr_watch() method uses the response ID returned by reg_attr_watch_async() to obtain the response or a notification from the SpectroSERVER to a previous attribute watch registration request. The response or notification is returned as a CsAttrWatchRsp object.

The reg_attr_watch_async() method returns a CsTresponseid that is the identifier to be used as the “claim ticket” when the response arrives.

The attr_watch_update() method is called whenever an unsolicited attribute change is received from the VNM. As attribute values change, these unsolicited updates are generated. The pointer to a CsAttrWatchRsp that contains these changes is returned back.


what A CsAttrWatchReq object specifying the attributes to be watched.



CsUIModelHandle test_ lock_async ( ) , test_lock ( )


test_lock_async ( ), test_lock ( )

CsTresponseid test_lock_async ( CsMailClient * who ) ;

CsVnmParmBlock * test_lock ( CsTresponseid resp_id ) ;

This method pair is used to check if a model is locked. The retriever method returns a pointer to a CsVnmParmBlock that indicates whether the model is locked or not.

See also:

The VnmParmBlock Reference section on CsVnmParmBlock for more information on retrieving information from one.




Caution:Caution:

Database corruption can occur if model locking is ignored. The locking mechanism maintained by the VNM is advisory. That is, it is the application’s responsibility to test the lock for the model before editing. If the test_ lock_async() fails, the model is currently under edit by another user and should not be edited.

CsUIModelHandle unlock_async ( ) , unlock ( )


unlock_async ( ), unlock ( )

CsTresponseid unlock_async ( CsMailClient * who ) ;

CsVnmParmBlock * unlock ( CsTresponseid resp_id ) ;

This method pair is used to remove a lock from a previously locked model. A model’s lock can be removed only by the user that locked it. Attempting to unlock a model that was not previously locked returns an error. The retriever method returns a pointer to a CsVnmParmBlock object that indicates whether the model was successfully unlocked or not.

See also:

The VnmParmBlock Reference section on CsVnmParmBlock for more information on retrieving information from one.



resp_id The response ID identifying the returned message

CsUIModelHandle unreg_at tr_watch_async ( ) , unreg_att r_watch ( )


unreg_attr_watch_async ( ), unreg_attr_watch ( )

CsTresponseid unreg_attr_watch_async ( CsAttrWatchReq * what, CsMailClient * who ) ;

CsAttrWatchRsp * unreg_attr_watch ( CsTresponseid resp_id ) ;

These methods are used by the client to unregister for watching changes to the values of a set of attributes. The client specifies the unregistration request using a CsAttrWatchReq object. The client may unregister for a subset of attributes for which it previously registered. The unreg_attr_watch() method uses the response ID returned by the above method to obtain the response from the SpectroSERVER to a previous attribute watch unregistration request. The response is returned as a CsAttrWatchRsp object.

The async method returns the response ID identifying the returned message.


what The CsAtrrWatchReq specifying the watch to unregister.



CsUIModelHandle wr i te2_async ( ) , wr i te2 ( )


write2_async ( ), write2 ( )

CsTresponseid write2_async ( CsAttrWriteReqList * what, CsMailClient * who ) ;

CsAttrValRspList write2 ( CsTresponseid resp_id ) ;

This pair of methods is used when attributes of a model are to be modified and may be used to modify all types of attributes including internal list attributes. The attributes of the model that are to be modified are specified in the input to the initiator, the CsAttrWriteReqList object. The attributes are specified by their IDs, types, and values.

See also: The VnmParmBlock Reference for more information on constructing, setting, and retrieving information from CsAttrWriteReqList and CsAttrValRspList objects.


what A CsAttrWriteReqList object containing the information to write.



Note:Note:

This method pair replaces the method pair write_async ( ), write ( ).

CsUIModelHandle wr i te_async ( ) , wr i te ( )


write_async ( ), write ( )

CsTresponseid write_async ( CsAttrValList * what, CsMailClient * who ) ;

CsAttrValList * write ( CsTresponseid resp_id ) ;

This pair of methods is used when attributes of a model are to be modified. The attributes of the model that are to be modified are specified in the input to the initiator, the CsAttrValList object. The attributes are specified by their IDs, types, and values. These methods cannot be used for non-external list attributes.

See also:

The section in the VnmParmBlock Reference on CsAttrValList for more information on constructing an CsAttrValList, and on setting and retrieving information from one.


what A CsAttrValList object that describes the information to search for.



Note:Note:

An overall error code is set in the CsVnmParmBlock object received from SpectroSERVER. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it could indicate difficulty writing a particular item. In that case, each error code must be examined individually. An error code of CsError::SUCCESS indicates the attribute was successfully modified. If an attribute could not be modified for some reason (for example, it was not WRITABLE), the error code for that particular attribute specifies the reason for the error.

CsUIModelTypeHandle wr i te_async ( ) , wr i te ( )


CsUIModelTypeHandle

Class Hierarchy

Include FileCsUIMTHndl.h

DescriptionThe CsUIModelTypeHandle class provides access to model types in the SPECTRUM knowledge base by means of the model type handle.

CsModelAncestor

CsHandleAncestor

CsUIModelTypeHandle

Note:Note:

When you call more than one type of registration method (i.e., reg_attr_watch(), reg_destroy_watch(), reg_activate_watch()) it is necessary to do a CsMailService::UnSolRegister ( ) for each registration method called. This is done to ensure that the proper Notify method will be called with a different response ID for each type of unsolicited registration, thus allowing your code to determine which update method will be called (i.e., activate_watch_update(), destroy_watch_update(), attr_watch_update()).



Public Methods

Method Description

CsUIModelTypeHandle ( ) Class constructor.

CsUIModelTypeHandle ( ) Copy constructor.


create_async ( ), create ( ) This pair of methods is used when a new model is to be created.

describe_async ( ), describe ( ) This pair of methods is used to get a description of different aspects of a model type.

find_attr_by_oid_async ( ), find_attr_by_oid ( )

This pair of methods allows the caller to find attributes for the given object identifiers.

is_derived_from_async ( ), is_derived_from ( )

Checks to see if this model type is derived from the model type given in the parm block.

read_async ( ), read ( ) This pair of methods is used to read the values of attributes of a model type.

reg_activate_watch_async ( ), reg_activate_watch ( ), activate_watch_update ( )

These methods are used to register for the activation of models of this type.


These methods register for watching changes in the values of a set of attributes of a specific model type.

reg_destroy_watch_async ( ), reg_destroy_watch, destroy_watch_update ( )

These methods are used to register for the destruction of models of this type.

unreg_activate_watch_async ( ), unreg_activate_watch ( )

Allows you to unregister from callbacks caused by a previous call to reg_activate_watch_async().

unreg_attr_watch_async ( ), unreg_attr_watch ( ),

Allows you to unregister from watching changes.

unreg_destroy_watch_async ( ), unreg_destroy_watch

Allows you to unregister from callbacks caused by a previous call to reg_destroy_watch_async().

CsUIModelTypeHandle CsUIModelTypeHandle ( )


CsUIModelTypeHandle ( )CsUIModelTypeHandle ( CsMTypeHandle & my_type,

CsLscpeHandle & my_landscape ) ;

This method constructs a CsUIModelTypeHandle object that provides a user-level interface to model types. This access allows creating models of a model type, modifying attributes of a model type, and describing model types.

See also:

VnmParmBlock Reference for more information on CsMTypeHandle.

write_async ( ), write ( ) This pair of methods is used when attributes of a model type are to be modified.


my_type A CsMTypeHandle object that identifies a model type in SpectroSERVER.

my_landscape A CsLscpeHandle object that identifies a landscape in SpectroSERVER. Because multiple landscapes can be accessed from a single application, it is important to specify a Landscape when using this constructor.

Method Description

CsUIModelTypeHandle CsUIModelTypeHandle ( )


CsUIModelTypeHandle ( )CsUIModelTypeHandle ( const CsUIModelTypeHandle & original ) ;

This method is the copy constructor for a CsUIModelTypeHandle.





Caution:Caution:


CsUIModelTypeHandle create_async ( ) , create ( )


create_async ( ), create ( )

CsTresponseid create_async ( CsAttrValList * what, CsMailClient * who ) ;

CsAttrValList * create ( CsTresponseid resp_id ) ;

This pair of methods is used when a new model of this model type is to be created. The attributes of the model that are to be initialized are specified in the CsAttrValList object that is input to the initiator. The attributes are specified by their IDs, types, and values.

These methods return a pointer to a CsAttrValList object, containing the handle of the newly created model.

See also: The section on CsAttrValList in the VnmParmBlock Reference for more information on constructing a CsAttrValList, and on setting and retrieving information from one.


what A CsAttrValList specifying the attribute to be updated on model creation.



Note:Note:

An overall error code is set in the CsVnmParmBlock received from SpectroSERVER. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it could indicate a difficulty writing a particular item. In that case, each error code must be examined individually.

For each attribute that was to be initialized, an error code indicates the result of the initialization. An error code of CsError::SUCCESS indicates that the attribute was successfully initialized. If an attribute could not be initialized for some reason (for example, it was not WRITABLE), the error code for that attribute specifies the reason for the error.

CsUIModelTypeHandle descr ibe_async ( ) , descr ibe ( )




CsAspectCount * describe ( CsTresponseid resp_id ) ;

This pair of methods is used to get a description of different aspects of a model type.


what A CsAspect object that describes the information to search for. The aspect to be described is specified in the input to the initiator, the Aspect, by setting CsAspect::aspect to the desired value. A description can be requested of one of the seven aspects of a model type listed in Table 21.



Table 21: Model Type Aspects

Aspect Purpose

CS_ASPECT_ATTRS Describes all the attributes of the model type.

CS_ASPECT_ATTR_COUNT Counts all the attributes of the model type.

CS_ASPECT_FULL_ATTRS Describes all the attributes of the model type fully — including the extensions of the descriptors.

CS_ASPECT_SELF Describes the model type itself.

CS_ASPECT_BASE_MTYPES Describes the model types from which this model type is derived.



Filters can be applied for some aspects by setting CsAspect::sub_aspect to the desired value. Currently, subaspect filtering can be applied to three aspects: CsAspect::CS_ASPECT_ATTRS, CsAspect::CS_ASPECT_FULL_ATTRS, and CsAspect::CS_ASPECT_GROUPS.

Table 22 lists the supported filters:


CS_ASPECT_DERIVED_MTYPES Describes the model types that have been derived from this model type.

CS_ASPECT_GROUPS Describes the attributes of a specific group of model types.

CS_ASPECT_ENUMS Describes the enumerations of a model type.

Table 22: Subaspect Filters

Subaspect Purpose

ALL Does not filter on anything; no details required.

SPECIFIC Only attributes with attribute IDs that match the attribute IDs specified in CsAspect::detail are described.

SPECIFIC_GROUP Describes specific attributes by group.

TYPE Only attributes of the type that match the types specified in CsAspect::detail are described.


OR_FLAGS Only attributes with any flags are described.

Table 21: Model Type Aspects (Continued)



Table 23: Aspect Filters

ASPECT ALL SPECIFIC SPECIFICGROUP TYPE

AND_FLAGS

OR_FLAGS


CS_ASPECT_COUNT X

CS_ASPECT_FULL_ATTRS

X X X X X X

CS_ASPECT_SELF X

CS_ASPECT_BASE_MTYPES

X

CS_ASPECT_DERIVED_MTYPES

X

CS_ASPECT_GROUPS X X X X X

CS_ASPECT_ENUMS X X X

Note:Note:

The describe method returns a pointer to a CsAspectCount. Depending on the aspect being described, this AspectCount contains a list of descriptors of various things, such as attributes, model types, etc. Type casting to the appropriate list type is mandatory. Table 24 lists the descriptors returned for the different aspects.

Table 24: Aspect Descriptors

Aspect List Type

CS_ASPECT_ATTR_COUNT: CsAspectCount

CS_ASPECT_SELF: CsMTypeDescList

CS_ASPECT_BASE_MTYPES: CsMTypeDescList

CS_ASPECT_DERIVED_MTYPES: CsMTypeDescList



See also:

The section on CsAspect in the VnmParmBlock Reference for constructing an Aspect and on setting its aspect, sub_aspect, and detail members.

Also, see the sections on CsAspectCount, CsFullAttrDescList, CsAttrDescList, and CsMTypeDescList for retrieving the information returned, and the sections on CsAttrDesc, CsFullAttrDesc, and CsMTypeDesc for information on the attribute descriptor, the full attribute descriptor, and the model type descriptor.

CS_ASPECT_ATTRS: CsAttrDescList

CS_ASPECT_FULL_ATTRS: CsFullAttrDescList

CS_ASPECT_GROUPS: CsAttrGroupList

CS_ASPECT_ENUMS CsEnumBlkList

Table 24: Aspect Descriptors (Continued)

Aspect List Type


CsUIModelTypeHandle f ind_att r_by_oid_async ( ) , f ind_att r_by_oid ( )


find_attr_by_oid_async ( ), find_attr_by_oid ( )

CsTresponseid find_attr_by_oid_async ( CsFindByOID * what, CsMailClient * who ) ;

CsFullAttrDescList * find_attr_by_oid ( CsTresponseid resp_id ) ;

This method pair allows the caller to find attributes for the given object identifiers.

is_derived_from_async ( ), is_derived_from ( )

CsTresponseid is_derived_from_async ( CsMTypeHandlePB * what, CsMailClient * who ) ;

CsVnmParmBlock * is_derived_from ( CsTresponseid resp_id ) ;

This pair of methods checks if this model type is derived from the model type given in the parm block.






what The model type to be compared against.



CsUIModelTypeHandle read_async ( ) , read ( )


read_async ( ), read ( )

CsTresponseid read_async ( CsAttrValList * what, CsMailClient * who ) ;

CsAttrValList * read ( CsTresponseid resp_id ) ;

This pair of methods is used to read the values of attributes of a model type. The attributes to be read are specified only by their IDs in the CsAttrValList object input to the initiator. Attribute type and value, if provided as input, are ignored. Do not use these methods for non external list attributes.

These methods return a pointer to a CsAttrValList containing the appropriate values or error codes.

See also: The section on CsAttrValList in the VnmParmBlock Reference for more information on constructing an CsAttrValList, and also on setting and retrieving information from one. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.





Note:Note:

An overall error code is set in the VnmParmBlock received from SpectroSERVER. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it could indicate a difficulty reading a particular item. In that case, each error code must be examined individually.If an individual attribute could not be read for some reason (for example, it was not READABLE), an error code is set for that attribute, specifying the reason for the error, and the value for that attribute is set to NULL. The value of an attribute is meaningful only if the error code for that attribute is CsError::SUCCESS.

CsUIModelTypeHandle reg_act ivate_watch_async ( ) , reg_act ivate_watch ( ) , act ivate_watch_update ( )


reg_activate_watch_async ( ), reg_activate_watch ( ), activate_watch_update ( )

CsTresponseid reg_activate_watch_async ( CsActivateWatchReq * what, CsMailClient * who ) ;

CsModelDescList * reg_activate_watch ( CsTresponseid resp_id ) ;

CsModelDescList * activate_watch_update ( CsTresponseid resp_id ) ;

The first two methods are used to register for the activation of models of this type. The CsActivateWatchReq object serves two purposes. First, if the CsActivateWatchReq::do_initial_describe is set to TRUE, the CsModelDescList return will contain the list of models of this type already activated. Second, the CsActivateWatchReq::mailbox_id should contain the return of a call to CsMailService::UnsolRegister. The Notify of the registered CsMailClient is called with the given mailbox_id as the CsTresponseid parameter when the SpectroSERVER calls back with a model activation notification. A CsMailClient object which uses this registration method would call reg_activate_watch() in their Notify method when the CsTresponseid passed in is equal to the CsTresponseid returned from reg_activate_watch_async().

The activate_watch_update () method is called whenever an unsolicited activation is received from the VNM. As models are activated, these unsolicited updates are generated. The pointer to a CsModelDescList that contains the activated models is returned back.


what A CsActivateWatchReq object with the initial set up for the watch.



CsUIModelTypeHandle reg_at tr_watch_async ( ) , reg_att r_watch ( ) , a t tr_watch_update ( )


reg_attr_watch_async ( ),reg_attr_watch ( ), attr_watch_update ( )

CsTresponseid reg_attr_watch_async ( CsAttrWatchReq * what, CsMailClient * who ) ;

CsAttrWatchRsp * reg_attr_watch ( CsTresponseid resp_id ) ;

CsAttrWatchRsp * attr_watch_update ( CsTresponseid resp_id ) ;

These methods allow the caller to register for watching changes in the values of a set of attributes of a specific model type. The client specifies the request by using reg_attr_watch_async() and passing a pointer to a CsAttrWatchReq object. The response ID returned is used to obtain the response or a notification from the SpectroSERVER to a previous attribute watch registration request via the reg_attr_watch() method. The response or notification is returned as a CsAttrWatchRsp object.

The attr_watch_update() method is called whenever an unsolicited attribute change is received from the VNM. As attribute values change, these unsolicited updates are generated. The pointer to a CsAttrWatchRsp that contains these changes is returned.


what A CsAttrWatchReq specifying the attributes to be watched..


resp_id The CsTresponseid object identifying the returned message.

CsUIModelTypeHandle reg_destroy_watch_async ( ) , reg_destroy_watch, destroy_watch_update ( )


reg_destroy_watch_async ( ), reg_destroy_watch, destroy_watch_update ( )

CsTresponseid reg_destroy_watch_async ( CsRegisterBase * what, CsMailClient * who ) ;

CsModelDescList * reg_destroy_watch ( CsTresponseid resp_id ) ;

CsModelDescList * destroy_watch_update ( CsTresponseid resp_id ) ;

The first two methods are used to register for the destruction of models of this type. The CsRegisterBase object has a notif_id member which should contain the return of a call to CsMailService::UnsolRegister. The Notify() method of the registered CsMailClient is called with the given notif_id when the SpectroSERVER calls back with a model destruction notification. A CsMailClient object which uses this registration method would call reg_destroy_watch() in their Notify() method when the CsTresponseid passed in is equal to the CsTresponseid returned from reg_destroy_watch_async(). This will return an empty CsModelDescList only indicating the success of the registration.

The destroy_watch_update() method is called whenever an unsolicited destroyed models is received from the VNM. As models are destroyed, these unsolicited updates are generated. The pointer to a CsModelDescList that contains the destroyed models is returned back.


what A CsRegisterbase containing the unsolicited registration id.



CsUIModelTypeHandle unreg_act ivate_watch_async ( ) , unreg_act ivate_watch ( )


unreg_activate_watch_async ( ), unreg_activate_watch ( )

CsTresponseid unreg_activate_watch_async ( CsMailClient * who ) ;

CsVnmParmBlock * unreg_activate_watch ( CsTresponseid resp_id ) ;

This pair of methods allow the caller to unregister from callbacks caused by a previous call to reg_activate_watch_async().




CsUIModelTypeHandle unreg_att r_watch_async ( ) , unreg_at tr_watch ( ) ,


unreg_attr_watch_async ( ), unreg_attr_watch ( ),

CsTresponseid unreg_attr_watch_async ( CsAttrWatchReq * what, CsMailClient * who ) ;

CsAttrWatchRsp * unreg_attr_watch ( CsTresponseid resp_id ) ;

This method pair is used to unregister for watching changes in the values of a set of attributes of a specific model type. The client specifies the request by using unreg_attr_watch_async() and passing a pointer to a CsAttrWatchReq object. The response ID returned is used to obtain the response or a notification from the SpectroSERVER to a previous attribute watch unregistration request by the unreg_attr_watch() method. The response or notification is returned as a CsAttrWatchRsp object.

unreg_destroy_watch_async ( ), unreg_destroy_watch

CsTresponseid unreg_destroy_watch_async ( CsMailClient * who ) ;

CsVnmParmBlock * unreg_destroy_watch ( CsTresponseid resp_id ) ;

This pair of methods allow the caller to unregister from callbacks caused by a previous call to reg_destroy_watch_async().


what A CsAttrWatchReq specifying the attributes to be no longer watched.


resp_id The CsTresponseid object identifying the returned message.






write_async ( ),write ( )

CsTresponseid write_async ( CsAttrValList * what, CsMailClient * who ) ;

CsAttrValList * write ( CsTresponseid resp_id ) ;

This pair of methods is used when attributes of a model type are to be modified. The attributes of the model type that are to be modified are specified in the CsAttrValList object input to the initiator. The attributes are specified by their IDs, types, and values. Do not use these methods for non-external list attributes.

These methods return a pointer to a CsAttrValList object containing the appropriate error codes.

See also:

CsAttrValList in the VnmParmBlock Reference for more information on constructing a CsAttrValList, and on setting and retrieving information from one. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.


what A CsAttrValList object containing the information to write.



Note:Note:

An overall error code is set in the VnmParmBlock received from SpectroSERVER. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it could indicate difficulty writing a particular item. In that case, each error code must be examined individually.An error code of CsError::SUCCESS indicates the attribute was successfully modified. If an attribute could not be modified for some reason (for example, it was not WRITABLE), the error code for that attribute specifies the reason for the error

CsUIRelationHandle wr i te_async ( ) , wr i te ( )


CsUIRelationHandle

Class Hierarchy

Include FileCsUIRelHndl.h

DescriptionThe CsUIRelationHandle class provides an interface that can be used to add associations, read associations, remove associations, describe associations, add rules, and read rules.

CsModelAncestor

CsUIHanedleAncestor

CsUIRelationHandle

Note:Note:

Each initiator method has at least two versions. One that requires memory to be allocated and a pointer to be passed, and another that allocates its own memory and passes a parmblock by reference.



Public Methods

Method‘ Description

CsUIRelationHandle ( ) Class constructor.

CsUIRelationHandle ( ) Copy constructor.

add_async ( ), add_async ( ), add ( )

These methods are used to add associations to a relation


count_async ( ), count_async ( ), count ( )

These methods are used to count the associations that match a certain pattern in a relation.

describe_async ( ), describe_async ( ), describe ( )

These methods are used to get a description of different aspects of a relation.

dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel ( ),

These methods perform functions on multiple models.

read_async ( ), read_async ( ), read ( )

These methods are used to read the associations that match a certain pattern in a relation.

read_exp_async ( ), read_exp_async ( ), read_exp ( )

These methods are used to read the expanded versions of the associations that match a certain pattern in a relation.

read_exprule_async ( ), read_exprule_async ( ), read_exprule ( )

These methods are used to read the expanded version of a rule that matches a certain pattern in a relation.

read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq ( )

These methods allow you to perform functions on multiple attributes of multiple models.



read_rule_async ( ), read_rule_async ( ), read_rule ( )

These methods are used to read a rule that matches a certain pattern in a relation.

reg_rel_watch_async ( ), reg_rel_watch ( ), rel_watch_update

These methods process registration for watching relation changes of a specific model.

remove_async ( ), remove_async ( ), remove ( )

These methods are used to remove associations from a relation.

unreg_rel_watch_async ( ), unreg_rel_watch ( )

These methods process unregistering for watching relation changes of a specific model.

Method‘ Description

CsUIRelationHandle CsUIRelat ionHandle ( )


CsUIRelationHandle ( )CsUIRelationHandle ( unsigned long relation,

const CsLscpeHandle my_landscape ) ;

This method constructs a CsUIRelationHandle that provides a user-level interface to services such as adding associations, reading associations, and reading rules.

CsUIRelationHandle ( )CsUIRelationHandle ( const CsUIRelationHandle & original ) ;

The copy constructor for the class.


relation An unsigned long identifying the relation in the SpectroSERVER.

my_landscape A CsLscpeHandle object that identifies a specific landscape in SpectroSERVER. Because multiple landscapes can be accessed from a single application, it is important to specify a Landscape when using this constructor.



CsUIRelationHandle add_async ( ) , add_async ( ) , add ( )


add_async ( ), add_async ( ), add ( )

CsTresponseid add_async ( CsAssocList * what, CsMailClient * who ) ;

CsTresponseid add_async ( CsAssocList & what, CsMailClient * who ) ;

CsAssocCount * add ( CsTresponseid resp_id ) ;

This method pair is used to add associations to a relation (i.e., when two models need to be related to each other). The models to be related form an association. Many associations can be added to a relation in a single request. A list of such associations (a CsAssocList) is the input to the initiator. The associations in the list are added to the relation, thereby relating the two models in each association. The add method returns a pointer to an AssocCount received from SpectroSERVER that indicates whether the associations were successfully added to the relation or not.

The add_async() method takes either a reference or a pointer to a CsAssocList depending upon which version is called. Either method returns a CsTresponseid which contains the number of items matched.

See also:

The VnmParmBlock Reference sections on CsAssociation and CsAssocList for information on constructing an Association and putting together a list of Associations in a CsAssocList object. Also, see the section on CsVnmParmBlock for information on retrieving information from one.


what A CsAssocList object that describes the information to search for.



CsUIRelationHandle copy ( )




Caution:Caution:

The caller is responsible for deleting the memory allocated to the CsModelAncestor object returned by copy().

CsUIRelationHandle count_async ( ) , count_async ( ) , count ( )


count_async ( ), count_async ( ), count ( )

CsTresponseid count_async ( CsAssocList * what, CsMailClient * who ) ;

CsTresponseid count_async ( CsAssocList & what, CsMailClient * who ) ;

CsAssocCount * count ( CsTresponseid resp_id ) ;

This method pair is used to count the associations that match a certain pattern in a relation. The association patterns to be matched are specified in the CsAssocList input to the initiator. Either the left or right or both models in an association pattern can be specified as a wildcard (CS_WILD_MODEL_HANDLE). The associations in the relation that match all the patterns in the CsAssocList are added up.

The count_async() method takes either a pointer or a reference to a CsAssocCount, depending upon which count_async() method is called. The returned CsTresponseid contains a count of the number of associations that matched all the patterns in the input list,

See also:

The VnmParmBlock Reference sections on CsAssociation and CsAssocList for more information on constructing an Association and building a list of Associations in a CsAssocList object, and also for more information on wildcards. Also, see the section on CsAssocCount for more information on retrieving the returned information.





CsUIRelationHandle descr ibe_async ( ) , descr ibe_async ( ) , descr ibe ( )


describe_async ( ), describe_async ( ), describe ( )


CsTresponseid describe_async ( CsAspect & what, CsMailClient * who ) ;

CsVnmParmBlock * describe ( CsTresponseid resp_id ) ;

These methods are used to get a description of different aspects of a relation. The aspect to be described is specified in the CsAspect object input to the initiator by setting CsAspect::aspect to the desired value. A description can be requested of the relation itself, by setting the CsAspect::aspect to CsAspect::CS_ASPECT_SELF.

The describe() method returns a pointer to a CsVnmParmBlock object that contains a descriptor of the relation that must be typecast to a CsRelDescList.

The describe_async() methods return either a pointer or a reference to a CsTresponseid, depending on which variety of the method is called.

See also: The VnmParmBlock Reference section on CsAspect for more information on constructing an Aspect and on setting its members. Also see the section on CsRelDescList for information on retrieving the


what A CsAspect object that describes the information to search for.



Caution:Caution:

A subaspect cannot be specified for CS_ASPECT_SELF to filter aspect descriptions; the subaspect default is ALL.

CsUIRelationHandle descr ibe_async ( ) , descr ibe_async ( ) , descr ibe ( )


information returned, and the section on CsRelDesc for information on a relation descriptor.

CsUIRelationHandle dofunc_mrel_async ( ) , dofunc_mrel_async ( ) , dofunc_mrel_async ( ) ,


dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel_async ( ), dofunc_mrel ( ),

CsTresponseid dofunc_mrel_async ( CsAssocList * relation, CsVnmMsg::CsVnmFunction_e function, CsFindSpec * filter, CsMailClient * who ) ;

CsTresponseid dofunc_mrel_async ( CsAssocList * relation,CsVnmMsg::CsVnmFunction_e function, CsMailClient * who ) ;

CsTresponseid dofunc_mrel_async ( CsAssocList & relation, CsVnmMsg::CsVnmFunction_e function, CsFindSpec & filter, CsMailClient * who ) ;

CsTresponseid dofunc_mrel_async ( CsAssocList & relation, CsVnmMsg::CsVnmFunction_e function, CsMailClient * who ) ;

CsModelDescList * dofunc_mrel ( CsTresponseid resp_id ) ;


relation A CsAssocList identifying the models to query. Each association should have either the left or right side as a wildcard representing the models to query.

function Which of the following CsUIModelHandle functions to invoke in SpectroSERVER: destroy(), lock(), unlock(), test_lock().


filter A CsFindSpec object to be used as a filter after the associations have been expanded.


CsUIRelationHandle dofunc_mrel_async ( ) , dofunc_mrel_async ( ) , dofunc_mrel_async ( ) ,


The dofunc_mrel_async() and dofunc_mrel() pair of methods perform functions on multiple models. They are similar to read_mrelq_async() and read_mrelq ( ) except that these methods can only perform model functions that do not need parameters.

Each dofunc_mrel_async ( ) method returns a CsTresponseid that is input to dofunc_mrel ( ) which returns a CsModelRsp object. Each CsModelRsp contains the response for a particular model.

See also:

The VnmParmBlock Reference sections on CsAssocList, CsModelRspLst, and CsVnmMsg.

Note:Note:

To invoke a model function that takes parameters, use read_mrelq().

CsUIRelationHandle read_async ( ) , read_async ( ) , read ( )


read_async ( ), read_async ( ), read ( )

CsTresponseid read_async ( CsAssocList * what, CsMailClient * who ) ;

CsTresponseid read_async ( CsAssocList & what, CsMailClient * who ) ;

CsAssocList * read ( CsTresponseid resp_id ) ;

This method pair is used to read the associations that match a certain pattern in a relation. The association patterns to be matched are specified in the CsAssocList object input to the initiator. Either the left or right or both models in an association pattern can be specified as a wildcard (CS_WILD_MODEL_HANDLE).

The read method returns a pointer to a CsAssocList object that contains all the associations matching all the patterns in the input list.

The read_async methods take either a pointer or a reference to a CsAssocList, depending on which variety of the method is called.

See also:

See the VnmParmBlock Reference sections on CsAssociation and CsAssocList for more information on constructing Associations and retrieving information from a CsAssocList object. Also, refer to the section on CsAssocCount for more information on retrieving the returned information.





CsUIRelationHandle read_exp_async ( ) , read_exp_async ( ) , read_exp ( )


read_exp_async ( ), read_exp_async ( ), read_exp ( )

CsTresponseid read_exp_async ( CsAssocList * what, CsMailClient * who ) ;

CsTresponseid read_exp_async ( CsAssocList & what, CsMailClient * who ) ;

CsExpAssocList * read_exp ( CsTresponseid resp_id ) ;

This method pair is used to read the expanded versions of the associations that match a certain pattern in a relation. The association patterns to be matched are specified in the CsAssocList object input to the initiator. The expanded portion is not used for matching. Either the left or right or both models in an association pattern can be specified as a wildcard (CS_WILD_MODEL_HANDLE). An association only returns the model and model type handles. An expanded association includes the names of the models and model types.

The read_exp method returns a pointer to a CsExpAssocList that contains the expanded versions of all the associations that matched all the patterns in the input list.

The read_exp_async methods take either a pointer or a reference to a CsAssocList, depending on the signature of the method called.

See also: The VnmParmBlock Reference sections on CsAssociation and CsAssocList for information on constructing an Association and a CsAssocList and for information on wildcards. Also see the section on CsExpAssocList for information on retrieving the returned information, and the section on CsExpAssociation for information on the expanded version of an Association.





CsUIRelationHandle read_exprule_async ( ) , read_exprule_async ( ) , read_exprule ( )


read_exprule_async ( ), read_exprule_async ( ),read_exprule ( )

CsTresponseid read_exprule_async ( CsRule * rule_pattern, CsMailClient * who ) ;

CsTresponseid read_exprule_async ( CsRule & rule_pattern, CsMailClient * who ) ;

CsExpRuleList * read_exprule ( CsTresponseid resp_id ) ;

This method pair is used to read the expanded version of a rule that matches a certain pattern in a relation. The rule pattern to be matched is specified in the CsRule object input to the initiator. Either the left or right or both model types in a rule pattern may be specified as a wildcard (CS_WILD_MTYPE_HANDLE).

The read_exprule() method returns a pointer to a CsExpRuleList that contains the expanded versions of all the rules that matched the pattern in the input.

The read_exprule_async() methods take either a pointer or a reference to a CsRule depending upon the method’s signature.

See also:

The VnmParmBlock Reference section on CsRule for more information on constructing a Rule and also for more information on wildcards. Also, refer to the section on CsExpRuleList for more information on retrieving the returned information, and the section on CsExpRule for information on the expanded version of a rule.


rule_pattern A CsRule object that describes the information to search for.



CsUIRelationHandle read_mrelq_async ( ) , read_mrelq_async ( ) , read_mrelq_async ( ) ,


read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq_async ( ), read_mrelq ( )

CsTresponseid read_mrelq_async ( CsAssocList * relation,CsVnmMsg::CsVnmFunction_e function,CsVnmParmBlock * request, CsMailClient * who ) ;

CsTresponseid read_mrelq_async ( CsAssocList & relation,CsVnmMsg::CsVnmFunction_e function,CsVnmParmBlock * request, CsMailClient & who ) ;

CsTresponseid read_mrelq_async ( CsAssocList * relation, CsVnmMsg::CsVnmFunction_e function, CsVnmParmBlock * request, CsFindSpec * filter, CsMailClient * who ) ;

CsTresponseid read_mrelq_async ( CsAssocList & relation, CsVnmMsg::CsVnmFunction_e function, CsVnmParmBlock & request, CsFindSpec & filter, CsMailClient * who ) ;

CsModelRspLst * read_mrelq ( CsTresponseid resp_id ) ;


relation A CsAssocList specifying the models to access.

function Which of the following CsUIModelHandle functions to invoke in SpectroSERVER: read(), read_next(), write(), describe(), action()

request Input parameters for the request.


filter A CsFindspec object to be used as a filter after the associations have been expanded.


CsUIRelationHandle read_mrelq_async ( ) , read_mrelq_async ( ) , read_mrelq_async ( ) ,


This method pair allows you to perform functions on multiple attributes of multiple models by creating a list of associations to tell SpectroSERVER which models to access. Each association should have either the left or right side as a wildcard. These expanded wildcards are the models that are queried.

The read_mrelq() method returns a list of CsModelRsp. Each CsModelRsp contains the response for a particular model.

The two additional read_mrelq_async() methods take either a pointer or a reference to a CsAssocList, depending upon the method’s signature; also these methods provide a filter that details the selection of models to access.

See also: The VnmParmBlock Reference sections on CsAssocList, CsModelRspLst, and CsVnmMsg.

Note:Note:

Use the appropriate type of CsVnmParmBlock for the specific CsUIModelHandle method being performed. See Table 25

Table 25: Method List

Method (CsVnmMsg.h) CsVnmParmBlock

MODEL_READ CsAttrValList

MODEL_WRITE CsAttrValList

MODEL_ACTION CsAction

MODEL_READ_NEXT CsAttrValList

MODEL_CHECK_PERMISSION CsSecPerm

MODEL_NEW_READ CsAttrReadReqList

MODEL_NEW_WRITE CsAttrWriteReqList

MODEL_DESCRIBE CsAspect

MODEL_FIND_ATTR_BY_OID CsFindByOID

CsUIRelationHandle read_rule_async ( ) , read_rule_async ( ) , read_rule ( )


read_rule_async ( ), read_rule_async ( ), read_rule ( )

CsTresponseid read_rule_async ( CsRule * rule_pattern, CsMailClient * who ) ;

CsTresponseid read_rule_async ( CsRule & rule_pattern, CsMailClient * who ) ;

CsRuleList * read_rule ( CsTresponseid resp_id ) ;

This method pair is used to read a rule that matches a certain pattern in a relation. The rule pattern to be matched is specified in the CsRule object input to the initiator. Either the left or right or both model types can be specified as a wildcard (CS_WILD_MTYPE_HANDLE).

The read_rule () method returns a pointer to a CsRuleList object that contains all the rules that matched the pattern in the input.

The read_rule_async() methods take either a pointer or a reference to a CsRule, depending upon the method’s signature.

See also:

The VnmParmBlock Reference section on CsRule for more information on constructing a Rule and also for more information on wildcards. Also see the section on CsRuleList for more information on retrieving the returned information.


rule_pattern A CsRule object that describes the information to search for.



CsUIRelationHandle reg_rel_watch_async ( ) , reg_rel_watch ( ) , re l_watch_update


reg_rel_watch_async ( ), reg_rel_watch ( ), rel_watch_update

CsTresponseid reg_rel_watch_async ( CsRelWatchReq * what, CsMailClient * who ) ;

CsRelWatchRsp * reg_rel_watch ( CsTresponseid resp_id ) ;

CsRelWatchRsp * rel_watch_update ( CsTresponseid resp_id ) ;

These methods process registration for watching relation changes of a specific model. The client specifies the request by using a CsRelWatchReq object. The relation change is essentially a change in the association.

The retriever of the pair uses the response ID returned by the requestor.

The rel_watch_update() method is called whenever an unsolicited relation change is received from the VNM. As associations are added or removed, these unsolicited updates are generated. The pointer to a CsRelWatchRsp that contains these changes is returned back.


what The CsRelWatchReq object specifying the type of association change to be watched.



CsUIRelationHandle remove_async ( ) , remove_async ( ) , remove ( )


remove_async ( ), remove_async ( ), remove ( )

CsTresponseid remove_async ( CsAssocList * what, CsMailClient * who ) ;

CsTresponseid remove_async ( CsAssocList & what, CsMailClient * who ) ;

CsAssocCount * remove ( CsTresponseid resp_id ) ;

This method pair is used to remove associations from a relation, (i.e., when the relation between two models needs to be broken). The models that are related form an association. Many associations can be removed from a relation in a single request. A list of such associations is the CsAssocList object input to the initiator. The associations in the list are removed from the relation, thereby breaking the relationship between the two models in each association.

The remove() method returns a pointer to a CsAssocCount that indicates how many associations were successfully removed from the relation.

The remove_async () methods take either a pointer or a reference to a CsAssocList, depending upon the method’s signature.

See also:

The VnmParmBlock Reference sections on CsAssociation and CsAssocList for information on constructing an association and stringing them together in a CsAssocList. Also, refer to the section on CsAssocCount for information on retrieving information from one.


what A CsAssocList object that describes the associations to be removed.



CsUIRelationHandle unreg_rel_watch_async ( ) , unreg_rel_watch ( )


unreg_rel_watch_async ( ), unreg_rel_watch ( )

CsTresponseid unreg_rel_watch_async ( CsRelWatchReq * what, CsMailClient * who ) ;

CsRelWatchRsp * unreg_rel_watch ( CsTresponseid resp_id ) ;

This method pair processes unregistering for watching relation changes of a specific model. The requestor specifies the unregistration request using a CsRelWatchReq object, and the responder uses the returned CsTresponseid to request a response from the SpectroServer. The response is returned in the form of a CsRelWatchRsp object.


what The CsRelWatchReq object specifying the type of association change to be no longer watched.



CsUIStat unreg_rel_watch_async ( ) , unreg_rel_watch ( )


CsUIStat

Class Hierarchy

Include FileCsUIStat.h

DescriptionThis class provides methods for reading the statistics accessible to a single SpectroSERVER, either from its internal database or the archived statics/events database. It includes methods necessary to choose the types of statistics to query for, and to scroll up/down the statistics database for statistics logged at earlier or later times, relative to the current position.

CsModelAncestor

CsUILogs

CsUIStat

Note:Note:

The retriever method descriptions for this class can be found in CsUILogs.h. These methods have been included here for clarity.

CsUIStat unreg_rel_watch_async ( ) , unreg_rel_watch ( )


Public Methods

Method Description

CsUIStat ( ) Class constructor.

CsUIStat ( ) Copy constructor.

attach_async ( ), attach ( ) This pair of methods allows the Application to attach to the Statistical database.


detach_async ( ), detach ( ) This pair of methods allows the Application to detach from the Statistical database.


This pair of methods allows you to change the filter used to screen the statistics that are sent.


Allows an application to scroll up within the SpectroSERVER Statistical database.


This pair of methods allows you to scroll to the bottom within the SpectroSERVER Statistical database.


Allows an application to scroll to the first statistic matching the specified date and time within the SpectroSERVER Statistical database.


Allows an application to scroll to the top of the SpectroSERVER Statistical database.

scroll_up_async ( ), scroll_up ( ) Allows an application to scroll up within the SpectroSERVER Statistical database.

unsol_scroll ( ) The retriever that should be used whenever an unsolicited statistic comes in from SpectroSERVER.

CsUIStat CsUIStat ( )


CsUIStat ( )CsUIStat ( CsLscpeHandle & my_landscape ) ;

This method constructs a CsUIStat object that provides a user-level interface to a particular landscape, to perform functions such as choosing the types of statistics to query to, and to scroll up/down the SpectroSERVER Statistical database.

See also:

The CsLscpeHandle class in the VnmParmBlock Reference, and the section on Distributed SpectroSERVER in the SpectroSERVER API Developer’s Guide.

CsUIStat ( )CsUIStat ( const CsUIStat & original ) ;

The copy constructor for this class.





CsUIStat at tach_async ( ) , at tach ( )



CsTresponseid attach_async ( CsIEventFilter * what, CsMailClient * who ) ;

CsAttachResponse * attach ( CsTresponseid r_id ) ;

This pair of methods allows an application to attach to the SpectroSERVER Statistical database. Attaching allows the Application to receive new statistics as they are generated. CsIEventFilter defines the types of statistics to be received.

This pair of methods returns a pointer to an AttachResponse containing the statistics or error codes and a WindowId. This window ID should be saved, because it is needed to detach from SpectroSERVER.



a Call the CsMailService method UnsolRegister() with the following parameters:

• A pointer to an instantiation of a derived class of CsMailClient with a Notify() to handle the unsolicited messages.

• A pointer to an instantiation of CsUIStat handle.


2 Construct a CsIEventFilter Object:


what A CsIEventFilter object that describes the information to search for.



CsUIStat at tach_async ( ) , at tach ( )



b Pass the constructor the number of stats to filter.

c Pass the constructor the EventFilter to filter stats.

3 Attach to the CsMailService for Statistics:

a Call the attach_async() method of CsUIStat with the following parameters:

• A pointer to the IEventFilter just constructed.



Table 26: CsUIStat attach_async() and attach() Error Codes

Error Meaning

NO_MORE_MESSAGES There are no statistics in the stat log that are applicable to the kind of filter that was used. If a datetime filter was chosen, there are no statistics that match the filter, the cursor position in the database is beyond the edge of the database, or it is trying to read a statistic while the cursor is already on the last record. Choose a less limiting filter.

INSUFFICIENT_MEMORY Not enough memory to create the previous, last, or next record read from the database.

NO_SUCH_WINDOW_ID The referenced window ID was not valid. This happens when attach fails for the client or when detach has been called with an invalid ID. The window ID should be obtained from the original AttachResponse, using the get_log_windowid() method after verifying that the response is valid.

CsUIStat copy ( )


See also:

The VnmParmBlock Reference section on CsIEventFilter for more information on constructing an IEventFilter. Also, see the section on CsAttachResponse for information on retrieving information from one.



CS_NULL_INPUT An invalid attach request was sent for an attach. The request is either not known to the SpectroSERVER Statistics Manager or it has not been properly configured.

Caution:Caution:


Table 26: CsUIStat attach_async() and attach() Error Codes

Error Meaning

CsUIStat detach_async ( ) , detach ( )



CsTresponseid detach_async ( CsILogWindowId * what, CsMailClient * who ) ;


This pair of methods allows the Application to detach from the Statistic Log Database. The Application ceases to get statistic updates. This method takes, as an input parameter, the window ID that was returned from the attach() method.

The retriever method returns a pointer to a VnmParmBlock, containing the error code for the detach.

Table 27 lists the possible CsError error return code:

See also: The VnmParmBlock Reference on CsILogWindowId for more information on constructing an ILogWindowId. Also, see the section on CsVnmParmBlock for information on retrieving information from one.


what A CsILogWindowId object that contains the window ID to be used.



Table 27: CsUIStat detach_async() and detach() Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID being used to detach is invalid (there is no client with that ID). Use the WindowId received when CsUIStat::attach()was called to construct the ILogWindowID. Pass the CsILogWindowID object to detach_async().

CsUIStat replace_f i l ter_async ( ) , replace_f i l ter ( )



CsTresponseid replace_filter_async ( CsIEventFilter * what, CsMailClient * who ) ;

CsScrollResponse * replace_filter ( CsTresponseid r_id ) ;

This pair of methods allows the Application to change the filter that is used to screen the statistics that are sent. The CsIEventfilter must include the window ID that was returned from the attach() method.

The replace_filter()method returns a pointer to a ScrollResponse. This contains statistics that have passed your new filtering criteria.



what A CsIEventFilter object that describes the information to search for.



Table 28: CsUIStat replace_filter_async() and replace_filter Error Codes

Error Meaning

INSUFFICIENT_MEMORY Not enough memory to create the new IEventFilter, because there was not enough memory when adding filter nodes on the EventFilter.

CsUIStat replace_f i l ter_async ( ) , replace_f i l ter ( )


See also:

The VnmParmBlock Reference section on CsIEventFilter for more information on constructing an IEventFilter. Also see the section on CsScrollResponse for information about extracting the statistics.

NO_MORE_MESSAGES There are no more statistics in the stat log that are applicable to the filter that was used. If datetime filters were chosen, then there are no statistics that fall between those datetime stamps. Another reason might be that the cursor position in the SpectroSERVER Stat Log database is beyond the edge of the database. Choose a less limiting filter.

Table 28: CsUIStat replace_filter_async() and replace_filter Error Codes

Error Meaning

CsUIStat scrol l_down_async ( ) , scrol l_down ( )



CsTresponseid scroll_down_async ( CsILogWindowId * what, CsMailClient * who ) ;

CsScrollResponse * scroll_down ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll down within the SpectroSERVER Statistical database. Scrolling down returns statistics that occurred later in time, relative to the current position. This method takes the window ID that was returned from the attach() method as an input parameter .


See also: The VnmParmBlock Reference section on CsILogWindowId for more information on constructing one. Also refer to the section on CsScrollResponse for more information on retrieving the statistics returned.


what A CsILogWindowId object that contains the window ID being used.



Table 29: CsUIStat scroll_down_async() and scroll_down() Error Codes

Error Meaning


NO_MORE_MESSAGES There are no more statistics in the stat log in the direction of scroll (already at the bottom of the stat log).

CsUIStat scrol l_ to_bot tom_async ( ) , scrol l_to_bot tom ( )



CsTresponseid scroll_to_bottom_async ( CsILogWindowId * what, CsMailCLient * who ) ;

CsScrollResponse * scroll_to_bottom ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll to the bottom within the SpectroSERVER Statistical database. Scrolling to the bottom returns the latest statistics in the database. This method takes the window ID that was returned from the attach() method as an input parameter.


See also: The VnmParmBlock Reference section on CsILogWindowId for more information on constructing one. Also refer to the section on CsScrollResponse for more information on retrieving the statistics returned.

scroll_to_date_time_async ( ),





Table 30: CsUIStat scroll_to_bottom_async() and scroll_to_bottom() Error Code

Error Meaning


CsUIStat scrol l_to_date_t ime_async ( ) , scrol l_to_date_t ime ( )


scroll_to_date_time ( ) CsTresponseid scroll_to_date_time_async

( CsIDateTime * what, CsMailClient * who ) ;

CsScrollResponse * scroll_to_date_time ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll to the first statistic matching the specified date and time within the SpectroSERVER Statistical database. If there are no matching statistics, the Application is positioned to the closest statistic. This method takes the window ID that was returned from the attach() method as an input parameter.

The scroll_to_date_time() method returns a pointer to a CsScrollResponse object that contains the statistics.

Table 31 lists the CsError error return code:

See also:The section in the VnmParmBlock Reference section on CsIDateTime for more information on constructing one. Also refer to the section on CsScrollResponse for more information on retrieving the statistics returned.


what A CsIDateTime object that contains the date and time to search for.


r_id The response ID that identifies the returned message.

Table 31: CsUIStat scroll_to_date_time_async() and scroll_to_date_time Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. The window ID should be obtained from the original CsAttachResponse object using get_log_windowid() after verifying that the response is valid.

CsUIStat scrol l_to_top_async ( ) , scrol l_to_top ( )



CsTresponseid scroll_to_top_async ( CsILogWindowId * what, CsMailClient * who ) ;

CsScrollResponse * scroll_to_top ( CsTresponseid r_id ) ;

This pair of methods is used to scroll to the top within the SpectroSERVER Statistical database. Scrolling to the top returns the earliest statistics in the database. This method takes as an input parameter the window ID that was returned from the attach() method. These methods return a pointer to a ScrollResponse that contains the statistics.


See also: See the VnmParmBlock Reference section on CsILogWindowId for more information on constructing one. Also refer to the section on CsScrollResponse for more information on retrieving the statistics returned.





Table 32: CsUIStat scroll_to_top_async() and scroll_to_top() Error Code

Error Meaning


CsUIStat scrol l_up_async ( ) , scrol l_up ( )


scroll_up_async ( ), scroll_up ( )

CsTresponseid scroll_up_async ( CsILogWindowId * what, CsMailClient * who ) ;

CsScrollResponse * scroll_up ( CsTresponseid r_id ) ;

This pair of methods allows the Application to scroll up within the SpectroSERVER Statistical database. Scrolling up returns statistics that occurred earlier in time, relative to the current position. This method takes as an input parameter the window ID that was returned from the attach() method.


See also: The VnmParmBlock Reference section on CsILogWindowId for more information on constructing one. Also, see the section on CsScrollResponse for more information on retrieving the statistics returned.





Table 33: CsUIStat scroll_up_async() and scroll_up() Error Codes

Error Meaning


NO_MORE_MESSAGES There are no more statistics in the stat log in the direction of scroll (already at the top of the stat log).

CsUIStat unsol_scrol l ( )


unsol_scroll ( )CsScrollResponse * unsol_scroll ( CsTresponseid r_id ) ;

This method is the retriever that should be used whenever an unsolicited statistic comes in from SpectroSERVER. The unsol_scroll() method is inherited from CsUILogs.

This method returns a pointer to a CsScrollResponse object that contains the statistics.

The unsol_scroll() method is one step in processing an unsolicited statistic message. Retrieving statistics requires the following general processes:

1 Message Arrives —The CsMailService receives an unsolicited message (unexpected response ID) for the subscriber from SpectroSERVER.

2 Unpack Message — The CsMailService unpacks the message, creating a CsScrollResponse object and passes it to the CsUIStat object.

3 Notify Subscriber — The CsMailService calls the client Notify() using the unexpected response ID.

4 Get Pointer — Within the Notify(), the subscriber calls the unsol_scroll() retriever method, passing it the response ID it received from the Notify().

5 Retrieve Information — The subscriber processes the information within the CsScrollResponse object.

See also:



Note:Note:

The Notify() method of a subscriber should be defined to include the code that calls the unsolicited retriever of CsUIStat, passing it r_id as a parameter, to retrieve the unsolicited message it has received.

CsUIStat unsol_scrol l ( )


CsMailService::UnSolRegister() and the VnmParmBlock Reference sections on CsScrollResponse for more information on retrieving statistics from a CsEventList.

CsUIVLMap unsol_scrol l ( )


CsUIVLMap

Class Hierarchy

Include FileCsUIVLMap.h

DescriptionThe CsUIVLMap class provides methods that can retrieve VNM/Landscape Map (V/L Map) information from SpectroSERVER. With the advent of Distributed SpectroSERVER, this class has been added to the Asynchronous SSAPI to provide applications with the ability to access multiple VNMs and Landscapes after making an initial connection to a Distributed SpectroSERVER. The application can request a copy of the VNM/Landscape Map, which contains information about all the SpectroSERVERs and landscapes that are accessible through the initial connection. The application can then use the information in the map to query any of the SpectroSERVERS using the asynchronous handle classes. The application can also receive updates to the map. The VNM/Landscape map is kept and maintained by the Location Server, and when accessing this information it talks directly with that application, not the SpectroSERVER.

CsUIVLMap is designed to work with applications that derive a class from CsMailClient, then instantiate an object of that class, which in turn registers with the MaillService to receive unsolicited updates. The response_id returned from the registration is used in forming the request to attach for VNM/Landscape Map information. The CsMailService calls the MailClient’s Notify() method when a response to the attach request arrives. The

CsModelAncestor

CsUIVLMap

CsUIVLMap unsol_scrol l ( )


MailClient can then collect that response, which will be a copy of the SpectroSERVER’s VNM/Landscape Map.

For as long as the application remains attached, the CsMailService will call the MailClient’s Notify() method when unsolicited messages arrive containing updates to the VNM/Landscape map. The application can apply these updates to its copy of the VNM/Landscape Map as they are collected. When the application no longer wishes to receive updates to the VNM/Landscape Map, it may detach from SpectroSERVER.

For more information about constructing applications that can access this information, refer to the SpectroSERVER API Developer’s Guide.

CsUIVLMap CsUIVLMap ( )


Public Methods

CsUIVLMap ( )CsUIVLMap ( void ) ;

This is the default constructor for the CsUIVLMap class.

CsUIVLMap ( )CsUIVLMap ( const CsUIVLMap & map_to_copy ) ;

This method is the copy constructor for CsUIVLMap. This method creates a new CsUIVLMap object and copies the value of the map_to_copy object into it.

Method Description

CsUIVLMap ( ) Class constructor.

CsUIVLMap ( ) Copy constructor.

attach_async ( ), attach ( ) Requests and retrieves V/L map updates.


detach_async ( ), detach ( ) Detach from SpectroSERVER and stop receiving V/L map updates.

get_non_secure_map_async ( ), get_non_secure_map ( )

unsol_update ( ) Allows a user to collect unsolicited updates

operator= ( ) Assignment operator.


map_to_copy Object to be copied.

CsUIVLMap at tach_async ( ) , at tach ( )



CsTresponseid attach_async ( CsVLMapAttachReq * map_attach_request,CsMailClient * requestor ) ;

CsVnmLscpeMap * attach ( CsTresponseid response_id ) ;

This method pair requests that SpectroSERVER send the current (at the time of the attach) V/L Map and allows a user program to call unsol_update() to get subsequent V/L Map updates as they are received from SpectroSERVER.

The initiator returns a response ID. This response ID is used by the retriever to collect a CsVnmLscpeMap object indicating whether the MailClient successfully detached from SpectroSERVER.



a Call the CsMailService method UnsolRegister() with the following parameters:

• A pointer to an instantiation of a derived class of CsMailClient with a Notify() to handle the unsolicited V/L Map updates.

• A pointer to an instantiation of CsUIVLMap handle.


2 Construct a CsVLMapAttachReq Object:


map_attach_request A CsVLMapAttachReq that contains a response ID returned from the call to CsMailService::UnsolRegister().

requestor The CsMailClient object to be notified on completion.

response_id Returned by the initiator; used as input by the retriever.

CsUIVLMap copy ( )


a Pass the response ID returned from UnsolRegister() to the constructor.

3 Attach to the CsMailService for V/L Map updates:

a Call the attach_async() method of CsUIVLMap with the following parameters:

• A pointer to the CsVLMapAttachReq object just constructed.




Note:Note:

If the request could not be processed, the initiator returns a -1. The retriever returns an error code imbedded in an empty CsVnmLscpeMap. The error message can be retrieved by calling CsVnmParmBlock::get_error().

Caution:Caution:


CsUIVLMap detach_async ( ) , detach ( )



CsTresponseid detach_async ( CsVLMapAttachReq * map_attach_request, CsMailClient * requestor ) ;

CsVnmParmBlock * detach ( CsTresponseid response_id ) ;

This pair of methods is responsible for detaching from the SpectroSERVER and thus stop receiving updates to V/L Map information. The detach () method takes a CsVnmParmBlock of type CsVLMapAttachRequest, and a pointer to the requesting MailClient. The detach_async() method returns a response id which is used subsequently to pick up the response to the attach request.

The detach() method is the retriever method used to collect a CsVnmParmBlock indicating whether the MailClient successfully detached from the SpectroSERVER.

See also:

CsVnmParmBlock and CsVLMapAttachReq in the VnmParmBlock Reference.


map_attach_request A CsVLMapAttachReq that contains a response ID returned from the call to CsMailService::UnsolRegister()

requestor The CsMailCleint object to be notified on completion.

response_id Returned by the initiator; used as input by the retriever.

Note:Note:

If the request could not be processed, a -1 is returned, and the CsVnmParmBlock object contains an error message.

CsUIVLMap get_non_secure_map_async ( ) , get_non_secure_map ( )


get_non_secure_map_async ( ),get_non_secure_map ( )

CsTresponseid get_non_secure_map_async ( CsVnmParmBlock * req, CsMailClient * requestor ) ;

CsVnmLscpeMap * get_non_secure_map ( CsTresponseid response_id ) ;

This method pair retrieves a snapshot of the non secure map (all entries in the map except those whose service type is a landscape service type).


req A CsVnmParmBlock

requestor The CsMailClient object to be notified on completion.

response_id The response ID identifying the returned message.


CsUIVLMap unsol_update ( )


unsol_update ( )CsVLMapUpdate * unsol_update

( CsTresponseid unsol_register_id ) ;

This retriever method allows a user to collect unsolicited updates and apply them to the MailClient’s copy of the V/L Map.

This method returns a pointer to a CsVLMapUpdate object containing the map updates.

A call to unsol_update() is used to retrieve an unsolicited V/L Map update message in the following manner:

1 Message Arrives -- The CsMailService receives an unsolicited message (unexpected response ID) for the subscriber from SpectroSERVER.

2 Unpack Message -- The CsMailService unpacks the message (a process which creates a CsVLMapUpdate object) and hands it to the CsUIVLMap handle.

3 Notify Subscriber -- The CsMailService calls the client’s Notify() using the unsolicited response ID.

4 Get Pointer -- Within the Notify(), the subscriber calls the unsol_update() retriever method, using the response ID passed to the Notify().

5 Retrieve Information -- The subscriber processes the information contained in the CsVLMapUpdate.

See also:

CsVLMapUpdate in the VnmParmBlock Reference.


unsol_register_id The response ID returned when the MailClient registered for unsolicited messages by calling UnsolRegister().

CsUIVLMap operator= ( )


operator= ( )CsUIVLMap & operator = ( const CsUIVLMap & right_hand_side ) ;

This method is an assignment operator for the CsUIVLMap class. It deletes the value of the current object and assigns it a reference to the CsUIVLMap right_hand_side.




Synchronous SSAPI Classes

This section gives a synopsis of the classes and methods which control and implement the Synchronous SSAPI.

The following classes are used in conjunction with CsVnmParmBlock and the classes derived from it. The CsVnmParmBlock classes are not specific to the SSAPI, and are explained in the VnmParmBlock Reference.

The Synchronous SSAPI includes classes to establish and manage communications with SpectroSERVER, and Handle classes, which are used to exchange information with objects within the SPECTRUM database. Table 34 lists the Synchronous SSAPI classes:

Table 34: Synchronous SSAPI Classes

Class Purpose

CsSMailService Enables information exchange with SpectroSERVER.

CsSMailServOpts Sets the CsMailService options.

CsSMSAppID Passes application information to the CsMailService.

CsSModelAncestor Defines the sync interface that communicates with the SSAPI.

CsSYAlarm Exchanges information about alarms.

CsSYEvent Exchanges information about events.

CsSYGlobalScapeHandle Searches across multiple landscapes.

CsSYLandScapeHandle Exchanges information about the Landscape.

Synchronous SSAPI Classes


Each class defines several methods. Each method provides a specific function. For example, the read_sync() method of the CsSYModelHandle class reads attributes of a model.

CsSYModelHandle Exchanges information about models.

CsSYModelTypeHandle Exchanges information about model types.

CsSYRelationHandle Exchanges information about relations.

CsSYStat Exchanges information about statistics.

CsSYVLMapHandle Receives information about the VNM/Landscape map in a Distributed SpectroSERVER environment.

Table 34: Synchronous SSAPI Classes (Continued)

Class Purpose

CsSMailService


CsSMailService

Class Hierarchy

Include FileCsSMailserv.h.

DescriptionThe CsMailService class provides a means of sending and receiving messages to a SpectroSERVER. Its methods deal with initiating contact with the distributed SpectroSERVER environment, and the maintenance of that connection. An instantiated CsMailService object is also referred to as the MailService. In the synchronous mode, the Application makes a request. The Synchronous SSAPI sends the request to SpectroSERVER and waits for a response. Once the response comes back, the SSAPI passes the response back to the requesting Application.

CsGSMailService

CsSMailService

Note:Note:

An CsSMailService must be created prior to instantiating any SSAPI handle objects and initiating any requests using a SSAPI handle.

CsSMailService


Public Methods

Method Description

CsSMailService ( ) Constructs and initializes a CsSMailService object.

CsSMailService ( ) Constructs a CsSMailService Object.

get_current_connect_error ( ) Returns the current connection error.

get_options ( ) Retrieves the options for the CsSMailService.

idle ( ) Allocates time, pending response from the server.

set_options ( ) Sets the options for the CsSMailService.

status ( ) Checks error status.

CsSMailService CsSMai lServ ice ( )


CsSMailService ( )CsSMailService ( const CsSMSAppID & ms_appid,

const CsSMailServOpts & ms_options = CsSMailServOpts::default_sms_options ) ;

This method initializes and returns a CsSMailService object.

CsSMailService ( )CsSMailService ( const char * vnm_name, int socket_number,

const CsSMSAppID & ms_appid, const CsSMailServOpts & ms_options =

CsSMailServOpts::default_sms_options ) ;

This method constructs the CsMailService object.


ms_appid Identifies the application constructing the mail service.


Note:Note:This method is new for 6.0.


vnm_name The name of the host on which SpectroSERVER is running.

socket_number TCP port number used by SpectroSERVER. Usually 0xBEEF.

ms_appid Identifies the application constructing the mail service.


Note:Note:This constructor has been obsoleted as of 6.0.

CsSMailService get_current_connect_error ( )



( char * * error_message = 0 ) const ;

This method returns the current connection error for this service. If the error_message parameter is not 0, then a vector duplicated copy of the corresponding error message is also returned. If there is no error message, then error_message will be set to 0. The error returned by this method is always the most current.


error_message A pointer to the current message

Caution:Caution:

The caller is responsible for deleting the returned error message using a C++ vector delete statement. Be careful when using this method when called back for handle_vnm_error(). It is possible that the connection state has changed since the notification was queued and this method may give an error that is inconsistent with the notification error code.

CsSMailService get_opt ions ( )


get_options ( )void get_options ( CsSMailServOpts * ms_opts ) ;

This method retrieves the options for the CsMailService in the form of the CsSMailServOpts object. To get the individual options use the CsSMailServOpts::get() methods.

The following is an example of how to implement this method.

CsSMailServOpts ms_opts;mail_service->get_options(&ms_opts) ;ms_opts.set_ciftimeout(60) ;mail_service->set_options(ms_opts) ;

idle ( )void idle ( void ) ;

This method allows Sync SSAPI to allocate some time pending response from the server. It would be followed by a call to CsSYVLMapHandle::get_updated_map ().


ms_opts Options object that will be set to match the current mail service options.

CsSMailService set_opt ions ( )


set_options ( )void set_options ( const CsSMailServOpts & ms_opts ) ;

This method sets the options for the CsMailService. To see the individual options see the class CsSMailServOpts. This method will be used to change the options of the CsMailService once the CsMailService is invoked.

status ( )int status ( void ) ;

This method checks error status and returns an int that indicates error status.


ms_opts The new set of options.

CsSMailServOpts s tatus ( )


CsSMailServOpts

Class Hierarchy

Include FileCsSMSOpts.h

DescriptionThis class is used to set the Mail Service’s options. A CsSMailServOpts object is created and passed as an argument in the CsSMailService constructor and CsSMailService::set_options() method. This class contains methods to get and set individual options.

CsSMSOpts

CsSMailServOpts s tatus ( )


Public Methods]

Method Description

CsSMailServOpts ( ) The class constructor.

CsSMailServOpts ( ) Copy constructor.


Sets the cache_failed_connections option.


Sets and retrieves the handshake timeout value.


This method pair sets and retrieves the number of milliseconds to wait for the TCP connect.


Sets and retrieves the minimum application version.


Returns the value of the use_polling flag.


Sets the size of the tcp buffer.

get_use_polling ( ), set_use_polling ( )

Sets the use_polling option to true.

get_user_name ( ), set_login ( ) Retrieves the user name of the user running the application.


CsSMailServOpts CsSMai lServOpts ( )


CsSMailServOpts ( )CsSMailServOpts( void ) ;

This constructor creates a CsSMailServOpts object with a set of default values for each option. To set the individual options use the methods that follow. The options and their default values are listed in the table below.

CsSMailServOpts ( )CsSMailServOpts ( const CsSMailServOpts & original ) ;

Copy constructor for this class.

Option Default Value

Seconds cif_timeout = 60 1 minute in seconds

CsVersionNumber min_version DEFAULT_VERSION

CsTboolean use_polling_flag TRUE

CsTulong poling cycle = 3600000 one hour in milliseconds

CsTulong tcp_buffer_size CS_NO_TCP_BUFFER_SIZE

CsTulong connect_time_limt = 5000 5 seconds in milliseconds

CsTboolean print_version FALSE

CsTboolean cache_failed_connections TRUE

const char * user_name = 0 uses operating system username

const char * password = 0 no password



CsSMailServOpts get_cache_fa i led_connect ions ( ) , set_cache_fa i led_connect ions ( )



void set_cache_failed_connections ( CsTboolean new_cache_failed_connections )const ;

CsTboolean get_cache_failed_connections ( void ) ;

This method pair sets and retrieves the cache_failed_connections option to TRUE or FALSE. If the option is TRUE, then failed connections will be cached and retried independently so application calls will not be delayed. This is particularly useful with distributed finds in a network where some machines may not be pingable.


int get_cif_timeout ( void ) const ;

void set_cif_timeout ( int new_cif_timeout ) ;

This method pair retrieves and sets the current value of the handshake time-out which is used for the creation of sockets. The CsMailService employs these sockets for communication. The values passed and returned are in seconds.


new_cache_failed_connections New flag value.


new_cif_timeout New timeout value.

CsSMailServOpts get_connect_t ime_limi t ( ) , set_connect_t ime_l imi t ( )



CsTulong get_connect_time_limit ( void ) const ;

void set_connect_time_limit ( CsTulong new_connect_time_limit ) ;

This method pair sets and retrieves the number of milliseconds to wait for the TCP connect.


int get_mail_timeout ( void ) const ;

void set_mail_timeout ( int new_mail_timeout ) ;

This method pair sets and retrieves the mail timeout value.


new_connect_time_limit New time value


new_mail_timeout New timeout value.

CsSMailServOpts get_min_vers ion ( ) , set_min_version ( )



CsVersionNumber get_min_version ( void ) const ;

void set_min_version ( CsVersionNumber new_min_version ) ;

This method pair sets and retrieves the minimum VPAPI version that this application can use to communicate with a server.


CsTulong get_polling_cycle ( void ) const ;

void set_polling_cycle ( CsTulong new_polling_cycle ) ;

This method pair sets and retrieves the length of the polling cycle for server location information. The values are in milliseconds.


new_min_version New VPAPI minimum version.


new_polling_cycle New polling value.

CsSMailServOpts get_pr int_vers ion ( ) , set_pr int_version ( )



CsTboolean get_print_version ( void ) const ;

void set_print_version ( CsTboolean new_print_version ) ;

This method pair sets and retrieves whether the version of SSAPI is printed when the mail service is constructed. If the option is TRUE then the version is printed to the standard output stream.


CsTulong get_tcp_buffer_size ( void ) ;

void set_tcp_buffer_size ( CsTulong new_tcp_buffer_size ) ;

This method pair sets and retrieves the size of the TCP buffer.


new_print_version New print version number.


new_tcp_buffer_size New size value.

CsSMailServOpts get_use_pol l ing ( ) , set_use_pol l ing ( )


get_use_polling ( ),set_use_polling ( )

CsTboolean get_use_polling ( void ) const ;

void set_use_polling ( CsTboolean new_use_polling_flag ) ;

This method pair sets and retrieves the value of the use_polling option. This controls how the mail service gets server location information. It can either poll periodically or listen continuously. If the option is TRUE then polling is used.

get_user_name ( ),set_login ( )

const char * get_user_name ( void ) const ;

void set_login ( const char * new_password,const char * new_user_name = 0 ) ;

This method pair sets and retrieves the user name of the user running the application. A return of NULL indicates that the user specified by the operating system will be used. In addition, set_login() sets the password used to login to all SPECTRUM servers.


new_use_polling_flag New flag value.


new_password Password for login.

new_user_name User name for login.

Note:Note:

The password is encrypted when set and cannot be read back in plain text, so there is no method to get the password. This method pair is new for 6.0.

CsSMailServOpts operator = ( )


operator = ( ) CsSMailServOpts & operator =

( const CsSMailServOpts & right_hand_side ) ;

Assignment operator for this class.



CsSMSAppID operator = ( )


CsSMSAppID

Class Hierarchy

Include FileCsSMSAppID.h

DescriptionThis class is used to pass application information to the Mail Service. A reference to a CsSMSAppID object is passed as an argument in the CsMailService constructor to set the Application ID information.

CsSMSAppID

CsSMSAppID CsSMSAppID ( )


Public Methods

CsSMSAppID ( )CsSMSAppID( const char * application_name = “UNKNOWN”,

const char * application_version = “0.0”,const char * sub_application_name = “UNKNOWN” ) ;

This method constructs a CsSMSAppID object which is used as an argument in a CsMailService constructor to set the application ID.


application_name The name of the client application establishing the connection, used by the application for identification. A list of the client’s applications attached to a SpectroSERVER may be viewed in the VNM Client View. An example would be SpectroGRAPH. The default value is UNKNOWN.

application_version The version number of the client application establishing the connection, used by the application (not by SpectroSERVER) for identification. An example would be 1.12. The default value is 0.0.

sub_application_name The name of the sub-application establishing the connection, used by the application (not by SpectroSERVER) for identification. An example would be Device View. The default value is UNKNOWN.

CsSModelAncestor CsSMSAppID ( )


CsSModelAncestor

Class Hierarchy

Include FileCsSMdlAnces.h

DescriptionThis class defines the interface for the Sync Handle classes that communicate with SSAPI. A CsSModelAncestor object should never be instantiated; this class should always be derived from.

CsSModelAncestor

CsSModelAncestor CsSModelAncestor


Public Methods

CsSModelAncestorCsSModelAncestor ( void ) ;

The class constructor.

Method Description

CsSModelAncestor Class Constructor.

get_current_connect_error ( )

Returns the current connection error for this handle.

get_current_server ( ) Sets server socket address to match socket address of requests

get_current_version ( ) This method returns the current VPAPI version used by this handle to communicate with the current server. If there is no current server, then it returns the default version.

get_service_id ( ) Returns a copy of this handle’s service ID.

get_service_type ( ) Returns the handle’s service type.

is_connected ( ) Returns TRUE if a connection to the server is available.

is_current_primary ( ) Checks whether requests are sent to primary server.

is_equal_service ( ) Compares handles for use of identical service IDs.

CsSModelAncestor get_current_connect_error ( )




This method returns the current connection error for this handle. If the error_message parameter is not 0, then a vector duplicated copy of the corresponding error message is also returned. If there is no error message, then error_message will be set to 0.

get_current_server ( )CsTboolean get_current_server ( CsSocketAddress * current_server ) ;

This method sets the current server socket address to match the server where requests for this handle would be sent. If there is no available server for this handle, then the socket address for the primary server is returned. In either case, the method return value is TRUE. If no server has data for this handle, then this method returns FALSE and current server is not defined.


error_message Returned error message.

Caution:Caution:

Be careful when using this method when called back for a connection notification. It is possible that the connection state has changed since the notification was queued and this method may give an error that is inconsistent with the notification error code. The error returned by this method is always the most current. The caller is responsible for deleting the returned error message using a C++ vector delete statement.


current_server Returned server address.

CsSModelAncestor get_current_vers ion ( )


get_current_version ( )CsVersionNumber get_current_version ( void ) const ;

This method returns the current VPAPI version used by this handle to communicate with the current server. If there is no current server, then it returns the default version.

get_service_id ( )CsServiceID * get_service_id ( void ) const ;

This returns a copy of this handle's service ID.

get_service_type ( )CsServiceType::CsServiceType_e get_service_type ( void ) const ;

This returns this handle's service type.

is_connected ( )CsTboolean is_connected ( void ) ;

This method returns TRUE if a connection is available to a server for this handle. If no such connection is available, this method returns FALSE.

Caution:Caution:

The caller is responsible for deleting memory allocated to the CsServiceID object returned by get_service_id().

CsSModelAncestor is_connect ion_success ( ) , is_connect ion_fa i lure ( )


is_connection_success ( ), is_connection_failure ( )

CsTboolean is_connection_success ( CsErrorr::CsError_e error_code ) ;

CsTboolean is_connection_failure ( CsErrorr::CsError_e error_code ) ;

This method pair tests whether a connection has succeeded or failed.

is_current_primary ( )CsTboolean is_current_primary ( void ) ;

This method checks whether the requests for this handle would be sent to the primary server. It returns TRUE if requests are being sent to the primary server. It also returns TRUE if there is no available server for this handle, since that usually means the application would be connected to the primary if it could. If requests are being sent to a secondary server, this method returns FALSE.

is_equal_service ( )CsTboolean is_equal_service

( const CsSModelAncestor & other_handle ) const ;

This compares the other handle with this handle to test whether they use the same service ID.





other_handle Handle to be compared against.

Synchronous Handle Classes



This section outlines the handle classes which are used by SMailClients to communicate with the SCsMailService.

The methods of these classes are called by the subscriber to initiate a request to SpectroSERVER, and return a pointer to a CsVnmParmBlock object. The specific type of ParmBlock depends on the method being called. This ParmBlock contains all the information requested by the subscriber.

For each such class described in this chapter, a synopsis of the constructor is listed first, followed by a synopsis of each method. The format of each synopsis is as follows:

1 The calls are shown.

2 Method functionality is described.

3 The returned object is described.

4 References to documents are listed where other information relevant to the method can be found.

5 In all cases, an overall error code is set in the returned ParmBlock. The error code can be obtained by calling the CsVnmParmBlock::get_error() method. If the request was successful, this returns CsError::SUCCESS. Other error codes are listed in the file <SPECTRUM Install Area>/SDK/include/VPAPI/CsError.h. In addition, each method can set error codes for particular parts of the request.

All Synchronous handles (except CsSYGlobalScapeHandle) establish a connection to the landscape explicitly or implicitly specified by the constructor used to instantiate the handle. The handle first checks whether a connection to the appropriate landscape already exists and, if not, it opens one. The connection to a landscape is closed when the last handle connected to that landscape is destroyed.



If the constructor does not specify a landscape, as is the case with the constructors from previous SSAPI releases (retained for backward compatibility), the connection established is to the initial landscape, (i.e., the landscape on the SpectroSERVER host specified in the CsMailService constructor. However, for applications that expect to take advantage of the distributed SpectroSERVER capabilities, a landscape should be specified when constructing a new handle. At any rate, a connection to the initial landscape will be maintained by the CsMailService, even if all handles which were connected to that landscape are destroyed.

The exceptions to the above are CsSYGlobalScapeHandle, which does not itself open a connection to a landscape, but opens and closes connections through the CsSYLandScapeHandles used in the searches, and the CsSYVLMapHandle class, which does not provide a constructor that specifies a landscape, since the V/L Map information is not landscape-specific.

When the CsMailService is destroyed, all means of connecting to landscapes are removed. For this reason, handles should not be created before the CsMailService has been instantiated, nor destroyed after the CsMailService is deleted.

Caution:Caution:

The SSAPI handle class constructors use connection resources, and are not intended to be copied, assigned to, or passed by value. They can be passed by reference, or be assigned to a pointer.

Caution:Caution:

Most VnmParmBlock objects used as input to a request must be allocated memory. The CsSMailService takes control of the memory and deletes it when finished. The exceptions are when the CsVnmParmBlock is passed by reference, which occurs in some methods of CsSYRelationHandle.

In addition, all VnmParmBlocks returned by the requesting methods are allocated memory and it is the developer’s responsibility to free this memory.

CsSYAlarm


CsSYAlarm

Class Hierarchy

Include FileCsSYAlarm.h

DescriptionThe CsSYAlarm class provides an interface which can be used to clear, update, and receive alarms.

CsSModelAncestor

CsSYAlarm

Note:Note:

CsSYAlarm can now retrieve unsolicited alarms from SpectroSERVER. This capability is turned off by default. Setting the collect_unsol parameter in the constructor to TRUE will turn on the collection of unsolicited alarms.

CsSYAlarm


Public Methods

Method Description

CsSYAlarm ( ) The class constructor.

CsSYAlarm ( ) A copy constructor.

ack_alarm_sync ( ) Method used to acknowledge alarms.

attach_sync ( ) Retrieves alarm information.

clear_alarm_sync ( ) Clears alarms.

detach_sync ( ) Discontinue retrieval of alarm information.

get_unsol_alarms ( ) Retrieves unsolicited alarms.

replace_filter_sync ( ) Changes the filter that screens alarms.

update_alarm_sync ( ) Changes the status of an alarm.

operator = ( ) The assignment operator for the class.

CsSYAlarm CsSYAlarm ( )


CsSYAlarm ( )CsSYAlarm ( CsLscpeHandle my_landscape,

CsTboolean collect_unsol = FALSE ) ;

This method constructs a CsSYAlarm object that provides a user-level interface to a particular landscape, to perform functions such as updating and clearing alarms, as well as retrieving unsolicited alarms. By default, collection of unsolicited alarms is turned off.

See also:

CsLscpeHandle in the VnmParmBlock Reference, and the section on the Synchronous SSAPI in the SSAPI Developer’s Guide.

CsSYAlarm ( )CsSYAlarm ( const CsSYAlarm & original ) ;

This method is the copy constructor for CsSYAlarm. It creates a new CsSYAlarm class and copies the value of the original object into it.



collected_unsol Determines whether or not unsolicited alarms are retained for later retrieval. By default, collection of unsolicited alarms is turned off. Setting collect_unsol to TRUE enables the collection of unsolicited alarms.



CsSYAlarm ack_alarm_sync ( )


ack_alarm_sync ( )CsVnmParmBlock * ack_alarm_sync ( CsAlarmRegister * request ) ;

This method is used to acknowledge alarms. The list of alarms to be acknowledged is contained in the given AlarmRegister. Check the error code in the returned CsVnmParmBlock to indicate if the request was successful.


request A CsAlarmRegister object that contains lists of alarms to be acknowledged.

CsSYAlarm at tach_sync ( )


attach_sync ( )CsAlarmAttachResponse * attach_sync

( CsAttachRequest * request ) ;

This method is used to attach to SpectroSERVER to retrieve alarm information.

This method returns a pointer to a CsAlarmAttachResponse object containing the alarm or error codes. The response contains the alarms that have been generated. There also is a window ID within the response that should be saved because it is needed to detach from SpectroSERVER Alarm Manager.


1 Register for unsolicited messages

a Call the CsSYSAlarm method unsol_register() and pass it a pointer to an instantiation of a derived class of CsSMailClient. Save the response ID from unsol_register().

2 Construct a CsAttachRequest object

a Pass to the constructor the response ID returned from unsol_register().

3 Attach to the SCsMailService for Alarms

a Call the attach_sync() method of CsSYAlarm and pass a pointer to the CsAttachRequest just constructed.



request A CsAttachRequest defining the attach information

CsSYAlarm at tach_sync ( )


See also:

VnmParmBlock Reference on CsAttachRequest for more information on constructing a CsAttachRequest object. Also consult the section on CsAlarmAttachResponse in the same book.

Table 35: CsSYAlarm attach_sync() Error Codes

Error Meaning


CS_NULL_INPUT The VnmParmBlock received by the attached SpectroSERVER was NULL, causing an error to be returned.

SUCCESS Attach was successful.

CsSYAlarm c lear_alarm_sync ( )


clear_alarm_sync ( )This method is used to clear an alarm (e.g., to clear a duplicate IP address alarm).

CsVnmParmBlock * clear_alarm_sync ( CsAlarmRegister * request ) ;

Table 36 lists the possible CsError return codes.


request A CsAlarmRegister object that is a list of CsAlarmListNode objects, each of which is a list of CsAlarmList objects. Each CsAlarmList object is a list of CsAlarmNode objects (alarms) for a particular model.

Table 36: CsSYAlarm clear_alarm_sync() Error Codes

Error Meaning


CS_NULL_INPUT The CsVnmParmBlock received by the attached SpectroSERVER was NULL, causing a CsVnmParmBlock error to be returned.

NULL_MESSAGE A valid CsVnmParmblock object was accepted by the interface; but an internal error resulted in no valid response being generated.


CsSYAlarm c lear_alarm_sync ( )


See also:

The VnmParmBlock Reference on CsAlarmRegister, CsAlarmListNode, CsAlarmList, and CsAlarmNode for information on constructing a CsAlarmRegister object and setting its member lists. Also, see the section on CsVnmParmBlock for information on retrieving information from a CsVnmParmBlock.


SUCCESS The alarm was cleared successfully.

Table 36: CsSYAlarm clear_alarm_sync() Error Codes

Error Meaning

CsSYAlarm detach_sync ( )


detach_sync ( )CsVnmParmBlock * detach_sync ( CsWindowId * request ) ;

This method allows the Application to disconnect and no longer receive alarms from SpectroSERVER Alarm Manager. When detach_sync() is called, any unsolicited alarms on the unsolicited alarms list are lost if they have not been copied.

This method returns a pointer to a CsVnmParmBlock object. Check the error code to see if the detach was successful.


See also:

The VnmParmBlock Reference on CsWindowId for more information on constructing a CsWindowId.


request A CsWindowId created from information received by the application when the attach_sync() method was called.

Table 37: CsSYAlarm detach_sync() Error Codes

Error Meaning


CS_NULL_INPUT The CsVnmParmBlock object received by the attached SpectroSERVER was NULL, causing a CsVnmParmBlock error to be returned.

NO_SUCH_WINDOW_ID The referenced window_id was not valid.

SUCCESS Detach was successful.

CsSYAlarm get_unsol_alarms ( )


The VnmParmBlock Reference on CsVnmParmBlock for information on retrieving information from a CsVnmParmBlock.

get_unsol_alarms ( )CsUnsolAlarmList * get_unsol_alarms

( unsigned long wait_time ) ;

This method accepts a waiting time period (wait_time) and attempts to retrieve unsolicited alarm updates from SpectroSERVER. If unsolicited updates have already accumulated, this method simply returns that list and does not wait for the time given. If an unsolicited update occurs while the method is waiting, the method returns that update immediately. If no update occurs within the waiting period, this method returns an empty list.

This method returns a pointer to a CsUnsolAlarmList containing all of the unsolicited alarms.

See also:

VnmParmBlock Reference on CsUnsolAlarmList for more information on retrieving the statistics returned.

replace_filter_sync ( )CsAlarmRegister * replace_filter_sync

( CsAlarmFilterPB * request ) ;


wait_time The amount of time, in milliseconds, to wait before returning if no unsolicited messages are received.


request New alarm filter.

CsSYAlarm update_alarm_sync ( )


This method is used to change the filter that is used to screen the alarms that are sent. It returns a list of all the alarms that pass this filter.

update_alarm_sync ( )CsVnmParmBlock * update_alarm_sync

( CsAlarmRegister * request ) ;

This method is used to change the status of an alarm. The status is an optional character string that provides a textual description of an alarm’s status.

This method returns a pointer to a CsVnmParmBlock. Check the error code to see if the update_alarm was successful.

Table 38 lists the possible CsError return codes.


request A CsAlarmRegister object that is a list of CsAlarmListNode objects, each of which is a list of CsAlarmList objects. Each CsAlarmList object is a list of CsAlarmNode objects (alarms) for a particular model.

Table 38: CsSYAlarm update_alarm_sync() Error Codes

Error Meaning


CS_NULL_INPUT The CsVnmParmBlock received by the attached SpectroSERVER was NULL, causing a CsVnmParmBlock error to be returned.

CsSYAlarm operator = ( )


See also:

The VnmParmBlock Reference on CsAlarmRegister, CsAlarmListNode, CsAlarmList, and CsAlarmNode for information on constructing a CsAlarmRegister and setting its member lists.


operator = ( )CsSYAlarm & operator = ( const CsSYAlarm & right_hand_side ) ;

This method is an assignment operator for the CsSYAlarm class. It deletes the value of the current object and assigns it a reference to the CsSYAlarm object right_hand_side.

NULL_MESSAGE A valid CsVnmParmblock was accepted by the interface; but an internal error resulted in no valid response being generated.



SUCCESS The alarm was updated successfully.



Table 38: CsSYAlarm update_alarm_sync() Error Codes (Continued)

Error Meaning

CsSYEvent operator = ( )


CsSYEvent

Class Hierarchy

Include FileCsSYEvent.h

DescriptionThe CsSYEvent class provides the methods necessary to select the types of events to query, and to scroll up or down the SpectroSERVER database for earlier or later events in time, relative to the current position.

CsSModelAncestor

CsSYLogs

CsSYEvent

Note:Note:

CsSYEvent can now retrieve unsolicited events from SpectroSERVER. This capability is turned off by default. Setting the constructor’s collect_unsol parameter to TRUE will turn on the collection of unsolicited events.



Public Methods

Method Description

CsSYEvent ( ) The class constructor

CsSYEvent ( ) A copy constructor.

attach_sync ( ) Connects to the event manager.

create_event_sync ( ) Creates events.

detach_sync ( ) Disconnects from the event manager.

get_messages_sync ( ) Returns events.

get_unsol_events ( ) Retrieves unsolicited events.

log_message_sync ( ) Records event messages.

replace_filter_sync ( ) Changes the filter used to screen events.

scroll_down_sync ( ) Scroll down an event log database.

scroll_to_bottom_sync ( ) Scroll to the bottom of an event log database.

scroll_to_date_time_sync ( ) Scroll to the first event that matches the date and time specified.

scroll_to_top_sync ( ) Scroll to the top of an event log database.

scroll_up_sync ( ) Scroll up an event log database.

operator = ( ) An overloaded operator.

CsSYEvent CsSYEvent ( )


CsSYEvent ( )CsSYEvent ( CsLscpeHandle my_landscape,


This method constructs a CsSYEvent object that provides a user-level interface to a particular landscape, to perform functions such as selecting the types of events to query, and to scroll up or down the SpectroSERVER database.

See also:

CsLscpeHandle in the VnmParmBlock Reference, and the section on Synchronous SSAPI Distributed SpectroSERVER Programming in the SpectroSERVER API Developer’s Guide.



collect_unsol Determines whether unsolicited events are retained for later retrieval. By default, the collection of unsolicited alarms is turned off. Setting collect_unsol to TRUE will enable the collection of unsolicited events.

CsSYEvent CsSYEvent ( )


CsSYEvent ( )CsSYEvent ( const CsSYEvent & original ) ;

This method is the copy constructor for CsSYEvent. It creates a new CsSYEvent object and copies the value of the original object into it.



CsSYEvent at tach_sync ( )


attach_sync ( )CsAttachResponse * attach_sync ( CsIEventFilter * request ) ;

This method is used to connect to the Event Manager in SpectroSERVER. This must be done before any communication can take place. The CsIEventFilter is used to tell SpectroSERVER what types of events the Application is interested in receiving.

This method returns a pointer to a CsAttachResponse containing the events or error codes and a CsWindowId. This window ID should be saved, because it is needed to detach from SpectroSERVER EventManager.



a Call the CsSYSEvent method unsol_register() and pass it a pointer to an instantiation of a derived class of CsSMailClient.

b Save the response ID from unsol_register().

2 Construct a CsIEventFilter object

a Pass the constructor the response ID returned from unsol_register().


c Pass the constructor a CsIEventFilter object to filter events.

3 Attach to the SCsMailService for Events

a Call the attach_sync() method of CsSYEvent and pass it a pointer to the CsIEventFilter object just constructed.



request A CsIEventFilter object that defines the events to be filtered.

CsSYEvent at tach_sync ( )


See also:

The VnmParmBlock Reference on CsIEventFilter for more information on constructing a CsIEventFilter.

The VnmParmBlock Reference on CsAttachResponse for retrieving information from a CsAttachResponse.

Table 39: CsSYEvent attach_sync Error Codes

Error Meaning

NO_MORE_MESSAGES There are no messages in the event log that are applicable to the filter that was used. If a datetime filter was chosen, then there are no messages that match the filter, the cursor position in the database is beyond the edge of the database, or it is trying to read a message while the cursor is already on the last record. Choose a less limiting filter.

INSUFFICIENT_MEMORY Not enough memory to create the previous, last or the next record read from the database.

NO_SUCH_WINDOW_ID The referenced window ID was not valid. Trying to scroll forward, backward, to the top, to the bottom with an invalid ID. This happens when attach fails for the client or when detach has been called with an invalid ID. The window ID should be obtained from the original attach response, CsAttachResponse using get_log_windowid() after verifying that the response is valid.

CS_NULL_INPUT An invalid attach request was sent for an attach. The request is either not known to the SpectroSERVER Event Manager or it has not been properly configured.

CsSYEvent create_event_sync ( )


create_event_sync ( )CsVnmParmBlock * create_event_sync ( CsIOEventList * request ) ;

This method is used to create events. If the events have alarms associated through EventDisp files, then alarms are also created.


request The list of events to create.

CsSYEvent detach_sync ( )


detach_sync ( )CsVnmParmBlock * detach_sync ( CsILogWindowId * request ) ;

This method is used to disconnect from the EventManager in SpectroSERVER. Once detached, event updates cease. The Application must give the CsILogWindowId object that it received when the CsSYEvent::attach_sync() method was called.

This method returns a pointer to a CsVnmParmBlock, object containing the error code for the detach.

Table 40 lists the CsError error return code.

See also:

The VnmParmBlock Reference on CsILogWindowId for more information on constructing a CsILogWindowId object.

The VnmParmBlock Reference on CsVnmParmBlock for information on retrieving information from a CsVnmParmBlock object.


request The CsILogWindowId object identifying the handle to detach.

Table 40: CsSYAlarm create_event_sync() Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID being used to detach is invalid (there is no client with that ID). Construct the CsILogWindowId object using the WindowId received when the attach_sync() method was called. Then pass the CsILogWindowID to detach_sync().

CsSYEvent get_messages_sync ( )


get_messages_sync ( )CsEventErrorList get_messages_sync

( CsEventIDListBlock * request ) ;

This method returns the events for the given list of IDs.


request The list of event IDs of events you want.

CsSYEvent get_unsol_events ( )


get_unsol_events ( )CsUnsolEventStatList * get_unsol_events


This method accepts a waiting time period (wait_time) and attempts to retrieve unsolicited event updates from SpectroSERVER. If unsolicited updates have already accumulated, this method simply returns that list and does not wait for the time given. If an unsolicited update occurs while the method is waiting, the method returns that update immediately. If no update occurs within the waiting period, this method returns an empty list.

See also:

The VnmParmBlock Reference on CsUnsolEventStatList for more information on retrieving the statistics returned.


wait_time The amount of time, in milliseconds, to wait before returning if no unsolicited messages are received.

CsSYEvent log_message_sync ( )


log_message_sync ( )CsVnmParmBlock * log_message_sync

( CsIOEventList * request ) ;

This method is used to record event messages for a specific model in the SpectroSERVER Event Log database. This method returns a pointer to a CsVnmParmBlock object. Check the error code to see if the request was successful. Table 42 lists possible CsError return codes.


request The list of events being sent.

Table 41: CsSYEvent log_message_sync Error Codes

Code Description

NO_EVENT_MESSAGE_ IN_LIST There was no EventMessage in the CsIOEventList that was passed in. A CsEventNode object was not created for the message to log and consequently it was unable to create a proper CsEventList or CsEventMessage object.

CS_NULL_INPUT The EventList used to construct this IOEventList was corrupted, and as a result, the event nodes corresponding to the event message on the list were not properly configured. This could be the result of an invalid model handle or an improper CsVarData object that carries the event text. Check the EventMessage that was input to ensure that the EventNodes put on the list have the proper values for the type of event message that is being logged in the database. For example, if a user text message is being logged, then the EventType for the Eventnode should be 0x10501. If it is anything else, the EventNode is wrong and therefore also the EventMessage. This further corrupts the CsEventList and CsIOEventList objects.

CsSYEvent log_message_sync ( )


See also:

The VnmParmBlock Reference on CsIOEventList for more information on constructing an IOEventList. Also see the same book for more information on CsEventMessage, CsEventNode, and CsVarData.

The VnmParmBlock Reference on CsVnmParmBlock for information on retrieving information from a VnmParmBlock.

CsSYEvent replace_f i l ter_sync ( )


replace_filter_sync ( )CsScrollResponse * replace_filter_sync

( CsIEventFilter * request ) ;

This method is used to change the filter that used to screen the events that are sent. CsIEventFilter takes the window ID returned from the attach_sync() method as one of its input parameters.

This method returns a pointer to a ScrollResponse. This contains events that have passed the Application’s new filtering criteria.


See also:

The VnmParmBlock Reference on CsIEventFilter for more information on constructing an IEventFilter.

The VnmParmBlock Reference on CsScrollResponse for information on extracting the events.


request The filter information being sent.

Table 42: CsSYEvent replace_filter_sync() Error Codes

Error Meaning

INSUFFICIENT_MEMORY Not enough memory is available to create the new CsIEventFilter when adding filter nodes.

NO_MORE_MESSAGES There are no more messages in the event log that are applicable to the filter. If datetime filters were chosen, then there are no messages that fall between those datetime stamps. In addition, the cursor position in the SpectroSERVER EventLog database is beyond the edge of the database. Choose a less limiting filter.

CsSYEvent scrol l_down_sync ( )


scroll_down_sync ( )CsScrollResponse * scroll_down_sync

( CsILogWindowId * request ) ;

This method is used to scroll down within the SpectroSERVER Event Log database. Scrolling down returns events that occurred later in time, relative to the current position. It takes the window ID returned from the attach_sync() method as one of its input parameters.


See also:

The VnmParmBlock Reference on CsILogWindowId for more information on constructing one.

The VnmParmBlock Reference on CsScrollResponse for more information on retrieving the events returned.


request The window ID of the application making the call.

Table 43: CsSYEvent scroll_down_sync() Error Codes

Error Meaning

NO_MORE_MESSAGES There are no more messages in the event log in the direction of scrolling. The current position is already at the bottom of the event log.


CsSYEvent scrol l_to_bot tom_sync ( )


scroll_to_bottom_sync ( )CsScrollResponse * scroll_to_bottom_sync


This method is used to scroll to the bottom within the SpectroSERVER Event Log database. Scrolling to the bottom returns the latest events in the database to the Application. It takes the window ID returned from the attach_sync() method as one of its input parameters.

Table 44 lists the CsError error return codes.

See also:





Table 44: CsSYEvent scroll_to_bottom_sync() Error Code

Error Meaning


CsSYEvent scrol l_ to_date_t ime_sync ( )


scroll_to_date_time_sync ( )CsScrollResponse * scroll_to_date_time_sync

( CsIDateTime * request ) ;

This method is used to scroll to the first event matching the specified date and time within the SpectroSERVER Event Log database. If there are no matching events, the Application is positioned to the closest event. scroll_to_date_time_sync() takes the window ID returned from the attach_sync() method as one of its input parameters.


See also:

The VnmParmBlock Reference on CsIDateTime for more information on constructing one, and on attribute types for CsIDateTime objects.



request The date and time to be scrolled to.

Table 45: CsSYEvent scroll_to_date_time_sync() Error Code

Error Meaning


CsSYEvent scrol l_ to_top_sync ( )


scroll_to_top_sync ( )CsScrollResponse * scroll_to_top_sync


This method is used to scroll to the top within the SpectroSERVER Event Log database. Scrolling to the top returns the earliest events in the database to the Application. It takes the window ID returned from the attach_sync() method as one of its input parameters.


See also:





Table 46: CsSYEvent scroll_to_top_sync() Error Code

Error Meaning


CsSYEvent scrol l_up_sync ( )


scroll_up_sync ( )CsScrollResponse * scroll_up_sync ( CsILogWindowId * request ) ;

This method is used to scroll up within the SpectroSERVER Event Log database. Scrolling up returns events that occurred earlier in time, relative to the current position. scroll_up_sync() uses the window ID returned from the attach_sync() method as input.


See also:





Table 47: CsSYEvent scroll_up_sync() Error Codes

Error Meaning

NO_MORE_MESSAGES There are no more messages in the event log in the direction of scrolling. The current position is already at the top of the event log.

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. The window ID should be obtained from the original CsAttachResponse object using get_log_windowid(), after verifying that the response is valid.



operator = ( )CsSYEvent & operator = ( const CsSYEvent & right_hand_side ) ;

This method is an assignment operator for the CsSYEvent class. It deletes the value of the current object and assigns it a reference to the CsSYEvent right_hand_side.



CsSYGlobalScapeHandle operator = ( )


CsSYGlobalScapeHandle

Class Hierarchy

Include FileCsSYGScHndl.h

DescriptionCsSYGlobalScapeHandle contains methods that provide a global view across all landscapes known to a SpectroSERVER. It provides a client with the ability to issue requests that will result in searching the global landscapes to provide the requested information, using a CsFindSpec object to determine the search criteria.

CsSYGlobalScapeHandle uses a CsMailClient object to perform the searches. The CsMailClient object issues the specified number of requests, and when responses are received for the original requests, the CsMailClient object issues additional requests until all appropriate landscapes have been searched.

When all responses have been received, the application requesting the information is notified through its CsMailClient’s Notify() method to retrieve the response to its find request. This response contains all the responses from all landscapes matching the CsFindSpec criteria.

If the number of landscapes in the landscape map exceeds the num_landscapes_per_search parameter passed to the constructor, additional requests are issued, as responses to outstanding requests are received. This process continues until the search is complete, but the number of outstanding requests never exceeds the number passed for the num_landscapes_per_search parameter.

CsSModelAncestor

CsSYGlobalScapeHandle



For example, if the landscape map contains 25 landscapes, and the constructor is passed a parameter to search only 5 at a time, 5 requests are sent, and as the responses are received, additional requests are sent until all 25 landscapes in the map have been queried. But no more than 5 requests are outstanding at a given time. When all responses have been received, the client requesting the information is notified.

The find_first_sync() method, however, works differently from the find_all_sync(). It returns as soon as a successful match is found, even if all landscapes have not yet been queried. The search is considered complete at that time and the client is notified even if there are outstanding requests and/or all landscapes have not been searched.

After instantiating an object of this class, a client needs to build a CsVnmParmblock object containing a CsFindSpec specification that describes the desired information. This CsFindSpec object is then passed to the appropriate find() method.

The following is an example of how a client application can initiate a search using the CsSYGlobalScapeHandle:

Create the CsSYGlobalScapeHandle object:

CsTulong num_landscapes = 5;

global_scape = new CsSYGlobalScapeHandle( num_landscapes ) ;

Set up a CsFindSpec object for all model types named Pingable:

char * name = “Pingable”;

CsBuffer * buff = new ( name, (int) 0 ) CsBuffer ;

CsFindSpec * spec = new CsFindSpec(CsCoreAttrIds::MTYPE_NAME,buff,CsAttrDesc::TEXT_STRING ) ;

Issue request

CsModelDescList * mdesclist = global_scape-> find_first_sync( spec ) ;

The response ID returned from initiator calls indicates if errors prevented a successful search from being initiated. A response ID of -1 may indicate that the response queue is full or that a search is already in progress. The



model description list may also contain an error indicating that a search request was unsuccessful. The get_error() method of the returned object should be used to determine if an error has occurred.

See also:

For more information on classes related to CsSYGlobalScapeHandle, refer to:

• CsHndlAnces.h for the current value of QUE_DEPTH.

• CsFindSpec.h for a description of the FindSpec used in the search.

• CsMDList.h for a description of the CsModelDescList parameter block.

• CsLHList.h for a description of the CsLscpeHandleList containing landscapes that were searched successfully.

• CsLHErrList.h for a description of the CsLHErrorList containing landscapes and error codes for landscapes that failed the search.

Caution:Caution:

The CsSYGlobalScapeHandle should not be reused until an initiated search has completed and the information is retrieved. If multiple simultaneous searches are desired, a new CsSYGlobalScapeHandle object should be created for each search.

Note:Note:

Errors for connections to individual landscapes are returned in the CsLHErrorList by the get_failed_landscapes() method.

CsSYGlobalScapeHandle CsSYGlobalScapeHandle ( )


Public Methods

CsSYGlobalScapeHandle ( )CsSYGlobalScapeHandle

( CsTulong num_landscapes_per_search = QUE_DEPTH ) ;

This is the class constructor. It takes as input the number of landscapes to be searched, which can limit the load generated by the searches. If it is not passed or is 0, it defaults to QUE_DEPTH, which is currently 10. If a larger number than QUE_DEPTH is passed, it also defaults to QUE_DEPTH.

Method Description

CsSYGlobalScapeHandle ( ) The class constructor.

CsSYGlobalScapeHandle ( ) Copy constructor.

find_all_sync ( ) Searches for specified models.

find_first_sync ( ) Finds first occurrence of a specified model.

get_failed_landscapes ( ) List of landscapes not successfully searched.

get_successful_landscapes ( ) List of landscapes successfully searched.



num_landscapes_per_search The window ID of the application making the call.

CsSYGlobalScapeHandle CsSYGlobalScapeHandle ( )


CsSYGlobalScapeHandle ( )CsSYGlobalScapeHandle

( const CsSYGlobalScapeHandle & original ) ;

This is the copy constructor.

find_all_sync ( )CsModelDescList * find_all_sync ( CsFindSpec * what ) ;

This method is used to initiate a search across landscapes for all models with the specified characteristics. This method takes a pointer to an object that describes “what to find” and a pointer to the client making the request. It returns a pointer to a model description list. The client application is responsible for deleting the returned list.




what The CsFindSpec object that defines the search.

CsSYGlobalScapeHandle f ind_f i rst_sync ( )


find_first_sync ( )CsModelDescList * find_first_sync ( CsFindSpec * what ) ;

This method is used to initiate a landscape-wide search for the first occurrence of a model with the specified characteristics. This method takes a pointer to a CsFindSpec, which describes what to find, and a pointer to the client making the request. It returns a pointer to a model description list. The client application is responsible for deleting the returned list.

get_failed_landscapes ( )CsLHErrorList * get_failed_landscapes ( void ) ;

This method returns the list of landscapes that were not successfully searched in the previous search request, along with the reason. The client application is responsible for deleting the returned list.

get_successful_landscapes ( )CsLscpeHandleList * get_successful_landscapes ( void ) ;

This method returns the list of landscapes that were searched successfully in the previous search request. The client application is responsible for deleting the returned list.


what The CsFindSpec object that defines the search.

Caution:Caution:

The caller is responsible for deleting memory allocated to the CsLHErrorList object returned by get_failed_landscapes().

Caution:Caution:

The caller is responsible for deleting memory allocated to the CsLscpeHandleList object returned by get_successful_landscapes().



operator = ( )CsSYGlobalScapeHandle & operator =

( const CsSYGlobalScapeHandle & right_hand_side ) ;

The class assignment operator.



CsSYLandScapeHandle operator = ( )


CsSYLandScapeHandle

Class Hierarchy

Include FileCsSYLscHnd.h

DescriptionThe CsSYLandScapeHandle class provides methods which can be used to find information on models and aspects within a Landscape.

CsSModelAncestor

CsSHandleAncestor

CsSYLandScapeHandle

CsSYLandScapeHandle CsSYLandScapeHandle ( )


Public Methods

CsSYLandScapeHandle ( )CsSYLandScapeHandle ( CsLscpeHandle my_landscape ) ;

This method constructs a CsSYLandScapeHandle object that provides a user-level interface to services such as find and describe.

See also:

The VnmParmBlock Reference on CsLscpeHandle for more information.

Method Description

CsSYLandScapeHandle ( ) The class constructor.

CsSYLandScapeHandle ( ) A copy constructor.

describe_sync ( ) Retrieves Landscape specifics.

find_sync ( ) Finds models in landscape.

model_permission_sync ( ) Filters a CsPermissionsList.

operator = ( ) An overloaded operator.


my_landscape A CsLscpeHandle object that identifies a landscape in SpectroSERVER. Because multiple landscapes can be accessed from a single application, it is important to specify a landscape when using this constructor.

Caution:Caution:

Do not use a null or default landscape handle with this constructor. To access models in a specific landscape, use the methods of CsSYVLMapHandle to get information from the VMN/Landscape Map about the available landscapes, then create a CsSYLandScapeHandle object to access the appropriate landscape.

CsSYLandScapeHandle CsSYLandScapeHandle ( )


CsSYLandScapeHandle ( )CsSYLandScapeHandle ( const CsSYLandScapeHandle & original ) ;

This is the copy constructor for CsSYLandScapeHandle. This method creates a new CsSYLandScapeHandle object and copies the value of the original object into it.



CsSYLandScapeHandle descr ibe_sync ( )


describe_sync ( )CsVnmParmBlock * describe_sync ( CsAspect * request ) ;

This method is used to get a description of different aspects of the Landscape specified in the constructor. The aspect to be described is specified in the input to the method, the Aspect, by setting CsAspect::aspect to the desired value. Currently, a description can be requested of one of five aspects of the landscape listed in Table 48:

Filters can be applied to all except CS_ASPECT_MTYPES, by setting CsAspect::sub_aspect to the desired value. Currently, the following subaspect filters, listed in Table 49, can be applied:


request The CsAspect object containing the search information.

Table 48: describe_sync() Landscape Aspects

Aspect Description

CS_ASPECT_MODEL_COUNT Counts all models in the landscape.

CS_ASPECT_MTYPES Describes all model types in the landscape.

CS_ASPECT_MODELS Describes all models in the landscape.

CS_ASPECT_ATTRS Describes all attributes of the model type.

CS_ASPECT_RELS Describes all relations in the landscape.

CS_ASPECT_ENUM Describes all the enumerations in the landscape.




Table 49: describe_sync() Aspect Filter Types


TYPE Only models, attributes, or relations of the type, specified in CsAspect::detail are counted.

SPECIFIC Only models, attributes, or relations specified in CsAspect::detail are described.


OR_FLAGS Only attributes with any of the specified flags set are described.

Table 50: describe_sync() Aspect Filters

ASPECT ALL SPECIFIC TYPE AND_FLAGS

OR_FLAGS

CS_ASPECT_MODEL_COUNT XX

CS_ASPECT_MTYPES X

CS_ASPECT_MODELS X X X



CS_ASPECT_ENUM X

Note:Note:

The subscriber must cast the pointer returned by the retriever to a pointer to the appropriate class. The following shows the casting that must be done for each aspect: CsAspectCount * port_model_count = ( CsAspectCount * ) Landscape.describe_sync( port_model_count ) ;



See also:

The VnmParmBlock Reference section on CsAspect for more information on constructing an Aspect and on setting its aspect, sub_aspect, and detail members. Also see the sections on CsAspectCount, CsModelDescList, CsRelDescList, and CsAttrDescList for information on retrieving the information returned, and the sections on CsModelDesc, CsRelDesc, and CsAttrDesc for information on the model descriptor, the relation descriptor, and the attribute descriptor.

CsSYLandScapeHandle f ind_sync ( )


find_sync ( )CsModelDescList * find_sync ( CsFindSpec * request ) ;

This method is used to find models in the landscape that have an attribute with a certain value. This attribute is specified by its ID, value and type in the input to the method.

If the attribute is not a SHARED attribute, the landscape is searched for models that have an attribute that matches the ID, type and value in the CsFindSpec object. However, if the attribute is SHARED, the landscape is searched for all models that share this attribute (models of a particular model type), and that have an attribute that matches the ID, type and value in the FindSpec

This method returns A CsModelDescList, which is a list of all the CsExpModelDesc objects that were found.

See also:

The VnmParmBlock Reference on CsFindSpec for more information on constructing a CsFindSpec object and on setting its members.

The VnmParmBlock Reference on CsModelDescList and CsExpModelDesc for more information on retrieving the information returned.


request The CsFindSpec object that defines the search.

CsSYLandScapeHandle model_permission_sync ( )


model_permission_sync ( )CsPermissionList * model_permission_sync

( CsPermissionList * request ) ;

This method is used to make a synchronous request to filter a CsPermissionList based on model permissions. The request is formed using the CsPermissionList::add_tail() method to supply the list of model handles to be scrutinized. CsPermissionList::set_access_level() allows the requestor to specify what access level the user needs for a model to be in the response.

CsPermissionList::set_user_mh() allows a requestor with ADMIN permission to specify which user’s permissions to check (the default is the connecting user).

The response can be examined by using the methods CsPermissionList::get_head() and CsPermissionList::get_next() to get the list of model handles which the user from CsPermissionList::get_user_mh() has access to at the level CsPermissionList::get_access_level() returns. The returned list is a subset of the list passed to model_permission_sync().

This method returns a CsPermission list object which contains only the allowed models.


request The CsPermissionList defining the permissions to compare against.

CsSYLandScapeHandle xmult i_model_request_sync ( )


xmulti_model_request_sync ( )CsModelActionList * multi_model_request_sync

( CsModelActionList * request ) ;

_

This method allows a user to apply actions to multiple models. A list of model/action combinations are used as input. The user is returned a list of expanded model descriptors. Each descriptor can be checked for an error to determine if the action was successful for that particular model. Do not access the pointer after calling this method.

multi_mtype_request_sync ( )CsModelActionList * multi_mtype_request_sync

( CsMTypeActionList * request ) ;

This method allows you to apply one action to multiple model types. You supply the “action enumeration” and a list of model type handles and are returned a list of model actions. Each action can be checked for an error to determine if that action was successful for that particular model type. Do not access the pointer after calling this method.


request The CsModelActionList defining the actions and models.


request The CsModelTypeActionList defining the action and model types.


CsSYLandScapeHandle operator = ( )


operator = ( )CsSYLandScapeHandle & operator =

( const CsSYLandScapeHandle & right_hand_side ) ;

This assignment operator for the CsSYLandScapeHandle class deletes the value of the current object and assigns it a reference to the CsSYLandScapeHandle object right_hand_side.



CsSYModelHandle operator = ( )


CsSYModelHandle

Class Hierarchy

Include FileCsSYMdlHnd.h

DescriptionThe methods of the CsSYModelHandle class provide access to models in a SpectroSERVER Landscape, using the model handle to identify the models.

CsModelAncestor

CsSHandleAncestor

CsSYModelHandle

CsSYModelHandle operator = ( )


Public Methods

Method Description

CsSYModelHandle ( ) The class constructor.

CsSYModelHandle ( ) A copy constructor.

action_sync ( ) Performs a user defined action.

check_permission_sync ( ) Returns TRUE if a connection is available.

describe_rels_sync ( ) Retrieves description of model relations.

describe_sync ( ) Retrieves description of model aspects.

destroy_sync ( ) Removes a model from the landscape.

find_attr_by_oid_sync ( ) Allows the caller to find attributes.

lock_sync ( ) Locks a given model.

read2_sync ( ) Reads a models attributes. (New)

read_sync ( ) Reads a models attributes. (Old)

read_next_sync ( ) Used to traverse an EXTERNAL, LIST type attribute

test_lock_sync ( ) Tests whether a model is locked.

unlock_sync ( ) Removes a lock from a previously locked model.

write2_sync ( ) Modifies a model’s attribute values. (New)

write_sync ( ) Modifies a model’s attribute values. (Old)


CsSYModelHandle CsSYModelHandle ( )


CsSYModelHandle ( )CsSYModelHandle ( CsModelHandle my_model ) ;

This method constructs a CsSYModelHandle that provides a user-level interface to services such as read, write, describe, and destroy.

See also:

CsModelHandle in the VnmParmBlock Reference for more information on model handles.

CsSYModelHandle ( )CsSYModelHandle ( const CsSYModelHandle & original ) ;

This method is the copy constructor for CsSYModelHandle. This method creates a new CsSYModelHandle and copies the value of the original object into it.


my_model A CsModelHandle object that identifies a model in a Landscape.

Caution:Caution:

When a handle is created, a connection to a SpectroSERVER Landscape is also created through the CsSMailService object. This connection persists until the handle is destroyed, and each connection left open will affect performance. For this reason, handles should be created, used, and destroyed as needed, rather than created, held open for the duration of the program, and destroyed at program completion.



CsSYModelHandle act ion_sync ( )


action_sync ( )CsVnmParmBlock * action_sync ( CsAction * request ) ;

This method is used to perform a user-defined action or function. This method is specified in the CsAction object that is an input to the method. All actions are performed by the inference handlers attached to the model. The action codes and the inference handlers that perform them are defined by the Application.

This method returns a pointer to a CsVnmParmBlock object that indicates whether the action was successful or not.

See also:

The VnmParmBlock Reference on CsAction for more information on constructing one and setting its members.


The Inference Handler API Developer’s Guide for more information on actions that can be performed by inference handlers.


request The action being sent.

CsSYModelHandle check_permission_sync ( )


check_permission_sync ( )CsSecPerm * check_permission_sync ( CsSecPerm * request ) ;

This method is used to check the requestor’s permission to this model and its attributes. The requestor needs to construct a VnmParmBlock ( in this case a CsSecPerm object) and pass it to check_permission_sync(). The CsSecPerm object allows you to check the permissions of the model and its attributes, which is simply an indexed list of attribute IDs. The check_permission_sync() method gets the permissions of the model and its attributes, pointed to by the CsSYModelHandle, and returns a pointer to a CsSecPerm that contains the response. CsSecPerm::get_access_response() is called to return the access permission of the model encoded as an integer. CsSecPerm defines the enum CsAlowedAction_e for READ, WRITE, and NONE to represent these cases. A value is returned for the model and one for each specified attribute. CsAllowedActions_e values are:

• WRITE = 4• READ = 9• NONE = 14

See also:

The VnmParmBlock Reference CsSecPerm for more information on constructing a CsSecPerm object.


request A CsSecPerm object that contains the specified attributes for the request.

CsSYModelHandle descr ibe_rels_sync ( )


describe_rels_sync ( )CsRelDescList * describe_rels_sync ( CsAspect * request ) ;

This method is used to get a description of different relations in which a model participates. The relation to be described is specified as a parameter in the input to the Aspect, by setting CsAspect::aspect to the desired value. Currently, a description can be requested of the relations in which the model is participating, by setting the CsAspect::aspect to CsAspect::CS_ASPECT_RELS.

Filters for the relations can be applied for each aspect by setting CsAspect::sub_aspect to the desired value. Table 51 lists the subaspect filters that can be applied:



request The CsAspect object used in the search.

Table 51: CsSYModelHandle describe_rels_sync() Subaspects


ALL Does not filter on anything, no details required.



CsSYModelHandle descr ibe_rels_sync ( )


See also:

The VnmParmBlock Reference section on CsAspect for more information on constructing an Aspect and on setting its aspect, sub_aspect, and detail members. Also refer to the section on CsRelDescList on retrieving the information returned, and the section on CsRelDesc for information on a relation descriptor.

Table 52: CsSYModelHandle describe_rels_sync() Aspect Filters

ASPECT ALL SPECIFIC TYPE

CS_ASPECT-RELS X X X

CsSYModelHandle descr ibe_sync ( )



This method is used to get a description of different aspects of a model. The aspect to be described is specified as a parameter in the input to describe_sync() by setting “CsAspect::aspect” to the desired value. Currently, a description of the relations in which the model is participating can be requested by setting the CsAspect::aspect to CsAspect::CS_ASPECT_RELS.

This method returns a pointer to a CsVnmParmBlock object that contains a list of descriptors of relations. The returned CsVnmParmBlock object must be cast to CsRelDescList.

Filters can be applied for each aspect by setting CsAspect::sub_aspect to the desired value. Table 53 lists the subaspect filters that can be applied:




Table 53: CsSYModelHandle describe_sync() Subaspects





CsSYModelHandle descr ibe_sync ( )


See also:

The VnmParmBlock Reference section on CsAspect for more information on constructing a CsAspect and on setting its aspect, sub_aspect, and detail members.

Also refer to the section on CsRelDescList to see how to retrieve the information returned, and the section on CsRelDesc for information on a relation descriptor.

Table 54: CsSYModelHandle describe_sync() Aspect Filters

ASPECT ALL SPECIFIC TYPE


CsSYModelHandle destroy_sync ( )


destroy_sync ( )CsVnmParmBlock * destroy_sync ( void ) ;

This method is used to remove a model from the landscape. The model is removed from all the relations that associate it to other models, and all its memory is reclaimed. However, none of the statistics and events pertaining to the model are removed from the respective logs. An event (CS_EVENT_MODEL_DESTROYED) is generated, indicating the destruction of the model.

This method returns a pointer to a CsVnmParmBlock object that indicates whether the model was destroyed. An error code of CsError::SUCCESS indicates that the model was successfully destroyed.

See also:


The Inference Handler API Developer’s Guide for more information about the effects of model destruction on inference handlers.

find_attr_by_oid_sync ( )CsFullAttrDescList * find_attr_by_oid_sync

( CsFindByOID * what ) ;

This method allows the caller to find attributes for the given object identifiers.



CsSYModelHandle lock_sync ( )


lock_sync ( )CsVnmParmBlock * lock_sync ( void ) ;

This method is used to lock a model to warn others, attempting to edit a model, that the model is in use. Only users, not inference handlers, can lock a model. A model can have only one lock at a time.

This method returns a pointer to a CsVnmParmBlock that indicates whether the model was successfully locked.


See also:

The VnmParmBlock Reference on CsVnmParmBlock for more information on retrieving information from a CsVnmParmBlock object.

Caution:Caution:

Database corruption can occur if model locking is ignored. The locking mechanism maintained by SpectroSERVER is advisory. That is, it is the application’s responsibility to test the lock for the model before editing. If the test_ lock_sync() indicates a locked model, the model is currently under edit by another user and should not be edited.

Table 55: CsSYModelHandle lock_sync() Error Codes

Error Meaning

ALREADY_LOCKED The model is locked, and should not be edited.

NOT_LOCKED The model is not locked, and can be edited.

CsSYModelHandle read2_sync ( )


read2_sync ( )CsAttrValRspList * read_sync ( CsAttrReadReqList * request ) ;

This method reads the attributes of a model, and may be used to read any type of attribute including internal list attributes. The user must construct a CsAttrReadReqList which will contain the id’s of the attributes to be read.

See also: The VnmParmBlock Reference for more information on constructing, setting, and retrieving information from CsAttrReadReqList and CsAttrValRspList objects.


request The CsAttrReadReqList object defining the attributes to be read

Note:Note:

This method replaces the CsSYModelHandle read_sync() and read_next_sync() methods.

CsSYModelHandle read_sync ( )


read_sync ( )CsAttrValList * read_sync ( CsAttrValList * request ) ;

This method is used for reading the values of attributes of a model. The attributes that are to be read are listed only by their IDs in the CsAttrValList object which is an input to this method.

This method returns a pointer to a CsAttrValList object containing the appropriate values or error codes.

If an OID suffix was supplied with the request, the OID suffix is returned with the value.


request The CsAttrValList object defining the attributes to be read.

Note:Note:

An overall error code is set in the CsVnmParmBlock object. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it can indicate a difficulty reading one or more attributes and each error code must be examined on an attribute-by-attribute basis. Error codes for individual attributes are significant only to that attribute. If a particular attribute value was not READABLE for some reason, an error code is set for that attribute, specifying the error, and the value for that attribute is set to NULL.An attribute value is valid only when the error code for that attribute is CsError::SUCCESS. Any other error code indicates an error while reading the associated attribute.

Note:Note:

Beginning with SPECTRUM 5.0, this method has been replaced with the read2_sync() method.Pay special attention to the object ID of attributes for SNMP (or other equivalent management protocols) managed devices. Observe the proper use of OID suffixes (instance IDs) when reading EXTERNAL-LIST type attributes. If an OID suffix is omitted when one is required, an error code is returned for that particular attribute and its value is set to NULL.

CsSYModelHandle read_sync ( )


See also:

The VnmParmBlock Reference for more information on CsAttrValList, constructing an AttrValList, and also on setting and retrieving information from one. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.

CsSYModelHandle read_next_sync ( )


read_next_sync ( )CsAttrValList * read_next_sync ( CsAttrValList * request ) ;

This method is applicable only to attributes that are EXTERNAL and LIST. It is used to traverse an EXTERNAL, LIST type attribute. The particular attribute that is read by this method is determined by an OID suffix (instance ID) specified in the input to the method. The read_next_sync() operation is similar to the get_next primitive of the SNMP protocol.

This method returns a pointer to an AttrValList containing the appropriate values and OID suffixes or error codes.

If no OID suffix was supplied with a request, the attribute value of the first entry for that OID is returned along with its OID suffix.

If a partial OID suffix was supplied with a request, the remainder of the OID suffix is treated as NULL and the attribute value for the next entry for that OID is returned along with its OID suffix.

If a complete OID suffix was supplied with a request, the attribute value for the next entry for that OID is returned along with its OID suffix.



CsSYModelHandle read_next_sync ( )


See also:

The section in the VnmParmBlock Reference on CsAttrValList for more information on constructing an AttrValList, and on setting and retrieving information from one. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.

Use the Model Type Editor to get more information about the MIB for the device that is represented by this model.

Note:Note:

An overall error code is set in the returned VnmParmBlock. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it can indicate a difficulty reading some attributes and each error code must be examined individually. Error codes for individual attributes are significant only for that attribute. If a particular attribute value was not READABLE for some reason, an error code is set for that attribute, specifying the error, and the value for that attribute is set to NULL.An attribute value is valid only when the error code for that attribute is CsError::SUCCESS. Any other error code indicates an error while reading the associated attribute.

Note:Note:

Beginning with SPECTRUM 5.0, this method has been replaced with the read2_sync() method.Pay special attention to the object ID of attributes for SNMP (or other equivalent management protocols) managed devices. Observe the proper use of OID suffixes (instance IDs) when reading EXTERNAL-LIST type attributes. If an OID suffix is omitted when one is required, an error code is returned for that particular attribute and its value is set to NULL.

CsSYModelHandle test_ lock_sync ( )


test_lock_sync ( )CsVnmParmBlock * test_lock_sync ( void ) ;

This method checks a pointer to a CsVnmParmBlock object that indicates whether the model is locked.

See also:


unlock_sync ( )CsVnmParmBlock * unlock_sync ( void ) ;

This method is used to remove a lock from a previously locked model. A model’s lock can be removed only by the user that locked it. Attempting to unlock a model that was not locked previously returns an error.

This method returns a pointer to a CsVnmParmBlock object that indicates whether the model was successfully unlocked or not.

See also:


Caution:Caution:

Database corruption can occur if model locking is ignored. It is the application’s responsibility to test the lock for the model before editing. If the test_ lock_sync() indicates a locked model, the model is currently under edit by another user and should not be edited

CsSYModelHandle wr i te2_sync ( )


write2_sync ( )CsAttrValRspList * write2_sync

( CsAttrWriteReqList * request ) ;

This method is used when attributes of a model are to be modified and may be used to modify all types of attributes including internal list attributes. The attributes of the model that are to be modified are specified in the input to the initiator, the CsAttrWriteReqList object. The attributes are specified by their IDs, types, and values.

See also: The VnmParmBlock Reference for more information on constructing, setting, and retrieving information from CsAttrWriteReqList and CsAttrValRspList objects.


request The CsAttrWriteRequestList object defining the attributes to be written

Note:Note:

Beginning with SPECTRUM 5.0, this method replaces the write_sync() method.

CsSYModelHandle wr i te_sync ( )


write_sync ( )CsAttrValList * write_sync ( CsAttrValList * request ) ;

This method is used when attributes of a model are to be modified. The attributes that are to be modified are specified by their IDs, types, and values in the input to the method, an CsAttrValList.

This method returns a pointer to an CsAttrValList containing the appropriate error codes. An error code of CsError::SUCCESS indicates the attribute was successfully modified. If an attribute could not be modified for some reason (e.g., it was not WRITABLE), the error code for that particular attribute specifies the reason for the error.

operator = ( )CsSYModelHandle & operator =

( const CsSYModelHandle & right_hand_side ) ;

This method is an assignment operator for the CsSYModelHandle class. It deletes the value of the current object and assigns it a reference to the CsSYModelHandle right_hand_side.


request The CsAttrValList object defining the attributes to be written.

Note:Note:

Beginning with SPECTRUM 5.0, this method has been replaced by the write2_sync() method.



CsSYModelTypeHandle operator = ( )


CsSYModelTypeHandle

Class Hierarchy

Include FileCsSYMTHnd.h

DescriptionThe CsSYModelTypeHandle class provides access to model types in the SPECTRUM knowledge base by means of the model type handle.

CsSModelAncestor

CsSHandleAncestor

CsSYModelTypeHandle



Public Methods

Method Description

CsSYModelTypeHandle ( ) Class constructor.

CsSYModelTypeHandle ( ) Copy constructor.

create_sync ( ) Used when a new model of this model type is to be created in the Landscape specified by the constructor.

describe_sync ( ) Retrieves a description of different aspects of a model type.

find_attr_by_oid_sync ( ) Finds attributes for the given object identifiers.

is_derived_from_sync ( ) Checks if this model type is derived from the model type given in the parm block.

read_sync ( ) Reads attributes of a given model type.

write_sync ( ) Modifies attributes of a given model type.


CsSYModelTypeHandle CsSYModelTypeHandle ( )


CsSYModelTypeHandle ( )CsSYModelTypeHandle

( CsMTypeHandle my_type, CsLscpeHandle my_landscape ) ;

This method constructs a CsSYModelTypeHandle that provides a user-level interface to model types. This access allows creating models of a model type, modifying attributes of a model type, and describing model types.

See also:

The VnmParmBlock Reference on CsMTypeHandle for more information.

CsSYModelTypeHandle ( )CsSYModelTypeHandle ( const CsSYModelTypeHandle & original ) ;

This method is the copy constructor for CsSYModelTypeHandle. This method creates a new CsSYModelTypeHandle object and copies the value of the original object into it.


my_type A CsMTypeHandle that identifies a model type in SpectroSERVER.

my_landscape A CsLscpeHandle object that identifies a landscape in SpectroSERVER. Because multiple landscapes can be accessed from a single application, it is important to specify a Landscape when using this constructor.



CsSYModelTypeHandle create_sync ( )


create_sync ( )CsAttrValList * create_sync ( CsAttrValList * request ) ;

This method is used when a new model of this model type is to be created in the Landscape specified by the constructor. The attributes of the model that are to be initialized are specified in the input to the method, the CsAttrValList. The attributes are specified by their IDs, types, and values.

This method returns a pointer to a CsAttrValList containing the handle of the newly created model. Also, for each attribute that was to be initialized, an error code indicates the result of the initialization. An error code of CsError::SUCCESS indicates that the attribute was successfully initialized. If an attribute could not be initialized for some reason, (e.g., it was not WRITABLE) the error code for that attribute specifies the reason for the error (in addition to the overall CsError code).

See also:

The VnmParmBlock Reference on CsAttrValList for more information on constructing a CsAttrValList, and on setting and retrieving information from one.


request The CsAttrValList object defining the attributes to be updated on model creation.

Note:Note:

An overall error code is set in the CsVnmParmBlock object. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it can indicate difficulty setting a particular item. Each error code must be examined individually.

CsSYModelTypeHandle descr ibe_sync ( )


describe_sync ( )CsAspectCount * describe_sync ( CsAspect * request ) ;

This method is used to get a description of different aspects of a model type. The aspect to be described is specified in the input to the method, the CsAspect object, by setting CsAspect::aspect to the desired value. A description can be requested of one of seven aspects of a model type. These aspects are listed in Table 56.

This method returns a pointer to a CsAspectCount. Depending on the aspect that was to be described, this CsAspectCount object contains a list of descriptors of various things, such as: attributes, model types, etc. Type casting to the appropriate list type is mandatory.

Filters can be applied for some aspects by setting CsAspect::sub_aspect to the desired value. Currently, subaspect filtering can be applied to three aspects, “CsAspect::CS_ASPECT_ATTRS,” “CsAspect::CS_ASPECT_FULL_ATTRS,” and “CsAspect::CS_ASPECT_GROUPS.”

The filters supported are listed in Table 57:



Table 56: Model Type Aspects

Aspect Description Class

CS_ASPECT_ATTRS Describes all the attributes of the model type.

CsAttrDescList

CS_ASPECT_ATTR_COUNT Counts all the attributes of the model type.

CsAspectCount



CS_ASPECT_FULL_ATTRS Describes all the attributes of the model type fully -- including the extensions of the descriptors.

CsFullAttrDescList

CS_ASPECT_SELF Describes the model type itself.

CsMTypeDescList

CS_ASPECT_BASE_MTYPES Describes the model types from which this model type is derived.

CsMTyoeDescList


Describes the model types that have been derived from this model type.

CsMTypeDescList

CS_ASPECT_GROUPS Describes the attributes of a specific group of model types.

CsAttrGroupList

CS_ASPECT_ENUMS Describes the enumerations of a model type.

CsEnumBlkList

Table 57: Subaspect filters for Model Type Aspects



SPECIFIC Only attributes with attribute IDs that match the attribute IDs specified in CsAspect::detail are described.

Table 56: Model Type Aspects (Continued)

Aspect Description Class




Table 59 lists the descriptors returned for the different aspects:

SPECIFIC_GROUP Describes specific attributes by group.

TYPE Only attributes of the type that match the types specified in CsAspect::detail are described.

AND_FLAGS Only attributes with all of the specified flags are described.

OR_FLAGS Only attributes with any of the specified flags are described.

Table 58: Model Type Aspect Filters

ASPECT ALL SPECIFIC SPECIFIC GROUP TYPE AND_

FLAGSOR_

FLAGS


CS_ASPECT_COUNT X

CS_ASPECT_FULL_ATTRS X X X X X X

CS_ASPECT_SELF X

CS_ASPECT_BASE_MTYPES

X


X

CS_ASPECT_GROUPS

X X X X X

CS_ASPECT_ENUMS X X

Table 57: Subaspect filters for Model Type Aspects




See also:

The section on CsAspect in the VnmParmBlock Reference for more information on constructing a CsAspect object and on setting its aspect, sub_aspect, and detail members. Also see the sections on CsAspectCount, CsAttrDescList, CsFullAttrDescList, and CsMTypeDescList for information on retrieving the information returned, and the sections on CsAttrDesc, CsFullAttrDesc, and CsMTypeDesc for information on the attribute descriptor, the full attribute descriptor, and the model type descriptor.

Table 59: Aspect Descriptions

Aspect Class


CS_ASPECT_SELF: CsMTypeDescList

CS_ASPECT_BASE_MTYPES: CsMTypeDescList

CS_ASPECT_DERIVED_MTYPES: CsMTypeDescList

CS_ASPECT_ATTRS: CsAttrDescList

CS_ASPECT_FULL_ATTRS: CsFullAttrDescList

CS_ASPECT_GROUPS: CsAttrGroupList

CS_ASPECT_ENUMS CsEnumBlkList

CsSYModelTypeHandle f ind_at tr_by_oid_sync ( )


find_attr_by_oid_sync ( )CsFullAttrDescList * find_attr_by_oid_sync

( CsFindByOID * what ) ;

This method allows the caller to find attributes for the given object identifiers.

is_derived_from_sync ( )CsVnmParmBlock * is_derived_from_sync

( CsMTypeHandlePB * what ) ;

This method checks if this model type is derived from the model type given in the parm block.


what The OID’s to be searched for.


what Model type to be compared with.

CsSYModelTypeHandle read_sync ( )


read_sync ( )CsAttrValList * read_sync ( CsAttrValList * request ) ;

This method is used to read default or shared values of attributes of a model type in the Landscape specified by the constructor. The attributes to be read are specified only by their attribute IDs in the input to the method, a CsAttrValList object. Attribute type and value, if provided as input, are ignored.

A pointer to an CsAttrValList object containing the appropriate values or error codes. If an individual attribute could not be read for some reason (for example, it was not READABLE), an error code is set for that attribute, specifying the reason for the error, and the value for that attribute is set to NULL. The value of an attribute is meaningful only if the error code for that attribute is CsError::SUCCESS.

See also:

The VnmParmBlock Reference on CsAttrValList for more information on constructing a CsAttrValList, object and also on setting and retrieving information from one. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.



Note:Note:

An overall error code is set in the CsVnmParmBlock object. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it can indicate difficulty reading a particular item. Each error code must be examined individually.

CsSYModelTypeHandle wr i te_sync ( )


write_sync ( )CsAttrValList * write_sync ( CsAttrValList * request ) ;

This method is used to modify attributes of a model type in the Landscape specified by the constructor. The attributes of the model type that are to be modified are specified in the input to the method. The attributes are specified by their IDs, types, and values.

This method return a pointer to a CsAttrValList object containing the appropriate error codes. An error code of CsError::SUCCESS indicates the attribute was successfully modified. If an attribute could not be modified for some reason (e.g., it was not WRITABLE), the error code for that attribute specifies the reason for the error.

See also: CsAttrValList in the VnmParmBlock Reference for more information on constructing a CsAttrValList object, and on setting and retrieving information from one. Also, see the section on CsAttrDesc for more information on casting an attribute value that is returned in the CsAttrValList object.


request The CsAttrValList object containing the attributes to be written.

Caution:Caution:

Do not change default attributes, as doing so may corrupt the modeling catalog of Landscapes linked via Distributed SpectroSERVER. Modifying shared attributes is allowable because changes to shared attributes do not affect the modeling catalog.

Note:Note:

An overall error code is set in the CsVnmParmBlock object. A completely successful request returns CsError::SUCCESS. If the overall error code is set to anything else, it can indicate difficulty writing a particular item. Each error code must be examined individually.



operator = ( )CsSYModelTypeHandle & operator =

( const CsSYModelTypeHandle & right_hand_side ) ;

This method is an assignment operator for the CsSYModelTypeHandle class. It deletes the value of the current object and assigns it a reference to the CsSYModelTypeHandle object right_hand_side.



CsSYRelationHandle operator = ( )


CsSYRelationHandle

Class Hierarchy

Include FileCsSYRelHnd.h

DescriptionThe CsSYRelationHandle class provides an interface which can be used to add associations, read associations, remove associations, describe associations, add rules, and read rules.

CsSModelAncestor

CsSHandleAncestor

CsSYRelationHandle



Public Methods

Method Description

CsSYRelationHandle ( ) Class constructor.

CsSYRelationHandle ( ) Copy constructor.

add_sync ( ) Adds associations to a relation.

count_sync ( ) Counts associations matching a pattern.

describe_sync ( ) Describes aspects of a relation.

dofunc_mrel_sync ( ) Performs an action on multiple models.

read_exp_sync ( ) Assignment operator.

read_exp_sync ( ) Expanded read of associations that match a desired pattern.

read_exprule_sync ( ) Expanded read of desired pattern in a relation.

read_mrelq_sync ( ) Read of desired pattern in a relation.

read_rule_sync ( ) Used when a rule that matches a certain pattern in a relation is to be read.

read_sync ( ) Used when the associations that match a certain pattern in a relation are to be read.

remove_sync ( ) Used when associations need to be removed from a relation.

operator = ( ) The assignment operator for the class.

CsSYRelationHandle CsSYRelat ionHandle ( )


CsSYRelationHandle ( )CsSYRelationHandle

( unsigned long relation, CsLscpeHandle my_landscape ) ;

This method constructs a CsSYRelationHandle object that provides a user-level interface to services such as adding associations, reading associations, and reading rules.

See also:

The VnmParmBlock Reference on CsRelationHandle for more information.


relation An unsigned long identifying the relation in the SpectroSERVER.

my_landscape A CsLscpeHandle object that identifies a specific Landscape in SpectroSERVER. Because multiple landscapes can be accessed from a single application, it is important to specify a Landscape when using this constructor.

CsSYRelationHandle CsSYRelat ionHandle ( )


CsSYRelationHandle ( )CsSYRelationHandle ( const CsSYRelationHandle & original ) ;

This is the copy constructor for CsSYRelationHandle which creates a new CsSYRelationHandle object and copies the value of the original object into it.

add_sync ( )CsAssocCount * add_sync ( CsAssocList * request ) ;

This method is used when associations need to be added to a relation (i.e., when two models need to be related to each other). The models that are to be related form an association. Many associations can be added to a relation in a single request. A list of such associations, the CsAssocList object, is the input to the method.

The associations in the list are added to the relation, thereby relating the two models in each association.

This method returns a pointer to a CsAssocCount. A value of CsError::SUCCESS indicates that the associations were successfully added to the relation.

See also:

The VnmParmBlock Reference on CsAssociation and CsAssocList for more information on constructing an Association and stringing them together in an AssocList.





request The CsAssocList object containing the associations to be counted after expansion.

CsSYRelationHandle count_sync ( )


count_sync ( )CsAssocCount * count_sync ( CsAssocList * request ) ;

This method is used when the associations that match a certain pattern in a relation need to be counted. The association patterns that are to be matched are specified in the CsAssocList object input to the method. The left, right, or both models in an association pattern can be specified as a wildcard (CS_WILD_MODEL_HANDLE).

The associations in the relation that match all the patterns in the CsAssocList are added up.

This method returns a pointer to a CsAssocCount that contains a count of the number of associations that matched each pattern in the input list. A value of CsError::SUCCESS indicates that the call was successful.

See also:

The VnmParmBlock Reference on CsAssociation and CsAssocList for more information on constructing an association and stringing them together in a CsAssocList, and also for more information on wildcards. Also see the section on CsAssocCount in for more information on retrieving the returned information.


request The CsAssocList object used in the count.

CsSYRelationHandle descr ibe_sync ( )



This method is used to get a description of different aspects of a relation. The aspect to be described is specified in the CsAspect input to the method by setting CsAspect::aspect to the desired value. Currently, a description can be requested of the relation itself, by setting the CsAspect::aspect to CsAspect::CS_ASPECT_SELF.

This method returns a pointer to a CsVnmParmBlock that contains a descriptor of the relation that must be typecast to a CsRelDescList. A value of CsError::SUCCESS indicates that the call was successful.

See also:

The VnmParmBlock Reference on CsAspect for more information on constructing a CsAspect object and on setting its members.

The VnmParmBlock Reference on CsRelDescList for information on retrieving the information returned, and CsRelDesc for information on a relation descriptor.



Note:Note:

A subaspect cannot be specified for CS_ASPECT_SELF to filter aspect descriptions; the subaspect default is ALL.

CsSYRelationHandle dofunc_mrel_sync ( )


dofunc_mrel_sync ( )CsModelRespList * dofunc_mrel_sync ( CsAssocList * relation,

CsVnmMsg::CsVnmFunction_e function, CsFindSpec * filter = 0 ) ;

This method is used to perform an action on multiple models. It is the same as read_mrelq_sync () except it can only perform functions that don't need parameters.


relation A CsAssocList identifying the models to query. Each association should have either the left or right side as a wildcard representing the models to query.

function Which of the following CsSYModelHandle functions to invoke in SpectroSERVER: destroy(), lock(), unlock(), test_lock()

filter A CsFindSpec object to be used as a filter after the associations have been expanded.

CsSYRelationHandle read_exp_sync ( )


read_exp_sync ( )CsExpAssocList * read_exp_sync ( CsAssocList * request ) ;

This method is used when the expanded versions of the associations that match a certain pattern in a relation are to be read. The association patterns to be matched are specified in the CsAssocList object input to the method. The left, right, or both models in an association pattern can be specified as a wildcard (CS_WILD_MODEL_HANDLE).

This method returns a pointer to a CsExpAssocList that contains the expanded versions of all the associations that matched all the patterns in the input list.

See also:

The VnmParmBlock Reference on CsAssociation and CsAssocList for information on constructing associations, and putting them together in a CsAssocList, and for information on wildcards. Also see the section on CsExpAssocList for more information on retrieving the returned information, and CsExpAssoc for information on the expanded version of an association.


request The CsAssocList object used in the read.

CsSYRelationHandle read_exprule_sync ( )


read_exprule_sync ( )CsExpRuleList * read_exprule_sync ( CsRule & rule_pattern ) ;

This method is used when the expanded version of a rule that matches a certain pattern in a relation is to be read. The rule pattern that is to be matched is specified in the CsRule object input to the method. The left, right, or both model types in an association pattern can be specified as a wildcard (CS_WILD_MTYPE_HANDLE).

This method returns a pointer to a CsExpRuleList that contains the expanded versions of all the rules that matched the pattern in the input.

See also:

The VnmParmBlock Reference on CsRule for more information on constructing a CsRule object and for more information on wildcards.

The VnmParmBlock Reference on CsExpRuleList for more information on retrieving the returned information, and CsExpRule for information on the expanded version of a rule.


rule_pattern The CsRule object used in the read.

CsSYRelationHandle read_mrelq_sync ( )


read_mrelq_sync ( )CsModelRespList * read_mrelq_sync ( CsAssocList * relation,

CsVnmMsg::CsVnmFunction_e function,CsVnmParmBlock * request, CsFindSpec * filter = 0 ) ;

This method is used to perform functions on multiple attributes of multiple models.


relation A CsAssocList specifying the models to access.

function Which of the following CsSYModelHandle functions to invoke in SpectroSERVER: read(), read_next(), write(), describe(), action()

request Input parameters for the request.

filter A CsFindspec object to be used as a filter after the associations have been expanded.

Note:Note:

Use the appropriate type of CsVnmParmBlock for the specific CsSYModelHandle function being performed. See Table 60



MODEL_READ CsAttrValList

MODEL_WRITE CsAttrValList

MODEL_ACTION CsAction

MODEL_READ_NEXT CsAttrValList

MODEL_CHECK_PERMISSION CsSecPerm

CsSYRelationHandle read_rule_sync ( )


read_rule_sync ( )CsRuleList * read_rule_sync ( CsRule & rule_pattern ) ;

This method is used when a rule that matches a certain pattern in a relation is to be read. The rule pattern to be matched is specified in the CsRule object input to the method. The left, right, or both model types can be specified as a wildcard (CS_WILD_MTYPE_HANDLE).

This method returns a pointer to a CsRuleList that contains all the rules that matched the pattern in the input.

See also:

The VnmParmBlock Reference on CsRule for more information on constructing a CsRule object and also for more information on wildcards.

The VnmParmBlock Reference on CsRuleList for more information on retrieving the returned information.

MODEL_NEW_READ CsAttrReadReqList

MODEL_NEW_WRITE CsAttrWriteReqList

MODEL_DESCRIBE CsAspect

MODEL_FIND_ATTR_BY_OID CsFindByOID


rule_pattern The CsRule object used in the read.



CsSYRelationHandle read_sync ( )


read_sync ( )CsAssocList * read_sync ( CsAssocList * request ) ;

This method is used when the associations that match a certain pattern in a relation are to be read. The association patterns that are to be matched are specified in the input (CsAssocList) to the method. Either the left or right or both models in an association pattern can be specified as a wildcard (CS_WILD_MODEL_HANDLE).

This method returns a pointer to a CsAssocList object that contains all the associations that matched all the patterns in the input list. A value of CsError::SUCCESS indicates that the call was successful.

See also:

The VnmParmBlock Reference on CsAssociation and CsAssocList for more information on constructing Associations and stringing them together in a CsAssocList, and for more information on wildcards.


request The CsAssocList object used in the read.

CsSYRelationHandle remove_sync ( )


remove_sync ( )CsAssocCount * remove_sync ( CsAssocList * request ) ;

This method is used when associations need to be removed from a relation (i.e., when the relation between two models needs to be broken). The models that are related form an Association. Many associations can be removed from a relation in a single request. A list of such associations is the input to the method, the AssocList. The associations in the list are removed from the relation, thereby breaking the relationship between the two models in each association.

This method returns a pointer to an AssocCount that indicates how many associations were successfully removed from the relation.

See also:

The VnmParmBlock Reference on CsAssociation and CsAssocList for more information on constructing associations and stringing them together in a CsAssocList object.

The VnmParmBlock Reference on CsAssocCount for more information on

retrieving information from a CsAssocCount object.


request The CsAssocList object containing the list of associations to be removed.



operator = ( )CsSYRelationHandle & operator =

( const CsSYRelationHandle & right_hand_side ) ;

This method is an assignment operator for the CsSYRelationHandle class. It deletes the value of the current object and assigns it a reference to the CsSYRelationHandle object right_hand_side.



CsSYStat operator = ( )


CsSYStat

Class Hierarchy

Include FileCsSYStat.h

DescriptionThis class provides methods for reading the statistics accessible to a single SpectroSERVER, either from its internal database or the archived statics/events database. It includes methods necessary to choose the types of statistics to query for, and to scroll up/down the statistics database for statistics logged at earlier or later times, relative to the current position.

CsSModelAncestor

CsSYLogs

CsSYStat

Note:Note:

CsSYStat objects are now capable of retrieving unsolicited statistics from SpectroSERVER. This capability is turned off by default. Setting the constructor’s collect_unsol parameter to TRUE will turn on the collection of unsolicited statistics.



Public Methods

Method Description

CsSYStat ( ) Class constructor.

CsSYStat ( ) Copy constructor.

attach_sync ( ) Allows an Application to attach to the Statistics Log database.

detach_sync ( ) Allows an Application to detach from the Statistics Log manager.

get_unsol_stats ( ) Retrieves unsolicited stat updates.

replace_filter_sync ( ) Used to change the filter that screens the statistics that are sent.

scroll_down_sync ( ) Used to scroll down within the Statistics Log database.

scroll_to_bottom_sync ( ) Used to scroll to the bottom of the Statistics Log database.

scroll_to_date_time_sync ( ) Used to scroll to the first occurrence within the Statistics Log database that matches the date time stamp.

scroll_to_top_sync ( ) Used to scroll to the top of the Statistics Log database.

scroll_up_sync ( ) Used to scroll up within the Statistics Log database.


CsSYStat CsSYStat ( )


CsSYStat ( )CsSYStat ( CsLscpeHandle my_landscape,


This method constructs a CsSYStat object that provides a user-level interface to a particular landscape, to perform functions such as choosing the types of statistics to query, and to scroll up/down the SpectroSERVER database.

See also:

CsLscpeHandle in the VnmParmBlock Reference, and the section on Synchronous SSAPI Programming in the SSAPI Developer’s Guide.

CsSYStat ( )CsSYStat ( const CsSYStat & original ) ;

This method is the copy constructor for CsSYStat. It creates a new CsSYStat object and copies the value of the original object into it.



collect_unsol Determines whether unsolicited statistics are retained for later retrieval. By default, collection of unsolicited statistics is turned off. Setting collect_unsol to TRUE will enable the collection of unsolicited statistics.



CsSYStat at tach_sync ( )


attach_sync ( )CsAttachResponse * attach_sync ( CsIEventFilter * request ) ;

This method allows the Application to attach to the Stat Manager in SpectroSERVER. Attaching allows the Application to receive statistical information. CsIEventFilter defines the types of statistics to be received.



a Call the CsSYStat method unsol_register() and pass it a pointer to an instantiation of a derived class of CsSMailClient.

b Save the response ID from unsol_register().

2 Construct a CsIEventFilter

a Pass the constructor the response ID returned from unsol_register().


c Pass the constructor a CsEventFilter to filter statistics.

3 Attach to the SCsMailService for Statistics

a Call the attach_sync() method of CsSYStat and pass it a pointer to the CsIEventFilter just constructed.

This method returns a pointer to a CsAttachResponse containing the statistics or error codes and a CsWindowId. This window ID should be saved, because it is needed to detach from SpectroSERVER.



request The CsIEventFilter containing the event filtering information.

CsSYStat at tach_sync ( )


See also:

The VnmParmBlock Reference on CsIEventFilter for more information on constructing one.

The VnmParmBlock Reference on CsAttachResponse for information on retrieving information from one.

Table 61: CsSYStat attach_sync() Error Codes

Error Meaning

NO_MORE_MESSAGES There are no statistics that are applicable to the filter that was used. If a datetime filter was chosen, then there are no statistics that match the filter, the cursor position in the database is beyond the edge of the database, or it is trying to read a statistic while the cursor is already on the last record. Choose a less limiting filter.

NO_SUCH_WINDOW_ID The referenced window ID was not valid. This happens when attach fails for the client or when detach has been called with an invalid ID. The window ID should be obtained from the original CsAttachResponse object using the get_log_windowid() method, after verifying that the response is valid.

CS_NULL_INPUT An invalid attach request was sent for an attach. The request is either not known to the SpectroSERVER Stat Manager or it has not been properly configured.

CsSYStat detach_sync ( )


detach_sync ( )CsVnmParmBlock * detach_sync ( CsILogWindowId * request ) ;

This method allows the Application to detach from the Statistic Log manager. The Application ceases to get statistic updates. This method takes the window ID that was returned from the attach_sync() method as an input parameter.

This method returns a pointer to a CsVnmParmBlock object containing the error code for the detach.


Table 62: CsSYStat detach_sync() Error Code

See also:

The VnmParmBlock Reference on CsILogWindowId for more information on constructing an ILogWindowId, and on CsAttachResponse for obtaining the window ID.

The VnmParmBlock Reference on CsVnmParmBlock for information on retrieving information from one.


request The CsILogWindowId object used to process the detach.

Error Meaning

NO_SUCH_WINDOW_ID The window id that is being used to detach is invalid. The window id should be obtained from the original CsAttachResponse using the get_log_windowid() method after verifying that the response is valid.

CsSYStat get_unsol_stats ( )


get_unsol_stats ( )CsUnsolEventStatList * get_unsol_stats


This method accepts a waiting time period (wait_time) and attempts to retrieve unsolicited statistic updates from SpectroSERVER. If unsolicited updates have already accumulated, this method simply returns that list and does not wait for the time given. If an unsolicited update occurs while the method is waiting, the method returns that update immediately. If no update occurs within the waiting period, this method returns an empty list.

See also:

The VnmParmBlock Reference on CsUnsolEventStatList for more information on retrieving the statistics returned.


wait_time The number of milliseconds to wait for an update.

CsSYStat replace_f i l ter_sync ( )


replace_filter_sync ( )CsScrollResponse * replace_filter_sync

( CsIEventFilter * request ) ;

This method is used to change the filter that screens the statistics being sent. This method takes the window ID that was returned from the attach_sync() method as an input parameter, as well as the new filter information, within the CsIEventFilter object.

This method returns a pointer to a CsScrollResponse object, which contains statistics that have passed the new filtering criteria.


See also:

The VnmParmBlock Reference for more information on constructing a CsIEventFilter object.

The VnmParmBlock Reference on CsAttachResponse on extracting the statistics.



Table 63: CsSYStat replace_filter_sync() Error Codes

Error Meaning

INSUFFICIENT_MEMORY Not enough memory to create filter nodes to the new CsIEventFilter object.

NO_MORE_MESSAGES There are no more statistics that are applicable to the filter used. If “datetime” filters were chosen, then no statistics fall between those “datetime” stamps. In addition, the cursor position in the SpectroSERVER Statistics Log database is beyond the edge of the database. Choose a less limiting filter.

CsSYStat scrol l_down_sync ( )


scroll_down_sync ( )CsScrollResponse * scroll_down_sync


This method is used to scroll down within the SpectroSERVER Statistics Log database. Scrolling down returns statistics that occurred later in time, relative to the current position. The input parameter is the window ID that was returned from the attach_sync() method.


See also:


The VnmParmBlock Reference on CsAttachResponse for more information on retrieving the statistics returned.



Table 64: CsSYStat scroll_down_sync() Error Codes

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. Obtain the window ID from the original AttachResponse using get_log_windowid(), after verifying that the response is valid.

NO_MORE_MESSAGES There are no more messages in the stat log in the direction of scroll. The index is already at the bottom of the event log.

CsSYStat scrol l_to_bot tom_sync ( )


scroll_to_bottom_sync ( )CsScrollResponse * scroll_to_bottom_sync


This method is used to scroll to the bottom within the SpectroSERVER Statistics Log database. Scrolling to the bottom returns the latest statistics in the database. This method takes the window ID that was returned from the attach_sync() method as an input parameter.

Table 65 lists the CsError error return:

See also:


VnmParmBlock Reference on CsSAttachResponse for more information on retrieving the statistics returned.



Table 65: CsSYStat scroll_to_bottom_sync() Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. Obtain the window ID from the original CsAttachResponse using get_log_windowid(), after verifying that the response is valid.

CsSYStat scrol l_ to_date_t ime_sync ( )


scroll_to_date_time_sync ( )CsScrollResponse * scroll_to_date_time_sync

( CsIDateTime * request ) ;

This method is used to scroll to the first statistic matching the specified date and time within the SpectroSERVER Statistics Log database. If there are no matching statistics, the application is positioned to the closest statistic. The input parameter for this method is the window ID that was returned from the attach_sync() method.


See also:

The VnmParmBlock Reference on CsIDateTime for more information on constructing one.



request The date and time to be scrolled to.

Table 66: CsSYStat scroll_to_bottom_sync() Error Code

Error Meaning


CsSYStat scrol l_ to_top_sync ( )


scroll_to_top_sync ( )CsScrollResponse * scroll_to_top_sync


This method is used to scroll to the top within the SpectroSERVER Statistics Log database. Scrolling to the top returns the earliest statistics in the database. The input parameter for this method is the window ID that was returned from the attach_sync() method.


See also:





Table 67: CsSYStat scroll_to_top_sync() Error Code

Error Meaning

NO_SUCH_WINDOW_ID The window ID that is being used is invalid. Obtain the window ID from the original CsAttachResponse object using get_log_windowid(), after verifying that the response is valid.

CsSYStat scrol l_up_sync ( )


scroll_up_sync ( )CsScrollResponse * scroll_up_sync ( CsILogWindowId * request ) ;

This method is used to scroll up within the SpectroSERVER Statistics Log database. Scrolling up returns statistics that occurred earlier in time, relative to the current position. The input parameter for this method is the window ID that was returned from the attach_sync() method.


See also:

The VnmParmBlock Reference on CsILogWindowId for more information on constructing one. Also, see the section on CsAttachResponse for information on retrieving the statistics returned.



Table 68: CsSYStat scroll_up_sync() Error Codes

Error Meaning


NO_MORE_MESSAGES There are no more statistics in the Stat Log in the direction being scrolled. The index is already at the top of the Stat Log.



operator = ( )CsSYStat & operator = ( const CsSYStat & right_hand_side ) ;

This method is an assignment operator for the CsSYStat class. It deletes the value of the current object and assigns it a reference to the CsSYStat object right_hand_side.



CsSYVLMapHandle operator = ( )


CsSYVLMapHandle

Class Hierarchy

Include FileCsSYVLMap.h

DescriptionThe CsSYVLMapHandle class provides methods that can retrieve Vnm/Landscape Map (V/L Map) information from SpectroSERVER. With the advent of Distributed SpectroSERVER, this base class has been added to the Synchronous SSAPI to provide applications with the ability to access multiple SpectroSERVERs and Landscapes. After making an initial connection to a Distributed SpectroSERVER, the application can request a copy of the VNM/Landscape Map, which contains information about all the SpectroSERVERs and landscapes that are accessible through the initial connection. The application can then use the information in the map to query any of the SpectroSERVERS using the Synchronous handle classes. The VNM/Landscape map is kept and maintained by the Location Server, and when accessing this information it talks directly with that application, not the SpectroSERVER.

For more information about constructing applications that can access this information, refer to the SSAPI Developer’s Guide.

CsSModelAncestor

CsSYVLMapHandle

Note:Note:

CsSYVLMapHandle can retrieve unsolicited map updates from SpectroSERVER. This capability is turned off by default. Setting the constructor’s collect_unsol parameter to TRUE will turn on the collection of unsolicited map updates.

CsSYVLMapHandle operator = ( )


Public Methods

Method Description

CsSYVLMapHandle ( ) Class constructor.

CsSYVLMapHandle ( ) Copy constructor.

attach_sync ( ) Requests V/L map at time of attach.

detach_sync ( ) Allows a user program to detach from SpectroSERVER.

get_non_secure_map ( ) Snapshot of the map containing only non secure entries.

get_unsol_updates ( ) Retrieves unsolicited map updates.

get_updated_map ( ) Gets an updated version of the Vnm/Landscape Map from SpectroSERVER.


CsSYVLMapHandle CsSYVLMapHandle ( )


CsSYVLMapHandle ( )CsSYVLMapHandle ( CsTboolean collect_unsol = FALSE ) ;

This is the default constructor for the CsSYVLMapHandle class. If no connection to the primary Landscape of a SpectroSERVER exists, this method will open a connection. If a connection exists, it will use that connection, rather than opening a new one. It will also keep an existing connection enabled, even if the handle that opened the connection is destroyed.

CsSYVLMapHandle ( )CsSYVLMapHandle ( const CsSYVLMapHandle & original ) ;

This method is the copy constructor for CsSYVLMapHandle. This method creates a new CsSYVLMapHandle object and copies the value of the original object into it.


collect_unsol Determines whether unsolicited Landscape Map messages are retained for later retrieval. By default, the collection of unsolicited V/L Map messages is turned off. Setting collect_unsol to TRUE will enable the collection of unsolicited V/L Map messages.



CsSYVLMapHandle at tach_sync ( )


attach_sync ( )CsVnmLscpeMap * attach_sync

( CsVLMapAttachReq * map_attach_request ) ;

This method requests SpectroSERVER to send a V/L Map at the time of the attach and allows an application to call get_unsol_updates() to get V/L Map updates as they occur and are stored by the SSAPI.

detach_sync ( )CsTresponseid * detach_sync

( CsVLMapAttachReq * map_attach_request ) ;

This method allows an application to detach from SpectroSERVER to stop receiving information on the V/L Map updates. Calling detach() destroys the CsSYVLMapHandle’s copy of the V/L Map.


map_attach_request The CsVLMapAttachReq object defining the attach request.


map_attach_request The CsVLMapAttachReq object defining the detach request.

CsSYVLMapHandle get_non_secure_map ( )


get_non_secure_map ( ) CsVnmLscpeMap * get_non_secure_map ( CsVnmParmBlock * req ) ;

Gets a snapshot of the map containing only non secure entries (all entries in the map except entries whose service type is a landscape service type).

get_unsol_updates ( )CsUnsolMapUpdateList * get_unsol_updates


This method accepts a waiting time period (wait_time) and attempts to retrieve unsolicited map updates from SpectroSERVER. If unsolicited updates have already accumulated, this method simply returns that list and does not wait for the time given. If an unsolicited update occurs while the method is waiting, the method returns that update immediately. If no update occurs within the waiting period, this method returns an empty list.

See also:

CsUnsolMapUpdateList in the VnmParmBlock Reference.


req A CsVnmParmBlock holding an error code.



wait_time The number of milliseconds to wait for an update.

CsSYVLMapHandle get_updated_map ( )


get_updated_map ( )CsVnmLscpeMap * get_updated_map ( void ) ;

This method gets an updated version of the Vnm/Landscape Map from SpectroSERVER. The Map received is a snapshot of the Map as it existed at the time of the response. An application should typically request an update, and after receiving it, delete any previously retrieved Map, using the new Map returned by this call.

Once you obtain a CsVnmLscpeMap object from the SSAPI, use an object of the CsVLMapLscpIter class to browse through the map.

See also:

CsVnmLMapLscpIter in the VnmParmBlock Reference.

operator = ( )CsSYVLMapHandle & operator =

( const CsSYVLMapHandle & right_hand_side ) ;

This method is an assignment operator for the CsSYVLMapHandle class. It deletes the value of the current object and assigns it a reference to the CsSYVLMapHandle right_hand_side.



Timing and Dispatch


Timing and Dispatch

This section describes the mechanisms provided with the Asynchronous SSAPI to handle timing and dispatching within an event-driven application.

Asynchronous Task SchedulingDevelopers using the Asynchronous SSAPI require a common interface which allows a function to register either a timer, a file descriptor or a work process, together with a corresponding handler (or call-back) function pointer and a generic pointer to any relevant state or context information.

To avoid synchronization problems, any Application that uses the Asynchronous SSAPI must schedule all tasks using a single timing and dispatching mechanism. This requirement also applies to the select(2) system call, which incorporates both alarm and I/O functionality. Synchronization problems include:

• Signals set by one process can cause previously set signals to be invalidated. Consequently, the signal handlers are never triggered.

• Multiple functions “block” or wait on a set of file descriptors for input, and the input arrives on another unwatched file descriptor. The unwatched file descriptor is likely to overflow.

To properly handle the dispatching of a Notify() within the Asynchronous CsMailService, a mechanism must be provided. This mechanism is a dispatch loop, similar to the XEvent loop found in the X Windows applications. This dispatch loop is started using the asynchronous CsMailService::deliver(). Within this continuous loop, Notify functions as well as user registered functions are called. Here are the types of functions to be registered:

• Timed function calls add_a_timer() — A timer and associated function can be set up within this mechanism. When the time originally set during the registration has elapsed, the function is called and control is returned to the deliver loop.

Timing and Dispatch Asynchronous Task Schedul ing


• I/O function calls add_an_input() — A file descriptor number and associated functions can be set up within this mechanism. When I/O is pending on that file descriptor, the function is called and control is returned to the deliver loop.

• Work function calls add_a_work_proc() — A function can be set up within this mechanism. If there are no other tasks to be dispatched, the mechanism calls this function and then returns control to the deliver loop.

CsIsolate Asynchronous Task Schedul ing


CsIsolate

Class Hierarchy

Include FileCsIsolate.h

DescriptionThis class contains prototypes of functions that provide the type of timing and dispatch mechanism needed by the SSAPI. It can be used with any object (or archive) defining these functions to register/unregister file descriptors or timers. These interface functions are declared as external, and are resolved by the linker (ld). They are referenced by libraries included in the SSAPI and must be resolved for linking.

Two libraries (libXIsol.a and libAIsol.a), which provide timing and dispatching mechanisms, are included in the SSAPI. The libXIsol.a library contains modules that provide the mechanism for X/Motif based SSAPI applications. Therefore, an application without a timing and dispatching mechanism that runs on X-windows, should link with libXIsol.a.

The libAIsol.a library contains modules that provide a complete timing and dispatching mechanism built entirely on UNIX system calls. An Application that neither runs on X-windows, nor has its own built-in timing and dispatching mechanism should link with libAIsol.a.

Two other libraries, libXR5Isol.a and libNDIsol.a, provide timing and dispatching mechanisms for X11 R5 and Neuron Data applications.

If an application already has a built-in timing and dispatching mechanism, the developer only needs to write functions that map the CsIsolate.h functions to the Application’s timing and dispatch functions. These “mapping” functions would have to be compiled and archived into a separate library. The application would then link with this new library

CsIsolate

CsIsolate Funct ion Prototypes


instead. Only one such library or object can be included in the link process.

CsIsolate.h also provides type definitions for the call-back procedures or handlers used by the registration functions. While the parameter ordering is important, it is not important that any handler or call-back function use any of the parameters (e.g., if the handler is only called given a predetermined context).

Function PrototypesThe following functions provide the timing and dispatching mechanism that is required by a SSAPI application.

Some of the functions described below take pointers to functions as parameters. These function pointers are defined here:

typedef void ( * input_call_proc)(void * context, int * source_fd, unsigned long * id) ;

typedef void (* timer_call_proc)(void * context, unsigned long * id) ;

typedef int (* work_call_proc) (void * context) ;

If any of the functions referred to by these pointers are non-static members of C++ classes, context will be interpreted as the this pointer of the object. In addition, these non-static member functions would be declared to take one parameter less than shown here. For example, either of these two definitions can be given for an input_call_proc:

void some_class::a_call_func( int * source_fd, unsigned long * id)

void another_call_func(struct * state_data, int * source_fd, unsigned long * id)



Note:Note:

AT&T™ C++ compilers, Version 3.0 and higher, do not support the casting of a member function pointer to a function pointer. With such compilers, it is necessary to enclose the real member function within a non-member wrapper function of type input_call_proc, timer_call_proc or work_call_proc, as appropriate.



Public Methods

Method Description

add_a_timer ( ) Registers a timer with the timing and dispatch mechanism.

add_an_input ( ) Registers source as a source of input with the timing and dispatching mechanism.

add_a_work_proc ( ) Registers the process with the timing and dispatching mechanism.

do_tasks ( ) Performs the actual wait/block function.

display_error ( ) Displays an error in a way which is independent of the display interface.

get_exit_status ( ) Returns the value of the internal exit_status flag.

main_loop ( ) Implements the main dispatch loop.

remove_a_timer ( ) Cancels the timer ID.

remove_an_input ( ) Cancels the input_handler that was associated with the id in the add_an_input() call.

remove_a_work_proc ( ) Cancels the process that was associated with the id in the add_a_work_proc() call.

set_exit_flag_ptr ( ) Added for compatibility with applications using the old constructor for CsMailService.

set_exit_status ( ) Sets the internal exit_status flag to TRUE or FALSE.

CsIsolate add_a_t imer ( )


add_a_timer ( )unsigned long add_a_timer ( unsigned long interval,

timer_call_proc timeout_handler, void * context ) ;

This function registers a timer with the timing and dispatch mechanism. When “interval” milliseconds have elapsed, the mechanism will call the timeout_handler. The timeout_handler will be passed the context as a parameter. The ID of the timer is returned

See also:

remove_a_timer()


interval Timer interval.

timeout_handler Function to be called on completion.

context Pointer to information to be passsed to the timeout_handler function.

Note:Note:

If the timeout_handler is a non-static member of a C++ class, “context” will be interpreted as the “this” pointer.

CsIsolate add_an_input ( )


add_an_input ( )unsigned long add_an_input ( int source, unsigned long mask,

input_call_proc input_handler, void * context ) ;

This function registers the input parameter “source” as a source of input with the timing and dispatching mechanism. When input arrives on “source”, the mechanism will call the input_handler with “context” as a parameter. “Mask” refers to the condition to be considered by the select(2) call, or exception. It should be set to one of the following values defined in CsIsolate.h: The ID of the input is returned.

• InputRead• InputWrite• InputExcept

These values can also be “ORed” together.


source File pointer.

mask Type of input.

input_handler Function to be called on completion.

context Pointer to information to be passed to the input_header function.

Note:Note:

If the input_handler is a non-static member of a C++ class, context will be interpreted as the “this” pointer.

More than one handler may be assigned to a file descriptor. However, only one handler per condition should be active at the same time.

CsIsolate add_a_work_proc ( )


add_a_work_proc ( )unsigned long add_a_work_proc

( work_call_proc process, void * context ) ;

This function registers the process parameter with the timing and dispatching mechanism. The mechanism will call process when there are no other tasks to be dispatched. It passes context as a parameter to process. The ID of the work process is returned

See also:

remove_a_work_proc()


process Function to be called.

context Pointer to information to be passed to the process function.

Note:Note:

If the process is a non-static member of a C++ class, context will be interpreted as the “this” pointer. Work processes should be quick and simple functions which do not have to be performed immediately. They must return a non-zero value if complete. As long as the work process continues to return 0, it will be rescheduled. This permits a more involved work process to be broken into iterative, simple processes.

CsIsolate do_tasks ( )


do_tasks ( )void do_tasks ( void ) ;

This function performs the actual wait/block function. It processes all queued input and all incomplete work processes. It then blocks until more work must be done, timers expire or input is queued up. Unless another timer has been started, the function returns immediately after processing the last expired timer.

display_error ( )void display_error ( char * error_message, int error_code ) ;

This function displays an error in a way which is independent of the display interface. It can either display the error message, or it can use an error code and map it to an error message. The example below displays the error code in hexadecimal format followed by the error message:

void display_error ( char * error_message, int error_code )

{

cout<<“Error ”<<hex<<error_code<<dec<<“: ”<<error_message<<endl;

}

Note:Note:

Since do_tasks() is called from within the CsMailService, it does not have to be called by the subscriber.


error_message Character string describing the error.

error_code Code that is mapped to the specific error that has occurred.

CsIsolate get_exit_status ( )


get_exit_status ( )int get_exit_status ( void ) ;

This function returns the value of the internal exit_status flag. When the flag is set to TRUE, it indicates that the application wishes to exit the main dispatch loop.

See also:

set_exit_status()

main_loop ( )void main_loop ( void ) ;

This function implements the main dispatch loop. In its simplest form, it loops calling do_tasks() until get_exit_status() returns TRUE.

remove_a_timer ( )void remove_a_timer ( unsigned long id ) ;

This function cancels the timer ID. If the timeout_handler() has been called previously because the timer has expired, there is no need to call this function. If remove_a_timer() is called for an invalid timer ID (one which has been removed already) no error will result.

See also:

add_a_timer()

remove_an_input()


id ID of the input to be canceled.

CsIsolate remove_an_input ( )


remove_an_input ( )void remove_an_input ( unsigned long id ) ;

This function cancels the input_handler that was associated with id in the add_an_input() call. Unlike timers, it is necessary to remove an input when it is no longer necessary to watch that file descriptor or when a new handler is needed. If this function is called for an invalid input ID (one which has been removed already), no error will result.

See also:

add_an_input()

remove_a_work_proc ( )void remove_a_work_proc ( unsigned long id ) ;

This function cancels the process that was associated with id in the add_a_work_proc() call.

If this function is called for an invalid input ID (one which has been removed already), no error will result.

See also:

add_a_work_proc()


id ID of the input to be canceled.


id ID of work process to be canceled.

CsIsolate set_exi t_f lag_ptr ( )


set_exit_flag_ptr ( )void set_exit_flag_ptr ( int * flag_ptr ) ;

This function has been added for compatibility with applications using the old constructor for CsMailService. It stores the address of the internal exit-status flag.

See also:

set_exit_status(), get_exit_status()


flag_ptr New exit flag value.

Note:Note:Be sure to use this pointer to access the internal status flag.

CsIsolate set_exit_status ( )


set_exit_status ( )void set_exit_status ( int value ) ;

This function sets the internal exit_status flag to TRUE or FALSE, to initiate whether or not the application wishes to exit the main dispatch loop.

With SPECTRUM 4.0, the Asynchronous SSAPI’s main dispatch loop was moved out of the CsMailService and into the Isolate layer. This will allow application developers to integrate SSAPI applications with other kinds of event handling, if needed.

As a result, applications that provide their own isolate layer will need to define three additional functions listed below:

• get_exit_status()• main_loop()• set_exit_flag_ptr()


value New exit flag value.

CsWorkProcess set_exit_status ( )


CsWorkProcess

Class Hierarchy

Include FileCsWorkProc.h

DescriptionThe CsWorkProcess class provides an interface for calling functions which are member functions of a class.

CsWorkProcess

CsWorkProcess set_exit_status ( )


Public Methods

Method Description

CsWorkProcess ( ) Class Constructor.

Call ( ) Casts the “what to do” pointer to “to what it should be.”

CsWorkProcess CsWorkProcess ( )


CsWorkProcess ( ) CsWorkProcess ( work_function func, void * call_back ) ;

The default constructor for the class. It takes a valid “work_function”. The “work_function” to be called may be a member function of an object (cast to work_function) ONLY if it takes no parameters - the void pointer in the type will become the “this” pointer when used to call a C++ member function and will therefore not be available for use otherwise. This is identical to using a “C” function such as:

1 void cfunc (void * cp)1 {1 ((class_type *) cp)->memb_func () ;1 }11 with the following function definition1 void class_type::memb_func ( void )1 {1 do some work with class data1 }1where class_type is the class to which the member function belongs and memb_func is the member function. In this example, the constructor would be called as: CsWorkProcess ( (work_function) cfunc, this ). To use the member function above directly:

CsWorkProcess ( (work_function) & class_type::memb_funct, this )


func Function to call.

call_back Object to be called back.

CsWorkProcess Cal l ( )


Call ( )Call ( void ) ;

This method casts the “what to do” pointer to “to what it should be”. It then deletes the “this” pointer.


Index

AAction codes 131add_a_timer() 350, 356add_a_work_proc() 351, 361add_an_input() 351, 357Alarm Manager 31, 76, 80AlarmRegister 79, 87API 18Application Program Interface 18Aspect 134, 278AssocCount 328Association 170, 175, 177, 178, 184,

322, 328AssocList 319, 328Asynchronous Handle Classes 73Asynchronous SSAPI 20, 211Asynchronous Task Scheduling 350AttachResponse 94, 106, 262, 264, 265,

338Attribute ID 124, 159AttrValList 299AttrValList, 300

CCall ( ) 367Call-back procedures 353Casting pointers 123, 292Connection_retry_interval 32CS_EVENT_MODEL_

DESTROYED 136CS_WILD_MODEL_HANDLE 172, 177CS_WILD_MTYPE_HANDLE 182

CsAction 131, 288CsAlarmAttachResponse 81, 241CsAlarmList 82, 83, 86, 87, 243, 247CsAlarmListNode 82, 83, 86, 87, 243,

247CsAlarmNode 82, 83, 86, 87, 243, 247CsAlarmRegister 79, 83, 87, 243, 247CsAspect 121, 173, 280, 291, 293, 311,

321aspect 121, 134, 154, 173, 278, 290,

292, 308, 321CS_ASPECT_RELS 134, 290, 292CS_ASPECT_SELF 173detail 135, 279, 290, 292, 309sub_aspect 134, 155, 278, 290, 292,

308CsAspectCount 156, 308, 311CsAssocCount 172, 177, 184, 320, 328CsAssociation 170, 172, 177, 178, 184,

319, 320, 327, 328CsAssocList 170, 172, 176, 177, 178,

181, 184, 319, 320, 327, 328CsAttachRequest 80, 81, 241CsAttachResponse 93, 191, 253, 254,

266, 334, 335, 338, 340, 342CsAttrDesc 140, 142, 159, 165, 280, 298,

300, 311, 313, 314CsAttrDescList 157, 311CsAttrGroupList 157CsAttrValList 140, 142, 148, 153, 159,

165, 297, 298, 300, 303, 307, 313, 314CsEnumBlkList 157CsError 241, 243, 245, 247, 253, 256,

295, 338, 342

Index


CIF_FAILURE 243CIF_FAILURE 83, 87, 248CS_NULL_INPUT 81, 82, 84, 86, 94,

99, 191, 242, 245, 247, 254, 259, 334

INSUFFICIENT_MEMORY 81, 82, 84, 86, 93, 100, 190, 193, 242, 243, 245, 247, 254, 261, 337

NO_EVENT_MESSAGE_ IN_LIST 259

NO_EVENT_MESSAGE_IN_LIST 99

NO_MORE_MESSAGES 93, 101, 102, 106, 190, 194, 195, 199, 254, 261, 262, 266, 334, 337, 338, 342

NO_SUCH_ALARM 83, 87, 244, 248NO_SUCH_WINDOW_ID 84, 94, 96,

102, 103, 104, 105, 106, 190, 192, 195, 196, 197, 198, 199, 245, 254, 262, 263, 264, 265, 266, 334, 335, 338, 339, 340, 341, 342

NULL_INPUT 243NULL_MESSAGE 82, 87, 243, 248SUCCESS 73, 81, 83, 84, 87, 136, 140,

142, 148, 153, 159, 165, 235, 242, 244, 245, 248, 294, 297, 300, 303, 313, 314, 319, 320, 321, 327

CsError.h 73, 235CsEventList 99, 107, 259CsEventMessage 99, 259, 260CsEventNode 259, 260CsExpAssoc 323CsExpAssociation 178CsExpAssocList 178, 323CsExpModelDesc 281CsExpRule 179CsExpRuleList 179, 324CsFindSpec 124, 281CsFullAttrDesc 311CsFullAttrDescList 157, 311

CsIDateTime 104, 197, 264, 340CsIEventFilter 92, 93, 100, 189, 191,

194, 205, 253, 254, 261, 333, 334, 337CsILogWindow Id 256CsILogWindowId 96, 102, 103, 105,

106, 192, 195, 196, 198, 199, 256, 262, 263, 265, 266, 335, 338, 339, 341, 342

CsIOEventList 95, 98, 259, 260CsIsolate.h 352CsLscpeHandle 119, 151, 169, 276,

306, 318CsMailClient 32, 58, 80, 92, 189, 205,

333Timeout() 58

CsMailclient.h 55CsMailService 20, 189, 205

get_handshake_timeout() 27is_connected() 28is_usable() 32register_for_connect() 28, 32set_exit_flag() 32shutdown_mailservice() 27Unregister() 30UnSolRegister() 31, 80, 92

CsModelDesc 280CsModelDescList 124, 281CsModelRsp 176, 181CsModelRspLst 176, 181CsMTypeDesc 311CsMTypeDescList 156, 311CsMTypeHandle 306CsRelDesc 134, 174, 280, 291, 293, 321CsRelDescList 134, 173, 292, 321CsRule 179, 182, 326CsRuleList 182, 326CsSAttachResponse 339, 341CsScrollResponse 100, 102, 103, 104,

105, 106, 107, 194, 195, 196, 197, 198, 199, 200, 261, 262, 263, 265, 266

CsSMailClient 241, 253

Index


CsSMailserv.h 213CsSMailService 213CsSYAlarm 330

~CsSYAlarm() 239attach_sync() 239, 241clear_alarm_sync() 243CsSYAlarm() 239detach_sync() 243

CsSYAlarm.h 237CsSYEvent 330

& operator = () 261~CsSYEvent() 251CsSYEvent() 250log_message_sync(), 266replace_filter_sync() 261scroll_down_sync() 264scroll_to_date_time_sync() 266scroll_to_top_sync() 264

CsSYEvent.h 249CsSYLandScapeHandle 268

~CsSYLandScapeHandle() 277CsSYLandScapeHandle( ) 277describe_sync() 278find_sync() 278

CsSYMdlHnd.h 285CsSYModelHandle 237, 287

& operator =() 303describe_rels_sync() 290destroy_sync() 294read_next_sync() 299read_sync() 299test_lock_sync() 301unlock_sync() 301

CsSYModelTypeHandle 304& operator = () 307create_sync() 307CsSYModelTypeHandle( ) 306CsSYModelTypeHandle() 306describe_sync() 308read_sync() 307

CsSYRelationHandle 316& operator = () 323~CsSYRelationHandle() 319add_sync() 319count_sync() 320CsSYRelationHandle() 316describe_sync() 321read_exprule_sync() 325read_rule_sync() 326read_sync() 322remove_sync() 328

CsSYRelHnd.h 275, 316CsSYSAlarm

get_unsol_alarms() 330unsol_register() 241

CsSYStat 330CsSYStat() 332get_unsol_stats() 344replace_filter_sync() 336scroll_to_date_time_sync() 340scroll_to_top_sync() 339unsol_register() 333, 342

CsSYStat.h 330, 344CsSYVLMapHandle

& operator = () 349attach_sync() 347CsSYVLMapHandle() 346detach_sync() 347

CsUIAlarm 75, 80, 186alarm_update() 88attach_async()‚ attach() 78, 80clear_alarm_async()‚

clear_alarm() 81, 88CsUIAlarm() 77detach_async()‚ detach() 84update_alarm_async()‚

update_alarm() 86CsUIAlarm.h 75CsUIEvent 92, 186

attach_async()‚ attach() 92

Index


create_event_async()‚create_event() 95

CsUIEvent() 90detach_async()‚ detach() 96log_message_async()‚

log_message() 98replace_filter_async()‚

replace_filter() 98, 100scroll_down_async()‚

scroll_down() 102scroll_to_bottom_async()‚

scroll_to_bottom() 106scroll_to_date_time_async()‚

scroll_to_date_time() 104scroll_to_top_async()‚

scroll_to_top() 103, 105scroll_up_async()‚ scroll_up() 102

CsUIEvent.h 88CsUIGlobalScapeHandle

CsUIGlobalScapeHandle( ) 111find_all_async( )‚ find_all( ) 114find_first_async( )‚ find_first( ) 115get_successful_landscapes( ) 116

CsUIHandles 57CsUILandScapeHandle 117, 119, 164

CsUILandScapeHandle() 119CsUILogs 107, 200CsUILscHndl.h 117CsUIMdlHndl.h 128CsUIModelHandle 108, 130, 175, 181,

325destroy_async()‚ destroy() 136

CsUIModelTypeHandle 149write_async()‚ write() 161, 164

CsUIMTHndl.h 149, 304CsUIRelationHandle 164

dofunc_mrel_async()‚ dofunc_mrel() 186

read_mrelq_async()‚ read_mrelq() 186

CsUIRelHndl.h 166CsUIStat 186CsUIStat.h 186CsUIVLMap 202CsUIVLMap.h 202CsUnsolEventStatList 246, 258, 336CsVarData 99, 259, 260CsVnmMsg 176, 181CsVnmParmBlock 20, 25, 73, 124, 131,

138, 144, 145, 173, 181, 235, 244, 245, 246, 247, 248, 256, 259, 260, 294, 295, 301, 325, 335

get_error() 73CsWindowId 84, 245, 253, 333

DDispatch loop 350do_tasks() 359

EEvent Log 89, 98, 101, 103, 104, 106Event Manager 31, 89, 96, 253EventFilter 100, 190EventList 99, 259EventMessage 99, 259EventNode 99EventType 259

Gget_exit_status() 360get_min_version 46get_next primitive (SNMP) 141get_non_secure_map 208get_non_secure_map_async 208

Index


Global 18Global classes 18

HHandle 30, 57Handle object 25Handles 30

II/O function calls 351IEventFilter 93, 100, 190, 191, 193, 261ILogWindowId 96, 192, 335Inference handlers 131, 288, 294, 295Initialize an SMailService 215Initiator

defined 73Instance ID 299IOEventList 98, 99, 260Isolation library 25

LLandscape 151, 169, 276, 294, 306, 318libAIsol.a 352libXIsol.a 352Lock a model 138, 295

MMailClient 56, 58MailService 56, 57, 79, 92, 107, 200

deliver() 350Main dispatch loop 24, 25main_loop() 360

method pair 73Model Type Editor 300

NNO 102Notify() 25, 31, 79, 80, 92, 107, 189, 200,

205Notify() dispatching 350

OObject id 297OID suffix 140, 141, 297, 299

RReceiver 31rel_test.cc 57Remove a lock 130, 145remove_a_timer() 360remove_a_work_proc() 361remove_an_input() 361Response ID 31, 79, 80, 92, 107, 189,

200, 205, 241, 253, 333Retriever

defined 73Retrieving statistics 107Rule 182

SScrollResponse 100, 102, 107, 193, 198,

261select(2) system call 350Send_msg_timeout 32

Index


set_exit_flag_ptr() 362set_min_version 224SSAPI 18Stat Log 187, 194, 195, 196, 197, 199Stat Manager 31Subscriber 30, 57, 79, 107, 123, 200,

279Synchronization problems 350Synchronous Handle Classes 235Synchronous SSAPI Classes 211

TTest a model lock 295, 301Testing for a locked model 144Timed function calls 350

UUnregister 30Unsolicited alarm message 79Unsolicited message 31, 189, 205Unsolicited messages 241Unsolicited statistics 187, 200UnSolRegister() 189, 205

VVnmParmBlock 98, 145, 165, 335VnmParmBlock classes 18

WWindow ID 81, 93, 96, 102, 103, 104,

106, 189, 192, 195, 196, 197, 198, 199, 241, 254, 262, 264, 265, 266, 334, 335, 338, 340, 342

Work function calls 351

XXEvent loop 350

ssapi reference guide (0486) - ca...

Documents