Skip to content

Commit 439525d

Browse files
ian-burnettian-burnett
authored
Readme updates (#7)
* Initial drop. * Add of CSD definitions. * Update of README for terminal sample. * Code clean. * Correction of README. * Restructure of README files. * Tidy of etc/README.md. * Document each folder. * Update of each etc folder README. * Update etc/README.md. * Corrected typos. * Update projects/README.md. * Individual README.md files for each Java project. * Remove unnecessary clutter in top-level README files. * More updates. * Try a relative link. * Move more down to project level descriptions. * Relative link on VSAM etc/ files. * Tidy of VSAM README. * Clean of top-level README. * Push all non-global content down to project level READMEs. * Clean of etc/README. * Push all project-specific detail down to lowest README level. * Tidying of low-level READMEs. * Correct copy & paste. * Ignore bin directories. * LINK README updates. * Tidy up of serialize sample README. * Tidy of TDQ README. * Update of terminal README. * Tidy of TSQ README. * Update of src/README. * Move Eclipse import instructions to projects folder.
1 parent f443fdd commit 439525d

File tree

16 files changed

+371
-109
lines changed

16 files changed

+371
-109
lines changed

‎README.md‎

Lines changed: 30 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -2,131 +2,50 @@ cics-java-jcics-samples
22
================
33
Sample CICS Java programs demonstrating how to use the JCICS API in an OSGi JVM server environment
44

5+
## Samples overview
56

6-
## Eclipse projects
7-
Java source code for the following classes is provided in the corresponding Eclipse plugin projects in the projects directory
7+
* [`com.ibm.cicsdev.link`](projects/com.ibm.cicsdev.link) - Performing CICS LINK operations using both commareas, and channels and containers.
8+
* [`com.ibm.cicsdev.serialize`](projects/com.ibm.cicsdev.serialize) - Serializing access to a common resource using the CICS ENQ and DEQ mechanism.
9+
* [`com.ibm.cicsdev.tdq`](projects/com.ibm.cicsdev.tdq) - Accessing transient data queues.
10+
* [`com.ibm.cicsdev.terminal`](projects/com.ibm.cicsdev.terminal) - Reading in data from a terminal for an OSGi application.
11+
* [`com.ibm.cicsdev.tsq`](projects/com.ibm.cicsdev.tsq) - Accessing temporary storage queues.
12+
* [`com.ibm.cicsdev.vsam`](projects/com.ibm.cicsdev.vsam) - Accessing KSDS, ESDS, and RRDS VSAM files.
813

9-
### Project com.ibm.cicsdev.link
1014

11-
* LinkProg1 - A class that demonstrates linking to the COBOL application EC01 using a COMMAREA
12-
* LinkProg2 - A class that demonstrates linking to the COBOL application EDUPGM using a COMMAREA mapped using a JZOS generated record
13-
* LinkProg3 - A class that demonstrates linking to COBOL application EDUCHAN using channels and containers
14-
* LinkProgCommon - Super class used to provide common service for the LinkProg samples
15-
* LinkServerEduchan - A Java version of the EDUCHAN COBOL program used as the back-end to LinkProg3
15+
## Repository structure
1616

17-
### Project com.ibm.cicsdev.serialize
17+
* [`etc/`](etc) - Supporting materials used to define CICS and z/OS resources needed for the samples.
18+
* [`projects/`](projects) - Complete Eclipse projects suitable for importing into a CICS Explorer environment.
19+
* [`src/`](src) - Supporting source code for non-Java programs.
1820

19-
* SerializeExample1 - A simple class to demonstrate using the CICS ENQ and DEQ mechanism from a JCICS environment.
2021

21-
### Project com.ibm.cicsdev.tdq
22+
## Pre-requisites
2223

23-
* TDQCommon - Super class used to provide common services for the TDQ samples
24-
* TDQExample1 - A simple class that writes Java strings to a TDQ and then reads them back.
25-
* TDQExample2 - An alternative implementation of TDQExample1 that writes and reads Java strings, but
26-
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.
27-
* TDQExample3 - A more complex example that writes structured records to a TDQ and then reads them back.
28-
29-
### Project com.ibm.cicsdev.terminal
30-
31-
* TerminalExample1 - A simple class to demonstrate receiving arguments from a terminal in a JCICS environment.
32-
33-
34-
### Project com.ibm.cicsdev.tsq
35-
36-
* TSQExample1 - A simple class that writes Java strings to a TSQ and then reads them back.
37-
* TSQExample2 - An alternative implementation of TSQExample1 that writes and reads Java strings, but performs all of the byte array to string conversion manually. This avoids the pre-req of CICS TS V5.1, but is slightly more
38-
work to code in Java.
39-
* TSQExample3 - A more complex example that uses a JZOS generated record to write a structured record to a TSQ and then read it back.
40-
* TSQExample4 - An extension of the TSQExample3 sample program, which populates a TSQ, updates items within the queue, then reads them back to confirm.
41-
* TSQCommon - Super class used to provide common services for the TSQ samples
42-
43-
### Project com.ibm.cicsdev.vsam
44-
45-
Provides examples for using VSAM files from a JCICS environment. All examples have a ESDS, KSDS, and RRDS variant. The numbered example classes are driving classes, with the ExampleCommon classes performing the JCICS calls.
46-
47-
* Example1 - Writes a single record to a file.
48-
* Example2 - Reads a single record from a file.
49-
* Example3 - Updates a single record in a file.
50-
* Example4 - Deletes a single record in a file (not ESDS).
51-
* Example5 - Browses a VSAM file.
52-
* ExampleCommon - Various routines that perform the various JCICS calls.
53-
54-
## CICS bundle projects
55-
The following Eclipse CICS bundle projects are provided to support deployment of the Java projects and the associated CICS resource definitions
56-
57-
* Project com.ibm.cicsdev.link.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.link Java samples
58-
* Project com.ibm.cicsdev.link.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.link sample
59-
* Project com.ibm.cicsdev.serialize.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.serialize samples
60-
* Project com.ibm.cicsdev.serialize.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.serialize sample
61-
* Project com.ibm.cicsdev.tdq.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.tdq samples
62-
* Project com.ibm.cicsdev.tdq.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.tdq sample
63-
* Project com.ibm.cicsdev.terminal.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.terminal sample
64-
* Project com.ibm.cicsdev.terminal.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.terminal sample
65-
* Project com.ibm.cicsdev.tsq.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.tsq samples
66-
* Project com.ibm.cicsdev.tsq.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.tsq sample
67-
* Project com.ibm.cicsdev.vsam.cicsbundle - CICS bundle project for deploying the com.ibm.cicsdev.vsam samples
68-
* Project com.ibm.cicsdev.vsam.resources.cicsbundle - CICS bundle project containing transaction and program definitions for the com.ibm.cicsdev.vsam sample
69-
70-
71-
## Supporting files
72-
* etc/Link/DFHCSD.txt - Output from a DFHCSDUP EXTRACT for the Link sample.
73-
* etc/TDQ/DFHCSD.txt - Output from a DFHCSDUP EXTRACT for the TSQ sample.
74-
* etc/TSQ/DFHCSD.txt - Output from a DFHCSDUP EXTRACT for the TDQ sample.
75-
* etc/VSAM/DFHCSD.txt - Output from a DFHCSDUP EXTRACT for the VSAM sample.
76-
* src/Cobol/EC01.cbl - Sample CICS COBOL application that returns the date and time in a COMMAREA.
77-
* src/Cobol/EDUCHAN.cbl - A sample CICS COBOL that returns the date and time and reversed input using channels and containers
78-
* EDUPGM.jar - A pre-built JAR containing the JZOS generated record that maps the copybook structure used in the EDUPGM COBOL sample. The generated class JZOSCommareaWrapperclass is used in the Link example 2 to map the fields in the COMMAREA used by the COBOL program EDUPGM.
79-
* TdqRecord.jar - A pre-built JAR containing the JZOS generated record that maps the copybook structure used in the TDQExample3.
80-
* TsqRecord.jar - A pre-built JAR containing the JZOS generated record that maps the copybook structure used in the TSQExample3.
81-
* vsam.jar - A pre-built JAR containing the JZOS generated record that maps the copybook structure used in all the VSAM samples.
82-
83-
84-
## Pre-reqs
85-
86-
* CICS TS V5.1 or later, due to the usage of the getString() methods.
87-
* Java SE 1.7 or later on the z/OS system
88-
* Java SE 1.7 or later on the workstation
89-
* Eclipse with CICS Explorer SDK installed
90-
91-
24+
* CICS TS V5.1 or later, due to the usage of the `getString()` methods.
25+
* Java SE 7 or later on the z/OS system.
26+
* Java SE 7 or later on the workstation.
27+
* Eclipse with CICS Explorer SDK installed.
28+
9229

9330
## Configuration
9431

9532
The sample Java classes are designed to be added to an OSGi bundle and deployed into a CICS OSGi JVM server, but can also be used as the basis for extending Web applications deployed into a Liberty JVM server.
9633

97-
### To add the resources to Eclipse:
98-
1. Using an Eclipse development environment import the project from the project folder using the menu File -> Import -> Existing Projects into Workspace
99-
1. Define and set a CICS Target Platform for the workspace using the menu Windows -> Preferences -> Target Platform
100-
101-
102-
### To start a JVM server in CICS:
103-
1. Enable Java support in the CICS region by adding the SDFJAUTH library to the STEPLIB concatenation and setting USSHOME and the JVMPROFILE SIT parameters.
104-
1. Define an OSGi JVM server called DFHJVMS using the CICS supplied sample definition in the CSD group DFH$OSGI
105-
1. Copy the CICS supplied DFHOSGI.jvmprofile zFS file to the zFS directory specified above and ensure the JAVA_HOME variable is set correctly.
106-
1. Install the DFHJVMS resource defined in step 2 and ensure it becomes enabled.
107-
108-
### To deploy the samples into a CICS region
109-
1. Using the CICS Explorer export the Java projects com.ibm.cicsdev.link.cicsbundle, com.ibm.cicsdev.tsq.cicsbundle and com.ibm.cicsdev.tdq.cicsbundle to a zFS directory. The sample definitions use the following style of zFS location /u/cics1/com.ibm.cicsdev.link.cicsbundle_1.0.0
110-
1. Define and install CICS BUNDLE resource defintions referring to the deployed bundle directory in step 1. and ensure all resources are enabled.
111-
1. Create the require transaction and program definitions using either the supplied DFHCSD.txt files as input to a CSD define job or using the CICS bundle projects
112-
com.ibm.cicsdev.link.resources.cicsbundle, com.ibm.cicsdev.tsq.resources.cicsbundle, com.ibm.cicsdev.tdq.resources.cicsbuncdle
113-
1. If using the TDQ sample define an intra-partition TDQ called MYQ1
114-
1. If using the LINK sample compile and deploy the COBOL programs EC01 and EDUCHAN, and either define PROGRAM definitions or enable program autoinstall.
115-
1. Optionally add a CICS Java program definiton for LinkServerEduchan called EDUCHAN if you wish to replace the EDUCHAN COBOL sample with the Java implemenation.
116-
11734

118-
### Running the Example
35+
### Starting a JVM server in CICS
11936

37+
1. Enable Java support in the CICS region by adding the `SDFJAUTH` library to the `STEPLIB` concatenation and setting `USSHOME` and the `JVMPROFILE` SIT parameters.
38+
1. Define an OSGi JVM server called `DFHJVMS` using the CICS-supplied sample definition in the CSD group `DFH$OSGI`.
39+
1. Copy the CICS supplied `DFHOSGI.jvmprofile` zFS file to the zFS directory specified by the `JVMPROFILE` SIT parameter, and ensure the `JAVA_HOME` variable is set correctly.
40+
1. Install the `DFHJVMS` resource defined in step 2 and ensure it becomes enabled.
12041

121-
At a 3270 terminal screen, enter the transaction you wish to run, for example JLN1 will run the Link example 1.
122-
123-
JLN1
124-
125-
and the following output will be returned
126-
127-
JLN1 - Starting LinkProg1
128-
Returned from link to EC01 with 19/08/16 09:17:01
12942

43+
### To deploy the samples into a CICS region
44+
1. Using the CICS Explorer export the `com.ibm.cicsdev.*.cicsbundle` projects to a zFS directory. The sample definitions use the following style of zFS location `/u/cics1/com.ibm.cicsdev.link.cicsbundle_1.0.0`.
45+
1. Define and install CICS `BUNDLE` resource defintions referring to the deployed bundle directory in step 1, and ensure all resources are enabled.
46+
1. Create the required transaction and program definitions using either the supplied `DFHCSD.txt` files as input to a CSD define job, or using the supplied CICS bundle projects.
47+
1. See the individual project directories for any additional supporting resources required.
48+
13049

13150
## License
13251
This project is licensed under [Apache License Version 2.0](LICENSE).
@@ -136,3 +55,5 @@ This project is licensed under [Apache License Version 2.0](LICENSE).
13655

13756
* For further details on using the IBM JZOS record generator see this [developer center article] (https://developer.ibm.com/cics/2016/05/12/java-cics-using-ibmjzos/)
13857
* For details on how to define a CICS OSGi JVM server refer to the Knowledge Center topic [Configuring an OSGi JVM server] (http://www.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.java.doc/JVMserver/config_jvmserver_app.html)
58+
59+

‎etc/Link/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Supporting materials used in conjunction with the JCICS LINK samples.
2+
3+
* DFHCSD.txt - Output from a DFHCSDUP EXTRACT operation to define the programs and transactions required.
4+

‎etc/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
etc
2+
===
3+
Supporting materials used in conjunction with the JCICS samples. Each folder provides supporting materials for the following projects:
4+
5+
* [Link](Link) - com.ibm.cicsdev.link
6+
* [Serialize](Serialize) - com.ibm.cicsdev.serialize
7+
* [TDQ](TDQ) - com.ibm.cicsdev.tdq
8+
* [TSQ](TSQ) - com.ibm.cicsdev.tsq
9+
* [Terminal](Terminal) - com.ibm.cicsdev.terminal
10+
* [VSAM](VSAM) - com.ibm.cicsdev.vsam
11+

‎etc/Serialize/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Supporting materials used in conjunction with the JCICS serialization samples.
2+
3+
* DFHCSD.txt - Output from a DFHCSDUP EXTRACT operation to define the programs and transactions required.
4+

‎etc/TDQ/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Supporting materials used in conjunction with the JCICS TDQ samples.
2+
3+
* DFHCSD.txt - Output from a DFHCSDUP EXTRACT operation to define the programs and transactions required.
4+

‎etc/TSQ/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Supporting materials used in conjunction with the JCICS TSQ samples.
2+
3+
* DFHCSD.txt - Output from a DFHCSDUP EXTRACT operation to define the programs and transactions required.
4+

‎etc/Terminal/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Supporting materials used in conjunction with the JCICS terminal samples.
2+
3+
* DFHCSD.txt - Output from a DFHCSDUP EXTRACT operation to define the programs and transactions required.
4+

‎etc/VSAM/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Supporting materials used in conjunction with the JCICS VSAM samples.
2+
3+
* DEFVSAM.jcl - Sample job to define the KSDS, ESDS, and RRDS VSAM files required.
4+
* DFHCSD.txt - Output from a DFHCSDUP EXTRACT operation to define the programs and transactions required.
5+

‎projects/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
projects
2+
===
3+
4+
Complete Eclipse projects demonstrating how to use the JCICS API in an OSGi JVM server environment.
5+
6+
7+
## Overall project structure
8+
9+
* `com.ibm.cicsdev.*` - Eclipse project containing the Java source code.
10+
* `com.ibm.cicsdev.*.cicsbundle` - Eclipse project for a CICS bundle that can be deployed into a CICS region.
11+
* `com.ibm.cicsdev.*.resources.cicsbundle` - Eclipse project for a CICS bundle that defines the required program and transaction resources for the sample.
12+
13+
14+
## Samples overview
15+
16+
* [`com.ibm.cicsdev.link`](com.ibm.cicsdev.link) - Performing CICS LINK operations using both commareas, and channels and containers.
17+
* [`com.ibm.cicsdev.serialize`](com.ibm.cicsdev.serialize) - Serializing access to a common resource using the CICS ENQ and DEQ mechanism.
18+
* [`com.ibm.cicsdev.tdq`](com.ibm.cicsdev.tdq) - Accessing transient data queues.
19+
* [`com.ibm.cicsdev.terminal`](com.ibm.cicsdev.terminal) - Reading in data from a terminal for an OSGi application.
20+
* [`com.ibm.cicsdev.tsq`](com.ibm.cicsdev.tsq) - Accessing temporary storage queues.
21+
* [`com.ibm.cicsdev.vsam`](com.ibm.cicsdev.vsam) - Accessing KSDS, ESDS, and RRDS VSAM files.
22+
23+
24+
## Adding the resources to Eclipse
25+
26+
1. Using an Eclipse development environment import the project from the project folder using the menu File -> Import -> Existing Projects into Workspace.
27+
1. Define and set a CICS Target Platform for the workspace using the menu Window -> Preferences -> Target Platform.
28+
29+
30+

‎projects/com.ibm.cicsdev.link/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
com.ibm.cicsdev.link
2+
===
3+
4+
Provides examples for performing CICS LINK operations using both commareas, and channels and containers.
5+
6+
* `LinkProg1` - a class that demonstrates linking to the COBOL application `EC01` using a COMMAREA.
7+
* `LinkProg2` - a class that demonstrates linking to the COBOL application `EDUPGM` using a COMMAREA mapped using a JZOS generated record.
8+
* `LinkProg3` - a class that demonstrates linking to COBOL application `EDUCHAN` using channels and containers.
9+
* `LinkProgCommon` - superclass used to provide common services for the `LinkProg` samples.
10+
* `LinkServerEduchan` - A Java version of the `EDUCHAN` COBOL program used as the back-end to `LinkProg3`.
11+
12+
13+
## Supporting files
14+
15+
* `lib/EDUPGM.jar` - a pre-built JAR containing the JZOS generated record that maps the copybook structure used in the `EDUPGM` COBOL sample. The generated class `JZOSCommareaWrapperclass` is used in the `LinkProg2` example to map the fields in the COMMAREA used by the COBOL program `EDUPGM`.
16+
* [`/etc/Link`](../../etc/Link) - contains the output of a DFHCSDUP EXTRACT operation needed to define the required programs and transactions.
17+
* [`/src/Cobol`](../../src/Cobol) - contains the COBOL programs `EC01` and `EDUCHAN` required by these samples.
18+
* [cics-java-jzosprog repo](https://github.com/cicsdev/cics-java-jzosprog/tree/master/src/Cobol) - repository containing the `EDUPGM` COBOL program.
19+
20+
21+
## Configuration
22+
23+
1. Compile and deploy the COBOL programs `EC01`, `EDUPGM`, and `EDUCHAN`.
24+
1. Define appropriate PROGRAM definitions, or enable program autoinstall.
25+
1. Optionally add a CICS Java program definiton for LinkServerEduchan called EDUCHAN if you wish to replace the EDUCHAN COBOL sample with the Java implemenation.
26+
27+
28+
## Running the Example
29+
30+
At a 3270 terminal screen, enter the transaction you wish to run, for example JOL1 will run the LINK example 1.
31+
32+
JOL1
33+
34+
and the following output will be returned
35+
36+
JOL1 - Starting LinkProg1
37+
Returned from link to EC01 with 19/08/16 09:17:01
38+

0 commit comments

Comments
 (0)