Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |
eLink Adapter for R/3 ALE Doc Home   |   BEA eLink Adapter for R/3 ALE User Guide   |   Previous Topic   |   Next Topic   |   Contents   |   Index

This topic describes how to integrate SAP R/3 with SAP application linking and embedding (ALE) technology in the BEA eLink environment. It includes the following main sections:

• ALE Integration

• Processing eLink-to-R/3 IDOCs

• Processing R/3-to-eLink IDOCs

For information about setting up ALE processing, see the following:

• Configuring ALE Integration.

• Configuring R/3 Connections.

The following topics provide important conceptual information about integrating with ALE:

• Usage Scenarios for ALE Integration

• Information Flow for ALE Integration

• Key ALE Concepts

Usage Scenarios for ALE Integration

Common ALE integration implementations of eLink Adapter for R/3 ALE include:

• Integrating R/3 and non-R/3 systems by using eLink Platform (TUXEDO) and eLink Adapter for R/3 ALE to exchange intermediate documents (IDOCs) and non-IDOCs across application and platform boundaries. For a discussion of IDOCs, see "Key ALE Concepts" later in this section.

• Communicating among R/3 systems by using eLink Platform (TUXEDO) and eLink Adapter for R/3 ALE to transport IDOCs reliably and efficiently among R/3 logical systems.

Integrating R/3 and Non-R/3 Systems

Figure 2-1 shows how eLink Adapter for R/3 ALE, in conjunction with BEA eLink Data Integration, can be used to integrate R/3 with non-R/3 systems:

In this scenario, these BEA components provide communication and data transformation services that enable the exchange of IDOC (R/3) and non-IDOC (non-R/3) data between R/3 and non-R/3 systems.

Figure 2-2 shows how eLink Platform (called TUXEDO in this and most other diagrams) and eLink Adapter for R/3 ALE can transport IDOCs among R/3 logical systems:

In this scenario, eLink Adapter for R/3 ALE and TUXEDO provide reliable and efficient communication services that enable the transport of IDOC packets between R/3 logical systems, thereby reducing the load on SAP communication services.

Figure 2-3 shows the information flow for the two main ALE processes: R/3-to-eLink (outbound process) and eLink-to-R/3 (inbound process):

• eLink-to-R/3 is a TUXEDO server that submits IDOC packets to R/3. eLink-to-R/3 receives each IDOC packet as an FML32 message buffer (forwarded from a TUXEDO queue), adds the IDOC data for R/3, and submits the IDOC packet to R/3 via transactional RFC (tRFC). See Information Flow for eLink-to-R/3 IDOCs later in this section for more information.

• R/3-to-eLink is a TUXEDO server that receives IDOC packets from R/3 via transactional RFC (tRFC). R/3-to-eLink adds each IDOC packet data into an FML32 message buffer and queues it into one or more TUXEDO queues. See "Information Flow for R/3-to-eLink IDOCs" later in this section for more information.

Key ALE Concepts

Two key concepts are used in ALE processing:

• Intermediate Documents (IDOCs)

• Transaction IDs (TIDs)

Intermediate Documents (IDOCs)

In the SAP R/3 environment, an intermediate document (IDOC) is a container for distributing R/3 application data among R/3 logical systems and for exchanging R/3 application data with non-R/3 systems.

In ALE processing, an IDOC consists of two types of records:

• The control record uniquely identifies the IDOC, specifying such information as the identity of the sender, the target (logical system ID), message type, IDOC-type, and status. The length of a control record is 464 bytes for version 3.x IDOCs and 524 bytes for version 4.x IDOCs.

• The data records uniquely identify a segment that contains application data. The length of a data record is 1055 bytes for version 3.x IDOCs and 1063 bytes for version 4.x IDOCs, which consists of a 55-byte header and a 1000-byte segment. The header identifies the segment type and hence the segment's structure.

Each IDOC is a sequential buffer that contains one control record and one or more data records, as shown in Figure 2-4:

For eLink-to-R/3 IDOCs, eLink-to-R/3 validates the size and structure of control records and data records. For each IDOC, eLink-to-R/3 also verifies that the DOCNUM data in the control record matches the DOCNUM data in associated data records.

An IDOC packet is a message that contains one or more individual IDOCs, as shown in Figure 2-5:

The R/3 System separately maintains status information about the creation, receipt, and processing of IDOCs. See your SAP R/3 documentation for more information about IDOCs.

In the TUXEDO environment, IDOC packets are transmitted in FML32 messages. These field definitions are specified in the cr3_ale.fml file, as described in FML32 Field Definitions in Introducing BEA eLink Adapter for R/3 ALE.

R/3 assigns a unique transaction ID (TID) to each IDOC packet it processes. R/3 uses TIDs to manage transactional integrity:

• eLink-to-R/3. For eLink-to-R/3 IDOC packets, R/3 uses TIDs to guarantee receipt once and only once.

• R/3-to-eLink. For R/3-to-eLink IDOC packets, R/3 uses TIDs to guarantee delivery once and only once.

In the TUXEDO environment, R/3-to-eLink and eLink-to-R/3 monitor TIDs through the use of TID log files. See "Managing Transactional Integrity for eLink-to-R/3 IDOCs" and "Managing Transactional Integrity for R/3-to-eLink IDOCs" for more information.

The following topics describe how to process eLink-to-R/3 IDOCs using the eLink-to-R/3 server. It includes the following topics:

• eLink-to-R/3 Server

• Information Flow for eLink-to-R/3 IDOCs

• Splitting eLink-to-R/3 IDOC Packets

• Managing Transactional Integrity for eLink-to-R/3 IDOCs

• Managing Transactional Integrity for eLink-to-R/3 IDOCs

• Handling Problems with eLink-to-R/3 IDOCs

eLink-to-R/3 must be properly configured before it can process IDOCs. See "Configuring the eLink-to-R/3 Server" in Configuring ALE Integration, for more information.

eLink-to-R/3 is a TUXEDO server that submits IDOC packets to R/3. eLink-to-R/3 receives each IDOC packet as an FML32 message buffer (forwarded from a TUXEDO queue) and it submits the IDOC packet to R/3 via tRFC. eLink-to-R/3 uses a TID log to track the TIDs associated with IDOC packets to guarantee delivery to R/3 once and only once. The name of the executable for eLink-to-R/3 is cr3alein.

eLink-to-R/3 provides two services that process eLink-to-R/3 IDOC packets:

Service Name	Description
CR3_SUBMIT	Receives an incoming FML32 buffer containing an IDOC packet from a TUXEDO queue; validates the IDOC packet data; obtains a TID from R/3 for the IDOC packet; binds the TID into the IDOC packet; and queues the IDOC message into the CR3_IDOC_IN queue.
CR3_IDOC_IN	Receives the IDOC packet from the CR3_IDOC_IN queue; encodes the IDOC data for R/3; and submits the IDOC packet to R/3 for processing.

The eLink-to-R/3 uses the following FML32 field definitions in IDOC messages:

Table 2-1 FML32 Fields for eLink-to-R/3 Messages

Field	Data Type	Description
CR3_IDOC	string	Contains an IDOC packet consisting of one or more IDOCs.
CR3_TARGET_ID	string	Contains a data-dependent routing value. Required even if it contains only a dummy value.
CR3_RFC_TID	string	Contains the transaction ID (TID) for the IDOC packet.
CR3_IDOC_CONTROL	string	Contains one or more control records for the IDOC packet.
CR3_IDOC_DATA	string	Contains one or more data records for the IDOC packet.

These fields are defined in the cr3_ale.fml file, as described in FML32 Field Definitions in Introducing BEA eLink Adapter for R/3 ALE.

Figure 2-6 shows the information flow for eLink-to-R/3 IDOCs:

The information flow for eLink-to-R/3 proceeds in the following sequence:

1. One or more instances of eLink-to-R/3 (a TUXEDO server) start up.

2. An application (a TUXEDO application, eLink Data Integration, or some other tool) constructs an FML32 buffer containing IDOC data and queues it into the CR3_SUBMIT queue.

3. The TMQFORWARD TUXEDO service dequeues the IDOC message from the CR3_SUBMIT queue and submits it to the CR3_SUBMIT service of the eLink-to-R/3 server.

4. The CR3_SUBMIT service receives the IDOC message and validates its contents:

   • It checks for the existence of the CR3_TARGET_ID field in the message buffer.

   • It checks the structure and size of the control record and associated data records.

   • Within the IDOC, it compares the DOCNUM fields in the control record and associated data records to verify that they match.

5. After validation, the CR3_SUBMIT service takes one of the following actions:

   • If the IDOC message fails validation, CR3_SUBMIT sends it to the error queue (CR3_ERROR queue).

   • If the IDOC message passes validation, CR3_SUBMIT obtains a TID from R/3, binds the TID to the IDOC packet in the FML32 buffer by encoding the TID in the message buffer (the CR3_RFC_TID field), and queues the IDOC message into the CR3_IDOC_IN queue.

6. TMQFORWARD dequeues the IDOC message from the CR3_IDOC_IN queue and submits it to the CR3_IDOC_IN service of the eLink-to-R/3 server.

7. The CR3_IDOC_IN service submits the IDOC packet and TID to R/3.

eLink-to-R/3 uses a TID log file to manage transactional integrity. See "Managing Transactional Integrity for R/3-to-eLink IDOCs" later in this section for more information.

By default, the eLink-to-R/3 server passes an IDOC message containing multiple IDOCs to R/3 in a single packet. You can configure eLink-to-R/3 to split IDOC messages containing multiple IDOCs into individual IDOC messages, each with its own TID. For example, if an IDOC message contains six IDOCs, eLink-to-R/3 can create six separate IDOC packets, each containing a single IDOC and associated with a unique TID. Figure 2-7 shows splitting IDOC packets and queueing them into the CR3_IDOC_IN queue:

Splitting IDOC packets provides additional flexibility for processing eLink-to-R/3 IDOCs. However, this configuration can also increase load on the R/3 System and reduce throughput performance. For example, an IDOC packet containing six IDOCs requires two RFC calls: one to request the TID and another to submit the IDOC packet to R/3. Six IDOC packets containing a single IDOC each, however, requires twelve separate RFC calls: six to request TIDs and six to submit each IDOC packet to R/3.

See "Splitting eLink-to-R/3 IDOC Packets Containing Multiple IDOCs" in Configuring ALE Integration, for instructions.

The eLink-to-R/3 server manages transactional integrity for eLink-to-R/3 IDOCs to guarantee that it delivers an IDOC packet to R/3 once and only once. R/3 uses the TID to guarantee that it processes the IDOC packet exactly once. If an attempt to submit an IDOC packet to R/3 fails, eLink-to-R/3 retries using the same TID. eLink-to-R/3 uses a TID log file to track the transaction IDs (TIDs) that R/3 assigns to each eLink-to-R/3 IDOC packet. See "Transaction IDs (TIDs)" earlier in this document for an introduction to TIDs.

The TID log file used with eLink-to-R/3 IDOCs contains information about TIDs that eLink-to-R/3 has received and processed. Each row in the TID file represents the TID for a separate IDOC packet and contains three fixed-position columns of information:

Table 2-2 Columns in the TID Log File for eLink-to-R/3 IDOCs

Column	Description
Date-Time Stamp	Date and time at which the state of this TID was last updated in the TID log file.
TID	TID that R/3 assigned to the IDOC packet.
Status	One of the following strings: CREATED indicates that eLink-to-R/3 has successfully associated a TID with the IDOC packet and queued it into the CR3_IDOC_IN queue. CONFIRMED indicates that eLink-to-R/3 has successfully passed the IDOC packet onto R/3.

The following example shows a sample TID file for eLink-to-R/3:

Tue Apr 27 14:27:40 1999  0A0201FD03F937262C600004  CONFIRMED

Tue Apr 27 14:29:39 1999  0A0201FD03F937262CD90007  CONFIRMED

Tue Apr 27 14:46:58 1999  0A0201FD03F9372630E8000A  CONFIRMED

Tue Apr 27 15:52:30 1999  0A0201FD041637263FC60013  CONFIRMED

The CR3_ALEIN_TID_FILE environment variable specifies the location of the TID log file for eLink-to-R/3. See "Setting Environment Variables for eLink-to-R/3" in Configuring ALE Integration, for more information.

Use the cr3tidmanager program to manage the size and number of entries kept in TID files. See "Configuring the TID File Manager" in Configuring ALE Integration, of this guide.

Figure 2-8 shows how eLink-to-R/3 uses the TID log file to manage transactional integrity for eLink-to-R/3 IDOCs:

The eLink-to-R/3 IDOC process involves two transaction boundaries:

• The first transaction boundary ensures that the CR3_SUBMIT service has bound the IDOC packet and TID together and has successfully queued the FML32 message buffer into the CR3_IDOC_IN queue. This transaction is the entry point for any external application that submits an IDOC packet to the eLink-to-R/3 server.

• The second transaction boundary ensures that the CR3_IDOC_IN service has successfully submitted the IDOC packet and associated TID to R/3. This transaction is an internal process that submits the IDOC packet and TID to R/3 until it succeeds.

First Transaction Boundary

For the first transaction boundary, the information flow proceeds in the following sequence:

1. TMQFORWARD starts a new TUXEDO transaction, unqueues an IDOC message from the CR3_SUBMIT queue, and submits the IDOC message to the CR3_SUBMIT service of the eLink-to-R/3 server.

2. After validating the IDOC data, the CR3_SUBMIT service requests a TID from R/3.

3. R/3 generates a unique TID and returns it to the CR3_SUBMIT service.

4. The CR3_SUBMIT service opens the TID log file.

5. The CR3_SUBMIT service searches for the TID in the TID log file:

   • If the TID is not found, the CR3_SUBMIT service appends a new entry for the TID, writes the date-time stamp, TID, and state (CREATED) in the entry, and then proceeds to the next step.

   • If the TID is found, R/3-to-eLink requests a new TID from R/3 because it is already processing the current TID.

6. The CR3_SUBMIT service binds the TID to the IDOC message (by encoding the TID in the CR3_RFC_TID field in the buffer) and assigns the message to the CR3_IDOC_IN queue.

7. The CR3_SUBMIT service returns TPSUCCESS or TPFAIL, as appropriate, to TMQFORWARD.

8. TMQFORWARD closes the transaction, committing the transaction if TPSUCCESS was returned, or rolling back the transaction if TPFAIL was returned. If the transaction is rolled back, the IDOC message remains in the CR3_SUBMIT queue.

For the second transaction boundary, the information flow proceeds in the following sequence:

1. TMQFORWARD starts a new transaction, dequeues an IDOC message from the CR3_IDOC_IN queue, and submits the IDOC message to the CR3_IDOC_IN service of the eLink-to-R/3 server.

2. The CR3_IDOC_IN service encodes the IDOC packet for R/3 and submits the IDOC packet to R/3.

3. If the IDOC packet is successfully sent, the CR3_IDOC_IN service opens the TID log file, finds the TID, and updates the date-time stamp and state (CONFIRMED) in the log file.

4. CR3_IDOC_IN returns the result of the send request (TPSUCCESS or TPFAIL) to TMQFORWARD.

5. TMQFORWARD closes the transaction, committing the transaction if TPSUCCESS was returned, or rolling back the transaction if TPFAIL was returned. If the transaction is rolled back, the IDOC message remains in the CR3_IDOC_IN queue.

eLink-to-R/3 uses TUXEDO's transaction management capabilities to ensure transactional integrity for eLink-to-R/3 IDOCs. The following table lists problems that can occur with eLink-to-R/3 IDOCs:

Table 2-3 Handling Problems with eLink-to-R/3 IDOCs

Problem	Description
Invalid IDOC structure	If an IDOC packet fails validation, the CR3_SUBMIT service queues the FML32 message into the CR3_ERROR queue and returns TPSUCCESS to TMQFORWARD.
No CR3_TARGET_ID	If an IDOC message contains no CR3_TARGET_ID field, the CR3_SUBMIT service queues the FML32 message into the CR3_ERROR queue and returns TPSUCCESS to TMQFORWARD.
TID Not received from R/3	If R/3 does not return a TID, CR3_SUBMIT returns TPFAIL to TMQFORWARD, and TMQFORWARD rolls back the transaction.
Send attempt to R/3 failed	If the CR3_IDOC_IN service does not successfully send the IDOC packet to R/3 (for example, the R/3 System is down), CR3_IDOC_IN returns TPFAIL to TMQFORWARD, and TMQFORWARD rolls back the transaction. The IDOC packet remains in the CR3_IDOC_IN queue until a subsequent send attempt succeeds.

Note: You must write an application to explicitly unqueue and handle messages in the CR3_ERROR queue.

The following topics describe how to process R/3-to-eLink IDOCs using the R/3-to-eLink server:

• R/3-to-eLink Server

• Information Flow for R/3-to-eLink IDOCs

• Splitting R/3-to-eLink IDOC Packets Into Individual IDOCs

• Queuing R/3-to-eLink IDOCs Into Multiple Queues

• Managing Data-Dependent Routing (DDR)

• Load Balancing High Volumes of R/3-to-eLink IDOCs

• Registering Multiple Program IDs

• Managing Transactional Integrity for R/3-to-eLink IDOCs

• Handling Problems with R/3-to-eLink IDOCs

The R/3-to-eLink server must be configured properly, before it can process R/3-to-eLink IDOCs. For information about setting up R/3-to-eLink, see Configuration Quick Reference.

R/3-to-eLink is a TUXEDO server that receives IDOC packets from R/3 via transactional RFC (tRFC). R/3-to-eLink encodes each IDOC packet into an FML32 message buffer and queues it into a TUXEDO queue. R/3-to-eLink uses a TID log file to track the IDOC packets that it processes to ensure that it queues an IDOC packet from R/3 once and only once. The name of the executable for R/3-to-eLink is cr3aleout.

R/3-to-eLink uses the following FML32 field definitions in IDOC messages:

Table 2-4 FML32 Fields for R/3-to-eLink Messages

Field	Data Type	Description
CR3_IDOC	string	Contains a string of one or more IDOCs.
CR3_TARGET_ID	string	Data-dependent routing value.
MERCATOR_FV_IN	string	Either Y or N. See the BEA eLink Data Integration Option v1.x for more information.

Figure 2-9 illustrates the information flow for R/3-to-eLink:

The information flow proceeds in the following sequence:

1. One or more instances of the R/3-to-eLink server start up and register a program ID with the R/3 gateway. R/3-to-eLink runs in register mode and listens for IDOC packets associated with that program ID on the registered port. This program ID corresponds to a particular RFC destination.

2. R/3 submits an IDOC packet to a port (rather than to a file or another R/3 System) for a specific RFC destination.

3. R/3 sends the IDOC packet to an instance of R/3-to-eLink that is registered on the program ID of the RFC destination.

4. R/3-to-eLink receives the IDOC packet and processes the IDOC data according to the way that R/3-to-eLink is configured, or more specifically, according to the destination mapping environment variables in the environment file.

   If the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable is set to "Y," then R/3-to-eLink splits IDOC packets containing multiple IDOCs into separate IDOC messages, each containing a single IDOC. If the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable is set to "N," then R/3-to-eLink does not split IDOC packets. It sends packets to the default queue. This process is described in detail in "Splitting R/3-to-eLink IDOC Packets Into Individual IDOCs."

   If the IDOC packets are split (CR3_ALE_DEFAULT_IDOC_SPLIT = "Y"), R/3-to-eLink uses the settings in the environment file to determine the target queue for each IDOC as well as other processing options. See "Queuing R/3-to-eLink IDOCs Into Multiple Queues" for more information.

R/3-to-eLink uses a TID log file to manage transactional integrity. See "Managing Transactional Integrity for R/3-to-eLink IDOCs" later in this topic for more information.

You can configure R/3-to-eLink to split IDOC packets containing multiple IDOCs into separate IDOC messages, each containing a single IDOC. By default, R/3-to-eLink encodes the entire IDOC packet into a single occurrence of the CR3_IDOC field in the message buffer, then queues the entire IDOC packet into a single message and places it in the default queue, which is defined in the CR3_ALE_DEFAULT_TARGET_ID environment variable. If you set the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable to "Y," however, R/3-to-eLink will split the IDOC packet into individual IDOCs, then queue the individual IDOCs into queues as described in "Queuing R/3-to-eLink IDOCs Into Multiple Queues."

R/3-to-eLink is configured to use the R/3-to-eLink environment file (cr3aleout.env) so that it can place IDOC messages into different target queues, manage data-dependent routing, and group similar IDOCs into larger IDOCs. R/3-to-eLink makes routing and grouping decisions about individual IDOCs according to two settings specified in an IDOC's control record: the logical system ID of the target R/3 System and the IDOC message type.

If the logical system ID and message type in an individual IDOC's control record (an individual IDOC from the one that has been split) match the logical system ID and message type found in an IDOC section of cr3aleout.env, R/3-to-eLink queues it using the settings specified in the matching IDOC section of cr3aleout.env. If a matching IDOC section cannot be found, R/3-to-eLink will queue it in the default queue. This is shown in Figure 2-10:

See "Setting Environment Variables for R/3-to-eLink" in Configuring ALE Integration, in this guide for more information about setting the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable.

The environment file, cr3aleout.env, is used to configure the environment for the R/3-to-eLink server. IDOC types are listed in the CR3_IDOC_LIST environment variable, and specific settings are made for each IDOC type. Each known IDOC type is provided with its own section of the environment file. The destination mapping settings in these sections specify the following information for each IDOC type:

• Logical system ID of the target R/3 logical system (environment variable: RECIEVER_PARTNER_NUMBER).

• Message type specified in the IDOC (environment variable: MESSAGE_TYPE).

• Compress flag indicating whether to compress IDOC packets (with matching logical system and IDOC message type values) into a single IDOC message in the queue (environment variable: COMPRESS).

• Target ID representing the data-dependent routing value (environment variable: ROUTING).

• Destination queue space name (environment variable: QUEUE_SPACE).

• Destination queue name (environment variable: QUEUE_NAME).

For each outbound R/3-to-eLink IDOC, R/3-to-eLink searches the environment file for the logical system ID of the target R/3 System (RECIEVER_PARTNER_NUMBER) and IDOC message type (MESSAGE_TYPE) specified in the outbound IDOC's control record. If it finds an IDOC section that matches the logical system ID and message type specified in the IDOC's control record, R/3-to-eLink assigns the IDOC to the destination queue space and queue specified in the matching IDOC section of the environment file. R/3-to-eLink also processes the IDOC according to the COMPRESS flag and the Target ID (ROUTING) settings in that section.

You use the COMPRESS environment variable specified in each IDOC section of the environment file to combine outbound IDOCs with matching combinations of logical system ID and IDOC message type into a single IDOC. For each outbound IDOC whose control record matches an IDOC section with regard to logical system ID and message type. If the COMPRESS variable is set to "Y", then R/3-to-eLink aggregates this IDOC with other matching IDOCs into a single, larger IDOC that it then assigns to the appropriate target queue. If the COMPRESS variable is set to "N", then R/3-to-eLink queues each outbound IDOC separately.

You use the Target ID (ROUTING environment variable) specified in each IDOC's section of the environment file to associate an IDOC with a data-dependent routing (DDR) value. For each outbound IDOC whose control record matches an IDOC section with regard to logical system ID and message type, R/3-to-eLink adds the specified ROUTING value to the CR3_TARGET_ID FML32 field of the outbound IDOC. If no matching IDOC section is found in the environment file for that outbound IDOC, then R/3-to-eLink encodes the default DDR value, which is defined in the CR3_ALE_DEFAULT_TARGET_ID environment variable.

See "Setting the Default Data-Dependent Routing Value" in Configuring ALE Integration, in this guide for more information.

The first example shows how the R/3-to-eLink server processes an IDOC packet that contains a single IDOC. Suppose the environment file contains the settings shown in Listing 2-1.

CR3_IDOC_LIST=MaterialMaster
[CR3_IDOC=MaterialMaster]
RECIEVER_PARTNER_NUMBER=LOGSYS1
MESSAGE_TYPE=MATMAS
COMPRESS=Y
ROUTING=DDR1
QUEUE_SPACE=QS1
QUEUE_NAME=Q1

The control record in an R/3-to-eLink IDOC named MaterialMaster specifies a target logical ID (RECIEVER_PARTNER_NUMBER) of LOGSYS and a message type (MESSAGE_TYPE) of MATMAS. Figure 2-11 shows how R/3-to-eLink would process this IDOC packet according to the settings in the sample environment file section:

In this scenario, R/3-to-eLink finds that the logical ID and message type specified in the outbound IDOC's control record match the logical ID and message type settings in the MaterialMaster IDOC section of the environment file, so it sends the IDOC message to the Q1 queue in queue space QS1. R/3-to-eLink encodes the specified TargetId value ("DDR1") in the CR3_TARGET_ID FML32 field. Compression does not apply in this case, because the IDOC packet contained only one IDOC.

The second example shows how R/3-to-eLink processes an IDOC packet that contains multiple IDOCs. Suppose the environment file contains the settings shown in Listing 2-2.

CR3_IDOC_LIST=MaterialMaster,MaterialMaster2,CustomerMaster,
VendorMaster
[CR3_IDOC=MaterialMaster]
RECIEVER_PARTNER_NUMBER=LOGSYS1
MESSAGE_TYPE=MATMAS
COMPRESS=Y
ROUTING=DDR1
QUEUE_SPACE=QS1
QUEUE_NAME=Q1
[CR3_IDOC=MaterialMaster2]
RECIEVER_PARTNER_NUMBER=LOGSYS2
MESSAGE_TYPE=MATMAS
COMPRESS=Y
ROUTING=DDR2
QUEUE_SPACE=QS1
QUEUE_NAME=Q2
[CR3_IDOC=CustomerMaster]
RECIEVER_PARTNER_NUMBER=LOGSYS3
MESSAGE_TYPE=DEBMAS
COMPRESS=N
ROUTING=DDR3
QUEUE_SPACE=QS2
QUEUE_NAME=Q3
[CR3_IDOC=VendorMaster]
RECIEVER_PARTNER_NUMBER=LOGSYS4
MESSAGE_TYPE=CREMAS
COMPRESS=Y
ROUTING=DDR4
QUEUE_SPACE=QS3
QUEUE_NAME=Q4

An R/3-to-eLink IDOC packet contains six IDOCs with the following settings in the control record of each IDOC, as shown in Table 2-5:

Table 2-5 Sample IDOC Packet Containing Multiple IDOCs

IDOC	LogicalId	MsgType
IDOC1	LOGSYS1	CREMAS
IDOC2	LOGSYS1	MATMAS
IDOC3	LOGSYS3	MATMAS
IDOC4	LOGSYS2	MATMAS
IDOC5	LOGSYS1	MATMAS
IDOC6	LOGSYS3	DEBMAS

Figure 2-12 shows how R/3-to-eLink would process this IDOC packet according to the settings in the environment file:

R/3-to-eLink splits the IDOC packet into individual IDOCs and queues each IDOC in the following manner:

• R/3-to-eLink assigns IDOC1 and IDOC3 to the default queue, because no matching section was found in the environment file.

• R/3-to-eLink assigns IDOC2, IDOC4, IDOC5, and IDOC6 to their respective queues.

• R/3-to-eLink compresses IDOC2 and IDOC5 into a single IDOC packet in Q1, because COMPRESS=Y in the matching section of the environment file.

Managing Data-Dependent Routing (DDR)

You can configure the default data-dependent routing (DDR) value that R/3-to-eLink assigns to each IDOC message (in the CR3_TARGET_ID field) that it queues. R/3-to-eLink behaves as follows:

• If no matching section is found in the environment file for an IDOC, then R/3-to-eLink assigns a default DDR value to the IDOC messages (CR3_ALE_DEFAULT_TARGET_ID environment variable).

• If a matching section is found in the environment file for an IDOC (the logical ID and message type of the IDOC's control record match the logical ID and message type of the IDOC section), then R/3-to-eLink assigns the DDR value (TargetId) from the matching IDOC section of the environment file to the IDOC.

See "Setting the Default Data-Dependent Routing Value" and "Splitting R/3-to-eLink IDOC Packets" in Configuring ALE Integration, in this guide for instructions.

Multiple instances of R/3-to-eLink can register using the same program ID. For deployments that involve high volumes of IDOC packets, you can enhance system performance by balancing the load across multiple instances of R/3-to-eLink. Instances that register under the same program ID must also share the same TID file. Figure 2-13 shows multiple instances of R/3-to-eLink listening for IDOCs on the same program ID and sharing the same TID file:

The number of R/3-to-eLink instances should match the anticipated number of IDOC packets that R/3 sends concurrently to port. For example, if R/3 sends five IDOC packets concurrently to port during peak loads, you should load five instances of R/3-to-eLink.

See "Configuring Load Balancing" in Chapter 6, Configuring ALE Integration," in this guide.

If R/3 is configured to send R/3-to-eLink IDOCs to different program IDs, you can configure the R/3-to-eLink server to handle these IDOCs by running multiple instances of R/3-to-eLink using different program IDs. You must make sure that all instances sharing the same program ID also share the same TID file, and that all instances sharing the same TID file also share the same program ID.

Note: Instances that register under different program IDs must not share the same TID file.

Figure 2-14 shows two groups of instances of R/3-to-eLink, each of which is listening for IDOCs on a shared program ID and sharing the same TID file:

See "Configuring Load Balancing for R/3-to-eLink" in Configuring ALE Integration, of this guide.

The R/3-to-eLink server manages transactional integrity for R/3-to-eLink IDOCs to ensure that an IDOC packet has been queued successfully. R/3-to-eLink uses a TID log file to track the transaction IDs (TIDs) associated with the IDOC packets it processes to ensure that it queues an IDOC packet from R/3 exactly once. See "Transaction IDs (TIDs)" later in this topic for an introduction to TIDs.

R/3-to-eLink uses a TID file to track the IDOC packets it processes to ensure that it queues an IDOC packet once and only once. The R/3 System assigns a TID to each R/3-to-eLink IDOC packet.

The TID file for R/3-to-eLink is a log of all the TIDs that R/3-to-eLink has received and processed. Each row in the TID file represents the TID for a separate IDOC packet and contains three fixed-position columns of information:

Column	Description
Date-Time Stamp	Date and time at which the TID log file was last updated.
TID	TID that R/3 assigned to the IDOC packet.
State	The processing state. One of the following strings: CREATED indicates that R/3-to-eLink has received the TID from R/3. EXECUTED indicates that R/3-to-eLink has queued the IDOC message with the TID and has committed the transaction. ROLLBACK indicates that R/3-to-eLink has rolled back the IDOC packet from the queue. CONFIRMED indicates that R/3-to-eLink has confirmed that the IDOC message has been queued and the transaction has been committed.

The following example shows a sample TID file for R/3-to-eLink:

Tue Apr 27 14:27:36 1999  0A0201FD03F937262C5B0001  CONFIRMED  

Tue Apr 27 14:29:38 1999  0A0201FD03E937262CD70004  CONFIRMED  

Tue Apr 27 14:46:56 1999  0A0201FD03F9372630E60009  CONFIRMED  

Tue Apr 27 15:50:21 1999  0A0201FD03E837263F98003F  CONFIRMED  

The CR3_ALEOUT_TID_FILE environment variable specifies the location of the TID log file for R/3-to-eLink. See "Setting Environment Variables for R/3-to-eLink" in Configuring ALE Integration, in this guide for more information.

Use the cr3tidmanager program to manage the size and number of entries kept in TID files. See "Configuring the TID File Manager" in Configuring ALE Integration, of this guide.

Figure 2-15 shows how R/3-to-eLink uses the TID log file to manage transactional integrity for R/3-to-eLink IDOCs:

The information flow proceeds in the following sequence:

1. R/3 sends a TID to an instance of R/3-to-eLink that is registered on the matching program ID.

2. R/3-to-eLink receives the TID and checks the TID file to determine whether it has previously received this TID from R/3. If the TID is not found in the TID file, then R/3-to-eLink appends an entry to the TID file, specifying the date-time stamp, TID, and the state (CREATED). R/3-to-eLink returns a code to R/3 indicating whether the TID was found, and the TID state determines whether R/3 continues processing.

3. If R/3 continues processing, R/3-to-eLink starts a new transaction.

4. R/3 sends the IDOC packet associated with the TID to the same instance of R/3-to-eLink.

5. R/3-to-eLink receives the IDOC packet and processes the IDOC data according to the way that R/3-to-eLink is configured (such as splitting IDOC packets, making routing decisions based on the environment file, and so on). R/3-to-eLink encodes the IDOC data in one or more FML32 message buffers and queues the message(s) into one or more queues.

6. After processing the IDOC data, R/3-to-eLink returns success or an SAP exception (if, for example, the target queue is full) to R/3.

7. Based on the status returned from R/3-to-eLink, R/3 instructs the same instance of R/3-to-eLink to commit or roll back the transaction:

8. R/3-to-eLink takes one of the following actions:

   • R/3-to-eLink commits the transaction and updates the date-time stamp and state (EXECUTED) in the TID file.

   • R/3-to-eLink call rolls back the transaction and updates the date-time stamp and state (ROLLBACK) in the TID file.

9. If the transaction is successfully committed, R/3-to-eLink updates the date-time stamp and state (CONFIRMED) in the TID file.

R/3-to-eLink uses TUXEDO's transaction management capabilities to ensure transactional integrity for R/3-to-eLink IDOCs. Figure 2-6 lists problems that can occur with R/3-to-eLink IDOCs:

Table 2-6 Handling Problems with R/3-to-eLink IDOCs

Problem	Description
Unable to Lock the TID File	The TID file might be locked by another instance of R/3-to-eLink or the TID File Manager. R/3-to-eLink retries the lock attempt. After a configurable number of retry attempts, R/3-to-eLink returns a lock error to R/3. R/3 then attempts to retry the operation until it succeeds or stops trying.
Unable to Update the TID File	The file might be corrupted. If R/3-to-eLink can lock the TID file but cannot update it, R/3-to-eLink retries the lock attempt. After a configurable number of retry attempts, R/3-to-eLink returns a lock error to R/3. R/3 then attempts to retry the operation until it succeeds or stops trying.
R/3-to-eLink cannot queue an IDOC message(s)	One or more target queues might be full. R/3-to-eLink returns an SAP exception to R/3, and R/3 instructs R/3-to-eLink to roll back the transaction. R/3 will subsequently resubmit the IDOC packet to R/3-to-eLink.