Skip Navigation Links | |
Exit Print View | |
Developing OTDs for Oracle Java CAPS Application Adapters Java CAPS Documentation |
Developing OTDs for Application Adapters
Date and Time Stamp Requirements
Installing SAP JCo for SAP BAPI
To Install SAP JCo on Windows 32
SAP JCo and SAP IDoc Class Library Installation
To Download the SAP Java IDoc Class Library
To Create IDoc OTDs Directly From SAP
To Create IDOC OTDs From a Description File
Exporting the IDOC File from SAP
To Download the IDoc Description File From SAP
Saving the IDoc Description File (After 4.6)
To Save the IDoc Description File From SAP
Configuring Your System Before Creating the OTD
Configuring NetBeans to Work with Siebel
Installing seebeyond.sif for Siebel 7.5.x
Installing SiebelMessage XSD Generation Process.xml for Siebel 7.7 and 7.8.x
Encoding Behavior for Redefinitions
enableUnmarshalValidation(boolean enable) Method
marshal(String charset) Method
marshal(OtdOutputStream out) Method
marshal(OtdOutputStream out, String charset) Method
unmarshal(OtdInputStream in) Method
unmarshal(OtdInputStream in, String charset) Method
unmarshal(byte[] in, String charset) Method
unmarshalFromString(String in) Method
Creating an Oracle Applications OTD
To Create an Oracle Applications OTD
Exposed Oracle Applications OTD Nodes
SWIFT Alliance Gateway Adapter OTD Features
Generating DTDs from PeopleTools 8.13
Generating and Publishing an XML Test Message
To generate a PeopleSoft XML message
Extracting and Viewing the XML Test Message
Generating a DTD for the XML File
When an OTD is built from a copybook file, it creates an OTD which contains methods that may be used with the converted contents of the copybook business object.
Figure 17 Sample Copybook OTD
The figure above shows the Copybook Converter OTD built from the sample copybook qan3glr1.cobol. The OTD has a node for each of the business processes that may be performed on the converted copybook. The unmarshal method allows business processes to flow data into the copybook OTDs and access contents field-by-field.
The Object Type Definitions (OTDs) created by the COBOL Copybook Converter provide the methods that you can use to extract content from 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.
This section addresses the concerns of global behavior, effects, and assumptions inherent to most methods.
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.
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 from 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.
The following methods are the root-level methods provided:
The enableUnmarshalValidation(boolean enable) method causes the OTD to validate data flow during an unmarshal call.
Table 1 enableUnmarshalValidation(boolean enable) 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 2 marshal() 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 3 marshal(String charset) 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 4 marshal(OtdOutputStream out) 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 5 marshal(OtdOutputStream out, String charset) 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 6 marshalToString 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 7 reset() Method
|
The resetHigh() method initializes the entire storage space of the OTD to high bit values; each byte is initialized to 0xFF.
Table 8 resetHigh() Method
|
The resetLow() method initializes the OTD storage space to low bit values; each byte is initialized to 0x0.
Table 9 resetLow() 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 10 retrieveEncoding() 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 11 unmarshal(byte[] in) Method
|
The 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 12 unmarshal(OtdInputStream in) 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 13 unmarshal(OtdInputStream 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 14 unmarshal(byte[] in, String charset) 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 15 unmarshalFromString(String in) 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 behavior 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 16 useEncoding(String enc) Method
|
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 17 Datum Method Forms
|
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.
When using BPM to process COBOL copybooks, the operations in Table are available.
Table 18 BPEL COBOL Operations
|
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.