SLAC ESD Software Engineering
Group
|
||||||||||
|
|
|
This page provides documentation for programmers developing the AIDA "SLC" peer, that is, it concentrates on AIDA on VMS, in the MCC HP Alpha cluster. AIDA's SLC peer contains Data Providers for the SLAC Control System (SLC), specifically the SLC DB, SLC History, SLC Model, SLC BPM, SLC Magnet, SLC Multiknob, and SLC Master Oscillator.
See Also: REF_AIDASHR;
Contents: Where's the code? Architecture Error
Handling Development Guide Name
Update
Here is described the process of getting, compiling, testing and releasing Aida SLC Data Provider code on the MCC/MCCDEV Alpha cluster. Since this implementation uses Java and JNI on OpenVMS, you might want to peruse HP's FAQ and the OpenVMS Java Documentation for the installed version (do $ java -version) before beginning. See A Brief Introduction to the Java Native Interface or the JNI FAQ from Sun for a summary on how to use javah and the JNI in general. There also is an Aida special page describing OpenVMS specific information for using JNI.
The primary source code repository for the SLC data providers (dpSlc*), is in CMS_AIDASHR on OpenVMS (reference dir REF_AIDASHR). java source code from REF_AIDASHR is compiled to AIDASHR.JAR. The native executable code from REF_AIDASHR is, as you'd expect, compiled into shareable image AIDASHR.EXE. So, in general, java code in AIDASHR.JAR uses native code in AIDASHR.EXE. The native code in AIDASHR.EXE calls routines in other shareables to get data in the usual way. Additionally, the AIDA.JAR file from Unix contains part of each of the SLC data providers (! - see below for more), plus the non-data-provider related parts of Aida.To understand this distribution of code we need to look at the architecture of an AIDA data Provider.
AIDA Data Providers are CORBA servers. As such, they are composed of client side and server side files, plus helper files which can be used on both sides. A CORBA IDL compiler generates both sides (all of the client side and almost all of the server side).
The client-side files are used by callers of the server - they comprise the server's callable interface and code which implements the CORBA network for the remote method invocation.
The server-side is also composed of code which implements the CORBA
remote method invocation, plus 2 files the IDL compiler can't write for
you:
The other 6 files that make up a data provider are entirely written by IDL, and never changed by a programmer directly. These are for instance: DpSlcModelIOperations, DpSlcModelI (see Table 1, it's all the files in AIDA.JAR), Call those 6 the "CORBA support files".
Now, our IDL compiler (jidl in fact, since most of AIDA is java), is only available on the AFS Unix hosts. It is in fact a Solaris executable (at the time of writing we use the Orbacus CORBA implementation, and there is no java executable for their java jidl compiler!). Therefore, we have to generate the CORBA support files - those used on both client and server - on Unix. This is true even for VMS based Aida data providers. However, since those files hardly ever change, we don't find that we have to transport them over to VMS often. In fact we keep the CORBA support files for all the data providers, those which are Unix based like DpCa, and those which are SLC based, like DpSlc, both in aida.jar, which is generated on Unix and shipped over to VMS only when a change which is material to a VMS data provider has been made.
Note then this subtle but important point: the CORBA support files for a VMS CORBA server, which you never change, are in aida.jar, which is generated on Unix and sometimes ftped to VMS. Where then are the 2 files we do change - the DpSlc<providername>_impl.java, and DpSlc<providername>Server.java? Answer: they're in REF_AIDASHR, and deployed in SLCIMAGE:AIDASHR.JAR. So the single java package of a given SLC Data Provider, like edu.stanford.slac.aida.dp.dpSlcModel, is spread over 2 .jar files, AIDA.JAR which contains the support files, and AIDASHR.JAR, which contains the files a programmer will change.
The CMS library CMS_AIDASHR (REF_AIDASHR) need contain only the 2 files a programmer changes (DpSlc<providername>_impl.java/cpp, and DpSlc<providername>Server.java/cpp), that go into AIDASHR.JAR if they're java, as they all are now, or AIDASHR.EXE if implemented in C. Additionally, it contains the C code for the shareable image AIDASHR, which implements the JNI interface (described below). AIDA.JAR is FTPed from from Unix and isn't changed on VMS. There are additionally 3 DCL files for each data provider, kept in SLCCOM (see Table 1)
AIDA.JAR contains all the core of Aida, like DaValue, DaObject. As described above, it also contains the CORBA IDL output files of some ofthe VMS based data providers, specifically dpslcHist, Model, and Bpm.
This is done on unix, at the time of writing, Solaris AFS. Do this is a local development directory, not production, because you have to create a java 1.4 version of class files. Be careful not to recompile production.
source $CD_SOFT/dev/script/ENVS.csh source $CD_SOFT/dev/script/aidaSetEnvDev.csh dev ${HOME}/cdsoft/aida/package/aida setenv JAVAVER 1.4.2 delpath CLASSPATH $AIDAROOT
delpath this necessary to make sure we don't try to compile local development java AIDA source using 1.4.2 against the 1.5 AIDA in $CD_SOFT/ref/aida/package/aida. This is what causes compile error "class file has wrong version 49.0, should be 48.0"
aidamake ACTION=clean aidamake vms
The gives version of aida.jar, that contains only the infrastructure and client side (not DPs), compiled in java 1.4.2, that includes the specific dpSlc IDL output needed in aida.jar. It's delivered as lib/aidaforvms.jar
After it's changed, it should be FTPed from CD_SOFT Unix to SLCIMAGE on VMS:
On Unix: $CD_SOFT/ref/package/aida/lib/aida.jar
On VMS: SLCIMAGE:AIDA.JAR
The Secure FTP command is of the form mu scp2 "
After the file is FTPed, we have to change its file attributes
before it'll work:
set file/attr=(RFM:STMLF,RAT:CR) aida.jar
Table 1: All files comprising a single example AIDA VMS Data Provider, the SLC Model DP.
File | Purpose | Repository | Deployed to |
DPSLCMODELSERVER.JAVA | Contains the "main" - the CORBA server setup and deployment. | CMS_AIDASHR | AIDASHR.JAR |
DPSLCMODELI_IMPL.JAVA | Principal server-side code. Defines behavior of server by calling routines in DPSLCMODEL_JNI.C | CMS_AIDASHR | AIDASHR.JAR |
DPSLCMODEL_JNI.C | Translates arguments in java strings to c strings, calls routines in DPSLCMODEL_JNI_HELPER.C to get data, and converts SLC errors to java exceptions. | CMS_AIDASHR | AIDASHR.EXE |
DPSLCMODEL_JNI_HELPER.C | Defines the "standalone_init" and calls existing SLC control system functions like model_get() to get data. | CMS_AIDASHR | AIDASHR.EXE |
EDU_STANFORD_SLAC_AIDA -_DP_DPSLCMODEL_DP.H | Defines JNI signatures for routines in DPSLCMODEL_JNI.C. Generated by javah from DPSLCMODELI_IMPL.CLASS | CMS_C_INC | AIDASHR.EXE |
DpSlcModelIOperations.class | Server interface definition | not in a repository | AIDA.JAR |
DpSlcModelI.class | Server interface declaration | not in a repository | AIDA.JAR |
_DpSlcModelIStub.class | What clients call client side | not in a repository | AIDA.JAR |
DpSlcModelIHolder.class | Streaming to an from Any help routines | not in a repository | AIDA.JAR |
DpSlcModelIHelper.class | Streamed DpSlcModel object | not in a repository | AIDA.JAR |
DpSlcModelIPOA.class | POA (CORBA orb) implementation. | not in a repository | AIDA.JAR |
MAKEFILE_DPSLCMODEL.COM | Makes AIDASHR.JAR and, if nec. AIDASHR.EXE | CMS_SLCCOM_GEN | SLCCOM: |
STARTDPSLCMODEL.COM | Runs the executable server | CMS_SLCCOM_GEN | SLCCOM: |
AIDA_DPSLCMODEL.SUBMIT | Called by warmslcx to setup batch process and run the server | CMS_SLCCOM_GEN | SLCCOM: |
There are additionally some files for maintaining AIDASHR.EXE in SLCSHR_CONTROL. The most important of these is AIDASHR_XFR_ALPHA.OPT which contains the transfer vectors for the JNI interface routines. For the SLC Model Dp, the native routines called by java through the JNI are defined in DPSLCMODEL_JNI.C.
At present, all the SLC Data Providers CORBA server side are implemented in Java, but call native code in shareables of the SLC controls system. They use the Java Native Interface (JNI) to make this connection. Taking the SLC Model data provider as an example, DPSLCMODELI_IMPL.JAVA is where your java code goes. Methods there call routines in DPSLCMODEL_JNI.C through JNI. DPSLCMODEL_JNI.C includes "edu_stanford_slac_aida_dp_dpslcmodel_dp.h", which is generated by javah against the DPSLCMODELI_IMPL.CLASS class file. This .H file is also in CMS_C_INC and is thus in the SLCTXT path. You must regenerate it when you add new JNI calls from Java to C. Look in SLCCOM:MAKEFILE_DPSLCMODEL.COM to see how it's generated.
Now DPSLCMODLEL_JNI.C must be compiled with a specific set of
options
for the JNI requirements. The **ATTRIBUTES**=JNI statement tells cmp
how to do this (thanks Ed). This also means that we can use
Java<->JNI<->VMS for other things besides Aida. All SLC
entry names are really uppercase which is incompatible with Java's case
sensitivity so the real interface to the SLC shareables is in
DPSLCMODEL_JNI_HELPER.C. SLC routine references in DPSLCMODEL_JNI.C are
made as as uppercase externals to entries in DPSLCMODEL_JNI_HELPER.C
where the actual call into the SLC shareable is made.
I'm sure all that JNI verbiage left you flummoxed so are the JNI
relationships:
DPSLCMODEL_IMPL.JAVA -> javac -> DPSLCMODELI_IMPL.CLASS ->
javah -> EDU....H ->
included in -> DPSLCMODEL_JNI.C -> calls ->
DPSLCMODEL_JNI_HELPER.C -> both .c files ->
buildshr -> AIDASHR -> SLC shareables.
Error handling is done through the API of the class Err, defined in package edu.stanford.slac.err. That package is developed on unix in $CD_SOFT/ref/package/err. Its jar file should therefore be FTPed from Unix to VMS whenever it's changed:
On Unix: $CD_SOFT/ref/package/err/lib/err.jar
On VMS: SLCIMAGE:ERR.JAR
Most of the exceptions issued by Aida are defined in class Except, defined in package edu.stanford.slac.except.That package is developed on unix in $CD_SOFT/ref/package/except. Its jar file should therefore be FTPed from Unix to VMS whenever it's changed, for instance, whenever a new exception is added:
On Unix: $CD_SOFT/ref/package/except/lib/except.jar
On VMS: SLCIMAGE:EXCEPT.JAR
Whenever a JAR file is FTPed (in bin mode) from Unix to VMS, its
file attributes must be adjusted: set
file/attr=(RFM:STMLF,RAT:CR)
This section describes the implementation of the java CLASSPATH on the VMS cluster, and step by step instructions for programmers to compile, build and release an AIDA Data Provider on a VMS node.
The OpenVMS implementation of java provides a JAVA$CLASSPATH logical in addition to the standard CLASSPATH. See the Release Notes for a more complete discussion of the distinction. We use JAVA$CLASSPATH because it does search list and rooted directory translation (mostly) of OpenVMS logical names and you use file paths that look like OpenVMS rather than a psuedo-UNIX format as is required for CLASSPATH. There are also DCL string length limitations that JAVA$CLASSPATH helps you minimize. When you login to OpenVMS your JAVA$CLASSPATH looks something like this:
MCCDEV> sho log java$classpath
"JAVA$CLASSPATH" = "[]" (LNM$JOB_81A48CC0)
= "MYJAVA$CLASSPATH:"
= "SLCIMAGE:DPSLC.JAR"
= "SLCIMAGE:DPSLCHIST.JAR"
= "SLCIMAGE:AIDASHR.JAR"
= "SLCIMAGE:AIDA.JAR"
= "SLCIMAGE:ERR.JAR"
= "SLCIMAGE:EXCEPT.JAR"
= "JAVALIB:[FOREIGN]OBEVENT.JAR"
= "JAVALIB:[FOREIGN]CLASSES111.ZIP"
= "JAVALIB:[FOREIGN]OB.JAR"
There are several things to note. JAR files we write are in SLCIMAGE, therefore they can be promoted and backed out through the usual DEV/PROD/NEW hierarchy, and test versions can be used simply by redefining SLCIMAGE (see below). JAR files from outside are kept in JAVALIB:[FOREIGN]. JAVA$CLASSPATH also has your default directory as the first place to look.
A side note about our jar files, like DPSLC.JAR. It's possible to make a jar file that is executable from a java command e.g. java -jar a.jar but we didn't do this. Instead we just put the necessary files in the jar file and invoke the main class from the java command. Making DPSLC.JAR an executable might be an option assuming that all the OpenVMS logical name translation is done properly and it's sensible to run all data providers from a single executable jar file.
See instructions elsewhere for how to create a
completely new AIDA Data Server on VMS (that is, a new Data
Provider). This section describes the steps in cyclic development of an
existing data provider.
MCCDEV> lib/create aidashr_devlib
MCCDEV> define myjava$classpath [------] MCCDEV> javac -g *.java MCCDEV> cinc *.c
MCCDEV> cd [------] MCCDEV> javah -jni "edu.stanford.slac.aida.dp.dpSlcModel.DpSlcModelI_impl" MCCDEV> rename EDU_STANFORD_SLAC_AIDA_DP_DPSLCBMODEL_DPS.H [.edu.stanford.slac.aida.dp.dpSlcModel]dpslcmodel_jni.h MCCDEV> cd [.edu.stanford.slac.aida.dp.dpSlcModel]
This section describes the testing an SLC Data Provider prior to its release. This is really just a subset of the steps above in the development cycle (steps 4, 5 and 7 above).
First check that there is no data provider of the instance you want to test presently running on the node for which you want ot test it (MCCDEV for development or MCC for production):
Which AIDAPROD or AIDADEV are running (on MCC, MCCDEV respectively):
sho sys /process=AIDA_DP*
Which AIDALCLS are running (on MCC):
sho sys /process=AIDA*LCLS
If one is presently running in batch, kill it from slcshr with warmslcx aida_dpslcmodel /kill.
Make the appropriate logical definitions so that yout local test software is used:
Start yours manually with @SLCCOM:AIDA_DPSLCMODEL.SUBMIT or @SLCCOM:STARTDPSLCMODEL.
The SUBMIT file sets the right process name, so stops the SLC process
watchdog from complaining, but also runs userlogin which you may not want.
Either of these starts the server in your local process, not detached. You can
debug the shareable by doing Ctrl^Y debug and set image, module, break etc. in
the usual manner (see below). You can debug the java code by starting the server
with jdb instead of the java command.
Each Data Provider should have its own test suite, kept on unix in $CD_SOFT/ref/package/aida/test/[java]/. These follow a particular naming convention. To start the SLC Model data provider test suite, on unix:
source /afs/slac/g/cd/soft/dev/script/ENVS.csh
cmlog -u &
source $CD_SOFT/dev/script aidaSetEnvDev.csh dev
aidatest daDpSlcModelTest 1 2 3 4
In addition to the regualr testing procedure described above, the DpSlcModel Data Provider (only at present), includes a simple unit test - which avoids having to start an aida network. See the header of DPSLCMODEL_JNI_HELPER.C for details.
cms_slcshr_control
, add or change the entries for the server you're
creating or modifying from your local AIDASHR_XFR_ALPHA.OPT (the one you created with the scan_for_globals tool, and then check-in the resulting file.
slccms {create elem|replace} EDU_STANFORD_SLAC_AIDA_DP_DPSLCMODEL_DP.H or slccms {create elem|replace} DPSLCBPM_JNI.H if you used the -o DPSLCBPM_JNI.H option to javah.
MCCDEV> cmp *.c
MCCDEV> set h mccdev ! Log in as SLCSHRLogout of slcshr.
MCCDEV::SLCSHR> buildshr aidashr /same
> copy slcimage:aidashr.jar [] Make sure to copy the newest in the slcimage logical list! > jar uvf aidashr.jar - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/DpSlcBpmI_impl.class" - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/DpSlcBpmIPOA.class" - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/DpSlcBpmServer.class" - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/DpSlcBpmI.class" - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/DpSlcBpmIHelper.class" - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/DpSlcBpmIHolder.class" - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/DpSlcBpmIOperations.class" - "-C" [------] "edu/stanford/slac/aida/dp/dpSlcBpm/_DpSlcBpmIStub.class"Check your new jar file with jar t, to see what's in it after you finished:
> jar tf aidashr.jar
> define myjava$classpath "[]aidashr.jar" [if you have a new jar file] > testshrx aidashr [if you have a new shareable] Stop the MCCDEV version of the server from SLCSHR, then back in local account: > @slccom:startdpslcbpm
MCCDEV> slccms
SlcCMS> set lib cms_aidashr
%CMS-I-LIBIS, library is CMS_:[AIDASHR]
%CMS-S-LIBSET, library set
-CMS-I-SUPERSEDE, library list superseded
SlcCMS> create elem DPSLCMODELI_IMPL.JAVA "SLC Model Data Provider Implementatio
n file"
Replace this file without compiling? (Y,N) [N]: y
%CMS-S-CREATED, element CMS_:[AIDASHR]DPSLCMODELI_IMPL.JAVA created
SlcCMS> create elem DPSLCMODELSERVER.JAVA "SLC Model Data Provider Server"
Replace this file without compiling? (Y,N) [N]: y
%CMS-S-CREATED, element CMS_:[AIDASHR]DPSLCMODELSERVER.JAVA created
SlcCMS>
> slccms create elem dpslcbpm.conf
> copy COMMON$ROOT:[COM.GEN]AIDA_DPSLCMODEL.SUBMIT [] > renam AIDA_DPSLCMODEL.SUBMIT AIDA_DPSLCBPM.SUBMIT > slccms create elem AIDA_DPSLCBPM.SUBMIT "Add AIDA SLC BPM Data Provider"
unix> aidatest daDpSlcBpmTest 1
The SLC Data Provider has Service Id = 8 (aida_services.service_id).
The names for the SLC data provider come from Oracle schema NLCDEV, table secndx (SLACPROD instance). secndx is updated after a dbinstall by a VMS batch job called SLCCOM:slcdb2oracle.com, which uses cmdsrv to cal a unix script $CD_SOFT/prod/solaris/bin/run_pmu_load.sh. That script rebuilds the secndx table of all SLC names, used by Artemis, and then runs aidaPmuNames_update to update the aida schemas with teh changes to secndx.
call hierarchy: run_pmu_load.sh - builds secndx, and then calls ... -> aidaPmuNames_update - csh script that runs sqlplus on... - -> aidaPmuNames_update.sql - sql script that runs sql scripts below and then commits. - - -> aida_slcService_namesUpdate.sql - SLC db nams - - -> aida_slcModelService_namesUpdate.sql - SLC Model names
Author: Robert C. Sass,
10-Jan-2003
Modified by: Ron MacKenzie,
03-Jun-2004
Put more detail in Release steps 3 and 4. Greg White,
18-Nov-2004, Heavily
modified
for streamlined development scheme for SLC Data Providers