HP NonStop CORBA 2.6 Programmer's Guide for C++ HP NonStop CORBA 2.6 Programmer's Guide for C++ Part number: 525936001. Published November 2003. Legal Notice Abstract This manual provides information for application programmers about writing applications for HP NonStop" CORBA® 2.6 in C++. The information provided focuses on the NonStop CORBA-specific implementation of the Object Management Group's CORBA standards. Product Version: HP NonStop" CORBA® 2.
Components of the NonStop CORBA Environment Using the NonStop Distributed Component Console Running NSDAdminServer and NSDEnvironServer Application Profiles: Configuring and Managing an Application 3.
Information Collected in a Trace Categories of Tracing How to Enable and Disable Tracing Calling the Trace Facility Trace Settings for Application Processes Simple Tracing Example How the Trace Facility Interface Works Using the showior tool The showior Tool Syntax Examples of showior Commands Using the esadmin Tool The esadmin Tool Syntax Running the esadmin Tool esadmin Tool Commands Viewing the Naming Service Using the Console to View the Naming Service Setting Up ns_browse to View the Naming Service The
Use of TMF Transaction Service Features Not Supported in NonStop CORBA TransactionalObject Interface Checked Transaction Behavior Transaction Branches and the Diamond Access Problem 8.
Global State Information Database Access Applications Using Proprietary Features 11. Using the IIOP/SSL API SSLIOP IDL Interface SSLIOP::Current SSLIOP::Current::get_peer_certificate() SSLIOP::Current::get_peer_certificate_chain() 12.
Naming Service Calls ORB_init (flow 1 in the figure) Naming Service Creates and Publishes Root Naming Context IOR URL (flow 2 in the figure) Network Client Imports IOR (flow 3 in the figure) Network Client ORB Tries to Contact Target Object (flow 4 in the figure) LSD Builds and Sends Forwarding Reply (flows 5 and 6 in the figure) Client ORB Tries Again (flows 6 and 7 in the figure) Comm Server Receives and Relays Request (flows 7 and 8 in the figure) Naming Service Processes Request (flows 8 and 9 in the fi
12.2. Legacy Client Wrapper 12.3. Listener Event Handler and Event-Handler User 12.4. Transfer Event Handler and Event-Handler User 12.5. Client Event Handler and Event-Handler User A.1. Basic NonStop CORBA Architecture A.2. Expanded View of NonStop CORBA Architecture A.3. Layered View of the NonStop CORBA Architecture A.4. Message Flows A.5. CORBA Process Run-Time Environment List of Tables 1.1. NSK C++ Sample Programs 5.1. Error Log Information 5.2. Tracing Options 5.3.
Copyright 2003 Hewlett-Packard Development Company L.P. Hewlett-Packard, HP, the HP invent logo, Compaq, the Compaq logo, Alpha, Atalla, CLX, Deskpro, Enform, Expand, Guardian, Himalaya, Inspect, Integrity, NonStop, OpenVMS, PayMaster, ProLiant, ServerNet, SignMaster, SNAX, Tandem, VAX, VMS, and WebSafe are trademarks of Hewlett-Packard Development Company L.P. in the U.S. and/or other countries.
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause in DFARS 252.227-7013. Hewlett-Packard Development Company L.P. 10600 Ridgeview Court Cupertino, CA 95014 USA Rights for non-DOD U.S. Government Departments and Agencies are as set forth in FAR 52.227-19(c)(1,2). Export of the information contained in this publication may require authorization from the U.S. Department of Commerce. HEWLETT-PACKARD DEVELOPMENT COMPANY L.P.
New and Changed Information New and Changed Information This edition of the HP NonStop CORBA 2.6 Programmer's Guide for C++ describes the following new features for HP NonStop CORBA 2.6: ● Support for the OMG CORBA 2.6.1 specification. The section number headings and specification versions have been updated to match the current OMG CORBA 2.6.1 specification. ● Support for GIOP/IIOP versions 1.1 and 1.2. ● Support for Portable Interceptors. ● Support for IIOP/SSL.
About This Guide About This Guide Who Should Read This Guide Organization of this Guide Manuals in the NonStop CORBA Set Notation Conventions This NonStop CORBA 2.6 Programmer's Guide for C++ provides information about designing and implementing application programs for the NonStop CORBA 2.6 environment. The guide explains how to take advantage of the specific implementation features of NonStop CORBA.
Organization of this Guide Section 1, Introduction to NonStop CORBA Programming, describes prerequisite knowledge and basic design activities. The major components of NonStop CORBA are introduced. Section 2, NonStop CORBA Administrative Environment, describes working in the Open System Services (OSS) environment and in the NonStop CORBA administrative environment. The NonStop Distributed Component Console is introduced. Application profiles are described.
Manuals in the NonStop CORBA Set The NonStop CORBA 2.6 Getting Started Guide for C++ describes how to install the product and verify installation. It also includes an introduction to the C++ product. The NonStop CORBA 2.6 Getting Started Guide for Java describes how to install the product and verify installation. It also includes an introduction to the Java product. The NonStop CORBA 2.
[] {} | ... "" Other punctuation Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list may be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines.
Long Commands If the syntax of a command is too long to be shown on a single line, each continuation line is indented three spaces, the first of which is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] CONTROLLER [ , attribute-spec ]... New and Changed Information Chapter 1.
Chapter 1. Introduction to NonStop CORBA Programming Chapter 1. Introduction to NonStop CORBA Programming Before You Begin Design Activities Sample Programs Introduction to NonStop CORBA Components NonStop CORBA 2.6 is based on the OMG standards for CORBA 2.6. This guide describes features specific to the NonStop CORBA implementation as the features apply to designing and coding applications.
● Object features such as inheritance and predefined classes and frameworks ● CORBA and related services You must also understand the following characteristics of NonStop CORBA and related products, which are described in later sections of this guide: ● Advantages and implications of using NonStop TS/MP (Pathway programming environment) server classes and stateless or stateful request processing. TS/MP server classes are referred to as server pools in NonStop CORBA.
Clients running on a NonStop system These processes reside on the same NonStop system (or Expand network) as the NonStop CORBA Object Request Broker (ORB) and act as CORBA clients. Clients running elsewhere as network or remote clients These processes reside on some other system (not the same NonStop system or Expand network as the NonStop CORBA ORB). The processes act as CORBA clients.
Illustrates some of the basic concepts of CORBA programming using NonStop CORBA. The stack sample shows you: stack ● An object interface definition written in IDL ● A server that implements the interface defined by the interface definition A client application which makes use of an instance of a stack object The stack sample may be used to verify installation of NonStop CORBA. Illustrates some of the basic concepts of Object-By-Value and describes a simple abstract interface.
database directly by using the NonStop Distributed Component Console or by using the cfgmgt tool. Comm Servers Comm Servers can be thought of as gateways allowing network clients to communicate with application servers on the NonStop system. They also act as TCP/IP network resource concentrators, mapping all connections from a client address to the same Comm Server. Comm Servers take advantage of TS/MP capabilities and are configured as TS/MP (Pathway) server classes.
● Naming Service (implemented as a server pool or NonStop TS/MP server class). NonStop CORBA implements the Interoperable Naming Service specified in the OMG CORBA 2.6.1 specifications, with the exception that the Resolve Initial References (RIR) URL is not supported. ● Event Service. A standard application service (one of the OMG Common Object Services) for asynchronous communication among objects ● Transaction Service.
Chapter 2. NonStop CORBA Administrative Environment Chapter 2. NonStop CORBA Administrative Environment Working in the Open System Services (OSS) Development Environment Using Guardian Commands and Files Through OSS OSS Environment Variables and the env.
● User commands and utilities. The osh command enters the OSS environment and starts an OSS shell process. To work with NonStop CORBA, you need to have a basic understanding of the OSS environment and you need to know how to use some of the OSS commands. A few of the commands most used in preparing a NonStop CORBA application are described in the following sections.
OSS Environment Variables and the env.sh File A shell implements environment variables that you can set and display. Processes started from the OSS shell can access exported environment variables. For example, NonStop CORBA processes and utilities use environment variables when you configure the system, develop a component, or run an application. The $NSD_ROOT/etc/env.sh file stores shell commands that set environment variables. The env.sh shell script must be executed during shell initialization by using .
This utility is the front end for the C++ compiler. You can invoke c89 from within the make file. nld This utility is the native (TNS/R) linker. It links one or more TNS/R native object files to produce an executable or relinkable native object file. You can run the nld utility from either the Guardian or the OSS environment. c89 automatically invokes the nld utility. Therefore, in most cases you need not use nld explicitly when creating application executable files.
● The NSDAdminServer process provides services that are independent of any security domain, such as system configuration information. ● The NSDEnvironServer process provides services for a specific security domain. ● The $NSD_ROOT/etc/env.sh file contains environment settings. ● The Configuration database (nsdcfgdb) contains entities for ORB components and application profiles. ● The adminDB stores the operational data used by the NSDAdminServer and NSDEnvironServer processes.
Note: You can set many configuration database entities by using the NonStop Distributed Component Console. These database settings apply to all applications, unless overridden by an application-specific configuration entity (that is, profile@ORB). Application-specific entities are managed by using the cfgmgt tool. See Application Profiles: Configuring and Managing an Application for more information. Note: The Console is also useful when you troubleshoot your application.
profile@ORB Server Transport Protocols Several of the server transport protocol settings are interrelated, and you must use caution when setting them. You may wish to refer to Writing Scalable Applications for a discussion of how the choice of server transport protocols affects application design. The rules are: tcp_server {true | false} Default is false. If set to true, you must either set use_comm_server true (called indirect TCP server) or set both host_name and port_number.
Default is true. fs_client {true | false} Default is true. tcp_client {true | false} Default is true. profile@ORB Miscellaneous Settings These settings are all optional. They apply only to the application using the profile. You can set the defaults for these values by using the Console, or by editing the default@ORB entity using the cfgmgt tool. log_file {EMS-process-name | STDCOLL | STDOUT | STDERR | oss-file-name} Default is STDCOLL. trace_file {file-name | STDOUT | STDERR} Default is STDOUT.
Controls whether wchar and wstring are enabled over GIOP 1.0. The key is allow_wchar_wstring_in_1_0, and the key value is true or false. The default is false. Since the default is false, you must set this configuration value if you want NonStop CORBA 2.6 to allow wchar and wstring to be transmitted over GIOP 1.0. Many vendors, including NonStop CORBA 2.3 B13, allow wchar and wstring to be transmitted over GIOP 1.0. NonStop CORBA 2.6 also allows wchar and wstring to be transmitted over GIOP 1.0.
Chapter 3. Compiling and Building an Application Chapter 3.
1. Define the CORBA object's interface in a CORBA Interface Definition Language (IDL) file. 2. Compile the IDL file using the NonStop CORBA IDL compiler. Compiling the IDL file will generate several files: ● A header file to include in client programs that use the CORBA object. ● A client stub source file to be compiled and linked with client programs. ● A header file to include in the server that implements the CORBA object. Note that the server header, in turn, includes the client header.
● Create an object implementation header file based on information found in the server skeleton header. ● Create the server main program and object implementation. Code must be written for each method declared in the IDL interface definition. ● Compile the server implementation code, producing an object file. ● Compile the server skeleton code produced by the IDL compiler, producing an object file.
Services, stateful and stateless objects, application data in a NonStop SQL/MP database, and writing multithreaded applications. Note: The make utility is vital in combining your program modules into a coherent application and enabling you to maintain individual modules. For detailed information, refer to the Open System Services User's Guide and to the Make (1) utility reference page either online or in the Open System Services Shell and Utilities Reference Manual.
nsdidl Compiler Syntax The following line is the command-line syntax for running the IDL compiler. The IDL compiler is invoked with the -language C++ option to generate C++ code. You can display help text by using the -? option. For example, to invoke the compiler to generate C++ bindings, type the following command: nsdidl -language C++ idlfile1[, idlfile2 ]... Preprocessor Options -D name Define name as a macro, with definition '1'. This option is the same as if the -D name=1 option is used.
#include idltest/t1_client.h and the -include 1 option generates: #include t1_client.h If level equals 0, the full pathname is generated. If level is more than the number of directories in the path, the full path is generated. -ir Generate an Interface Repository (IR) from the input IDL (the existing IR definitions are updated). The default is off. -IR Generate an Interface Repository (IR) from the input IDL (the existing IR definitions are replaced). Useful if you use Dynamic Invocation Interface (DII).
nsdidl: Error: compiler options must preceed file names, use: nsdidl [-?][-v][-D name][-D name=definition][-U][-I dir][-language (C++ | Java)] [-version][-o dir][-generate arg][-h suffix][-s suffix][-client suffix][-server suffix][-no_][-include level][-typecodes][-IR][-ir][-preprocessor arg] [-preprocessed][-map2package module package][-dll define-name][filename]* 1 error Chapter 2. NonStop CORBA Administrative Environment Chapter 4.
Chapter 4. Deploying a NonStop CORBA Application Chapter 4. Deploying a NonStop CORBA Application The general steps to consider in deploying a NonStop CORBA application after you have compiled your files are: ● Check that you have set up your application profile as described in Application Profiles: Configuring and Managing an Application. ● Use the Console to make sure that any other subsystem configuration profile settings are correct. ● Decide if you want to enable tracing.
sample script shown below illustrates how the environment is configured (this example is from the Bank sample program supplied with NonStop CORBA). For server-pool environments, HP recommends using a script. If you are not familiar with configuring NonStop TS/MP environments, see the NonStop TS/MP System Management Manual (note that in TS/MP documentation, server pools are called server classes).
else G_HOMETERM=\$ZTNT.$HOMETERM fi [[ -n $VERBOSE ]] && print "Standard output will appear on $G_HOMETERM" # Start a PATHMON environment: # 1. Get "default" volume name. This is where the PATHCTL file is # created by PATHMON. We'll create the PATHMON log file there as well. # 2. Blindly create the PATHMON log file. If it is already there, ignore # the error. # 3. Start the PATHMON process PMLOG=$(info_define -detail =_DEFAULTS | awk '/VOLUME/ {print $3}').
[ SQL defines set server DEFINE =acctcat, class catalog, subvol $SQLCAT set server DEFINE =accttab, class map, file $SQLTAB.accttab set server env NSDOM_CFG_DBM=$NSDOM_CFG_DBM set server arglist "-ORBprofile", "bank_server_pool" [ [ [ [ set set set set server server server server env env env env NSDOM_CFG_TRACE_POA=1 NSDOM_CFG_TRACE_PROXY=1 NSDOM_CFG_TRACE_GIOP_FW=1 NSDOM_CFG_TRACE_GCFEH=1 $APPL_TRACE_ENABLED [ define to use SRL set server define =_SRL_01, class map, file $NSD_SRL_SUBVOL.
Chapter 5. Tracing and Debugging Applications Chapter 5.
esadmin Tool Commands Viewing the Naming Service Using the Console to View the Naming Service Setting Up ns_browse to View the Naming Service The ns_browse Tool Syntax Examples of ns_browse Commands Troubleshooting Application Components Troubleshooting a NonStop CORBA application or component involves evaluating information from the following sources: ● System exceptions raised by the NonStop CORBA run-time environment, reported to the client program.
tracing. In some cases, an operator must work with other operators on remote systems to discover configuration mismatches. For a more general understanding of NonStop CORBA component interactions, architecture, and message flows, see Appendix A, Architectural Walkthrough. Using the Error Logging Facility Unexpected conditions detected by NonStop CORBA can be logged through the Event Management Service (EMS) on NonStop systems.
Process ID of the process that logged the error Thread ID of the thread that logged the error Exception type (not all log messages are associated with an exception) Exception name (not all exceptions are named) Name of source file that logged the error Line number of the source file that logged the error PId TId ExcptType ExcptName File Line While much of this information is composed by the error logging facility at the time the call is made, you must supply some of it when you make your calls.
To start an alternate collector for the NonStop CORBA Software Developer Kit (SDK) environment, you enter the following commands at the TACL prompt: > EMSACOLL /NAME $xxx, NOWAIT/ BLOCKING OFF For more information about starting the EMS collector, see the EMS Manual. Note: The variable $xxx is the process name for the collector that you set using MY_COLLECTOR in the $NSD_ROOT/etc/env.sh file or in log_file in the default@ORB entity in the configuration database.
information that can help you troubleshoot the problem. Calling the Error Logging Facility Each call to the error logging facility is made at one of four severity levels: Critical, Error, Warning, or Informational: ● Critical indicates an error that could result in significant loss of, or damage to, your subsystems environment. ● Error indicates an error occurred that might require some user action to fix the problem (for example, a configuration error).
#define NSDOM_LOG_SET_LOG_FILE(pp_log_file_name) ; NSDOM_LOG_WARNING(pv_err_num, pp_text) ; NSDOM_LOG_WARNING_ENV(pv_err_num, pp_text, pp_env) ; In the above macros, exc refers to a CORBA exception, and env refers to CORBA environment. Component Names Each NonStop CORBA component should be assigned a unique component name so NonStop CORBA can identify the process that is logging the error message. Component names are assigned once for each process, which must be done before an error message can be logged.
NSDOM_Error_Log::get_default().log_error(__FILE__, __LINE__, \ pv_err_num, pp_text); NSDOM_Error_Log::get_default().log_error(__FILE__, __LINE__, \ pv_err_num, pp_text, pp_exc); NSDOM_Error_Log::get_default().log_info(__FILE__, __LINE__, \ pv_err_num, pp_text); NSDOM_Error_Log::get_default().log_info(__FILE__, __LINE__, \ pv_err_num, pp_text, pp_exc); NSDOM_Error_Log::get_default().set_component_name(pp_comp_name); NSDOM_Error_Log::get_default().
} catch (const CORBA::Exception& ex ) { NSDOM_LOG_ERROR_EXC (7003, "Error writing to CustDB", ex ); } The following code shows how to log an error using if/then logic. This technique is usually less desirable than using exceptions.. some CORBA work ... if (!CORBA::environment::default_environment().OK()) // log an error LOG_ERROR_ENV( 7003, "Error writing to CustDB", lv_env); ...
void log_critical(char *pp_src_file_name, // name of src file int pv_src_line_num, // line num of src long pv_err_num, // error number char *pp_text, // text const CORBA::Exception &pr_ex); // exception void log_error(char *pp_src_file_name, // name of src file int pv_src_line_num, // line num of src long pv_err_num, // error number char *pp_text); // text void log_error(char *pp_src_file_name, // name of src file int pv_src_line_num, // line num of src long pv_err_num, // error number char *pp_text, // tex
The NonStop CORBA trace facility provides an API that writes trace messages to an ASCII file. You use the trace facility to implement instrumentation in your NonStop CORBA applications. You can add trace statements to specific portions of NonStop CORBA applications or components to help troubleshoot program code. Design of the Trace Facility The trace facility consists of a single class called NSDOM_Trace. This object provides several methods that write trace messages out to a specified trace file.
NSDOM_CFG_TRACE_IR ir NSDOM_CFG_TRACE_GCFEH event_context_free NSDOM_CFG_TRACE_GFSEH event_file_system NSDOM_CFG_TRACE_SOCKEH NSDOM_CFG_TRACE_SOCKEH_DETAIL event_socket NSDOM_CFG_TRACE_EVENT_CORE event_core NSDOM_CFG_TRACE_GIOP_FW orb_giop_connections NSDOM_CFG_TRACE_ORB orb_request_queue NSDOM_CFG_TRACE_POA poa NSDOM_CFG_TRACE_OTS none NSDOM_CFG_TRACE_PROXY NSDOM_CFG_TRACE_PROXY_DETAIL orb_proxy NSDOM_CFG_TRACE_THREADS threads NSDOM_CFG_TRACE_TIMER event_time NSDOM_CFG_TRACE_DETAIL
NSDOM_CFG_TRACE_PI NSDOM_CFG_TRACE_PI_DETAIL pi NSDOM_CFG_TRACE_SSL ssl Traces basic Portable Interceptor activity. If detail, add data representation during portable interceptor processing NonStop CORBA SSLIOP activity How to Enable and Disable Tracing You can enable tracing by using one of the following techniques: ● Use the NonStop Distributed Component Console. The Console updates the configuration database.
You can also modify the $NSD_ROOT/bin/nsdstart script. This script contains NonStop CORBA subsystem trace-flag settings that have been commented out. Like the Console, the nsdstart script sets tracing only for NonStop CORBA subsystem processes, not application processes. To enable tracing for one or more of the subsystem processes, you must uncomment the appropriate lines before running nsdstart.
LSD NSDOM_CFG_TRACE_ORB Naming Service NSDOM_CFG_TRACE_ORB NSDOM_CFG_TRACE_POA OTS NSDOM_CFG_TRACE_ORB NSDOM_CFG_TRACE_POA NSDOM_CFG_TRACE_OTS XID Broker NSDOM_CFG_TRACE_ORB NSDOM_CFG_TRACE_POA NSDOM_CFG_TRACE_OTS NSDOM_CFG_TRACE_ORB NSDOM_CFG_TRACE_GIOP_FW NSDOM_CFG_TRACE_SOCKEH NSDOM_CFG_TRACE_POA NSDOM_CFG_TRACE_PROXY NSDOM_CFG_TRACE_ORB NSDOM_CFG_TRACE_GIOP_FW NSDOM_CFG_TRACE_GFSEH NSDOM_CFG_TRACE_GCFEH NSDOM_CFG_TRACE_POA NSDOM_CFG_TRACE_PROXY NSDOM_CFG_TRACE_ORB NSDOM_CFG_TRACE_OTS NSDOM_CFG_T
Trace Settings for Application Processes To enable tracing for an NonStop CORBA client or server process, set one or more environment variables prior to running the process. For a client process, setting NSDOM_CFG_TRACE_PROXY to TRUE is a useful starting point. If more detail is needed, enable one or more of the protocol trace variables (depending on the protocols in use by the client). For a server process, setting NSDOM_CFG_TRACE_POA to TRUE is a useful starting point.
static void open_trace_file (CORBA::Environment &pr_env); static void close_trace_file (CORBA::Environment &pr_env); static void log_trace (char *pp_trace_data, short pv_trace_data_len, CORBA::Environment &pr_env); }; Trace Method Descriptions The NSDOM_Trace::log_trace() method writes a trace message to the trace file.
SSL_connect The SSL_connect trace record is emitted by a SSL client and is triggered when a hello message is sent from the client to the server. The connect side of the SSL handshake is traced. The SSL version is included in the trace record.
Using the showior tool The $NSD_ROOT/bin/unsupported/showior tool can help you in troubleshooting applications. Use this tool to help determine if a server is publishing the correct information about an object, for example, the right TCP address and port number. You can also use this tool to determine if a client has the right profiles available, that is, profiles that match the client's capabilities.
tasks, the Console is the preferred tool for management in production environments. The esadmin tool can only be run from the JORB Lite environment on a workstation, but it can be used with the Event Service on the NonStop system. The esadmin tool uses a graphical user interface (GUI) to let you administer one or more NonStop CORBA Event Service channels.
Alternatively, you can specify a file containing an event-channel object reference. This file could, for example, have been created by another program that created an event channel. If you use a file-based IOR for the event service, the event channel can be on any accessible system. After you have chosen the event channel to administer, the esadmin tool displays the Event Channel Status window.
Viewing the Naming Service You can use the NonStop Distributed Component Console or the ns_browse tool to look at entries stored in the Naming Service database. The Naming Service database can be viewed as a tree of naming contexts. A naming context is an object that contains a set of name bindings. A binding is a name-to-object association. Because a context is like any other object, it can also be bound to a name in another naming context.
For more information about using the Console, see the NonStop CORBA 2.6 Administration Guide and the online help provided with the Console. Setting Up ns_browse to View the Naming Service The ns_browse tool runs on the NonStop system, and it allows you to look at entries stored in the Naming Service database. You might use the ns_browse tool if for some reason you did not want to use the Console, or if the Console were not available.
bind_new_context destroy list new_context rebind rebind_context remove_context resolve unbind Note that the specified operation is performed against the base naming context, as specified with the -ior option. Each operation is described in detail below. bind object-name stringified-IOR This option binds the name specified by object-name to the object whose IOR is specified by stringified-IOR.
unbind object-name This option unbinds the name specified by object-name from the object it is currently bound to. Examples of ns_browse Commands The following commands demonstrate how the ns_browse tool works: 1. Run ns_browse without any parameters, as follows: ns_browse This command causes the tool to display usage information. 2. Run ns_browse to list the contents of the root naming context: ns_browse list 3.
Chapter 6. Writing Scalable Applications Chapter 6.
● Configure application server processes as server pools. NonStop CORBA then uses the capabilities of TS/MP to spread the workload among multiple processes, adds new processes as needed, and provides load balancing. ● Configure the Comm Server, LSD, ILSD, and/or BSD processes in your NonStop CORBA system to use Parallel Library TCP/IP, so that a single TCP/IP port is shared by multiple communications processes. ● Increase the number of Comm Server processes to support increased request traffic.
Stateful and Stateless Objects In NonStop CORBA, objects can be either stateful or stateless. The use of stateful and stateless objects is closely related to the use of server pools. If an object is stateful, all operations directed to that object must be handled by the same servant (instance of the object). Operations directed to other objects in the class can be handled by different servants in other processes.
TS/MP transport protocol. (By default, an object with a lifespan policy of PERSISTENT is assumed to be stateless.) The state policy has two values: STATEFUL and STATELESS.
the TS/MP configuration to zero. Otherwise, TS/MP server processes are deleted if they are inactive for some time, even if a stateful session is still in progress. The use of stateful servants thus disallows dynamic shrinking of the server pool. Adjusting TS/MP Configuration Parameters If you use server pools for your application server processes, you can support increased request traffic by adjusting parameters in your TS/MP configuration.
running in a server pool can share the same port. When configured this way, the server pool appears as a single IP host to the outside world. A round-robin filter distributes the incoming connections among the communications processes in the pool. Because Parallel Library TCP/IP does the load balancing, when you use it to configure Comm Server processes the LSD process has less work to do than it would if you used separately configured logical Comm Server processes.
You can also use the two alternatives in combination if you need more than sixteen Comm Server processes. Using Multiple Instances of NonStop TCP/IP If the TCP/IP process is a performance bottleneck, you can increase the number of external port connections available to your application by doing the following: 1. Add multiple instances of NonStop TCP/IP to your NonStop CORBA system. 2.
Chapter 7. Managing Transactions Chapter 7.
NSOTS and TMF communicate through a pseudo-file called a recoverable resource manager (RM) file. They exchange signals through this file using the TMF APIs. These signals are used to start and terminate transactions. The RM file is also used during the initialization of NSOTS to recover any in-doubt transactions following a failure. The operations tmf_start and tmf_end are added to the CosTransactions::Current interface to control the participation of NSOTS in outstanding TMF transactions.
Transaction Branches and the Diamond Access Problem Because of the way TMF handles distributed transactions, you may need to design your application to avoid database access deadlocks between transaction branches, sometimes called the diamond access problem. This problem is not specific to NonStop CORBA, and can occur in any system where TMF is used. It is most likely to occur in highly distributed applications with distributed databases.
In this figure, the application starts a debit/credit transaction on System A. The debit account is held on System B and the credit account is held on System C. System D has an object that requires input from both debits and credits (in this case a Bank Vault Account that tracks debits and credits). The problem occurs when Systems B and C attempt to write to the Bank Vault object on System D. At that time, one write operation might be locked out by the other.
In configurations where the NSotsTM process runs as a server pool with multiple processes, contention between NSotsTM processes can cause the diamond access problem to occur. To avoid this cause of the problem, no application changes are required. NonStop CORBA provides the NSotsXID process to act as a broker between NSotsTM processes, so that only one process has control at a time.
Chapter 8. Writing Multithreaded Applications Chapter 8.
Multithreading in Client Applications One typical use of multithreading in NonStop CORBA client programs is to issue concurrent requests to one or more objects. When multithreading is not used, operations are synchronous. That is, when a client performs an operation on an object, it must wait for the response to arrive before doing any further processing. If a client application creates multiple threads, each thread can perform operations and thus have concurrent outstanding requests.
● Create a thread ● Yield control of the processor ● Wait for other threads to complete ● Cancel a thread ● Save and retrieve thread-specific data Also provided are two concurrency-control mechanisms: mutexes and condition variables.
specifies the thread function that will be called when the thread is launched (the main line of the new thread). The third parameter is the thread argument referenced in Step 2, which allows the Fw_Thread::create function to pass context to the thread. (The third parameter could be the C++ keyword this or a reference to any other object.) The last parameter sets the relative priority of the thread.
Creating and Using a Condition Variable A condition variable communicates information about shared data. For example, you can use a condition variable to signal that a queue is no longer empty, or that it has become empty, or that something else needs to be done or can be done within the shared data manipulated by threads in an application program. A condition variable allows a thread to start a task and then enter a waiting state until a necessary condition (performed by another thread) is satisfied.
● To set the value of a 32bit entry in the table, call the specific_set() method, passing the associated key returned by specific_key_create(). ● To retrieve the value of a 32bit entry in the table, call the specific_get() method, passing the associated key returned by specific_key_create(). Terminating Execution of a Thread In a multithreaded process, you must explicitly exit each thread created by the process.
Chapter 9. Designing Advanced Applications Chapter 9.
Designing Object Interfaces and Classes The following is a summary list of the issues you should consider when designing object interfaces (in IDL) and the resulting object classes in a NonStop CORBA application. These considerations may be more important in the highly distributed environment of a NonStop system than they are on other platforms. ● The role of each object interfacefor example, whether each object represents an entity in a databaseand the relationships among objects.
use. Object Roles and Relationships The following three-tier classification of object roles is not specific to NonStop CORBA but is used throughout this section: ● Interface objects typically run on a client workstation or other end-user device, such as a bank-teller input device or a gas-station pump. ● Control objects typically run on a server machine.
maintain dynamic state in the form of a cursor for the result set. Whether an object maintains dynamic context between calls has implications for load balancing, and therefore for application throughput, as described in Parallel Processing and Its Implications. Entity Objects An entity object typically represents stored data, although it could also represent a device.
The following example shows an IDL object definition with multiple attributes: interface account { readonly attribute string CustomerName; readonly attribute string CustomerAddress; } If this type of object is distributed, the client must send a separate message to read each attribute.
Parallel Processing and Its Implications NonStop CORBA can run application servers as server pools. This style of implementation allows many processes to act as one logical server; each new unit of work goes to the next available free server process in the pool. Server processes can run in different processors to allow for parallel processing.
an object interface. ● Server pools. Implications of the use of server pools and whether the use of server pools must be transparent to the application. ● Transaction management. Whether a client or object has responsibility for managing nested transactions. ● Concurrency. Whether clients or an object must coordinate concurrent access to data, and whether the client requires threads. ● Interoperability.
Taking Advantage of Concurrency If your application has the potential for concurrency (that is, it includes thread-blocking operations but not process-blocking operations), you may be able to use multithreading to reduce the number of processes required to handle a given workload. For details, refer to Writing Multithreaded Applications. If your application performs process-blocking operations, you can take advantage of process concurrency by using server pools.
Chapter 10. Porting CORBA Applications to NonStop CORBA Chapter 10. Porting CORBA Applications to NonStop CORBA Global State Information Database Access Applications Using Proprietary Features This section describes general considerations for porting CORBA applications from other ORBs to NonStop CORBA 2.6. For specific details about the NonStop CORBA implementation that may be useful in porting applications, refer to the NonStop CORBA 2.6 Programmer's Reference.
additional rework. Chapter 9. Designing Advanced Applications Chapter 11.
Chapter 11. Using the IIOP/SSL API Chapter 11. Using the IIOP/SSL API SSLIOP IDL Interface SSLIOP::Current SSLIOP::Current::get_peer_certificate() SSLIOP::Current::get_peer_certificate_chain() This section describes the objects used by applications to access IIOP/SSL. The IIOP/SSL features are available for the C++ ORB only. Note: Before you begin to use IIOP/SSL you must have installed the IIOP/SSL option for NonStop CORBA 2.6.
// Exception that indicates a SSLIOP::Current operation was // invoked outside of an SSL session. exception NoContext {}; // Return the active cipher string get_cipher() raises (NoContext); // Return the number of bits in the active cipher int get_cipher_bits() raises (NoContext); // Return the peer certificate DN associdate with the current request. string get_peer_certificate_dn() raises (NoContext); // Return the peer certificate DN associated with the current request.
string cipher; }; typedef sequence ServiceContextBody; }; #pragma prefix "omg.org" }; #pragma prefix "" #endif SSLIOP::Current To obtain a reference to SSLIOP::Current, use the standard CORBA::resolve_initial_references mechanism to pass an objectid string of SSLIOPCurrent.
SSLIOP::SSL_cert_var chain = ssliop->get_peer_certificate_chain(); // walk the cert chain and print the subject and issuer's DN for (int i=0; i < chain->length(); i++) { CORBA::Octet *der_cert = chain[i]; // Use OpenSSL to parse the certificate. // Convert to OpenSSL internal X509 format (DER to Internal X509) X509 *peer_x509 = ::d2i_X509(0, &der_cert, cert->length() ); // Obtain the subject's DN.
Appendix A. Architectural Walkthrough Appendix A.
Figure A-2 expands the view of NonStop CORBA to include several more important concepts. Stubs and skeletons exist for each object type. The ORBs must use one or more transport protocol mechanisms or transport types. If the TCP/IP transport protocol is used, the Bootstrap Service Daemon (BSD), Interoperable Location Service Daemon (ILSD), and Location Service Daemon (LSD) might be called upon, and Comm Servers (CS) might be used. If Comm Servers are used, the LSD must also be used.
A layered architecture view of the NonStop CORBA architecture would look like Figure A-3. In this view the application might be a client, a server, or both. In all cases, the applications use IDL compiler-generated code to communicate with the ORB and POA. If the application needs the Transaction Service, you can link in the OTS run-time. The GIOP layer represents the general inter-ORB implementation. Below the GIOP there are three alternatives.
Walkthrough of Message Flows Using the Naming Service as an Example Message flows in a NonStop CORBA subsystem can be complex. Understanding the patterns is often helpful in debugging an application or tuning for performance. You may find it useful as background information when you deploy applications. This section describes the flow of messages from a client to and from a single service, the Naming Service, as an example of how the flow might happen in a typical application.
● Comm Server receives and relays reply (flows 9 and 10 in the figure). ● Client ORB processes reply. The client is now ready to execute methods against the root naming context. The following sections describe each of the above events in more detail: Naming Service Calls ORB_init (flow 1 in the figure) When the Naming Service calls ORB_init, the NS@ORB entity is read. The ORB sets up a GIOP server component for the configured server transport protocols.
ORB.resolve_initial_references (NameService) , for example), but this relatively simple way is used for this example. Network Client ORB Tries to Contact Target Object (flow 4 in the figure) Once it has the CORBA::Object, the client ORB narrows the reference to a COSNaming Naming Context. The client ORB must determine if the target object is a naming context, so it performs the following: ● Connects to the address in the IIOP profile (LSD). ● Sends an _is_a request to the LSD.
Comm Server Receives and Relays Reply (flows 9 and 10 in the figure) When the server_agent receives the reply, it ● Demarshals the reply through the request ID. ● Interposes original request ID. ● Asks the originating client_agent to relay the reply. The client_agent then relays the reply (flow 10 in the figure), sending the reply message on its connection. Client ORB Processes an is_a Reply Now the client ORB demarshals the reply. It ● Sees the result is true.
Appendix B. Object References Appendix B.
Obtaining Object References NonStop CORBA obtains server IORs at three points: ● Explicitly, when the application calls CORBA::Object::object_to_string(). This action is usually done when an IOR must be "hand delivered" to a client, for example, during initial testing of a system when the Naming Service is being avoided. ● Implicitly, when an object is returned as an out parameter or result for an operation. An example is found in the Naming Service resolve() operation.
NSDOM_GCF_IOP::Profile_Tag Addresses If a server is configured to enable GIOP over TS/MP (tsmp_server true), the profile address will contain pathmon-process-name and server-class. NSDOM_GFS_IOP::Profile_Tag Addresses If a server is configured to enable GIOP over the Guardian file system (fs_server true), the address field will contain a Guardian file system address. If the servant's POA has the PERSISTENT lifespan policy, the profile address will be set to pname.subdevice.
tcp_process $ztc1 host_name oss2.widget.com port_number 0 When NonStop CORBA builds an IOP::TAG_INTERNET_IOP profile, the profile's host field must be in dot-decimal form to avoid having to export the DNS/host-file configuration to every client. Also, the port field must have the actual port number selected by TCP if it was configured as 0.
This behavior is similar to the CORBA process-per-request scenario. Because NonStop CORBA establishes a new TS/MP link to process each request, load balancing occurs at the time of the request. IORs for Stateful Objects in a Server Pool A stateful request (that is, a request for an operation on a stateful object) must always go to the process where the object was created. Therefore, NonStop CORBA generates a reference for a stateful object.
Appendix C. Servant Reference Counting in NonStop CORBA Appendix C. Servant Reference Counting in NonStop CORBA The OMG specification for CORBA 2.6 defines two options for servant reference counting: ● Reference counting using the RefCountServantBase mix-in class ● No reference counting The NonStop CORBA 2.6 product supports both these options and adds a third: reference counting within the CORBA::Object associated with the servant.
void NSDOM_ServantBase::_remove_nsd_ref() { if (_uses_which_ref_type() == Uses_NSDOM_ref_count) { CORBA::release( this->_this_reference() ); } else this->_remove_ref(); } Appendix B.
Index Index Symbols .profile script, OSS Environment Variables and the env.
reconfiguring for scalability, Adjusting TS/MP Configuration Parameters using with Parallel Library TCP/IP, Using Parallel Library TCP/IP broadcast() method, Creating and Using a Condition Variable Buffer size adjusting for performance, Adjusting Message-Buffer Sizes limitations to adjustment, Adjusting Message-Buffer Sizes Building applications, Tips for Building NonStop CORBA Application Components Building transactional clients and servers, Special Considerations for Building Transactional Clients and Se
increasing number of, Increasing the Number of Comm Server Processes reconfiguring for scalability, Adjusting TS/MP Configuration Parameters using with Parallel Library TCP/IP, Using Parallel Library TCP/IP Compiler options (see IDL compiler) Concurrency and client design, Designing a Client and object design, Designing Object Interfaces and Classes and performance tuning, Taking Advantage of Concurrency Condition variable available operations for, Using the NonStop CORBA Portable Threading (vthread) API de
server wrapper with waited calls, Calling a Context-Free or Context-Sensitive Pathsend Server for Waited Operations Control objects considerations for, Control Objects defined, Object Roles and Relationships use of, Designing Object Interfaces and Classes CORBA objects, Development Begins with IDL and CORBA Objects CosTransactions module, Managing Transactions CosTransactions.
Dynamic invocation as a design choice, Designing a Client as alternative to multithreading, Multithreading in Client Applications E ehbase.h header file contents of, Base Event-Handler Interfaces function of, I/O Event-Handler Framework Entity objects considerations for, Entity Objects defined, Object Roles and Relationships env.sh contents, OSS Environment Variables and the env.
Error numbers, Error Numbers Errors IDL compiler, nsdidl Compiler Error Handling vthread API, Error Reporting from vthread Methods esadmin commands, esadmin Tool Commands introduction to, Using the esadmin Tool running, Running the esadmin Tool syntax, The esadmin Tool Syntax Event core, in event framework, Event Core Event framework APIs to, The NonStop CORBA Event Framework APIs contrasted with Event Service, Design of the Event Framework design and function of, Design of the Event Framework registering e
fs_server (see Application profiles) Fw_Client_EH class, Client Event Handler and Event-Handler User Fw_Client_EH_User class functional description, Client Event Handler and Event-Handler User using in TCP/IP server wrappers, Calling a TCP/IP Server Fw_Listener_EH class, Listener Event Handler and Event-Handler User Fw_Listener_EH_User class functional description, Listener Event Handler and Event-Handler User using in Pathsend client wrappers, Writing a Client Wrapper for a Context-Free Pathsend Requester
Fw_Event, Fw_Sock_Client_EH, Fw_Sock_Server_EH, and Fw_Sock_Listener_EH) using in TCP/IP client wrappers, Writing a Client Wrapper for a Remote (TCP/IP) Client Fw_Thread class, Using the NonStop CORBA Portable Threading (vthread) API Fw_Thread object, creating and using, Creating and Using Threads Fw_Transfer_EH class, Transfer Event Handler and Event-Handler User Fw_Transfer_EH_User class, Transfer Event Handler and Event-Handler User G get_message() method, Calling a TCP/IP Server GIOP over Guardian file
ILSD (see Interoperable Location Service Daemon (ILSD)) Indirect TCP/IP server, Addresses Interface Definition Language (see IDL) Interface objects considerations for, Interface Objects defined, Object Roles and Relationships Interface Repository (IR) defined, Introduction to NonStop CORBA Components Interoperable Location Service Daemon (ILSD) defined, Introduction to NonStop CORBA Components reconfiguring for scalability, Adjusting TS/MP Configuration Parameters using with Parallel Library TCP/IP, Using P
J Jacket procedures DCE_BEGIN_TRANSACTION_, Managing Transactions in Server Wrappers DCE_SERVERCLASS_SEND_, Calling a Context-Free TS/MP Server for Nowait Operations for multithreading, Using the NonStop CORBA Portable Threading (vthread) API for process-blocking operations, Multithreading in Server Implementations libraries to use in legacy wrappers, Calling a Context-Free TS/MP Server for Nowait Operations join() method, Using the yield(), join() and cancel() Methods JTS client stub, Components of Transac
defined, Introduction to NonStop CORBA Components reconfiguring for scalability, Adjusting TS/MP Configuration Parameters using with Parallel Library TCP/IP, Using Parallel Library TCP/IP lock() method for a condition variable, Creating and Using a Condition Variable for a mutex, Creating and Using a Mutex Log files (see Tracing) Log messages (see Error logging) log_file (see Application Profiles) LSD (see Location Service Daemon (LSD)) M Makefiles, Makefiles Managing processes, using TS/MP, Writing Your A
N Naming context, defined, Viewing the Naming Service Naming Service adding, renaming, or removing a context, Using the Console to View the Naming Service how to view, Viewing the Naming Service using ns_browse with, Setting Up ns_browse to View the Naming Service viewing or saving an object reference, Using the Console to View the Naming Service viewing with Console, Using the Console to View the Naming Service NonStop CORBA architecture basic (figure), Architectural Walkthrough extended view (figure), Arc
starting and stopping, Running NSDAdminServer and NSDEnvironServer nsdcfgdb (see Configuration database) NSDEFw_GCF class, TS/MP Event Handlers and Event-Handler Users (Class NSDEFw_GCF) NSDEFw_GFS class functional description, Guardian File-System Event Handlers and Event-Handler Users (Class NSDEFw_GFS) using in Pathsend client wrappers, Writing a Client Wrapper for a Context-Free Pathsend Requester NSDEFw_Timer class, Using a Timer for a Thread NSDEnvironServer defined, Components of the NonStop CORBA En
tools, OSS Development and Debugging Tools using Guardian commands and files with, Using Guardian Commands and Files Through OSS ORB other vendor's, Troubleshooting Application Components ORB_CTRL_MODEL threading-policy setting, Multithreading in Server Implementations ORB_init() method used by event framework to launch null thread, Null Thread using to initialize event framework, Writing a Client Wrapper for a Context-Free Pathsend Requester OSS (see Open System Services (OSS)) OTS client stub, Components
port_number (see Application profiles) Portable threading interface (see vthread API) Porting applications from other ORBs, Porting CORBA Applications to NonStop CORBA Preemption not supported on NonStop systems, Using the yield(), join() and cancel() Methods on other platforms, Creating and Using a Mutex Preemption_Mutex class, Creating and Using a Mutex Preprocessing (see IDL compiler) Preprocessor options, IDL compiler, Preprocessor Options Prerequisite knowledge for writing NonStop CORBA applications, B
R Recoverable resource manager (RM) file, Use of TMF Reentrant code, Multithreading in Server Implementations , Creating and Using a Mutex Reference counting, servant, Servant Reference Counting in NonStop CORBA Registering events with event framework, Event Types Remote (TCP/IP) client, legacy wrapper for, Writing a Client Wrapper for a Remote (TCP/IP) Client Remote (TCP/IP) server, legacy wrapper for, Calling a TCP/IP Server Remote client (see Client, network) Remote ORBs, Troubleshooting Application Comp
Server event handler and event-handler user functional description, Server Event Handler and Event-Handler User use in client wrappers, Basic Structure of a Client Wrapper Server pools adjusting configuration for scalability, Adjusting TS/MP Configuration Parameters and Parallel Library TCP/IP, Using Parallel Library TCP/IP and state policy, State Policy and stateless factory objects, Using Stateless Factory Objects to Create Stateful Servants changing processor assignments for, Adjusting TS/MP Configuratio
Server for Waited Operations SERVERCLASS_SEND_ procedure, Calling a Context-Free or Context-Sensitive Pathsend Server for Waited Operations Servers, design considerations for, Designing a Server Services introduction to, Introduction to NonStop CORBA Components Severity levels (see Error logging) showior commands, Examples of showior Commands introduction to, Using the showior tool syntax, The showior Tool Syntax signal() method, Creating and Using a Condition Variable signal_completion() method, Writing a
figure, Listener Event Handler and Event-Handler User using in Pathsend client wrappers, Writing a Client Wrapper for a Context-Free Pathsend Requester using in TCP/IP client wrappers, Writing a Client Wrapper for a Remote (TCP/IP) Client State information, global negative effect on portability, Global State Information negative effect on scalability, Object Distribution State policy choosing for a server wrapper, Calling a Context-Free or Context-Sensitive Pathsend Server for Waited Operations description
T TCP/IP client, legacy wrapper for, Writing a Client Wrapper for a Remote (TCP/IP) Client TCP/IP protocol wrapper for legacy client using, Writing a Client Wrapper for a Remote (TCP/IP) Client wrapper for legacy server using, Calling a TCP/IP Server TCP/IP server direct, Addresses indirect, Addresses legacy wrapper for, Calling a TCP/IP Server tcp_client (see Application Profiles) tcp_process (see Application profiles) tcp_server (see Application profiles) Thread-blocking operations explanation of, Multith
calling the trace facility, Calling the Trace Facility choices in Console, How to Enable and Disable Tracing component categories for, Categories of Tracing enabling and disabling, How to Enable and Disable Tracing enabling for application processes, Trace Settings for Application Processes environment variable options (table), Categories of Tracing example, Simple Tracing Example facility design, Design of the Trace Facility introduction, Using the Trace Facility log file contents, Information Collected in
information in IORs, Object References profile tags in IORs, Content of Object References selecting for clients, profile@ORB Client Transport Protocols selecting for servers, profile@ORB Server Transport Protocols Troubleshooting introduction to, Troubleshooting Application Components naming service, Viewing the Naming Service using esadmin, Using the esadmin Tool using ns_browse, Setting Up ns_browse to View the Naming Service using showior, Using the showior tool using the Console, Using the Console to Vi
Using the IIOP/SSL API, Using the IIOP/SSL API V vthread API cancel() method, Using the yield(), join() and cancel() Methods condition variable, Creating and Using a Condition Variable creating a thread, Creating and Using Threads detaching a thread, Detaching a Thread error reporting, Error Reporting from vthread Methods features of, Using the NonStop CORBA Portable Threading (vthread) API join() method, Using the yield(), join() and cancel() Methods mutual exclusion (mutex), Creating and Using a Mutex te
WRITEREAD requests, Writing a Client Wrapper for a Context-Free Pathsend Requester X XID broker, Transaction Branches and the Diamond Access Problem XID broker process, Components of Transaction Service Implementation Y yield() method, Using the yield(), join() and cancel() Methods Appendix C.
