Terminal sample (#6)

ian-burnett · web-flow · commit f443fddda6c5 · 2016-12-24T15:47:25.000Z
* Initial drop.

* Add of CSD definitions.

* Update of README for terminal sample.

* Code clean.
diff --git a/README.md b/README.md
@@ -26,6 +26,10 @@ Java source code for the following classes is provided in the corresponding Ecli
 performing all of the codepage conversion manually. This avoids the pre-req of CICS TS V5.1, but is slightly more work to code in Java.
 * TDQExample3 - A more complex example that writes structured records to a TDQ and then reads them back.
 
+### Project com.ibm.cicsdev.terminal
+
+* TerminalExample1 - A simple class to demonstrate receiving arguments from a terminal in a JCICS environment.
+
 
 ### Project com.ibm.cicsdev.tsq
 
@@ -56,6 +60,8 @@ The following Eclipse CICS bundle projects are provided to support deployment of
 * Project com.ibm.cicsdev.serialize.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.serialize sample
 * Project com.ibm.cicsdev.tdq.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.tdq samples
 * Project com.ibm.cicsdev.tdq.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.tdq sample
+* Project com.ibm.cicsdev.terminal.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.terminal sample
+* Project com.ibm.cicsdev.terminal.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.terminal sample
 * Project com.ibm.cicsdev.tsq.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.tsq samples
 * Project com.ibm.cicsdev.tsq.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.tsq sample
 * Project com.ibm.cicsdev.vsam.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.vsam samples
diff --git a/etc/Terminal/DFHCSD.txt b/etc/Terminal/DFHCSD.txt
@@ -0,0 +1,15 @@
+
+ DEFINE PROGRAM(JAVATRM1) GROUP(JCICSAMP)
+        DESCRIPTION(Java terminal sample)
+        CONCURRENCY(REQUIRED) API(CICSAPI) DYNAMIC(NO)
+        JVM(YES) JVMSERVER(DFHJVMS) DATALOCATION(ANY)
+        JVMCLASS(com.ibm.cicsdev.terminal.TerminalExample1)
+
+ DEFINE TRANSACTION(JTM1) GROUP(JCICSAMP) PROGRAM(JAVATRM1)
+        DESCRIPTION(Java terminal sample)
+        TASKDATALOC(ANY)
+
+ DEFINE BUNDLE(JCICTERM) GROUP(JCICSAMP)
+        DESCRIPTION(JCICS terminal sample)
+        BUNDLEDIR(/u/cics1/com.ibm.cicsdev.terminal.cicsbundle_1.0.0)
+
diff --git a/projects/com.ibm.cicsdev.terminal.cicsbundle/.project b/projects/com.ibm.cicsdev.terminal.cicsbundle/.project
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>com.ibm.cicsdev.terminal.cicsbundle</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>com.ibm.cics.bundle.ui.bundlebuilder</name>
+			<arguments>
+				<dictionary>
+					<key>bundleID</key>
+				</dictionary>
+				<dictionary>
+					<key>majorVersion</key>
+				</dictionary>
+				<dictionary>
+					<key>microVersion</key>
+				</dictionary>
+				<dictionary>
+					<key>minorVersion</key>
+				</dictionary>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>com.ibm.cics.bundle.ui.bundlenature</nature>
+	</natures>
+</projectDescription>
diff --git a/projects/com.ibm.cicsdev.terminal.cicsbundle/.settings/org.eclipse.core.resources.prefs b/projects/com.ibm.cicsdev.terminal.cicsbundle/.settings/org.eclipse.core.resources.prefs
@@ -0,0 +1,3 @@
+eclipse.preferences.version=1
+encoding//META-INF/cics.xml=UTF-8
+encoding/com.ibm.cicsdev.terminal.osgibundle=UTF-8
diff --git a/projects/com.ibm.cicsdev.terminal.cicsbundle/META-INF/cics.xml b/projects/com.ibm.cicsdev.terminal.cicsbundle/META-INF/cics.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<manifest xmlns="http://www.ibm.com/xmlns/prod/cics/bundle" id="com.ibm.cicsdev.terminal.cicsbundle" bundleMajorVer="1" bundleMinorVer="0" bundleMicroVer="0" bundleVersion="1" bundleRelease="0" build="IntB-201511072132">
+    <meta_directives>
+        <timestamp>2016-11-04T15:15:33.327Z</timestamp>
+    </meta_directives>
+    <import name="DFHJVMS" type="http://www.ibm.com/xmlns/prod/cics/bundle/JVMSERVER" optional="false" warn="false"/>
+    <define name="com.ibm.cicsdev.terminal" type="http://www.ibm.com/xmlns/prod/cics/bundle/OSGIBUNDLE" path="com.ibm.cicsdev.terminal.osgibundle"/>
+</manifest>
diff --git a/projects/com.ibm.cicsdev.terminal.cicsbundle/com.ibm.cicsdev.terminal.osgibundle b/projects/com.ibm.cicsdev.terminal.cicsbundle/com.ibm.cicsdev.terminal.osgibundle
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<osgibundle symbolicname="com.ibm.cicsdev.terminal" version="1.0.0" jvmserver="DFHJVMS"/>
diff --git a/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/.project b/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/.project
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>com.ibm.cicsdev.terminal.resources.cicsbundle</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>com.ibm.cics.bundle.ui.bundlebuilder</name>
+			<arguments>
+				<dictionary>
+					<key>bundleID</key>
+					<value>com.ibm.cicsdev.terminal.resources.cicsbundle</value>
+				</dictionary>
+				<dictionary>
+					<key>majorVersion</key>
+					<value>1</value>
+				</dictionary>
+				<dictionary>
+					<key>microVersion</key>
+					<value>0</value>
+				</dictionary>
+				<dictionary>
+					<key>minorVersion</key>
+					<value>0</value>
+				</dictionary>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>com.ibm.cics.bundle.ui.bundlenature</nature>
+	</natures>
+</projectDescription>
diff --git a/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/.settings/org.eclipse.core.resources.prefs b/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/.settings/org.eclipse.core.resources.prefs
@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+encoding//META-INF/cics.xml=UTF-8
diff --git a/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/JAVATRM1.program b/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/JAVATRM1.program
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><cicsdefinitionprogram xmlns="http://www.ibm.com/xmlns/prod/CICS/smw2int" concurrency="REQUIRED" datalocation="ANY" description="Java terminal sample" execkey="CICS" jvm="YES" jvmclass="com.ibm.cicsdev.terminal.TerminalExample1" jvmserver="DFHJVMS" name="JAVATRM1"/>
diff --git a/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/JTM1.transaction b/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/JTM1.transaction
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><cicsdefinitiontransaction xmlns="http://www.ibm.com/xmlns/prod/CICS/smw2int" description="Java terminal sample" localq="N_A" name="JTM1" program="JAVATRM1" taskdataloc="ANY"/>
diff --git a/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/META-INF/cics.xml b/projects/com.ibm.cicsdev.terminal.resources.cicsbundle/META-INF/cics.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<manifest xmlns="http://www.ibm.com/xmlns/prod/cics/bundle" id="com.ibm.cicsdev.terminal.resources.cicsbundle" bundleMajorVer="1" bundleMinorVer="0" bundleMicroVer="0" bundleVersion="1" bundleRelease="0" build="IntB-201511072132">
+    <meta_directives>
+        <timestamp>2016-11-11T11:05:46.741Z</timestamp>
+    </meta_directives>
+    <define name="JAVATRM1" type="http://www.ibm.com/xmlns/prod/cics/bundle/PROGRAM" path="JAVATRM1.program"/>
+    <define name="JTM1" type="http://www.ibm.com/xmlns/prod/cics/bundle/TRANSACTION" path="JTM1.transaction"/>
+</manifest>
diff --git a/projects/com.ibm.cicsdev.terminal/.classpath b/projects/com.ibm.cicsdev.terminal/.classpath
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.7"/>
+	<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
+	<classpathentry kind="src" path="src"/>
+	<classpathentry kind="output" path="bin"/>
+</classpath>
diff --git a/projects/com.ibm.cicsdev.terminal/.gitignore b/projects/com.ibm.cicsdev.terminal/.gitignore
@@ -0,0 +1 @@
+/bin/
diff --git a/projects/com.ibm.cicsdev.terminal/.project b/projects/com.ibm.cicsdev.terminal/.project
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>com.ibm.cicsdev.terminal</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.ManifestBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.SchemaBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>com.ibm.cics.explorer.sdk.CICSJavaOSGiBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.pde.PluginNature</nature>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+	</natures>
+</projectDescription>
diff --git a/projects/com.ibm.cicsdev.terminal/META-INF/MANIFEST.MF b/projects/com.ibm.cicsdev.terminal/META-INF/MANIFEST.MF
@@ -0,0 +1,11 @@
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: Sample JCICS terminal code
+Bundle-SymbolicName: com.ibm.cicsdev.terminal
+Bundle-Version: 1.0.0
+Bundle-Vendor: IBM
+Bundle-RequiredExecutionEnvironment: JavaSE-1.7
+CICS-MainClass: com.ibm.cicsdev.terminal.TerminalExample1
+Import-Package: com.ibm.cics.server;version="[1.401.0,2.0.0)"
+Bundle-ClassPath: .
+
diff --git a/projects/com.ibm.cicsdev.terminal/build.properties b/projects/com.ibm.cicsdev.terminal/build.properties
@@ -0,0 +1,4 @@
+source.. = src/
+output.. = bin/
+bin.includes = META-INF/,\
+               .
diff --git a/projects/com.ibm.cicsdev.terminal/src/com/ibm/cicsdev/terminal/TerminalExample1.java b/projects/com.ibm.cicsdev.terminal/src/com/ibm/cicsdev/terminal/TerminalExample1.java
@@ -0,0 +1,116 @@
+package com.ibm.cicsdev.terminal;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.StringTokenizer;
+
+import com.ibm.cics.server.CicsConditionException;
+import com.ibm.cics.server.DataHolder;
+import com.ibm.cics.server.EndOfChainIndicatorException;
+import com.ibm.cics.server.Task;
+import com.ibm.cics.server.TerminalPrincipalFacility;
+
+/**
+ * Provides an example of receiving arguments to a transaction at a 3270 terminal.
+ */
+public class TerminalExample1
+{
+    /**
+     * Main entry point to a CICS OSGi program.
+     */
+    public static void main(String[] args) throws CicsConditionException
+    {
+        // Get details about our current CICS task
+        Task task = Task.getTask();
+
+        // Retrieve the raw string from the terminal
+        // This will need to be issued before we write anything out
+        String strTerm = getTerminalString();
+
+        // Now we can report status to the terminal
+        task.out.println(" - Starting TerminalExample1");
+
+        // Do we have terminal arguments?
+        if (strTerm != null) {
+
+            // Parse to individual elements
+            String[] termArgs = parseTerminalString(strTerm);
+
+            // Display arguments
+            for (int i = 0; i < termArgs.length; i++) {
+                task.out.println( String.format("Arg %d : %s", i, termArgs[i]) );
+            }
+        }
+        
+        // Completion message
+        task.out.println("Completed TerminalExample1");        
+    }
+
+    /**
+     * Verifies the current task is associated with a terminal and then
+     * receives the input data. The received data is converted to a Java
+     * string and returned.
+     * 
+     * @return a String containing the data input at the terminal. If the
+     * transaction's principal facility is not a terminal, then <code>null</code>
+     * will be returned.
+     */
+    private static String getTerminalString() throws CicsConditionException
+    {
+        // Get the current task's principal facility
+        Object pf = Task.getTask().getPrincipalFacility();
+        
+        // Are we of a suitable type?
+        if ( pf instanceof TerminalPrincipalFacility ) {
+
+            // Cast to correct type
+            TerminalPrincipalFacility tpf = (TerminalPrincipalFacility) pf;
+            
+            // Create a holder object to store the data
+            DataHolder holder = new DataHolder();
+            
+            try {
+                // Perform the receive from the terminal
+                tpf.receive(holder);               
+            }
+            catch (EndOfChainIndicatorException e) {
+                // Normal operation - ignore this one
+            }
+            catch (CicsConditionException cce) {
+                // Propagate all other problems
+                throw cce;
+            }
+            
+            // Convert the received data into a valid String
+            // Assume this is a valid character string in the CICS local CCSID 
+            // Requires CICS TS V5.1 and later (JCICS 1.401.0)            
+            return holder.getStringValue();
+        }
+        else {
+            // Not a terminal principal facility
+            return null;
+        }
+    }
+
+    /**
+     * Breaks down the input string into 
+     * @param strTerm
+     * @return
+     */
+    private static String[] parseTerminalString(String strTerm)
+    {
+        // A place to store the output collection
+        List<String> args = new ArrayList<>();
+        
+        // Tokenize the input string using standard whitespace characters
+        StringTokenizer tok = new StringTokenizer(strTerm);
+        
+        // Add each of the tokens to the output collection
+        while ( tok.hasMoreTokens() ) {
+            args.add(tok.nextToken());
+        }
+        
+        // Convert the collection to an array
+        return args.toArray( new String[args.size()] );
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+eclipse.preferences.version=1`
	`2`	`+encoding//META-INF/cics.xml=UTF-8`
	`3`	`+encoding/com.ibm.cicsdev.terminal.osgibundle=UTF-8`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`
	`2`	`+<osgibundle symbolicname="com.ibm.cicsdev.terminal" version="1.0.0" jvmserver="DFHJVMS"/>`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+<?xml version="1.0" encoding="UTF-8"?><cicsdefinitionprogram xmlns="http://www.ibm.com/xmlns/prod/CICS/smw2int" concurrency="REQUIRED" datalocation="ANY" description="Java terminal sample" execkey="CICS" jvm="YES" jvmclass="com.ibm.cicsdev.terminal.TerminalExample1" jvmserver="DFHJVMS" name="JAVATRM1"/>`