February 2004

Magic 9 Server Version 9.4 SP2b for UNIX Platforms

Dear Developer,

We are happy to introduce the Magic 9.4 Server for UNIX platforms.

Please read the information below to learn more about the Magic 9 Server for UNIX, Version 9.4 Service Pack 2b.

Magic Version 9.4 SP2b provides enhanced performance and stability, and introduces enhanced integration and connectivity capabilities.

For information about Magic Version 9.4 Service Pack2b see http://ftp.magicsoftware.com/v9product/readmes/readme940sp2b.htm

This readme gives information about the topics listed below: 

Installation components

Installation instructions

Starting the Magic Server/Broker

Verifying Browser-Client connectivity

Magic 9 server log file

Magic requesters

Using flat files

Using colors in browser tasks

Apache requester installation and configuration

Platform-specific information

Gateway-specific information

Limitations

Recommendations

Browser client language support

Java integration

License registration

Websphere MQ setup

Installation components (Top)

· Magic Server (bin/magicrnt)

· Magic Broker (broker/mgrqmrb)

· Magic command line requester (broker/mgrqcmdl)

· Magic gateway for Oracle 8i and Oracle 9i (bin/mgoracle8 , bin/mgoracle9)

· Magic gateway for DB2 UDB Version 7.2 (bin/mgdb2) – for AIX platform only

· Magic gateway for ODBC (bin/mgodbc) – for Linux platform only

· Magic gateway for iSeries ISAM tables (bin/mgeac) – for Linux platform only

· Magic gateway for iSeries SQL tables (bin/mgdb400) – for Linux platform only

· Magic gateway for Informix Version 7.3 (bin/mginformix)

· Magic memory gateway (bin/mgmemory)

· Magic CGI requester (cgibin/mgrqcgi94)

· Magic requester for Apache Web Server (cgibin/mod_mgrequest94.so , cgibin/mod_mgrequest94.so.NO_EAPI , cgibin/mod_V2_mgrequest94.so)

· Magic 9 UDF/UDP examples (userproc directory)

· Magic 9 Web utility files used for Browser Client & WOL support (web_utils directory)

· Magic 9 license server (FlexLM 7 in license directory)

· Magic 9 installation verification utility (install_utils directory)

· Magic 9 Hangul support (language/mglocal.kor)

· Magic 9 SNMP sub-agent (snmp/mgsnmp.so)

· Magic 9 Messaging component (messaging/messaging.mff)

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Installation instructions (Top)

Notes:

1. During the installation, several user-environment files are overwritten. Therefore it is best to back up the following files before starting the installation process:
.cshrc, .profile, .bash_profile (applies to Linux only)

2. If you already have a previous Magic 9 server version installed, it is best to install the product using a different user name.

3. In the installation fails, it is best to delete all files in $MAGIC_HOME and start a new installation from the beginning.

Installation steps:

· Create a new user. (The installation should be performed using a non-root user.)

· Log in as the new user.

· Uncompress the installation file (magic94_<platform>.tar.Z) using the local uncompress utility or a compatible utility, such as gunzip).

· Run the command from $HOME directory: tar xvf <installation file>.
The installation file name is magic94_<platform>.tar.

· Run the ./mginstall command and enter the requested information.
Note: The RedHat 7.x cgi-bin directory is located in /var/www/cgi-bin.

· After the installation has been successfully completed, run the $HOME/sbin/mgroot.sh file as a root user. This script copies Magic files that should be accessed by your Web Server.

· To set up an Apache Web Server, append the $HOME/web_utils/magic.conf file to the Apache configuration file (httpd.conf) and restart the Apache Web Server.

· Log out from the new user and log in again to enable the new environment settings.

· If you need to uninstall the product, delete the user home directory created for the installation. For a complete removal, delete the files copied by the $MAGIC_HOME/sbin/mgroot.sh script and remove the changes that were applied to the web server.

· For Linux installations: When installing on SuSE 7.3 or RedHat 9.0 (or more recent versions) the following commands should be executed:

o Log in as the new user

o Execute: cd $MAGIC_HOME/lib

o Execute: ln -s /usr/lib/libssl.so.0 libssl.so.2

o Execute: ln -s /usr/lib/libcrypto.so.0 libcrypto.so.2

Starting the Magic Server/Broker (Top)

To run the Magic Server:

1. Start the license server by running the $HOME/license/mglmstart script.

2. Use the mgrnt script or invoke the magicrnt executable file. By default Magic uses the INI file specified in the MGENV environment variable.

For the non-default INI file, use:

mgrnt –ini=<ini file> &

For an additional INI file, use:

mgrnt –ini=<ini file> \@<additional ini> &

Several scripts have been added to the sbin directory to simplify the Magic server administration:

startb Start the Magic Broker

stopb Stop the Magic Broker (and Server engines)

stopm Stop all Magic Server engines connected to the Magic Broker

checkm Check which Magic Server engines are connected to the Magic Broker

Note: The stopb and stopm scripts require supplying the broker password, as shown in the following example:

stopb –password=<broker supervisor password>

Verifying Browser Client connectivity (Top)

1. Start the Magic Broker (using startb)

2. Start the Magic engine (using mgrnt &)

3. Check that the Magic Server connected successfully to the Magic Broker (using checkm)

4. From the Internet Browser (IE 5.5 and above) call the following URL:

http://<server name>/<cgi bin alias>/mgrqcgi94?appname=VerifyInstall&prgname=verify

For example : http://myserver/cgi-bin/mgrqcgi94?appname=VerifyInstall&prgname=verify

If your Magic Enterprise server environment has been configured correctly, a message to that effect appears.

Magic 9 Server log file (Top)

The Magic 9 log file mgflwmtr.log.<pid> is created for each server you start. You can choose another name for this log file by using the Monitor2File entry in the Magic.ini file. This log file replaces the Magic 8 log file, mgrntlog.<pid>. For a more detailed log, set LoadMonitor = Y
in the MAGIC.INI file, and set the flow monitor options in the file pointed to by the MGFLWMTR environment variable. The default is $MAGIC_HOME/etc/MGFLWMTR.INI.

Magic requesters (Top)

The MGREQENV environment variable points to the MGREQ.INI file used by the Magic Server, the Magic Broker, and the Magic command line requester. (The installation sets MGREQENV = $HOME/etc/MGREQ.INI).

To send a request to a Magic Server on UNIX from an Internet Browser, there are two types of requesters:

1. The Magic CGI requester (mgrqcgi94):
http://<server_name>/cgi-bin/mgrqcgi94?appname=example1&prgname=prog1

2. The Magic requester for Apache (mod_mgrequest94.so):
http://<server_name>/mgrequest9?appname=example1&prgname=prog1

Additional Settings

Two settings have been added to the MGREQ.INI file that affects the requester execution.

RetryMainTime=nn (default: 5)
The RetryMainTime setting determines the time interval that a requester connected to an alternate Request Broker should try to reconnect to the main Request Broker.

If the requester is already connected to the main Request Broker, the RetryMainTime setting does not apply.

The time interval is specified in minutes.

For example, when RetryMainTime=15, the requester tries to reconnect to the main Request Broker every 15 minutes. When the main Request Broker becomes available, the requester connects to it and disconnects from the alternate Request Broker. If the main Request Broker becomes unavailable, the requester returns to the alternate Request Broker and tries to reconnect to the Main Request Broker every 15 minutes.

When RetryMainTime=0, the requester does not try to connect to the main Request Broker but remains connected to the alternate Request Broker.

KeepAlive=Y\N (default: N)
When KeepAlive=Yes, the Magic Generic Messaging Layer module, mgrqgnrc94.dll, lets the system administrator use operating-system level-settings to control the keep-alive intervals for each open connection.

Only a system administrator should determine the settings for the operating system intervals.

Using flat files (Top)

If your application is stored as a Magic Flat File (MFF), replace the last character (N) in the [MAGIC_SYSTEMS] section of the MAGIC.INI file with a Y. Refer to the Magic eDeveloper Reference Guide for more information about this feature.

Example:

1. When you use the Magic application file in an Oracle database:
System1 = example1,e1,example1mcf,14,Default Database,,N,N,N

2. When you use the Magic Flat File %MagicDir%/example1.mff for the same application
System1 = example1,e1,%MagicDir%/example1.mff,1,,,N,N,Y

Using colors in browser tasks (Top)

To use colors properly on UNIX platforms, you must define all the colors that are used as
non-system colors. The easiest way to do this is to access the color file in the Magic toolkit mode and define the colors accordingly.

Apache requester installation and configuration (Top)

Apache module requester setup

Magic 9 includes requesters for the Apache Web Server version 1.3 and version 2.0. To use the 1.3 requester, Apache should be compiled using the DSO option. The requester module mod_mgrequest94.so should be placed in the libexec directory of the Apache installation (default: /usr/local/httpd/libexec) with execute permissions.

The installation includes the following requesters:

1. mod_mgrequest94.so - to be used with Apache with SSL support

2. mod_mgrequest94.so.NO_EAPI - to be used with Apache 1.3 without SSL support

3. mod_V2_mgrequest94.so - to be used with Apache 2.0

The lines listed below should be added to the Apache configuration file, httpd.conf.

LoadModule mgrequest9_module libexec/mod_mgrequest94.so

<Location /mgrequest9>

SetHandler mgrequest9-handler

</Location>

SetEnv MGREQ_INI_PATH <directory>

The Apache Web server should be restarted after making this modification.

The Apache requester is configured using the MGREQ.INI file. The directory location of the MGREQ.INI file is specified by the MGREQ_INI_PATH setting in the Apache configuration file, httpd.conf.

Example:

SetEnv MGREQ_INI_PATH /usr/local/httpd/conf

The Apache requester uses the /usr/local/httpd/conf/MGREQ.INI file.

To use this requester, call Magic using a URL like the one below: http://server/mgrequest9?appname=...

You should also modify the MAGIC.INI file to read:
InternetDispatcherPath= /mgrequest9

Using an Apache Web Server with a non-default port (port number other than 80)

If you would like to use Apache with a non-default port, you should change the setting shown below in the MAGIC.INI file:
InternetDispatcherPath= http://server:port/cgi-bin/mgrqcgi94
instead of
/cgi-bin/mgrqcgi94

Platform-specific information (Top)

AIX - The Magic 9 Server for AIX should be used with AIX 4.3.3 or with other more recent operating systems that are backward compatible.

The Oracle gateway should be used with the Oracle 8.1.7 or the latest 9i Client.

The Magic DB2 gateway for AIX should be used with the DB2 Version 7.2 client.

The Websphere MQ 5.3 client/server is required for working with the messaging component.

JRE 1.3.1 is required for working with Java integration capabilities.

Apache 2.0.45 (or a more recent version) is required in order to use the Apache 2 requester.

Solaris - The Magic 9 Server for Solaris should be used with Solaris 8 or with other more recent operating systems that are backward compatible.

The Oracle gateway should be used with the Oracle 8.1.7 or the latest 9i Client.

The Websphere MQ 5.3 client/server is required for working with the messaging component.

JRE 1.3.1 is required for working with Java integration capabilities.

Apache 2.0.45 (or a more recent version) is required in order to use the Apache 2 requester.

Linux - For Intel processors only, Linux requires Kernel 2.4.10 (and up) and GLIBC 2.2.

The Oracle gateway should be used with the Oracle 8.1.7 or the latest 9i Client.

The Websphere MQ 5.3 client/server is required for working with the messaging component.

JRE 1.4.1 is required for working with Java integration capabilities.

Apache 2.0.43 (or a more recent version) is required in order to use the Apache 2 requester.

Gateway-specific information (Top)

To enable the use of a particular gateway, remove the # sign from the corresponding entry in the $MAGIC_HOME/etc/mgenv file.

When using the Oracle gateway, make sure that ORACLE_HOME and ORACLE_SID are set in the $MAGIC_HOME/etc/mgenv file, and that the environment variable LD_LIBRARY_PATH (or LIBPATH for AIX) includes the $ORACLE_HOME/lib directory.

When using the DB2 gateway, make sure that DB2INSTANCE is set in the $MAGIC_HOME/etc/mgenv file.

When using the Informix gateway, make sure that INFORMIXDIR and INFORMIXSERVER are set in the $MAGIC_HOME/etc/mgenv file, and that the environment variable LD_LIBRARY_PATH (or LIBPATH for AIX) includes the $INFORMIXDIR/lib and the $INFORMIXDIR/lib/esql directories.

For information regarding the ODBC gateway on the Linux platform, please refer to :

http://ftp.magicsoftware.com/v9product/readmes/readmeodbc94_linux.htm

Limitations (Top)

· Connectivity to messaging servers via JMS is not supported using the provided messaging component.

Recommendations (Top)

· We highly recommended backing up Magic configuration files, such as MAGIC.INI, MGRB.INI, MGREQ.INI, and license.dat, before modifying them.

Browser Client (Top)

The browser client technology of eDeveloper has gone through a major performance enhancement by enabling the end-user’s browser to locally cache the logic segments of the application. In this way a significant amount of data is retrieved from the client’s cache instead of being transmitted anew for every task. The browser client caching mechanism is aware of changes introduced to existing tasks and will cache and utilize the modified task.

This mechanism is affected by two new environment settings: Browser client cache path and Browser client cache alias (CTLCacheFilesPath and CTLCacheFilesAlias accordingly). Both are defined in the MAGIC.INI file.

The Magic server should have write permission to the directory defined by the CTLCacheFilesPath environment setting.

The Web server should have read permission to the same directory. You may choose to create a different directory and point to it by the CTLCacheFilesPath environment variable. The alias defined by the CTLCacheFilesAlias environment variable should also point to this directory.

The Browser client feature using the new Task Caching mechanism requires a modification in the ANSI to Unicode translation environment setting (Ansi2Unicode). The character set of the language in use should be set using the Standard name and the Java name. For example, if the language of a browser client application is Korean than the environment setting should include both the “MS949” Java name and the “windows-949” separated by slash.

For example: MS949/windows-949 You may use the following link to find the Standard name and Java name of various character sets: http://www.devsphere.com/mapping/docs/guide/encodings.html

A remarked entry named MGLOCAL, which points to the Korean support library mglocal.kor, exists in the mgenv file. This file is required for proper functioning of browser-based applications when using Korean/Hangul characters.

Java integration (Top)

The Java CLASSPATH separator character on UNIX platforms is a colon (:) as opposed to the Windows platform separator character which is a semicolon (;).

For example: CLASSPATH = /java/MyClasses:/java/OtherClasses

For more information, please refer to the Java documentation (Java 2 SDK Tools and Utilities at http://java.sun.com/j2se/1.3/docs/tooldocs/tools.html).

AIX

The JAVA_HOME entry should be set in the MAGIC_JAVA section of the MAGIC.INI file.

For example: If JAVA_HOME = /usr/java131

Magic appends /jre/bin/classic/libjvm.a in order to find the libjvm.a library.

If you encounter problems locating this file you can use the environment variable: MG_JAVALIB, which should be set to the absolute path of the library file.

For example: MG_JAVALIB = /usr/java131/jre/bin/classic/libjvm.a

The AIX LIBPATH variable should include /usr/java131/jre/bin:/usr/java131/jre/bin/classic

Solaris

The $MAGIC_HOME/lib/stub entry in LD_LIBRARY_PATH is only required if you do not have Java installed on your server.

If Java is installed on your server, you should edit the following scripts: .cshrc and .profile, and remove $MAGIC_HOME/lib/stub from the LD_LIBRARY_PATH.

The LD_LIBRARY_PATH environment variable should include $JAVA_HOME/jre/lib/sparc/client

Linux

The $MAGIC_HOME/lib/stub entry in LD_LIBRARY_PATH is only required if you do not have Java installed on your server.

If Java is installed on your server, you should edit the following scripts: .cshrc and .profile, and remove $MAGIC_HOME/lib/stub from the LD_LIBRARY_PATH.

The LD_LIBRARY_PATH environment variable should include $JAVA_HOME/jre/lib/i386/client and $JAVA_HOME/jre/lib/i386

License Registration (Top)

To obtain a permanent license for the Magic enterprise server please follow the procedure outlined below:

Run the request_license script, which can be found in the $MAGIC_HOME/sbin directory.
This script creates a file called lic_request.url, which includes the hostname and hostid.
Copy this file to a Win32 system that is connected to the Internet, and double-click on the file.

For more information, please refer to the Magic Guide to Installation and Licensing.

Websphere MQ (Top)

If you are using an MQ client software, you should set the following logical name in the MAGIC.INI file:
WMQ_ModuleName = C

If you are using an MQ server software, meaning that the MQ Queue manager runs on the same machine as the Magic Server, you should set the following logical name in the MAGIC.INI file:
WMQ_ModuleName = S

Thank you,

The Magic eDeveloper UNIX Team