Building PIP v0.2 from the distribution file

Copyright (c) 2010 Fidelity Information Services, Inc.  All Rights Reserved.


Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.


GT.M™ and PIP™ are trademarks of Fidelity Information Services, Inc.  Other trademarks are the property of their respective owners.


This document contains descriptions of GT.M and PIP and the operating instructions pertaining to the various functions that comprise the system.  This document does not contain any commitment of FIS.  FIS believes the information in this publication is accurate as of its publication date; such information is subject to change without notice.  FIS is not responsible for any errors or defects. 


  1. Building PIP v0.2 from the distribution file
    1. Overview
    2. Caveat
    3. Prerequisites
    4. Instructions
      1. Install pre-requisites from Ubuntu package repositories
      2. Increase OS parameters
      3. Install GT.M
      4. Unpack PIP archive
      5. Build and install the external call library
      6. Build MTM
      7. Set up environment variables for GT.M
      8. Initialize the GT.M environment
      9. Verify that the "driver" works and recompile PIP
      10. Edit scripts to reflect the correct location of the PIP directory
      11. Start PIP and verify that MTM and server processes are alive
      12. Set up automatic startup and shutdown
      13. Verify automatic shutdown startup
    5. Use PIP

Overview

These instructions are for building PIP from the distribution file pip_V02_20100227.7z on an Ubuntu 8.04 LTS Jeos virtual machine.  Adapt as needed to your Linux distribution and release.


When booting a virtual machine, it is assumed that you have set up networking via port forwarding from the host, or otherwise, to connect to port 22 on the virtual machine for ssh (character mode) access and to port 61315 for the MTM.


Most of the PIP installation does not require root privileges.  Where root access is required, the commands are shown prefixed with sudo.  Your Linux system may be configured you to explicitly use a root shell instead of sudo.


Caveat

PIP V0.2 is the first release of PIP that is reasonably cleanly separated from FIS Profile.  It is also the first packaging of PIP that is intended to be upgradeable - but this is not proven yet.  These instructions are "expert friendly" as is PIP v0.2 (at least for the moment).  Please send comments on these instructions to ks dot bhaskar at fisglobal dot com.

Prerequisites

In addition to packages from the Ubuntu repositories, you will need:


Instructions

Install pre-requisites from Ubuntu package repositories

sudo aptitude install libicu-dev file make

Increase OS parameters

Edit the file /etc/sysctl.conf (you will need root access) and add three parameters at the end and load the new parameters into the running kernel (on reboots, the new parameters will be picked up automatically):


pip@ubuntu:~$ tail -4 /etc/sysctl.conf

# Added by Bhaskar for PIP - 20100224

kernel.msgmnb = 65536000

kernel.msgmni = 512

kernel.msgmax = 1048700

pip@ubuntu:~$ sudo sysctl -p # you may get more output, but verify that these are set

kernel.msgmnb = 65536000

kernel.msgmni = 512

kernel.msgmax = 1048700

pip@ubuntu:~$

Install GT.M

Install in an appropriate system directory.  /usr/lib/fis-gtm/platform_version is suggested, e.g., /usr/lib/fis-gtm/V5.4-000A_x86.  You will need ICU support because PIP is configured to use GT.M in UTF-8 mode.  Depending on your Linux distribution, you may, or may not, have to specify the ICU version.  GT.M installation requires root access.

Unpack PIP archive

Unpack the PIP archive into a directory of your choice, e.g., /home/pip/pip_V02 and change to that directory, e.g., cd pip_V02.

Build and install the external call library

cd ~/pip_V02/extcall_V1.2/shlib ; make
cd ../src ; make ; cp extcall.sl ..
cd ../alerts ; make ; cp alerts.sl ..


Edit alerts.xc and extcall.xc in the extcall_V1.2 subdirectory, and mtm.xc in the mtm_V2.4.5 subdirectory to ensure that the first line of each file points to the absolute path name of the shared library.  In this example:


pip@ubuntu:~/pip_V02/extcall_V1.2$ head -1 *.xc

==> alerts.xc <==

/home/pip/pip_V02/extcall_V1.2/alerts.sl


==> extcall.xc <==

/home/pip/pip_V02/extcall_V1.2/extcall.sl

pip@ubuntu:~/pip_V02/extcall_V1.2$


And:


pip@ubuntu:~/pip_V02$ head -1 mtm_V2.4.5/mtm.xc

/home/pip/pip_V02/mtm_V2.4.5/mtmapi.sl
pip@ubuntu:~/pip_V02$

Build MTM

cd ~/pip_V02/mtm_V2.4.5 ; make

Set up environment variables for GT.M

Edit ~/pip_V02/gtmenv and ensure that the environment variable gtm_dist points to the directory where GT.M is installed.  Edit ~/pip_V02/gtmenv1 and set the value of the environment variable gtm_icu_version to that of your Linux distribution (in the case of Ubuntu 8.04 LTS the version is 3.8.1; GT.M requires only the 3.8, you should omit the .1).  You can use the icu-config --version command to find the ICU version installed on your system; if it is not installed, you can query the package manager.

Initialize the GT.M environment

pip@ubuntu:~/pip_V02$ ./dm


GTM>


Create new journal files with the journal file in the correct directory for your installation.


GTM>zsy "$gtm_dist/mupip set -journal=""on,before,file=/home/pip/pip_V02/gbls/mumps.mjl"" -region DEFAULT"

%GTM-I-JNLFNF, Journal file /home/pip/pip_V02/gbls/mumps.mjl not found

%GTM-I-FILERENAME, File /home/pip/pip_V02/gbls/mumps.mjl is renamed to /home/pip/pip_V02/gbls/mumps.mjl_2010055151444

%GTM-I-JNLCREATE, Journal file /home/pip/pip_V02/gbls/mumps.mjl created for region DEFAULT with BEFORE_IMAGES

%GTM-I-PREVJNLLINKCUT, Previous journal file name link set to NULL in new journal file /home/pip/pip_V02/gbls/mumps.mjl created for database file /home/pip/pip_V02/gbls/mumps.dat

%GTM-I-JNLSTATE, Journaling state for region DEFAULT is now ON


GTM>


If you get the GDINVALID error, for example:


GTM>zsy "$gtm_dist/mupip set -journal=""on,before,file=/home/pippip_V02/gbls/mumps.mjl"" -region DEFAULT"

%GTM-E-GDINVALID, Unrecognized Global Directory file format: /home/pip/pip_V02/gbls/mumps.gld, expected label: GTCGBDUNX106, found: GTCGBDUNX006

it means that you are running a 64-bit GT.M.  The global directory distributed with PIP is compiled with a 32-bit GT.M.  You will need to delete the old global directory and create a replacement:


GTM>zsy "rm gbls/mumps.gld"


GTM>do ^GDE

%GDE-I-GDUSEDEFS, Using defaults for Global Directory

        /home/pip/pip_V02/gbls/mumps.gld


GDE> change -segment default -block_size=4096 -global_buffer_count=2000 -file_name=/home/pip/pip_V02/gbls/mumps.dat

GDE> change -region default -record_size=4080 -key_size=255

GDE> exit

%GDE-I-VERIFY, Verification OK


%GDE-I-GDCREATE, Creating Global Directory file

        /home/pip/pip_V02/gbls/mumps.gld

pip@ubuntu:~/pip_V02$


Now you can go back into GT.M and create new journal files.

Verify that the "driver" works and recompile PIP

From the GT.M direct mode, prompt:


GTM>d ^DRV


should take you into the "driver" from where you can login with a userid of 1 and a password of XXX.  Two consecutive presses F11 will take you out of the driver and back to the GT.M direct mode prompt.  Now recompile PIP with the following commands executed at the GT.M direct mode:

  

GTM>DO boot^UCGMCU(),bootFWPh2^UCGMCU()


Generates a lot of output with warnings and then ends with an error:


%GTM-E-ZLINKFILE, Error while zlinking "USTMAPDF",%GTM-E-FILENOTFND, File USTMAPDF not found
                At M source location linkList+7^UCGMCU

GTM>

Ignore the error at the end and recompile the other elements with the following commands.  Ignore any warnings.


DO BUILDALL^DBSPROC ; compiles PROCEDURES

DO BUILDALL^DBSDSMC ; compiles SCREENS

DO BUILDALL^DBSRWDRV ; compile REPORTS

DO BUILDALL^DBSFILB ; compile all FILERS

Edit scripts to reflect the correct location of the PIP directory

Edit the file pip_V02/mtm/PIPMTM to specify the directory where PIP is installed, in this example, /home/pip.

Start PIP and verify that MTM and server processes are alive

pip@ubuntu:~/pip_V02$ ./pipstart

nohup: redirecting stderr to stdout
%GTM-I-MUJNLSTAT, Initial processing started at Thu Feb 25 11:41:41 2010
%GTM-S-JNLSUCCESS, Show successful
%GTM-S-JNLSUCCESS, Verify successful
%GTM-S-JNLSUCCESS, Recover successful
%GTM-I-MUJNLSTAT, End processing at Thu Feb 25 11:41:41 2010
%GTM-I-FILERENAME, File /home/pip/pip_V02/gbls/mumps.mjl is renamed to /home/pip/pip_V02/gbls/mumps.mjl_2010056113215
%GTM-I-JNLCREATE, Journal file /home/pip/pip_V02/gbls/mumps.mjl created for database file /home/pip/pip_V02/gbls/mumps.dat with BEFORE_IMAGES
%GTM-I-JNLSTATE, Journaling state for database file /home/pip/pip_V02/gbls/mumps.dat is now ON

GTM>Halt

pip@ubuntu:~/pip_V02$ ps -ef | grep -E \(mtm\)\|\(mumps\) | grep -v grep
pip       3959     1  0 11:41 pts/0    00:00:00 /home/pip/pip_V02/mtm_V2.4.5/mtm -nMTM_PIPV02 -p61315 -l/home/pip/pip_V02/mtm/MTM_PIPV02.LOG
pip       4002     1  0 11:41 ?        00:00:00 /usr/lib/fis-gtm/V5.4-000A_x86/mumps -direct
pip       4005     1  0 11:41 ?        00:00:00 /usr/lib/fis-gtm/V5.4-000A_x86/mumps -direct
pip@ubuntu:~/pip_V02$

Set up automatic startup and shutdown

Create a file /etc/init.d/pip_V02 along the following lines:


pip@ubuntu:~$ cat /etc/init.d/pip_V02

#! /bin/bash                         

### BEGIN INIT INFO                  

# Provides:          pip_V02         

# Required-Start:    $local_fs       

# Required-Stop:     $local_fs       

# Default-Start:     2 3 4 5         

# Default-Stop:      0 1 6           

# Short-Description: PIP V0.2        

# Description:       Starts and Stops PIP V02

### END INIT INFO                            


# Author: K.S. Bhaskar <ks.bhaskar@fisglobal.com>


# Do NOT "set -e"


NAME=pip_V02

PATH=/sbin:/usr/sbin:/bin:/usr/bin

DESC="PIP V0.2"                   

SCRIPTNAME=/etc/init.d/$NAME      



#

# Function that starts PIP V0.2

#

do_start()

{

       su -c "cd /home/pip/pip_V02 ; ./pipstart" pip

}


#

# Function that stops PIP V02

#

do_stop()

{

       su -c "cd /home/pip/pip_V02 ; ./pipstop" pip

}


case "$1" in

 start)

       do_start

       ;;

 stop)

       do_stop

       ;;

 restart|force-reload)

       do_stop

       do_start

       ;;

 *)

       echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload}" >&2

       exit 3

       ;;

esac


:

pip@ubuntu:~$


Create symbolic links in /etc/rc*.d to the script in /etc/init.d so that PIP is automatically started and stopped.


pip@ubuntu:~$ cd /etc/rc5.d/ ; sudo ln -s ../init.d/pip_V02 S95pip_V02 ; sudo ln -s ../init.d/pip_V02 K05pip_V02
pip@ubuntu:/etc/rc5.d$ cd /etc/rc4.d/ ; sudo ln -s ../init.d/pip_V02 S95pip_V02 ; sudo ln -s ../init.d/pip_V02 K05pip_V02
pip@ubuntu:/etc/rc4.d$ cd /etc/rc3.d/ ; sudo ln -s ../init.d/pip_V02 S95pip_V02 ; sudo ln -s ../init.d/pip_V02 K05pip_V02
pip@ubuntu:/etc/rc3.d$ cd /etc/rc2.d/ ; sudo ln -s ../init.d/pip_V02 S95pip_V02 ; sudo ln -s ../init.d/pip_V02 K05pip_V02
pip@ubuntu:/etc/rc2.d$ cd /etc/rc6.d/ ; sudo ln -s ../init.d/pip_V02 K05pip_V02
pip@ubuntu:/etc/rc6.d$ cd /etc/rc1.d/ ; sudo ln -s ../init.d/pip_V02 K05pip_V02
pip@ubuntu:/etc/rc1.d$ cd /etc/rc0.d/ ; sudo ln -s ../init.d/pip_V02 K05pip_V02
pip@ubuntu:/etc/rc0.d$

Verify automatic shutdown startup

Reboot the virtual machine and connect to port 61315 to verify operation.  In this example, I have booted the virtual machine so that port 61315 on the host machine is forwarded to port 61351 on the virtual machine, so this also verifies the ability to connect to the virtual machine.


$ telnet localhost 61315

Trying ::1...

Trying 127.0.0.1...

Connected to localhost.

Escape character is '^]'.

^]

telnet> close

Connection closed.

$

Use PIP

You can connect to port 61315 with a JDBC client such as DbVisualizer.  For now, you can use the JDBC driver provided with PIP V0.1.  Also, you can go in to the "driver" and experiment with PIP.  (Yes, this release of PIP is expert friendly.)