Root-level Methods

The following methods are the root-level methods provided:

• enableUnmarshalValidation(boolean enable) Method

• marshal() Method

• marshal(String charset) Method

• marshal(OtdOutputStream out) Method

• marshal(OtdOutputStream out, String charset) Method

• marshalToString() Method

• reset() Method

• resetHigh() Method

• resetLow() Method

• retrieveEncoding() Method

• unmarshal(byte[] in) Method

• unmarshal(OtdInputStream in) Method

• unmarshal(OtdInputStream in, String charset) Method

• unmarshal(byte[] in, String charset) Method

• unmarshalFromString(String in) Method

• useEncoding(String enc) Method

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:

1. Unmarshaling the data, whereby the data’s stated encoding becomes the current encoding.

2. 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