IBM Java Record I/O (JRIO) to IBM JZOS Batch Toolkit Migration and Sample Code

(last updated May, 2012)

IBM Java Record (JRIO) is deprecated as of SDK 6.0.1. No new function will be added to any release of IBM Java Record I/O (JRIO).

IBM 31-bit SDK for z/OS, Java Technology Edition, V7.0 and IBM 64-bit SDK for z/OS, Java Technology Edition, V7.0 are planned to be the last releases to support the JRIO component.

We strongly recommend migrating to IBM JZOS Batch Toolkit, which currently has equivalent functionality and will be enhanced with new functions. A JRIO Usage Tracker and a set of JZOS JRIO-Equivalent Sample Code are provided to help users transition from JRIO to JZOS.

For more comprehensive information, refer to the IBM JZOS Batch Toolkit for z/OS SDKs webpage.

For API specifics, refer to IBM JZOS Batch Toolkit API.


grey_rule.gif

JZOS Benefits

IBM JZOS Batch Toolkit for z/OS provides many additional benefits over JRIO. These include but are not limited to:

  • Better I/O error and exception reporting.
  • Support for all record formats that are supported by the C language I/O Library.
  • Dynamic Allocation on VSAM datasets. JRIO is limited to non-VSAM datasets.
  • Users can specify all the parameters that are accepted by the C language I/O Library.
  • AccessMethodServices/IDCAMS allows users not only to create or delete VSAM datasets, but offers useful capabilities such as LISTC.
  • Offers additional capabilities such as LOCATE/OBTAIN dataset information, catalog search, read PDS directories, logstream support.

grey_rule.gif

JRIO Usage Tracker

To help users determine whether their applications use JRIO, a new tool, JRIO Usage Tracker, was provided as part of the JRIO component starting from z/OS SDK601 SR1 (PTFs UK72318 and UK72319 for the 31-bit product and UK74829 and UK74870 for the 64-bit product) and z/OS SDK7 SR1 (PTFs UK78842 and UK78843 for the 31-bit product and UK78844 and UK78845 for the 64-bit product). The tool will help users decide if migration actions to the JZOS component will be necessary and which workloads will be affected.

The tool provides two approaches to track JRIO instances: 1) It records JRIO instances on the z/OS operation console when the z/OS Console ID Tracking facility is enabled; and 2) Optionally, it writes additional information about an application instance to a Unix file if the application is invoked with a new JRIO-specific command option, -DRIOJATRACK:

1) Using z/OS Console ID Tracking Facility for Instances Report

  1. From the z/OS operator console, issue the operator command "SETCON TRACKING=ON" to activate the Console ID Tracking facility.
  2. Run your application(s).
  3. From the z/OS operator console, issue the operator command "DISPLAY OPDATA,TRACKING" to display the recorded instances of events.
  4. Identify JRIO instances. A JRIO instance starts with the letter "J", followed by a colon ":", and then a number. (Refer to Console Data Display for details)
  5. Obtain the names of the applications from the "TRACKING INFORMATION" column of the identified JRIO instances.
  6. Retrieve the frequencies of the application runs from the "NUM" column.
  7. If desired, issue the operator command "SETCON TRACKING=OFF" to deactivate the Console ID Tracking facility.
  8. Optionally, add identified JRIO instances to a CNIDTRxx parmlib member, and then use the command SET CNIDTR=xx to exclude the instances listed in the member from being recorded again.

For more information about z/OS Console ID Tracking Facility, refer to z/OS MVS Planning: Operations, SA22-7601.

Console Data Display

Each instance on the console consists of the following fields:

a) TRACKING INFORMATION (up to 28 characters, as limited by the console display)

J:<number of calls> <application name>:<line number> <immediate class>:<line number>

where

J:<number of calls>
J stands for "JRIO"
<number of calls>
Number of calls on the call stack prior to the JRIO class.

<application name>:<line number>
<application name> The name of the application that uses JRIO. For multi-threaded applications, the "application name" will be the name of the Class that implements the thread calling JRIO. In most cases for a multi-threaded application this will be Thread.java, but it would be something different if Thread has been extended.
<line number> The line number where the application make the first call to JRIO. The call may be a direct or an indirect call to JRIO.

<immediate class>:<line number>
<immediate class> The name of the class that makes the immediate call to JRIO.
<line number> The line number where the class makes the immediate call.

<application name>:<line number> and <immediate class>:<line number> may be the same if the first JRIO call in the application is a direct call to JRIO.

Due to the 28-byte limitation of the z/OS Console Tracker, tracking information exceeding 28 bytes will be discarded. A "*" character will be appended to a truncated TRACKING INFORMATION to alert users.

Example 1:
An application, UserApp, whose first call to JRIO is a direct call at line 17:

   J:1 UserApp:17 UserApp:17

Example 2:
An application named UserAppl made an indirect call to JRIO at line 8 and there were a total of 6 calls (including the first call) before it reached JRIO. Class3 made the immediate call to JRIO at line 19:

   J:6 UserApp2:8 Class3:19

Example 3:
Same as Example 2, but with a longer application name, UserAppVeryLongName. The data exceeding 28 characters is truncated and the information about the immediate class is incomplete. Notice that the information is appended with a "*" character to alert users of the truncation.

   J:6 UserAppVeryLongNameApp:8 C*

Example 4:
For multi-threaded applications, the tracker will report the name of the Class that implements the thread calling JRIO. The following example shows an instance of Thread invoking JGCreateFile5a which in turn makes an immediate call to JRIO:

   J:2 Thread:769 JGCreateFile*

b) VALUE (4 bytes)
The field is not used by JRIO and is initialized with 0x00. The hex value 00 will be shown in the column.

c) JOBNAME
If the application is submitted through a JCL, the field will show the JOBNAME as indicated in the submitted JCL.
If the application is executed through a logon, then the field may be the logon ID followed by a random digit.

d) PROGNAME +OFF:
The name of the program and the offset into the program where the call occurred. For a Unix program, "*PATHNAM" is always shown as the PROGNAME.

e) ASID:
The ASID of the violator.

f) NUM:
The column displays the number of occurrences of tracking the same instance. An instance is uniquely identified by the combined values of several attributes: TRACKING INFORMATION, VALUE, JOBNAME, PROGNAME +OFF, and ASID. There may be redundant instances for an application executed from a logon session due to the random digit appended to the logon ID as the JOBNAME.

The maximum number of unique instances that can be recorded is 1,000. Once this limit is reached, the facility internally issues the DISPLAY OPDATA,TRACKING command, which writes the recorded instances to the hardcopy log, and then issue message CNZ1001I to indicate that the facility is full. Further instances will not be recorded until the tracking facility is deactivated and then reactivated.

Below is an example of the display of the Console ID Tracking facility when the DISPLAY OPDATA,TRACKING command is issued:

 

 

In this example, a user with the user id "JAVAFVT" executed UserApp once, UserAppVeryLongName also once, and UserApp2 twice from a UNIX login session. The user also submitted UserApp2 using JCL from MVS using the JOBNAME "JCLJOB" three times. The tracker reports the three JCL submissions in one row and reports its three occurrences in the "NUM" column. However, each UNIX job execution is reported as a distinct instance, because, as mentioned above, UNIX jobs do not have MVS JOBNAME, and the system creates a unique JOBNAME by appending a random digit to the login id, which makes the combined value of the instance unique as well.

Notice that the TRACKING INFORMATION of UserAppVeryLongName ends with a "*" because the information was truncated due to limited space in the column.

2) Using JRIO Tracking Command -DRIOJATRACK for Additional Information

The tracking data displayed on the console is limited. To obtain additional information, you can invoke the application with a new JRIO-specific command option, -DRIOJATRACK, and additional information about the application will be written to a Unix file.

The command can be specified with or without a file name. If a file name is provided, the tracking data will be written to the specified file name; otherwise the data will be written to a default file in the /tmp directory with a naming convention as described below.

a) Specify -DRIOJATRACK with a file name

   java -DRIOJATRACK=<file name> <user application>

For example,

   java -DRIOJATRACK=/home/javafvt/logs/jrioTrackLog  MyApp

   Tracking data will be written to /home/javafvt/logs/jrioTrackLog

b) Specify -DRIOJATRACK without a file name

   java -DRIOJATRACK <user application>

For example,

   java -DRIOJATRACK MyApp

   Tracking data will be written to a file with the file name with the format,
   jrio.track.yyyy-mm-dd.hh:mm:ss.SS

where
   yyyy-mm-dd  is the year, month, and date when the application instance is reported
   hh:mm:ss.SS is the time in hour, minute, second, and millisecond when the 
               application instance is reported

For example,  /tmp/jrio.track.2011-06-15.14:55:06.230

An exception or error that occurs during the logging will be written to standard error (STDERR), and an entry will be added to JRIO trace file if the JRIO debug option -DRIOJADEBUG is also supplied.

A log entry in the Unix file consist of the following fields:

Event Date/Time :  The date/time when the instance occurred 
Entry File Name :  The name of the file that contains the entry application  
Class Path      :  The value of the CLASSPATH environment variable when the
                   application instance is reported 

TRACKING INFORMATION (console display) : Same as the TRACKING INFORMATION displayed 
                                         on the console
TRACKING INFORMATION (complete)        : The complete TRACKING INFORMATION, without
                                         truncation if exceeding 28 characters         

No. of Calls prior to JRIO Class:  Number of calls on the call stack prior to the 
                                   JRIO class
Call Stack Entry                :  The entry on the top of call stack
Immediate Call to JRIO          :  The immediate call entry to the JRIO class 
                                   on the call stack    
JRIO Class                      :  The invoked JRIO class            

Call Stack:  The calling stack of the invoked instance. It includes all the calls up 
             to the execution point when the instance was reported.

Example for standalone applications:

The following log entry shows that the application, UserAppVeryLongName, made an indirect call to JRIO at line number 8. There were a total of 6 calls before it reached JRIO RecordFile class. The last call to JRIO was made on line number 19 in Class3. TRACKING INFORMATION is truncated on the console display due to limited space. The log entry contains the TRACKING INFORMATION with and without the truncation.

Event Date/Time: 11/15/2011 07:11:05
Entry File Name: UserAppVeryLongName.java 
Class Path     :
/home/javafvt/jriotrkr:/home/javafvt/java_sdks/J7.0/lib:/home/javafvt/java_sdks/
   J7.0.1/lib/ext:/home/javafvt/jriotrkr/*.jar:

TRACKING INFORMATION (console display): J:6 UserAppVeryLongName:8 C*
TRACKING INFORMATION (complete)       : J:6 UserAppVeryLongName:8 Class3:19

No. of Calls prior to JRIO Class: 6
Call Stack Entry      :
com.ibm.jrio.ut.macro.UserAppVeryLongName.main(UserAppVeryLongName.java:8)
Immediate Call to JRIO: com.ibm.jrio.ut.macro.Class3.callJrio(Class3.java:19)
JRIO Class            : com.ibm.recordio.RecordFile.getInstanceOf(RecordFile.java:106)

Call Stack:
  com.ibm.jrio.ut.macro.UserAppVeryLongName.main(UserAppVeryLongName.java:8)
  com.ibm.jrio.ut.macro.UserAppVeryLongName.getData(UserAppVeryLongName.java:15)
  com.ibm.jrio.ut.macro.Class1.getNum(Class1.java:11)
  com.ibm.jrio.ut.macro.Class2.getNum(Class2.java:9)
  com.ibm.jrio.ut.macro.Class3.getNum(Class3.java:8)
  com.ibm.jrio.ut.macro.Class3.callJrio(Class3.java:19)
  com.ibm.recordio.RecordFile.getInstanceOf(RecordFile.java:106)
  java.lang.J9VMInternals.initialize(J9VMInternals.java:228)
  java.lang.J9VMInternals.initializeImpl(Native Method)
  com.ibm.recordio.driver.Configuration.<clinit>(Configuration.java:64)
  com.ibm.recordio.driver.Configuration.classinit(Configuration.java:191)
  com.ibm.recordio.driver.Configuration.JrioUsageTrackingService...
         (Configuration.java:833)
  java.lang.Thread.getStackTrace(Thread.java:1100)
  java.lang.Thread.getStackTraceImpl(Native Method)

Example for multi-threaded applications:

This example shows the call stack of a thread, the class along with the line number that makes the first call to JRIO, and the name of the JRIO class that is used.

Event Date/Time: 11/15/2011 06:05:09
Entry File Name: Thread.java
Class Path     : /javatest/TestSuite/JGrinder15.jar:/javatest/TestSuite

TRACKING INFORMATION (console display): J:2 Thread:769 JGCreateFile*
TRACKING INFORMATION (complete)       : J:2 Thread:769 JGCreateFile5a:36

No. of Calls prior to JRIO Class: 2
Call Stack Entry:	    : java.lang.Thread.run(Thread.java:769)
Immediate Call to JRIO:
   testcases.connectors.jrio.JGCreateFile5a.run(JGCreateFile5a.java:36)
JRIO Class            : com.ibm.recordio.RecordFile.getInstanceOf(RecordFile.java:160)

Call Stack:
 java.lang.Thread.run(Thread.java:769)
 testcases.connectors.jrio.JGCreateFile5a.run(JGCreateFile5a.java:36)
 com.ibm.recordio.RecordFile.getInstanceOf(RecordFile.java:160)
 java.lang.J9VMInternals.initialize(J9VMInternals.java:228)
 java.lang.J9VMInternals.initializeImpl(Native Method)
 com.ibm.recordio.driver.Configuration.(Configuration.java:63)
 com.ibm.recordio.driver.Configuration.classinit(Configuration.java:190)
 com.ibm.recordio.driver.Configuration.JrioUsageTrackingService(Configuration.java:832)
 java.lang.Thread.getStackTrace(Thread.java:1100)
 java.lang.Thread.getStackTraceImpl(Native Method)

grey_rule.gif

JZOS JRIO-Equivalent Sample Code

To facilitate your transition from JRIO to JZOS, a set of JZOS sample code with JRIO equivalent functions are provided. You can download the sample code here:

  • jzos_migration_sample.zip (source and compiled Java samples) Download

JRIO-equivalent sample code is a subset of the JZOS sample programs which has additional samples to demonstrate the JZOS features that JRIO does not offer, for example, dynamic allocation of datasets, catalog searching, MVS job submssion, and interaction with MVS Console. Click sample programs for additional information and download.


grey_rule.gif

A summary of the JRIO-equivalent sample code follows:

nonvsam.directory.DeleteDirectory

Demonstrates how to delete a directory. It may be either a HFS directory or a PDS directory


nonvsam.directory.ListDirectory

Demonstrates how to list the contents of a directory in two different ways. One approach lists all of the objects in the directory and the other approach lists only the sub-directories.


nonvsam.directory.MakeDirectory

Demonstrates how to create a new directory with default attribute values.


nonvsam.directory.MakeDirectoryLike

Demonstrates how to create a directory using the attributes of an existing directory.


nonvsam.file.CopyFile

Demonstrates how to copy data from one file to another, appending to the second file if it already exists.


nonvsam.file.CreateFile

Demonstrates how to create a file with default attributes values.


nonvsam.file.CreateFileLike

Uses BPXWDYN to dynamically allocate a new dataset with the same attributes as a given dataset.


nonvsam.file.CreateFileWithFileAttributes

Demonstrates how to create a non-VSAM MVS dataset with specific file attributes.


nonvsam.file.DeleteFile

Demonstrates how to delete a file.


nonvsam.file.GetFileAttributes

Demonstrates how to retrieve file attributes.


nonvsam.file.RandomAccessFile

Demonstrates how to randomly access a file.


nonvsam.file.ReadFile

Demonstrates how to read a file sequentially.


nonvsam.file.RenameFile

Demonstrates how to rename a file.


nonvsam.file.WriteFile

Demonstrates how to write data to a file sequentially.


vsam.cluster.DefineKsdsAIX

Demonstrates how to create a VSAM alternate index.


vsam.cluster.DefineKsdsCluster

Demonstrates how to create a VSAM cluster.


vsam.cluster.DeleteKsdsAIX

Demonstrates how to delete a VSAM alternate index created by DefineKsdsAIX.


vsam.cluster.DeleteKsdsCluster

Demonstrates how to delete a VSAM KSDS cluster created by DefineKsdsCluster.


vsam.file.DeleteKsdsRecords

Demonstrates how to delete records from a VSAM dataset.


vsam.file.SeqReadKsds

Demonstrates how to read records from a VSAM dataset.


vsam.file.SeqWriteKsds

Demonstrates how to write records to a VSAM dataset.


vsam.file.UpdateKsdsRecords

Demonstrates how to update records in a VSAM dataset.


Browse z/OS