com.ibm.jzos

Class DfSort

  • java.lang.Object
    • com.ibm.jzos.DfSort

  • public class DfSort
extends java.lang.Object
    This class provides a Java wrapper around the DFSORT utility.

    DFSORT is useful for performing high-volume sort and merge operations. When invoked from Java, either the input can be taken from existing datasets or produced directly from Java. Likewise, the output from DFSORT can be written to a dataset or read directly back into Java. When writing from or reading into Java, java.io InputStreams and OutputStreams may be used to read and write data from the Java application to DFSORT.

    For more information, see the following:

    DFSORT DD allocations can be specified via addAllocation(String)

    DFSORT control statements are specified via addControlStatement(String).

    Since:
    2.3.0

    • Constructor Summary

      Constructors 
      Constructor and Description
      DfSort() 

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      void addAllocation(java.lang.String allocation)
      Add an allocation request to be sent to the DFSORT invocation.
      void addControlStatement(java.lang.String controlStatement)
      Add a control statement to be sent to the DFSORT invocation.
      void disableInputStream()
      Indicate that the records to DFSORT are to be provided via the SORTIN DD and not from Java.
      void disableOutputStream()
      Indicate that the output records from DFSORT are to be sent to the SORTOUT DD and not to Java.
      void execute()
      Run the jdfsort child process, which is a z/OS Java USS binary command wrapper for invoking DFSORT.
      java.io.OutputStream getChildStdinStream()
      Returns a java.io.OutputStream that can be used to send records to the child DFSORT process.
      java.io.InputStream getChildStdoutStream()
      Returns a java.io.InputStream that can be used to read output records from the child DFSORT process.
      int getReturnCode()
      Wait for DFSORT to complete.
      java.util.List getStderrLines()
      Return a list of stderr output lines (Strings) from the spawned DfSort process.
      boolean isSameAddressSpace()
      Answer true if the child jdfsort process will be spawned in the same address space that is running the Java JVM.
      void setInputStreamHasRdws()
      Indicate that the records to be sent as input to DFSORT are variable length, and that each record will prefixed by a 4 byte (big endian) RDW.
      void setInputStreamRecLen(int reclen)
      Set a fixed record length for the records that will be sent as input to DFSORT.
      void setLoggingLevel(int logLevel)
      Set the logging level for the jdfsort child process.
      void setOutputStreamHasRdws()
      Indicate that the records sent from DFSORT to java are variable length, and that each record will prefixed by a 4 byte (big endian) RDW.
      void setOutputStreamRecLen(int reclen)
      Set a fixed record length for the records that will be received from DFSORT.
      void setSameAddressSpace(boolean same)
      Sets whether the child DFSORT process will be spawned in the same address space as the Java JVM, or in a separate/new BPX address space.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • DfSort

        public DfSort()

    • Method Detail

      • addAllocation

        public void addAllocation(java.lang.String allocation)
        Add an allocation request to be sent to the DFSORT invocation.

        The allocation strings are expected to be in the syntax required by BPXWDYN.

        Typically, DFSORT may have allocations for the following DDs:

        • SORTIN - Where DFSORT gets sort/merge input.
        • SORTOUT - Where DFSORT writes sort/merge output
        Example:

        DfSort dfSort = new DfSort(); dfSort.addAllocation("alloc fi(sortin) da('HLQ.MY.DATASET') reuse shr msg(2)");

        Note: allocation requests must be added before calling execute() in order to have any effect.

      • addControlStatement

        public void addControlStatement(java.lang.String controlStatement)
        Add a control statement to be sent to the DFSORT invocation. Example:

        DfSort dfSort = new DfSort(); dfSort.addControlStatement("SORT FIELDS=(1,80,CH,A)");

        Note: control statements must be added before calling execute() in order to have any effect.

      • setInputStreamRecLen

        public void setInputStreamRecLen(int reclen)
        Set a fixed record length for the records that will be sent as input to DFSORT. This length must match the record length expected by DFSORT as specified by the RECORD control statement.

        This method is mutually exclusive with setInputStreamHasRdws() and disableInputStream().

        Note: this property must be changed before calling execute() in order to have any effect.

        Parameters:
        reclen - int the input record length for fixed records
        See Also:
        getChildStdinStream(), addControlStatement(String)

      • setInputStreamHasRdws

        public void setInputStreamHasRdws()
        Indicate that the records to be sent as input to DFSORT are variable length, and that each record will prefixed by a 4 byte (big endian) RDW. This RDW value must be less than or equal to the maximum record length expected by DFSORT as specified by the RECORD control statement. The RECORD control statement must indicate that DFSORT is to expect variable length records.

        Note: this property must be changed before calling execute() in order to have any effect. This method is mutually exclusive with setInputStreamRecLen(int) and disableInputStream().

        See Also:
        getChildStdinStream(), addControlStatement(String)

      • disableInputStream

        public void disableInputStream()
        Indicate that the records to DFSORT are to be provided via the SORTIN DD and not from Java.

        Note: this property must be changed before calling execute() in order to have any effect.

        This method is mutually exclusive with setInputStreamRecLen(int) and setInputStreamHasRdws().

      • setOutputStreamRecLen

        public void setOutputStreamRecLen(int reclen)
        Set a fixed record length for the records that will be received from DFSORT. This length must match the record length produced by DFSORT as specified by the RECORD control statement.

        Note: this property must be changed before calling execute() in order to have any effect. This method is mutually exclusive with setOutputStreamHasRdws() and disableOutputStream().

        Parameters:
        reclen - int the output record length for fixed records
        See Also:
        getChildStdoutStream(), addControlStatement(String)

      • setOutputStreamHasRdws

        public void setOutputStreamHasRdws()
        Indicate that the records sent from DFSORT to java are variable length, and that each record will prefixed by a 4 byte (big endian) RDW. This RDW value will be less than or equal to the maximum record length as specified by the RECORD control statement. The RECORD control statement must indicate that DFSORT is to produce variable length records.

        Note: this property must be changed before calling execute() in order to have any effect. This method is mutually exclusive with setOutputStreamRecLen(int) and disableOutputStream().

        See Also:
        getChildStdoutStream(), addControlStatement(String)

      • disableOutputStream

        public void disableOutputStream()
        Indicate that the output records from DFSORT are to be sent to the SORTOUT DD and not to Java.

        Note: this property must be changed before calling execute() in order to have any effect. This method is mutually exclusive with setOutputStreamRecLen(int) and setOutputStreamHasRdws().

      • getChildStdinStream

        public java.io.OutputStream getChildStdinStream()
        Returns a java.io.OutputStream that can be used to send records to the child DFSORT process. This data stream is used to provide input to DFSORT via a sort input exit as an alternative to DD:SORTIN.

        The data sent to this stream should be fixed length records if setInputStreamRecLen(int)() has been used, or RDW-prefixed records if setInputStreamHasRdws() has been used. If however, disableInputStream() was set (the default), then this stream has no use, as input to DFSORT will come from DD:SORTIN.

        For best performance, this OutputStream should be wrapped in a BufferedOutputStream. To write RDW-prefixed records, see RDWOutputRecordStream.

        Returns:
        java.io.OutputStream
        Throws:
        java.lang.IllegalStateException - if called before execute()

      • getChildStdoutStream

        public java.io.InputStream getChildStdoutStream()
        Returns a java.io.InputStream that can be used to read output records from the child DFSORT process. This data stream will contain sorted output data from DFSORT via a sort output exit as an alternative to DD:SORTOUT.

        The data sent to this stream should be fixed length records if setOutputStreamRecLen(int)() has been used, or RDW-prefixed records if setOutputStreamHasRdws() has been used. If however, disableOutputStream() was set (the default), then this stream has no use, as output from DFSORT will go to DD:SORTOUT.

        For best performance, this InputStream should be wrapped in a BufferedInputStream. To read RDW-prefixed records, see RDWInputRecordStream.

        Returns:
        java.io.InputStream
        Throws:
        java.lang.IllegalStateException - if called before execute()

      • execute

        public void execute()
             throws ErrnoException
        Run the jdfsort child process, which is a z/OS Java USS binary command wrapper for invoking DFSORT. Passed as arguments to jdfsort are the allocation commands, control statement commands, input/output stream settings.
        Throws:
        ErrnoException - if there is a failure launching the child process

      • getReturnCode

        public int getReturnCode()
        Wait for DFSORT to complete. This method should be called after execute() and after I/O from the child's stdin and/or stdout has been processed.
        Returns:
        int the DFSORT return code. Value unpredictable if called before execute().
        Throws:
        RcException - if the child process terminates abnormally without a return code

      • getStderrLines

        public java.util.List getStderrLines()
        Return a list of stderr output lines (Strings) from the spawned DfSort process. This method only applies if isSameAddressSpace() = false. Otherwise, DFSORT messages will be written to java's stderr.
        Returns:
        List a list of strings

      • isSameAddressSpace

        public boolean isSameAddressSpace()
        Answer true if the child jdfsort process will be spawned in the same address space that is running the Java JVM. Answer false if the child process will be spawned in a separate/new BPX address space. Reusing the same address space involves less overhead, but has limitations since only one DFSORT process should be active at a given time in a given address space, since the same DD names are used.
        See Also:
        setSameAddressSpace(boolean)

      • setSameAddressSpace

        public void setSameAddressSpace(boolean same)
        Sets whether the child DFSORT process will be spawned in the same address space as the Java JVM, or in a separate/new BPX address space.
        Parameters:
        same - flag to indicate whether the DFSORT child invocation process should run in the same address space as the JVM. If true, run the DFSORT child invocation process in the same address space as the JVM. If false, spawn a new address space.
        See Also:
        isSameAddressSpace()

      • setLoggingLevel

        public void setLoggingLevel(int logLevel)
        Set the logging level for the jdfsort child process.

        May be any ZUtil.LOG_* values. The default value is ZUtil.LOG_NOTICE, or if set, the system property jzos.logging. If an invalid value is given, the default level "I" (informational) is assumed.

        Note: this property must be changed before calling execute() in order to have any effect.

        Parameters:
        logLevel - the logging level
Skip navigation links
� Copyright IBM Corporation 2005, 2022.