Integrating with ALE

 

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:

• Chapter 6, "Configuring ALE Integration"

• Chapter 7, "Configuring R/3 Connections"

ALE Integration

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 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 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:

Figure 2-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 (R/3) and non-IDOC (non-R/3) data between R/3 and non-R/3 systems.

Communicating Among R/3 Logical Systems

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

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

Information Flow for ALE Integration

Figure 2-3 shows the information flow for the two main ALE processes: ALE R/3 to eLink and ALE eLink to R/3:

Figure 2-3 Overview of Information Flow for ALE Processing

• ALE eLink to R/3 is a TUXEDO server that submits IDOC packets to R/3. ALE 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.

• ALE R/3 to eLink is a TUXEDO client that receives IDOC packets from R/3 via Transactional RFC (tRFC). ALE 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 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:

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

• The 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 2-4:

Figure 2-4 Structure of an ALE IDOC

For eLink to R/3 IDOCs, ALE eLink to R/3 validates the size and structure of control records and data records. For each IDOC, ALE 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:

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

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:

• 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, ALE R/3 to eLink and ALE 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.

Processing eLink to R/3 IDOCs

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

• ALE eLink to R/3 Server

• Information Flow for eLink to R/3 IDOCs

• Splitting eLink to R/3 IDOC Packets

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

• Managing Transactional Integrity for eLink to R/3 IDOCs

• Handling Problems with eLink to R/3 IDOCs

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

ALE eLink to R/3 Server

ALE eLink to R/3 is a TUXEDO server that submits IDOC packets to R/3. ALE 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. ALE eLink to R/3 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 eLink to R/3 is cr3alein.

ALE eLink to R/3 Services (CR3_SUBMIT and CR3_IDOC_IN)

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

FML32 Field Definitions for eLink to R/3 IDOCs

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

Table 2-1 FML32 Fields for ALE 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.

Information Flow for eLink to R/3 IDOCs

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

Figure 2-6 Information Flow for eLink to R/3 IDOCs

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

1. One or more instances of ALE 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 ALE 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 ALE eLink to R/3.

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

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

Splitting eLink to R/3 IDOC Packets

By default, ALE eLink to R/3 passes an IDOC message containing multiple IDOCs to R/3 in a single packet. You can configure ALE 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, ALE eLink to R/3 can create six IDOC separate 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:

Figure 2-7 Splitting eLink to R/3 IDOC Packets

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 Chapter 6, "Configuring ALE Integration," for instructions.

Load Balancing High Volumes of eLink to R/3 IDOCs

Multiple instances of ALE eLink to R/3 can log onto R/3 and submit eLink to R/3 IDOCs for processing. For deployments that involve high volumes of eLink to R/3 IDOCs, you can enhance system performance by balancing the load across multiple instances of ALE eLink to R/3. See "Configuring Load Balancing for eLink to R/3 IDOCs" in Chapter 6, "Configuring ALE Integration," for instructions.

Managing Transactional Integrity for eLink to R/3 IDOCs

ALE eLink to R/3 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, ALE eLink to R/3 retries using the same TID. ALE 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.

About the TID Log File Used for eLink to R/3 IDOCs

The TID log file used with eLink to R/3 IDOCs contains information about TIDs that ALE 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 ALE 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 ALE eLink to R/3 has successfully passed the IDOC packet onto R/3.

The following example shows a sample TID file for ALE 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 ALE eLink to R/3. See "Setting Environment Variables" in Chapter 6, "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 Chapter 6, "Configuring ALE Integration," in this guide.

Processing TIDs with eLink to R/3 IDOCs

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

Figure 2-8 TID Processing for ALE eLink to R/3

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 ALE eLink to R/3.

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

Second Transaction Boundary

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

Handling Problems with eLink to R/3 IDOCs

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

Processing R/3 to eLink IDOCs

The following topics describe how to process R/3 to eLink IDOCS using the ALE R/3 to eLink client:

• ALE R/3 to eLink Client

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

ALE R/3 to eLink must be configured properly before it can process R/3 to eLink IDOCs.

ALE R/3 to eLink Client

ALE R/3 to eLink is a TUXEDO client that receives IDOC packets from R/3 via Transactional RFC (tRFC). ALE R/3 to eLink encodes each IDOC packet into an FML32 message buffer and queues it into a TUXEDO queue. ALE 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 ALE R/3 to eLink is cr3aleout.

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

Table 2-4 FML32 Fields for ALE 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.

Information Flow for R/3 to eLink IDOCs

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

Figure 2-9 Information Flow for R/3 to eLink IDOCs

The information flow proceeds in the following sequence:

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

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

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

   • If a destination map file is configured, then ALE R/3 to eLink automatically splits IDOC packets containing multiple IDOCs into separate IDOC messages, each containing a single IDOC. ALE R/3 to eLink uses the settings in the destination map 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" later in this topic for more information.

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

Splitting R/3 to eLink IDOC Packets Into Individual IDOCs

You can configure ALE R/3 to eLink to split IDOC packets containing multiple IDOCs into separate IDOC messages, each containing a single IDOC. By default, ALE R/3 to eLink encodes the entire IDOC packet into a single occurrence of the CR3_IDOC field in the message buffer and queues the entire IDOC packet into a single message. If you set the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable to "Y", however, ALE R/3 to eLink will split the IDOC packet into individual IDOC messages and then queue all IDOC packets into a single queue as shown in Figure 2-10:

Figure 2-10 Splitting IDOC Packets and Queuing IDOC Messages to a Single Queue

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

Queuing R/3 to eLink IDOCs Into Multiple Queues

ALE R/3 to eLink can be configured to use a destination map file so that it can place IDOC messages into different target queues, manage data-dependent routing, and group similar IDOC messages into larger IDOC messages. ALE R/3 to eLink makes routing and grouping decisions about individual IDOCs according to two settings specified in an IDOCs 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 R/3 to eLink automatically splits IDOC packets containing multiple IDOCs into separate IDOC messages, each one containing a single IDOC. It then queues the IDOC messages using the settings in the destination map file:

Figure 2-11 Splitting IDOC Packets and Queuing to Multiple Queues

Before you can 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 file in the CR3_ALEOUT_DEST_MAP_FILE environment variable. See "Configuring a Destination Map File" in Chapter 6, "Configuring ALE Integration," for this procedure.

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 R/3 to eLink IDOC, ALE R/3 to eLink searches the destination map file for the target R/3 system and IDOC message type specified in an IDOCs control record. If it finds a matching entry, ALE R/3 to eLink assigns the IDOC to the destination queue space and queue specified in the entry. ALE R/3 to eLink also processes the IDOC according to the Compress flag and the Target ID settings in the entry.

Compressing R/3 to eLink 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 R/3 to eLink aggregates this IDOC with other matching IDOCs in a single, larger IDOC message that it then assigns to the appropriate target queue. If the Compress column is "N", then ALE R/3 to eLink queues 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 R/3 to eLink adds 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 R/3 to eLink 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_ale.ubb configuration file.

See "Setting the Data-Dependent Routing Value" in Chapter 6, "Configuring ALE Integration," in this 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 R/3 to eLink processes an IDOC packet that contains a single IDOC. Suppose the destination map file contains the entry shown in Table 2-5:

Table 2-5 Settings in a Sample Destination Map File

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

The control record in an R/3 to eLink IDOC specifies a target logical ID of "LOGSYS" and a message type of "MATMAS". Figure 2-12 shows how ALE R/3 to eLink would process this IDOC packet according to the settings in the destination map file:

Figure 2-12 Queuing a Single IDOC According to the Destination Map File

In this scenario, ALE R/3 to eLink finds the matching entry in the destination map file and sends the IDOC message to the Q1 queue in queue space QS1. ALE 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 ALE R/3 to eLink processes an IDOC packet that contains multiple IDOCs. Table 2-6 shows the destination map file entries:

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

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-7:

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

Figure 2-13 Queuing Multiple IDOCs According to the Destination Map File

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

• ALE R/3 to eLink assigns IDOC1 and IDOC3 to the default queue because no matching entry was found in the destination map file.

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

• ALE R/3 to eLink 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 R/3 to eLink assigns to each IDOC message (in the CR3_TARGET_ID field) that it queues. The behavior of ALE R/3 to eLink 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 R/3 to eLink 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 R/3 to eLink 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 Chapter 6, "Configuring ALE Integration," in this guide for instructions. See your TUXEDO documentation for more information about data-dependent routing.

Load Balancing High Volumes of R/3 to eLink IDOCs

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

Figure 2-14 Multiple Instances of ALE R/3 to eLink Sharing the Same Program ID

The number of ALE 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 ALE R/3 to eLink.

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

Registering Multiple Program IDs

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

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

Figure 2-15 Multiple Instances of ALE R/3 to eLink Using Different Program IDs

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

Managing Transactional Integrity for R/3 to eLink IDOCs

ALE R/3 to eLink manages transactional integrity for R/3 to eLink IDOCs to ensure that an IDOC packet has been queued successfully. ALE 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.

About the TID Log File Used for R/3 to eLink IDOCs

ALE 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 ALE R/3 to eLink is a log of all the TIDs that ALE 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 ALE R/3 to eLink has received the TID from R/3. EXECUTED indicates that ALE R/3 to eLink has queued the IDOC message with the TID and has committed the transaction. ROLLBACK indicates that ALE R/3 to eLink has rolled back the IDOC packet from the queue. CONFIRMED indicates that ALE 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 ALE 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 ALE R/3 to eLink. See "Setting Environment Variables for ALE R/3 to eLink" in Chapter 6, "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 Chapter 6, "Configuring ALE Integration," in this guide.

Processing TIDs with R/3 to eLink IDOCs

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

Figure 2-16 TID Processing for ALE R/3 to eLink

The information flow proceeds in the following sequence:

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

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

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

5. ALE R/3 to eLink receives the IDOC packet and processes the IDOC data according to the way that ALE R/3 to eLink is configured (such as splitting IDOC packets, making routing decisions based on a map file, and so on). ALE 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, ALE R/3 to eLink 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 R/3 to eLink, R/3 instructs the same instance of ALE R/3 to eLink to commit or roll back the transaction:

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

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

   • ALE R/3 to eLink 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 R/3 to eLink updates the date-time stamp and State (CONFIRMED) in the TID file.

Handling Problems with R/3 to eLink IDOCs

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

Table 2-8 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 ALE R/3 to eLink or the TID File Manager. ALE R/3 to eLink retries the lock attempt. After a configurable number of retry attempts, ALE 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 ALE R/3 to eLink can lock the TID file but cannot update it, ALE R/3 to eLink retries the lock attempt. After a configurable number of retry attempts, ALE 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.
ALE R/3 to eLink cannot queue an IDOC message(s)	One or more target queues might be full. ALE R/3 to eLink returns a SAP exception to R/3, and R/3 instructs ALE R/3 to eLink to roll back the transaction. R/3 will subsequently resubmit the IDOC packet to ALE R/3 to eLink.