com.ibm.jzos
Class ZLogstream

java.lang.Object
  extended by com.ibm.jzos.ZLogstream

public class ZLogstream
extends java.lang.Object

A JNI Wrapper for z/OS Logstreams, supporting IXGCONN (connect) and IXGWRITE (write) services.

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 a Java security manager is active, it is used to check permissions for 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.

See Also:
ZLogstreamException

Field Summary
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
ZLogstream(java.lang.String name)
          Constructor that creates a ZLogstream instance wrapper and connects to the named z/OS Logstream.
 
Method Summary
 void close()
          Closes this ZLogstream by disconnecting from the z/OS Logstream.
 java.lang.String getName()
          Answers the name of the logstream
 long getRetrySleepTimeMs()
           
 byte[] getToken()
          Answers the 16-byte logstream token
 int getWriteRetryCount()
           
 void setRetrySleepTimeMs(long retryTimeMs)
           
 void setWriteRetryCount(int writeRetryCount)
           
 java.lang.String toString()
          Answer a String representation of the receiver
 void write(byte[] bytes, int offset, int len, boolean sync)
          Writes bytes to the ZLogstream by disconnecting from the z/OS Logstream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, 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.

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 the required permission is not granted based on the policy in effect. The
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.

write

public void write(byte[] bytes,
                  int offset,
                  int len,
                  boolean sync)
           throws ZLogstreamException
Writes bytes to the ZLogstream by disconnecting from 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 occurs (Stage Formatting not Finished), 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
sync - if true, use IXGWRITE MODE=SYNC, otherwise MODE=ASYNCNORESPONSE
Throws:
ZLogstreamException - if there was an error from IXGWRITE, or possibly IXGCONN on a reconnect
See Also:
setWriteRetryCount(int), setRetrySleepTimeMs(long)

getName

public java.lang.String getName()
Answers the name of the logstream


getToken

public byte[] getToken()
Answers the 16-byte logstream token


getWriteRetryCount

public int getWriteRetryCount()
Returns:
int the default retry count for certain kinds of write errors

setWriteRetryCount

public void setWriteRetryCount(int writeRetryCount)
Parameters:
writeRetryCount - the default retry count for certain kinds of write errors

getRetrySleepTimeMs

public long getRetrySleepTimeMs()
Returns:
long the time to sleep in ms between retries

setRetrySleepTimeMs

public void setRetrySleepTimeMs(long retryTimeMs)
Parameters:
retryTimeMs - the time to sleep in ms between retries

toString

public java.lang.String toString()
Answer a String representation of the receiver

Overrides:
toString in class java.lang.Object