|  | June 2000
| More Information About The Magic Database Gateway for CORBA using Orbix Version 8.30-3 |
| Dear Developer, We are happy to introduce The Magic Gateway for CORBA using Orbix. This gateway version is compatible with Magic Version 8.30 SP6 and for Magic Broker 8.30-7 and above. Note: This gateway supports the changes made in the Magic Corba gateway for Visigenic version 8.30-1. Please refer to the general readme file for Corba (readme_corba.htm) for further information. |
| 1. Changes in the Current Release 2. Magic Configuration for the Corba Orbix Gateway 3. Error Messages 4. Installing Orbix 5. Example 6. Orbix_Names Changes in the Current Release 8.30-3 1. Long application names: Because the length of the Application Name field within the Service Environemt table was resized to 128 chars in Corba GW 8.30-3, there is no need for the ORBIX_NAMES section in the mgreq.ini. Instead, similar to VisiGenic, the application name, when using the ORBIX server, will be in the following format : IR Module::IR IR Interface(NS_id.NS_kind/NS_id1.NS_kind1[...]) For example: TestCorbaMod::TestCorba(testServer.testServerKind) TestCorbaMod - IR module name TestCorba - IR interface name testServer - First level NS id testServerKind- First level NS kind The format of the NS id+NS kind pathname is also specified under the CORBA gateway specifications document. 2. The gateway is compiled with the 3.01 Orbix client version libraries. 3. Fix of memory loss problem when working with dynamic sequences/arrays. For users moving from Orbix GW 8.30-2 to 8.30-3 Naming Services Name, of the Orbix Server, will no longer be specified in the Mgreq.ini. It will now be specified in the Service Address, that is, in the Remote Application column of the Service table. The format for this entry for Orbix is as explained in point #1 above . Magic Configuration for the Corba Orbix Gateway Magic’s new Corba gateway for Orbix is provided as a DLL file whose name is Mgorcrb.dll. This DLL is used to call Orbix Corba Server objects from Magic. Details regarding the working are given below. The gateway must be specified in the mgreq.ini file. The following three sections must be present in the mgreq.ini for the proper functioning of the gateway. (Please refer the example given at the end of this document. ) [REQUESTER_ENV] Gateway = 4 [MAGIC_MESSAGING_GATEWAYS] MGSRVR04 = … … … This section will contain all the normal tokens specified at this place such as DLL name, log level, etc. In addition, there are the following tokens for the Corba Gateway: ORB = -OAlocalIPC 0; For the Orbix gateway, there is no need to specify the –OAagent parameter, which was being passed in the Visigenic gateway. The only thing that needs to be written is 'ORB='. NS = <path & file name of the file holding the IOR of the Naming Service server object>. This will specify the full path and file name of a file that holds the IOR of the root naming context of the Names Server (NS Server). If the Names Server name is not specified, the gateway will try to locate and use the Default Names Server. IR= <Name of the Interface Repository Server> This will specify the Name of Interface Rep server as registered with the Implementation Repository. The entry can also be in the form of a Naming Service name. This token is not compulsory. If no IR is specified, the gateway will try to search and bind to the default Interface Repository. IRHOST = <i.p / name of machine hosting the IR > This specifies the computer on which the Interface Rep is present. This token is also not mandatory. If not specified, the gateway will try to search and bind to an IR on the local machine. Note: This field is used only when the IR= specifies the IR Server Name as registered with the Implementation Repository. It is not used if the IR= specifies a Naming Service name. Some important points: The gateway uses only the Naming Service to locate Corba server objects. The gateway implements only the client side. It cannot be used to have Magic applications as CORBA servers. All the Object/Context names specified are case sensitive. Specifying the Remote Application in the Service Table of the Magic is the same as in the gateway for Visigenic. Specifying the parameters to be passed to the Corba gateway for Orbix remains the same as in the Corba gateway for Visigenic. There is a limitation in the current gateway for complex data types such as structures, etc. The Server object being called must have been compiled and built with its byte alignment set to 4 bytes. The following points (7 and 8 ) apply to Magic Orbix GW ver 8.30-3 only: The user may specify either a complete object name in Service Address section, or only the context name, while specifying the Object name in the Method Name colounm of the Call Remote . If the user specifies a complete object name in the Service Address section, and also another object name in the Method Name of the Call Remote, the name from Service Address will be used. The following points (9 and 13 ) apply to Magic Orbix GW ver8.30-1-8.30-2 only: The user may specify a complete object name in the Mgreq.ini, under a special section called [ORBIX_NAMES]. The user can provide only the Context name in the Mgreq.ini, and specify the object name in the Method Name column of the Call Remote (see the last section in this document [ORBIX_NAMES]). If the user specifies a complete object name in the Mgreq.ini's [ORBIX_NAMES] section, and also specifies another name in the method name of the Call Remote, the name from the Mgreq.ini will be used. If entries in the [ORBIX_NAMES] section of the mgreq.ini are modified/deleted, Magic must be restarted for the changes to take effect. If new entries are made, the changes will apply immediatly. When reading the [ORBIX_NAMES] section, if there are multiple entries of the same Remote Application, then the first entry to be read will be used. The [ORBIX_NAMES] section is read only on Magic Startup. If the remote Apps entry was not read during startup, then during its invocation the [ORBIX_NAMES] section will be read again. New entries will be added below the entries read earlier, irrespective of the location in the [ORBIX_NAMES] section. Error Messages: If the file specified as the NS server in the mgreq.ini does not exist or is not the correct one, and the gateway fails to locate a default NS server, then the Call Remote operation will fail with error message “Connection Failed – unknown host.” If the Orbix daemon is not up and running, then the Call Remote will fail with the error message “Program not found.” If the NS name specified for the Server object being called is not found the Call Remote operation will fail with error message “Application not supported by any application server.” Details of the errors can be seen in the log created for this gateway. Setting up Orbix Overview of Orbix An Orbix server program has a name, unique within its host machine. When a client invokes a method on an object, a server process containing the target object must be available. If the process is not running, the Orbix daemon at the server host attempts to launch the server process automatically. To allow an Orbix daemon to manage the server processes running in the system, Orbix provides an Implementation Repository. The Implementation Repository maintains a mapping from a server’s name to the filename of the executable code implementing that server. The server code must therefore be registered with the Implementation Repository. The Interface Repository Orbix maintains object specifications by storing an object’s IDL interface in a database called the Interface Repository. Some client applications use the Interface Repository to determine object interfaces and all information about those interfaces at runtime. A client accesses the Orbix Interface Repository by contacting an Interface Repository server. This is a standard Orbix server that provides a programming interface, defined in IDL, to the Interface Repository. To allow clients to obtain information about IDL definitions implemented in your system, you must add those definitions to the Interface Repository. Unlike Visigenic, where the user has to launch the Interface Repository every time, in Orbix that is not the case. The Interface Repository Server has to be registered with the Implementation Repository only once. If an operation wants to use the Interface Repository before it has been launched, the Implementation Repository automatically launches the Interface Rep Server. Therefore once the user has registered the Interface Rep, there is no need to bother about it again. The user can of course delete or modify it as desired. Installation Install Orbix as per the instructions in the Orbix Users manual Further explanations in this document assume that Orbix has been installed in the c:\iona directory. After successful installation of the product, we need to register the Naming Service Server and the Interface Repository Server with the Implementation Repository and also register other server objects that we intend to call. Make sure that the Orbix Daemon is started. On Windows/NT the daemon can be added to the service list. To do so run the command orbixd –j . To uninstall the daemon as a service in Windows/NT, run the command orbixd –w There are 3 basic steps in setting up a server in Orbix Register a Server Specify the user rights for the server Add the IDL information of the Server into the Interface Repository Check that Orbix installation succeeded 1. Registering a Server The putit utility registers servers with the Orbix Implementation Repository. You can use the putit command in its simplest form as follows: putit <server_name> <command_line> If the <command_line> specified contains blanks, then the command line must be enclosed in double quotes. 1.1 Registering the Names Server The NS.exe, in the bin directory, is the standard Names Server supplied by Orbix. Register this NS Server with the Implementation Rep by using the following command. * Before activating the following command you must create the Server Name sub directory . In this example :"c:\iona\ior" . For Orbix 3.01 putit NS “c:\iona\bin\NS.bat –I c:\iona\ior\NS.IOR” For Orbix 3.0c putit NS “c:\iona\bin\NS.exe –I c:\iona\ior\NS.IOR” * Pay attention -I (like Iona) (For Orbix 3.01 Iona Technologies has replaced the ns.exe with ns.bat). This will register the NS server with the Implementation Rep with Server Name as NS. The IOR of the server will be stored in a file called NS.IOR in the c:\iona\ior directory. This path and file name will be specified in the NS= token for the gateway in the mgreq.ini. Note that the IOR directory should be created before running the command; it is not created automatically when running the command. (Note: The IOR sub-directory is a user-created directory; it is not created by the Orbix installation program.) 1.2 Registering the Interface Repository The IFR.exe, in the bin directory, is the standard Interface Repository Server supplied by Orbix. Register the Server with the Orb by using the following command. putit IFR c:\iona\bin\IFR.exe This registers the Interface Rep server with the Implementation Rep with the name IFR. This name (IFR) will be used in the IR= token in the mgreq.ini. 1.3 Registering other servers Other server objects are registered in the same way as mentioned above. For example, to register the testServer object run the command : putit IonaServer c:\magic\test\server.exe note : If the server object had registered a Name in the impl_is_ready(...) method of the BOA, then the same Name must be specified in the putit command. "IonaServer" in this example 2. Specifying the user rights for a Server After registering a server object, we must specify the user rights for that server object. To specify the user rights for the NS server. Start Orbix Server manager, From the Host menu select Connect and specify the computer on which the Implementation rep is running. After the Server Manager has connected to the Implementation Rep, select the NS, and go to the Rights tab. Add the user names to the Launch/Invocation rights. Specifying all as the User Name will allow Launch/Invocation rights to everybody. 3. Adding the IDL info to the IR For every server object that we register with the Implementation Rep, and wish to call from Magic, we also have to put the IDL definitions into the Interface Repository The Orbix utility putidl allows you to enter all the definitions in an IDL source file into the Interface Repository. This utility provides a simple and safe way to add IDL definitions to the repository. For example, the following command adds the definitions in the file banksimple.idl to the IR: putidl banksimple.idl 4. Check that Orbix installation succeeded This section contains a check list to verify that ORBIX is properly installed and that the server that you wish to contact is properly registered with the ORB. Note: The values shown in the screen shots used in this document may be different than the corresponding values for your installation. Please ensure that the values you check are correct as per your installation. For more details regarding the proper ranges and defaults please refer to the ORBIX documentation. To check the Installation, first start the Orbix Daemon (from Services Table or by Start/Programs/Orbix/Orbix Deamon). Check your installation by verifying the details in the Orbix Configuration Explorer, Orbix Server Manager, Orbix Names Browser and Orbix IFR Browser Orbix Configuration Explorer Run the Orbix Configuration explorer(Start/Programs/Orbix/Configuration Explorer) Check that for all three configurations, viz. - Common, OrbixNames and Orbix, all variables are assigned proper values as per your installation. Orbix Server Manager Start the ORBIX Server Manager Connect to the host machine on which the Implementation repository resides Check that all the Servers registered using the “PUTIT” utility are listed. Select the server object General tab - verify that the Server Name and Owner are correct Activation tab - make sure that all entries are correct as per your setup Rights tab - verify that the assigned rights are proper Orbix Names Browser Start the ORBIX Names Browser Connect to the host machine on which the Names Server you will be using resides Check that the NS name of the Server you wish to contact is listed in the Names Browser. Select the NS name entry of the server you wish to contact Verify that the details for this entry are correct Orbix IFR Browser Start the ORBIX IFR Browser Connect to the machine hosting the IFR server. Check that the IDL of the server you wish to contact is registered with the IFR browser. Select the IDL entry of the server you wish to contact Verify that all the contents of the IDL, viz. Modules, Interfaces etc, are listed properly For further details regarding Orbix refer the Orbix Administrator’s Guide. For further details about the Naming Service please refer the OrbixNames Programmer’s guide. 5. Example: Following is an example of calling a method on an Orbix Corba server using the new gateway (ORBIX GW release 8.30-3): If the details of the server object to be called are as follows:
Module Name | = AccModule
Interface Name | = AccIntFace
Method Name | = balance (assume method takes no parameters and returns nothing)
NS Name of interface’s object | = AccName
NS Context for the object | = AccContext
The IOR file of the Names Server | = C:\iona\ior\NS.ior
There are two methods in which the user can specify which Orbix server to call: Method 1 In Magic: In the Services table in Magic add the following line: For Orbix GW ver 8.30-3
# | Name | Server | Remote Application
1 | MyOrbixServer | Default Corba Server | AccModule ::AccIntFace (AccIntFace/AccName)
For Orbix GW ver 8.30-2-8.30-1
# | Name | Server | Remote Application
1 | MyOrbixServer | Default Corba Server | AccModule ::AccIntFace
In the Flow table specify the Call Remote as is done for the Visigenic Gateway. i.e. Call >> Remote Service = MyOrbixServer Program Name = balance In Mgreq.i ni : Make the following minimum entries needed for the gateway: [REQUESTER_ENV] Gateway = 4 [MAGIC_MESSAGING_GATEWAYS] MGSRVR04= Mgorcrb.dll, , , , ORB =-OAlocalIPC 0; NS=c:\iona\ior\ns.ior For Orbix GW 8.30-1-8.30-2 add the following lines as well [ORBIX_NAMES] AccModule::AccIntFace=AccContext/AccName Method 2 In Magic: In the Services table in Magic add the following line: For Orbix GW ver 8.30-3
# | Name | Server | Remote Application
1 | MyOrbixServer | Default Corba Server | AccModule ::AccIntFace (AccContext)
For Orbix GW ver 8.30-1-8.30-2
# | Name | Server | Remote Application
1 | MyOrbixServer | Default Corba Server | AccModule ::AccIntFace
In the Flow table specify the Call Remote as is done for the Visigenic Gateway. i.e. Call >> Remote Service = MyOrbixServer Program Name = AccName.balance In Mgreq.ini : Make the following minimum entries needed for the gateway: [REQUESTER_ENV] Gateway = 4 [MAGIC_MESSAGING_GATEWAYS] MGSRVR04= Mgorcrb.dll, , , , ORB =-OAlocalIPC 0; NS=c:\iona\ior\ns.ior For Orbix GW 8.30-1-8.30-2 add the following lines as well [ORBIX_NAMES] AccModule::AccIntFace=AccContext The User can specify only the Context name in the Remote Application column of the Services table.. In this case while specifying the Remote Call >>Program Name, the user will have to specify the methods as <Object Name>.<method name>, as shown in the second case in the above example. The gateway will contact the Names Server as specified by the IOR (C:\iona\ior\ns.ior). From this Names Server it will try to resolve the name AccContext/AccName. Since IR= and IRHOST= are not specified the gateway will try to connect to the default Interface Repository on the local machine. If the Server object is found, the method balance will be executed, and the results (if any) will be retrieved. 6. [ORBIX_NAMES] This section applies only to Corba GW version 8.30-1. It will contain the Interface Name/Name Service name pairs of the remote applications specified in the Service table of Magic. The entries will be in the following form: < Remote App Name> = <Naming Service Name of the Object> While specifying the NS name of a server, every individual context and name in the path should be separated by a forward slash ( / ). When specifying the Id and the kind in a name, the id and the kind should be separated by a dot ( . ) For example: ModuleName::InterfaceName = CtxID1.CtxKind1/CtxID2/ServerObjID.ServerObjKind Note : This method of specifying the Interface Name/NS name pairs was changed in the current version GW 8.30-3 . These entries will be specified directly in the Services table, along with the remote application name. There will be no [ORBIX_NAMES] section in the Mgreq.ini for the GW 8.30-3 . This method was used in the GW prior to 8.30-3 because Remote App Name in Services Table was limited to 30 characters . |
| Thank you, The Magic Version 8 Team |