com.ibm.jzos.ZLogstream

All Implemented Interfaces:: AutoCloseable

public class ZLogstream extends Object implements AutoCloseable

A JNI Wrapper for z/OS Logstreams, supporting IXGCONN (connect) and IXGWRITE (write). Support for IXGBRWSE (read) and IXGDELT (delete) services and InputStream/OutputStream wrappers were added in release 2.4.0.

Refer to z/OS MVS Programming: Assembler Services Guide - SA22-7605 for more information on defining and using z/OS Logstreams, aka the z/OS System Logger.

Note: If the thread that opens a logstream terminates, further use of the logstream from other threads will fail with a ZLogstreamException(RC=8/082D). The write(byte[], int, int, boolean) method will automatically catch and reconnect if this occurs, but it is the clients responsibility to handle this exception and reconnect for other methods.

Note: To release the native work areas allocated during the process and avoid memory leaks, a ZLogstream instance must be closed at the end of the execution or when the execution is interrupted by an exception. Below is an example that uses try block to catch exceptions and a finally block to ensure the close method is called in any circumstance.


        try {
                zls = new ZLogstream(logName, true);
                zls.browseStart(true, true);
                ...
                zls.browseEnd();
        } catch (Exception e) {
                // handle exception as appropriate here
        } finally {
                try {
                        zls.close();
                } catch (Exception e) {
                        // handle exception as appropriate here
                }
        }

Note: If a Java security manager is active, it is used to check permissions for reading or writing to a resource path name generated from the logstream name. For a logstream named "XXX.YYY.ZZZ", a pathname of "/LOGSTREAM/XXX/YYY/XXX" is used.

The class implements AutoCloseable. It can be used with the AutoCloseable with a try-with-resources block or without, as shown in the two examples below: Example 1: Allocate and close a ZFile when a try-with-resources block is not used. The an explicit call to the close() close the ZFile object and release the associated resources. The close() method is called in a finally block to assure that the close is performed after the try block completes.


    ZFile zfile = new  new ZFile(fileName, options);
    try {
        byte[] recBuf = new byte[lrecl];
        // read the records sequentially
        while (zfile.read(recBuf) != -1) {
            String record = new String(recBuf);
            System.out.println("Record=" + record);
        }
    }
    finally {
      zfile.close();
    }

Example 2: Allocate a ZFile when a try-with-resources block is used. The method close() is not needed. Upon exiting a try-with-resources block, the AutoCloseable will automatically call the close() method which will lose the ZFile object and release the associated resources.


    try (ZFile zfile = new  new ZFile(fileName, options)) {
        byte[] recBuf = new byte[lrecl];
        // read the records sequentially
        while (zfile.read(recBuf) != -1) {
            String record = new String(recBuf);
            System.out.println("Record=" + record);
        }
    }
    ...

Since:

2.1.0

See Also:

Field Summary

Fields

Modifier and Type

Field

Description

static final long

DEFAULT_RETRY_SLEEP_MS

The time, in milliseconds to sleep between retries

static final int

DEFAULT_WRITE_RETRY_COUNT

The count for retries certain write errors
Constructor Summary

Constructors

Constructor

Description

ZLogstream(String name)

Constructor that creates a ZLogstream instance wrapper and connects to the named z/OS Logstream.

ZLogstream(String name, boolean readOnly)

Constructor that creates a ZLogstream instance wrapper and connects to the named z/OS Logstream.
Method Summary

Modifier and Type

Method

Description

void

browseEnd()

Ends a browse session to the ZLogstream.

void

browseStart(boolean activeOnly, boolean oldest)

Starts a browse session to the ZLogstream.

void

browseStartBlockID(boolean activeOnly, long blockID)

Starts a browse session to the ZLogstream.

void

browseStartSearch(boolean activeOnly, long timestamp)

Starts a browse session to the ZLogstream.

void

close()

Closes this ZLogstream by disconnecting from the z/OS Logstream.

void

deleteAll()

Deletes all blocks in the ZLogstream.

void

deleteRange(long blockID)

Deletes a range of blocks in the ZLogstream that are older than the given block id.

long

getBlockID()

Answers as a long the 8-byte blockID from the last block read or written.

InputStream

getInputStream()

Create and return an InputStream that can be used to read from this ZLogstream.

InputStream

getInputStream(byte separator)

Create and return an InputStream that can be used to read from this ZLogstream.

int

getLastRecordRead(byte[] bytes, int offset)

Gets the last record read.

int

getMaxBlockLength()

Answers the maximum block(record) length for this logstream.

String

getName()

Answers the name of the logstream

OutputStream

getOutputStream(boolean synch)

Create and return an OutputStream that can be used to write this ZLogstream.

OutputStream

getOutputStream(boolean synch, byte separator)

Create and return an OutputStream that can be used to write this ZLogstream.

PrintStream

getPrintStream(String encoding, boolean synch)

Create and return a PrintStream that can be used to write this ZLogstream.

long

getRetrySleepTimeMs()

Answers the time to sleep in ms between retries

long

getTimestamp()

Answers as a long the 8-byte timestamp in TOD clock format from the last block read or written.

byte[]

getToken()

Answers the 16-byte logstream token.

int

getWriteRetryCount()

Answers the default retry count for certain kinds of write errors

boolean

hasBrowseSession()

Answer true if there is a browse session; false otherwise

boolean

isClosed()

Answer true if closed, false if open

boolean

isGMT()

Answer true if timestamps are in GMT(UTC).

boolean

isOpen()

Answer true if open, false if closed

int

readBlockID(long blockID, byte[] bytes, int offset)

Reads a record (block) from the logstream with a given blockID.

int

readCursor(byte[] bytes, int offset, boolean forward)

Reads a record (block) from the logstream at the current cursor position.

int

readCursor(byte[] bytes, int offset, boolean forward, boolean multiBlock)

Reads a record (block) from the logstream at the current cursor position.

int

readSearch(long timestamp, byte[] bytes, int offset)

Reads a record (block) from the logstream using a given timestamp as a search argument.

void

reconnect()

Reconnect this logstream.

void

setGMT(boolean isGMT)

Sets whether timestamps are in GMT(UTC) or LOCAL TOD clock format.

void

setRetrySleepTimeMs(long retryTimeMs)

Sets the time to sleep in ms between retries

void

setWriteRetryCount(int writeRetryCount)

Sets the default retry count for certain kinds of write errors

String

toString()

Answer a String representation of the receiver

void

write(byte[] bytes, int offset, int len, boolean synch)

Writes bytes to the z/OS Logstream.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details
- DEFAULT_WRITE_RETRY_COUNT
  
  public static final int DEFAULT_WRITE_RETRY_COUNT
  
  The count for retries certain write errors
  See Also:
  
  Constant Field Values
- DEFAULT_RETRY_SLEEP_MS
  
  public static final long DEFAULT_RETRY_SLEEP_MS
  
  The time, in milliseconds to sleep between retries
  See Also:
  
  Constant Field Values
Constructor Details
- ZLogstream
  
  public ZLogstream(String name) throws ZLogstreamException
  
  Constructor that creates a ZLogstream instance wrapper and connects to the named z/OS Logstream.
  This method calls the IXGCONN macro to create a connection to the named logstream. The IXGCONN option AUTH=WRITE is used to connect in read or write mode.
  Parameters:
  
  name - the name of the z/OS logstream to open, length invalid input: '<'= 26 characters
  
  Throws:
  
  ZLogstreamException - if the logstream could not be connected
  
  SecurityException - if a SecurityManager is active and write permission is not granted based on the policy in effect.
  
  See Also:
  
  ZLogstream(String, boolean)
- ZLogstream
  
  public ZLogstream(String name, boolean readOnly) throws ZLogstreamException
  
  Constructor that creates a ZLogstream instance wrapper and connects to the named z/OS Logstream.
  This method calls the IXGCONN macro to create a connection to the named logstream.
  
  Parameters:
  
  name - the name of the z/OS logstream to open, length invalid input: '<'= 26 characters
  
  readOnly - if false the logstream is connected with IXGCONN option AUTH=WRITE
  
  Throws:
  
  ZLogstreamException - if the logstream could not be connected
  
  SecurityException - if a SecurityManager is active and the requested permission (read or write) is not granted based on the policy in effect.
  
  Since:
  
  2.4.0
Method Details
- close
  
  public void close() throws ZLogstreamException
  
  Closes this ZLogstream by disconnecting from the z/OS Logstream.
  This method calls the IXGCONN macro to disconnect from the logstream. This method does nothing if the ZLogstream has already been closed.
  
  Specified by:
  
  close in interface AutoCloseable
  
  Throws:
  
  ZLogstreamException - if there was an error disconnecting.
- isClosed
  
  public boolean isClosed()
  
  Answer true if closed, false if open
  
  Since:
  
  2.4.0
- isOpen
  
  public boolean isOpen()
  
  Answer true if open, false if closed
  
  Since:
  
  2.4.0
- reconnect
  
  public void reconnect() throws ZLogstreamException
  
  Reconnect this logstream.
  This method can be used if for some reason the underlying logstream connection is lost, which can occur if the thread that opened the logstream goes away. If this situation occurs, a ZLogstreamException(RC=8/0x082D) will occur. The write(byte[], int, int, boolean) method will automatically catch this exception and reconnect, but it is the clients responsibility to handle this exception and reconnect for other methods.
  
  Throws:
  
  ZLogstreamException
- write
  
  public void write(byte[] bytes, int offset, int len, boolean synch) throws ZLogstreamException
  
  Writes bytes to the z/OS Logstream.
  This method calls the IXGWRITE macro to write bytes to the logstream. If a RC=8/082D error occurs (Invalid Token), then try to reconnect to the logstream and retry. If a RC=8/0868 (Stage Formatting not Finished) or RC=8/0865 (Staging dataset is full) occurs, then we sleep a little (retryTimeMs) and retry for up to writeRetryCount times.
  Parameters:
  
  bytes - the byte array containing the raw block to write via IXGWRITE
  
  offset - the offset in bytes to beginning of block to write
  
  len - the length of the block to write
  
  synch - if true, use IXGWRITE MODE=SYNC, otherwise MODE=ASYNCNORESPONSE
  
  Throws:
  
  ZLogstreamException - if there was an error from IXGWRITE, or possibly IXGCONN on a reconnect
  
  IllegalStateException - if the logstream is not open in write mode
  
  See Also:
  
  setWriteRetryCount(int)
  
  setRetrySleepTimeMs(long)
  
  reconnect()
- browseStart
  
  public void browseStart(boolean activeOnly, boolean oldest) throws ZLogstreamException
  
  Starts a browse session to the ZLogstream.
  This method calls the IXGBROWSE REQUEST=START macro, with either OLDEST or YOUNGEST option. This method is automatically called by readCursor(byte[], int, boolean) if there is not a browse session.
  
  Parameters:
  
  activeOnly - if true only active blocks are read; otherwise all
  
  oldest - if true, the cursor is placed on the oldest block; if false the youngest
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if a session is already started, or the logstream is not open
  
  Since:
  
  2.4.0
- browseStartSearch
  
  public void browseStartSearch(boolean activeOnly, long timestamp) throws ZLogstreamException
  
  Starts a browse session to the ZLogstream.
  This method calls the IXGBROWSE REQUEST=START macro, with the SEARCH=timestamp option.
  
  Parameters:
  
  activeOnly - if true only active blocks are read; otherwise all
  
  timestamp - the 8-byte TOD clock format timestamp to search for. The setGMT(boolean) option controls whether this is in GMT(UTC) or LOCAL format.
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if a session is already started, or the logstream is not open
  
  Since:
  
  2.4.0
- browseStartBlockID
  
  public void browseStartBlockID(boolean activeOnly, long blockID) throws ZLogstreamException
  
  Starts a browse session to the ZLogstream.
  This method calls the IXGBROWSE REQUEST=START macro, with the STARTBLOCKID=blockID option.
  
  Parameters:
  
  activeOnly - if true only active blocks are read; otherwise all
  
  blockID - the 8-byte block ID to start on.
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if a session is already started, or the logstream is not open
  
  Since:
  
  2.4.0
- browseEnd
  
  public void browseEnd() throws ZLogstreamException
  
  Ends a browse session to the ZLogstream. If this method is called and there is not an existing browse session, this returns without error and is ignored.
  This method calls the IXGBROWSE REQUEST=END macro. This method is automatically called by close()
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
- hasBrowseSession
  
  public boolean hasBrowseSession()
  
  Answer true if there is a browse session; false otherwise
  
  Returns:
  
  boolean
  
  Since:
  
  2.4.0
- deleteAll
  
  public void deleteAll() throws ZLogstreamException
  
  Deletes all blocks in the ZLogstream.
  This method calls the IXGDELET BLOCKS=ALL macro.
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if the logstream is not open in write mode
  
  Since:
  
  2.4.0
- deleteRange
  
  public void deleteRange(long blockID) throws ZLogstreamException
  
  Deletes a range of blocks in the ZLogstream that are older than the given block id.
  This method calls the IXGDELET BLOCKS=RANGE macro.
  
  Parameters:
  
  blockID - the block ID
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if the logstream is not open in write mode
  
  Since:
  
  2.4.0
- readCursor
  
  public int readCursor(byte[] bytes, int offset, boolean forward) throws ZLogstreamException
  
  Reads a record (block) from the logstream at the current cursor position. If this method is called and there is not an existing browse session, one is started automatically by calling browseStart(boolean, boolean). The default browse session properties are activeOnly=true, and oldest=forward.
  This method calls the IXGBROWSE REQUEST=READCURSOR macro.
  Parameters:
  
  bytes - the byte array in which to read the block
  
  offset - the offset in bytes to beginning of block to read
  
  forward - if true, then reads oldest-to-youngest; if false: youngest-to-oldest
  
  Returns:
  
  int the length of the record/block read; -1 if no more available (EOF) or the stream is empty.
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
  
  See Also:
  
  getLastRecordRead(byte[], int)
- readCursor
  
  public int readCursor(byte[] bytes, int offset, boolean forward, boolean multiBlock) throws ZLogstreamException
  
  Reads a record (block) from the logstream at the current cursor position. If this method is called and there is not an existing browse session, one is started automatically by calling browseStart(boolean, boolean). The default browse session properties are activeOnly=true, and oldest=forward.
  This method calls the IXGBROWSE REQUEST=READCURSOR macro.
  Parameters:
  
  bytes - the byte array in which to read the block
  
  offset - the offset in bytes to beginning of block to read
  
  forward - if true, then reads oldest-to-youngest; if false: youngest-to-oldest
  
  multiBlock - if true, then reads multiple blocks (records) in each I/O, and returns one record at a time; if false, reads a single block in each I/O.
  
  Returns:
  
  int the length of the record/block read; -1 if no more available (EOF) or the stream is empty.
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.11
  
  See Also:
  
  getLastRecordRead(byte[], int)
- readBlockID
  
  public int readBlockID(long blockID, byte[] bytes, int offset) throws ZLogstreamException
  
  Reads a record (block) from the logstream with a given blockID. If this method is called and there is not an existing browse session, one is started automatically by calling browseStart(boolean, boolean). The default browse session properties are activeOnly=true, and oldest=true.
  This method calls the IXGBROWSE REQUEST=READBLOCK,BLOCKID= macro.
  Parameters:
  
  blockID - the 8-byte blockID of the block to read
  
  bytes - the byte array in which to read the block
  
  offset - the offset in bytes to beginning of block to read
  
  Returns:
  
  int the length of the record/block read
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
  
  See Also:
  
  getLastRecordRead(byte[], int)
- readSearch
  
  public int readSearch(long timestamp, byte[] bytes, int offset) throws ZLogstreamException
  
  Reads a record (block) from the logstream using a given timestamp as a search argument. If this method is called and there is not an existing browse session, one is started automatically by calling browseStart(boolean, boolean). The default browse session properties are activeOnly=true, and oldest=true.
  This method calls the IXGBROWSE REQUEST=READBLOCK,SEARCH=timestamp macro. The GMT= option is set depending on the current setGMT(boolean) setting.
  Parameters:
  
  timestamp - the 8-byte TOD clock format timestamp
  
  bytes - the byte array in which to read the block
  
  offset - the offset in bytes to beginning of block to read
  
  Returns:
  
  int the length of the record/block read
  
  Throws:
  
  ZLogstreamException
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
  
  See Also:
  
  getLastRecordRead(byte[], int)
- getLastRecordRead
  
  public int getLastRecordRead(byte[] bytes, int offset) throws ZLogstreamException
  
  Gets the last record read. This is useful when a warning-level ZLogstreamException is thrown for a read operation, but the user wishes to obtain the record read and continue processing.
  
  Parameters:
  
  bytes - the byte array in which to read the block
  
  offset - the offset in bytes to beginning of block to read
  
  Returns:
  
  int the length of the record/block read; -1 if no more available (EOF) or the stream is empty.
  
  Throws:
  
  ZLogstreamException
  
  Since:
  
  2.4.0
- getOutputStream
  
  public OutputStream getOutputStream(boolean synch)
  
  Create and return an OutputStream that can be used to write this ZLogstream.
  The OutputStream, although by definition binary, will delineate records written to the logstream by the EBCDIC newline (X'15') separator written to the OutputStream. The close() and flush() methods will also force any pending data to be written as a record.
  Note: z/OS Logstreams do not allow records of zero length, so if such a record is attempted using this interface, a single null (x'00') byte will be written.
  
  Parameters:
  
  synch - if true, logstream records are written synchronously
  
  Returns:
  
  an OutputStream to be used for writing to the logstream
  
  Throws:
  
  IllegalArgumentException - if this logstream is not open in write mode.
  
  Since:
  
  2.4.0
- getOutputStream
  
  public OutputStream getOutputStream(boolean synch, byte separator)
  
  Create and return an OutputStream that can be used to write this ZLogstream.
  The OutputStream, although by definition binary, will delineate records written to the logstream by the given separator byte written to the OutputStream. The close() and flush() methods will also force any pending data to be written as a record.
  Note: z/OS Logstreams do not allow records of zero length, so if such a record is attempted using this interface, a single null (x'00') byte will be written.
  Note: The returned OutputStream is not thread-safe; multi-threaded access should be serialized.
  
  Parameters:
  
  synch - if true, logstream records are written synchronously
  
  separator - the byte value used to delineate logstream records
  
  Returns:
  
  an OutputStream to be used for writing to the logstream
  
  Throws:
  
  IllegalStateException - if this logstream is not open in write mode.
  
  Since:
  
  2.4.0
- getPrintStream
  
  public PrintStream getPrintStream(String encoding, boolean synch) throws UnsupportedEncodingException
  
  Create and return a PrintStream that can be used to write this ZLogstream.
  Note: z/OS Logstreams do not allow records of zero length, so if such a record is attempted using this interface, a single null (x'00') byte will be written.
  Note: The returned PrintStream is not thread-safe; multi-threaded access should be serialized.
  
  Parameters:
  
  encoding - the target encoding used to translate characters and bytes (from the default file encoding). ZUtil.getDefaultPlatformEncoding() may be used to obtain the EBCDIC encoding used by the Java process.
  
  synch - if true, writes to the logstream will be synchronous; otherwise asynchronous
  
  Returns:
  
  a PrintStream to be used for writing to the logstream
  
  Throws:
  
  IllegalStateException - if this logstream is not open in write mode.
  
  UnsupportedEncodingException
  
  Since:
  
  2.4.0
- getInputStream
  
  public InputStream getInputStream()
  
  Create and return an InputStream that can be used to read from this ZLogstream.
  The InputStream, although by definition binary, will delineate records read from the the logstream with an EBCDIC newline (X'15') character.
  Note: The returned InputStream is not thread-safe; multi-threaded access should be serialized.
  
  Returns:
  
  an InputStream which can be used to read from the logstream
  
  Since:
  
  2.4.0
- getInputStream
  
  public InputStream getInputStream(byte separator)
  
  Create and return an InputStream that can be used to read from this ZLogstream.
  The InputStream, although by definition binary, will delineate records read from the the logstream by the given separator byte.
  Note: The returned InputStream is not thread-safe; multi-threaded access should be serialized.
  
  Parameters:
  
  separator - the byte value used to delineate logstream records
  
  Returns:
  
  an InputStream which can be used to read from the logstream
  
  Throws:
  
  IllegalStateException - if this logstream is not open.
  
  Since:
  
  2.4.0
- getName
  
  public String getName()
  
  Answers the name of the logstream
- getToken
  
  public byte[] getToken()
  
  Answers the 16-byte logstream token. Answers null if the logstream is not open.
- getBlockID
  
  public long getBlockID()
  
  Answers as a long the 8-byte blockID from the last block read or written.
  
  Throws:
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
- getTimestamp
  
  public long getTimestamp()
  
  Answers as a long the 8-byte timestamp in TOD clock format from the last block read or written. The GMT flag is used to control whether a GMT(UTC) or LOCAL timestamp is returned.
  Returns:
  
  long the TOD clock format 8-byte timestamp
  
  Throws:
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
  
  See Also:
  
  setGMT(boolean)
- getMaxBlockLength
  
  public int getMaxBlockLength()
  
  Answers the maximum block(record) length for this logstream.
  
  Throws:
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
- getWriteRetryCount
  
  public int getWriteRetryCount()
  
  Answers the default retry count for certain kinds of write errors
  See Also:
  
  write(byte[], int, int, boolean) for more information
- setWriteRetryCount
  
  public void setWriteRetryCount(int writeRetryCount)
  
  Sets the default retry count for certain kinds of write errors
  Throws:
  
  IllegalArgumentException - if argument is negative
  
  See Also:
  
  write(byte[], int, int, boolean) for more information
- getRetrySleepTimeMs
  
  public long getRetrySleepTimeMs()
  
  Answers the time to sleep in ms between retries
- setRetrySleepTimeMs
  
  public void setRetrySleepTimeMs(long retryTimeMs)
  
  Sets the time to sleep in ms between retries
  
  Throws:
  
  IllegalArgumentException - if argument is negative
- isGMT
  
  public boolean isGMT()
  
  Answer true if timestamps are in GMT(UTC). Answer false if timestamps are in LOCAL TOD clock format.
  Throws:
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
  
  See Also:
  
  setGMT(boolean)
- setGMT
  
  public void setGMT(boolean isGMT)
  
  Sets whether timestamps are in GMT(UTC) or LOCAL TOD clock format. The default is false (LOCAL format) if not explicitly set.
  Throws:
  
  IllegalStateException - if the logstream is not open
  
  Since:
  
  2.4.0
  
  See Also:
  
  isGMT()
- toString
  
  public String toString()
  
  Answer a String representation of the receiver
  
  Overrides:
  
  toString in class Object

Class ZLogstream

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

DEFAULT_WRITE_RETRY_COUNT

DEFAULT_RETRY_SLEEP_MS

Constructor Details

ZLogstream

ZLogstream

Method Details

close

isClosed

isOpen

reconnect

write

browseStart

browseStartSearch

browseStartBlockID

browseEnd

hasBrowseSession

deleteAll

deleteRange

readCursor

readCursor

readBlockID

readSearch

getLastRecordRead

getOutputStream

getOutputStream

getPrintStream

getInputStream

getInputStream

getName

getToken

getBlockID

getTimestamp

getMaxBlockLength

getWriteRetryCount

setWriteRetryCount

getRetrySleepTimeMs

setRetrySleepTimeMs

isGMT

setGMT

toString