Developing OTDs for Application Adapters

COBOL Copybook OTD Methods

The Object Type Definitions (OTDs) created by the COBOL Copybook Converter provide the method that you can use to extract or insert content into OTDs.

This section describes the COBOL copybook methods (operations) that are available for you to use in the source code for the Collaborations or Business Activities.

OTD Method Guidelines

This section addresses the concerns of global behavior, effects, and assumptions inherent to most methods.

Encoding Behavior for Redefinitions

The unmarshal and marshal methods of a COBOL Copybook OTD (with the exception of the marshalToString and unmarshalFromString) have been reimplemented to heed the OTD structure’s data type information. When data flows into or out of the OTD, character set encoding is applied only to the portions of the data that fall on or draw from OTD fields corresponding to items in the Copybook specification that store character data (i.e., usage display items, whether implicitly or explicitly specified). Data for other types of OTD fields are not subject to charset encoding, since these fields are capable of containing binary (non-character) data.

An ambiguity arises when an OTD field, corresponding to a usage display item, is also the object of redefinition(s) in the Copybook. Redefined items may have alternate, multiple storage types, and to deal with such an item, the OTD must decide which one of the multiple definition is in effect at the time of unmarshaling or marshaling, in relation to the available data. The current implementation of COBOL Copybook OTDs resolve this ambiguity by ignoring redefinitions. The decision whether or not to apply encoding to a field is based solely on the item’s original storage specification in the Copybook.

DBCS Items

COBOL Copybook OTDs do not support any particular Double Byte Character Set (DBCS) encoding. When inserted into DBCS nodes, it will not perform inspections of data to determine what specific DBCS encoding is used by character codes or byte sequences (e.g., discerning between a double-byte and a multi-byte encoding). As a consequence:

DBCS items are represented in the OTD by Java byte array nodes, and their content will be treated as binary "blobs" with the following rules:
- If content is set directly to a DBCS node, it is stored as-is.
- If the content is retrieved directly from the DBCS node, the content that was originally set is also returned as-is.
- If content is unmarshaled via the OTD root, the portion corresponding to the DBCS node is stored as-is. It should be noted however, that correctness of the aggregate input is the responsibility of the root-level unmarshal call (e.g., do not use unmarshalFromString if the OTD contains DBCS items).
- If the OTD’s content is marshaled, the portion corresponding to the DBCS node is yielded as-is, and is excluded from any character set transcoding that character data nodes of the OTD may be subjected to.
Copybook OTDs will not auto-truncate DBCS data. Since the OTD cannot know the specific DBCS encoding of the data, it cannot correctly truncate it at the correct character boundaries. If the content which is set directly to a DBCS node exceeds the item’s width, the OTD will raise an exception.

Root-level Methods

The following methods are the root-level methods provided:

enableUnmarshalValidation(boolean enable) Method

The enableUnmarshalValidation(boolean enable) method causes the OTD to validate data flow during an unmarshal call.

Table 1–1 enableUnmarshalValidation(boolean enable) Method


Syntax	Throws	Examples
void enableUnmarshalValidation(boolean enable)	None.	// enable validation during unmarshal // call to unmarshal may raise an exception if content is not compatible byte[] content = ... OTD_1.enableUnmarshalValidation(true); OTD_1.unmarshal(content); // disable validation during unmarshal // call to unmarshal will not raise data-related exceptions // instead, data-related exceptions may/will occur when // accessing specific nodes with invalid data. byte[] content = ... OTD_1.enableUnmarshalValidation(false); OTD_1.unmarshal(content)

marshal() Method

The marshal() method serializes the OTD’s content as an array of bytes. The content is encoded with the OTD’s current encoding, which is the encoding specified when data was last unmarshaled (see setEncoding() and unmarshal() for additional details). If no data was unmarshaled prior to a marshal call, then the OTD defaults to EBCDIC CP037 encoding. If the OTD content is incompatible with the current encoding (this can happen when data was unmarshaled with a different encoding than the current one), a com.stc.otd.runtime.MarshalException occurs.

Table 1–2 marshal() Method


Syntax	Throws	Examples
byte [] marshal()	MarshalException, IOException, UnsupportedEncodingException	// populate OTD and marshal entire content in EBCDIC OTD_1.setField1(... OTD_1.setField2(... ... byte[] output = OTD_1.marshal(); // write ASCII data to OTD // edit some fields // marshal OTD data (still ASCII) byte[] content = ... OTD_1.unmarshal(content, "US-ASCII"); OTD_1.setField9(... OTD_1.setField10(... byte[] output = OTD_1.marshal(); // write ASCII data to OTD // edit some fields // marshal OTD data using different encoding (may fail depending on data) byte[] content = ... OTD_1.unmarshal(content, "US-ASCII"); OTD_1.setField9(... OTD_1.setField10(... OTD_1.useEncoding("CP277"); byte[] output = OTD_1.marshal();

marshal(String charset) Method

The marshal(String charset) method serializes the content of the OTD as an array of bytes. The content is encoded using the user-specified character set. The encoding specified in this call acts as a temporary override to the OTD’s current encoding, but does not become the current encoding (see setEncoding and unmarshal documentation for information). If the OTD content is not compatible with the current encoding (this can happen if data was unmarshaled using an encoding different from the current one), com.stc.otd.MarshalException occurs. If the specified charset value does not name a supported character set, a java.io.UnsupportedEncodingException is generated.

Table 1–3 marshal(String charset) Method


Syntax	Throws	Examples
byte[] marshal(String charset)	MarshalException, IOException, UnsupportedEncodingException	byte[] content = cocoOtd.marshal("cp037"); // retrieve OTD content as EBCDIC databyte[] content = cocoOtd.marshal("US-ASCII"); // retrieve OTD content as ASCII data

marshal(OtdOutputStream out) Method

The marshal(OtdOutputStream out) method serializes the content of the OTD and writes it to the supplied output stream object. The output is encoded using the same user-specified encoding used when the data was last unmarshaled (see setEncoding and unmarshal documentation for additional details). If no data was unmarshaled prior to the call to marshal, then EBCDIC CP037 encoding is used. If the OTD content is not compatible with the current encoding (this can happen if the data was unmarshaled using an encoding different from the current one), com.stc.otd.MarshalException occurs. A java.io.IOException is generated if an output error occurs in attempting to write data to the stream object.

Table 1–4 marshal(OtdOutputStream out) Method


Syntax	Throws	Examples
void marshal(OtdOutputStream out)	MarshalException, IOException, UnsupportedEncodingException

marshal(OtdOutputStream out, String charset) Method

The marshal(OtdOutputStream out, String charset) method flows data out from the OTD to the supplied stream object, using the specified charset encoding. The given encoding acts as a temporary override to the OTD’s current encoding, it does not become the current encoding (see setEncoding and unmarshal documentation for information).

If the specified charset is not compatible with the OTD content (this can happen when the data was unmarshaled to the OTD using a different encoding), com.stc.otd.runtime.MarshalException occurs. If the encoding is not supported or recognized, java.io.UnsupportedEncodingException is generated.

Table 1–5 marshal(OtdOutputStream out, String charset) Method


Syntax	Throws	Examples
void marshal(OtdOutputStream stream, String charset)	MarshalException, IOException, UnsupportedEncodingException

marshalToString() Method

The marshalToString() method serializes the content of the OTD to a String object. The String is created by decoding the byte data with the OTD’s current encoding, which is the encoding specified when data was last unmarshaled (see setEncoding and unmarshal documentation for additional details). If no data was unmarshaled prior to a marshal call, then the OTD defaults to EBCDIC CP037 encoding. Only use this method with copybook OTDs built from copybooks comprised solely of usage display entries. Using this method on OTDs designed to hold binary data (e.g., packed decimal, internal decimal) may invalidate the data, because portions of the binary content may not have a suitable mapping to UTF-8. A java.io.UnsupportedEncodingException may occur if the current encoding (i.e., the encoding used by the last unmarshal call) is not capable of encoding the data. This is possible because certain charset encodings in Java are not two-way encodings (encodings that can decode or encode, but not both).

Table 1–6 marshalToString Method


Syntax	Throws	Examples
String marshalToString()	MarshalException, IOException, UnsupportedEncodingException

reset() Method

The reset() method initializes the storage space of the OTD as follows:

alphanumeric fields (PIC X) - blank spaces (EBCDIC value 0x40)
numeric fields (PIC 9) - binary zero
packed decimal fields - signed-trailing packed binary zero

Table 1–7 reset() Method


Syntax	Throws	Examples
void reset()	None.

resetHigh() Method

The resetHigh() method initializes the entire storage space of the OTD to high bit values; each byte is initialized to 0xFF.

Table 1–8 resetHigh() Method


Syntax	Throws	Examples
void resetHigh()	None.

resetLow() Method

The resetLow() method initializes the OTD storage space to low bit values; each byte is initialized to 0x0.

Table 1–9 resetLow() Method


Syntax	Throws	Examples
void resetLow()	None.

retrieveEncoding() Method

The retrieveEncoding() method returns the canonical name of the current OTD encoding. The default current OTD encoding is "CP037" until it is changed by a successful useEncoding call, or by a call to one of the encoding-specifiable unmarshal methods. The canonical name may differ from the one used previously to set the current encoding. See the Java 2 API documentation for java.nio.charset. Charset for more information.

Table 1–10 retrieveEncoding() Method


Syntax	Throws	Examples
String retrieveEncoding()	None.

unmarshal(byte[] in) Method

The unmarshal(byte[] in) method deserializes the given input into an internal data tree. Data flowed to the OTD using this method must use EBCDIC CP037 encoding. This method sets the OTD’s current encoding to EBCDIC CP037, which is used when data is subsequently marshaled without an overriding encoding; e.g., as allowed in a marshal(OtdOutputStream, String) call.

Table 1–11 unmarshal(byte[] in) Method


Syntax	Throws	Examples
void unmarshal(byte[] in)	UnmarshalException, IOException

unmarshal(OtdInputStream in) Method

Th unmarshal(OtdInputStream in) method populates the OTD using the supplied OtdInputStream object as the data source. The supplied object must be an opened stream with available data. A com.stc.otd.runtime.UnmarshalException is generated if the data obtained from the stream is incompatible with the OTD, and a java.io.IOException is generated if any other input error occurs in attempting to read data from the stream object. The stream object must flow data encoded in EBCDIC CP037. This method sets the OTD’s current encoding to EBCDIC CP037, which is used when data is subsequently marshaled without overriding encoding; e.g., as allowed in a marshal (OtdOutputStream, String) call.

Table 1–12 unmarshal(OtdInputStream in) Method


Syntax	Throws	Examples
void unmarshal(OtdInputStream in)	UnmarshalException, IOException

unmarshal(OtdInputStream in, String charset) Method

The unmarshal(OtdInputStream in, String charset) method flows data to the OTD from the supplied Stream object. The stream must be open and have available data. The charset argument specifies the encoding of the stream data. The specified encoding becomes the current encoding of the OTD and is used when data is subsequently marshaled without overriding encoding; e.g., as allowed in a marshal(OtdOutputStream, String) call.

If the stream data is incompatible with the OTD, a com.stc.otd.runtime.UnmarshalException is generated. If the stream data cannot be read, a java.io.IOException is generated. If the charset value does not name a supported charset, or if it names a supported charset with one-way encoding (capable of decoding or encoding, but not both), a java.io.UnsupportedEncodingException is generated.

Table 1–13 unmarshal(OtdInputStream in, String charset) Method


Syntax	Throws	Examples
void unmarshal(OtdInputStream in, String charset)	UnmarshalException, IOException, UnsupportedEncodingException

unmarshal(byte[] in, String charset) Method

This method populates the OTD using the data supplied in the byte array in. The charset argument specifies the encoding of the given data. The specified encoding becomes the current encoding of the OTD, and is used when data is subsequently marshaled without an overriding encoding; e.g., as allowed in a marshal (OtdOutputStream, String) call. If the specified charset value does not name a supported character set or names a supported charset with one-way encoding (one that can decode or encode, but not both), a java.io.UnsupportedEncodingException is generated.

Table 1–14 unmarshal(byte[] in, String charset) Method


Syntax	Throws	Examples
void unmarshal(byte[] in, String charset)	Unmarshal Exception, IOException, UnsupportedEncodingException	byte[] bytes = ...cocoOtd.unmarshal(bytes, "cp037"); // Interpret bytes content as EBCDIC datacocoOtd.unmarshal(bytes, "US-ASCII"); // Interpret bytes content as ASCII data

unmarshalFromString(String in) Method

The unmarshalFromString(String in) method populates the OTD using the specified String object as the input source. This method is useful only to unmarshal data to copybook OTDs comprised solely of character-data records (entries specified implicitly or explicitly as USAGE DISPLAY). The current OTD encoding (see setEncoding and unmarshal document for additional details) is used to encode the String’s bytes.

Table 1–15 unmarshalFromString(String in) Method


Syntax	Throws	Examples
void unmarshalFromString(String in)	UnmarshalException, IOException

useEncoding(String enc) Method

Use the useEncoding(String enc) method to designate a particular encoding to be used as the OTD’s current encoding. The current OTD encoding is used when the OTD is marshaled without an overriding encoding, which is permitted for the marshal (OtdOutputStream, String) method.

An OTD’s current encoding is initially EBCDIC (CP037) when it is instantiated. There are two ways to change it:

Unmarshaling the data, whereby the data’s stated encoding becomes the current encoding.
Using this method to specify it.

Changing the encoding through the use of this method causes reset() to be subsequently (and automatically) called, causing the OTD’s existing content to be erased. This behaviour exists to avoid situations where data, successfully unmarshaled with one charset, fails to marshal under a different charset, due to the absence of codepoint mappings between the two encodings. Use the marshal(String) method when data, which flowed in using a charset, must then be flowed out with a different charset.

If the specified encoding is the same as the current OTD encoding, the call returns without affecting the OTD’s state (i.e., reset() is not called) and the data and current encoding will remain unchanged.

If the specified encoding is not supported, or is not a two-way encoding (one that can decode or encode, but not both), a java.io.UnsupportedEncodingException is thrown.

Table 1–16 useEncoding(String enc) Method


Syntax	Throws	Examples
void useEncoding(String enc)	UnsupportedEncodingException

Non-Root Methods

Every leaf node in a COBOL Copybook OTD represents an elementary item in the Copybook source. For every given leaf node, the OTD provides “getter” and “setter” methods of which the return type and input types depend on the data type and usage type specified in the copybook for the elementary item to which the node corresponds.

For a given non-repeating leaf node named Datum, the following method forms are provided, where T is determined from the follow table.

T getDatum()
void setDatum(T)

Table 1–17 Datum Method Forms


Data Types	Display	COMP or COMP-4	COMP-1	COMP-2	COMP-3	COMP-5	INDEX
Alphabetic For example: PIC AAA	String
Alphanumeric For example: PIC X9	String		String	String
Alphanumeric edited For example: PIC XB9	String
Numeric edited For example: PIC ZZZ99	String
DBCS For example PIC GGBGG	byte[]
External floating point For example: PIC +9V99E+99	BigDecimal
Numeric integer (9 digits or less)	int	int			int		int
Numeric floating point (COMP-1 or COMP-2 items)	BigDecimal
Numeric Integer (10 to 18 digits)	long	long			long	long
Numeric integer (19 digits or more)	BigDecimal	Big Decimal			Big Decimal	Big Decimal

For repeating leaf nodes, these two alternative methods are provided:

T getDatum(int i)
void setDatum(int i, T)

where i is expected to be a value from 0, representing the ordinal of the desired repetition instance, and where T is determined as previously described.

BPEL Operations

When using eInsight to process COBOL copybooks, the operations in Table are available.

Table 1–18 BPEL COBOL Operations


eInsight Operation	Activity
Marshal	Allows you to marshal an OTD instance to a string.
MarshalToBytes	Marshals an OTD instance (or OTD tree) to byte array using current encoding (CP037).
MarshalToString	Marshals an OTD instance (or OTD tree) to string using current encoding (CP037).
Unmarshal	This operation is retained for purposes of compatibility with the previous release of the COBOL Copybook Converter. The Unmarshal operation allows you to select unmarshaling from byte array or from string.
UnmarshalFromBytes	Unmarshals data from byte array into an OTD instance.
UnmarshalFromString	Unmarshals data from string into an OTD instance.

Note –

It is recommended that you use the Marshal and Unmarshal methods since they allow for more control over the output data. Both methods are available for purposes of increased compatibility.