Installing git and getting our first Open Source Software

In the previous post I discussed the fact that we have two Open Source camps on the IBM i, I believe the easiest start into the community for many is going to be via the ILE camp. If this is the camp you want to start with, this post is hopefully going to show you how to install git and get the first software package onto your IBM i.

Important!
Before we go any further, if you have not bookmarked the IBM i Technology Updates site you should do that now! I would also suggest bookmarking https://bitbucket.org/ibmi/opensource/wiki/Home where you will find a plethora of useful information.

Background
The source code we will copy is a compilation of the API samples Carsten Flensburg produced for the IPro Developer magazine, he kindly agreed that we could use it for the Open Source community. Many of the samples are written in RPG/CLP and UIM, which show how to use the various API’s available to carry out various tasks. RPG free code is used in many so not only can you benefit from learning about the API you may also start to use the free format within your own programs.  We are going to implement a script to copy the source to Source Physical Files so that you can compile all of the sample code within PDM.

Installing the OSS Tools
First we need to install PASE and LPP 5733OPS which is a collection of Open Source tools for IBM i. IBM packaged 5733OPS in a way which seems to confuse a number of people, installing the LPP options does not install all of the tools. It installs some items and puts placeholders in for others. When IBM completes the build and test of a tool/function they will fill the placeholder with the code, apparently this makes the release of future options much faster as they ship as PTFs.

5733OPS
We decided to install all of the stubs even though we only need a few of them. In our opinion it is better to put all of the stubs in place for future options as they only take up minimal space and make future changes much easier. You will need 57xxSS1 Option 33 (PASE environment), 5733SC1 which provides the a number of tools and features relevant to the PASE environment  as well as the 5733OPS LPP. They are all available via ESS (Entitled Software Site) or if you have a recent shipment of CDs from IBM they could be there. (Note depending on when your order was fulfilled could influence the content shipped with 5733OPS).

PASE and OpenSSH/SSL
Install 57xxSS1 Option 33 if not already installed. Next install  5733SC1 Option 1 & 2 this will add OpenSSH/SSL. While we do not need SSH/SSL for this exercise we will probably need it later as SSL is required for connecting to https sites. There is no need to IPL the system after installing.

5733OPS stubs
You can just install the options we will need but I would recommend installing all 15! You will need at least Options 6,7 for the actions we will be carrying out.

5733OPS PTF’s
Once you have the options installed you need to install PTFs which add the functionality (remember this is how IBM ships new features/tools for 5733OPS). You can find a list of the latest PTFs available using the link provided above (Note this list changes as new features are added so the PTFs we installed may not be the latest). The ones we installed are SI63502 for git and SI63134  for curl functionality (not necessary but a surprisingly powerful tool that you will definitely gain benefit from sooner or later. 

Check we have git installed
We are now ready to move to the QP2TERM environment. On a command line issue the ‘call/qp2term’ command which will put you into the PASE environment. No need to know lots of AIX/Linux commands as we are going to spend as little time as possible in PASE. Once you are in PASE issue the following command. ‘git –version’ you should see output similar to the following (it could change as IBM updates the git install version).

git –version
git version 2.10.2
If you do not see the above go back and ensure you have all of the required options installed before going any further.

OK whats next
As mentioned above we are going to download the Carsten Flensburg API samples from a copy we have built on github in one of our repositories (eventually this will be moved to the  OSSILE repository when we have decide on the format to use). Use the following URL in a browser to see what is available.

https://github.com/ChrisHird

The GitHub repository we are going to use

You can drill down further into the information to see what is contained in the repository, at this point we are not going to explain how we built the content and what each of the files mean (we will do that later when we show how to contribute and maybe even set up your own repository) but take some time to drill down into the files.

It is important to understand that when we ‘clone’ the repository we are going to get a copy of all the files that you see under the code tab. Some of those files may be important later. (Note this repository is going to continue to grow as we have only added 100+ of the 400+ samples so far).

Lets get that Source
It only takes one command to pull all of those files to our IBM i, the ‘git clone’ command. No need to understand the mechanics behind the command at this stage, we will get to that later. On a command line issue the following command.

git clone https://github.com/ChrisHird/CF_API
Oops
You may get the following error because we are using the https url, this is a problem with curl that we are trying to resolve at this time.
Cloning into ‘CF_API’…
fatal: unable to access ‘https://github.com/ChrisHird/CF_API/’: SSL certificate problem: unable to get local issuer certificate

Fix it!
To work around this you have a couple of options, you can run the following command in QP2TERM which will add the sslVerify false setting to your .gitconfig file.

git config –global https.sslVerify false
Or you could use the git/ssh request such as ‘git clone git://github.com/ChrisHird/CF_API.git’, this will carry out the same process but use a different protocol.

Yeah! But where are the files
You should now have all of the files downloaded to the IFS (the location depends on your IBM i profile, if you have a home directory defined this is where you will find the files, otherwise it could be the location you ran the command from). While the IFS can be used as a source location for some commands IBM has yet to fully support the IFS for all compile commands, this means we need to copy at least some of the code from the IFS into Source Physical Files before compilation. 

PASE needs a script
We supplied a script called setup which will allow the build of individual samples from a OSSILE download. We are going to hack that to take individual samples and copy it to Source Files in a library of our choosing. One of the issues with PASE is the script files are sensitive to CLR and LF characters plus the CCSID of the file and content. There is no simple way around this so we are going to supply a copy for download. If you are confident you can create your own script file using the code below, even better amend it to meet any additional needs.

copysrc script
The following is an explanation of the content as we added it to our script file (~/CF_API/copysrc). The objective of the script is to copy the samples to the source file one at a time, as mentioned you could update the script to meet your needs such as compiling immediately after each copy) 

Which sample
The content of the repository is structured to allow a single example to be copied, there is a README.md file which has a list of all the samples which you should consult to identify which sample you are interested in. The script will require one parameter which is the last few digits of the directory name as defined in the README.md eg: 
* 100 - Sample of QDBRTVFD
This shows that the cbx100 directory content is a Sample of QDBRTVFD. Review the README.md file online if you find viewing it in QP2TERM difficult.

Script content, what does it do 

#!/QOpenSys/usr/bin/ksh
PWD=`pwd`
export PWD
export SRCLIB=OSSILESRC
if [ ! -e /qsys.lib/ossilesrc.lib ]; then
system “CRTLIB $SRCLIB”
fi
# need parameter to determine the build directory
if [ “$#” -eq 0 ]; then
print “No Arguments”
exit
fi
# the build name is the first parameter prepended with cbx
export BUILD=”cbx$1″
export WORKDIR=$(pwd)/$build 
Lines beginning with # are comments
Line(1) defines the shell ksh, you can change it to a different shell if you wish.
Lines(2-3) are assigning the working directory as the one where the script is run from and exporting it.
Line(4) is setting the Source Library as OSSILESRC and exporting it (you need to export a variable to be able to use it), you can change this to what ever you want as the source library.
Lines(5-7) are checking to ensure the source library exists, if it doesn’t we will create it.
Lines (9-12) we need to have at least one parameter passed in to define the directory (BUILD) we are going to copy across so if one is not available we will simply exit.
Line(14) is the source file definition, it is created by taking the first parameter passed to the script $1 (yes we are going to pass in parameters to the script, additional parameters will be $2, $n…) and prefixing it with cbx. 
Line(15) is assigning the working directory, this is the sub directory of CF_API where all of source content resides
system -kpieb “CRTSRCPF FILE($SRCLIB/$BUILD) RCDLEN(150)”
This is simply going to create the library and source files that we need to copy the source into
for FILE in “$WORKDIR”*
do
export FILENAME=$(echo ${FILE} | awk -F”/” ‘{print $NF}’)
export OBJ=$(echo $FILENAME | awk -F”\.” ‘{print $1}’)
export EXT=$(echo $FILENAME | awk -F”\.” ‘{print $2}’)
system -kpieb “ADDPFM FILE($SRCLIB/$BUILD) MBR($OBJ) SRCTYPE($EXT)”
system -kpieb “CPYFRMSTMF FROMSTMF(‘${FILE}’) TOMBR(‘/QSYS.LIB/$SRCLIB.LIB/$BUILD.FILE/$OBJ.MBR’) MBROPT(*REPLACE)”
done
The above is where all of the work gets done.
Line(1-2) we have a for – do loop , for each object we find in the directory, assign the name to the FILE variable and do the following 
Line(3-5) we extract the file name from the path and then split it into 2 parts Object and Extension
Line(6) we add the source file member
Line(7-8) we copy the source statements from the IFS file to the Source Physical File with *REPLACE for the member Option.
Line(9) is the end of the for loop.
 
How do I run the script
There is no need to compile the script, just ensure its installed in the CF_API directory created by the git download and executable (to make the script executable use chmod command) then run as follows.
./copysrc ’99a’
This will copy the content of ‘~/CF_API/cbx99a’ to a source file OSSILESRC/CBX99A. 

What should I see?
Here are a couple of screen shots of our results.





Wrap up!

That is it, you can now take what you have learned and download any OSSILE repository using similar techniques. The script file is probably the most challenging part because of the editor issues (we used vi in a putty based shell to create ours, not a simple exercise for begginers). However as promised, you can find a copy of the script at https://www.shieldadvanced.com/remote_supprt/copysrc, download it to your IBM i and copy to the CF_API directory. As mentioned above the script cannot be run until it is made executable  ‘chmod +x copysrc’.

Last Words..
Hope that you find the steps easy to follow, if you have any questions please feel free to contact me on Ryver where I will be happy to help resolve any issues you have. 

Happy coding!

Chris…