Integrating with ALE

This chapter describes how to integrate with SAP's Application Linking and Embedding (ALE) technology in the BEA eLink environment. It includes the following sections:

• About ALE Integration

• Processing Inbound IDOCs

• Processing Outbound IDOCs

For information about setting up ALE processing, see the following chapters in the BEA eLink Adapter for R/3 Installation and Configuration Guide:

• Configuring ALE Integration

• Configuring R/3 Connections

About ALE Integration

This section provides important conceptual information about integrating with ALE. It includes the following topics:

• Usage Scenarios for ALE Integration

• Information Flow for ALE Integration

• Key ALE Concepts

Usage Scenarios for ALE Integration

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

• Integrating R/3 and non-R/3 systems using TUXEDO and BEA eLink Adapter for R/3 to exchange IDOCs across application and platform boundaries.

• Communicating among R/3 systems using TUXEDO and BEA eLink Adapter for R/3 to reliably and efficiently transport IDOCs among R/3 logical systems.

Integrating R/3 and Non-R/3 Systems

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

Figure 3-1 Integrating R/3 and Non-R/3 Systems

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

Communicating Among R/3 Logical Systems

Figure 3-2 shows how TUXEDO and BEA eLink Adapter for R/3 can be used to transport IDOCs among R/3 logical systems:

Figure 3-2 Communicating Among R/3 Logical Systems

In this scenario, BEA eLink Adapter for R/3 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.
 

Information Flow for ALE Integration

Figure 3-3 provides an overview of the information flow for the two main ALE processes, ALE Outbound and ALE Inbound:

Figure 3-3 Overview of Information Flow for ALE Processing

• ALE Inbound is a TUXEDO server that submits IDOC packets to R/3. ALE Outbound receives each IDOC packet as an FML32 message buffer (forwarded from a TUXEDO queue), encodes the IDOC data for R/3, and submits the IDOC packet to R/3 via tRFC. See Information Flow for Inbound IDOCs for more information.

• ALE Outbound is a TUXEDO client that receives IDOC packets from R/3 via Transactional RFC (tRFC). ALE Outbound encodes each IDOC packet data into an FML32 message buffer and enqueues it into one or more TUXEDO queues. See Information Flow for Outbound IDOCs for more information.

Key ALE Concepts

This section describes the following key concepts used in ALE processing:

• Intermediate Documents (IDOCs)

• Transaction IDs (TIDs)

Intermediate Documents (IDOCs)

In SAP's 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:

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

• Data records uniquely identify a segment that contains application data. The length of a data record is 1055 bytes, 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 3-4:

Figure 3-4 Structure of an ALE IDOC

For inbound IDOCs, ALE Inbound validates the size and structure of control records and data records. For each IDOC, ALE Inbound 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 3-5:

Figure 3-5 Types of IDOC Packets

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.fml file, as described in FML32 Field Definitions in Introducing BEA eLink Adapter for R/3.
 

Transaction IDs (TIDs)

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

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

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

In the TUXEDO environment, ALE Outbound and ALE Inbound monitor TIDs through the use of TID log files. See Managing Transactional Integrity for Inbound IDOCs and Managing Transactional Integrity for Outbound IDOCs for more information.

Processing Inbound IDOCs

This section describes how to process inbound IDOCS using the ALE Inbound server. It includes the following topics:

• About the ALE Inbound Server

• Information Flow for Inbound IDOCs

• Splitting Inbound IDOC Packets

• Load Balancing High Volumes of Inbound IDOCs

• Managing Transactional Integrity for Inbound IDOCs

• Handling Problems with Inbound IDOCs

ALE Inbound must be properly configured before it can process IDOCs. See "Configuring ALE Inbound" in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide for more information.
 

About the ALE Inbound Server

ALE Inbound is a TUXEDO server that submits IDOC packets to R/3. ALE Inbound 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. ALE Inbound uses a TID log file to track the TIDs associated with IDOC packets to guarantee delivery to R/3 once and only once. The name of the executable for ALE Inbound is cr3alein.
 

ALE Inbound Services (CR3_SUBMIT and CR3_IDOC_IN)

ALE Inbound provides two services that process inbound 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 enqueues 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.

 

FML32 Field Definitions for Inbound IDOCs

ALE Inbound uses the following FML32 field definitions in IDOC messages:

Table 3-1 FML32 Fields for ALE Inbound 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. Internal Use Only.
CR3_IDOC_CONTROL	string	Contains one or more control records for the IDOC packet. Internal Use Only.
CR3_IDOC_DATA	string	Contains one or more data records for the IDOC packet. Internal Use Only.

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

Information Flow for Inbound IDOCs

Figure 3-6 shows the information flow for inbound IDOCs:

Figure 3-6 Information Flow for Inbound IDOCs

The information flow for ALE Inbound proceeds in the following sequence:

1. One or more instances of ALE Inbound (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 enqueues it into the CR3_SUBMIT queue.

3. TMQFORWARD dequeues the IDOC message from the CR3_SUBMIT queue and submits it to the CR3_SUBMIT service of the ALE Inbound 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 enqueues 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 ALE Inbound.

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

ALE Inbound uses a TID log file to manage transactional integrity. See Managing Transactional Integrity for Outbound IDOCs for more information.
 

Splitting Inbound IDOC Packets

By default, ALE Inbound passes an IDOC message containing multiple IDOCs to R/3 in a single packet. You can configure ALE Inbound 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, ALE Inbound can create six IDOC separate packets, each containing a single IDOC and associated with a unique TID. Figure 3-7 shows splitting IDOC packets and enqueueing them into the CR3_SUBMIT queue:

Figure 3-7 Splitting Inbound IDOC Packets

Splitting IDOC packets provides additional flexibility for processing inbound 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 Inbound IDOC Packets Containing Multiple IDOCs in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide for instructions.
 

Load Balancing High Volumes of Inbound IDOCs

Multiple instances of ALE Inbound can log onto R/3 and submit inbound IDOCs for processing. For deployments that involve high volumes of inbound IDOCs, you can enhance system performance by balancing the load across multiple instances of ALE Inbound. See Configuring Load Balancing for Inbound IDOCs in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide for instructions.
 

Managing Transactional Integrity for Inbound IDOCs

ALE Inbound manages transactional integrity for inbound 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, ALE Inbound retries using the same TID. ALE Inbound uses a TID log file to track the transaction IDs (TIDs) that R/3 assigns to each inbound IDOC packet. See Transaction IDs (TIDs) for an introduction to TIDs.
 

About the TID Log File Used for Inbound IDOCs

The TID log file used with inbound IDOCs contains information about TIDs that ALE Inbound 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 3-2 Columns in the TID Log File for Inbound 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 ALE Inbound has successfully associated a TID with the IDOC packet and enqueued it into the CR3_IDOC_IN queue. CONFIRMED indicates that ALE Inbound has successfully passed the IDOC packet onto R/3.

The following example shows a sample TID file for ALE Inbound:

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

The CR3_ALEIN_TID_FILE environment variable specifies the location of the TID log file for ALE Inbound. See Setting Environment Variables for ALE Inbound in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration 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 in the BEA eLink Adapter for R/3 Installation and Configuration Guide.
 

Processing TIDs with Inbound IDOCs

Figure 3-8 shows how ALE Inbound uses the TID log file to manage transactional integrity for inbound IDOCs:

Figure 3-8 TID Processing for ALE Inbound

The inbound 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 enqueued 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 ALE Inbound.

• 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, dequeues an IDOC message from the CR3_SUBMIT queue, and submits the IDOC message to the CR3_SUBMIT service of the ALE Inbound 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, ALE Outbound 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 enqueues the message into 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 ALE Inbound 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.

ALE Inbound uses TUXEDO's transaction management capabilities to ensure transactional integrity for inbound IDOCs. Figure 3-3 lists problems that can occur with inbound IDOCs:

Table 3-3 Handling Problems with Inbound IDOCs

Problem	Description
Invalid IDOC structure	If an IDOC packet fails validation, the CR3_SUBMIT service enqueues 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 enqueues the FML32 message into the CR3_ERROR queue and returns TPSUCCESS to TMQFORWARD.
TID Not received from R/3	If R/3 for some reason does not return a TID, CR3_SUBMIT 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 dequeue and handle messages in the CR3_ERROR queue.

Processing Outbound IDOCs

This section describes how to process outbound IDOCS using the ALE Outbound client. It includes the following topics:

• About the ALE Outbound Client

• Information Flow for Outbound IDOCs

• Splitting Outbound IDOC Packets Into Individual IDOCs

• Enqueuing Outbound IDOCs Into Multiple Queues

• Managing Data-Depending Routing (DDR)

• Load Balancing High Volumes of Outbound IDOCs

• Registering Multiple Program IDs

• Managing Transactional Integrity for Outbound IDOCs

• Handling Problems with Outbound IDOCs

ALE Outbound must be properly configured before it can process outbound IDOCs. For information about setting up ALE Outbound, see Configuring ALE Outbound in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide.
 

About the ALE Outbound Client

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

ALE Outbound uses the following FML32 field definitions in IDOC messages:

Table 3-4 FML32 Fields for ALE Outbound 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 Adapter for Mercator User Guide for more information.

 

Information Flow for Outbound IDOCs

Figure 3-9 illustrates the information flow for ALE Outbound:

Figure 3-9 Information Flow for Outbound IDOCs

The information flow proceeds in the following sequence:

1. One or more instances of ALE Outbound (a TUXEDO client) start up and register a program ID with the R/3 Gateway. ALE Outbound 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 ALE Outbound that is registered on the program ID of the RFC destination.

4. ALE Outbound receives the IDOC packet and processes the IDOC data according to the way that ALE Outbound is configured, with or without a destination map file:

   • If a destination map file is not configured, then ALE Outbound sends the IDOC packet to the default queue. If the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable is set to "Y", then ALE Outbound splits IDOC packets containing multiple IDOCs into separate IDOC messages, each containing a single IDOC, as described in Splitting Outbound IDOC Packets Into Individual IDOCs .

   • If a destination map file is configured, then ALE Outbound automatically splits IDOC packets containing multiple IDOCs into separate IDOC messages, each containing a single IDOC. ALE Outbound uses the settings in the destination map file to determine the target queue for each IDOC as well as other processing options. See Enqueuing Outbound IDOCs Into Multiple Queues for more information.

ALE Outbound uses a TID log file to manage transactional integrity. See Managing Transactional Integrity for Outbound IDOCs for more information.
 

Splitting Outbound IDOC Packets Into Individual IDOCs

You can configure ALE Outbound to split IDOC packets containing multiple IDOCs into separate IDOC messages, each containing a single IDOC. By default, ALE Outbound encodes the entire IDOC packet into a single occurrence of the CR3_IDOC field in the message buffer and enqueues the entire IDOC packet into a single message. If you set the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable to "Y", However, ALE Outbound will split the IDOC packet into individual IDOC packets and then enqueue all IDOC packets into a single queue. Figure 3-10 shows splitting IDOC packets and enqueueing them into a single queue:

Figure 3-10 Splitting IDOC Packets and Enqueuing to a Single Queue

See Setting Environment Variables for ALE Outbound in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide for more information about setting the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable.
 

Enqueuing Outbound IDOCs Into Multiple Queues

ALE Outbound can be configured to use a destination map file so that it can enqueue IDOC messages into different target queues, manage data-dependent routing, and group similar IDOC messages into larger IDOC messages. ALE Outbound 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 a destination map file is used, ALE Outbound automatically splits IDOC packets containing multiple IDOCs into separate IDOC messages, each one containing a single IDOC, and enqueues them into target queues. Figure 3-11 shows splitting IDOC packets and enqueueing them into multiple queues (using the settings in the destination map file):

Figure 3-11 Splitting IDOC Packets and Enqueuing to Multiple Queues

To use a destination map file, you must set up the target queue spaces and queues (including the default queue space and queue), create the destination map file, and specify the name and location of the destination map file in the CR3_ALEOUT_DEST_MAP_FILE environment variable. See Configuring the Destination Map File in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide for more information.
 

About the Destination Map File

The destination map file is an ASCII text file. Each row in the file denotes a separate entry and specifies the following information:

• Logical system ID of the target R/3 logical system.

• Message type specified in the IDOC.

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

• Target ID representing the data-dependent routing value.

• Destination queue space name.

• Destination queue name.

For each outbound IDOC, ALE Outbound searches the destination map file for the target R/3 system and IDOC message type specified in an IDOC's control record. If it finds a matching entry, ALE Outbound enqueues the IDOC into the destination queue space and queue specified in the entry. ALE Outbound also processes the IDOC according to the Compress flag and the Target ID settings in the entry.

Compressing Outbound IDOCs

You use the Compress column in the destination map file to combine IDOC messages with matching logical system IDs and IDOC message types into an IDOC message containing multiple IDOCs. For each matching entry, if the Compress column is "Y", then ALE Outbound aggregates this IDOC with other matching IDOCs in a single, larger IDOC message that it then enqueues into the appropriate target queue. If the Compress column is "N", then ALE Outbound enqueues each IDOC message separately.

Setting the Data-Dependent Routing Value

You use the TargetId column in the destination map file to associate an IDOC with a data-dependent routing (DDR) value. For each matching entry, ALE Outbound encodes the specified TargetId value in the CR3_TARGET_ID FML32 field of the IDOC message. If this DDR is unspecified, or if no matching entry is found in the destination map file, then ALE Outbound encodes the default DDR value, which is defined in the CR3_ALE_DEFAULT_TARGET_ID environment variable.

Note: To use DDR, the DDR value must match the field ID configured in the ROUTING section of the cr3.ubb configuration file.

See Setting the Data-Dependent Routing Value in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide for more information. See your TUXEDO documentation for more information about data-dependent routing.
 

Examples of Using a Destination Map File

The first example shows how ALE Outbound processes an IDOC packet that contains a single IDOC. Suppose the destination map file contains the following entry:

Table 3-5 Settings in a Sample Destination Map File

LogicalId	MsgType	Compress	TargetId	QueueSpace	QueueName
LOGSYS1	MATMAS	Y	DDR1	QS1	Q1

Suppose also that the control record in an outbound IDOC specifies a target logical ID of "LOGSYS" and a message type of "MATMAS". Figure 3-12 shows how ALE Outbound would process this IDOC packet according to the settings in the destination map file:

Figure 3-12 Enqueuing a Single IDOC According to the Destination Map File

In this scenario, ALE Outbound finds the matching entry in the destination map file and sends the IDOC message to the Q1 queue in queue space QS1. ALE Outbound 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 ALE Outbound processes an IDOC packet that contains multiple IDOCs. Suppose the destination map file contains the following entries:

Table 3-6 Settings in a Sample Destination Map File

LogicalId	MsgType	Compress	TargetId	QueueSpace	QueueName
LOGSYS1	MATMAS	Y	DDR1	QS1	Q1
LOGSYS2	MATMAS	Y	DDR2	QS1	Q2
LOGSYS3	DEBMAS	N	DDR3	QS2	Q3
LOGSYS4	CREMAS	Y	DDR4	QS3	Q4

Suppose also that an outbound IDOC packet contains six IDOCs with the following settings in the control record of each IDOC:

Table 3-7 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 3-13 shows how ALE Outbound would process this IDOC packet according to the settings in the destination map file:

Figure 3-13 Enqueuing Multiple IDOCs According to the Destination Map File

ALE Outbound splits the IDOC packet into individual IDOCs and enqueues each IDOC in the following manner:

• ALE Outbound enqueues IDOC1 and IDOC3 into the default queue because no matching entry was found in the destination map file.

• ALE Outbound enqueues IDOC2, IDOC4, IDOC5, and IDOC6 into their respective queues.

• ALE Outbound compresses IDOC2 and IDOC5 into a single IDOC packet in Q1 because Compress="Y" in the matching entry in the destination map file.

Managing Data-Depending Routing (DDR)

You can configure the default data-dependent routing (DDR) value that ALE Outbound assigns to each IDOC message (in the CR3_TARGET_ID field) that it enqueues. The behavior of ALE Outbound depends on whether a DDR value is defined in the destination map file:

• If no destination map file is used, or if no matching entry is found in the destination map file for an IDOC, then ALE Outbound assigns a default DDR value to the IDOC messages (CR3_ALE_DEFAULT_TARGET_ID environment variable).

• If a matching entry is found in the destination map file for an IDOC, then ALE Outbound assigns the DDR value (TargetId) from the map file.

See Setting the Default Data-Dependent Routing Value and Setting Data-Dependent Routing Values in the Map File in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide for instructions. See your TUXEDO documentation for more information about data-dependent routing.
 

Load Balancing High Volumes of Outbound IDOCs

Multiple instances of ALE Outbound 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 ALE Outbound. Instances that register under the same program ID must also share the same TID file. Figure 3-14 shows multiple instances of ALE Outbound listening for IDOCs on the same program ID and sharing the same TID file:

Figure 3-14 Multiple Instances of ALE Outbound Sharing the Same Program ID

The number of ALE Outbound 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 ALE Outbound.

See Configuring Load Balancing in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide.
 

Registering Multiple Program IDs

If R/3 is configured to send outbound IDOCs to different program IDs, you can configure ALE Outbound to handle these IDOCs by running multiple instances of ALE Outbound 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. Instances that register under different program IDs must not share the same TID file.

Figure 3-15 shows two groups of instances of ALE Outbound, each of which is listening for IDOCs on a shared program ID and sharing the same TID file:

Figure 3-15 Multiple Instances of ALE Outbound Using Different Program IDs

See Configuring Multiple Program IDs in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide.
 

Managing Transactional Integrity for Outbound IDOCs

ALE Outbound manages transactional integrity for outbound IDOCs to ensure that an IDOC packet has been enqueued successfully. ALE Outbound uses a TID log file to track the transaction IDs (TIDs) associated with the IDOC packets it processes to ensure that it enqueues an IDOC packet from R/3 exactly once. See Transaction IDs (TIDs) for an introduction to TIDs.
 

About the TID Log File Used for Outbound IDOCs

ALE Outbound uses a TID file to track the IDOC packets it processes to ensure that it enqueues an IDOC packet once and only once. The R/3 system assigns a TID to each outbound IDOC packet.

The TID File for ALE Outbound is a log of all the TIDs that ALE Outbound 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 ALE Outbound has received the TID from R/3. EXECUTED indicates that ALE Outbound has enqueued the IDOC message with the TID and has committed the transaction. ROLLBACK indicates that ALE Outbound has rolled back the IDOC packet from the queue. CONFIRMED indicates that ALE Outbound has confirmed that the IDOC message has been enqueued and the transaction has been committed.

The following example shows a sample TID file for ALE Outbound:

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

The CR3_ALEOUT_TID_FILE environment variable specifies the location of the TID log file for ALE Outbound. See Setting Environment Variables for ALE Outbound in Configuring ALE Integration in the BEA eLink Adapter for R/3 Installation and Configuration 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 in the BEA eLink Adapter for R/3 Installation and Configuration Guide.
 

Processing TIDs with Outbound IDOCs

Figure 3-16 shows how ALE Outbound uses the TID log file to manage transactional integrity for outbound IDOCs:

Figure 3-16 TID Processing for ALE Outbound

The information flow proceeds in the following sequence:

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

2. ALE Outbound 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 ALE Outbound appends an entry to the TID file, specifying the date-time stamp, TID, and the State (CREATED). ALE Outbound 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, ALE Outbound starts a new transaction.

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

5. ALE Outbound receives the IDOC packet and processes the IDOC data according the way that ALE Outbound is configured (such as splitting IDOC packets, making routing decisions based on a map file, and so on). ALE Outbound encodes the IDOC data in one or more FML32 message buffers and enqueues the message(s) into one or more queues.

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

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

8. ALE Outbound takes one of the following actions:

   • ALE Outbound commits the transaction and updates the date-time stamp and State (EXECUTED) in the TID file.

   • ALE Outbound calls rolls back the transaction and updates the date-time stamp and State (ROLLBACK) in the TID file.

9. If the transaction is successfully committed, ALE Outbound updates the date-time stamp and State (CONFIRMED) in the TID file.

ALE Outbound uses TUXEDO's transaction management capabilities to ensure transactional integrity for outbound IDOCs. Figure 3-8 lists problems that can occur with outbound IDOCs:

Table 3-8 Handling Problems with Outbound IDOCs

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