orb2 for C/C++ Administrator Guide (z/os)

Transcription

1 orb2 for C/C++ Administrator Guide (z/os)

2

3 orb2 for C/C++ Administrator Guide (z/os) Subject Platform-specific instructions for installing, configuring and administering orb2. Software Supported orb2 for C/C++ Revision History Initial Document August 2005

4 2AB, Inc. disclaims the implied warranties of merchantability and fitness for a particular purpose and makes no express warranties except as may be stated in its written agreement with and for its customer. In no event is 2AB, Inc. liable to anyone for any indirect, special or consequential damages. The information and specifications in this document are subject to change without notice. Consult your 2AB, Inc. marketing representative for product or service availability. U.S. Government Restricted Rights. The Software Program(s) and Documentation furnished under this Agreement were developed at private expense and are provided with Restricted Rights. Any use, duplication, or disclosure by and for any agency of the U.S. Government shall be subject to the Restricted Rights applicable to commercial computer software under FAR Clause or DFAR Clause or any successor thereof. Copyright by 2AB, Inc. All Rights Reserved. Trademarks The 2AB logo is a registered trademark of 2AB, Inc. 2AB, explorer, ilock, ilock Security Services, jlock, orb2, orblock, weblock and Xcon are trademarks of 2AB, Inc. Microsoft, Windows, Windows NT, Windows 2000 and Windows XP are registered trademarks of the Microsoft Corporation. OMG, Object Management Group, OMG Interface Definition Language (IDL), Unified Modeling Language and UML are trademarks of the Object Management Group. CORBA and IIOP are registered trademarks of the Object Management Group. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. HP-UX is a registered trademarks of the Hewlett-Packard Company. Apache and Tomcat are trademarks of The Apache Software Foundation. AIX and Domino are trademarks of the International Business Machines Corporation in the United States or other countries or both. iplanet, J2EE, J2SE, Java, JavaScript, JavaServer Pages, JKD, Solaris, Sun and Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other brand or product names are trademarks or registered trademarks of their respective companies or organizations.

5

6

7 Contents Contents Tables About This Document Chapter 1 Technical Support i-v z/os 1.1 Installing orb2 for C/C++ on z/os orb2 for C/C++ Components The orb2 Environment orb2 License Trader Starting the Trader Stopping the Trader Trader Operation Building an orb2 Program Design and Write the Interface in IDL Generate Sources with stubgen Write the Server Implementation Compile and Link the Server Implementation Running the Demo Programs Administrator Guide orb2 for C/C++ i

8 Contents ii orb2 for C/C++ Administrator Guide

9 Tables Table 1.1 orb2 Components and Locations on z/os Administrator Guide orb2 for C/C++ iii

10 Tables iv orb2 for C/C++ Administrator Guide

11 About This Document This document describes the installation, administration and operation of orb2 for C/C++ Release 3.7. It should be read in conjunction with the existing orb2 for C/C++ documentation, which assumes you are running on Unix or Windows. This guide specifically addresses operation on z/os (native). All other concepts remain the same and are documented in the other orb2 for C/C++ documents. Technical Support Your feedback is important to us. Please provide input to the 2AB Technical Support Staff. You can communicate comments to and request help from the Technical Support Staff via the following methods: Telephone U.S. or Canada: (Toll Free) All Other Countries: Administrator Guide orb2 for C/C++ v

12 About This Document Technical Support vi orb2 for C/C++ Administrator Guide

13 Chapter 1 z/os This chapter explains how to install orb2 on z/os (native), where to locate orb2 components and how to build a C/C++ program utilizing orb2 technology. 1.1 Installing orb2 for C/C++ on z/os Your installation media (usually a CD) will contain three files: orb2ccppadminguide.pdf (this file) INSTALL.ZOS - a binary file containing the orb2 product in an archive form INSTALL.JCL - an ASCII file containing the JCL that will extract and install the product Installation of the orb2 product involves the following steps: 1. On z/os, you must pre-allocate the dataset ORB2C.INSTALL with the following attributes: 8,500 BLOCKS, RECFM=FB, LRECL=80, BLKSIZE=0. 2. On the machine that you have the CD-ROM mounted on, FTP the files to the z/os machine. The INSTALL.ZOS file on the CD is binary and must be copied to ORB2C.INSTALL. The INSTALL.JCL file in the CD is text and can be copied to any convenient location. 3. Once the package has been completely received, submit the JCL in dataset INSTALL.JCL (or from wherever you saved it). This will extract the orb2c.package dataset and create a series of datasets with the ORB2.* high-level qualifier. 1.2 orb2 for C/C++ Components By default, orb2 for C/C++ is installed under the high-level qualifier of ORB2. The components of orb2 are located as shown in the following table: Table 1.1 orb2 Components and Locations on z/os Component Location JCL Procedures Configuration Data Log files C Demonstration programs C++ Demonstration programs ORB2.JCL ORB2.PROCLIB ORB2.CONFIG ORB2.TRLOGx ORB2.DEMOS.C ORB2.DEMOS.CPP Administrator Guide orb2 for C/C++ 1-1

14 z/os 1.3 The orb2 Environment 1.3 The orb2 Environment All orb2 clients and services will obtain configuration information from a properties file accessible from DD:ORB2CFG, which by default points to "ORB2.CONFIG(PROPS)". As delivered, this PDS member is empty. This means that the orb2 program will start with certain defaults. The orb2 program: searches for Trader on the current host (not localhost!) searches for Trader on port To specify a different properties file, simply change where the ORB2CFG DD points to. It can point to a member in a PDS or a sequential file. Please see the orb2 for C/C++ User Guide for details about the properties that may be specified in this file. 1.4 orb2 License All orb2 programs (clients, servers and utilities) require a license file to operate. The license file is accessed via DD:ORB2LIC and by default, points to ORB2.CONFIG(LICENSE). Take care to never change this file as any change will render the license file invalid. 1.5 Trader Starting the Trader The Trader can be started by submitting the job in "ORB2.JCL(TRSTART)". The trader will run as long as the job continues to run Stopping the Trader Stop the trader by submitting the job in "ORB2.JCL(TRSTOP)". This will cause the trader to close down cleanly, and most importantly, will cause the trader to write a clean checkpoint to its logfile. Note You must close down the trader cleanly in this way to get a clean checkpoint. In particular, do not cancel the trader job in SDSF! Failure to observe this condition will likely result in corrupted logfiles Trader Operation The trader s behavior differs slightly from its unix counterpart: Periodic checkpoints are not implemented, even if requested in the properties file. When the trader starts, it takes the file pointed to by DD ORB2LOGO to initialize its internal database. As types, contexts and offers are registered and removed from the trader, they are recorded in a workfile pointed to by DD ORB2LOGW. When the trader is closed down with the TRSTOP job as shown above, the trader will write a clean checkpoint 1 to the file pointed to by DD ORB2LOGN. 1. A "clean checkpoint" is one in which only the active types, contexts and offers are written to the logfile. By contrast, the workfile at DD ORB2LOGW contains all operations, including add and delete operations on the same offer. As a result, the workfile is typically much larger than a logfile from a "clean checkpoint". 1-2 orb2 for C/C++ Administrator Guide

15 1.6 Building an orb2 Program z/os As delivered, DD ORB2LOGO points to the (0) version of a GDG, and DD ORB2LOGN points to the (+1) version of the GDG. This makes the logfile written by the last successful shutdown available to the trader at next startup. DD ORB2LOGW also points to a (+1) GDG to provide a history of trader operations in case the trader is not shut down in an orderly manner. This file may be passed to the trader on startup for recovery purposes but will have to be examined to ensure all lines are complete before doing so. 1.6 Building an orb2 Program This section describes how to build and run orb2 programs. The text refers to the supplied demonstration programs, but you will use these techniques to build your own applications. For terms that are unfamiliar to you, please refer to the orb2 for C/C++ User Guide for more details. As described in the orb2 for C/C++ User s Guide, there are several tasks involved in building an orb2 program: Design and write your interface in IDL (Interface Definition Language). Generate C or C++ sources from the IDL using stubgen. This must be accomplished on a unix or Windows machine as stubgen is not implemented on z/os. Using FTP or another equivalent process, transfer the generated sources into your source PDS on z/os. Write the implementation of your server using the generated skeletons as a guide. If required, write the implementation of your client. Compile your implementation, linking with the orb2 libraries as required, to produce your server and client executables. This section will primarily address the tasks of compiling and linking your application code with orb2 libraries to obtain your executables. As you will be generating C or C++ code from IDL on a Windows or Unix machine, the orb2 for C/C++ User Guide covers this topic in detail. Similarly, writing your implementation code is also covered in the orb2 for C Reference, or the orb2 for C++ Reference Design and Write the Interface in IDL As mentioned in the previous section, other orb2 documents will cover this topic in greater detail than this document. There is, however, an important limitation that you should be aware of. The ultimate destination of the source files generated by stubgen will be a PDS on z/os. Member names cannot be longer than eight characters. This means that the name of your IDL files cannot be longer than six characters (not including the.idl suffix). This is because stubgen will generate source files with the name m_name.c, t_name.h, etc. The final length of the generated filenames cannot exceed eight characters. The module and interface names within the IDL may remain the same, but you must rename your IDL files to be unique in the first six characters. Failure to adhere to this limitation will result in generated filenames that may not be unique, and files will be overwritten when they are transferred to the PDS on z/os. Administrator Guide orb2 for C/C++ 1-3

16 z/os Generate Sources with stubgen Generate Sources with stubgen As described earlier, this must be done on a unix or windows machine. See the orb2 for C/C++ User Guide for more details Write the Server Implementation The stubgen program will have created a server skeleton in namesrv.c which you can use as a basis for your own development efforts. We recommend that you rename this file before editing it to avoid the possibility of overwriting your changes in another run of stubgen. See the orb2 for C/C++ User Guide for more details Compile and Link the Server Implementation Creating a good load module will involve running a job that will execute as many compile steps as required, then a link step to link each of the compiled objects along with the orb2 library. JCL and PROCs have been provided to help you perform this task. There is a PROC for the compile and a PROC for the LINK step. The compile PROC will write the resulting object to an object PDS. The prelink step resolves any external references that exist in your application, generated code and the orb2 library. The link step performs the final step of creating the load module from the component objects. 1.7 Running the Demo Programs Two C and two C++ demonstration programs have been provided to help you verify that your installation is good and to provide you with a model on which you can base your own development efforts. This section will explain how to run the C Trading demo. Running each of the other demos is an almost identical procedure: 1. Start the trader if it is not already running: Run job ORB2.JCL(TRSTART). 2. If the Calculator Type does not exist, add it: Modify the ARGS= parameter and then run job ORB2.JCL(TYPECLG). 3. Compile the Calculator Demo (we have already generated the C sources from IDL for you): Run job ORB2.DEMOS.C.JCL(TRADCL) Run the Calculator Server: Run job ORB2.DEMOS.C.JCL(RUNSRV). 5. Run the Calculator Client as many times as you wish: Run job ORB2.DEMOS.C.JCL(RUNCLI). By default the client requests an "add" operation. See the orb2 for C/C++ User Guide for more information. 6. To stop the Calculator server, change the argument to -kill and run job ORB2.DEMOS.C.JCL(RUNCLI). See both the client and server jobs end. 7. To stop the Trader, run job ORB2.JCL(TRSTOP). 1. Note that you can perform individual compiles with the TRADC job, and individual link-edits with the TRADL job. 1-4 orb2 for C/C++ Administrator Guide