Installation Issues

- Pre-requisite versions of OS, DCE, DBMS required for Entera.

• Please read latest Entera 4 version release notes thoroughly and understand the product support matrix in addition to required level of DCE.

• Before installing Entera ensure all dependant hardware/requirements have been installed and are operational. A review of the version levels of current hardware, O/S and other software including DBMS will need to be undertaken as Entera 4 may not support earlier platform and O/S versions. Where OS or data base upgrades are required the impact of such upgrades will need to be assessed in relation to other software that may be in use.

• Ensure you are installing the latest version of Entera 4 and determine if any subsequent patches are available. On release of this document, Entera 4.2.1 was available.

- Organization of Entera 4 installation compared to Entera TCP Development.

• Entera 3.2 was divided into Entera 3.2 DCE and Entera 3.2 TCP. When the product was installed, $ODEDIR to needed to include either ‘dce’ or ‘tcp’ as the last directory. For example, ODEDIR=/opt/entera/tcp. When Entera 4 is installed, no such division is required. $ODEDIR is the base directory where Entera 4 is installed.

- Selection of naming service during Entera 4 installation.

• The Entera 4 install program will prompt you for the naming service. Choose “Entera Lightweight” if you intend to use the Entera 4 Broker for your application(s), as distinct from the DCE Cell Directory Server (CDS).

- Obtain latest software upgrades/patches.

• Please refer to Entera Technical Support or Entera Development Support web page found at http://www.inprise.com/devsupport/entera

Follow link to Entera Patches for latest product download.

• Patches are shipped with an installer similar to the installer for the base product and should be installed on top of original Entera installation; the same ODEDIR value should be used.

Development Issues

- Prior to Entera TCP application migration:

• Ensure latest Entera 4 compliant software is present including versions of operating system, DCE, and any required patches, DBMS and Java.

• Ensure a solid understanding of how Entera 4 application components interact in an Entera 4 Broker environment (Read separate document Entera_4_Broker.doc)

- Deprecated Entera TCP features.

• OEC3270 mainframe connectivity package.

• Perl language support; no perl stub code can be generated in Entera 4.

• Entera TCP security featuring utilities oecsec, oecacl and oecpw.

• Third party product RPCPainter, a tool for integration of Entera TCP into PowerBuilder, is not available for Entera 4.

• Custom built data access servers such as any_start or eda_start.

- Customization of Entera TCP stub code.

• Both Entera TCP and Entera 4 have the concept of stub code generation. Once generated, the code is then built into the applications executables. Although it is recommended that all stub code be kept separate from actual application logic, this is not always the case in practice. Stub code generated in Entera 4 is completely different from Entera TCP code, different structure, API calls, etc. Any updates or application integration of Entera TCP stub code needs to be recognized and appropriate action taken when replaced by Entera 4 stubs. Some Entera customers may have developed custom wrappers and implemented other homemade middleware utilities and services. Simple migration of such customizations may not be possible and will require further study so that an appropriate strategy can be determined in moving forward with Entera 4. Qualified Inprise consultants working alongside consultants or engineers from within the customer’s organization should ideally undertake this type of migration project.

- Makefile updates

• Ensure the Entera utility `getplatform` is used on your development platform to resolve compilers, compile and link options, include file locations, shared library locations and shared library dependencies.

• Entera 4 depends on shared libraries as opposed to static libraries. DBMS software such as Oracle, DB2 and Sybase is accessed in Entera through open client API calls (DBMS libraries are no longer statically bound into Entera servers). Again, use `getplatform` to resolve required libraries and their locations.

• Entera 4 applications depend on DCE include files. It needs to locate them under /usr/include/dce where they should be installed as part of DCE Core services or DCE Application tools.

• References to Entera TCP development tool names updated with Entera 4 equivalents. Parameters supplied to these tools need to be examined and modified as necessary. Refer to the next section for details about how Entera TCP tools are mapped to Entera 4.

- Utility updates.

• obigen replaces rpcmake. Values for language specification differ. For example use ‘C1.0’ instead of for C language.

• dobigen replaces sqlmake. Values for language specification differ. For example use ‘C1.0’ instead of ‘c’ for C language.

• tobigen replaces tpmake.

• obitest replaces rpctest/rpcdebug.

• Java GUI tools migwiz/entgen/obitestj. These utilities depend on an installation of Java.

- Enhanced language support

• Support added for generation of Java stub code.

- DCE Threads in Entera 4 applications.

• OSF DCE is a multi-threaded environment. It uses threads, streams of execution within a process, in order to execute multiple concurrent tasks within the same application. This feature is automatic within the DCE runtime libraries. Determining whether a server can be multi-threaded or not can be controlled at the application level using a DAP attribute called MaxCalls. Its value indicates the maximum number of concurrent threads of execution allowed in the server process. Configuring multi-threaded servers can be used to great advantage in writing distributed applications. However, many existing languages, libraries and application services were not originally designed to function properly in a multi-threaded environment. Global data must be protected from simultaneous access. This can be achieved through mutex locks where synchronized access to variables shared across threads can be achieved. Libraries accessed by applications must also be ‘thread-safe’, a term given to software that has the ability to function successfully in a multi-threaded environment where protection of shared data is a key feature.

• One of the most important directives of operating in a multi-threaded environment is that no service should ever be called that blocks the entire process. Unfortunately, many existing system calls have this characteristic. To circumvent this limitation, DCE includes ‘jackets’ or ‘wrappers’ for many commonly used functions that allow them to be called in a way that doesn’t conflict with the use of threads. To ensure the ‘jacket’ functions are invoked applications should include the header file pthread.h even if MaxCalls=1, indicating an explicit single-threaded server, is set. In addition, it may be necessary to replace some system calls with an equivalent pthread function call. For instance, any call to usleep() should be replaced with a call to pthread_delay_np().

• By default, client applications are single-threaded; they can only execute one RPC at a time. However, concurrent RPCs can be invoked using an asynchronous option available in Entera 4. A new thread can be automatically created to issue each RPC, instead of using the main thread. The client program can poll to find out when an RPC is completed and, for clients written in C, designate a function to be executed immediately upon an RPC’s return. This option allows the main thread to perform other tasks on behalf of the users. If the development language supports it, clients may be enhanced to be multi-threaded since they will have access to DCE’s threads API. The asynchronous option is available through specification of the ‘[async]’ attribute in an interface ACF file (refer to Entera 4 documentation on ACF files).

- Application code update requirements and Entera TCP compatibility library.

• Many Entera TCP applications have embedded Entera TCP API calls. Entera 4 provides a compatibility library containing ‘wrappers’ for these functions, preventing extensive code updates when migrating. On Unix platforms, the library is called libcmptu40.<ext> while on Microsoft Windows it is installed as compat.dll. However, not all TCP API calls are included in the compatibility library. For example, dce_setenv() needs to be replaced with ode_cln_open_session().

• On some platforms, the TCP API function dce_dbgwrite() sometimes fails to correctly log messages when it has many variable parameters. It may even cause the application to fail. The recommended is for it to be replaced with Entera 4 API function ode_log_write() using a format similar to the following:

ode_log_write(log_level, __FILE__, NULL, __LINE__, “%s\n”, var1, var2 );

In Entera TCP values for log_level include DCE_LOG_ERROR, DCE_LOG_DEBUG and DCE_LOG_WARNING. These Entera TCP defined values can be retained in and are mapped to appropriate values for Entera 4. They are resolved through header file $ODEDIR/include/dceinc.h which should already be included by Entera TCP applications.

• How do Entera TCP error codes map to Entera 4 error codes?

There are two sets of error codes in Entera 4, those returned from the Entera runtime and those returned from the DCE RPC runtime. Refer to the contents of $(ODEDIR)/include/dceerr.h showing how codes that are mapped to Entera TCP error definitions. This header file is included in $ODEDIR/include/dceinc.h, so replacement of TCP error definitions is not necessary. Although Entera TCP API functions dce_errnum() and dce_error() will now return Entera 4 codes they can still be compared to the Entera TCP defined variables such as DCE_NOERROR, DCE_NOSOCKCONN, DCE_BADHOST, etc. The API function dce_errstr() will return an appropriate Entera 4 or DCE RPC message string. DCE RPC error code values will vary depending platform origin. Review the header file $(ODEDIR)/dceinc/dce/rpcsts.h for all UNIX DCE RPC and Microsoft RPC error values. Entera runtime errors may be examined in header file $(ODEDIR)/include/odests.h. The utility $(ODEDIR)/bin/dceerror can be used to return a textual representation for any Entera 4 error value. Note the source of the utility may be found at the end of Chapter 17 Troubleshooting in Entera 4 Developers guide.

- IDL and ACF files replace Definition files.

• Entera 4 uses DCE IDL and ACF files for generation of interface stub code rather than TCP definition files. Refer to Chapter 2 File Specifications in Entera 4 Reference guide for more details on IDL and ACF files. Definition files can be migrated to IDL and ACF files using Entera 4 utility def2idl or migwiz. The rule of thumb when using IDL and ACF files for stub code generation is that both files should always reside in the same directory location. The ACF file contains important Entera specific additions to DCE standards and impacts the contents of generated stub code. If the ACF file is absent, your application may compile and link successfully but fail at runtime.

• 31 character limit for RPC functions – exitsing functions > 31 chars need to be modified in the definition file prior to def2idl, in client and server application code.

• 17 character limit for Interface names – exiting interface names > 17 chars need to be modified prior to def2idl.

• IDL files must always be paired with corresponding IDL files. Whenever an IDL file is specified as an input to utilities such as obigen or obitest, the associated ACF file is expected to reside in the same directory location as that of the IDL file.

- Variable-named Servers in Entera 4.

• Unlike conventional RPCs, a RPC invoked to select a particular server instance of an interface through specification of a server-name takes advantage of an Entera feature called variable-named servers. Invocation of the RPC from a client has the format:

RESULT = SERVERA_RPC(“serverA”, param_1, param_2, …, param_n)

This format can still used in Entera 4. However, when client and server stub code is generated for variable-named servers, the ACF file must have the ‘variable’ attribute specified. Refer to P 5-11, 5-12 of Entera 4 Reference Guide for a discussion on variable-named servers and Chapter 2 File Specifications of Entera 4 Reference Guide for details about ACF files. When a variable-named server is started, it identifies itself in its DAP file through attribute Servicename. Data access servers can use command line option ‘–s’ to specify the name of the server. If you use universal client utility obitest to run a RPC against a variable-named server, specify the server name on command line option ‘-x’.

- Requirements for migration of Visual Basic and PowerBuilder clients.

• In Entera TCP, clients depended on an Entera library named odetnn.dll, where ‘nn’ represented the Entera version. Microsoft Windows clients now depend on two main Entera libraries, oden40.dll containing Entera 4 API functions and compat.dll with compatibility wrappers for obsolete Entera TCP API functions. Of course, both these libraries depend on other Entera 4 libraries contained in %ODEDIR%/bin and underlying MS-RPC libraries.

• Visual Basic:
• Entera external function declarations, loaded into Visual Basic clients when developed with Entera TCP from a file of the format odetnn.bas, must be replaced with Entera 4 external function declarations described in oded40.bas and odecd40.bas (if Entera TCP API function calls exist). These files are located in an appropriate subdirectory under %ODEDIR%. For instance, files relevant to Visual Basic version 5.0 can be found in %ODEDIR%/VB50.
• Entera TCP file odeconst.bas containing Entera global variable declarations should be replaced with Entera 4 equivalent file, odests40.bas, located in the same directory as odecd40.bas and oded40.bas. However, if your VB application refers to constants defined in odeconst.bas, either these references should be replaced with equivalent Entera 4 constants. Alternatively, the original constants are retained as global variable declarations but they must have values consistent with Entera 4. Refer to header file dceerr.h located under %ODEDIR%/include for mapping of Entera TCP constants to equivalent Entera 4 constant values.
• Entera TCP Visual Basic stub code must be replaced with Entera 4 stub code.

• PowerBuilder:
• Entera external function declarations, loaded into PowerBuilder clients when developed with Entera TCP from a file of the format odepbnn.txt, must be replaced with Entera 4 external function declarations described in odeext40.txt and odecd40.txt (if Entera TCP API function calls exist). These files are located in an appropriate subdirectory under %ODEDIR%. For instance, files relevant to PowerBuilder version 5.0 can be found in %ODEDIR%/PB50.

• Entera TCP file odeconst.txt containing Entera global variable declarations should be replaced with Entera 4 equivalent file, odests40.txt, located in the same directory as odeext40.txt and odecd40.txt.
• Replace PowerBuilder library that implements all PowerScript functions necessary to perform Entera TCP RPCs with libraries necessary to perform Entera 4 RPCs. In Entera TCP the library name would have a format of odetnn.pbl where ‘nn’ identifies the version of Entera TCP. The file %ODEDIR%/PBxx/odet40.pbl is the library with necessary functions for the Entera 4 DCE API while compat.pbl is required if your PB application contains calls to the Entera TCP API.
• Entera TCP PowerBuilder stub code must be replaced with Entera 4 stub code.
• More information about typical issues encountered when migrating PowerBuilder clients from Entera TCP to Entera DCE can be found in Entera 3 Client Developers Guide P. 92.

- HP problem with $ODEDIR/include/nbase.h

• When compiling migrated Entera applications on HP-UX, a problem frequently encountered involves a data variable declaration in a standard DCE header file shipped with Entera 4, $ODEDIR/dceinc/dce/nbase.h. A compiler error is reported for line 148 containing:

idl_byte tower_octet_string[];

It should be replaced with

idl_byte tower_octet_string[1];

 

Runtime Issues

- Distributed Application Profile (DAP) files.

• Entera 4 servers, clients and the Broker need to have a DAP file specified upon startup rather than an Entera TCP environment file. A DAP file can be specified for servers and the Broker using either command line option ‘–f’ or ‘–e’.

• Some environment file properties have no equivalent DAP attributes in Entera 4. Map environment file properties to DAP attributes where possible. Refer to Chapter 2 File Specifications for details of DAP attributes. Refer to additional documents, Entera_4_Broker.doc and Server_DAP_attributes.doc for DAP file examples needed for the Broker and a server, respectively.

- Entera 4 Broker versus Entera TCP rpcbroker.

• Refer to Entera_4_Broker.doc for a detailed explanation of Broker operation.

- Restriction of Port Ranges used by Entera 4 servers.

• In a secure production environment whereby clients need to communicate with servers through a firewall, it is necessary to predefine a set of port numbers that will be used by servers and which correspond with the port ranges allowed access through the firewall.

This can be accomplished on the server platform by setting a DCE environment variable such as RPC_RESTRICTED_PORTS in HP/DCE. Refer to your DCE product vendor for more information. Individual servers can themselves specify a port number either explicitly using the Protseq DAP attribute or from a range of ports using TCPPortRanges and UDPPortRanges DAP attributes. Please note, however, in using these DAP attributes, full server bindings are stored in the Broker and may require extra maintenance.

- Multiple network interfaces on an Entera server platform.

• Q. How do I keep my server from registering all network addresses of a host machine in the Endpoint-Mapper?

A. If a server machine has two or more network interfaces, it will have at least that many network addresses. A typical server program will export binding handles to DCE CDS or Entera Broker for every protocol sequence on every network interface. If some of these interfaces are unreachable from some clients, binding may be delayed while the client cycles through the useless handles. To limit a particular server, set the environment variables RPC_UNSUPPORTED_NETIFS and/or RPC_UNSUPPORTED_NETADDRS to exclude the interface or specific addresses that you don't want your server to use. On HP-UX, set RPC_SUPPORTED_NETADDRS instead, to give a list of addresses you do want to use. Look in your vendor's documentation for syntax and to verify that they support this feature; Open Group does not standardize it. You must set the environment before starting the server, of course, and you may have to manually remove CDS/Broker entries that are already present.

- Security in Entera 4 versus Entera TCP Security.

• Entera TCP security is no longer supported. Entera 4 options include support for DCE Security and Generic Security Service (GSS) API.

- Shared library dependencies in Entera 4.

• Ensure appropriate environment variable from list below is set to find Entera 4 shared library dependencies such as:

UNIX Microsoft Windows (NT)

$ODEDIR/bin/libodedu40.<ext> %ODEDIR%\bin\oden40.dll

$ODEDIR/lib/libmsgcat.<ext> %ODEDIR%\bin\odemsg.dll

/usr/include/libdce.<ext> C:\winnt\system32\rpcrt4.dll

$DB2_HOME/lib/libdb2.<ext>

HP-UX => $SHLIB_PATH where <ext> is ‘sl’

AIX => $LIBPATH where <ext> is ‘a’

Solaris => $LD_LIBRARY_PATH where <ext> is ‘so’

MS Windows => %PATH% (although applications, like Visual Basic, can impact it.)

- Format of DBMS values returned in Entera 4 differ from previous Entera versions.

• Entera 4 returns Sybase database datetime fields differently from Entera 3.2. In Entera 3.2 datetime is "Oct 27 1998 12:00:00:000AM" compared to Entera 4 datetime of "Oct 27 1998 12:00AM". Entera 3.2 and Entera 4 use different Sybase client libraries. The format difference is caused by the difference in the Sybase libraries. You can change the way datetimes are formatted by using SQL's 'convert' function.

• Entera 4 DB2 access through db2_start or Fx servers return datetime data in a format not compatible with Entera TCP. The DB2 Call Level Interface, used by Entera to communicate with DB2, had a bug causing this problem. Refer to IBM technical support for more details.

- Log Files.

• Message logged in Entera 4 logfiles have a different format compared to Entera TCP. Volume of messages written is reduced, even for maximum logging level. In Entera TCP, messages could be logged from deep within the proprietary library. As Entera 4 relies on the DCE runtime, it is not possible to obtain log messages from the DCE library calls.

Operations Issues

- AppCenter should be used for management of Entera 4 severs instead of AppMinder/Netminder.

• AppMinder/Netminder products are no longer supported. If you wish to manage Entera applications, their successor, AppCenter, can be used.

• Ensure DAP attribute NewProcess=0 is set when starting Entera 4 servers from an AppCenter configuration. If NewProcess=1 is set, the server will run in the background under a new process identifier compared to its original pid. AppCenter is only aware of the original pid and will not be able to manage the servers real process.

• Appminder 3.2 provides utilities such as 'amping', 'ambrwcfg', 'amgetsvr', 'amlodsvr’ and 'amuldsvr', etc. These can be replaced with AppCenters command line interface facility, cmdline.

- When shutting down Entera servers and the Broker use: -

$ $ODEDIR/bin/killer –s 15 <name_of_process>

Summary

Entera TCP applications selected for migration to Entera 4 should first be examined for all possible options. An Inprise PSO Entera migration questionnaire, Entera_4_Migration_Questionnaire.doc, should be completed and returned to Inprise to determine feasibility of any proposed migration. Once assessed, it may be necessary for customers to receive Entera 4 training and onsite consultancy to support the migration effort. During migration, applications could be enhanced to take advantage of some new features in Entera 4 such multi-threaded servers and database connection pooling for data access and Fx servers. Refer to Entera 4 documentation for more details. Obviously, a full quality assurance plan must be taken into an account before any migration should take place.