TIC Server Object Gateway User s Guide

Transcription

1 TIC Server Object Gateway User s Guide Glossary Index Figures Tables What s New in This Manual ix Manual Information ix New and Changed Information ix About This Manual xi Objectives of This Manual Audience xi Organization of This Manual Related Reading xiii Your Comments Invited Notation Conventions xv 1. Introduction to TIC Server Object Gateway (SOG) xiv Benefits of Using TIC Server Object Gateway 1-2 Components of TIC Server Object Gateway 1-3 xi Scenario for Application Development (Design Time) 1-5 Scenario for Application Deployment (Run Time) 1-6 xii Related Concepts and Terminology 1-7 SOG Development Kit and Run-Time Environment 1-7 Using ActiveX Controls 1-7 The Object Manager 1-7 The Host Database 1-8 Preparing and Deploying Your Client Application 1-9 Features of the SOG Run-Time Environment 1-9 SogSupport 1-9 POET2SOG 1-10 Phases of Client Application Development Using TIC Server Object Gateway 1-10 Transaction Innovation Corporation i

2 Contents 2. Installing TIC Server Object Gateway 2. Installing TIC Server Object Gateway Hardware Requirements 2-1 PC Workstation 2-1 NonStop Himalaya host 2-1 Software Requirements 2-1 PC Workstation 2-1 NonStop Himalaya Host 2-1 Installation Procedure 2-2 Menu on the TIC Server Object Gateway Installer CDs 2-2 General Strategy for Development Installation 2-3 General Strategy for Run-Time Installation 2-3 Instructions: NSK Component Installation 2-3 Instructions: NSK Component Configuration 2-4 Instructions: PC Components Installation 2-5 Verifying the TIC Server Object Gateway Installation Getting Started With the Object Manager Steps in Using the Object Manager 3-1 Process Overview: Using the Object Manager Start the Object Manager Open a DDL Dictionary Create a New Service Object in the Service Objects Window Copy DDL Definitions to the Service Objects Workspace Set Service Object Properties and Service Object Element Properties Save and Generate the Service Object Create an Application in the Applications Window Add Service Objects to the Applications Workspace Set Host Properties for the Application Save and Build the Application 3-20 What You Need From the Object Manager for Client Development 3-21 ii

3 Contents 4. Developing Your Client Application 4. Developing Your Client Application Selecting a Client Development Tool 4-2 Differences Between VBScript and the Other Client Tools 4-2 Design Issues 4-3 Introducing TIC Server Object Gateway Tools for Client Development 4-5 SogConnect 4-5 SogLink 4-5 SogServiceObject 4-5 How the SOG Tools Work 4-6 What You Need 4-6 Client Run-Time Steps for TIC Server Object Gateway 4-6 Deciding How to Handle Request and Reply Buffers 4-8 If You Use Direct Buffer Access With Visual C Using the SOG Error Dialog for Testing 4-9 Setting Your AppName in the Error Dialog Caption 4-9 Evaluating Subsystem Errors 4-10 Handling TMF Transactions on the NonStop Himalaya Server 4-14 Sending and Receiving UMS Messages 4-15 Enabling UMS 4-15 Sending UMS Messages on the NonStop Himalaya Host 4-15 Receiving UMS Messages Programmatically 4-15 Code Example Showing UMS Message Routines in Visual Basic 4-16 Indexing Into Request and Reply Messages 4-17 Code Examples in Visual Basic 4-18 Example of TMF Transactions Using Visual Basic or PowerBuilder 4-23 Code Examples in Visual C Code Examples in PowerBuilder 4-29 Considerations and Code Examples in VBScript 4-34 Deployment Procedure 4-36 iii

4 Contents 5. Methods and Properties of SOG Development Objects 5. Methods and Properties of SOG Development Objects Methods of SogConnect 5-2 Properties of SogConnect 5-5 Methods of SogLink 5-9 Properties of SogLink 5-19 Methods of SogServiceObject 5-34 Properties of SogServiceObject Supporting Customer Applications Gathering Information for Problem Solving 6-2 Connecting to the Run-Time Host Database 6-2 Viewing and Changing Server Properties of Applications and Service Objects 6-3 Configuring the SogConnect Component 6-5 Procedure 6-5 Configuring the SogGateway Component 6-6 Procedure 6-6 Testing the SOG Connection to the Host 6-8 Testing UMS Functionality 6-9 Starting the NSKLink Trace Function 6-10 Viewing Type Libraries 6-11 Registering Type Libraries 6-11 Registering Type Libraries for Your Run-Time Installation 6-11 Copying Applications to a Host Database 6-14 Deleting an Application From a Host Database 6-16 Importing an Application Into a Host Database Configur TIC Server Object Gateway Configuring the Host Database and Type Libraries in the Object Manager 7-2 Configuring the OGDBSVR Database Server 7-3 Example of OGDBCNFG Configuration File 7-4 Configuring the NSKLink Servers in the Master Database Pathway Environment 7-5 Starting the SOG Pathway Environment Using the PATHCOOL File 7-6 Stopping the NSKLLSNR and NSKLUMSW Processes 7-6 Example of PATHCNFG Configuration File 7-7 iv

5 Contents 7. Configuring TIC Server Object Gateway (continued) 7. Configuring TIC Server Object Gateway (continued) Moving the Run-Time Master Database 7-9 Increasing the Capacity of a Run-Time Installation 7-10 Configuring Additional SOGDB-SERVER Processes 7-10 Configuring Additional TCP/IP Connections 7-11 Configuring the NSKLink Servers 7-12 Example of NSKLCNFG Configuration File 7-14 Monitoring the NSKLink Servers Using NSKLinkMonitor on the PC Migrating POET Applications to TIC Server Object Gateway Comparing POET and TIC Server Object Gateway 8-1 Introducing the POET2SOG Migration Utility 8-2 Setting PARAMS for POET2SOG 8-3 Running POET2SOG 8-3 A. Messages Installer Messages A-1 PC Installation Messages A-1 Host Configuration Messages A-4 Migration Tool Messages A-7 Object Manager and SogSupport Messages A-13 B. Data Conversion Permissible Data Types B-1 Differences Between Host and PC Data Types B-2 Data Conversion Tables B-3 Data Conversions for PowerBuilder B-3 Data Conversions for Visual Basic and VBScript B-5 Data Conversions for Visual C++ B-7 Data Conversion Errors B-8 C. Errors Reported by SOG Objects v

6 Contents Glossary Glossary Index Figures Tables Figure 1-1. Design-Time Components of TIC Server Object Gateway 1-5 Figure 1-2. Run-Time Components of TIC Server Object Gateway 1-6 Figure 1-3. Phases of Client Development Using TIC Server Object Gateway 1-11 Figure 3-1. Steps in Creating a SOG Application Using the Object Manager 3-2 Figure 3-2. The Object Manager Window 3-3 Figure 3-3. DDL Subvolume Dialog Box Displayed in Object Manager 3-4 Figure 3-4. DDL Window Open in the Object Manager 3-5 Figure 3-5. Service Objects Window and New Service Object Dialog Box 3-7 Figure 3-6. DDL Window and Service Objects Window Open Together 3-9 Figure 3-7. Service Objects Window With Server Tab Displayed 3-12 Figure 3-8. Service Object Element Properties Window Showing Elementary Service Object Element 3-13 Figure 3-9. Applications Window Showing New Application 3-15 Figure Completed SogExampleVB Application 3-17 Figure Host Tab of Applications Window 3-18 Figure 4-1. Client Run-Time Steps Using TIC Server Object Gateway 4-7 Figure 6-1. SogSupport With Copy Applications Dialog Box 6-15 Table 1-1. TIC Server Object Gateway Components on the PC 1-3 Table 1-2. TIC Server Object Gateway Components on the NonStop Himalaya Host 1-4 Table 3-1. Setting Host or Server Properties of Service Objects 3-11 Table 4-1. Subsystem Error Types Used in SOG Error Dialog 4-10 Table 7-1. Commands in the OGDBCNFG Configuration File 7-3 Table 7-2. PARAMS and ASSIGNS for PATHCNFG File 7-5 Table 7-3. Commands in the NSKLCNFG File 7-13 Table 8-1. PARAM Commands for the POET2SOG Migration Utility 8-3 Table B-1. SOG Data Types and DDL Data Types B-1 vi

7 Contents Tables (continued) Tables (continued) Table B-2. Data Conversions for PowerBuilder B-3 Table B-3. Data Conversions for Visual Basic and VBScript B-5 Table B-4. Data Conversions for Visual C++ B-7 Table B-5. Data Buffer Initialization B-9 vii

8 Contents viii

9 About This Manual This manual introduces the TIC Server Object Gateway (SOG), describes the components of SOG, and describes how to use the software to develop a Windows client/transaction server application that is linked to a Pathway server process on a NonStop Himalaya server. Objectives of This Manual Identify, install, and configure the components of the SOG software on the PC and the NonStop Himalaya host. Understand the benefits of using TIC Server Object Gateway to develop Windows client applications. Follow a basic procedure for using the Object Manager to create SOG service objects and SOG applications; and understand what files you need from the Object Manager for client development. Develop a client/transaction server application for the PC using the SOG components with your selected development tool. Deploy your completed client application to run-time workstations, and copy SOG applications to the run-time host database using SogSupport. Migrate existing Pathway Open Environment Toolkit (POET) applications to TIC Server Object Gateway, if desired. Audience This manual is designed for programmers, system administrators, and system managers who are responsible for setting up and managing a TIC Server Object Gateway workstation installation, host installation, or client application. Information is also provided for installing TIC Server Object Gateway components on the NonStop Himalaya host. To use the Object Manager on the development workstation, you need a working knowledge of Microsoft Windows NT 4.0, and of your chosen client development tool (including but not limited to Visual Basic, VBScript, PowerBuilder, and Visual C++). To use SOG, you do not need to have knowledge of or experience with Pathway programming for the NonStop Himalaya server. However, you do need to understand which services of the Pathway server you want to access using your client application. TIC Server Object Gateway makes these services available to you during the development cycle by opening the DDL dictionary on the host that contains the data definitions used by the target Pathway server. An understanding of the Data Definition Language (DDL) or of DDL dictionaries in general is very helpful in working with a DDL dictionary. If your completed client application will exchange requests and replies with a NonStop Himalaya server that is running TMF (Transaction Management Facility), xi

10 About This Manual Organization of This Manual you need to understand how to handle TMF transactions. For information about TMF, see the NonStop Transaction Manager/MP (TM/MP) library manuals listed under Related Reading. Organization of This Manual This manual is divided into eight sections, a glossary, and three appendixes, as follows: Section 1, Introduction to TIC Server Object Gateway (SOG), presents a high-level overview of the functions performed by the major components of the TIC Server Object Gateway and outlines the application development process using the components of Server Object Gateway. Section 2, Installing TIC Server Object Gateway, describes the hardware and software requirements for the PC and the NonStop Himalaya host, and gives detailed steps for installing the Server Object Gateway components. Section 3, Getting Started With the Object Manager, outlines the basic procedures that you use to create SOG entities (service objects and applications) using the Object Manager graphical user interface. Screen examples are given using the sample DDL dictionary installed as part of SOG. Section 4, Developing Your Client Application, includes the following topics: Getting Started With the Server Object Gateway Programming Tools" describes preliminary design issues and programming decisions to make before starting your SOG project, introduces the SOG components that you use in client development, and describes the steps that your completed runtime client application must pass through in using the SOG tools. Programming Decisions and Methodology describes how to use the SogConnect ActiveX control to create a SogLink object that enables your application to communicate with the NonStop Himalaya host, and how to programmatically create the service objects you want to send to the host over the link. Code Examples illustrate how to use the SOG tools in Visual Basic, Visual C++, PowerBuilder, and VBScript. Application Deployment describes procedure for installing your completed client application in a run-time (production) system. Section 5, Methods and Properties of SOG Development Objects lists and describes the methods and properties of the three SOG programming tools or objects (SogConnect, SogLink, and SogServiceObject). Section 6, Supporting Customer Applications, describes the use of the SogSupport application in verifying your TIC Server Object Gateway installation, and testing the connection between the PC and the NonStop Himalaya host. The basic process for deploying a completed client application is also described. Section 7, Configuring TIC Server Object Gateway,gives detailed steps for configuring the TIC Server Object Gateway components and for increasing the capacity of a run-time installation. xii

11 About This Manual Related Reading Section 8, Migrating POET Applications to TIC Server Object Gateway, describes considerations for migrating Pathway Open Environment Toolkit (POET) applications to TIC Server Object Gateway, and gives instructions for using the POET2SOG migration utility. The Glossary defines terms used in this manual for describing the components and use of TIC Server Object Gateway. Appendix A, Messages, lists and defines the diagnostic and informational messages generated by TIC Server Object Gateway components, including the Installer, the migration utility, and the Object Manager and SogSupport applications. Appendix B, Data Conversion, describes how TIC Server Object Gateway handles data conversion between the PC and the NonStop Himalaya host, and describes the data conversion library available with TIC Server Object Gateway. Section C, Errors Reported by SOG Objects, lists and defines the Error code values returned by SOG components at run time. These values are available in the <SogObject>.Error, ErrorText, and ErrorDetail fields. Related Reading For background in programming for a NonStop Himalaya host, see the following Compaq manuals: Introduction to NonStop Transaction Manager/MP NonStop TM/MP Application Programmer s Guide NonStop TS/MP Management Programming Manual Data Definition Language (DDL) Reference Manual For background in Windows programming for the PC using automation and ActiveX controls, see the following publications: ActiveX Development with Visual Basic 5: Windows 95 & Windows NT: The Professional Guide to Programming Internet/Intranet Applications by Evangelos Petroutsos, Ventana Communications, Dave s Book of Top Ten Lists for Great Windows Programming by Dave Edson, M&T Press, Inside Visual C++: Updated for Version 5.0 and Internet Development (Microsoft Programming Series) by David Kruglinski, Microsoft Press, Programming Windows 95 (Microsoft Programming Series) by Charles Petzold, Microsoft Press, Understanding ActiveX and OLE by David Chappell, Microsoft Press, xiii

12 About This Manual Your Comments Invited Your Comments Invited After using this manual, please take a moment to send us your comments. You can do this by returning a Reader Comment Card or by sending an Internet mail message. A Reader Comment Card is located at the back of printed manuals and as a separate file on the TIC User Documentation disc. You can either fax or mail the card to us. The fax number and mailing address are provided on the card. Also provided on the Reader Comment Card is an Internet mail address. When you send an Internet mail message to us, we immediately acknowledge receipt of your message. A detailed response to your message is sent as soon as possible. Be sure to include your name, company name, address, and phone number in your message. If your comments are specific to a particular manual, also include the part number and title of the manual. Many of the improvements you see in TIC manuals are a result of suggestions from our customers. Please take this opportunity to help us improve future manuals. xiv

13 About This Manual Notation Conventions Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. Vertical Line. In describing commands in the Object Manager and SogSupport, a vertical line separates a menu name from a command name in this manual and in the online help. For example, the following sentence refers to the Open DDL Dictionary command in the File menu: Click File Open DDL Dictionary. This sentence describes the Generate command in the Service Objects menu: Use the Service Objects Generate command to produce a service object type library, a data conversion file, and a generated code file.. Period. In names of the methods and properties of the SOG objects, a period separates the object name from the method or property. For example, this is a description of the function of the CreateLink method of the SogConnect object: The SogConnect.CreateLink method creates an instance of the SogLink object for your application. The following sentence describes the Error method of the SogServiceObject object: SogServiceObject.Error returns the SOG error number if a SOG error occurs. xv

14 About This Manual General Syntax Notation xvi

15 What s New in This Manual Manual Information Abstract This manual describes the installation, configuration, use, and management of the TIC Server Object Gateway (SOG). SOG allows Windows application developers to access the services of Pathway servers as if the services were ActiveX objects. This manual is written for Windows developers who use a PC client development tool such as Visual Basic, VBScript, Visual C++, or PowerBuilder, and for system administrators who install and configure the SOG software on the PC and on the NonStop Himalaya host. Product Version TIC Server Object Gateway Version 1.5 Supported Releases N/A Part Number Document History Published May 2000 Part Number Product Version Published TIC Server Object Gateway Version TIC Server Object Gateway Version 1.5 November 1998 May 2000 New and Changed Information The following changes have been made in this edition: VBScript is now supported as a client language. VBScript is a scripting language designed for use with Active Server Pages (ASP), and therefore does not support all the features available with the other client development tools. Specifically, using SOG with VBScript supports only one data type (variant) and does not support return values, direct buffer access, or dialog-box methods. See Differences Between VBScript and the Other Client Tools on page 4-2 for more information. Sample code for VBScript has been provided in Considerations and Code Examples in VBScript on page ix

16 What s New in This Manual New and Changed Information VBScript usage of the methods and properties of SOG objects has been added to Section 5, Methods and Properties of SOG Development Objects. Note that some SOG methods and properties are the same for VBscript and for Visual Basic, while other methods and properties are different for the two languages. Section 3, Getting Started With the Object Manager, was expanded and rewritten to give more detailed instructions. Ten new figures were added to show a working session using the sample DDL dictionary that is installed with TIC Server Object Gateway. The size of a UMS message was given in the first edition as 100 bytes in Sending and Receiving UMS Messages on page This number has been corrected to 1952 bytes. ReleaseServiceObject, a new Service Object method, has been added to Section 5, Methods and Properties of SOG Development Objects. ReleaseServiceObject frees memory space allocated to service objects. ReplyBufferSize, a Service Object property, has been added to Section 5, Methods and Properties of SOG Development Objects. ReplyBufferSize returns the actual size of the reply buffer from the NonStop Himalaya host. The ability to set and change the service object security ID using SogSupport has been added to Section 6, Supporting Customer Applications. You can now set an optional password for connecting to the NonStop Himalaya server using SogSupport. The parameter for setting the password is described in Table 7-1, Commands in the OGDBCNFG Configuration File, on page 7-3. An example of running the PATHCOOL command to restart the SOG Pathway environment has been added to Starting the SOG Pathway Environment Using the PATHCOOL File on page 7-6. The NSKLinkMonitor application is described in Section 7, Configuring TIC Server Object Gateway. NSKLinkMonitor is a PC GUI application that enables you to monitor connections between the NonStop Himalaya server and SOG clients, both development and run-time. The addition of several no fraction data conversion methods is discussed in Appendix B, Data Conversion. The no fraction methods drop the fractional part when converting to a PC long or short data type. Minor corrections and edits were made throughout the manual. x

17 1 Introduction to TIC Server Object Gateway (SOG) TIC Server Object Gateway (SOG) is a set of programs and utilities that you can use to create a Windows client application that will exchange requests and replies with Pathw ay servers to access the databases controlled by the servers. In the SOG client/transaction server environment, the client is a Windows program running on a PC workstation, and the server is a Pathway server running on the NonStop Himalaya host. You can write your client programs using Visual Basic, PowerBuilder, Visual C++, or VBScript. Client programs can can transact with any Pathway server written in COBOL, C, C++, TAL or PTAL. Even though your client applications can use SOG tools to access Pathway services on a NonStop Himalaya system, you need not be familiar with Pathway programming yourself. Your completed client application can take advantage of both the online transaction processing (OLTP) capabilities of the host system and the graphical user interface (GUI) capabilities of the Windows environment on the PC. This section discusses the following topics: Benefits of using TIC Server Object Gateway to develop client/transaction server application SOG components for development and run time on both the PC and the host SOG terminology and concepts, including: Using the SOG development kit and run-time environment Using ActiveX controls Performing Object Manager tasks, including: Creating and generating SOG service objects Creating and building SOG applications Using the SOG host database for development and for run time Develioping and deploying your completed client application Using the SogSupport tool for managing a SOG installation Using the POET2SOG migration utility Phases of client application development using TIC Server Object Gateway 1-1

18 Introduction to TIC Server Object Gateway (SOG) Benefits of Using TIC Server Object Gateway Benefits of Using TIC Server Object Gateway The TIC Server Object Gateway software provides the following benefits: Object-oriented design paradigm TIC Server Object Gateway uses current object technology to enable you to build PC-based client applications that are linked to Pathway server-based transaction processing services. Simple open interface for client/server communication using request and reply messages A client application created using SOG will handle the end-user interface and can perform some business application logic operations on the PC workstation. The target Pathway servers on the NonStop Himalaya host perform database processing and some business application logic operations for the client. IPCs (interprocess communications) are used to transfer data between the client and the server. ActiveX a standard way for applications to share functionality with other applications SOG produces ActiveX objects that can be used in client development. ActiveX is Microsoft Corporation s object-based technology for sharing services and information across process and machine boundaries. Both ActiveX and COM (Component Object Model) are successors to Microsoft s OLE (Object Linking and Embedding) technology. These three technologies share many features. Sharable, reusable code A workgroup of developers can share a SOG host database containing common SOG entities (service objects and applications) to use in their client/server applications. Two easy-to-use graphical user interfaces (GUIs) for the PC: Use the Object Manager to develop SOG service objects and SOG applications. Use SogSupport to support run-time client installations. The end product (after you finish client development using your desktop development tool) is a Windows client application that accesses the host yet appears native to the Windows environment. 1-2

19 Introduction to TIC Server Object Gateway (SOG) Components of TIC Server Object Gateway Components of TIC Server Object Gateway On the PC workstation, TIC Server Object Gateway consists of three major components, described in Table 1-1 Table 1-1. TIC Server Object Gateway Components on the PC PC Component Object Manager SogGateway SogConnect SogSupport Description and Functions A GUI design tool that allows you to construct SOG entities (service objects and applications). Use these entities to create a client application that can access Pathway services on the NonStop Himalaya host. Use the Object Manager to: Copy request and reply message definitions from a DDL dictionary on the host to your workspace on the PC. Create and generate service objects (SOG entities that describe the Pathway services you want to use). Create and build application objects (SOG entities t tha combine a series of service objects performing specifi c tasks). A SOG module that communicates with the PWSVRLNK server on the host in order to handle: Requests to the host Replies from the host An ActiveX control that you use with your client development tool. SogConnect has a CreateLink method that you use to create a SogLink object, which in turn gives you methods for creating and manipulating the service objects that communicate with the Pathway server. A GUI support tool that enables you to manage the SOG applications in the host run-time database, to test the host connection, and to configure SogConnect and SogGateway. 1-3

20 Introduction to TIC Server Object Gateway (SOG) Components of TIC Server Object Gateway On the host, TIC Server Object Gateway consists of the major components listed and des cribed in Table 1-2. Table 1-2. TIC Server Object Gateway Components on the NonStop Himalaya Host Host Component SOG host database SOG database server, OGDBSVR NSKLink servers (PWSVRLNK, NSKLLSNR, and NSKLUMSW) and NSKLinkMonitor POET2SOG migration utility Description and Function A database that stores information about the SOG entities that you create using the Object Manager (service objects and applications). The development host database consists of four files: SOGSOBJ, SOGSOBJE, SOGAPPL, SOGAPPSO. The run-time host database consists of the pertinent application records from the SOGAPPL file, as well as the run-time service objects file specified during development using the Object Manager and copied to the run-time system using SogSupport. A Pathway server configured by the SOG Installer. OGDBSVR manages the SOG host database and also reads DDL dictionaries for the Object Manager (the DDL dictionaries must be D-series or newer releases). Three host servers that handle communication over the TCP/IP link between the PC and the host. NSKLinkMonitor.exe is a PC GUI application that monitors the connections between SOG applications and the host. For information about the NSKLink servers, see Section 7, Configuring TIC Server Object Gateway. For information about using NSKLinkMonitor, see the online help for NSKLinkMonitor. A program that copies services from an existing POET design registry on the NonStop Himalaya host to the SOG t hos database. POET services are thus converted into SOG service objects. See Section 8, Migrating POET Applications to TIC Server Object Gateway for more information about using POET2SOG. 1-4

21 Introduction to TIC Server Object Gateway (SOG) Scenario for Application Development (Design Time) Scenario for Application Development (Design Time) Figure 1-1, shows the components of TIC Server Object Gateway as installed in an application development (design-time) environment. The Object Manager creates the following files on the PC that you use in developing your client application: Type libraries (.TLB files) that contain descriptions of the service objects and applications you create using the Object Manager, including the object properties and methods. Data conversion files (.TDC and.tds files) that contain mapping information needed to format requests and replies between the host and the PC. Generated code files (.BAS,.SRX, or.cpp files) that contain code statements in the selected client language, which you can insert into your client application. The Object Manager sends requests through SogConnect to SogGateway to communicate with the PWSVRLNK server and finally the SOG database server, named OGDBSVR, on the host. The OGDBSVR database server reads records from DDL dictionaries on the host and manages the SOG host database. The host database is composed of four files that contain records describing the SOG entities (service objects and applications) created on the development PC. Figure 1-1. Design-Time Components of TIC Server Object Gateway PC Host Object Manager SogGateway PWSVRLNK OGDBSVR Server Type Library Files Data Conversion Files Generated Code FIles DDL Dictionaries SOG Host Database CDT 001.CDD 1-5

22 Introduction to TIC Server Object Gateway (SOG) Scenario for Application Deployment (Run Time) Scenario for Application Deployment (Run Time) Figure 1-2 shows the run-time components of TIC Server Object Gateway, The Windows client in Figure 1-2 is the completed application that you develop using generated code, the application type library, and the application data conversion file created by the Object Manager. The type libraries and data conversion files are also used during run time by SogConnect and the Windows client. The Windows client uses the SogConnect component to: Retrieve information from the type library and data conversion files as needed by the application at run time. Exchange requests and replies with the target Pathway servers on the host. These requests and replies, which are the heart of the transaction processing that your client application is designed to accomplish, are transmitted using SogGateway and PWSVRLNK (one of the NSKLink servers). The SOG run-time host database contains information about the client application that was created using the Object Manager. The OGDBSVR database server retrieves host information as needed from the SOG host database. Figure 1-2. Run-Time Components of TIC Server Object Gateway PC Host Windows Client SogConnect SogGateway PWSVRLNK Pathway Servers Target Database OGDBSVR Server SOG Host Database App Type Libraries Data Conversion CDT 002.CDD 1-6

23 Introduction to TIC Server Object Gateway (SOG) Related Concepts and Terminology Related Concepts and Terminology Before using TIC Server Object Gateway, you should be familiar with the concepts discussed in the following paragraphs. SOG Development Kit and Run-Time Environment TIC Server Object Gateway consists of a development kit and an application run time environment: The development kit contains the Object Manager and SogSupport interfaces as well as SogConnect and SogGateway. The development kit enables application developers to view DDL dictionaries on the host and use the DDL structures to generate ActiveX objects to use in their PC applications. Development kit components are installed from the Developer s Installer CD as described in Section 2, Installing TIC Server Object Gateway. The run-time environment contains the SogConnect ActiveX control and the SogGateway components that access Pathway servers on the host. The run-time environment enables a client application to exchange requests and replies with a Pathway server. Run-time environment components are installed from the Run-Time Installer CD as described in Section 2, Installing TIC Server Object Gateway. Using ActiveX Controls ActiveX technology enables you to combine and reuse objects in your custom solutions. Any ActiveX-enabled application should be able to use TIC Server Object Gateway. An ActiveX control, such as SogConnect, is an instance of a class that exposes an interface, providing methods, properties, and events that you can access from your client applications. In client development using SOG tools, the DDL data structures of the host appear as ActiveX control properties of the SogServiceObjects you create. Using the SOG tools enables you to invoke a Pathway service and its IPC fields using standard object references. The Object Manager The Object Manager is an easy-to-use GUI that is installed on the design-time PC workstation. You use the Object Manager to create the SOG entities (service objects and applications) that you subsequently use to build your completed client application. 1-7

24 Introduction TIC Server Object Gateway (SOG) The Host Database Creating and Generating Service Objects A service object is a SOG entity that embodies a Pathway service. Each service object contains a request message and an associated reply message. SOG service objects contain the requests and replies that your client application will use to transact with your target Pathway server. The requests and replies are derived from the DDL dictionary associated with that Pathway server. You use the Object Manager to copy the IPCs (interprocess communications) you want from the DDL dictionary to your service object workspace (request and reply messages). Then you save the SOG service object in the SOG host database. You use the Service Objects Generate command to generate sample code in your selected client language, and to create the type library and data conversion files for the service object. Creating and Building Applications An application is a SOG entity that you build from one or more SOG service objects. Using the Object Manager, you copy the service objects that you need for your client application into a SOG application, which you save in the host database. Then you use the Applications Build command to create a run-time service objects file, and to create the type library and data conversion files for the application. The Host Database TIC Server Object Gateway maintains a database on the host. The SOG host database is: Managed by the SOG database server, OGDBSVR. For design time, composed of four files that store information about the SOG entities you create using the Object Manager. For run time, composed of only the application database file and the run-time service objects files associated with the applications you re using. To view the property values for the entities stored in the host database, use the Object Manager and SogSupport. Development Host Database Several developers can share a single host database for developing their own custom client applications that access Pathway servers. During development, the Object Manager uses the following four database files: SOGAPPL stores information about SOG applications. SOGAPPSO stores information about SOG application service objects. SOGSOBJ stores information about SOG service objects. SOGSOBJE stores information about SOG service object elements. 1-8

25 Introduction to TIC Server Object Gateway (SOG) Preparing and Deploying Your Client Application Run-Time Host Database At run time, your completed client application needs only the application records from the SOGAPPL file, as well as the run-time service objects file. You will also need the application type library and application data conversion files created by the Object Manager. For details, see Deployment Procedure in Section 4, Developing Your Client Application. Preparing and Deploying Your Client Application After building a SOG application using the Object Manager, you can then develop your client application using your selected development tool (such as Visual Basic, Visual C++, PowerBuilder, or VBScript). To deploy a completed client application, you install the run-time SOG components on both the PC and the host, copy your completed client application to the client workstations, and use SogSupport to copy the SOG application information needed for run time. For more information, see Deployment Procedure on page Features of the SOG Run-Time Environment The TIC Server Object Gateway run-time environment provides: Waited sends to Pathway servers TMF transaction management Unsolicited Message Service (UMS) support Automatic data conversion for individual fields in the request and reply messages Data trace facility Error reporting SogSupport Use the SogSupport tool to configure and manage SogConnect and the SogGateway module and to deploy your completed client application. Use SogSuppor to: Manipulate the PC registry entries used by TIC Server Object Gateway and SogConnect Validate installation of the SOG development kit and run-time environment Enable and disable data tracing by SogConnect and SogGateway Copy the necessary SOG application information from the development system to the run-time system as part of application deployment Alter configuration information for SOG applications in the host database Change the security ID associated with individual service objects For more information, see Section 6, Supporting Customer Applications. 1-9

26 Introduction to TIC Server Object Gateway (SOG) POET2SOG POET2SOG The POET2SOG migration utility provides a migration path for current POET (Pathway Open Environment Toolkit) users. POET2SOG converts POET services to a SOG host database. Then you can use the Object Manager to manipulate the service objects tha t represent the POET services. For more information, see Section 8, Migrating POET Applications to TIC Server Object Gateway. Phases of Client Application Development Using TIC Server Object Gateway After installing and configuring TIC Server Object Gateway (as described in Section 2, Installing TIC Server Object Gateway), you must proceed through three major phases of client development using the SOG components (Figure 1-3). 1. Using the Object Manager: a. Browse a DDL dictionary on the host and select the request and reply messages that constitute the interprocess communication (IPC)s of the Pathway services you will use in your client application. b. Create SOG service objects and add the request and reply messages that you select from the DDL dictionary. c. Use the Service Objects Generate command for each service object. The Generate command yields a service object type library, a service object data conversion file, and a generated code file that you can use in Phase 2. d. Create a SOG application and add to the application the service objects generated in step 2c. e. Use the Applications Build command to produce an application data conversion file, an application type library, and a run-time service objects file that you will use in Phases 2 and 3. For more information about using the Object Manager, see Section 3, Getting Started With the Object Manager and see the online help for the Object Manager. 2. Use your selected client development tool along with the SOG development tools to create your application. You must use the SogConnect.OCX ActiveX control as well as the following files created with the Object Manager in Phase 2: Application type library file (.TLB file) Application data conversion file (.TDS file) Run-time service objects file (located on the host) Generated code file in your selected client language (.BAS, CPP, or.srx file) For more information about using the SOG tools, see Section 4, Developing Your Client Application. 1-10

27 Introduction to TIC Server Object Gateway (SOG) Phases of Client Application Development Using TIC Server Object Gateway (Figure 1-3 shows the three phases of client development in the context of the development and run-time environments. The SOG development environment is also a fully operational run-time environment. This means you can test your client application during the design phase before deploying the completed application to the run-time environment.) Figure 1-3. Phases of Client Development Using TIC Server Object Gateway PC Host Design PC Development Host Phase 1 Object Manager Tasks DDL Dictionaries Phase 2 Client Development OGDBSVR Server SOG Host Database Run-Time Client PC Run-Time Host Phase 3 Completed Client Application Pathway Server OGDBSVR Server Target Database SOG Host Database CDT 003.CDD 3. Install and configure the run-time (production) system: On the client workstations: Use the SOG Run-Time Installer CD to install the SOG workstation runtime components. Install your completed client application. 1-11

28 Introduction to TIC Server Object Gateway (SOG) Phases of Client Application Development Using TIC Server Object Gateway Copy the application type library and the application data conversion file from the development PC and register the type libraries. On the NonStop Himalaya host: Use the SOG Installer to install and configure the SOG host run-time components. See Section 2, Installing TIC Server Object Gateway for more information and procedures. Use SogSupport on the run-time PC to copy the application information from the development host system to the run-time host system (including the run-time service objects file). For more information about phase 3, see Deployment Procedure on page 4-36 and Section 7, Configuring TIC Server Object Gateway. 1-12

29 2 Installing TIC Server Object Gateway This section lists the hardware and software requirements for TIC Server Object Gateway and describes installation and verification procedures for both the PC and the NonStop Himalaya host. Hardware Requirements PC Workstation Minimum 486/66 processor (Pentium processor preferred) Minimum memory size 32 MB for NT 4.0 or 24 MB for Win95 NonStop Himalaya host NonStop Himalaya server Software Requirements PC Workstation Either: Windows NT 4.0 with Service Pack 3 and TCP/IP, or Windows95 with DCOM95 (downloadable from the Microsoft web page, and TCP/IP Client (development) language that supports ActiveX and COM (such as Visual Basic 5 or higher, PowerBuilder 5 or higher, Visual C++ 5 or higher, or VBScript) NonStop Himalaya Host TIC Kernel operating system supporting Native C, running either: D42 release or higher, or G02 release or higher Required products: TCP/IP, TS/MP (Pathway), TM/MP (TMF) The SOG Installer program configures and starts several Pathway servers for TIC Server Object Gateway. 2-1

30 Installing TIC Server Object Gateway Installation Procedure Installation Procedure TIC Server Object Gateway has two installer compact discs (a Developer s Installer CD and a Run-Time Installer CD). The two CDs contain installable components for both the host and the PC. Insert the appropriate CD into a PC connected over TCP/IP to the the NonStop Himalaya host. Developer s Installer CD: Installs the design-time or development components of TIC Server Object Gateway on the: NonStop Himalaya host Development PC workstations Configures the NonStop Kernel host components for design time. Run-time Installer CD: Installs the run-time components of TIC Server Object Gateway on the: NonStop Himalaya host Run-time client PCs Configures the NonStop Kernel host components for run time. The general procedure is the same for the developer s and the run-time installation. Menu on the TIC Server Object Gateway Installer CDs When either of the installation CDs are autorun, a menu of options is presented. Select the function you want to perform from that list. Instructions for installation are included on the CD. Running the Tutorial The tutorial is part of the SOG installation on the PC. Run the Tutorial from the developer' s CD or the SOG installation directory for a "live" way to learn how to use the Object Manager. You can choose to run the tutorial as a demo (you won't need to touch the keyboard or mouse) or as a tutorial (you must make selections as instructed). 2-2

31 Installing TIC Server Object Gateway General Strategy for Development Installation General Strategy for Development Installation Use the Developer s Installer CD as follows: 1. Perform an NSK Component Installation on each host that is to be used in the development installation. 2. Perform an NSK Component Configuration on each host. You can either specify the same SOG host database for each development workgroup, or specify different host databases for each workgroup. Having one host database for all SOG developers ensures that application and service object names are unique. 3. Perform a PC Components Installation on each developer PC. General Strategy for Run-Time Installation Use the Run-Time Installer CD as follows: 1. Perform an NSK Component Installation on each host that is to be used in the runtime installation. 2. Perform an NSK Host Component Configuration on each host and specify the same SOG host database for each run-time group that will be using TIC Server Object Gateway. 3. Perform a PC Components Installation on each run-time PC. 4. Install your completed client application on each run-time PC (see Deployment Procedure in Section 4 for more details). Verifying the TIC Server Object Gateway Installation 1. On the NonStop Himalaya host, run the PATHCOOL obey file (created by the Installer in the SOG subvolume). This restarts Pathway. 2. Verify that the $SOG server is running: a. At the TACL prompt, enter: >status $SOG 2-3

32 Installing TIC Server Object Gateway Instructions: NSK Component Configuration b. Then start PATHCOM and include the process name of the SOG PATHMON server. Use the STATUS SERVER command to verify that the SOG Pathway servers are running, as follows: >pathcom $sog =status server * SERVER #RUNNING ERROR INFO EXAMPLE-SERVER 1 NSKLLSNR-SVR 1 NSKLUMSW-SVR 1 PWSVRLNK-SERVER SOGDB-SERVER 1 1 $SOG is the default name for the TIC Server Object Gateway PATHMON process. However, this process name might be changed during host configuration. The SOG PATHMON process name should also be shown in the PATHCOOL file, located on the SOG installation subvolume on the NonStop Himalaya host. The TACL STATUS command displays the process status, including CPU numbers, swap file and program file name (PATHMON is the program file name). The PATHCOM STATUS SERVER command lists the Pathway servers for TIC Server Object Gateway. Note that EXAMPLE-SERVER is present only on design (development) installations. 2-4

33

34

35 3 Getting Started With the Object Manager This section describes the tasks you need to perform using the Object Manager. These instructions use the examples that are installed with TIC Server Object Gateway. In fact, you can perform the same steps on your development PC using the sample DDL dictionary and SOG host database. For more detailed information, see the online help; the online help is intended to be the primary documentation for the Object Manager. Steps in Using the Object Manager The general strategy for using the Object Manager includes the following steps, all of which are described in detail in this section: 1. Start the Object Manager. 2. Open one or more DDL dictionaries on the host. 3. Create a service object in the Service Objects window workspace. 4. Copy request and reply message definitions from the DDL dictionary to your workspace in the Service Objects window. 5. Set selected properties of the service object, such as the client language to be used, the data conversion to be performed, and the names of the data elements. 6. Generate the service objects using the Service Objects Generate command. Generating a service object saves the service object properties to the SOG host database and creates the following files, all on the PC: A service object type library (<service-object>.tlb file) A data conversion file (<service-object>.tdc file) A generated code file in your chosen client language 7. Create a SOG application in the Applications window workspace. 8. Add the generated service objects that you want to use in your client application. 9. Set host properties for the application as a whole. 10. Build the application using the Applications Build command. Building an application saves the application to the SOG host database and creates these files: An application type library (<application>.tlb file) on the PC A data conversion file (<application>.tds file) on the PC A run-time service objects file on the NonStop Himalaya host (necessary for run-time deployment of your completed client application) 3-1

36 Getting Started With the Object Manager Process Overview: Using the Object Manager You can also perform the following tasks using the Tools menu commands: View the type libraries created by SOG. Compare IPC modification dates in a DDL dictionary to those in a service object. Display IPC references (list the service objects that use a selected IPC). Display and modify the configuration of the host database and the type libraries. Process Overview: Using the Object Manager Figure 3-1 shows the process of copying IPCs from a DDL dictionary to a SOG service object, then combining service objects into a SOG application. In developing your client, you need to use the the SOG programming tools and the files produced by the Build Applications command. For more information, see What You Need From the Object Manager for Client Development on page 3-21 Figure 3-1. Steps in Creating a SOG Application Using the Object Manager DDL window. Copy DDL definitions to the Request Message and Reply Message fields of your service object. Service Objects window. Set the service object properties and generate the service object. Applications window. Add service objects to your application, set the application properties, and build the application. DDL Dictionary add_contact_req add_contact_rep delete_contact_req delete_contact_rep... AddContactVB Request Message add_contact_req Reply Message add_contact_rep SogExampleVB ServiceObjects MyFirstSO AddContactVB MyNextSO Generate Files: Generated code SrvObj. type library SrvObj. data conversion Build Files: Run-time service objects App. type library App. data conversion CDT 004.CDD 3-2

37 Getting Started With the Object Manager 1. Start the Object Manager 1. Start the Object Manager On your development PC, select the Object Manager from the Start menu, or double- click the SogObjectManager.EXE file. The Object Manager window (Figure 3-2) has seven menus of commands (File, Service Objects, Applications, and so on. A button bar provides shortcuts to selected commands. In the Object Manager, you can open three other working windows: DDL, Service Objects, and Applications, as shown in the figures in this section. Figure 3-2. The Object Manager Window CDT 012.CDD Online Help Online help is available in several ways: selecting from the Help menu, pressing the F1 key, or clicking the Help button on dialogs. You can also get online help for specific commands by using either of the following methods: Select a menu title and press F1. Hold the cursor on a button in the button bar to display popup help for the button. 3-3

38 Getting Started With the Object Manager 2. Open a DDL Dictionary 2. Open a DDL Dictionary Select the File Open DDL Dictionary command or click the Open DDL Dictionary button (the button labeled with a file folder on the far left of the button bar). A DDL dictionary contains the request and reply messages expected by a Pathway server. You can, however, use request and reply messages from two different DDL dictionaries. Enter the DDL Subvolume Name Figure 3-3 shows the Open DDL Dictionary dialog box. Specify the name of the subvolume on the NonStop Himalaya host that contains the DDL dictionary you want to use. This example uses the sample DDL dictionary installed with SOG on the host. (The installation subvolume is specified at installation time and is not predefined.). After you open a DDL dictionary, that DDL subvolume name becomes the default value and is displayed the next time you invoke the Open DDL Dictionary dialog box. In addition, the entry field on the dialog box has a drop-down list of previous entries from which you can select (like many entry fields in the Object Manager). Figure 3-3. DDL Subvolume Dialog Box Displayed in Object Manager CDT 011.CDD 3-4

39 Getting Started With the Object Manager 2. Open a DDL Dictionary Note. If you receive an error message when you try to open a DDL dictionary, you might need to configure the connection to the host database, as described in Configuring the Host Database and Type Libraries in the Object Manager on page 7-2. Also see the description of Object Manager error messages in Appendix A, Messages. Examining the DDL Dictionary in the DDL Window The DDL window displays the DDL definitions contained in the DDL dictionary. The expanded sample DDL dictionary is shown in Figure 3-4. Like all the Object Manager windows, the DDL window has a tree control on the left-hand side that displays the objects, while the right-hand side displays the properties of the currently selected element. Figure 3-4. DDL Window Open in the Object Manager CDT 005.CDD The DDL window displays: The records and definitions contained in the DDL dictionary, in the tree control on the left-hand side. In the sample DDL dictionary, the first interprocess communication (IPC), named add_contact_req, is expanded in Figure

40 Getting Started With the Object Manager 3. Create a New Service Object in the Service Objects Window The properties of the currently selected DDL element, on the right-hand side (the DDL Element Properties window). White fields contain values that you can change. Gray fields cannot be changed. Note. All windows in the Object Manager are resizeable. You can tile the windows and adjust their sizes so that all the fields are easily visible. 3. Create a New Service Object in the Service Objects Window Open your workspace in the Service Objects window and get ready to create your service objects. Use one of the following methods: Select the Service Objects Show command followed by Service Objects New. The Show command displays the service objects currently in the host database.) The New command creates an empty service object containing blank Request and Reply Messages. Select the Service Objects New command. This creates a new service object containing blank Request and Reply Messages for you to populate, and also displays in your workspace the service objects currently stored in the host database. Instead of menu commands, you can use the buttons on the button bar that are equivalents for these two Service Objects commands: The button labeled with a hammer invokes Show Service Objects. The hammer-and-plus-sign invokes New Service Object. Window Title Indicates Whether Changes Have Been Saved to Host Database When you open the Service Objects window, the original window title is: Host Database:Service Objects This title indicates that the screen is simply listing the service objects in the host database. After you make any change to a service object, the window title changes to: Workspace:Service Objects This title indicates that the screen is listing the service objects in your workspace, and that you have made changes to your copy of the service objects from the host database. Your changes are saved to the host database only when you invoke a Save command. Afterwards, the window title reverts to: Host Database:Service Objects There are three Save commands in the Object Manager: File Save Host Database saves all changes made in the workspace to service objects or applications. Service Objects Save All saves changes made to service objects only. Applications Save All saves changes made to applications only. 3-6

41 Getting Started With the Object Manager 3. Create a New Service Object in the Service Objects Window Enter the Service Object Name Enter a name in the Service Object Name field, shown in Figure 3-5. Click the Help button for information about service object names. For illustrative purposes, this section of the manual uses AddContactVB, which is part of the sample host database provided with SOG. While reading this section, you can create a new service object by supplying a name of your choice, or you can simply open AddContactVB and read these instructions without making any changes to the host database. Remember that any changes you make in your workspace are not actually made to the host database until you use one of the Save commands (File Save Host Database, Service Objects Save All, or Applications Save All.) Note. If the host database is not correctly configured, an error message is displayed. For a description of Object Manager messages, see Appendix A, Messages. To configure the host database, see Configuring the Host Database and Type Libraries in the Object Manager on page 7-2. Figure 3-5. Service Objects Window and New Service Object Dialog Box CDT 006.CDD 3-7

42 Getting Started With the Object Manager 4. Copy DDL Definitions to the Service Objects Workspace 4. Copy DDL Definitions to the Service Objects Workspace With both the DDL and Service Objects windows open (see Figure 3-6, DDL Window and Service Objects Window Open Together, on page 3-9), you are ready to begin constructing your service objects, as follows: Double-click the new service object in the Service Objects window or expand it by clicking on the plus-sign (+) in front of its name. Make sure the empty Request Message and Reply Message fields are visible. Browse the DDL dictionary and locate the IPCs you want to use in this service object (typically, you ll be looking for request and reply messages). Drag-and-drop (or copy-and-paste) the IPCs from the DDL dictionary to the Request Message and Reply Message fields in your service object. For example, to add the add_contact_req IPC to the request message in the AddContactVB service object, first expand the service object so that the Request and Reply Message fields are visible. Then click on add_contact_req and drag it to the Request Message field. Note. When you drag an object in the Object Manager, the cursor functions as a cue: A crossed-circle (international No sign) appears if you cannot drop the object in the selected field. A plus sign indicates that you can drop the object in the selected field. Figure 3-6 shows the Object Manager with the DDL and Service Objects windows open and tiled horizontally. With windows tiled in this way, you can see and access both sides of each window: that is, the objects on the left, as well as their properties on the right. In the DDL window in Figure 3-6, the DDL definition add_contact_req is selected, and the properties for add_contact_req are displayed on the right-hand side of the window. Similarly, in the Service Objects window in the figure, the service object AddContactVB is expanded and selected, as indicated in the title of the Service Object Properties window on the right. 3-8

43 Getting Started With the Object Manager 4. Copy DDL Definitions to the Service Objects Workspace Figure 3-6. DDL Window and Service Objects Window Open Together CDT 007.CDD 3-9

44 Getting Started With the Object Manager 5. Set Service Object Properties and Service Object Element Properties 5. Set Service Object Properties and Service Object Element Properties After you ve copied the request and reply messages into your service object, you can set client, server, and security properties on the Service Objects window. Deciding Which Properties to Set The client, server, and security tabs on the Service Objects window contain fields that you need to set at some point in order to use your service objects. However, if all the service objects in your application will have the same values for the server fields, you can choose to set the server properties later, at the application level. Set Client Properties for Each Service Object This window is your only opportunity to set the client properties (client language, data conversion, and Generate IPC structures). Set these properties on the client tab of the Service Objects window, shown in Figure 3-6. The client property values are used in generating the individual service objects and the generated code file. A typical strategy is to accept the Automatic data conversion in every case, but to select Generate IPC structures only if you are planning to use direct buffer access. See the online help for more information about these properties. Set Server Properties for Service Objects or for Application as a Whole Setting or changing the three host or server properties (Pathmon system, Pathmon process, and Server class) can be done either for the service objects individually or for the application as a whole. However, if the server properties are set in the Object Manager for both the service object and the application, SOG uses the value set at the service object level. To save time and effort, leave these fields blank in the Service Objects window (Server tab, shown in Figure 3-7), and set the server properties later, on the Applications window, so long as all your service objects are to have the same host or server values. If you need to change these properties later, you can change them for the entire application at once by using the Applications Properties window in the SogSupport application. Table 3-1, Setting Host or Server Properties of Service Objects lists all the client, server, and security properties, and summarizes how you can set or change the property values. For example, in the Object Manager, you can set the Host name and Host port properties for an application as a whole, but you cannot set Host name and Host port for individual service objects. Table 3-1 also shows that both of these properties can be set programmatically at the link level using the SogLink properties, but cannot be set programmatically for individual service objects. In addition, you can set the security ID for individual service objects in either the Object Manager or SogSupport, but you cannot set the security ID programmatically using the properties of the SOG objects. As a final example, you must set the run-time service objects file for an application using either the Object Manager or SogSupport, because you cannot set the run-time service objects file programmatically. 3-10

45 Getting Started With the Object Manager 5. Set Service Object Properties and Service Object Element Properties For more information about setting server properties using the SOG GUIs and SOG objects, see Order of Precedence for Server Properties on page 6-4. Table 3-1. Setting Host or Server Properties of Service Objects Property Name Object Manager SogSupport SOG Object Properties Svc Obj Applic Svc Obj Applic SogLink SSvcObj Pathmon System Yes Yes Yes Yes Yes Yes Pathmon Process Yes Yes Yes Yes Yes Yes Server Class Yes Yes Yes Yes Yes Yes Host Name/Addr -- Yes -- Yes Yes -- Host Port -- Yes -- Yes Yes -- Name of run-time service objects file -- Yes -- Yes Security ID Yes -- Yes How to Set Service Object Properties Select the service object name as a whole. Then supply values for any of the following fields (on the Service Objects Properties window) that you want to specify for the individual service object rather than for the application as a whole: On the Client tab (shown in Figure 3-5, Service Objects Window and New Service Object Dialog Box): Select the client language you will use to develop your client application (such as Visual Basic, Visual C++, PowerBuilder, or VBScript). Even if you plan to use another ActiveX-enabled client development tool, select one of the available languages. The client language you select determines the elements and formatting in the generated code file produced by the Object Manager, and the data conversion used at run time. See the online help for more information and guidelines. Specify whether SOG is to convert data automatically between PC and host formats. If you do not select automatic data conversion, you must provide your own data conversion in your completed client application. See Appendix B, Data Conversion for information about automatic data conversion. Specify whether SOG is to generate IPC structures in the generated code file. You might want to specify this option in order to use direct buffer access or to simplify migration from the Pathway Open Environment Toolkit (POET). The generated code file defines all the individual fields of your service objects, and you can set and retrieve the value of each elementary item in the IPC using those fields. If, however, you want to use the IPC buffer directly, click Generate IPC Structures. 3-11

46 Getting Started With the Object Manager 5. Set Service Object Properties and Service Object Element Properties Figure 3-7. Service Objects Window With Server Tab Displayed CDT 016.CDD On the Server tab (shown in Figure 3-7, Service Objects Window With Server Tab Displayed), specify values describing the Pathway server that will communicate with your application, as follows (specify only the values that you want to take effect at the service object level, to avoid later having to change these values for every service object rather than for the application as a whole): Specify the Pathmon system name (the system name of the host) if the service object is to have a different Pathmon system than the SOG application as a whole. Specify the name of the target Pathmon process (the Pathmon process for the target Pathway system) if the service object is to have a different Pathmon process than the SOG application as a whole. Specify the server class of the target Pathmon process if the service object is to have a different server class than the SOG application as a whole. The example in Figure 3-7 uses the SOG example-server, which is installed only on SOG development installations. 3-12

47 Getting Started With the Object Manager 5. Set Service Object Properties and Service Object Element Properties Specify the server language (COBOL, TAL or C) used by the target Pathway server. Select C if the server is using C++. Select TAL if the server uses ptal. On the DDL tab, there are no fields that you can change for a service object. On the Security tab, specify an optional security ID if you want to require the client application to include the security ID at run time in order to use the service object. Set Service Object Element Properties (Optional) Perform this step only if you want to change the default element name or default data conversion. In the tree control on the Service Objects window, expand each service object completely and then select each elementary data item in turn. On the right-hand side, the Service Objects Elements Properties window lists the properties of the selected element, as shown in Figure3-8. Figure 3-8. Service Object Element Properties Window Showing Elementary Service Object Element CDT 008.CDD 3-13

48 Getting Started With the Object Manager 6. Save and Generate the Service Object On the Properties tab of the Service Objects Elements Properties window, you can modify the element name, which is the name you will use in your completed client application to refer to this field. You can also select a different type of automatic data conversion. See the online help and Appendix B, Data Conversion for more information and guidelines. The Redefinition tab has no fields that you can change, but it is affected by the Direct Buffer Access tab. On the Direct Buffer Access tab, if you are using direct buffer access and if your service object contains any fields characterized by DDL Redefines, you must specify the discriminator value for those discriminated unions. The discriminator determines which element is converted. See the online help for more information about discriminators. 6. Save and Generate the Service Object After completing the fields that you want to set for the service object, use the Service Objects Save All command to save your workspace to the host database. Select each service object in turn and use the Service Objects Generate command. The Service Objects Generate command produces the following files: A service object type library (.TLB file). A service object data conversion file (.TDC file). A generated code file that you can use in developing your client application. You must specify a location on your PC for the generated code file produced by the Generate command. You can overwrite or append to an file. Caution. If you subsequently make changes to any service object that you ve placed in your application, you must regenerate the service objects and rebuild the application in the Object Manager. 7. Create an Application in the Applications Window Open a workspace in the Applications window and get ready to create an application, using one of the following methods: Show Application button followed by the New Application button) Select the Applications New command (or click the New Application button) Select the Applications Show command followed by Applications New (or click the Both Applications Show and Applications New commands open the Applications window and display the applications currently in the host database, but the New command also gives you a new, empty application for you to populate with service objects. 3-14

49 Getting Started With the Object Manager 7. Create an Application in the Applications Window Enter the Application Name Enter an application name of your choice in the New Application dialog box (not shown in a figure, but similar to the New Service Object dialog box shown in Figure 3-5). This section of the manual uses one of the example applications, SogExampleVB, that is part of the sample host database installed with SOG. Figure 3-9, Applications Window Showing New Application, shows the Applications window after creating a new, empty application. Note that the empty application contains a placeholder for the service objects you will add in the next step. On the Service Objects tab, all the service objects in the host database are listed in the Design Service Objects list. The service objects that you copy into your application will be listed in the Service Objects in Application list. Figure 3-9. Applications Window Showing New Application CDT 009.CDD 3-15

50 Getting Started With the Object Manager 8. Add Service Objects to the Applications Workspace Window Title Indicates Whether Changes Have Been Saved to Host Database When you open the Applications window, the original display title of the window is Host Database:Applications. This title indicates that the screen is listing the applications contained in the host database. After you make any change to the applications, the window title changes to Workspace:Applications, indicating that the screen is listing the applications in your workspace and that you have made changes that have not been saved to the host database. Changes are saved to the host database only when you invoke the Applications Save All command. After the save completes, the window title reverts to Host Database:Applications. 8. Add Service Objects to the Applications Workspace Select the application name and then add or delete service objects from the list of Design Service Objects on the Service Objects tab of the Application Properties window. To add a selected service object, use drag and drop, or click the Add Service Object to Application button. To delete a selected service object from the application, click the Delete Service Object from Application button. After the SogExampleVB application is populated with three service objects, the Applications window appears as in Figure 3-10, Completed SogExampleVB Application. Note. All service objects that you want to use in your application must be generated (as described in step 6) before you can perform the next step (Applications Build). You can place all the service objects for your client application in one SOG application, or in several SOG applications. However, all service objects that will be handled in the same TMF transaction must be placed in the same SOG application. 3-16

51 Getting Started With the Object Manager 8. Add Service Objects to the Applications Workspace Figure Completed SogExampleVB Application CDT 010.CDD 3-17

52 Getting Started With the Object Manager 9. Set Host Properties for the Application 9. Set Host Properties for the Application On the Host tab of the Applications Properties window (shown in Figure 3-11), verify or change the values for the following host properties of your application: The run-time service objects file (the name of the file to be created on the host that will contain the service object information for this application) Pathmon system name (the name of the host on which the application will run) The target Pathmon process (the name of the Pathmon process on the host) The server class of the target Pathway server, such as SOGDB-SERVER or EXAMPLE-SERVER (as used in the examples) Host name/ip address of the target host system (as defined for TCP/IP) Host port number (TCP/IP) to be used to connect to the host system Figure Host Tab of Applications Window CDT 013.CDD 3-18

53 Getting Started With the Object Manager 9. Set Host Properties for the Application About Setting the Host Properties for the Application or the Service Object The five host properties listed above (System, Pathmon, Server class, Host name, and Port) must be specified at some point for your application. You can set various ones of these properties in several different ways: On the Service Objects Properties window On the Applications Properties window Using the SogSupport application Programmatically, using the properties of SogLink and SogServiceObject as described in Section 5, Methods and Properties of SOG Development Objects For a summary of how to set each property, see Table 3-1, Setting Host or Server Properties of Service Objects, on page If you set the Host properties for the application as a whole, it is simpler to change the property values later using SogSupport than it would be if you set the properties for the individual service objects. Keep in mind also that not all the properties can be set using any one method; for example, the run-time service objects file and the security ID cannot be set programmatically. Some Properties Are Required Before Building an Application The Applications Build command requires that the following properties must be set before you can build an application in the Object Manager: Pathmon process name Server Class Run-time service objects file If you don t know the run-time values for these properties, you can set any Pathmon process name or server class name in order to complete a build. Later you can change the values for these properties using either SogSupport or the SOG programming tools. However, the run-time service objects file can only be changed later by using SogSupport, not the SOG programming tools. 3-19

54 Getting Started With the Object Manager 10. Save and Build the Application 10. Save and Build the Application After completing the fields that you want to set for the application, use the Applications Save All command to save your workspace to the host database. Select each application in turn, and use the Applications Build command. The Applications Build command yields the following files: File <application>.tlb file <application>.tds file Host run-time service objects file Description SOG application type library SOG application data conversion file SOG host database file containing application information such as definitions of the service objects contained in the application. Specify the file name on the Host tab of the Applications Properties window. Assign a unique run-time service objects file to each application, or assign one file to several SOG applications. Use SogSupport to copy the SOG application information (specifically, the host run-time service objects file) to the run-time host system when you deploy your completed client application. Note. If the Build command fails, you may need to generate the service objects that are part of your application. For more information about error messages, see Object Manager and SogSupport Messages on page A-13. If you subsequently make changes to any service object that you ve placed in your application, you must regenerate the service objects and rebuild the application. 3-20

55 Getting Started With the Object Manager What You Need From the Object Manager for Client Development What You Need From the Object Manager for Client Development In developing your client application, you need to use several of the files that you create using the Object Manager. PC Files Have the following files available in your PC development environment: File Description Origin <application>.tlb file <application>.tds file Generated code file Host File SOG application type library SOG application data conversion file.bas,.cpp,.srx, or.vbs file Produced by Applications Build command Produced by Applications Build command Produced by Service Objects Generate command During deployment of your completed client application, use SogSupport to copy the application records from the following file to the target host system: File Description Origin Host run-time service objects file Contains host information about the service objects in the SOG application Produced by Applications Build command. The file name is specified on the Host tab of the Application Properties window in the Object Manager. Section 4, Developing Your Client Application describes the details of client development. For a description of the files you need at run time, see Deployment Procedure on page For example, the <application>.tlb and <application>.tds files are needed on the PCs where the client application is to run. After you copy the files to the PC, use SogSupport to register the type libraries as described in Registering Type Libraries on page

56 Getting Started With the Object Manager What You Need From the Object Manager for Client Development 3-22

57 4 Developing Your Client Application This section discusses design issues and programming decisions that you should make before writing your client application, introduces the SOG components that you use in client development, presents examples of client development methodology using the support client languages, and summarizes the deployment procedure for installing your completed client application in a run-time (production) system. This section contains the following topics: Getting Started With the TIC Server Object Gateway Programming Tools Selecting a Client Development Tool on page 4-2 Differences Between VBScript and the Other Client Tools on page 4-2 Design Issues on page 4-3 Introducing TIC Server Object Gateway Tools for Client Development on page 4-5 How the SOG Tools Work on page 4-6 What You Need on page 4-6 Client Run-Time Steps for TIC Server Object Gateway on page 4-6 Programming Decisions and Methodology Deciding How to Handle Request and Reply Buffers on page 4-8 Using the SOG Error Dialog for Testing on page 4-9 Handling TMF Transactions on the NonStop Himalaya Server on page 4-14 Sending and Receiving UMS Messages on page 4-15 Indexing Into Request and Reply Messages on page 4-17 Code Examples Code Examples in Visual Basic on page 4-18 Code Examples in Visual C++ on page 4-24 Code Examples in PowerBuilder on page 4-29 Considerations and Code Examples in VBScript on page 4-34 Application Deployment Deployment Procedure on page

58 Developing Your Client Application Selecting a Client Development Tool Selecting a Client Development Tool TIC Server Object Gateway allows you to build components that can be integrated into any ActiveX-enabled application. In addition, SOG generates application code for any of the following popular client development tools: Visual Basic version 5 or higher Visual C++ version 5 or higher PowerBuilder version 5 or higher VBScript Differences Between VBScript and the Other Client Tools Because VBScript is a scripting language designed for use with Active Server Pages (ASP), using SOG with VBScript does not support all the features available with the other client development tools. Specifically, SOG with VBScript: Supports only the variant data type When data is retrieved from the host server for a SOG service object, the data is converted into a format consistent with the client language data type. With Visual Basic, PowerBuilder and C++, service object element data is returned as integer, float, double, logical or string data types. With VBScript, however, all service object element data is returned to the program as variant data type. Does not support parameters that return values Several of the SOG object methods contain by-reference parameters, in which values are returned to the calling program. However, when you specify VBScript as the client language, the SOG object methods do not support parameters that return values. Thus, wherever the return value Success is used in a SOG method, no return parameter is supported when VBScript is selected as the client language. Use the SOG Error properties to determine whether the invoked method was successful. Does not support direct buffer access The GetDirectBufferInterface method of SogServiceObject is not available when the client language is VBScript. Similarly, the SetRequestBuffer and GetReply Buffer calls from SogServiceUtils. DLL are not available when using VBScript. Does not support dialog boxes and the methods to display the SOG error dialog Because displaying a dialog is inconsistent with Web applications, SOG methods that cause a dialog to be displayed cannot be used if the client language is VBScript. The following dialog-box methods and properties are not available with VBScript: DisplayErrorDialog method of SogConnect, SogLink, and SogServiceObject AutoDisplayErrorDialog property of SogLink and SogServiceObject DisplayConvErrorDialog method of SogServiceObject AutoDisplayConvErrorDialog property of SogServiceObject 4-2

59 Developing Your Client Application Design Issues Design Issues Before you write your client application, you should resolve the following issues about how the client will perform specific programming functions and what the client will require from the Pathway server. Required fields (the following two types affect the client): Which fields does the server require the client to supply in the request message? Which fields are optional? You need to know the required fields so that you can add code to the client program to make sure that values are supplied for the required fields before sending the request message to the host. Do you need to set or change any of the required SOG server properties programmatically? The server properties of System, Pathmon, ServerClass, HostAddress, and PortNumber must accurately represent the run-time NonStop Himalaya host. Typically, you would set these properties in the Object Manager using the application properties as a default for the application and using the individual service object properties to override the application default. After you leave the Object Manager, you can change these server properties using SogSupport. You can also set server properties programmatically using the SogLink and SogServiceObject properties. Because programmatic settings are hardcoded, the recommended strategy is to set server properties using Object Manager or SogSupport. Programmatic setting, however, is well suited for testing an application during development. Data conversion and formatting: Does the service object require that data supplied to the server in the request message be in a specific format? For example, binary numbers are Big Endian on the NonStop Himalaya host, but Little Endian on the PC; that is, the bytes are reversed. For example, on the host, the number 1 is represented as 0,1. On the PC, the number 1 is represented as 1,0. This makes the number 1 on the host equal to the number 256 on the PC. Thus, data must be converted between the host and PC formats. SOG offers some automatic data conversion that you can select in the Object Manager. See Appendix B, Data Conversion for more information. If you want to do your own data conversion, you must include routines in your completed client application. Error handling: How will the client handle service object errors? You need to build error handling into your application. In addition, all three SOG objects have Error properties for reporting SOG errors, as well as additional subsystem error information and a data conversion error dialog that you can use during development and testing. For more information, see the descriptions of the Error properties in Section 5, Methods and Properties of SOG Development Objects and the error codes in Appendix C, Errors Reported by SOG Objects. 4-3

60 Developing Your Client Application Design Issues TMF (Transaction Management Facility): If the target database is audited by TMF, you must use the SogLink methods for handling TMF transactions on the client side. For more information, see Handling TMF Transactions on the NonStop Himalaya Server later in this section. Handling request and reply buffers: Which of the two strategies for handling request and reply buffers is appropriate for your application? You can use either: ActiveX properties of the service objects you create for sending requests and replies In this case, you use the Send method to send request messages to the Pathway server. Direct buffer access for sending requests and receiving replies. There is a SogServiceObject method provided for direct buffer access (GetDirectBufferInterface). However, the methodology for using direct buffer access depends on your development tool, as shown in the code examples in this section and in the methods and properties of the SOG objects in Section 5, Methods and Properties of SOG Development Objects. Make sure that the actual IPC structures are consistent with the DDL dictionary. When you create a service object, the Object Manager reads the IPC structures from the source DDL dictionary. The DDL dictionary that you use to create service objects must accurately represent the IPC structures that are in use by the target Pathway server. If the target Pathway server uses the code files generated by DDL, TIC Server Object Gateway can convert the IPCs to and from the client language. If, however, the IPC structures used by the server were manually modified after being created in DDL, there is no guarantee that SOG can properly format the request and reply IPCs. 4-4

61 Developing Your Client Application Introducing TIC Server Object Gateway Tools for Client Development Introducing TIC Server Object Gateway Tools for Client Development To develop your client/transaction server application, use the following three objects that are part of the TIC Server Object Gateway development kit. The methods and properties of the SOG tools are described in detail in Section 5, Methods and Properties of SOG Development Objects. SogConnect The SogConnect ActiveX control, available as SogConnect.OCX, is installed on the development workstation by the SOG Installer. SogConnect has one specific method (CreateLink, described later in this section and in Section 5, Methods and Properties of SOG Development Objects), which you use to get started with SOG tools. CreateLink creates the SogLink object, described below. SogConnect also has properties for setting and displaying the SOG error dialog during development testing, as described in Step 5b. Send Requests and Receive Replies (Using Direct Buffer Access) later in this section. SogLink SogLink is a SOG object that you create using SogConnect. The SogLink object embodies a SOG application s connection with the NonStop Himalaya server. After you create an instance of SogLink for your SOG application, you must first establish the link using the SogLink.EstablishLink method. Then use the CreateServiceObject method to create an individual SogServiceObject for each SOG service object you are using in your client application. The SogServiceObjects inherit their default settings from the parent SogLink. They also have all the properties that were set for them in the Object Manager. SogLink also provides methods for handling Transaction Management Facility (TMF) transactions and for enabling Unsolicited Message Service (UMS). SogLink has properties such as DataTraceFile, LogFile, ErrorText, and SendTimeout. SogServiceObject In your client application, you create each SogServiceObject using SogLink. Each SogServiceObject embodies a single SOG service object that you created using the Object Manager (containing a Pathway service constructed from DDL definitions). SogServiceObject has methods for setting request fields, for retrieving reply fields, and for sending the request to the Pathway server. Each SogServiceObject has a number of stock properties, including properties for setting or getting data trace flags, logging level, error, buffer size (for POET migration), subsystem error, and server properties (system Pathmon, and server class). Because the server properties can be set in several ways (using the Object Manager, SogSupport, or programmatically), the server properties are subject to rules of precedence as described in the property descriptions in Section

62 Developing Your Client Application How the SOG Tools Work How the SOG Tools Work Your code must first call the CreateLink method of the SogConnect object. In the CreateLink call, specify the name of the application that you built in the Object Manager. CreateLink locates and opens the application type library and data conversion files, and reads the application in the host database. CreateLink returns a SogLink object, which you then use to establish the link with the NonStop Himalaya server, to create your service objects (SogServiceObject objects), and to handle TMF transactions. You use SogServiceObject methods to send the requests to the server and to receive replies from the server. What You Need Using the Object Manager, create and generate service objects for each of the Pathway services you want to use. Then create and build an application object. Use the SOG application name in calls to the SogConnect and SogLink objects. Use the SOG service object names in calls to the SogServiceObject object. During application development, you will need the following files: The application type library file (.TLB) The application data conversion file (.TDS) The host database application file (SOGAPPL) The host run-time service objects file You may also want to have the generated code file that is produced by the Object Manager ServiceObjects Generate command. During application development, you can test your application by assigning temporary values for the server properties (system, Pathmon, server class) and the TCP/IP properties (host address and port number) for SogLink and SogServiceObject. Client Run-Time Steps for TIC Server Object Gateway At run time, your completed client application needs to proceed through the following steps, illustrated in Figure 4-1. Each step represents specific methods of SOG objects. 1. Use the TIC Server Object Gateway tools to set up the client/transaction server environment (do this once in each SOG application, before connecting to the host). a. Create the link with the NonStop Himalaya host. b. Set the SogLink properties to be inherited by service objects in your application. 4-6

63 Developing Your Client Application Client Run-Time Steps for NonS TIC Server Object Gateway c. Establish the link. d. Create all the service objects you will use. e. To use direct buffer access: In Visual C++, create the direct buffer interface. In Visual Basic or PowerBuilder, use the SetRequestBuffer and GetReplyBuffer calls to SogServiceUtils.DLL, as illustrated in the code examples. 2. Make requests of the NonStop Himalaya server and receive the replies (do this for every service object you use; do this for each service object in an application). a. Load the request message. b. Send the request. c. Receive the reply. d. Process the data. 3. Release all the service objects, any direct buffer pointers, and the link itself after completing all your sends to the server (do this once at the end of the application). Figure 4-1. Client Run-Time Steps Using TIC Server Object Gateway Step 1a Call SogConnect.CreateLink Step 1c Call SogLink.EstablishLink Step 1d Call SogLink.CreateServiceObject SogConnect control SogLink object SogService- Objects Step 3 Call SogLink.ReleaseLink Call SogServiceObject.ReleaseServiceObject NonStop TM Himalaya Step 2 Send requests to host and receive replies. CDT 014.CDD 4-7

64 Developing Your Client Application Deciding How to Handle Request and Reply Buffers Deciding How to Handle Request and Reply Buffers To send requests to the NonStop Himalaya host and receive replies from the host, you can use either of the following two ways to handle request and reply buffers with the SOG tools: Access the request and reply fields using the properties of the service objects. To do this, you Set the request field and Get the reply field, as follows: Visual Basic, VBScript, and PowerBuilder ServObj.Req_xxx = NewValue value = ServObj.Rep_xxx Visual C++ m_pservobj->setreq_xxx(newvalue); value = m_pservobj->getrep_yyy(); Use "direct buffer access," typically in order to ease migration from existing POET applications. To use direct buffer access in Visual C++, you need to use the GetDirectBufferInterface method of SogServiceObject. To use direct buffer access in Visual Basic and in PowerBuilder, use two SogServiceUtils.DLL calls (SetRequestBuffer and GetReplyBuffer). You cannot use direct buffer access in VBScript. Similarly, the SetRequestBuffer and GetReplyBuffer calls from SogServiceUtils.DLL are not supported for VBScript. The examples in this section use both of these strategies: For examples of direct buffer access using Visual Basic, see Step 5b. Send Requests and Receive Replies (Using Direct Buffer Access). For examples of both direct buffer access and ActiveX properties, see Code Examples in Visual C++. For example of direct buffer access using PowerBuilder, see Step 5b. Send the Requests and Receive Replies (Using Direct Buffer Access). If You Use Direct Buffer Access With Visual C++ In Visual C++, you must allow for structure alignment. If you are using direct buffer access, you need to specify the following command from the generated code file produced by the Object Manager: #pragma pack 1 This ensures that the structure alignment in Visual C++ matches the IPCs used by the Pathway server for all server languages. After the IPC structure definitions, you can return to the configured structure alignment by using the following: #pragma pack 4-8

65 Developing Your Client Application Using the SOG Error Dialog for Testing Using the SOG Error Dialog for Testing During development of your application, you can invoke the SOG error dialog whenever one of the SOG components encounters an error. The SOG error dialog is intended as a development tool, and is not meant to replace your own error handling. However, it may be useful to help you debug the use of the SOG objects. Note. If you are using VBScript, you cannot use any of the SOG dialog-box methods or properties, including the Error dialog and Error properties. Each of the three SOG objects have a method and a property that you can use to invoke the SOG error dialog: Invoke the SOG error dialog directly with a call to the <SogObject>. DisplayErrorDialog method when an error occurs, as shown in this Visual Basic example: If Not MyServiceObject.Send Then MyServiceObject.DisplayErrorDialog End If Set the property <SogObject>.AutoDisplayErrorDialog to True to display the SOG error dialog whenever a SOG object encounters. an error Following is an example using Visual Basic: MyServiceObject.AutoDisplayErrorDialog = True Now, if the call below fails, the Sog Error Dialog will be displayed automatically MyServiceObject.Send Both the DisplayErrorDialog method and the AutoDisplayErrorDialog properties are available with all three SOG objects (SogConnect, SogLink, and SogServiceObjects). Setting Your AppName in the Error Dialog Caption Use the SetApplicationCaption method of the SogConnect object to display your application name in the SOG error dialog, as shown in this Visual Basic example: Dim myappcaption As String myappcaption = "My Great App" SogConnect1.SetApplicationCaption (myappcaption) You must set the application caption before calling SogLink.CreateLink, or else the caption is not inherited by SogLink and your SogServiceObjects as they are created. Note that the string here is not the application type library name generated by the Object Manager. Instead, this string can be anything you like. 4-9

66 Developing Your Client Application Evaluating Subsystem Errors Evaluating Subsystem Errors For many types of SOG errors, additional error information is available in the SubsystemError(index) and SubsystemErrorText(index) fields. The presence of these error fields is indicated by error codes in the Error property of the SOG object. The error codes are shown in column 1 of Table 4-1. The index value indicates the type of error associated with the SubsystemError field or the SubsystemErrorText field, as shown in the table. There are four types of subsystem errors: COM (Component Object Model), NSKLink, TLBUtils, and Conversion. Table 4-1. Subsystem Error Types Used in SOG Error Dialog (page 1 of 2) COM Errors (When <SogObject>.Error = SOGERR_COM_ERROR = 1001 Numeric (Available in <SogObject>.SubsystemError( index ) Index Value Meaning Data Type 0 HRESULT (entire COM error) long (shown in Hex) Example: 0x Severity long Example: "1" 2 Facility long Example: "3" 3 Error long Example: "259" Text (Available in <SogObject>.SubsystemErrorText( index ) 0 COM Error Text Text Example: "Can t Save." TypeLibraryUtils Errors (When <SogObject>.Error = SOGERR_TLB_UTILS_ERROR = 1002) Numeric (Available in <SogObject>.SubsystemError( index ) 0 lasterror long Example: HRESULT long Example: 0x (reinterpreted in Hex) Text (Available in <SogObject>.SubsystemErrorText( index ) 0 errortext text Example: "Unable to open TDS file." 1 fileinerror text Example: "MyApp.TDS" 2 ServiceObjectInError text Example: "EmpStatus" 4-10

67 Developing Your Client Application Evaluating Subsystem Errors Table 4-1. Subsystem Error Types Used in SOG Error Dialog (page 2 of 2) Conversion Errors (When <SogObject>.Error = SOGERR_CONVERSION_ERROR = 1003 Numeric (Available in <SogObject>.SubsystemError( index ) Index Value Meaning Data Type 0 Conversion Error long Example: "4" Text (Available in <SogObject>.SubsystemErrorText( index ) 0 Conversion Error Text Text Example: "Overflow into output field" 1 DDL Field Text Example: "emp_status.data.g1.g2[].g3.e3[]" 2 Property Text Example: "Rep_e3" 3 Index(es) Text Example: "4, 7" or "none" 4 Conversion Procedure used Text Example: "long to long" 5 Action Attempted Text Example: "Converting 1 IPC field" Host Database Errors (When <SogObject>.Error = SOGERR_GWLINK_APP_HOST_ERROR = 1004) Text (Available in <SogObject>.SubsystemErrorText( index ) 0 Application in error text Example: "LoanProcessingApp" 1 Service in Error The service in error is in SubsystemErrorText(1). text Example: "GetCustomerData" NSKLink Errors (When <SogObject>.Error = SOGERR_NSK_LINK_ERROR = 1009) Numeric (Available in <SogObject>.SubsystemError( index ) 0 NSKLink error long Example: NSKLink errordetail long Example: 0 Text (Available in <SogObject>.SubsystemErrorText( index ) 0 NSKLink errortext text Example: "A TMF transaction is already active." 4-11

68 Developing Your Client Application Evaluating Subsystem Errors Recording the Location Tag of an Error When returning an error, each component of TIC Server Object Gateway sets a location tag that identifies the exact location where the error occurred in the SOG component code. The location tag is a unique number (for example, in text: "020010"). If you encounter an error that requires support, having the location tag as well as the other error codes will facilitate analysis of the problem. There are two ways to get the location tag: Find the location tag on the SOG error dialog. Retrieve the location tag programmatically by requesting <SogObject>.SubsystemErrorText(10). Code Example of Error Handling in Visual Basic The following example code illustrates decoding the returned SOG error code in Visual Basic. Note that Chr(10) is a carriage return, and SubsystemErrorText(10) is the hard-coded location tag. For examples of error handling in Visual C++ or PowerBuilder see the code examples provided on the TIC Server Object Gateway product CD. Public Sub DecodeSOGError(servObj As Object) Dim text As String Select Case servobj.error Case SOGERR_OK Exit Sub Case SOGERR_COM_ERROR text ="COM Error Number" + CStr(servObj.SubsystemError(3)) _ + Chr(10) + "Error Severity is: "_ + CStr(servObj.SubsystemError(1)) _ + Chr(10) + servobj.subsystemerrortext(0) _ + Chr(10) + "Server Object Gateway location tag is: "_ + servobj.subsystemerrortext(10) Case SOGERR_NSK_LINK_ERROR text = "NSKLink Error Number " +_ CStr(servObj.SubsystemError(0)) _ + Chr(10) + servobj.subsystemerrortext(0) _ + Chr(10) + "Server Object Gateway location tag is: " _ + servobj.subsystemerrortext(10) Case SOGERR_TLB_UTILS_ERROR text = "Type Library Utility Error Number " _ + CStr(servObj.SubsystemError(0)) _ + Chr(10) + servobj.subsystemerrortext(0) _ + Chr(10) + "File Name is" + servobj.subsystemerrortext(1) _ + Chr(10) + "Service Object Name is: " _ + servobj.subsystemerrortext(2) _ + Chr(10) + "Server Object Gateway location tag is: "_ + servobj.subsystemerrortext(10) 4-12

69 Developing Your Client Application Evaluating Subsystem Errors Case SOGERR_CONVERSION_ERROR text = "Conversion Error Number " _ + CStr(servObj.SubsystemError(0)) + Chr(10) _ + servobj.subsystemerrortext(0) + Chr(10) _ + "Item Name is " + servobj.subsystemerrortext(1) _ + Chr(10) + "Index is " + servobj.subsystemerrortext(2) _ + Chr(10) + "DDL Name is:" + servobj.subsystemerrortext(3) _ + Chr(10) + "Conversion Procedure is: "_ + servobj.subsystemerrortext(4) _ + Chr(10) + "Server Object Gateway location tag is: "_ + servobj.subsystemerrortext(10) Case Else text = "Error Number " + CStr(servObj.error) _ + Chr(10) + servobj.errortext + " " _ + Chr(10) + servobj.errordetailtext _ + Chr(10) + "Server Object Gateway location tag is: "_ + servobj.subsystemerrortext(10) End Select MsgBox (text) End Sub 4-13

70 Developing Your Client Application Handling TMF Transactions on the NonStop Himalaya Server Handling TMF Transactions on the NonStop Himalaya Server If the run-time NonStop Himalaya server is running the Transaction Management Facility (TMF) and the target database files are audited, you need to communicate with TMF each time you initiate a transaction with the Pathway server (except for read-only transactions). A TMF transaction is an all-or-none series of requests or operations. Requests that need to complete as a group are sent in a single TMF transaction. If any request in the group fails, none of the requests can commit; all must be backed out or aborted. With TIC Server Object Gateway, a TMF transaction is composed of service objects. What s more, all SOG service objects that you include in a single TMF transaction must be built into the same SOG application using the Object Manager. The SogLink object has three methods to handle TMF transactions on the host, as follows: SogLink.BeginTransaction() initiates a TMF transaction. This call must precede the first service object request to the server in the TMF transaction. SogLink.AbortTransaction() backs out of an error situation encountered by a request within TMF transaction. SogLink.EndTransaction() closes a transaction after receiving a successful reply on every request in the TMF transaction. Examples of TMF transactions in Visual Basic and PowerBuilder are included in the code examples later in this section under Example of TMF Transactions Using Visual Basic or PowerBuilder. Handling TMF transactions using Visual C++ is illustrated in Code Examples in Visual C

71 Developing Your Client Application Sending and Receiving UMS Messages Sending and Receiving UMS Messages Your completed client application can receive Unsolicited Message Service (UMS) messages from the NonStop Himalaya host. To verify that your SOG installation is able to receive UMS messages, use the Test Unsolicited Messages command in SogSupport during client development. See Section 6, Supporting Customer Applications for details about using SogSupport. Enabling UMS To receive UMS messages, a SOG application enables UMS programmatically, using the SogLink.EnableUMS method, described in Section 5, Methods and Properties of SOG Development Objects. Sending UMS Messages on the NonStop Himalaya Host For a host program to send a UMS message, use the following header format for the UMS message and send it to the NKLUMSW server on the NonStop Himalaya host: typedef struct { short dummy1; // ignored unsigned short dummy2 ; // ignored char dummy3 [10] ; // ignored char UMSLinkID [32 ] ; // space-filled unsigned short dummy4; // ignored } ums_header_def; The body of the UMS message, which follows the header, can be text or a data structure. The size of the body of the message can be as many as 1952 bytes. The UMSLinkID in the header is an identifier string of your choice; it must match the UMSLinkID that was specified in your client application using SogLink.EnableUMS (or if you are testing UMS using SogSupport, on the Test Unsolicited Messages dialog box). However, you can specify "*" as the UMSLinkID in the message header to send a UMS message to all SOG applications that have enabled UMS. Receiving UMS Messages Programmatically 1. Enable UMS messages in your client application by calling SogLink.EnableUMS and specifying a UMSLinkID to identify your application. 2. A program on the host sends a UMS message to the SOG NSKLUMSW server, using Guardian procedure calls Write or Writeread, or using Serverclass_send_, and specifying either your UMSLinkID or *. (For example, the Test Unsolicited Messages command in SogSupport elicits a UMS message from one of the SOG servers and reports the UMS message received.) 3. In your client application, call SogLink.GetUMSMessageText() to read the UMS message. Call GetUMSMessageText repeatedly until it returns

72 Developing Your Client Application Code Example Showing UMS Message Routines in Visual Basic Code Example Showing UMS Message Routines in Visual Basic The following code illustrates how to handle UMS messages in your client application. The code is taken from the Visual Basic example that is installed with the TIC Server Object Gateway product files. Global Const SOGERR_NO_UMS_MSG = Private Sub UMSCheckUMS_Click() Dim umsmsg As String See if a UMS message has been received While PWLink.GetUmsMessageText(umsMsg) loop since there may be more than 1 message Wend MsgBox (umsmsg) If PWLink.error <> SOGERR_NO_UMS_MSG Then Else End If End Sub Call DecodeSOGError(PWLink) MsgBox ("No UMS message") Private Sub UMSDisable_Click() End Sub PWLink.DisableUms set the menu items appropriately UMSEnable.Enabled = True UMSDisable.Enabled = False UMSCheckUMS.Enabled = False Private Sub UMSEnable_Click() If PWLink.EnableUms("TestUMS") Then Else End If End Sub set the menu items appropriately UMSEnable.Enabled = False UMSDisable.Enabled = True UMSCheckUMS.Enabled = True DecodeSOGError (PWLink) 4-16

73 Developing Your Client Application Indexing Into Request and Reply Messages Indexing Into Request and Reply Messages You need to use index values to represent data items in IPC fields that were described by the OCCURS or OCCURS DEPENDING ON clauses in DDL. Any group or element within DDL can have an OCCURS clause. There are two forms of OCCURS: OCCURS <max> TIMES OCCURS <min> TO <max> TIMES DEPENDING ON <field name> Here is an example of a request message including fields that use OCCURS clauses: 01 Req_IPC. 05 G1 occurs 3 times. 10 E1. 10 G2 occurs 2 times. 10 E2 occurs 3 times. 10 G3. 15 E3. 15 E4 occurs 4 times depending on E3. The following example shows how to index into this request message using Visual Basic and also shows the indexing used in DDL: In Visual Basic code: so.req_e4(i,j,k) = val so.req_e3(i,j) = val so.req_e2(i,j,k) = val so.req_e1(i) = val As each index is processed, the following check is performed: if <idx> > 0 and <idx> <= max If the results of this check are False, an error is set. In DDL: Req_ipc.g1[i].g2[j].g3.e4[k] Req_ipc.g1[i].g2[j].g3.e3 Req_ipc.g1[i].g2[j].e2[k] Req_ipc.g1[i].e1 If the data includes an OCCURS DEPENDING ON clause, the <field name> value is used (and is first converted if the IPC is a reply message), and the following operation is performed: if <idx> > 0 and <idx> <= max and <idx> <= <value of field name> In Visual C++, indexing is performed as: m_pso->setreq_e4(i,j,k, val); // val is always the last variable val = m_pso->getrep_e4(i,j,k); // if this was a reply 4-17

74 Developing Your Client Application Code Examples in Visual Basic Code Examples in Visual Basic The following topics describe how to use Server Object Gateway with Visual Basic to develop a client application that accesses Pathway servers on the host. A complete example application is installed on the development workstation as part of TIC Server Object Gateway. Step 1. Add the SogConnect Object to Your Project In the VB graphical development environment, add the SogConnect nongraphical control to the forms on which you want to use Pathway services. 1. Click Project Components and select SogConnect ActiveX Control Module. 2. Select the SogConnect icon on the toolbar and draw the SogConnect nongraphical control on a form. VB assigns the name SogConnect1. Because you need only one SogConnect control in an application, you can rename the control as you like. Step 2. Make Global Declarations of SogLink and Service Objects In your code file, declare your link and each of your service objects as follows: Public <PWLink> As Object Public <AddContact_SO> As Object (Need 1 for each service object you will use) AddContact_SO is the name of one of the service objects used in the example code provided with TIC Server Object Gateway. Step 3. Create a Link Using SogConnect.CreateLink Method Dim success as Boolean String <application-name> = "AppName" Set PWLink = <SogConnect>.CreateLink("AppName", success) Creates a link If PWLink.EstablishLink = FALSE Then Error handling: AppName.TLB may not exist or.tlb file may not be registered or.tds file does not exist or.tds file is not in SOG host database End if 4-18

75 Developing Your Client Application Code Examples in Visual Basic Step 4. Use the Link to Create the Service Objects Set <AddContact_SO> = PWLink.CreateServiceObject("<AddContact>",, success) If Not success Then Handle errors: For example, the serviceobject may not be in the AppName.TLB file or in the run-time host database. End if Step 5a. Send Requests and Receive Replies (Using Service Object Properties) The following example uses the properties associated with a service object to send a request and receive the reply. The example includes a TMF transaction, as described in Example of TMF Transactions Using Visual Basic or PowerBuilder. Set the Request properties AddContact_SO.Req_request_type = If AddContact_SO.Error <> 0 Then Error handling for data conversion error End if PWLink.BeginTransaction note this is a method of the link, not a service object success = AddContact_SO.Send If Not success Then Error handling for data conversion error, pathway, comm, etc PWLink.AbortTransaction End If If (AddContact.Rep_reply_code <> 0) Then Do Error handling End If PWLink.EndTransaction or PWLink.AbortTransaction 4-19

76 Developing Your Client Application Code Examples in Visual Basic Step 5b. Send Requests and Receive Replies (Using Direct Buffer Access) The recommended way to use direct buffer access in Visual Basic is by making calls to the SogServiceUtils.DLL instead of using the SogServiceObject method GetDirectBufferInterface as is done in Visual C++. The usage of the SetRequestBuffer and GetReplyBuffer calls to SogServiceUtils.DLL is as follows: SetRequestBuffer (Request, Requestlen, ServiceObject, SogDLLError) GetReplyBuffer (Reply, Replylen, ServiceObject, SogDLLError) The following declarations for direct buffer access will be in the Visual Basic generated code file produced by the Object Manager. If you want to use direct buffer access, place these declarations in a module (.BAS) file of your choice. (If you want to use the properties of the service object to handle requests and replies, you do not need these declarations; see Step 5a.) SOG Gateway functions in SogServiceUtils Public Declare Function SetRequestBuffer Lib_ "SogServiceUtils" (TypeStruct As Any, ByVal ByteCount As_ Long, ByRef SogService As IUnknown, SogDLLError as Long) As Boolean Public Declare Function GetReplyBuffer Lib_ "SogServiceUtils" (TypeStruct As Any, ByVal ByteCount As_ Long, ByRef SogService As IUnknown, SogDLLError as Long) As Boolean Copy Structures and Length Constants From Generated Code File Copy the structures from the generated code file into your project. Copy the length constants from the generated code file into your project: Global Const add_contact_req_client_len = 136 Global Const reply_hdr_client_len =

77 Developing Your Client Application Code Examples in Visual Basic Set the Request Fields, Send the Request, and Get the Reply The following example uses direct buffer access to send a service object request to the host.the example includes a TMF transaction, as described in Example of TMF Transactions Using Visual Basic or PowerBuilder. Using direct buffer access Dim req As add_contact_req_type Defined in the code fragment file Dim reply As reply_hdr_type Defined in the code fragment file Load fields in the IPC Req.f1 = val Req.f2 = val Req.f3 = val SetRequestBuffer(Request, Requestlength,AddContact_SO, SogDLLError) If Not success Then Do Error handling -- Check SogDLLError first, then AddContact_SO.Error End if PWLink.BeginTransaction note this is a method of the link, not a service object success = AddContact_SO.Send If Not success Then Handle error for data conversion, Pathway, comm, etc PWLink.AbortTransaction Exit Sub End If See if something came back replylen = AddContact_SO.ReplyBufferSize If replylen = 0 Then Do Error handling End if 4-21

78 Developing Your Client Application Code Examples in Visual Basic success = GetReplyBuffer(reply, replylength, AddContact_SO, SogDLLError) If Not success Then End If Do Error handling: Example, for Memory problems Check SogDLLError first, then AddContact_SO.Error PWLink.AbortTransaction Exit Sub If NOT reply.reply_code = 0 Then Do Error handling PWLink.AbortTransaction End if PWLink.EndTransaction Step 6. Release the Link When you complete your sends to the NonStop Himalaya server and have received all replies, you need to release the link and set your service objects and your link to Nothing. ReleaseLink is a method of SogLink. AddContact_SO.ReleaseServiceObject Set AddContact_SO = Nothing PWLink.ReleaseLink Set PWLink = Nothing 4-22

79 Developing Your Client Application Example of TMF Transactions Using Visual Basic or PowerBuilder Example of TMF Transactions Using Visual Basic or PowerBuilder Use the SogLink methods BeginTransaction, AbortTransaction, and EndTransaction to handle TMF transactions. In the following example, three requests (SO1, SO2, and SO3) are sent under one TMF transaction. The instance of SogLink is named PWLink. PWLink.BeginTransaction If Not SO1.Send Then Error = SO1.ErrorCode Do your own Error handling based on this error code PWLink.AbortTransaction Exit Sub End If If Not SO2.Send Then Error = SO2.ErrorCode Do your own Error handling based on this error code. PWLink.AbortTransaction Exit Sub End If If Not SO3.Send Then Error = SO3.ErrorCode Do your own Error handling based on this error code. PWLink.AbortTransaction Exit Sub End If PWLink.EndTransaction 4-23

80 Developing Your Client Application Code Examples in Visual C++ Code Examples in Visual C++ The following steps illustrate how to use TIC Server Object Gateway with Visual C++ to develop a client application that accesses Pathway servers on the host. The code examples shown here are part of the complete example application that is installed on the development workstation. Note that in Visual C++, you use wrapper classes and interface pointers in manipulating the SOG tools. If you are using SogConnect on a dialog, the steps are similar to those shown here, but easier. Because using SogConnect for a view class is more difficult, we show it in this example. Step 1. Add the SOG Tools to Your MFC Project in Visual C++ 1. Create an MFC project using Microsoft Developer s Studio. 2. Add the SogConnect control (a wrapper class) to your project by selecting: Project Add to Project Components and controls a. From Components and Controls, select Registered ActiveX Controls. b. From the list of ActiveX controls, select: SogConnect Control and click Insert. c. In the Confirm Classes, click OK. Visual Studio builds a C++ wrapper class for SogConnect and adds a sogconnect.h and sogconnect.cpp file to your project. 3. In the view object s header file (such as VCExampleView.h for the example in the SOG installation), add: #include "sogconnect.h" a. In the public: attributes, enter: CSogConnect ISogLink* m_sogconnect; m_psoglink; 4. Add a wrapper for the service objects. Start the Class Wizard using Ctrl-W or by selecting View Class Wizard. a. Select the Message Maps tab, then select: Add Class From a type library b. Browse to the location of your SOG application type library (SogExampleVC.TLB in this example). c. Click Ok to add sogexamplevc.h and sogexamplevc.cpp to your project. 4-24

81 Developing Your Client Application Code Examples in Visual C++ 5. In the same view object header file used in 3. above, add: #include "sogexamplevc.h" a. In the public: attributes, enter pointer definitions for each service object you will be using: AddContactVC* m_paddcontact; DeleteContactVC* m_pdeletecontact; ReadContactVC* m_preadcontact; 6. If you are using whole IPC structures (for direct buffer access): a. include for each service object: #include IPCs.h // this is the edited generated code file for the service object b. In the public: attributes, define the direct buffer interface for each service object as follows: ISogDirectBufferAccess* m_paddcontactdirectbuffer; 7. In the view object s OnCreate method, set up the link and all the service objects. Create these only one time. // Load (create) the control so it is available if(!m_sogconnect.create (NULL, WS_DISABLED, { CRect (0,0,0,0), this, 0 )) AfxMessageBox("Could not create SogConnect ActiveX control", MB_ICONSTOP MB_OK); } return -1; 8. Create a BSTR with the name of your application type library: BSTR appname = CString("SogExampleVC").AllocSysString(); 4-25

82 Developing Your Client Application Code Examples in Visual C++ Step 2. Create a Link Using SogConnect.CreateLink Method 1. Use the SogConnect.CreateLink method to open and set up the application type library: LPDISPATCH pdispptr = m_sogconnect.createlink(&appname, &success); SysFreeString(appName); // make sure it worked. Get the error; decide what to do. if(!success) { } m_sogconnect.displayerrordialog(); return success; 2. Using the pointer just returned, create an ISogLink object: m_psoglink = new ISogLink ( pdispptr ); Step 3. Establish the Link Make sure you can connect to the host correctly. success = m_psoglink->establishlink(); if(!success) { } // Your App should give custom error message m_psoglink->displayerrordialog(); return success; Step 4. Use the Link to Create the Service Objects 1. Get a pointer to each service object: pdispptr = m_psoglink->createserviceobject("addcontactvc", &success); if(!success) { m_psoglink->displayerrordialog(); return success; } 4-26

83 Developing Your Client Application Code Examples in Visual C++ 2. Create your service objects using the pointers: m_paddcontact = new AddContactVC ( pdispptr ); // Get a pointer to the directbuffer if using IPC structures. m_paddcontactdirectbuffer = (ISogDirectBufferAccess*)m_pAddContact ->GetDirectBufferInterface(); Step 5. Send Requests and Receive Replies Now the objects are ready to use. Here is an example that uses the properties of the AddContact service object to send the request to the host: // example showing how to set elements directly. m_paddcontact->setreq_request_type(900); m_psoglink->begintransaction(); success = m_paddcontact->send(); if(!success) } } m_paddcontact->displayerrordialog(); return; The following example uses direct buffer access and illustrates how to use the TMF transaction methods of SogLink. add_contact_req_def // use the IPC structure from IPC.h addcontactrequest; add_contact_reply_def // use the IPC structure addcontactreply; // load the IPC structure memset(&addcontactrequest, ' ', sizeof(add_contact_req_def)); workstring.format("%06d", dlg.m_ncontactnumber); memcpy(&addcontactrequest.contact_info.contact_number, workstring,6); addcontactrequest.request_hdr.request_type = 900; // Pass the IPC structure hresult = m_paddcontactdirectbuffer->setrequestbufferdirect( sizeof(add_contact_req_def), (long*)&addcontactrequest, &vt_success); if(hresult!= S_OK)!vt_success) { workstring.format("error 0x%s", hresult); AfxMessageBox(workString, MB_OK); return; 4-27

84 Developing Your Client Application Code Examples in Visual C++ } // get the whole reply structure hresult = m_paddcontactdirectbuffer->getreplybufferdirect( sizeof(add_contact_reply_def), (long*)&addcontactreply, &vt_success); if(addcontactreply.reply_hdr.reply_code!= 0) { m_psoglink->aborttransaction(); workstring.format("error %d doing addcontact", addcontactreply.reply_hdr.file_error); AfxMessageBox(workString, MB_OK); return; } m_psoglink->endtransaction(); Step 6. Release the Link When you complete your transactions with the NonStop Himalaya server, you need to release the link and delete the link. ReleaseLink is a method of SogLink. 1. In the view object s PostNcDestroy method, release all the objects: if(m_paddcontact!= NULL) { } m_paddcontact->releaseserviceobject(); m_paddcontact->releasedispatch(); delete m_paddcontact; m_paddcontact = NULL; if(m_paddcontactdirectbuffer!= NULL) { } m_paddcontactdirectbuffer->release(); m_paddcontactdirectbuffer = NULL; if(m_psoglink!= NULL) { } m_psoglink->releaselink(); m_psoglink->releasedispatch(); delete m_psoglink; m_psoglink = NULL; 4-28

85 Developing Your Client Application Code Examples in PowerBuilder Code Examples in PowerBuilder The following steps illustrate how to use TIC Server Object Gateway with PowerBuilder to develop a client application that accesses Pathway servers on the host. The code examples shown here are part of the complete example application that is installed on the development workstation. There are many similarities between PowerBuilder code and Visual Basic code. For example, handling TMF transactions (shown in this example) is done just as it is for Visual Basic. See Handling TMF Transactions on the NonStop Himalaya Server earlier in this section for more information about TMF transactions. Step 1. Add the SogConnect Object to Your Window In the PowerBuilder graphical development environment, add the SogConnect nongraphical control to the window in whose script you will create the SogLink: 1. Click Controls OLE and select the Insert Control tab. 2. Select the SogConnect Control and draw the SogConnect nongraphical control on the window. PowerBuilder assigns a default name to the control. You may find it helpful to rename the control to a meaningful name like "SogConnect." Step 2. Make Declarations of SogLink and Your Service Objects oleobject PWLink oleobject AddContact_SO Step 3. Create a Link Using the SogConnect.CreateLink Method boolean bsuccess integer iresult // create PB object for SogLink PWLink = create oleobject // Create a SogLink using the application name created in // the Object Manager PWLink = SOGConnect.object.CreateLink("<AppName>", REF & bsuccess) If not bsuccess Then SogConnect.object.DisplayErrorDialog return End If If Not PWLink.EstablishLink Then PWLink.DisplayErrorDialog return End If 4-29

86 Developing Your Client Application Code Examples in PowerBuilder Step 4. Use the Link to Create the Service Objects // Create PowerBuilder objects for each service AddContact_SO = create oleobject AddContact_SO = PWLink.CreateServiceObject("AddContactPB", "",& REF bsuccess) If not bsuccess Then End If PWLink.DisplayErrorDialog return Step 5a. Send the Requests and Receive Replies (Using Active X Properties) The following example uses the properties associated with a service object to send a request and receive the reply. The code for PowerBuilder is the same as the code used in the Visual Basic examples previously in this section. The example includes a TMF transaction, as described in Example of TMF Transactions Using Visual Basic or PowerBuilder. // Set the Request properties AddContact_SO.Req_request_type = If AddContact_SO.Error <> 0 Then // Error handling for data conversion error End if PWLink.BeginTransaction // note this is a method of the link, // not a service object success = AddContact_SO.Send If Not success Then // Error handling for data conversion error, // pathway, comm, etc PWLink.AbortTransaction End If If (AddContact.Rep_reply_code <> 0) Then // Do your stuff End If // PWLink.EndTransaction or PWLink.AbortTransaction 4-30

87 Developing Your Client Application Code Examples in PowerBuilder Step 5b. Send the Requests and Receive Replies (Using Direct Buffer Access) To use direct buffer access with PowerBuilder, you need to use the GetAutomation NativePointer and ReleaseAutomationNativePointer statements to create a pointer to an OLE object (in this case, the service object). You also need to use the GetReplyBuffer and SetRequestBuffer calls to the SogServiceUtils.DLL. The usage for these is as follows: ulong pobject IntegerResult = ServiceObject.GetAutomationNativePointer (pobject) bsuccess = SetRequestBuffer(Request, RequestLength, pobject, SogDLLError) bsuccess = GetReplyBuffer(Reply, ReplyLength, pobject, SogDLLError) IntegerResult = ServiceObject.ReleaseAutomationNativePointer (pobject) The following declarations for direct buffer access will be in the PowerBuilder generated code file produced by the Object Manager. If you want to use direct buffer access, place these declarations in the Declare Global External Functions or Local External Functions window. (If you want to use the properties of the service object to handle requests and replies, you do not need these declarations; instead see Step 5a.) Function Boolean SetRequestBuffer( & REF structure TypeStruct, long ByteCount, & REF ulong link, REF long SogDDLError) Library "SogServiceUtils" Function Boolean GetReplyBuffer ( & REF Structure TypeStruct, long ByteCount, & REF ulong link, REF long SogDDLError) Library & "SogServiceUtils" Create the Structure Declarations In the Library Painter, import the structure declarations from the generated code file (.srx file). 1. Declare an instance of the request and reply structures in your script: add_contact_req reply_hdr AddRequest AddReply 4-31

88 Developing Your Client Application Code Examples in PowerBuilder 2. Copy the request and reply lengths from the generated code file and add them to your declarations: long add_contact_req_client_len = 136 long reply_hdr_client_len = 4 Set the Request Fields, Send the Request, and Get the Reply AddRequest.request_hdr.request_type = 900 //Note that if the field has a type of numeric string on the host, //it must be filled with valid ASCII numbers, not blanks. AddRequest.contact_info.contact_number[1] = "000005" // If you re using PowerBuilder , you must assign // one character at at time to an array of characters // so that PowerBuilder does not add an extra null character // to the array for i = 1 to 10 next AddRequest.contact_info.owner_name.first_name[i] = & mid(sle_firstname.text,i) Prepare to Send the Message integer result ulong pobject // get a pointer to service object iresult = AddContact_SO.GetAutomationNativePointer(pobject) if iresult <> 0 then end if messagebox(title, "GetAutomationNativePointer returned an & error") return Set the Request Buffer for the Service Object bsuccess = SetRequestBuffer (AddRequest, & add_contact_req_client_len, pobject, SogDLLError) Release the Pointer iresult = AddContact_SO.releaseAutomationNativePointer(pObject) 4-32

89 Developing Your Client Application Code Examples in PowerBuilder Check for Success if not bsuccess then AddContact_SO.displayerrordialog return end if Begin the Transaction bsuccess = PWLink.begintransaction if not bsuccess then PWLink.displayerrordialog return end if Send the Message to the Server bsuccess = AddContact_SO.send if not bsuccess then AddContact_SO.displayerrordialog PWLink.aborttransaction return end if Get the Reply iresult = AddContact_SO.GetAutomationNativePointer(pobject) if iresult<> 0 then messagebox(title, "GetAutomationNativePointer returned an & error") return end if bsuccess = GetReplyBuffer(AddReply, reply_hdr_client_len,& pobject, SogDLLError) iresult = AddContact_SO.releaseAutomationNativePointer(pObject) if not bsuccess then AddContact_SO.displayerrordialog PWLink.aborttransaction return end if if AddReply.reply_code <> 0 then // Do error handling PWLink.aborttransaction return end if PWLink.endtransaction 4-33

90 Developing Your Client Application Considerations and Code Examples in VBScript Step 6. Release the Link AddContact_SO.ReleaseServiceObject destroy AddContact_SO PWLink.releaselink() destroy PWLink Considerations and Code Examples in VBScript When developing for VBScript, you create the SogConnect object using the command CreateObject. The SogConnect object must be in the scope of the statements referencing its methods and properties. After the SogConnect object is created, you can use the SogConnect object in the same manner as used in Visual Basic. The steps in these examples correspond to the steps in the Visual Basic code example earlier in this section. Steps 1 and 2. Declare and Create Objects <SCRIPT LANGUAGE=VBScript RUNAT=Server> 'Declarations Dim PWLink Dim soaddcontact_so Dim SogConnect Set SogConnect = CreateObject("NSSog.SogConnectScript.1") If SogConnect.error <> 0 then ' Error handling End If 4-34

91 Developing Your Client Application Considerations and Code Examples in VBScript Step 3. Create a SogLink Object Using the CreateLink Method Set PWLink = SogConnect.CreateLink(<ApplicationName as String>) If PWLink.Error <> 0 then ' Error handling End if PWLink.EstablishLink ' Establishes link with current values ' Test for success using PWLink.Error Step 4. Use the Link to Create the Service Objects Set soaddcontact_so = PWLink.CreateServiceObject( "AddContact_SO", "") Test for success using PWLink.Error Step 5. Send Requests and Receive Replies See step 5a of the Visual Basic code example on page Step 6. Release the Link and Destroy the Objects soaddcontact_so.releaseserviceobject Set soaddcontact_so = Nothing PwLink.ReleaseLink Set PwLink = Nothing Set SogConnect = Nothing 4-35

92 Developing Your Client Application Deployment Procedure Deployment Procedure Use the following procedure for deploying your completed client application to its run-time (production) environment: 1. On each client PC: Use the SOG Application Installer CD and select PC Components Installation (for an Application Installation). This installs and configures the run-time TIC Server Object Gateway components. Install your completed client application. Place copies of the following files from the development workstation: Application type library file (<application>.tlb) Application data conversion file (<application>.tds) Register the type library file (<application>.tlb). You can register type libraries using SogSupport or using two different SOG programmatic tools, as described in Registering Type Libraries on page On the target host, use the SOG Application Installer CD and select: NSK Host Installation (for an Application Installation) Host Component Configuration. 3. Use SogSupport on a PC connected to the run-time NonStop Himalaya system to: Copy the application or applications from the development host database to the production host database. (The Applications Copy command copies the runtime service objects file and other application information about your completed client application and its service objects to the destination (run-time) host database.) You can also use the Applications Import command in SogSupport to perform the same type of copy operation when you cannot connect to the development host database at the same time as the run-time host database. Register the application type library file (<application>.tlb) if you did not register it if when you installed your client application in step 1. Configure the application information, if necessary. You can set values for the system, Pathmon, server class, HostAddress and Port to be used for the run-time application, if these values have not been set during development, or if you want to change to assigned values. For more information about using SogSupport, see the SogSupport online help and Section 6, Supporting Customer Applications. 4-36

93 5 Methods and Properties of SOG Development Objects This section describes the methods and properties of the three SOG objects that you use programmatically in your completed client application. See Section 4, Developing Your Client Application for code examples illustrating the usage of the methods and properties described here. The three SOG objects are: SogConnect Methods of SogConnect on page 5-2 Properties of SogConnect on page 5-5 SogLink Methods of SogLink on page 5-9 Properties of SogLink on page 5-19 SOG Service Object(s) Methods of SogServiceObject on page 5-34 Properties of SogServiceObject on page 5-40 Evaluating the Return Value of Success Some methods for the SOG objects return Success as a Boolean in Visual Basic, Visual C++ and PowerBuilder. The return value of Success is defined as follows: True (nonzero) indicates success. False (zero) indicates failure. To retrieve the error, use the Error properties provided for the three SOG objects. When you specify VBScript as the client language, the SOG object methods do not support parameters that return values. Thus, wherever the return value of Success is used, no return parameter is supported for VBScript. Instead, use the Error properties of the three SOG objects to determine whether the invoked method was successful. 5-1

94 Methods and Properties of SOG Development Objects Methods of SogConnect Methods of SogConnect The SogConnect object has three methods associated with it: CreateLink on page 5-2 DisplayErrorDialog on page 5-3 SetApplicationCaption on page 5-4 These SogConnect methods are described on the following pages. CreateLink SogConnect.CreateLink creates a SogLink object. If unsuccessful, this method returns an empty (NULL) object. (To retrieve the error, get the property SogConnect.Error.) The actual connection to the host is not made until you call SogLink.EstablishLink. Before establishing the link, you can set several SogLink properties that have effect only if set before calling SogLink.EstablishLink. Those properties are LogFile, DataTraceFile, HostAddress, and PortNumber. The remaining server properties for the link (System, Pathmon, and Server class) have the values that were set using the Object Manager or SogSupport for the SOG application or SOG service object. See the descriptions of these properties for order of precedence. Type Arguments Return Type Usage: Visual Basic VBScript Method <application-name> as string (this is the name of the type library file built by the Object Manager for your application) Success as Boolean for Visual Basic, Visual C++, PowerBuilder SogLink as Object Dim appname as String appname = "MyApp" Set PWLink = SogConnect.CreateLink(appName, success) Dim appname as String appname = "MyApp" Set PWLink = SogConnect.CreateLink(appName) Visual C++ LPDISPATCH pdispptr = m_psogconnect.createlink(bstr* appname, &success); m_psoglink = new CSogLink (pdispptr); PowerBuilder MyLink = SogConnect.object.CreateLink(AppName, success) 5-2

95 Methods and Properties of SOG Development Objects Methods of SogConnect DisplayErrorDialog SogConnect.DisplayErrorDialog method displays the SOG error dialog. (The SOG error dialog is for development use only; it is not intended for production or run-time use.) All three SOG objects contain this method. Type Arguments Return Type Usage: Visual Basic VBScript Visual C++ PowerBuilder Method None None SogConnect.DisplayErrorDialog Not available m_sogconnect.displayerrordialog(); SogConnect.object.DisplayErrorDialog 5-3

96 Methods and Properties of SOG Development Objects Methods of SogConnect SetApplicationCaption SogConnect.SetApplicationCaption sets your application name in the caption of the SOG error dialog. (The SOG error dialog is for development use only; it is not intended for production or run-time use.) You can use any name you like as AppCaption to identify your code for yourself. If you are using the SOG error dialog, you must set the application caption before calling SogLink.CreateLink. Otherwise, the caption will not be inherited by SogLink and by the SogServiceObjects you create. Only SogConnect contains this method. Type Arguments Return Type Usage: Visual Basic VBScript Visual C++ PowerBuilder Method AppCaption as string None SogConnect.SetApplicationCaption("AppCaption") Not available m_sogconnect.setapplicationcaption(bstr* AppCaption); SogConnect.object.SetApplicationCaption("AppCaption") 5-4

97 Methods and Properties of SOG Development Objects Properties of SogConnect Properties of SogConnect The SogConnect object contains the following properties: AutoDisplayErrorDialog on page 5-5 Error, ErrorText, ErrorDetail, and ErrorDetailText on page 5-6 SubsystemError on page 5-7 and SubsystemErrorText on page 5-8 The properties of SogConnect are described on the following pages. AutoDisplayErrorDialog SogConnect.AutoDisplayErrorDialog displays the SOG error dialog for any SOG error that is subsequently returned. (The SOG error dialog is for development use only; it is not intended for production or run-time use.) All three SOG objects contain this property. Type Function Value Usage: Property Set Boolean Visual Basic SogConnect.AutoDisplayErrorDialog = True False VBScript Visual C++ Not available m_psogconnect->setautodisplayerrordialog ( TRUE FALSE ); PowerBuilder SogConnect.object.AutoDisplayErrorDialog = True False 5-5

98 Methods and Properties of SOG Development Objects Properties of SogConnect Error, ErrorText, ErrorDetail, and ErrorDetailText All four are SogConnect properties that report errors as follows: Error contains an error number. ErrorText supplies text associated with Error. ErrorDetail supplies additional details associated with Error, if available. ErrorDetailText supplies text associated with ErrorDetail. All the SOG objects have these four error properties. For more details about using the SOG error dialog, see Using the SOG Error Dialog for Testing on page 4-9 and Table 4-1, Subsystem Error Types Used in SOG Error Dialog For a list of all the error values, see Appendix C, Errors Reported by SOG Objects. Type Function Value Usage: Properties Get long for Error and ErrorDetail string for ErrorText and ErrorDetailText Visual Basic and VBScript longvar = SogConnect.Error Visual C++ PowerBuilder StringVar = SogConnect.ErrorText longvar = SogConnect.ErrorDetail StringVar = SogConnect.ErrorDetailText longvar = m_psogconnect->geterror(); longvar = m_psogconnect->geterrordetail(); CStringVar = m_psogconnect->geterrortext(); CStringVar = m_psogconnect-> GetErrorDetailText(); longvar = SogConnect.object.Error StringVar = SogConnect.object.ErrorText longvar = SogConnect.object.ErrorDetail StringVar = SogConnect.object.ErrorDetailText 5-6

99 Methods and Properties of SOG Development Objects Properties of SogConnect SubsystemError SogConnect.SubsystemError(index) returns a SOG subsystem error. The subsystem, which is indicated in the SogServiceObject.Error property, is one of the following: 1001 = SOGERR_COM_ERROR 1002 = SOGERR_TLB_UTILS_ERROR 1003 = SOGERR_CONVERSION_ERROR 1004 = SOGERR_GWLINK_APP_HOST_ERROR 1009 = SOGERR_NSK_LINK_ERROR The values of index, and the meanings of each value, are given in Evaluating Subsystem Errors on page Type Function Value Usage: Property Set string Visual Basic and VBScript longvar = SogConnect.SubsystemError(longindex) Visual C++ longvar = m_psogconnect ->GetSubsystemError(longindex); PowerBuilder longvar = SogConnect.SubsystemError(longindex) 5-7

100 Methods and Properties of SOG Development Objects Properties of SogConnect SubsystemErrorText SogConnect.SubsystemErrorText(index) returns text associated with SubsystemError, for those errors for which error text is available. The values of index, and the meanings of each value, are given in Evaluating Subsystem Errors on page Type Function Value Usage: Property Set string Visual Basic and VBScript StringVar = SogConnect.SubsystemErrorText(longindex) Visual C++ CStringVar = m_psogconnect ->GetSubsystemErrorText(longindex); PowerBuilder StringVar = SogConnect.SubsystemErrorText(longindex) 5-8

101 Methods and Properties of SOG Development Objects Methods of SogLink Methods of SogLink The SogLink object has the following methods, grouped here according to similar function: AbortTransaction on page 5-9 BeginTransaction on page 5-10 CreateServiceObject on page 5-11 DisableUMS on page 5-12 DisplayErrorDialog on page 5-13 EnableUMS on page 5-14 EndTransaction on page 5-15 EstablishLink on page 5-16 GetUMSMessageText on page 5-17 ReleaseLink on page 5-18 The methods of SogLink are described in alphabetic order on the following pages. AbortTransaction SogLink.Abort Transaction ends a TMF transaction following an error and does not commit any of the requests. Instead, all requests (or service objects) in the transaction are backed out. See also the SogLink methods BeginTransaction and EndTransaction, and Example of TMF Transactions Using Visual Basic or PowerBuilder on page Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method None. Boolean OK = MyLink.AbortTransaction OK = m_psoglink->aborttransaction(); OK = MyLink.AbortTransaction 5-9

102 Methods and Properties of SOG Development Objects Methods of SogLink BeginTransaction SogLink.BeginTransaction begins a TMF transaction on the NonStop Himalaya server. A TMF transaction consists of a set of operations (in this case, represented as service objects) that either must all complete or else must all be backed out as a group for database integrity. See also the SogLink methods Abort Transaction and EndTransaction, and Example of TMF Transactions Using Visual Basic or PowerBuilder on page Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method None Boolean OK = MyLink.BeginTransaction OK = m_psoglink->begintransaction(); OK = MyLink.BeginTransaction 5-10

103 Methods and Properties of SOG Development Objects Methods of SogLink CreateServiceObject SogLink.CreateServiceObject returns a SogServiceObject object if successful. If unsuccessful, it returns an empty (NULL) object. Use SogLink.Error to retrieve the error. <service-object-name> identifies the service object within the application. This service object must have been generated during design phase using the Object Manager and is instantiated in your client application by CreateServiceObject. <security-string> is the Security ID assigned in the Object Manager or SogSupport. Enforcing security by requiring a Security ID is optional. The security string field, however, is required regardless of whether a Security ID was set for this service object, as follows: If a Security ID was assigned, you must include the correct security string for each service object. If no Security ID was assigned, you can include a blank or empty string, but do not omit the field. Type Arguments Method <service-object-name> as string <security-string> as string (a required parameter; can be blank but cannot be omitted) Success as Boolean for Visual Basic, Visual C++, and PowerBuilder Return Type ServiceObject as object in Visual Basic and in VBScript, as LPDISPATCH in Visual C++, and as oleobject in PowerBuilder Usage: Visual Basic Set ServiceObject = MyLink.CreateServiceObject("ServObjName", Securitystring, Success) VBScript Set ServiceObject = MyLink.CreateServiceObject("ServObjName", Securitystring) Visual C++ LPDISPATCH pdispptr = m_psoglink ->CreateServiceObject(LPCTSTR ServiceObject, LPCTSTR Securitystring, BOOL* Success); m_pservobj = new CServObj (pdispptr); PowerBuilder ServiceObject = MyLink.CreateServiceObject("ServObjName", Securitystring, Success) 5-11

104 Methods and Properties of SOG Development Objects Methods of SogLink DisableUMS SogLink.DisableUMS disables reception by the link of messages from the Unsolicited Message Service (UMS) on the host. Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method None None MyLink.DisableUMS m_psoglink->disableums(); MyLink.DisableUMS 5-12

105 Methods and Properties of SOG Development Objects Methods of SogLink DisplayErrorDialog SogLink.DisplayErrorDialog displays the SOG error dialog. See also the SogLink property AutoDisplayErrorDialog on page 5-5. All three SOG objects contain this method. Type Method Arguments None Return Type Usage: Visual Basic MyLink.DisplayErrorDialog VBScript Not available Visual C++ m_psoglink->displayerrordialog(); PowerBuilder MyLink.DisplayErrorDialog 5-13

106 Methods and Properties of SOG Development Objects Methods of SogLink EnableUMS SogLink.EnableUMS enables reception by the link of messages from the Unsolicited Message Service (UMS) on the host, for messages associated with UMSLinkID. Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method UMSLinkID as string ("*" receives a message sent to any UMSLinkID) Boolean OK = MyLink.EnableUMS(UMSLinkID) OK = m_psoglink->enableums(lpctstr UMSLinkID); OK = MyLink.EnableUMS(UMSLinkID) 5-14

107 Methods and Properties of SOG Development Objects Methods of SogLink EndTransaction SogLink.EndTransaction commits a TMF transaction (a set of operations that must all be completed or backed out as a group for database integrity). See also the SogLink methods AbortTransaction and End Transaction, and see the Example of TMF Transactions Using Visual Basic or PowerBuilder on page Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method None Boolean OK = MyLink.EndTransaction OK = m_psoglink->endtransaction(); OK = MyLink.EndTransaction 5-15

108 Methods and Properties of SOG Development Objects Methods of SogLink EstablishLink SogLink.EstablishLink establishes the connection to the Pathway system using SogGateway. After you call SogConnect.CreateLink, the actual the connection to the host is not made until you call SogLink.EstablishLink. Before establishing the link, you can set several SogLink properties that must be set prior to calling EstablishLink in order to have effect. These properties are DataTraceFile, HostAddress, LogFile, and PortNumber. You must call EstablishLink before you can send requests and replies to the NonStop Himalaya server. See also the SogLink method ReleaseLink on page Type Arguments Return Type Method None Boolean Usage: Visual Basic and VBScript Visual C++ PowerBuilder OK = MyLink.EstablishLink OK = m_psoglink->establishlink(); OK = MyLink.EstablishLink 5-16

109 Methods and Properties of SOG Development Objects Methods of SogLink GetUMSMessageText SogLink.GetUMSMessageText checks for a message from the Unsolicited Message Service (UMS), if UMS messages are enabled. If a message is available, the UMS message text is returned. If no UMS message is received, SOG error code is returned. See also the SogLink method EnableUMS on page There can be more than one message waiting. You should loop getting messages until error is returned ( No UMS message was available. ) Type Arguments Return Type Usage: Visual Basic VBScript Visual C++ PowerBuilder Method UmsMessageText as string Boolean for Visual Basic, Visual C++, and PowerBuilder String for VBScript OK = MyLink.UmsMessageText(UmsMessageText) MessageText = MyLink.UMSMessageText OK = m_psoglink->getumsmessage(bstr* UmsMessageText); OK = MyLink.UmsMessageText(UmsMessageText) 5-17

110 Methods and Properties of SOG Development Objects Methods of SogLink ReleaseLink SogLink.ReleaseLink shuts down SogGateway correctly. You must call ReleaseLink after you have sent all your requests to the NonStop Himalaya host and received the replies. Failure to call ReleaseLink may result in orphaned SOG objects and a hung client application. See also the SogLink method EstablishLink on page Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method None None MyLink.ReleaseLink m_psoglink->releaselink(); MyLink.ReleaseLink 5-18

111 Methods and Properties of SOG Development Objects Properties of SogLink Properties of SogLink The SogLink object contains a number of properties to set logging and data trace functions, to perform error handling, and to set server properties of the application. The properties of SogLink are: AutoDisplayErrorDialog on page 5-20 DataTraceFile on page 5-21 DataT racefile DataTraceFlags on page 5-22 Error, ErrorText, ErrorDetail, ErrorDetailText on page 5-23 HostAddress on page 5-24 LogFile on page 5-25 LogLevel on page 5-26 Pathmon on page 5-27 PortNumber on page 5-28 SendTimeout on page 5-29 ServerClass on page 5-30 SubsystemError on page 5-31 and SubsystemErrorText on page 5-32 System on page 5-33 The SogLink properties are described on the following pages. SogLink Properties Are Inherited by Service Objects For many SogLink properties, a value that you set serves as the default value for the service objects you create using SogLink.CreateServiceObject unless you explicitly set the value for the service object. See the descriptions of the properties for details of precedence. Similarly, in the Object Manager, values set for a SOG application serve as defaults whenever that property is not set for the SOG service object. Several SogLink properties must be set prior to calling SogLink.EstablishLink in order to have effect. These properties are: DataTraceFile HostAddress LogFile PortNumber Only set these properties to override values set in the Object Manager or SogSupport. Setting these properties in the client application prevents you from altering the values in SogSupport. 5-19

112 Methods and Properties of SOG Development Objects Properties of SogLink AutoDisplayErrorDialog SogLink.AutoDisplayErrorDialog, if true, causes SogLink to automatically display the SOG error dialog (containing SOG error messages) after an error occurs involving the SOG tools. (The SOG error dialog is for development use only; it is not intended for production or run-time use.) Type Function Value Usage: Visual Basic VBScript Visual C++ PowerBuilder Property Set Boolean MyLink.AutoDisplayErrorDialog = True False Not available m_psoglink->setautodisplayerrordialog (TRUE FALSE); MyLink.AutoDisplayErrorDialog = True False 5-20

113 Methods and Properties of SOG Development Objects Properties of SogLink DataTraceFile SogLink.DataTraceFile specifies the file name to receive trace information from SogConnect. To set the trace file programmatically, you must set the DataTraceFile property before calling SogLink. EstablishLink; otherwise, the set has no effect. Service objects that you create using SogLink.CreateServiceObject inherit the DataTraceFile setting if it was set for SogLink. The data trace file can also be set using the Configure SogConnect command in SogSupport. To use a different data trace file, use SogLink.DataTraceFile. Type Function Value Usage: Property Set string Visual Basic and VBScript MyLink.DataTraceFile = NewValue Visual C++ PowerBuilder m_psoglink->setdatatracefile(lpctstr lpsznewvalue); MyLink.DataTraceFile = NewValue 5-21

114 Methods and Properties of SOG Development Objects Properties of SogLink DataTraceFlags SogLink.DataTraceFlags is a bit-field flag. Before setting this property, determine its value by adding together these SOG-defined values: SOG_CON_TRACE_REQ_BUFF_ BEFORE_CONV = 1 SOG_CON_TRACE_REQ_BUFF_ AFTER_CONV = 2 SOG_CON_TRACE_REP_BUFF_ BEFORE_CONV = 4 SOG_CON_TRACE_REP_BUFF_ AFTER_CONV = 8 The SogLink.DataTraceFlags property, if set, is the default value inherited by the service objects that you create using SogLink. Data tracing can also be enabled in SogSupport using the Configure SogConnect command. The SogLink.DataTraceFlags property overrides any trace setting made in SogSupport. If this property is not set, the TraceFlag value is read from the Windows registry. Type Function Value Usage: Visual Basic and VBScript Visual C++ Property Set long MyLink.DataTraceFlags = NewValue m_psoglink->setdatatraceflags(long nnewvalue); PowerBuilder MyLink.DataTraceFlags = NewValue 5-22

115 Methods and Properties of SOG Development Objects Properties of SogLink Error, ErrorText, ErrorDetail, ErrorDetailText All four of these are SogLink properties that report errors as follows: Error contains an error number. ErrorText supplies text associated with Error. ErrorDetail supplies additional details associated with Error, if available. ErrorDetailText supplies text associated with ErrorDetail. All the SOG objects have these four error properties. For more details about using the error dialog, see Using the SOG Error Dialog for Testing on page 4-9 and Table 4-1, Subsystem Error Types Used in SOG Error Dialog. For a list of all the error values, see Appendix C, Errors Reported by SOG Objects. Type Function Value Usage: Properties Get long for Error and ErrorDetail string for ErrorText and ErrorDetailText Visual Basic and VBScript longvar = MyLink.Error Visual C++ PowerBuilder StringVar = MyLink.ErrorText longvar = MyLink.ErrorDetail StringVar = MyLink.ErrorDetailText longvar = m_psoglink->geterror(); CStringVar = m_psoglink->geterrortext(); longvar = m_psoglink->geterrordetail(); CStringVar = m_psoglink ->GetErrorDetailText(); longvar = MyLink.Error StringVar = MyLink.ErrorText longvar = MyLink.ErrorDetail StringVar = MyLink.ErrorDetailText 5-23

116 Methods and Properties of SOG Development Objects Properties of SogLink HostAddress SogLink.HostAddress sets the host address (either the TCP/IP host name or the IP address) of the NonStop Himalaya host for SogLink and for the SogServiceObjects created by SogLink. You must set the SogLink.HostAddress property before calling the SogLink. EstablishLink method in order to set this property programmatically. If you establish the link without first setting the host address, the link uses the host address that was set for the application as a whole. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any HostAddress value assigned to the application or the service object using either the Object Manager or SogSupport. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. The order of precedence for HostAddress is: 1. Value set using SogLink.HostAddress 2. Value set for the application using Object Manager or SogSupport Type Function Property Set Value string (for example, home or ) Usage: Visual Basic and VBScript MyLink.HostAddress = NewValue Visual C++ PowerBuilder m_psoglink->sethostaddress(lpctstr lpsznewvalue); MyLink.HostAddress = NewValue 5-24

117 Methods and Properties of SOG Development Objects Properties of SogLink LogFile SogLink.LogFile specifies the file name of the log file used by SogConnect. To specify a log file programmatically, you must set this property before calling SogLink.EstablishLink; otherwise, the set has no effect. The service objects that you create with SogLink.CreateServiceObject inherit the log file from SogLink if the property was set for the link. There is no LogFile property for SogServiceObjects. You can also set the log file using the Configure SogConnect command in SogSupport. However, the LogFile property of SogLink overrides any setting made in SogSupport. Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set string MyLink.LogFile = NewValue m_psoglink->setlogfile(lpctstr filename); MyLink.LogFile = NewValue 5-25

118 Methods and Properties of SOG Development Objects Properties of SogLink LogLevel SogLink.LogLevel sets the level of logging you want for SogConnect, as follows: 0 = errors 1 = +warning 2 = +verbose You can set or change the log level for SogLink at any time, although the change does not affect running applications. Any service objects created after setting the log level inherit the new setting made using SogLink.LogLevel. You can also set the log level: Using SogServiceObject.LogLevel (for specific service objects; overrides the SogLink setting) Using the Configure SogConnect command in SogSupport SogLink.LogLevel overrides any log level setting made in SogSupport. Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set long MyLink.LogLevel = NewValue m_psoglink->setloglevel(long nnewvalue); MyLink.LogLevel = NewValue 5-26

119 Methods and Properties of SOG Development Objects Properties of SogLink Pathmon SogLink.Pathmon sets the name of the Pathmon process on the NonStop Himalaya host for SogLink and for the SogServiceObjects created by SogLink. To set the Pathmon process programmatically at the link level, you must set this value before calling SogLink.EstablishLink. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. Pathmon, System and ServerClass are properties of both SogLink and SogServiceObject, and the value you set for SogLink is inherited by all the service object created by SogLink. You can set the Pathmon name for a specific service object using the SogService Object Pathmon property. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any Pathmon value assigned to the application or the service object in either the Object Manager or SogSupport. The order of precedence for Pathmon is: 1. Value set using SogServiceObject.Pathmon 2. Value set using SogLink.Pathmon 3. Value set for the service object using Object Manager or SogSupport 4. Value set for the application using Object Manager or SogSupport Type Function Value Usage: Property Set string Visual Basic and VBScript MyLink.Pathmon = NewValue Visual C++ PowerBuilder m_psoglink->setpathmon(lpctstr lpsznewvalue); MyLink.Pathmon = NewValue 5-27

120 Methods and Properties of SOG Development Objects Properties of SogLink PortNumber SogLink.PortNumber sets the port number on the NonStop Himalaya host for SogLink and for the SogServiceObjects created by SogLink. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. You must set the SogLink.PortNumber property before calling the SogLink.Establish Link method if you want to set this property programmatically. If you establish the link without first setting the port number, the link uses the port number that was set for the application as a whole. There is no PortNumber property for SogServiceObject. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any PortNumber value assigned to the application or the service object in either the Object Manager or SogSupport. The order of precedence for PortNumber is: 1. Value set using SogLink.PortNumber 2. Value set for the application using Object Manager or SogSupport Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set short MyLink.PortNumber = NewValue m_psoglink->setportnumber(short nnewvalue); MyLink.PortNumber = NewValue 5-28

121 Methods and Properties of SOG Development Objects Properties of SogLink SendTimeout SogLink.SendTimeout specifies the length of time, in milliseconds, that the service objects created by SogLink wait for a Send to complete. The default value is 120,000 milliseconds (120 seconds). The service objects that you create with SogLink.CreateServiceObject inherit the SendTimeout from SogLink if this property is set for the link. You can also set SendTimeout for specific service objects using SogServiceObject.SendTimeout. During development and debugging, you can specify a value of -1 to wait indefinitely (this is useful for debugging a server). Programmatically setting the SogLink.SendTimeout property overrides any value that was set using the Configure SogConnect command in SogSupport. Type Function Value Usage: Property Set long (-1 means infinite wait) Visual Basic and VBScript MyLink.SendTimeout = NewValue Visual C++ PowerBuilder m_psoglink->setsendtimeout(long nnewvalue); MyLink.SendTimeout = NewValue 5-29

122 Methods and Properties of SOG Development Objects Properties of SogLink ServerClass SogLink.ServerClass sets the Pathway server class on the NonStop Himalaya host for SogLink and for the SogServiceObjects created by SogLink. To set the server class programmatically at the link level, you must set this property before calling SogLink.EstablishLink. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. ServerClass, Pathmon, and System are properties of both SogLink and SogServiceObject, and the value you set for SogLink is inherited by all the service objects created by SogLink. However, you can set the ServerClass name for specific service objects using the SogServiceObject ServerClass property. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any ServerClass value assigned to the application or the service object in either the Object Manager or SogSupport. The order of precedence for ServerClass is: 1. Value set using SogServiceObject.ServerClass 2. Value set using SogLink.ServerClass (set before calling CreateLink) 3. Value set for the service object using Object Manager or SogSupport 4. Value set for the application using Object Manager or SogSupport Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set string MyLink.ServerClass = NewValue m_psoglink->setserverclass(lpctstr lpsznewvalue); MyLink.ServerClass = NewValue 5-30

123 Methods and Properties of SOG Development Objects Properties of SogLink SubsystemError SogLink.SubsystemError(index) returns a SOG subsystem error. The subsystem, which is indicated in the SogServiceObject.Error property, is one of the following: SOGERR_COM_ERROR = 1001 SOGERR_TLB_UTILS_ERROR = 1002 SOGERR_CONVERSION_ERROR = 1003 SOGERR_GWLINK_APP_HOST_ERROR = 1004 SOGERR_NSK_LINK_ERROR = 1009 The values of index, and the meanings of each value, are given in Using the SOG Error Dialog for Testing on page 4-9. Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set long longvar = MyLink.SubsystemError(index) longvar = m_psoglink ->GetSubsystemError(index); longvar = MyLink.SubsystemError(index) 5-31

124 Methods and Properties of SOG Development Objects Properties of SogLink SubsystemErrorText SogLink.SubsystemErrorText(index) returns text associated with SubsystemError, for those errors for which error text is available. The values of index, and the meanings of each value, are given in Evaluating Subsystem Errors on page Type Function Value Usage: Property Set string index as long Visual Basic and VBScript StringVar = MyLink.SubsystemErrorText(index) Visual C++ PowerBuilder CStringVar = m_psoglink ->GetSubsystemErrorText(index); StringVar = MyLink.SubsystemErrorText(index) 5-32

125 Methods and Properties of SOG Development Objects Properties of SogLink System SogLink.System sets the system name of the NonStop Himalaya host for SogLink and for the SogServiceObjects created by SogLink. This system name is the Expand node name of the host, which is uppercase and includes a leading backslash "\" (for example, \THOST). To set the system programmatically at the link level, you must set this property before calling SogLink.EstablishLink. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. System, ServerClass, and Pathmon are properties of both SogLink and SogServiceObject, and the value you set for SogLink is inherited by all the service objects created by SogLink. You can set the System name for a specific service object using the SogService Object System property. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any System value assigned to the application or the service object in either the Object Manager or SogSupport. The order of precedence for System is: 1. Value set using SogServiceObject.System 2. Value set using SogLink.System 3. Value set for the service object using Object Manager or SogSupport 4. Value set for the application using Object Manager or SogSupport Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set string (such as \THOST) MyLink.System = NewValue m_psoglink->setsystem(lpctstr lpsznewvalue); MyLink.System = NewValue 5-33

126 Methods and Properties of SOG Development Objects Methods of SogServiceObject Methods of SogServiceObject All the SOG service objects that you create using the CreateServiceObject method of SogLink have a common set of stock or fixed methods. Note. The termsogserviceobject is used in this manual to represent an individual service object that you create using SogLink.CreateServiceObject. There is no actual object named SogServiceObject, whereas the objects SogConnect and SogLink do exist. The stock methods of SogServiceObject are: DisplayConvErrorDialog on page 5-34 DisplayErrorDialog on page 5-35 GetDirectBufferInterface on page 5-36 InitializeRequest on page 5-37 ReleaseServiceObject on page 5-38 Send on page 5-39 The methods of SogServiceObject are described on the following pages. DisplayConvErrorDialog SogServiceObject.DisplayConvErrorDialog displays the SOG data conversion error dialog. (The SOG conversion error dialog is for development use only; it is not intended for production or run-time use.) Only SogServiceObject contains this method. Type Arguments Return Type Usage: Visual Basic VBScript Visual C++ PowerBuilder Method None serviceobject.displayconverrordialog Not available m_pserviceobject -> DisplayConvErrorDialog(); serviceobject.displayconverrordialog 5-34

127 Methods and Properties of SOG Development Objects Methods of SogServiceObject DisplayErrorDialog SogServiceObject.DisplayErrorDialog displays the SOG error dialog. (The SOG error dialog is for development use only; it is not intended for production or run-time use.) All three SOG objects contain this method. Type Arguments Return Type Usage: Visual Basic VBScript Visual C++ PowerBuilder Method None SogServiceObject.DisplayErrorDialog Not available m_pserviceobject -> DisplayErrorDialog(); SogServiceObject.DisplayErrorDialog 5-35

128 Methods and Properties of SOG Development Objects Methods of SogServiceObject GetDirectBufferInterface SogServiceObject.GetDirectBufferInterface enables the use of direct buffer access to ease POET migration, specifically in Visual C++. Using direct buffer access is accomplished differently in the various supported client tools, as follows: In Visual C++, use the GetDirectBufferInterface method to create an IDirectBufferAccess interface pointer, which you can call directly. In Visual Basic, instead of using the GetDirectBufferInterface method, you need to call the SetRequestBuffer and the GetReplyBuffer functions of the SogService Utils.DLL and pass in your service object as described later in this section in Code Examples in Visual Basic on page In PowerBuilder, use the PowerBuilder GetAutomationNativePointer statement to create a pointer to your service object. Then, call the SetRequestBuffer and GetReplyBuffer functions of SogServiceUtils.DLL and pass in the pointer, as described later in this section in Code Examples in PowerBuilder on page The direct buffer interface has calls to set values in the actual service objects. See your development tool for a list of calls. For more information, see Deciding How to Handle Request and Reply Buffers on page 4-8. Type Arguments Return Type Usage: Visual Basic VBScript Visual C++ PowerBuilder Method None None See alternate method described in Code Examples in Visual Basic on page Not available LPUNKNOWN m_pserviceobject ->GetDirectBufferInterface(); See alternate method described in Code Examples in PowerBuilder on page

129 Methods and Properties of SOG Development Objects Methods of SogServiceObject InitializeRequest SogServiceObject.InitializeRequest initializes the buffer with default values for all the request fields of the service object. This method allows you to send a request to the NonStop Himalaya server while setting only a few fields and leaving the rest as initialized. The fields are initialized according to the data types. InitializeRequest clears conversion errors. This method has no effect when using direct buffer access. Type Arguments Return Type Usage: Visual Basic VBScript Visual C++ PowerBuilder Method None None ServiceObject.InitializeRequest Not available m_pserviceobject->initializerequest(); ServiceObject.InitializeRequest 5-37

130 Methods and Properties of SOG Development Objects Methods of SogServiceObject ReleaseServiceObject SogServiceObject.ReleaseServiceObject releases SOG s private reference to a specified service object when the service object is set to Nothing in the client application. Use this method to free resources associated with the service object when you release all user references to the service object. Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method None Boolean ServiceObject.ReleaseServiceObject m_pserviceobject->releaseserviceobject(); ServiceObject.ReleaseServiceObject 5-38

131 Methods and Properties of SOG Development Objects Methods of SogServiceObject Send SogServiceObject.Send sends a service object (request message) to the NonStop Himalaya host and returns the reply message. Type Arguments Return Type Usage: Visual Basic and VBScript Visual C++ PowerBuilder Method None Boolean ok = ServiceObject.Send ok = m_pserviceobject->send(); ok = ServiceObject.Send 5-39

132 Methods and Properties of SOG Development Objects Properties of SogServiceObject Properties of SogServiceObject All the service objects that you create using the CreateServiceObject method of SogLink have a common set of stock or fixed properties, listed below. Note. The term SogServiceObject is used in this manual to represent an individual service object that you create using SogLink.CreateServiceObject. There is no actual object named SogServiceObject, whereas the objects SogConnect and SogLink do exist. In addition to the stock properties, your service objects have the properties that you assigned to them using the Object Manager. The properties you assigned are the elementary items of the Request and Reply messages. The properties of SogServiceObject are: AutoDisplayConvErrorDialog on page 5-41 AutoDisplayErrorDialog on page 5-42 DataTraceFlags on page 5-43 Error, ErrorText, ErrorDetail, ErrorDetailText on page 5-44 LogLevel on page 5-45 Pathmon on page 5-46 ReplyBufferSize on page 5-47 ReplyExpectedSize on page 5-48 SendTimeout on page 5-49 ServerClass on page 5-50 SubsystemError on page 5-51 and SubsystemErrorText on page 5-52 System on page 5-53 These properties of SogServiceObject are described in alphabetic order on the following pages. 5-40

133 Methods and Properties of SOG Development Objects Properties of SogServiceObject AutoDisplayConvErrorDialog SogServiceObject.AutoDisplayConvErrorDialog, if true, automatically displays a dialog box displaying SOG data conversion messages if there is a data conversion error. (The SOG conversion error dialog is for development use only; it is not intended for production or run-time use.) Only the SogServiceObject object contains this property. Type Function Value Usage: Property Set Boolean Visual Basic serviceobject.autodisplayconverrordialog = True False VBScript Visual C++ Not available m_pserviceobject ->SetAutoDisplayConvErrorDialog(long nnewvalue); PowerBuilder serviceobject.autodisplayconverrordialog = True False 5-41

134 Methods and Properties of SOG Development Objects Properties of SogServiceObject AutoDisplayErrorDialog This SogServiceObject property, if true, automatically displays a dialog with error messages when an error occurs involving the SOG tools. The SOG error dialog is for development use only; it is not intended for production or run-time use. For more information about the SOG error dialog, see Using the SOG Error Dialog for Testing on page 4-9. All three SOG objects contain this property. Type Function Value Usage: Property Set Boolean Visual Basic serviceobject.autodisplayerrordialog = True False VBScript Visual C++ Not available m_pserviceobject ->SetAutoDisplayErrorDialog(long nnewvalue); PowerBuilder serviceobject.autodisplayerrordialog = True False 5-42

135 Methods and Properties of SOG Development Objects Properties of SogServiceObject DataTraceFlags This SogServiceObject property is a bit-field flag. Before setting this property, determine its value by performing a logical-and of the following SOG-defined values: SOG_CON_TRACE_REQ_BUFF_ BEFORE_CONV = 1 SOG_CON_TRACE_REQ_BUFF_ AFTER_CONV = 2 SOG_CON_TRACE_REP_BUFF_ BEFORE_CONV = 4 SOG_CON_TRACE_REP_BUFF_ AFTER_CONV = 8 If any field is set, SogServiceObject writes appropriate trace information to the TraceFile. Data tracing can also be enabled in SogSupport using the Configure SogConnect command. The SogServiceObject.DataTraceFlags property overrides any trace setting made in SogSupport as well as any trace setting made with SogLink.DataTraceFlags. (The setting made with SogLink.DataTraceFlags is the default value inherited by service objects created by SogLink.) If this property is not set, the TraceFlag value is read from the Windows registry. Type Function Value Usage: Property Set long Visual Basic and VBScript serviceobject.datatraceflags = NewValue Visual C++ PowerBuilder m_pserviceobject->setdatatraceflags(long nnewvalue); serviceobject.datatraceflags = NewValue 5-43

136 Methods and Properties of SOG Development Objects Properties of SogServiceObject Error, ErrorText, ErrorDetail, ErrorDetailText All four are SogServiceObject properties that report errors as follows: Error contains an error number. ErrorText supplies text associated with Error. ErrorDetail supplies additional details associated with Error, if available. ErrorDetailText supplies text associated with ErrorDetail. All the SOG objects have these four error properties. For more details about using the error dialog, see Using the SOG Error Dialog for Testing on page 4-9 and Table 4-1, Subsystem Error Types Used in SOG Error Dialog. For a list of all the SOG error values, see Appendix C, Errors Reported by SOG Objects. Type Function Value Usage: Properties Get long for Error and ErrorDetail string for ErrorText and ErrorDetailText Visual Basic and VBScript longvar = serviceobject.error Visual C++ PowerBuilder StringVar = serviceobject.errortext longvar = serviceobject.errordetail StringVar = serviceobject.errordetailtext longvar = m_pserviceobject->geterror(); CStringVar = m_pserviceobject- >GetErrorText(); longvar = m_pserviceobject ->GetErrorDetail(); CStringVar = m_pserviceobject ->GetErrorDetailText(); longvar = serviceobject.error StringVar = serviceobject.errortext longvar = serviceobject.errordetail StringVar = serviceobject.errordetailtext 5-44

137 Methods and Properties of SOG Development Objects Properties of SogServiceObject LogLevel SogServiceObject.LogLevel sets the desired level of logging, as follows: 0 = errors 1 = +warning 2 = +verbose Use SogServiceObject.LogLevel to override the default settings for the service object (inherited from SogLink or set in SogSupport using Configure SogConnect). Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set integer serviceobject.loglevel = NewValue m_pserviceobject->setloglevel(long nnewvalue); serviceobject.loglevel = NewValue 5-45

138 Methods and Properties of SOG Development Objects Properties of SogServiceObject Pathmon SogServiceObject.Pathmon sets the name of the Pathmon process on the NonStop Himalaya host for SogServiceObjects. Pathmon, System and ServerClass are properties of both SogLink and SogServiceObject. You can set the Pathmon name for a service object using the SogServiceObject Pathmon property. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any Pathmon value assigned to the application or the service object in either the Object Manager or SogSupport. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. The order of precedence for Pathmon is: 1. Value set using SogServiceObject.Pathmon 2. Value set using SogLink.Pathmon 3. Value set for the service object using Object Manager or SogSupport 4. Value set for the application using Object Manager or SogSupport Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set string serviceobject.pathmon = NewValue m_pserviceobject->setpathmon(lpctstr lpsznewvalue); serviceobject.pathmon = NewValue 5-46

139 Methods and Properties of SOG Development Objects Properties of SogServiceObject ReplyBufferSize SogServiceObject.ReplyBufferSize returns the actual size of the reply buffer for a given service object from the NonStop Himalaya host. Use this property to determine the actual size of the buffer returned from the host. Type Function Value Property Get long Usage: Visual Basic and VBScript longvar = serviceobject.replybuffersize Visual C++ PowerBuilder longvar = m_pserviceobject-> GetReplyBufferSize(); longvar = serviceobject.replybuffersize 5-47

140 Methods and Properties of SOG Development Objects Properties of SogServiceObject ReplyExpectedSize SogServiceObject.ReplyExpectedSize sets the expected size of the reply buffer from the NonStop Himalaya host. Use this property when the reply size is likely to be larger than the size indicated in the original DDL definition. For example, the reply size can be larger if the DDL definition contains OCCURS DEPENDING ON fields, and your server is returning more than was allowed for in the DDL description. Type Function Value Property Set integer Usage: Visual Basic and VBScript serviceobject.replyexpectedsize = NewValue Visual C++ m_pserviceobject->setreplyexpectedsize(long nnewvalue); PowerBuilder serviceobject.replyexpectedsize = NewValue 5-48

141 Methods and Properties of SOG Development Objects Properties of SogServiceObject SendTimeout SogServiceObject.SendTimeout specifies the length of time, in milliseconds, to wait for a Send to complete. The default value is 120,000 milliseconds (120 seconds). Service objects inherit a default value from either of the following sources: The current registry value, set by SogSupport SogLink.SendTimeout, if the property is set for the link Programmatically setting the SendTimeout property overrides any value that was set using the Configure SogConnect dialog box in SogSupport. During development and debugging, you can specify a value of -1 to wait indefinitely (this is useful for debugging a server). Type Function Value Property Set long (-1 means infinite wait) Usage: Visual Basic and VBScript Visual C++ PowerBuilder serviceobject.sendtimeout = NewValue m_pserviceobject->setsendtimeout(long nnewvalue); serviceobject.sendtimeout = NewValue 5-49

142 Methods and Properties of SOG Development Objects Properties of SogServiceObject ServerClass SogServiceObject.ServerClass sets the server class of the target Pathway server on the NonStop Himalaya host for this SogServiceObject. ServerClass, Pathmon, and System are properties of both SogLink and SogServiceObject. You can set the ServerClass name for a service object using the SogServiceObject ServerClass property. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any ServerClass value assigned to the application or the service object in either the Object Manager or SogSupport. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. The order of precedence for ServerClass is: 1. Value set using SogServiceObject.ServerClass 2. Value set using SogLink.ServerClass (set before calling CreateLink) 3. Value set for the service object using Object Manager or SogSupport 4. Value set for the application using Object Manager or SogSupport Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set string serviceobject.serverclass = NewValue m_pserviceobject->setserverclass(lpctstr lpsznewvalue); serviceobject.serverclass = NewValue 5-50

143 Methods and Properties of SOG Development Objects Properties of SogServiceObject SubsystemError SogServiceObject.SubsystemError(index) contains a SOG subsystem error number. The SubsystemError fields contain additional error information if SogServiceObject.Error is one of the following: SOGERR_COM_ERROR = 1001 SOGERR_TLB_UTILS_ERROR = 1002 SOGERR_CONVERSION_ERROR = 1003 SOGERR_GWLINK_APP_HOST_ERROR = 1004 SOGERR_NSK_LINK_ERROR = 1009 The values of index, and the meanings of each value, are given in Evaluating Subsystem Errors on page Type Function Value Usage: Property Get long Visual Basic and VBScript longvar = serviceobject.subsystemerror(index) Visual C++ PowerBuilder longvar = m_pserviceobject ->GetSubsystemError(index); longvar = serviceobject.subsystemerror(index) 5-51

144 Methods and Properties of SOG Development Objects Properties of SogServiceObject SubsystemErrorText SogServiceObject.SubsystemErrorText(index) contains additional text, if available, pertaining to a SOG subsystem error reported in SogServiceObject.SubsystemError. The subsystems are listed for SubsystemError. The values of index, and the meanings of each value, are given in Evaluating Subsystem Errors on page Type Function Value Usage: Property Get string index as long Visual Basic and VBScript StringVar = serviceobject.subsystemerrortext(index) Visual C++ CStringVar = m_pserviceobject ->GetSubsystemErrorText(index); PowerBuilder StringVar = serviceobject.subsystemerrortext(index) 5-52

145 Methods and Properties of SOG Development Objects Properties of SogServiceObject System SogServiceObject.System sets the system name of the NonStop Himalaya host for the SogServiceObject. The value you set must include the leading backslash in the system name (such as \HOST). System, Pathmon, and ServerClass are properties of both SogLink and SogServiceObject. You can set the System name for a service object using the SogServiceObject System property. This property can also be set using the Object Manager and SogSupport. However, a value that you set programmatically using this property overrides any System value assigned to the application or the service object in either the Object Manager or SogSupport. It is not recommended to set this property programmatically because this prevents you from setting the property in SogSupport. The order of precedence for System is: 1. Value set using SogServiceObject.System 2. Value set using SogLink.System 3. Value set for the service object using Object Manager or SogSupport 4. Value set for the application using Object Manager or SogSupport Type Function Value Usage: Visual Basic and VBScript Visual C++ PowerBuilder Property Set string serviceobject.system = NewValue m_pserviceobject->setsystem(lpctstr lpsznewvalue); serviceobject.system = NewValue 5-53

146 Methods and Properties of SOG Development Objects Properties of SogServiceObject 5-54

147 6 Supporting Customer Applications Use the SogSupport tool on the PC to configure and support a TIC Server Object Gateway installation. SogSupport is intended for the use of trained support personnel. However, the end user may be asked to run the Support program on behalf of the support team. This section describes using the SogSupport tool to perform the following tasks: View the host database that is currently configured as the run-time host database in SogSupport (page 6-3). Change the server properties of SOG applications and their service objects in displayed the database (page 6-3). Configure SogConnect and SogGateway (configuring SogGateway includes specifying the run-time host database, which is displayed by the Applications Show command) (page 6-5 and 6-6). Test the connection between TIC Server Object Gateway and the NonStop Himalaya host (page 6-8). Test whether unsolicited messages are being received from the NonStop Himalaya host by your TIC Server Object Gateway installation (page 6-9). Start the NSKLink Trace function for SOG product support (do this only on advice of support personnel) (page 6-10). View SOG application type libraries using the Type Library Viewer (page 6-1 1). Register SOG type libraries using SogSupport (page 6-1 1). Register or unregister SOG typ e libraries using an EXE file or a DLL call (page 6-1 1). Copy a SOG application and its run-time service objects file from one host database to another host database. (Copying a SOG application from the development host database to the run-time host database is a required step in deploying a SOG client application.) (page 6-14). Delete an application from a SOG host database (page 6-16). Import a SOG application into a host database from another host database that is not simultaneously connected to SogSupport (page 6-17 ). 6-1

148 Supporting Customer Applications Gathering Inform ation for Prob lem Solving Gathering Information for Problem Solving SogSupport offers several features that are helpful for gathering information about your system and about your TIC Server Object Gateway installation. You may be asked by TIC Support to use these features when reporting and solving problems. Help About Server Object Gateway Support command This command displays version information for SogSupport. On the About dialog box, you can click two buttons to get more information, as follows : Server Object Gateway Information button Displays version information for SOG components. Displays the values stored in the Windows registry for SOG (by default, stored in C:\ Program Files\NSSog \Bin\SogProductInfo.txt) System Info button Displays Microsoft system information about the PC workstation. Data Trace functions Enable Data Trace for SogConnect and SogGateway if directed to do so by support personnel or your system administrator. Use the Configure SogConnect and Configure SogGateway commands as described in this section. Tools SOG Product Support command Enable NSKLink Trace if directed to do so by support personnel. Use the SOG Product Support command as described in this section in Starting the NSKLink Trace Function. Connecting to the Run-Time Host Database If you cannot open the host database after starting SogSupport, you might need to configure the connection to the run-time host database using SogSupport. 1. Select the Configure SogGateway command. 2. On the Sog Run-Time Database tab, verify that all the fields are specified and the settings are correct. You need to specify System, Pathmon, Server class, Host Name/Address, and Port. 6-2

149 Supporting Customer Applications Viewing and Changing Server Properties of Applications and Service Objects Viewing and Changing Server Properties of Applications and Service Objects The PC running SogSupport must be connected using TCP/IP to the host system that contains the database you want to view, and the database must be the one configured as the run-time host database for SogGateway, as described in Configuring the SogGateway Component. 1. Using SogSupport, select the Applications Show command. The Applications window displays the applications stored in the run-time host database, which is currently specified on the SogGateway configuration dialog box. Like the Applications window in the Object Manager, the right-hand side of the window displays the properties of the selected application or service object. 2. On the Applications window, you can: View the names of the service objects in a specific application. Change or update the server properties of the applications and service objects as needed for deployment to the run-time system. For an application, you can change the values in the following fields: The run-time service objects file, which contains the host information about the service objects in the selected application (typically, you would not change this file name; the correct file is required at run time). Default values for the three server properties of the service objects in the application: Pathmon system name (the name of the target host system) Pathmon process (the name of the Pathmon process on the target system) Pathmon server class (the server class containing the target Pathway server) TCP/IP connection information: Host Name/Address (the TCP/IP host name or the IP address of the runtime NonStop Himalaya host system) Host Port (the port number assigned to the TCP/IP port that will be used to connect the completed client application to the NonStop Himalaya server) To display the service objects contained in an application, expand the tree control on the left side of the window. To display the properties of a service object, select the object. For a service object, you can set or change: The three server properties listed above (System, Pathmon, Server class). The security ID, an optional password containing as many as 16 characters. If a security ID is specified, the client application must provide the correct security ID in order to use the service object. The security ID can contain any alphanumeric characters or punctuation marks, and is both case-sensitive and space-sensitive. 6-3

150 Supporting Customer Applications Viewing and Changing Server Properties of Applications and Service Objects In addition, the SogSupport Applicationswindow displays, for information only, the Generation date (when the service object was generated by the Object Manager) and the modification date of the service object. Order of Precedence for Server Properties The host server properties (System, Pathmon, and Server Class) embody the target Pathway server for an object (that is, for a SOG application or service object). You can set the server properties for these objects in two ways: Programmatically, using the SOG objects (SogLink and SogServiceObject) Using the SOG GUIs (the Object Manager or SogSupport) To summarize, the order of precedence for server properties is as follows: 1. Values set programmatically using SogServiceObject properties. 2. Values set programmatically using SogLink properties. 3. Values set for the service objects (in either the Object Manager or SogSupport). 4. Values set for the application as a whole (in the Object Manager or SogSupport). Thus, a value that you set programmatically at the service object level overrides any value previously set either programmatically at the SogLink level or using the Object Manager or using SogSupport. To set the server properties programmatically, use the SOG tools as described in Section 4, Developing Your Client Application. In SogSupport and the Object Manager, if these properties are not specified for the service object, the values used are those set for the application properties. Strategy for Setting Server Properties in Your Application A typical strategy is to set the server properties for the SOG application as a whole when you create the application in the Object Manager. The server properties set for the application act as default values for all the service objects within the application. Then, before you build the application, you might set server properties for individual service objects that have a different target server. After you build the application, the service object properties that you set retain their settings, but any server properties that you did not set receive the server properties that are set for the application. (The Object Manager requires you to specify at least the Pathmon and Server class properties for the application or for the service objects in order to generate and build.) Finally, in your completed client application, you can programmatically change the server properties using the SOG objects (SogLink and SogServiceObject). This capability may be useful during development and testing, but it is not recommended to set the server properties programmatically in your client application. Reversing hardcoded programmatic settings requires rewriting and installing code, whereas using SogSupport to change the server properties for an application can easily be done on one dialog box. 6-4

151 Supporting Customer Applications Configuring the SogConnect Component Configuring the SogConnect Component Use the Configure SogConnect command to view and change the configuration values for the SogConnect component of TIC Server Object Gateway. The values you can change for SogConnect are for application send time-out, application logging, and data trace functions only. Procedure 1. Using SogSupport, select the Configure SogConnect command. 2. On the Client Default Values for Local Applications tab, you can specify the default value for the Send Timeout for Applications. This is the amount of time that a local SOG client application waits for a message to be sent to the host. 3. On the Log tab, you can specify the name of the log file and logging parameters as follows: Log File Name The name of the file on the run-time PC that will contain the logging records for SogConnect operations. Logging occurs by default, and the default log file for SogConnect is SogConnect.log in the location where TIC Server Object Gateway is installed. Log Timeout in Seconds The amount of time to wait if there is a delay in writing to the log. Log Level The level of logging messages you want recorded in the log. You can select one of the following: Errors to see only errors. Warnings to see errors and warnings. Verbose to see errors, warnings, and comments. 1. On the Data Trace tab, you can enable data tracing by checking: Enable Trace In ordinary conditions, data trace should not be enabled, because tracing significantly affects performance for TIC Server Object Gateway. However, you may be asked by support personnel to enable data tracing in order to examine the raw buffers if alignment or data conversion problems arise. The data trace for SogConnect shows each field individually as it is converted as well as the entire IPC. The trace gives the service object and application names, the data address in Hex and ASCII, and the IPC offset. On the Data Trace tab, you can specify data trace parameters as follows: Trace Filename The name of the PC file to receive the data trace records. The default trace file for SogConnect is SogConnect.trc, located in the SOG installation directory. 6-5

152 Supporting Customer Applications Configuring the SogGateway Component Trace File Timeout (in seconds) The amount of time for SogConnect to wait if there is a delay in writing to the trace file. Data Trace Options: The point for the data trace to occur in the data transfer between SogConnect and the host. You can select any or all of the following: Message to Pathway Server Before Data Conversion Message to Pathway Server After Data Conversion Message from Pathway Server Before Data Conversion Message from Pathway Server After Data Conversion 2. After completing all the fields that you want to change on the Configure SogConnect dialog box, click OK. The OK button enacts all the changes you entered on all the tabs of the dialog box. Configuring the SogGateway Component Use the Configure SogGateway command to view and change the configuration values for the SogGateway component of TIC Server Object Gateway. The values you can set for SogGateway include send timeout, run-time host database configuration, and logging and data trace. Specifying the Run-Time Host Database Location Use the Configure SogGateway dialog box to specify configuration values for the run-time host database. When you install the host components of a run-time SOG installation, the SOG Installer configures the location of the database server for the SOG run-time host database. Using SogSupport, you can specify new values for the run-time host database.you may need to do this when deploying your completed client application to the production (run-time) system. Procedure 1. Using SogSupport, close the host database if the database is open (use the File Close Host Database command).you cannot change the run-time host database configuration when the host database is open. 2. Select the Configure SogGateway command. The Configure SogGateway dialog box appears. 3. On the General tab of the Configure SogGateway dialog box, you can change the following values: Send Timeout (default, minimum, and maximum values) Send Timeout is the amount of time (in seconds) that SogGateway waits for a reply from the SOG host database server (OGDBSVR). 6-6

153 Supporting Customer Applications Procedure 4. On the SOG Run-Time Database tab, specify the database server for the run-time host database to which SogSupport is connected. (This is the database that is displayed by the Applications Show command in SogSupport and is used as the destination for Applications Copy.) You can set the following fields for SOG Run-Time Host Database: System Pathmon Server Class Host Name/Address Port The name of the run-time (production) host system The name of the Pathmon process that will control the SOG run-time host database (typically, $SOG). The name of the server class of the SOG host database server (typically, SOGDB-SERVER). The TCP/IP host name or the IP address of the runtime NonStop Himalaya host system. The TCP/IP port number that SogGateway will use to communicate with the run-time host database server (for example,1234). 5. On the Log tab, you can specify the name of a log file and logging parameters as follows: Log File Name The name of the file on the run-time PC that will containthe error logging records for SogGateway operations. Logging occurs by default, and the default log file for SogGateway is SogGateway.log in the location where TIC Server Object Gateway is installed. Log Timeout in Seconds The amount of time that SogGateway waits if there is a delay in writing to the log. Log Level The level of logging messages you want recorded in the log. You can select: Errors to see only errors. Warnings to see errors and warnings. Verbose to see errors, warnings, and comments. 1. On the Data Trace tab, you can enable data tracing by checking the Enable Trace checkbox. In ordinary conditions, data trace should not be enabled because tracing causes a decrease in performance for TIC Server Object Gateway. However, you may be asked by support personnel to enable data tracing in order to examine the raw buffers if alignment or data conversion problems arise. The data trace for SogGateway does not show individual applications, service object fields, or IPCs 6-7

154 Supporting Customer Applications Testing the SOG Connection to the Host On the Data Trace tab, you can specify data trace parameters as follows: Trace Filename The name of the PC file to receive the data trace records. SogGateway.trc is the default trace file for SogGateway; it is located in the SOG installation directory. Trace File Timeout (in seconds) The amount of time for SogGateway to wait if there is a delay in writing to the trace file. Data Trace Options: The point for the data trace to occur in the data transfer between SogGateway and the host. You can select either or both of the following options; Message to Pathway Server Message from Pathway Server 2. After completing all the fields that you want to change on the Configure SogGateway dialog box, click OK. The OK button enacts all the changes made on all the tabs of the dialog box. Testing the SOG Connection to the Host 1. Using SogSupport, select the Test SOG Connect to Host command to verify that the NonStop Himalaya host is in proper communication with SogConnect and SogGateway. 2. If SogSupport currently has a Gateway link open (typically open for the Applications Show or Applications Copy commands), a dialog box is displayed asking whether you want to release the existing Gateway link. If you click Yes, the existing Gateway link is closed and a new one is opened using the current SogGateway configuration values. The test is run on the new Gateway link. If you click No, the existing Gateway link is used for the test 3. The Test SogConnect to Host dialog box is displayed. In the Send Count field, enter the number of times you want to send a test message to the host. 4. Either click Send or press Return to send the test message or messages to the host. SogSupport sends a test message through SogConnect to SogGateway. Then SogGateway sends the message to the run-time SOG database server (OGDBSVR). When the server replies to SogSupport, the reply is checked, and the transmission time is displayed. Resolving Connection Errors If an error occurs, and the test does not succeed, try the following steps: 1. Verify that the PC is communicating with the NonStop Himalaya host. If necessary, issue a TCP/IP ping to the host address. 6-8

155 Supporting Customer Applications Testing UMS Functionality 2. Check that the SogGateway configuration for the run-time host database has valid values for: System name Pathmon process name Pathmon server class Host name/address Port 3. Verify that the host Pathway environment specified in the SogGateway configuration is running and that all the Pathway servers are running. 4. Check the OUT files for the NSKLLSNR and PWSVRLNK servers for errors (the names of the OUT files for these servers are specified in the PATHCNFG file). Correct those errors before retrying the Test SOG Connect to Host command. 5. Using SogSupport, turn on logging for SogConnect. Then check the log file (by default, SogConnect.log). 6. Check the SogSupport.log file in the installed TIC Server Object Gateway directory. Testing UMS Functionality If you want your SOG application to receive any unsolicited messages that may originate from the NonStop Himalaya host, you should verify that UMS messages (Unsolicited Message Service messages) are being successfully received. One of the SOG host processes (NSKLUMSW) watches for unsolicited messages coming from the host to the TIC Server Object Gateway components on the host and the PC. The Test Unsolicited Messages command sends an unsolicited message to NSKLUMSW on the host. The ultimate destination of the message is the PC components of SOG. 1. Using SogSupport, select the Test Unsolicited Messages command. The Test Unsolicited Messages dialog box is displayed. 2. Specify a UMSLinkID (a name for your message test). This can be any 32- character string that identifies your message, or you can specify * to send a UMS message to all UMS-enabled SOG applications. (To enable UMS for a SOG application, call the SogLink.EnableUMS method. For the test only, there is an Enable UMS button.) 3. Specify the process name of the NSKLUMSW-SVR process on the host. An example of a process name is $TSG1. 4. Enter a message. You can specify any text or data, or a data structure. The message can be as many as 100 bytes. 6-9

156 Supporting Customer Applications Starting the NSKLink Trace Function 5. Click the Enable UMS button. This enables SogSupport to receive UMS messages. 6. Click the Send UMS button. Your UMS message is sent to the host and SosSupport displays a message confirming that the message was sent. 7. Click the Get UMS button. 8. Watch the UMS Message Received field to verify that the message returns correctly. To send another message after receiving a UMS message, first click the Clear button to clear the Message Received field. If you encounter an error, refer to the SogSupport.log file in the installed location of TIC Server Object Gateway on the PC. If no UMS message is received, start the procedure again at step 3. Sending Unsolicited Messages on the Host To test sending an unsolicited message from your program on the host: 1. Perform steps 1 and 2 in the previous procedure (for testing UMS). 2. Send a message from your program on the host using the appropriate UMSLinkID or the wild-card *. 3. Click Get UMS to receive the unsolicited message. For information, see Sending UMS Messages on the NonStop Himalaya Host on page Starting the NSKLink Trace Function NSKLink Trace can trace programmatic activity of the TIC Server Object Gateway components. Use the NSKLink Trace function only when requested to do so by support personnel investigating a reported problem with TIC Server Object Gateway. Running NSKLink Trace significantly decreases system performance. 1. Using SogSupport, select Tools SOG Product Support. 2. Select the trace options you need: NSKLink Trace Option Enable Trace Start Tracing Now Enable Object Manager Trace Description Starts tracing any SOG application the next time the application starts. Starts tracing SOG applications that are already running, with an active link to the host. Starts tracing the next time the Object Manager starts. 6-10

157 Supporting Customer Applications Viewing Type Libraries The following trace options are available: Trace API Trace Sends Trace Filename Trace Connects Trace UMS Trace Host IPC Bytes to display 3. Click OK. 4. In the NSKLink Trace window, select File Save to save the trace output to a file. Viewing Type Libraries Using SogSupport, select the Type Libraries View Type Library command to start the Type Library Viewer. SogSupport uses the same Type Library Viewer provided by the Object Manager. The viewer opens either the location where the last successful type library operation occurred, or the installed location of SogSupport. Registering Type Libraries When you build an application in the Object Manager, the application type libraries are automatically registered for you. However, if you move your type libraries, you need to use So gsupport to register the type libraries in the new location. 1. Using SogSupport, select the Type Libraries Register Type Library command to select a type library to register. The Register Type Library dialog box displays type library files for the applications you ve created using the Object Manager. 2. Select the type library you want to register, and then click Open. If the type library you want to register is located in another directory, click the Browse button and select the correct directory. 3. SogSupport automatically registers the selected type library and displays a confirmation message. Registering Type Libraries for Your Run-Time Installation You can also register type libraries programmatically during installation of your completed client application. TIC Server Object Gateway provides two methods: SogRegTLBFile.EXE SogRegisterTLBFile function in SogUtils.DLL Using SogRegTLBFile.EXE to Register Type Libraries SogRegTLBFile.EXE is an interactive program, similar to RegSvr32.exe, for registering type libraries. Run the.exe file from the MS-DOS command prompt. 6-11

158 Supporting Customer Applications Registering Type Libraries for Your Run-Time Installation The syntax of SogRegTLBFile.EXE is: SogRegTLBFile [options] <tlbfilename>.tlb options = /s Don't show dialog with success or failure /u Unregister the type library Using SogUtils.DLL to Register Type Libraries You can use the SogRegisterTLBFile and SogUnRegisterTLBFile functions in the SogUtils.DLL to register and unregister application type libraries for you. The syntax of SogRegisterTLBFile is: HRESULT SogRegisterTLBFile(char* tlbfilename, BOOL bshowdialog); The syntax of SogUnRegisterTLBFile is: HRESULT SogUnRegisterTLBFile(char* tlbfilename, BOOL bshowdialog); If tlbfilename is empty or NULL, the call returns ERROR_INVALID_DATA (13L). If tlbfilename does not exist, the call returns ERROR_FILE_NOT_FOUND (2L). Otherwise, the call returns the HRESULT from the Windows Typelibrary routines. You can incorporate these DLL calls into your application s InstallShield installation code, as shown in the following example: InstallShield script code prototype NUMBER SogUtils.SogRegisterTLBFile(STRING, NUMBER); // declares function in DLL ///////////////////////////////////////////////////////////// // Function: RegisterTypeLibraries // Must be called after SOG files are installed so that // SOGUTILS.DLL can be used. ///////////////////////////////////////////////////////////// function RegisterTypeLibraries() STRING szdir, szfilenamepattern, svfilename, szdll; NUMBER nop, nhresult; begin // register each example.tlb file szdll = TARGETDIR ^ "sogutils.dll"; szdir = TARGETDIR if(usedll(szdll) = 0) then nop = RESET; szfilenamepattern = "*.TLB"; 6-12

159 Supporting Customer Applications Registering Type Libraries for Your Run-Time Installation while(findallfiles (szdir, szfilenamepattern, svfilename, nop) = 0) nop = CONTINUE; nhresult = SogRegisterTLBFile(svFileName, FALSE); // don't show dialog endwhile UnUseDLL(szDLL); endif; end; 6-13

160 Supporting Customer Applications Copying Applications to a Host Database Copying Applications to a Host Database Use the Applications Copy command to copy an application from a source host database to a destination host database. For example, a necessary step in application deployment is to use the Copy command to copy an application from the development host database into the run-time host database. The PC running SogSupport must be able to simultaneously connect, using TCP/IP, to both the source and the destination host database. You can also delete selected applications from the destination host database. 1. Using SogSupport, select the Applications Copy command. The Copy Applications From dialog box is displayed. 2. Specify the location of the source host database -- the one from which you want to copy applications to another host database. Typically, the source will be the development host database. However, it is possible to specify a run-time host database for the source in the copy operation. (The destination host database is always the one configured as the run-time host database for SogGateway. During testing, this might be a design host database.) To specify the source host database, enter or select values for the following fields: System Pathmon Server Class Host Name/Address Port The name of the NonStop Himalaya system (such as \THOST) that contains the application you want to copy. Typically this is the name of the development (designtime) host. The name of the Pathmon process that controls the source SOG host database (such as $SOG). The name of the server class of the Pathmon process (typically, SOGDB-SERVER). The TCP/IP host name or the IP address of the development host system. 3. Click OK to open the specified source host database. The Copy Applications dialog box is displayed. The TCP/IP port number (such as 1234) that is used to communicate with the NSKLLSNR server. 6-14

161 Supporting Customer Applications Copying Applications to a Host Database Figure 6-1. SogSupport With Copy Applications Dialog Box CDT 015.CDD Figure 6-1 shows the SogSupport window with the Copy Applications dialog box open: On the left-hand side is the source host database that you specified on the previous dialog box (Copy Applications From). On the right is the destination host database, which is determined by the current settings on the Configure SogGateway dialog box. The names of the database servers are listed above the two databases (\SVLDEV.$TSOG and \SVLDEV.$DW1 in the figure). You can expand the tree control on both sides of the window to look at the names of the run-time service objects file and the service objects in each application. 4. Select the application that you want to copy to the destination host database. Then click Copy. 5. The Select Run-Time Service Objects File dialog box is displayed. Specify a file name located on the destination (run-time) host system and click OK. SogSupport copies the necessary records from the run-time service objects file on the source (development) NonStop Himalaya system to this file location on the 6-15