src.com.ibm.as400.access.ListUtilities Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jt400 Show documentation
Show all versions of jt400 Show documentation
The Open Source version of the IBM Toolbox for Java
///////////////////////////////////////////////////////////////////////////////
//
// JTOpen (IBM Toolbox for Java - OSS version)
//
// Filename: ListUtilities.java
//
// The source code contained herein is licensed under the IBM Public License
// Version 1.0, which has been approved by the Open Source Initiative.
// Copyright (C) 1997-2001 International Business Machines Corporation and
// others. All rights reserved.
//
///////////////////////////////////////////////////////////////////////////////
package com.ibm.as400.access;
import java.io.IOException;
/**
Provides utilities for retrieving lists of objects.
**/
class ListUtilities
{
// Default setting for listWaitTimeout property.
// This is the maximum amount of time to wait for a list to complete before giving up.
private static final int DEFAULT_MAX_WAIT_TIME = 60; // 60 seconds
// The length of the "List information" structure parameter.
static final int LIST_INFO_LENGTH = 80; // 80 bytes
//
// Possible values for the "Information complete indicator" field:
// Whether all requested information has been returned.
//
// Complete and accurate information.
// All of the requested records have been returned in the receiver variable.
static final char INFORMATION_COMPLETE = 'C';
// Incomplete information.
// An interruption causes the receiver variable to contain incomplete information.
static final char INFORMATION_INTERRUPTED = 'I';
// Partial and accurate information.
// Partial information is returned when the receiver variable is full and not all of the records requested are returned.
static final char INFORMATION_PARTIAL = 'P';
//
// Possible values for the "List status indicator" field:
// The status of building the list.
//
// The building of the list is pending.
static final char LIST_PENDING = '0';
// Note: For a synchronous request, we'd probably never get this status back.
// The list is in the process of being built.
static final char LIST_BEING_BUILT = '1';
// Note: Even though we wouldn't normally expect this status for synchronous requests,
// we've occasionally gotten it for requests that list massively large numbers of objects.
// The list has been completely built.
static final char LIST_COMPLETE = '2';
// An error occurred when building the list.
// The next call to the Get List Entries (QGYGTLE) API will cause the error to be signaled
// to the caller of the QGYGTLE API.
static final char LIST_ERROR = '3';
// The list is primed and ready to be built.
// The list will be built asynchronously by a server job,
// but the server job has not necessarily started building the list yet.
static final char LIST_PRIMED = '4';
// Given the current selection criteria and information requested,
// there is too much data to be returned.
static final char LIST_TOO_MUCH_DATA = '5';
/**
Returns the value of the "list status indicator" field returned by QGY* API's.
@param listInformation The "list information" structure returned by a QGY* API (that requested the building of a list).
@return The converted value of the "list status information" field. Possible values are '0', '1', '2', '3', '4', or '5'.
@throws ErrorCompletingRequestException if the List Status Information is other than "complete", "being built", or "pending"; or if the Information Complete Indicator is "interrupted".
**/
private static char checkListStatus(byte[] listInformation)
throws ErrorCompletingRequestException
{
char infoCompleteIndicator, listStatusIndicator;
try {
// Convert the two CHAR(1) fields from EBCDIC to Unicode.
byte[] arry = { listInformation[16] }; // ICI is at offset 16
infoCompleteIndicator = new CharConverter(37).byteArrayToString(arry,0,1).charAt(0);
arry[0] = listInformation[30]; // LSI is at offset 30
listStatusIndicator = new CharConverter(37).byteArrayToString(arry,0,1).charAt(0);
}
catch (java.io.UnsupportedEncodingException e) { // will never happen
throw new InternalErrorException(InternalErrorException.UNEXPECTED_EXCEPTION, e);
}
switch (listStatusIndicator)
{
case LIST_COMPLETE:
break; // This is the indicator that we normally expect.
case LIST_BEING_BUILT:
case LIST_PENDING:
// These status values are unusual, but aren't necessarily error conditions
// (even if we indicated we wanted the list built synchronously).
if (Trace.traceOn_) Trace.log(Trace.DIAGNOSTIC, "List status indicator:", listStatusIndicator);
break;
default: // any other status
StringBuffer msg = new StringBuffer("Unable to synchronously build object list on server.");
try {
msg.append("\n List status indicator: " + listStatusIndicator);
msg.append("\n Info complete indicator: " + infoCompleteIndicator);
msg.append("\n Total records: " +
BinaryConverter.byteArrayToInt(listInformation, 0));
msg.append("\n Records returned: " +
BinaryConverter.byteArrayToInt(listInformation, 4));
}
catch (Throwable t) {} // will never happen
finally {
Trace.log(Trace.ERROR, msg.toString());
}
throw new ErrorCompletingRequestException(ErrorCompletingRequestException.AS400_ERROR);
}
if (infoCompleteIndicator == INFORMATION_INTERRUPTED)
{
Trace.log(Trace.ERROR, "Info complete indicator: " + infoCompleteIndicator);
throw new ErrorCompletingRequestException(ErrorCompletingRequestException.AS400_ERROR);
}
return listStatusIndicator;
}
/**
Closes the list on the system. This releases any system resources previously in use by the list.
@exception AS400SecurityException If a security or authority error occurs.
@exception ErrorCompletingRequestException If an error occurs before the request is completed.
@exception InterruptedException If this thread is interrupted.
@exception IOException If an error occurs while communicating with the system.
@exception ObjectDoesNotExistException If the object does not exist on the system.
**/
static void closeList(AS400 system, byte[] listHandle) throws AS400SecurityException, ErrorCompletingRequestException, InterruptedException, IOException, ObjectDoesNotExistException
{
if (listHandle == null) return;
ProgramParameter[] parameters = new ProgramParameter[]
{
new ProgramParameter(listHandle),
new ErrorCodeParameter()
};
ProgramCall pc = new ProgramCall(system, "/QSYS.LIB/QGY.LIB/QGYCLST.PGM", parameters); // not a threadsafe API
if (!pc.run())
{
throw new AS400Exception(pc.getMessageList());
}
}
// Calls QGYGTLE to get the current "list information" on the progress of list-building.
private static byte[] refreshListInformation(byte[] listHandle, ProgramCall pgmCall)
throws AS400SecurityException, ErrorCompletingRequestException, InterruptedException, IOException, ObjectDoesNotExistException
{
if (pgmCall.getParameterList().length == 0)
{
ProgramParameter[] parameters = new ProgramParameter[]
{
// Receiver variable, output, char(*).
new ProgramParameter(8), // minimum length is 8 bytes
// Length of receiver variable, input, binary(4).
new ProgramParameter(BinaryConverter.intToByteArray(8)),
// Request handle, input, char(4).
new ProgramParameter(listHandle),
// List information, output, char(80).
new ProgramParameter(LIST_INFO_LENGTH),
// Number of records to return, input, binary(4).
// '0' indicates: "Only the list information is returned and no actual list entries are returned."
new ProgramParameter(new byte[] { 0x00, 0x00, 0x00, 0x00 } ),
// Starting record, input, binary(4).
// '0' indicates: "The list information should be returned to the caller immediately."
// '-1' indicates: "The whole list should be built before the list information is returned to the caller."
//new ProgramParameter(new byte[] { 0x00, 0x00, 0x00, 0x00} ),
new ProgramParameter(new byte[] { (byte)0xFF, (byte)0xFF, (byte)0xFF, (byte)0xFF} ),
// Error code, I/0, char(*).
new ErrorCodeParameter()
};
try { pgmCall.setProgram("/QSYS.LIB/QGY.LIB/QGYGTLE.PGM", parameters); }
catch (java.beans.PropertyVetoException pve) {} // will never happen
}
if (!pgmCall.run()) {
throw new AS400Exception(pgmCall.getMessageList());
}
return pgmCall.getParameterList()[3].getOutputData(); // the "List Information" structure
}
/**
Calls QGYGTLE (repeatedly if necessary) until the specified list is completely built.
For use following calls to APIs that return an "Open list information format" structure.
@param system The system where the list is being built.
@param listHandle The list handle for the list.
@param listInformation The "list information" structure returned by a QGY* API (that requested the building of a list).
@return The final "list information" structure.
**/
static byte[] waitForListToComplete(AS400 system, byte[] listHandle, byte[] listInformation)
throws AS400SecurityException, ErrorCompletingRequestException, InterruptedException, IOException, ObjectDoesNotExistException
{
ProgramCall pgmCall = null; // for calling QGYGTLE
final int waitSecondsPerIteration = 1; // wait 1 second between retries
int accumulatedWaitSeconds = 0; // accumulated total wait time
int maxWaitSeconds = getMaxWaitTime();
char listStatus = checkListStatus(listInformation);
while (listStatus != LIST_COMPLETE &&
accumulatedWaitSeconds < maxWaitSeconds)
{
try {
Thread.sleep(waitSecondsPerIteration*1000); // wait for 1 second
accumulatedWaitSeconds += waitSecondsPerIteration;
}
catch (InterruptedException ie) {} // ignore
if (Trace.traceOn_) Trace.log(Trace.DIAGNOSTIC, "Calling QGYGTLE.PGM to wait for list to be completely built.");
// See if the building of the list (on the server) has completed yet.
// Note: Even when we specify '-1' for the "number of records" parameter on the QGYOxxx request (to build the list synchronously), we can encounter a "list being built" status, if the request is building a massively large list of objects.
if (pgmCall == null) pgmCall = new ProgramCall(system);
listInformation = refreshListInformation(listHandle, pgmCall);
listStatus = checkListStatus(listInformation);
}
if (listStatus != LIST_COMPLETE) {
Trace.log(Trace.ERROR, "The building of the list did not complete within the specified time limit of " + maxWaitSeconds + " seconds.");
throw new ErrorCompletingRequestException(ErrorCompletingRequestException.AS400_ERROR);
}
return listInformation;
}
/**
Calls QGYGTLE, repeatedly if necessary, to retrieve the specified number of list entries.
This assumes that the list has previously been built on the system.
@param system The system where the list has been built.
@param listHandle The list handle for the list.
@param lengthOfReceiverVariable The value of the "Length of receiver variable" field.
@param number The number of list entries to return.
@param listOffset The offset into the list (0-based).
@param outputListInfoContainer Container in which to receive the generated "List information" structure. Ignored if null.
**/
static byte[] retrieveListEntries(AS400 system, byte[] listHandle, int lengthOfReceiverVariable, int number, int listOffset, Object[] outputListInfoContainer)
throws AS400SecurityException, ErrorCompletingRequestException, InterruptedException, IOException, ObjectDoesNotExistException
{
ProgramParameter[] parameters = new ProgramParameter[]
{
// Receiver variable, output, char(*).
new ProgramParameter(lengthOfReceiverVariable),
// Length of receiver variable, input, binary(4).
new ProgramParameter(BinaryConverter.intToByteArray(lengthOfReceiverVariable)),
// Request handle, input, char(4).
new ProgramParameter(listHandle),
// List information, output, char(80).
new ProgramParameter(LIST_INFO_LENGTH),
// Number of records to return, input, binary(4).
new ProgramParameter(BinaryConverter.intToByteArray(number)),
// Starting record, input, binary(4). (1-based: The first record is record number '1')
// '0' indicates that the list information should be returned to the caller immediately. The special value 0 is only allowed when the number of records to return parameter is zero.
// '-1' indicates that the whole list should be built before the list information is returned to the caller.
new ProgramParameter(BinaryConverter.intToByteArray(listOffset == -1 ? -1 : listOffset+1)),
// Error code, I/0, char(*).
new ErrorCodeParameter()
};
ProgramCall pc = new ProgramCall(system, "/QSYS.LIB/QGY.LIB/QGYGTLE.PGM", parameters); // not a threadsafe API
byte[] listInformation;
int recordsReturned;
// Call QGYGTLE, to retrieve the list entries.
// If we discover that the "receiver variable" was too small, try calling again, with progressively larger "receiver variable".
do
{
if (pc.run())
{
listInformation = parameters[3].getOutputData();
checkListStatus(listInformation);
recordsReturned = BinaryConverter.byteArrayToInt(listInformation, 4);
}
else // the call to QGYGTLE failed
{
listInformation = null;
recordsReturned = 0;
// See if the call failed because of a too-small receiver variable.
AS400Message[] messages = pc.getMessageList();
// GUI0002 means that the receiver variable was too small to hold the list.
if (!messages[0].getID().equals("GUI0002")) {
throw new AS400Exception(messages);
}
}
if (recordsReturned < number) // we didn't get as many records as we requested
{
if (listInformation != null)
{
// See if we've reached the end of the list.
int totalRecords = BinaryConverter.byteArrayToInt(listInformation, 0); // The total number of records available in the list.
int firstRecordInReceiverVariable = BinaryConverter.byteArrayToInt(listInformation, 36);
// Note: The "First record in receiver variable" field is 1-based; that is, the first record is record number '1' (rather than '0').
if ((firstRecordInReceiverVariable + recordsReturned) > totalRecords) {
// All the records in the list have been returned, so don't keep requesting more.
break;
}
}
if (Trace.traceOn_) Trace.log(Trace.DIAGNOSTIC, "Retrieved messages, records returned: " + recordsReturned + ", number:", number);
if (recordsReturned < 0)
{ // This will never happen, but satisfy the static code analyzer.
throw new InternalErrorException(InternalErrorException.UNKNOWN, "Records returned: " + recordsReturned, null);
}
// Try again, with a larger "receiver variable".
lengthOfReceiverVariable *= 1 + number / (recordsReturned + 1);
if (Trace.traceOn_) Trace.log(Trace.DIAGNOSTIC, "Updated length: ", lengthOfReceiverVariable);
parameters[0] = new ProgramParameter(lengthOfReceiverVariable);
parameters[1] = new ProgramParameter(BinaryConverter.intToByteArray(lengthOfReceiverVariable));
}
} while (recordsReturned < number);
// If the caller specified a non-null 'outputListInfo' parameter, copy the "list information" structure into it, to pass it back to the caller.
if (outputListInfoContainer != null && listInformation != null)
{
outputListInfoContainer[0] = listInformation;
}
return parameters[0].getOutputData(); // the contents of the "receiver variable" field
}
// Returns the maximum number of seconds to wait for a list to be built.
private static int getMaxWaitTime()
{
int listWaitTimeout = DEFAULT_MAX_WAIT_TIME;
String propVal = SystemProperties.getProperty(SystemProperties.LIST_WAIT_TIMEOUT);
if (propVal != null)
{
try {
listWaitTimeout = Integer.parseInt(propVal);
if (listWaitTimeout == 0) listWaitTimeout = Integer.MAX_VALUE; // '0' means "no limit"
}
catch (Exception e) {
if (Trace.traceOn_) Trace.log(Trace.WARNING, "Error retrieving listWaitTimeout property value:", e);
}
}
return listWaitTimeout;
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy