Table of Contents
Overview
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.1 and IBM 64-bit SDK for z/OS, Java Technology Edition, V7.1 are 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.
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.
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
- From the z/OS operator console, issue the operator command "SETCON TRACKING=ON" to activate the Console ID Tracking facility.
- Run your application(s).
- From the z/OS operator console, issue the operator command "DISPLAY OPDATA,TRACKING" to display the recorded instances of events.
- Identify JRIO instances. A JRIO instance starts with the letter "J", followed by a colon ":", and then a number. (Refer to Console Data Display below for details)
- Obtain the names of the applications from the "TRACKING INFORMATION" column of the identified JRIO instances.
- Retrieve the frequencies of the application runs from the "NUM" column.
- If desired, issue the operator command "SETCON TRACKING=OFF" to deactivate the Console ID Tracking facility.
- 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 (PDF, 1.6MB), 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./p>
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.(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)
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 (ZIP, 67.1KB)
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.
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.