Exceptions
All the wrapper methods throw COMException. The public "hr" field of COMException holds the COM HRESULT from the underlying COM error that caused the exception.
The COMException class extends Java.io.IOException. This provides convenience when writing Servlet and JSP pages. The standard Servlet signature includes a "throws IOException" clause, which means that the Servlet can choose to not catch IOExceptions and may allow them to bubble up and be reported by the container. By declaring COMException as a subclass of IOException, we enable Servlet authors to easily dispense with the "catch (COMException)" clause if they choose.
Many of the wrapper methods also throw unchecked exceptions (such as OutOfMemoryException and InvalidArgumentException) under a few obvious circumstances. If you attempt to call a method on a wrapper object after calling "release" on that instance, it will throw an InvalidStateException.
Always Release COM Resources Explicitly
As soon as you are finished using a particular instance of the ParameterData, RemoterServer, or ASOSession class, you should explicitly call its "release" method. This will free the associated COM resources.
Although the finalizers for those classes may do this implicitly, the finalizer feature is intended only as a safety net, and you should not rely on it. (Finalizers are not guaranteed to be invoked in a timely fashion, and sometimes may not be invoked at all.) You should always explicitly call the "release" method as soon as you are done with any instance of these wrapper classes.
ParameterData Methods
Because Java is a strongly typed language, the generic SetAttribute andGetAttribute methods of the COM ParameterData class are not applicable. Instead, a collection of type-specific accessor methods is provided.
Although all the Java ParameterData accessor methods make a best effort to convert between the type of the method signature and the declared type of the specified ParameterData attribute, we recommend that attributes be accessed using the Java method that is a best match for the declared type of the attribute. For example, the following pairings are recommended:
ParameterData data values (except for primitive integer or double scalars) are represented in Java as Java object instances (such as String, Integer, Double, Date, BigDecimal, and Byte array). Null object references correspond to NULL 4GL data values, and you may use null object references as a convenient alternative to the setNull and isNull methods.
The full range of Ingres MONEY values (-999,999,999,999,999 to +999,999,999,999.99) is supported. But the maximum precision and scale of the COM DECIMAL type is 28. Therefore, although the Ingres DECIMAL type supports up to 31 digits of precision or scale, only 28 digits can be faithfully marshaled.
Because of the idiosyncrasies of COM DECIMAL conversions, the values returned by getBigDecimal have variable scale. That is, trailing zeros after the decimal point are always truncated and are not reflected in the scale of the BigDecimal instance returned.
To ensure a more consistent handling of scale, an overloaded getBigDecimal method is also provided. This method takes an additional integer parameter (between 0 and 28), which specifies the desired minimum scale of the BigDecimal result. This parameter represents only the minimum scale, and the result will be zero-padded to achieve at least that requested scale. If a value already contains non-zero digits beyond the requested minimum scale, those will not be truncated. (If you want to reduce the scale for a particular application, you may use the Java BigDecimal methods, which provide options to apply whatever type of rounding or truncation is desired.)
The available methods are summarized as follows.
//
// Default constructor.
//
ParameterData()
//
// A convenience constructor that takes a string of attribute declarations,
// and does the declareAttr calls automatically. The declaration string is
// simply a whitespace-delimited list of attrName attrType pairs.
// For human readability, "=" and ";" are also treated as whitespace.
//
ParameterData(String decls)
//
// To release associated COM resources.
//
void release()
//
// Attribute declaration. (Same as the COM DeclareAttribute method.)
//
void declareAttr(String attrName, String attrType)
//
// Type-specific set methods.
//
void setInt(String attrName, int attrValue)
void setDbl(String attrName, double attrValue)
void setInteger(String attrName, Integer attrValue)
void setDouble(String attrName, Double attrValue)
void setString(String attrName, String attrValue)
void setDate(String attrName, Date attrValue)
void setDateWithoutTime(String attrName, Date attrValue)
void setBigDecimal(String attrName, BigDecimal attrValue)
void setByteArray(String attrName, byte[] attrValue)
//
// Special set methods.
//
void setEmpty(String attrName)
void setNull(String attrName)
void setBlankDate(String attrName)
//
// Type-specific get methods.
//
int getInt(String attrName)
double getDbl(String attrName)
Integer getInteger(String attrName)
Double getDouble(String attrName)
String getString(String attrName)
Date getDate(String attrName)
BigDecimal getBigDecimal(String attrName)
BigDecimal getBigDecimal(String attrName, int minScale)
Byte[] getByteArray(String attrName)
//
// Inquiry methods.
//
int lastRow(String attrName)
boolean isEmpty(String attrName)
boolean isNull(String attrName)
boolean isBlankDate(String attrName)
boolean isDateWithoutTime(String attrName)
RemoteServer Methods
The RemoteServer methods correspond in a fairly obvious way to the underlying COM RemoteServer methods.
The "optional" parameters from the COM interface (such as the byValPDO or byRefPDO on the callProc methods) can be specified as "missing" by passing a null Java object reference. Missing "location" or "routing" parameters on the connect and getConnectionDetails methods can be specified either as empty strings or as null object references.
//
// Default constructor.
//
RemoteServer()
//
// To release associated COM resources.
//
void release()
//
// Connection methods.
//
void connect(String akaName, String location, String routing)
void getConnectionDetails(String akaName, String location, String routing)
void disconnect()
//
// SCP calls.
//
void callProc(String procName,
ParameterData byValPDO,
ParameterData byRefPDO)
//
// Property accessors.
//
String getAkaName()
void setAkaName(String akaName)
String getImageFile()
void setImageFile(String imageFile)
String getCmdFlags()
void setCmdFlags(String cmdFlags)
String getLocation()
void setLocation(String location)
String getRouting()
void setRouting(String routing)
int getPrivateOrShared()
void setPrivateOrShared(int iVal)
int getUseASOLib()
void setUseASOLib(int iVal)
boolean isConnected()
//
// Deprecated methods.
//
void initiate(String imgFile,
String cmdFlags,
String location,
String routing,
int privateOrShared)
void terminate()
ASOSession Methods
The ASOSession methods correspond in a fairly obvious way to the underlying COM ASOSession methods.
The "optional" parameters from the COM interface (such as the byValPDO or byRefPDO on the callProc methods) can be specified as "missing" by passing a null Java object reference. Missing "location" or "routing" parameters on the connect method can be specified either as empty strings or as null object references.
//
// Default constructor.
//
ASOSession()
//
// To release associated COM resources.
//
void release()
//
// Connection methods.
//
void connect(String akaName, String location, String routing)
void attachRSO(RemoteServer rso)
void disconnect()
//
// BPM setup and SCP calls.
//
void defineBPM(String userclassname)
void callProc(String procName,
ParameterData byValPDO,
ParameterData byRefPDO)
//
// Property accessors.
//
int getClientType()
void setClientType(int clientType)
int getClientUserId()
void setClientUserId(int userId)
String getClientUserName()
void setClientUserName(String userName)
String getClientIpAddress()
void setClientIpAddress(String ipAddress)
int getOscaErrorNo()
int getOscaErrorType()
String getOscaMsgTxt()
RemoteServer getRSO()
boolean isConnected()
Example
///////////////////////////////////////////////////////////////////////////
//
// The following example illustrates the use of the Java wrapper interface.
//
///////////////////////////////////////////////////////////////////////////
import com.ca.openroad.*;
class comtest {
public static void main(String[] args) throws COMException {
//
// The PDO and RSO are declared here so that they can be accessed
// from both the try block and the finally block.
//
ParameterData pdo = null;
RemoteServer rso = null;
try {
//
// Using the convenience constructor for the PDO.
//
pdo = new ParameterData("hellostring=STRING; counter=INTEGER");
pdo.setString("hellostring", "Hello ASO, from Java!");
pdo.setInt("counter", 99);
rso = new RemoteServer();
rso.connect("comtest", null, null);
rso.callProc("helloworld", null, pdo);
System.out.println(pdo.getString("hellostring"));
System.out.println(pdo.getInt("counter"));
rso.disconnect();
}
finally {
//
// Not catching COMExceptions, just letting them bubble up.
// HOWEVER, we must ensure that the pdo.release() and rso.release()
// get called regardless of exception exits. That's why we need
// to put those in a "finally" block.
//
if (pdo != null)
pdo.release();
if (rso != null)
rso.release();
}
}
}