In this sample program, you will set up an IMS JMP region that can run a Java application that uses IMS type-2 drivers. This application can IMS message queues to receive and handle input and output messages.
To complete this sample program in your environment, you need the following software:
- Java 17 or later (on z/OS)
- Visual Studio Code
You also need to understand how to work with the following software:
- Java programming: Beginner
- SQL: Beginner
- z/OS: Intermediate
- IMS: Intermediate
Download the ims-java-jmp project by clicking Clone or Download and then selecting Download ZIP.
- Access to z/OS (3270 connection or Zowe Explorer)
- RACF read authority on SMP/E installed IMS libraries
- RACF update authority on the high-level qualifiers (HLQs)that you are using for the IMS instance libraries
In order to see the "non-key" fields in your program you will need to add several fields to the DI21PART database. The DDL to accomplish this can be found under src->resources->DI21PART.ddl. This code can be ran using your IMS SQL executor of choice (IMS Explorer for VsCode, IMS Explorer for Development, IMS SPUFI).
-
Create a PSB for your JBP region to use. You can find the PSB under ims-java-jbp->part-one-files->JBPPARTS.DDL
-
This code can be ran using your IMS SQL executor of choice (IMS Explorer for VsCode, IMS Explorer for Development, IMS SPUFI).
-
Your PSB will need to be using your newly populate DI21PART DBD
You might notice that the parameter "LANG=JAVA" is shown in the DDL. This parameter is required for applications using this PSB that are running in a JBP region.
- Enter the IMPORT type-2 command to IMS to import the PSB into the catalog:
IMPORT DEFN SOURCE(CATALOG) NAME(JMPPARTS)
- Enter the CREATE type-2 command:
CREATE PGM NAME(JMPPARTS) LIKE(RSC(DFSIVP37)).
These commands allow IMS resources to use the DBD and PSB.
- To verify that the commnands worked properly, issue the QUERY command to see the PSB:
QUERY PGM NAME(JMPPARTS) SHOW(ALL)
You should now see the PSB that you created and the LRgnType value should be JMP.
If your query fails or your LRgnType value is not JMP, ensure that you followed the previous steps properly.
- Pass a type-two command to create a transaction code and link it to the PGM that you just defined:
CREATE TRAN NAME(RUNPARTS) LIKE(DESC(DFSDSTR1)) SET(PGM(JMPPARTS), CLASS(2))
This transaction is given the default parameters through the ***LIKE(DESC(DFSDSTR1))*** parameter.
The ***PGM*** parameter is overwritten to connect the transaction to the PSB and PGM that was just created.
The ***CLASS*** parameter is overwritten to allow the transaction to run in the JMP region that will be created in the following steps.
- To verify your work, run a QUERY command:
QUERY TRANNAME NAME(RUNPARTS) SHOW(ALL)
The parameter LPSBName should be ***JMPPARTS***.
Congratulations! You now have a PSB and a transaction defined for your JMP region to access.
- Visual Studio Code
- Required extensions: Project Manager for Java, Java Extension Pack, and Maven for Java
For this sample program, you will write a Java application that uses IMS message queues to access and manipulate an IMS database.
Just like you would with a distributed Java application, you will use the IMS Universal drivers.
This sampe program's application consists of five files and is already mostly written for you.
The following is a breakdown of what each segment of the application does.
This file will be the main class of your project.
First, a connection object is created:
IMSDataSource ds = new IMSDataSource();
ds.setDriverType(2);
ds.setDatabaseName("JMPPARTS");
ds.setUser("MYUSER");
ds.setPassword("MYPASS");
imsConnection = ds.getConnection();
Since DI21PART only contains keys, additional field data will be supplied using local metadata. This is contained in JMPPARTS.xml and DI21PART.xml.
Be sure to provide your system's user name and password.
Then the application will create and handle the input and output messages.
inputMessage = app.getIOMessage("class://com.ibm.ims.jmp.message.PartInfoInput");
outputMessage = app.getIOMessage("class://com.ibm.ims.jmp.message.PartInfoOutput");
if (!foundError) {
while (messageQueue.getUnique(inputMessage)) {
action = inputMessage.getString("IN_COMMAND").trim();
partKey = inputMessage.getString("PARTKEY").trim();
if (action.equalsIgnoreCase("ADD") || action.equalsIgnoreCase("UPD")) {
partName = inputMessage.getString("PARTNAME").trim();
partDesc = inputMessage.getString("PARTDESC").trim();
}
PartInformation part = new PartInformation();
part.setPartKey(partKey);
part.setPartName(partName);
part.setPartDesc(partDesc);
PartInventoryService partService = new PartInventoryService(imsConnection);
if (partService != null) {
String returnMessage = "";
if (action.equalsIgnoreCase("ADD")) {
returnMessage = partService.addPart(part);
}
else if (action.equalsIgnoreCase("DEL")) {
returnMessage = partService.deletePart(part.getPartKey());
}
else if (action.equalsIgnoreCase("UPD")) {
returnMessage = partService.updatePart(part);
}
else if (action.equalsIgnoreCase("GET")) {
returnMessage = partService.getContact(part.getPartKey());
}
else {
returnMessage = "ERROR: INVALID COMMAND WAS SPECIFIED";
}
outputMessage.setString("RETURN_MSG", returnMessage);
messageQueue.insert(outputMessage, MessageQueue.DEFAULT_DESTINATION);
tran.commit();
}
This code uses the information in PartInfoInput.java and PartInfoOutput.java to create "template" input and output messages.
The application then reads a message from the message queue and places the information into the inputMessage variable.
This information is then parsed and placed into a PartInformation object. The action code (ADD, UPD, DEL, GET) is retreived from the message and passed into PartInventoryService.java. This class performs the specified unit of work and returns an output message.
The output message will then be written to the job log and the application will wait for another message to handle.
This class is called by PartsInventory.java. It receives the action code retrieved from the message queue and passes a corresponding SQL call against the parts database.
This class contains four main functions:
public String addPart(PartInformation part) -- SQL INSERT
public String deletePart(String partKey) -- SQL DELETE
public String updatePart(PartInformation part) -- SQL UPDATE
public String getContact(String partKey) -- SQL SELECT
All of these functions return an output message back to PartsInventory.java to be written to the message queue.
This class provides getter and setter methods for a parts object.
A part object contains a Part Key, Part Name, Part Description, Segment Number, and an Output Message
Field information from the message queue is read into a PartInformation object in PartsInventory.java and then passed into PartInventoryService.java for handling.
public class PartInfoInput extends IMSFieldMessage {
static DLITypeInfo[] fieldInfo = new DLITypeInfo[]{new DLITypeInfo("IN_COMMAND", 3, 1, 4), new DLITypeInfo("PARTKEY", 3, 5, 17),
new DLITypeInfo("PARTNAME", 3, 22, 12), new DLITypeInfo("PARTDESC", 3, 26, 21)
};
// IMSFieldMessage(DLITypeInfo[] typeInfo, int length, boolean isSPA)
public PartInfoInput() {
super(fieldInfo, 46, false);
}
}
This class extends the IMSFieldMessage class provided by Java and creates an array of DLITypeInfo objects. This array contains field data describing the segment and field information of the PARTROOT similar to how a COBOL copybooks are used with IMS.
The super statement specifies the total field length (46) and sets isSPA (is scratch pad area) to false.
public class PartInfoOutput extends IMSFieldMessage {
// does serial version UID need to be included
static DLITypeInfo[] fieldInfo = new DLITypeInfo[]{new DLITypeInfo("RETURN_MSG", 3, 1, 200),
new DLITypeInfo("ERROR_MSG", 3, 201, 500)
};
public PartInfoOutput() {
super(fieldInfo, 700, false);
}
}
This class works similarly to PartInfoInput.java. Two fields are created: a return message and an error message.
The super statement specifies the total field length (46) and sets isSPA (is scratch pad area) to false.
Before proceeding to the next part, be sure you overwrite the Username and Password values in PartsInventory.java.
-
Export your application as a JAR file. This creates the application in a usable format for the JMP region.
a. In the Java Projects drop down, select the "|->" logo. Select JMPPARTS as your main class. You now have a JAR file called JMPPARTS.jar.
You are now ready to set up your environment for a JMP.
Rename your new *.jar file to jmpparts.jar (to match your PSB). Your program is now ready to be moved to z/OS.
- 3270 Client or Zowe Explorer
- FTP enabled on z/OS or Zowe Explorer
- Access to OMVS
- For your Java program to run, add the IMS Universal drivers and JMPPARTS.jar to your environment:
IMSUDB.jar
This is your IMS universal driver. This allows you to create a local, type-two connection to the database that you will be working with.
**JMPPARTS.jar**
This is your program JAR from the last step. This must be placed on your system for your JBP region to access it.
-
Create a USS directory to store the files.
a. Using either z/OS, FTP, or Zowe Explorer, create a folder containing a pgm folder for your Java program (JMPPARTS.jar) and a lib folder for all of the JAR files that your application will be using.
b. Use an FTP client or Zowe Explorer to transfer all of the files under part-three-files->jars into your lib folder and transfer your application JAR into the bin folder that was just created.
Three PROCLIB members must be modified for your JMP program to run.
DFSJVMMS
This member serves as your Java classpath.
-
Specify any JAR files that are included in your classpath in the first section of this member.
-
Specify the path to your application JAR that was made in the last step.
-
In the second section of this member, specify your JVM options.
The following example shows the DFSJVMMS member:
-Djava.classpath=>
/u/ibmuser/ims/java/bin/imsudb.jar:>
/path/to/yourJavaApp.jar
*
*
********************************************************************
* JVM options for heap size tuning.
********************************************************************
-Dibm.jvm.events.output=stdout
-Xgcpolicy:gencon
-Xmx200m
-Xmx128m
-Xms100m
-Xmnx60m
-Xmns20m
-Xdump:java+heap+system:events=throw,filter=java/lang/OutOfMemoryError
*
DFSJVMEV
-
Specify the location of your Java installation, specifically, the lib, bin, and j9vm directories.
-
Specify the path to libT2DLI_64.so.
The following example shows the DFSJVMEV member:
**********************************************************************
* Specify the location of Java native code (libT2DLI.so and
* libT2DLI_64.so) and Java Virtual Machine (JVM) installation.
*
* Note: If you need to add another path, the previous line should have
* ':' to separate the paths and '>' as the continuation character.
**********************************************************************
LIBPATH=>
/usr/lpp/java/J17.0_64/bin:>
/usr/lpp/java/J17.0_64/lib/j9vm:>
/usr/lpp/java/J17.0_64/lib:>
/path/to/libT2dli_64.so
*
DFSJVMAP
This proclib member maps your Java application to the PSB resource you defined to IMS.
-
Use the left side of the equal sign to specify your PSB name and the right side with be the path to your .class file in your Java application's .jar file.
For this sample program, you need to add only the following line to your PROCLIB member.
**********************************************************************
* Test IMS JMP Program
**********************************************************************
JMPPARTS=com.ibm.ims.jmp.PartsInventory
Congratulations! You have successfully set up your Java environment.
-
Under part-three-files->jobs, find a file named DFSJMP.txt.
This job has some lines that must be modified for it to run in your environment. Those lines are marked. For more information on this procedure, see the DFSJMP procedure documentation
-
In the first step that calls the DFSJMP proc, replace IMSID with your IMSID. The other default parameters will likely work for this sample program.
Note that the JVM parm is set to JVM=64. If you use a version of Java that supports 31-bit instructions (Java 8 and lower), this parameter can be set to 31 or 3164 (mixed mode) to allow for interoperability with other 31-bit applications.
-
Do not change the the JBPRGN exec section. All of the parameters specified in the last step will be passed through to this statement.
-
Replace the HLQs with your IMS HLQ in the STEPLIB and PROCLIB statements.
-
Specify STDOUT and STDERR and the other SYSOUT DD statements. These will need to be specified for you to see the output for your Java application.
-
After all the lines marked for replacement are corrected, copy this file to the "YOUR IMS HLQ".JOBS data set. This job will be called from SDSF by passing a WTOR command.
To start your JMP region, pass this command in SDSF to the IMS region that will be running your job:
/r ##,/STA REGION DFSJMP
Note: Replace the "##" with the WTOR number of your IMS region
You should then see DFSJMP running as an active job.
If you see errors, the STDOUT and STDERR segments can provide more information about how to correct the issues.
You should see a message similar to this stating that the JVM has completed initialization.
DFSJVM64: JVM initialization started: Wed Feb 11 17:14:47.426 2026
DFSJVM64: JVM initialization complete: Wed Feb 11 17:14:47.645 2026
DFSJVM64: Process ID:::::::: PID =67580
DFSJVM64: Parent Process ID: PPID=1
DFSJVM64: Process Group ID:: PGID=67580
Your application can now be run by calling its transaction code.
- Call your application by passing this command in the IMS terminal.
All interactions with this application first require the trancode, an action (ADD, UPD, DEL, GET), and then the data being passed
into the data base (PARTKEY, PARTNAME, PARTDESC).
Note that the command *is* space sensitive, and everything must line up with the field information supplied in your Java application.
After submitting this command, you should receive a message back stating that the part information supplied has been added to the table.
- To verify this, view your part information by passing a GET command.
RUNPARTS GET 027618032P303
You should receive output containing the PARTNAME and PARTDESC for the PARTKEY that was provided.
- Update the part the you just entered.
RUNPARTS UPD 027618032P303 CAT 6 ETHERNET
You should receive a message stating that your part has been updated.
- Delete the part that you just inserted.
RUNPARTS DEL 027618032P303
You should receive a message back stating that the part has been deleted
All of these operations are read off the message queue, handled by the IMS SQL that you wrote in your application, and then passed back to the message queue for you to view the output.
Congratulations! You have now created a Java application that uses IMS message queues, and a JMP region to run it in. You can modify this application to add more functionaliy, work with additional tables in the parts database, or even use a different database.