ZLogstream (IBM JZOS Toolkit API)

java.lang.Object
- com.ibm.jzos.ZLogstream

```
public class ZLogstream
extends java.lang.Object
```
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.
Since:

2.1.0

See Also:

ZLogstreamException

Field Summary

Fields
Modifier and Type	Field and Description
`static long`	`DEFAULT_RETRY_SLEEP_MS` The time, in milliseconds to sleep between retries
`static int`	`DEFAULT_WRITE_RETRY_COUNT` The count for retries certain write errors

Constructor Summary

Constructors
Constructor and Description
`ZLogstream(java.lang.String name)` Constructor that creates a ZLogstream instance wrapper and connects to the named z/OS Logstream.
`ZLogstream(java.lang.String name, boolean readOnly)` Constructor that creates a ZLogstream instance wrapper and connects to the named z/OS Logstream.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`java.io.InputStream`	`getInputStream()` Create and return an InputStream that can be used to read from this ZLogstream.
`java.io.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.
`java.lang.String`	`getName()` Answers the name of the logstream
`java.io.OutputStream`	`getOutputStream(boolean synch)` Create and return an OutputStream that can be used to write this ZLogstream.
`java.io.OutputStream`	`getOutputStream(boolean synch, byte separator)` Create and return an OutputStream that can be used to write this ZLogstream.
`java.io.PrintStream`	`getPrintStream(java.lang.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
`java.lang.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 Detail
  - 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 Detail
  - ZLogstream
```
public ZLogstream(java.lang.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 <= 26 characters
    
    Throws:
    
    ZLogstreamException - if the logstream could not be connected
    
    java.lang.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(java.lang.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 <= 26 characters
    
    readOnly - if false the logstream is connected with IXGCONN option AUTH=WRITE
    
    Throws:
    
    ZLogstreamException - if the logstream could not be connected
    
    java.lang.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 Detail
  - 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.
    
    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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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
    
    java.lang.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 java.io.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:
    
    java.lang.IllegalArgumentException - if this logstream is not open in write mode.
    
    Since:
    
    2.4.0
  - getOutputStream
```
public java.io.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:
    
    java.lang.IllegalStateException - if this logstream is not open in write mode.
    
    Since:
    
    2.4.0
  - getPrintStream
```
public java.io.PrintStream getPrintStream(java.lang.String encoding,
                                          boolean synch)
                                   throws java.io.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:
    
    java.lang.IllegalStateException - if this logstream is not open in write mode.
    
    java.io.UnsupportedEncodingException
    
    Since:
    
    2.4.0
  - getInputStream
```
public java.io.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 java.io.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:
    
    java.lang.IllegalStateException - if this logstream is not open.
    
    Since:
    
    2.4.0
  - getName
```
public java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.IllegalStateException - if the logstream is not open
    
    Since:
    
    2.4.0
    
    See Also:
    
    isGMT()
  - toString
```
public java.lang.String toString()
```
    Answer a String representation of the receiver
    
    Overrides:
    
    toString in class java.lang.Object

Methods inherited from class java.lang.Object

DEFAULT_WRITE_RETRY_COUNT

DEFAULT_RETRY_SLEEP_MS

ZLogstream

ZLogstream

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