#############################################################
# Copyright (c) 2005, 2006 IBM Corporation and others. 
# All rights reserved.   This program and the accompanying materials 
# are made available under the terms of the Eclipse Public License v1.0 
# which accompanies this distribution, and is available at 
# http://www.eclipse.org/legal/epl-v10.html         
# $Id: building-notes.txt,v 1.2 2006/02/06 20:18:17 nmehrega Exp $ 
#  
# Contributors: 
# IBM - Initial contribution
#############################################################

These are specific instructions for building and testing the BCI and ProbeAgentExtension subprojects on many platforms.


JDK_HOME: a Java install directory that has a subdirectory called "include"

RASERVER_SDK: a directory with a RAC SDK package unzipped in it. Also has an "include" subdirectory. This is needed for files like piAgentExtension.h

Connecting to Toronto
---------------------
Whenever possible, you should use ssh rather than telnet or rlogin. Toronto 
(and presumably IBM) prefers for preserving the security of the connections 
over the WAN. Ssh is available on all our Linux machines and some of our 
Solaris machines. Putty (freeware) is a suitable ssh client for connecting 
from Windows.

A couple of the platforms in Toronto are tricky to connect to, so check the 
platform specifics for gotchas before you leap in with both feet.


WIN32 with Visual Studio 7
=====

set JDK_HOME=<your jdk dir>
set RASERVER_SDK<your rac sdk dir>
set INCLUDE=%INCLUDE%;%JDK_HOME%\include;%JDK_HOME%\include\win32

cd BCI
nmake -f makefile.win_ia32
cd ..\ProbeAgentExtension\WinBuild
nmake -f ProbeAgentExtension.mak
.\package.bat


zLINUX on enwlinx2
==================

You can't access enwlinx2 directly from Cupertino - you have to ssh to enwlinx1 or enwlinx3
and then ssh from there to enwlinx2. Also, you have to use ssh protocol 1, not protocol 2. 
(This appears to be the default when using ssh from enwlinx1 to enwlinx2; I can't speak for any others.)

Transfer sources to enwlinx2 with proper Unix newlines.
Using FTP in ASCII mode is not good enough - the ftpd doesn't do newline translations.
enwlinx2 has g++ version 2.95.2 and God knows what includes, libs, and other details.

username testcup1
password ratl1cup

If you can't ftp directly to enwlinx2, you will have to ftp to enwlinx1 or 3 and then scp
the files to enwlinx2. Some magic makes this work without asking for a password:
	scp localfile enwlinx2:/home/testcup/path/to/file


export JDK_HOME=/opt/IBMJava2-s390-141
export RASERVER_SDK=/home/testcup1/apratt/rac-zLinux/sdk
cd BCI
gmake -f Makefile.unix
cd ../ProbeAgentExtension
gmake -f Makefile.unix
gmake -f Makefile.unix package

x86 LINUX on cypress
====================

setenv JAVA_HOME ~/ibm-linux-jvm
setenv JDK_HOME ~/j2sdk1.4.2_04
setenv RASERVER_HOME ~/rac-linux
setenv LD_LIBRARY_PATH $JAVA_HOME/lib:$JAVA_HOME/lib/i386:$JAVA_HOME/lib/i386/client:$JAVA_HOME/bin/classic:$JAVA_HOME/bin/j9vm:$RASERVER_HOME/lib
# Put Java_home/bin first, to get "java"
# Then include JDK_home second, to get "jar"
setenv PATH $JAVA_HOME/bin:$JDK_HOME/bin:.:$RASERVER_HOME/bin:$PATH
setenv BCIINCLUDE ~/BCI/BCIEng
setenv RASERVER_SDK ~/racsdk

HPUX on dali
=============
stty erase '^?' kill ^U susp ^Z
setenv JDK_HOME /opt/java1.4
setenv JAVA_HOME /opt/java1.4/jre
setenv RASERVER_HOME /people/apratt/rac-hpux
setenv LD_LIBRARY_PATH $JDK_HOME/jre/lib:$JDK_HOME/jre/bin/classic:$JDK_HOME/jre/bin/j9vm:$RASERVER_HOME/lib
setenv PATH /opt/ansic/bin:/usr/local/bin:/usr/sbin:$JDK_HOME/bin:$JAVA_HOME/bin:.:$RASERVER_HOME/bin:/usr/ccs/bin:/opt/gnu/bin:/tools/bin:$PATH
setenv RASERVER_SDK /people/apratt/racsdk
setenv SHLIB_PATH $JAVA_HOME/jre/lib/PA_RISC2.0/hotspot:/opt/java1.4/jre/lib/PA_RISC2.0:$RASERVER_HOME/lib
setenv LD_PRELOAD $JAVA_HOME/jre/lib/PA_RISC2.0/hotspot/libjvm.sl


SOLARIS on renoir
=================
setenv JDK_HOME /tools/install/jdk/j2sdk1.4.1_04
setenv RASERVER_HOME ~/rac-solaris
setenv LD_LIBRARY_PATH $JDK_HOME/jre/lib:$JDK_HOME/jre/bin/classic:$JDK_HOME/jre/bin/j9vm:$RASERVER_HOME/lib
setenv PATH /usr/sbin:$JDK_HOME/bin:.:$RASERVER_HOME/bin:/usr/ccs/bin:/opt/gnu/bin:/tools/bin:$PATH
setenv RASERVER_SDK ~/racsdk

cd BCI
gmake -f Makefile.unix
cd ../ProbeAgentExtension
gmake -f Makefile.unix
gmake -f Makefile.unix ZIP="jar cMf" package


OS400 on torascgm
=================

For testing, build on TORAS1FB:
TORAS1FB: user name apratt, password pur1fy, build env under /home/apratt/build
...but 1fb is configured for an Israeli locale and Hebrew character set, which gives the logging analyzer agent people fits and might hurt us too, so maybe you don't want to use that one.

The Toronto build machine is TOASCGM:
TORASCGM: user name bluerat, password ecl1pse (new as of 10/04)
build env under /home/xuan/racbuild
...but this is the official build machine. Stay off unless you have permission from people like Qiyan Li or Samson Wai in Toronto, otherwise you'll step on builds and people will hurt you.

The right sandbox machine to build and test on is toras3rm.torolab.ibm.com:
TORAS3RM: user name apratt, password eclipse, build env under /home/apratt/build

See instructions in the BlueRat VOB at
www/Hyades/AS400/iSeries_howto.html and other files near there for
instructions on getting a terminal session running.

(From green screen:)
addlible HYADESDC
ADDLIBLE IBMRAC
strqsh

(now in qsh environment:)
export QIBM_MULTI_THREADED=Y
cd /home/apratt/build/probes
cd BCI
gmake -f makefile.os400
cd ../ProbeAgentExtension
gmake -f makefile.os400

This builds into a program library called IBMRAC.

To test Probekit in standalone mode, change to a directory with
"j.class" in it and run this:

java -XrunpiAgent:server=standalone,extensionLibrary=PROBEAGENT/PROBEAGENT,ext-pk-BCILibraryName=PROBEAGENT/BCIENGPROB,ext-pk-logLevel=finest,ext-pk-logFile=stderr,ext-pk-probescript=scr j

One good indication of anyone using a RAC on a machine is to run 
WRKACTJOB SBS(QINTER) 
and if there is a RASTART job running under another person's ID then that person is using the machine.

java -XrunpiAgent:server=standalone,extensionLibrary=PROBEAGENT/PROBEAGENT,ext-pk-BCILibraryName=PROBEAGENT/BCIENGPROB,ext-pk-logLevel=finest,ext-pk-logFile=stderr,ext-pk-probescript=scr j                                           

Unlike z/OS, native code string literals on AS400 are EBCDIC. So are most strings coming from the RAC, like configuration strings. So are command-line arguments in the options string, etc. As always, Java strings are UTF8. In addition, engine script strings that come from the Workbench are ASCII (actually UTF8), because they're sent with BINARY_CUSTOM_COMMAND.

This means that an engine script coming from a file on disk must be converted to ASCII, and then the string literals in the script interpretation function must be within pragma convert(819), just like zOS.

-------------------------
Starting the RAC on AS400
-------------------------

You start the RAC from outside the qsh environment.

The RAC lives in /opt/hyadesdc or /opt/IBMRAC.

Here is how you start a RAC on iSeries so you can deploy to it from a workbench: 

1. One-time setup, in qsh: run SetConfig.sh just like on Unix. [Do you need to set RASERVER_HOME for this shell script to work?] 
2. Outside qsh, run ADDLIBLE HYADESDC to add the RAC library to your PATH. Or IBMRAC if that's your bag.
3. Make sure no RAC is running: run WRKACTJOB and see that no PGM-RASERVER job is running. 
4. Run SBMJOB CMD(CALL RASERVER) JOBD(RASTART) to start the RAC process. 

You can check the job queue with WRKACTJOB to see that it is really running: the status column of that job should be THDW. 

You can also start the server from inside qsh: system SBMJOB CMD\(CALL RASERVER\) JOBD\(RASTART\)

To end the RAC job, run WRKACTJOB and kill the PGM-RASERVER job by typing a "4" in front of the job entry and pressing Enter. 

If the RAC won't start and nothing appears in the RAC's log file, use this command: WRKSPLF ("work with spool files"). Scroll to the last entry with your name on it, then up to the last one called QPRINT. Enter "5" to display this file. It will be an error message from the RAC, reporting (for instance) an error parsing the serviceconfig.xml file.



AIX
=================

Build on olt2.torolab.ibm.com / testcup1 / ratl1cup

Note: olt2 is a productionbuild machine in Toronto, so treat it with respect. 
Do not consume large amounts of disk space or CPU time. You'll be quite unpopular 
if you screw up the Toronto builds.

RASERVER_SDK is ~/racsdk
JDK_HOME is ~/head/depends/java

You'd like to run this: . ~/head/depends/bin/setbldenv.aix-ppc.sh
but you can't because testcup1 can't read the files in ~/head/depends/bin

cd /home/testcup1/apratt/probes/BCI
make -f Makefile.unix
cd ../ProbeAgentExtension
make -f Makefile.unix
make -f Makefile.unix package

Test on nith.torolab.ibm.com (accepts telnet, same user/pw)

export PATH=/usr/java14/bin:$PATH
export LIBPATH=/usr/java14/jre/bin/classic:/usr/java14/jre/bin:/home/testcup1/rac/lib:$LIBPATH
/home/testcup1/rac/bin/RAServer


OS390 on torolabb
=================

You have to use rlogin to access torolabb, not telnet or ssh. A secure way to
access this system is ssh to another machine in toronto (like enwlinx1) and
then rlogin to torolabb.

Login name on torolabb: testcup, pw z0stests (this pw as of 4/13/05)

If this account is locked out (e.g. tried the wrong password too often), then 
Samson Wai (the account owner) has to go to https://idman.torolab.ibm.com/ to 
request the unlock.

------------------
Source translation
------------------
When you bring sources over from the ASCII universe (ours) to the
EBCDIC one, they need to be converted or the build tools will spit
them out on the floor as nasty tasting. An easy way to do this is 
to use the -aa option of unzip. For example, on torolabb:

   > ftp somewhere.cupertino.ibm.com
   ftp> get mysources.zip
   ftp> quit
   > unzip -aa mysources.zip

If you can't find unzip, it lives in /home/eclipse/bin on torolabb.

Another alternative is to use something like SmartFTP to transfer
files - it knows how to transfer directory hierarchies (no pre-zip
step) and to do the translation on the fly.

--------------------------------------------
Important things to know about the zOS port:
--------------------------------------------

There is a bug in zOS version 1.5 and 1.6 that causes printf and fprintf 
(and possibly other library calls) to crash unpredictably. Subtle, 
seemingly-unrelated changes to a program can cause a given printf to start 
crashing, or to stop crashing. It has to do with a use of an uninitialized 
variable in some system library routines. There is a patch, called PQ89263, 
that isn't quite out yet (as of 7/23/04) but that might fix the problem. 
Instead, I just removed all printf calls from ProbeAgentExtension.c; I use 
sprintf and fputs instead. (There aren't any in BCIEngProbe or the RAC 
libraries, and the ones in piAgent for debugging etc. don't seem to crash.)

The zOS makefiles tell the compiler to treat every string literal ("hello") 
and char literal ('/') as ASCII. But text data read from a file is always 
EBCDIC, and data going from and to the RAC is EBCDIC. Convert with __etoa() 
and __atoe(), which rewrite strings in place. Strings that go to library 
functions (like printf) need to be EBCDIC: to get EBCDIC literals, use 
#pragma convlit(suspend) before and convlit(resume) after:

#ifdef MVS
#pragma convlit(suspend)
#endif
	FILE *fp = fopen(theFile, "r"); /* the literal string "r" must be EBCDIC
#ifdef MVS
#pragma convlit(resume)
#endif

--------------------------------------
What follows are instructions for building BlueRat components from the "probes" level.
Different instructions below are for building the RAC at the "collection" level.
--------------------------------------

Running /labb/u068/ts30783/zosv1r5.sh will set the env vars so the V1R5 
compiler is used when you use the cxx command.  That compiler will accept the 
TARGET(zOSV1R5) parameter.

The 1.4 JDK is /usr/lpp/java/IBM/J1.4

On torolabb in testcup there are two environment setup files:
setpath-zOS.sh is the one to use to build BlueRat;
setpath-rac.sh is the one to use to build the RAC.

This is the contents of the first one, the BlueRat building one:
cp -r /home/eclipse/head/depends ~/apratt
export PATH=~/apratt/depends/bin:~/apratt/depends/make:~/apratt/depends/java/bin:/bin:/usr/sbin:/usr/share/lib/terminfo/:.:/etc:/tools/:/home/testcup
export JAVA_HOME=~/apratt/depends/java
export JDK_HOME=~/apratt/depends/java
export RASERVER_SDK=~/apratt/depends/racsdk
export LIBPATH=$JAVA_HOME/bin/classic:$JAVA_HOME/bin:$LIBPATH
export RASERVER_HOME=~/apratt/rac
export LIBPATH=$RASERVER_HOME/lib:$RASERVER_HOME/com.ibm.rational.pd.probekit/lib

. /labb/u068/ts30783/zosv1r5.sh

cd ~/apratt/probes/BCI
make -f Makefile.unix
cd ../ProbeAgentExtension
make -f Makefile.unix
make -f Makefile.unix package

--------------------------------------------------------------------------
Here is how I was able to build the RAC:
--------------------------------------------------------------------------

- From your home directory create a subdirectory called "build".
- In the build subdirectory, create a soft link called "depends" to "/home/eclipse/head/depends"
- in the build subdirectory, create another subdirectory (called "source", or whatever you want to call it)
- in the build/source subdirectory, extract the source tree starting with the "collection" subdirectory 

This is the environment-setting script that lets me build the RAC:

#!/bin/sh
RELEASE=build

#
# Compiler
#
export _CXX_CXXSUFFIX=cpp
export STEPLIB=SYS1.OSV2R10.SCBCCMP
#export STEPLIB=SYS1.OSV2R10.SCBCCMP:$STEPLIB
export TZ=EST5EDT
export NLSPATH=/usr/lib/nls/msg/%L/%N
export LIBPATH=/usr/lib
export LANG=C
export _C89_CCMODE=1
export  _CC_CCMODE=1
export _CXX_CCMODE=1
export _C89_CVERSION="0x220A0000"
export  _CC_CVERSION="0x220A0000"
export _CXX_CVERSION="0x220A0000"
export _C89_PVERSION="0x220A0000"
export  _CC_PVERSION="0x220A0000"
export _CXX_PVERSION="0x220A0000"
export _C89_CLIB_PREFIX="SYS1.OSV2R10"
export  _CC_CLIB_PREFIX="SYS1.OSV2R10"
export _CXX_CLIB_PREFIX="SYS1.OSV2R10"

umask 022
PATH=/c390/build/bin:/usr/local/bin:/usr/sbin:/usr/share/lib/terminfo:/etc:/tools:.:$PATH

#
# Zip/Unzip
#
PATH=/c390/build/bin:$PATH

#
# Java
#
PATH=$HOME/$RELEASE/depends/java/bin:$PATH

#
# GNU make
#
PATH=$HOME/$RELEASE/depends/make:$PATH

export PATH

XERCESC_HOME=$HOME/$RELEASE/depends/xercesc
export XERCESC_HOME


-------------------
To test standalone:
-------------------

export PATH=/usr/lpp/java/IBM/J1.4/bin:$PATH
export LIBPATH=/home/testcup/apratt/rac/plugins/com.ibm.rational.pd.probekit/lib:$LIBPATH
java -XrunpiAgent:server=standalone,extensionLibrary=ProbeAgentExtension.so,ext-pk-BCILibraryName=BCIEngProbe.so,ext-pk-logLevel=finest,ext-pk-logFile=stderr,ext-pk-probescript=scr j
