public class ZLogstream
extends java.lang.Object
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: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.
ZLogstreamException
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 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.
|
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 |
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.
|
public static final int DEFAULT_WRITE_RETRY_COUNT
public static final long DEFAULT_RETRY_SLEEP_MS
public ZLogstream(java.lang.String name) throws ZLogstreamException
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.
name
- the name of the z/OS logstream to open, length <= 26 charactersZLogstreamException
- if the logstream could not be connectedjava.lang.SecurityException
- if a SecurityManager is active and write
permission is not granted based on the policy
in effect.ZLogstream(String, boolean)
public ZLogstream(java.lang.String name, boolean readOnly) throws ZLogstreamException
This method calls the IXGCONN macro to create a connection to the named logstream.
name
- the name of the z/OS logstream to open, length <= 26 charactersreadOnly
- if false the logstream is connected with IXGCONN option AUTH=WRITEZLogstreamException
- if the logstream could not be connectedjava.lang.SecurityException
- if a SecurityManager is active and the requested
permission (read or write) is not granted based on the policy
in effect.public void close() throws ZLogstreamException
This method calls the IXGCONN macro to disconnect from the logstream. This method does nothing if the ZLogstream has already been closed.
ZLogstreamException
- if there was an error disconnecting.public boolean isClosed()
public boolean isOpen()
public void reconnect() throws ZLogstreamException
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.
ZLogstreamException
public void write(byte[] bytes, int offset, int len, boolean synch) throws ZLogstreamException
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.
bytes
- the byte array containing the raw block to write via IXGWRITEoffset
- the offset in bytes to beginning of block to writelen
- the length of the block to writesynch
- if true, use IXGWRITE MODE=SYNC, otherwise MODE=ASYNCNORESPONSEZLogstreamException
- if there was an error from IXGWRITE, or possibly IXGCONN on a reconnectjava.lang.IllegalStateException
- if the logstream is not open in write modesetWriteRetryCount(int)
,
setRetrySleepTimeMs(long)
,
reconnect()
public void browseStart(boolean activeOnly, boolean oldest) throws ZLogstreamException
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.
activeOnly
- if true only active blocks are read; otherwise alloldest
- if true, the cursor is placed on the oldest block; if false the youngestZLogstreamException
java.lang.IllegalStateException
- if a session is already started, or the logstream is not openpublic void browseStartSearch(boolean activeOnly, long timestamp) throws ZLogstreamException
This method calls the IXGBROWSE REQUEST=START macro, with the SEARCH=timestamp option.
activeOnly
- if true only active blocks are read; otherwise alltimestamp
- the 8-byte TOD clock format timestamp to search for.
The setGMT(boolean)
option controls whether this is in GMT(UTC) or LOCAL format.ZLogstreamException
java.lang.IllegalStateException
- if a session is already started, or the logstream is not openpublic void browseStartBlockID(boolean activeOnly, long blockID) throws ZLogstreamException
This method calls the IXGBROWSE REQUEST=START macro, with the STARTBLOCKID=blockID option.
activeOnly
- if true only active blocks are read; otherwise allblockID
- the 8-byte block ID to start on.ZLogstreamException
java.lang.IllegalStateException
- if a session is already started, or the logstream is not openpublic void browseEnd() throws ZLogstreamException
This method calls the IXGBROWSE REQUEST=END macro. This method is automatically called by close()
ZLogstreamException
java.lang.IllegalStateException
- if the logstream is not openpublic boolean hasBrowseSession()
public void deleteAll() throws ZLogstreamException
This method calls the IXGDELET BLOCKS=ALL macro.
ZLogstreamException
java.lang.IllegalStateException
- if the logstream is not open in write modepublic void deleteRange(long blockID) throws ZLogstreamException
This method calls the IXGDELET BLOCKS=RANGE macro.
blockID
- the block IDZLogstreamException
java.lang.IllegalStateException
- if the logstream is not open in write modepublic int readCursor(byte[] bytes, int offset, boolean forward) throws ZLogstreamException
browseStart(boolean, boolean)
.
The default browse session properties are activeOnly=true, and oldest=forward.
This method calls the IXGBROWSE REQUEST=READCURSOR macro.
bytes
- the byte array in which to read the blockoffset
- the offset in bytes to beginning of block to readforward
- if true, then reads oldest-to-youngest; if false: youngest-to-oldestZLogstreamException
java.lang.IllegalStateException
- if the logstream is not opengetLastRecordRead(byte[], int)
public int readBlockID(long blockID, byte[] bytes, int offset) throws ZLogstreamException
browseStart(boolean, boolean)
.
The default browse session properties are activeOnly=true, and oldest=true.
This method calls the IXGBROWSE REQUEST=READBLOCK,BLOCKID= macro.
blockID
- the 8-byte blockID of the block to readbytes
- the byte array in which to read the blockoffset
- the offset in bytes to beginning of block to readZLogstreamException
java.lang.IllegalStateException
- if the logstream is not opengetLastRecordRead(byte[], int)
public int readSearch(long timestamp, byte[] bytes, int offset) throws ZLogstreamException
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.
timestamp
- the 8-byte TOD clock format timestampbytes
- the byte array in which to read the blockoffset
- the offset in bytes to beginning of block to readZLogstreamException
java.lang.IllegalStateException
- if the logstream is not opengetLastRecordRead(byte[], int)
public int getLastRecordRead(byte[] bytes, int offset) throws ZLogstreamException
ZLogstreamException
is thrown
for a read operation, but the user wishes to obtain the record read and continue
processing.bytes
- the byte array in which to read the blockoffset
- the offset in bytes to beginning of block to readZLogstreamException
public java.io.OutputStream getOutputStream(boolean synch)
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.synch
- if true, logstream records are written synchronouslyjava.lang.IllegalArgumentException
- if this logstream is not open in write mode.public java.io.OutputStream getOutputStream(boolean synch, byte separator)
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.synch
- if true, logstream records are written synchronouslyseparator
- the byte value used to delineate logstream recordsjava.lang.IllegalStateException
- if this logstream is not open in write mode.public java.io.PrintStream getPrintStream(java.lang.String encoding, boolean synch) throws java.io.UnsupportedEncodingException
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.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 asynchronousjava.lang.IllegalStateException
- if this logstream is not open in write mode.java.io.UnsupportedEncodingException
public java.io.InputStream getInputStream()
public java.io.InputStream getInputStream(byte separator)
separator
- the byte value used to delineate logstream recordsjava.lang.IllegalStateException
- if this logstream is not open.public java.lang.String getName()
public byte[] getToken()
public long getBlockID()
java.lang.IllegalStateException
- if the logstream is not openpublic long getTimestamp()
java.lang.IllegalStateException
- if the logstream is not opensetGMT(boolean)
public int getMaxBlockLength()
java.lang.IllegalStateException
- if the logstream is not openpublic int getWriteRetryCount()
public void setWriteRetryCount(int writeRetryCount)
java.lang.IllegalArgumentException
- if argument is negativewrite(byte[], int, int, boolean) for more information
public long getRetrySleepTimeMs()
public void setRetrySleepTimeMs(long retryTimeMs)
java.lang.IllegalArgumentException
- if argument is negativepublic boolean isGMT()
java.lang.IllegalStateException
- if the logstream is not opensetGMT(boolean)
public void setGMT(boolean isGMT)
java.lang.IllegalStateException
- if the logstream is not openisGMT()
public java.lang.String toString()
toString
in class java.lang.Object