Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
eLink Adapter for R/3 ALE Doc Home | BEA eLink Adapter for R/3 ALE User Guide | Previous Topic | Next Topic | Contents | Index

Configuring ALE Integration

This topic describes how to configure your BEA eLink Adapter for R/3 ALE installation for integration with SAP application linking and embedding (ALE) technology. It includes the following main sections:

- Configuring the eLink-to-R/3 Server

- Configuring the R/3-to-eLink Server

- Configuring Queues

- Configuring the TID File Manager

- Shutting Down the BEA eLink Adapter for R/3 ALE

  Note: You need to complete the tasks in this section only if you require application integration with ALE.

Using BEA eLink Adapter for R/3 ALE, TUXEDO applications can exchange SAP Intermediate Documents (IDOCs) with R/3 Systems. See Chapter 2, "Integrating with ALE," in this guide for more information about ALE integration.

Configuring the eLink-to-R/3 Server

The following topics describe how to configure the eLink-to-R/3 server:

- Configuring the UBB File for eLink-to-R/3

- Setting Environment Variables for eLink-to-R/3

In addition, see the following topics for further configuration instructions:

- Setting Up Queues for eLink-to-R/3 IDOCs

- Configuring eLink-to-R/3 Connections in Chapter 6, "Configuring R/3 Connections"

eLink-to-R/3 is a TUXEDO server that submits IDOC packets to R/3 via tRFC. eLink-to-R/3 receives IDOC packets forwarded from a TUXEDO queue, encodes the IDOC data for R/3, and submits the message to R/3 via tRFC. See "Processing eLink-to-R/3 IDOCs" in Integrating with ALE, of this guide for more information about eLink-to-R/3.

Configuring the UBB File for eLink-to-R/3

eLink-to-R/3 is a standard TUXEDO server that is defined in the UBB file. You must configure this file to specify the server group, server, environment file, and services associated with the eLink-to-R/3 server. See Appendix A, "Sample cr3_ale.ubb File," for a listing of the sample UBB file that comes with BEA eLink Adapter for R/3 ALE.

Defining the eLink-to-R/3 server (cr3alein)

In the SERVERS section of your UBB file, you must specify the eLink-to-R/3 server as cr3alein, then define it in the succeeding code lines by specifying its server group, server ID, and environment file

Do this using the following syntax:

>     cr3alein
>     	SRVGRP=GroupId SRVID=ServerID
>     	CLOPT = "-A -- -i unique_id -e env_filename"

where:

- GroupID is the unique ID of the server group to which the eLink-to-R/3 server belongs.

- ServerID is the unique ID of the eLink-to-R/3 server.

- -i unique_id is the unique ID that identifies the label section in the environment file containing the adapter's environment variables. You would use this value when you run multiple eLink adapters that share this configuration file. If it is not specified, then the unique ID defaults to the process name.

- -e env_filename is the environment file that specifies the detailed configuration information.

Listing 5-1 shows SERVERS settings for the eLink-to-R/3 server (cr3alein) in a sample UBB file for Windows NT:

Listing 5-1 Sample SERVERS Settings for eLink-to-R/3 Server

>     cr3alein
>     	SRVGRP=CR3 SRVID=3
>     	CLOPT="-A -- -i cr3alein -e cr3alein.env"

Defining eLink-to-R/3 Services

In the SERVICES section of your UBB file, define the CR3_SUBMIT and CR3_IDOC_IN services, as shown in the following example:

>     CR3_SUBMIT
>     CR3_IDOC_IN

CR3_SUBMIT checks the validity of the data meant for R/3. CR3_IDOC_IN sends it to R/3.

Setting Environment Variables for eLink-to-R/3

The eLink-to-R/3 server requires environment variables that specify connection information and the behavior of the server to R/3. These environment variables are defined in an environment file that is specified in the UBB file as the ENVFILE parameter for the server.

Environment Variables for eLink-to-R/3

Configure the required and optional environment variables for eLink-to-R/3 as shown in Table 6-1:

####

Table 5-1 Environment Variables for the eLink-to-R/3 Server

Category / Variable | Set To | Description
--- | --- | ---
Connecting To R/3 |  |
CR3_DESTINATION | System Name | Destination in the sideinfo that defines the R/3 application server to connect to. Default is undefined. This setting is case sensitive. Required.
CR3_CLIENT | Client Number | R/3 login client number. Default is undefined. Required.
CR3_USER | User | R/3 login user. Default is undefined. The user must be of type CPIC. Required.
CR3_PASSWORD | Password | R/3 login user password. Default is undefined. Required.
CR3_LANGUAGE | E | R/3 login language. Default is E for English. Required.
SIDE_INFO | Path and File | Full path to the sideinfo file. Required.
Managing the TID File |  |
CR3_ALEIN_TID_FILE | Path and File | Full path and filename for the eLink-to-R/3 TID file, without the .tid file extension. Required.
CR3_ALEIN_TID_PER_IDOC | Y or N | Specify "Y" to split IDOC packets containing multiple IDOCs and pass them as individual IDOCs to R/3. Specify "N" (the default) to pass multiple IDOCs to R/3 in one batch. "N," the default is also preferred because, very seldom, is there any need to split inbound IDOCs. Optional.
Managing Queues |  |
CR3_ALEIN_IDOCIN_QUEUE | Queue Name | Name of the queue for messages containing processed IDOCs and their corresponding TIDs. By default, should be set to CR3_IDOC_IN. TMQFORWARD dequeues messages from this queue and forwards them to the CR3_IDOC_IN service for submission to R/3. Required.
CR3_ALEIN_IDOCIN_QUEUE_SPACE | Queue Space | Queue space that contains the CR3_IDOC_IN queue. Required.
CR3_ALEIN_ERROR_QUEUE | Queue Name | Name of the queue for messages containing IDOCs that the CR3_SUBMIT has received and rejected due to IDOC format or consistency errors. By default, should be set to CR3_ERROR. Required.
CR3_ALEIN_ERROR_QUEUE_SPACE | Queue Space | Queue space that contains the CR3_ERROR_QUEUE. Required.
Logging |  |
CR3_ALEIN_PRINT_FILE | Path and File | Specifies the full path and file for logging and tracing output. If this variable is not used (value is null), output is sent to the TUXEDO USERLOG. Optional.
CR3_TRACE | Y or N | Specify "Y" to include detailed trace information in the log output. Optional.

Sample Environment File for eLink-to-R/3 (cr3alein.env)

BEA eLink Adapter for R/3 ALE provides a semi-configured TUXEDO environment file (cr3alein.env) for use with the eLink-to-R/3 server. You should create a separate environment file for each eLink-to-R/3 server specified in the cr3_ale.ubb configuration file.

Note the settings in the sample cr3alein.env file:

Listing 5-2 Sample Environment File (cr3alein.env)

>     CR3_DESTINATION=<R/3 system name>
>     CR3_CLIENT=<R/3 client id>
>     CR3_USER=<R/3 user>
>     CR3_PASSWORD=<R/3 password>
>     CR3_LANGUAGE=E
>     CR3_ALEIN_TID_FILE=<your eLink app directory>\cr3alein
>     CR3_ALEIN_TID_PER_IDOC=N
>     CR3_ALEIN_IDOCIN_QUEUE=CR3_IDOC_IN
>     CR3_ALEIN_IDOCIN_QUEUE_SPACE=QSPACE
>     CR3_ALEIN_ERROR_QUEUE=CR3_ERRQUE
>     CR3_ALEIN_ERROR_QUEUE_SPACE=QSPACE
>     CR3_ALEIN_PRINT_FILE=<your eLink app directory>\cr3alein.log
>     CR3_ALEIN_TRACE=Y

Note: You can use any directory for the eLink application directory. However, it is recommended that you use the same directory as the TUXEDO APPDIR.

Setting Up the eLink-to-R/3 Connection to R/3

To set up the eLink-to-R/3 connection to R/3, you must set environment variables and configure the sideinfo file. See Configuring eLink-to-R/3 Connections in Chapter 6, "Configuring R/3 Connections" for instructions.

Configuring Queues for eLink-to-R/3

eLink-to-R/3 requires that you set up two TUXEDO queues, CR3_ALE_ERROR_QUEUE and CR3_ALE_IDOC_IN_QUEUE. See "Setting Up Queues for eLink-to-R/3 IDOCs" later in this topic for instructions.

Specifying the TID File for eLink-to-R/3

eLink-to-R/3 uses a TID file to log TIDs that it has already processed to guarantee that it delivers an IDOC packet to R/3 once and only once. You must specify the path and file name of the TID file (without an extension) in the CR3_ALEIN_TID_FILE environment variable, as shown in the following example:

>     CR3_ALEIN_TID_FILE=<your eLink app directory>\cr3alein

Upon start-up, if the eLink-to-R/3 server does not find a TID file in the specified location, it creates one automatically. See "Configuring the TID File Manager" on page 5-27 for information about configuring and administering the TID file.

Splitting eLink-to-R/3 IDOC Packets Containing Multiple IDOCs

By default, eLink-to-R/3 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 IDOC separate packets, each containing a single IDOC and associated with a unique TID.

To split eLink-to-R/3 IDOC packets, set the CR3_ALEIN_TID_PER_IDOC environment variable to "Y", as shown in the following example:

>     CR3_ALEIN_TID_PER_IDOC=Y

See "Splitting eLink-to-R/3 IDOC Packets Containing Multiple IDOCs" in Integrating with ALE, of this guide for more information.

Configuring Logging for eLink-to-R/3

By default, eLink-to-R/3 writes logging output to the TUXEDO USERLOG. If sending output to a file, you must specify its name and location in the CR3_ALEIN_PRINT_FILE environment variable.

You can also include trace information in the log by setting the CR3_TRACE environment variable to "Y". You exclude trace information by omitting this environment variable or setting it to "N".

The following example sets logging options for eLink-to-R/3:

>     CR3_ALEIN_PRINT_FILE=<your eLink app directory>\cr3alein.log
>     CR3_TRACE=Y

Configuring the R/3-to-eLink Server

The R/3-to-eLink is a TUXEDO server. Configuration is required in the TUXEDO UBB file to run the R/3-to-eLink server within the TUXEDO domain. An environment file will define detailed configuration information required by the R/3-to-eLink.

The following topics describe how to configure the R/3-to-eLink server:

- Configuring the UBB File for R/3-to-eLink

- Setting Environment Variables for R/3-to-eLink

- Configuring Load Balancing for R/3-to-eLink

- Configuring Multiple Program IDs

See "Setting Up Queues for R/3-to-eLink IDOCs" later in this topic for configuration instructions.

The R/3-to-eLink server receives R/3-to-eLink IDOC packets from R/3 via Transactional RFC (tRFC); encodes each IDOC packet to an FML32 message buffer; and queues the IDOC message into a TUXEDO queue for subsequent processing. See "Processing R/3-to-eLink IDOCs" in Integrating with ALE, of this guide for more information about R/3-to-eLink.

Configuring the UBB File for R/3-to-eLink

R/3-to-eLink is a standard TUXEDO server that is defined in the UBB file. You must configure this file to specify the server group, server, and environment file associated with the R/3-to-eLink server. See Appendix A, "Sample cr3_ale.ubb File," for a listing of the sample UBB file that comes with the BEA eLink Adapter for R/3 ALE.

Defining the R/3-to-eLink Server (cr3aleout)

In the SERVERS section of your UBB file, you must specify the R/3-to-eLink server as cr3aleout, then define it in the succeeding code lines by specifying its server group, server ID, and environment file.

Do this using the following syntax:

>     cr3aleout
>     	SRVGRP=GroupId SRVID=ServerID
>     	CLOPT = "-A -- -i unique_id -e env_filename"

where:

- GroupID is the unique ID of the server group to which the R/3-to-eLink server belongs.

- ServerID is the unique ID of the R/3-to-eLink server.

- -i unique_id is the unique ID that identifies the label section in the environment file containing the adapter's environment variables. You would use this value when you run multiple eLink adapters that share this configuration file. If it is not specified, then the unique ID defaults to the process name.

- -e env_filename is the environment file that specifies the environment for the R/3-to-eLink server.

Listing 5-3 shows SERVERS settings for the R/3-to-eLink server (cr3aleout) in a sample UBB file for Windows NT:

Listing 5-3 Sample SERVERS Settings for R/3-to-eLink Server

>     cr3aleout
>     	SRVGRP=CR3 SRVID=4
>     	CLOPT="-A -- -i cr3aleout -e cr3aleout.env"

Setting Environment Variables for R/3-to-eLink

The detailed configuration information for the R/3-to-eLink is specified in an environment file. The configuration information is grouped into the following tables. Users must provide server connection variables, client connection variables, generic configuration variables, and some additional variables based on different TUXEDO actions.

The environment variables for an adapter can be specified in an environment file individually or as part of a combined environment file with environment variables for other adapters. See the "Description" for the [SERVER=..] adapter unique ID variable in Table 5-7 for more information.

Adapter Unique ID Variable

You can configure the following adapter unique ID variable for the R/3-to-eLink server:

####

Table 5-2 Adapter Unique ID Variable for the R/3-to-eLink Server

Task / Variable | Value | Description
--- | --- | ---
[SERVER=..] | String The adapter unique ID will either be the value of the -i flag on the CLOPT line, or if not specified, then the default value of the process name. | Adapter unique id. The label section defines all the environment variables for this adapter with this adapter unique id. If the environment file specifies environment variables for more than one adapter, the [SERVER=..] environment variable must be presented to distinguish the environment variables for this adapter with this adapter unique id from the environment variables for other adapters. Required.

Server Connection Variables

You can configure the following server connection variables for the R/3-to-eLink server:

####

Table 5-3 Server Connection Variables for the R/3-to-eLink Server

Task / Variable | Value | Description
--- | --- | ---
CR3_HOST | String | Destination switch in the sideinfo file. This setting is case sensitive. Required.
CR3_SOCKET | String | R/3 socket. Required.
CR3_PROGRAM_ID | String | R/3 program ID. Required.

R/3 Client Connection Variables

You can configure the following client connection variables for the R/3-to-eLink server:

####

Table 5-4 Client Connection Variables for the R/3-to-eLink Server

Task / Variable | Value | Description
--- | --- | ---
CR3_DESTINATION | String | Destination switch in the sideinfo file. This setting is case sensitive. Required.
CR3_CLIENT | String | R/3 client. Required.
CR3_USER | String | R/3 user. Required.
CR3_PASSWORD | String | R/3 password. Required.
CR3_LANGUAGE | String | R/3 logon language. E for English is the default. This setting should not be changed because no other language is presently supported. Required.
SIDE_INFO | String | Path and file name of sideinfo file. This file defines the R/3 connection information that is used by the ALE library. Note: R/3-to-eLink will not read this environment variable; it is read by the ALE library - it is documented here for completeness only. Required.

Other Required and Optional Environment File Variables

You can configure the following required and optional environment variables for R/3-to-eLink:

####

Table 5-5 Environment Variables for the R/3-to-eLink Server

Variable | Set To | Description
--- | --- | ---
Configuring IDOC Routing |  |
CR3_ALE_DEFAULT_TARGET_ID | Data-dependent routing (DDR) value | Default data-dependent routing value that is encoded in the CR3_TARGET_ID field in the FML32 message (if it cannot be determined for a particular IDOC in the environment file). This environment variable must be defined. Required.
Splitting IDOC Packets |  |
CR3_ALE_DEFAULT_IDOC_SPLIT | Y or N | If an IDOC section cannot be found that matches the outbound IDOC's control record with respect to logical ID and message type, this setting specifies whether IDOC packets containing multiple IDOCs are passed either together in a single message (if variable = "N") or split into separate IDOC packets, with one IDOC per message (if variable = "Y"). Optional.
Configuring Queues |  |
CR3_ALE_TARGET_QUEUE | Queue | Name of the default target TUXEDO queue. This is used if no IDOC section of the environment file matches the outbound IDOC with respect to logical ID and message type. Required.
CR3_ALE_TARGET_QUEUE_SPACE | Queue Space | Name of the TUXEDO queue space containing the default target queue. Required.
Configuring the TID Log File |  |
CR3_ALEOUT_TID_FILE | Path and File Name | Name and location of the TID file. The file name must not include an extension. Required.
Logging Options |  |
CR3_ALEOUT_PRINT_FILE | Path and File | Specifies the full path and file for logging and tracing output. If this variable is not used (value is null), output is sent to the TUXEDO USERLOG. Optional.
CR3_TRACE | Y of N | Specify "Y" to include detailed trace information in the log output. Optional.

These environment variables are defined in the server startup program.

Generic Configuration Variables

You can configure the following generic configuration variables for the R/3-to-eLink server:

####

Table 5-6 Generic Configuration Variables for the R/3-to-eLink Server

Task / Variable | Value | Description
--- | --- | ---
CR3_EXIT_R3_CONNECT_ LOSS | Y or N | Specifies whether R/3-to-eLink is to exit when it detects that it has lost the ALE connection to R/3. If not specified or defined as a value other than Y, then R/3-to-eLink will not exit upon losing the ALE connection and will try to restore it. Required.
CR3_CONNECT_RETRY_ ATTEMPTS | Number | Number of connection retry attempts. If CR3_EXIT_R3_CONNECT_LOSS = "Y," the adapter will exit no matter what the value is for this variable. If CR3_EXIT_R3_CONNECT_LOSS = "N," then there are two options: 1) CR3_CONNECT_RETRY_ ATTEMPTS (this variable) and CR3_CONNECT_RETRY_ INTERVAL (next variable) have null values. With this option, the adapter will continue trying to make a connection until it is successful. 2) If values are provided for CR3_CONNECT_RETRY_ ATTEMPTS (this variable) and CR3_CONNECT_RETRY_ INTERVAL (next variable), the connection is attempted according to these values. Required.
CR3_CONNECT_RETRY_ INTERVAL | Number with minimum 1 | Time is seconds. It is the length of time the system waits before attempting to make another connection to R/3. If CR3_EXIT_R3_CONNECT_LOSS = "Y," the adapter will exit no matter what the value is for this variable. If CR3_EXIT_R3_CONNECT_LOSS = "N," then there are two options: 1) CR3_CONNECT_RETRY_ ATTEMPTS (this variable) and CR3_CONNECT_RETRY_ INTERVAL (next variable) have null values. With this option, the adapter will continue trying to make a connection until it is successful. 2) User can provide values for CR3_CONNECT_RETRY_ ATTEMPTS (this variable) and CR3_CONNECT_RETRY_ INTERVAL (next variable), the connection is attempted according to these values. Required.

These environment variables are defined in the server startup program.

Configuration Variables for Destination Mapping

These configuration variables specify IDOC destination mapping so that R/3-to-eLink can queue IDOC messages into different target queues, manage data-dependent routing, and group similar IDOC messages into larger IDOC messages. 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 of the target R/3 System and the IDOC message type specified in an IDOC section (which starts with [CR3_IDOC=..].) match these same settings specified in an IDOC's control record, R/3-to-eLink automatically splits IDOC packets containing multiple IDOCs into separate IDOC messages, with each message containing a single IDOC.

####

Table 5-7 Configuration Variables for Destination Mapping

Task / Variable | Value | Description
--- | --- | ---
CR3_IDOC_LIST | String | Comma-separated list of all IDOC names.
[CR3_IDOC=..] | String | IDOC Name. The six configuration variables immediately below the bracketed line specify the destination mapping for IDOCs with this name.
RECIEVER_PARTNER_ NUMBER | String | Logical System ID of the target R/3 logical system.
MESSAGE_TYPE | String | Message type specified in the IDOC.
COMPRESS | Y or N | If Compress=Y, then R/3-to-eLink concatenates IDOC packets with matching logical system and IDOC message type values into a single IDOC message in the queue. If Compress=N, then R/3-to-eLink keeps the IDOCs in individual IDOC messages.
ROUTING | String | Data-dependent routing (DDR) value. The value is encoded in the FML field CR3_TARGET_ID for use with DDR.
QUEUE_SPACE | String | Name of the destination queue space for the IDOC message.
QUEUE_NAME | String | Name of the destination queue for the IDOC message.

Sample Destination Mapping Settings

Listing 5-4 shows destination mapping settings for the IDOCs in a sample cr3aleout.env file for Windows NT:

Listing 5-4 Sample Destination Mapping Settings for Outbound IDOCs

>     CR3_IDOC_LIST=MaterialMaster
>     [CR3_IDOC=MaterialMaster]
>     RECIEVER_PARTNER_NUMBER=ALETEST01
>     MESSAGE_TYPE=MATMAS
>     COMPRESS=N
>     ROUTING=CR3_ERROR
>     QUEUE_SPACE=QSPACE
>     QUEUE_NAME=CR3_ERRQUE

Specifying Default Target Queue Spaces and Queue Names in the Environment File

You use the QUEUE_SPACE and QUEUE_NAME settings in the environment file to associate an IDOC with a destination TUXEDO queue space and queue. If an IDOC section in the environment file matches the logical system ID of the target R/3 System and the IDOC message type specified in an IDOC's control record, then R/3-to-eLink queues the IDOC into the specified queue space and queue name. If no matching combination of logical system ID and IDOC message type is found in an IDOC section of the environment file, then R/3-to-eLink queues the IDOC message into the default queue space and queue, which are specified in the CR3_ALE_TARGET_QUEUE_SPACE and CR3_ALE_TARGET_QUEUE environment variables.

Note: You must create the default queue and any individual queues before processing R/3-to-eLink IDOCs. See "Setting Up Queues for R/3-to-eLink IDOCs" later in this topic for information.

Setting Data-Dependent Routing Values in the Environment File

You use the TargetId (ROUTING) settings in the environment file to associate an IDOC with a data-dependent routing value. If the logical system ID of the target R/3 System and the IDOC message type specified in an IDOC section of the environment file match the logical system ID and message type of an IDOC's control record, then R/3-to-eLink encodes the specified TargetId value in the CR3_TARGET_ID FML32 field of the IDOC message. If no matching section is found in the environment file, 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" on page 5-18 for more information.

Compressing R/3-to-eLink IDOCs

You use the COMPRESS environment variable to combine IDOC messages with matching logical system IDs and IDOC message types into an IDOC message containing multiple IDOCs. If the logical system ID of the target R/3 System and the IDOC message type specified in an IDOC section of the environment file match the logical system ID and message type of an IDOC's control record, and its COMPRESS setting is "Y", then R/3-to-eLink aggregates the IDOCs with matching criteria into a single, larger IDOC message that it then queues into the appropriate target queue. If the Compress setting is "N", then R/3-to-eLink queues each IDOC message separately.

Configuring Queues for R/3-to-eLink

R/3-to-eLink requires that you set up at least one default TUXEDO queue and additional queues as needed. See "Setting Up Queues for R/3-to-eLink IDOCs" later in this topic for instructions.

Setting the Default Data-Dependent Routing Value

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.

Set the CR3_ALE_DEFAULT_TARGET_ID environment variable to a DDR value in the cr3aleout.env file as follows:

>     CR3_ALE_DEFAULT_TARGET_ID=DDR_VALUE

The following is an example from that file setting the default target ID to CR3_ERROR:

>     CR3_ALE_DEFAULT_TARGET_ID=CR3_ERROR

See "Setting Data-Dependent Routing Values in the Environment File" later in this topic and "Managing Data-Dependent Routing" in Chapter 2, "Integrating with ALE," in this guide for more information.

Splitting R/3-to-eLink IDOC Packets

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 queues the entire IDOC packet. If you set the CR3_ALE_DEFAULT_IDOC_SPLIT environment variable to "Y", R/3-to-eLink will split the IDOC packet into individual IDOC packets. See "Splitting R/3-to-eLink IDOC Packets Into Individual IDOCs" in Integrating with ALE, of this guide for more information.

Specifying the TID File for R/3-to-eLink

R/3-to-eLink uses a TID file to log TIDs that it has already processed to guarantee that it queues an IDOC packet from R/3 once and only once. You must specify the path and file name of the TID file (without an extension) in the CR3_ALEOUT_TID_FILE environment variable, as shown in the following example (Windows NT):

>     CR3_ALEOUT_TID_FILE=<your eLink app directory>\cr3aleout

Upon start-up, if R/3-to-eLink does not find a TID file in the specified location, it creates one automatically. See "Configuring the TID File Manager" later in this topic for information about configuring and administering the TID file.

Configuring Logging for R/3-to-eLink

By default, R/3-to-eLink writes logging and tracing output to the TUXEDO USERLOG. If your are sending output to a file, you must specify its name and location in the CR3_ALEOUT_PRINT_FILE environment variable.

You can also include trace information in the log by setting the CR3_TRACE environment variable to "Y". You exclude trace information by omitting this environment variable or setting it to "N".

The following example from the R/3-to-eLink environment file, cr3aleout.env, sets logging options for R/3-to-eLink:

>     CR3_ALEOUT_PRINT_FILE=
>     CR3_ALEOUT_TRACE=Y

Configuring Load Balancing for R/3-to-eLink

Multiple instances of R/3-to-eLink can log onto R/3 and submit R/3-to-eLink IDOCs for processing. For deployments that involve high volumes of R/3-to-eLink IDOCs, you can enhance system performance by balancing the load across multiple instances of R/3-to-eLink.

Use TUXEDO's load balancing capabilities to manage the number of R/3-to-eLink instances running. See your BEA TUXEDO documentation regarding TUXEDO administrative tools for more information.

Note: Each instance of R/3-to-eLink requires a separate R/3 login, so be sure to tune the number of concurrent instances to optimize system performance without requiring excessive R/3 resources. Instances can log in using the same user name and password.

Example:

More than one instance of R/3-to-eLink can be specified in cr3_ale.ubb. The number of instances you can specify is limited only by the capacity of the network on which you are running. Two instances have been defined in Listing 5-5. For more information on the meaning of the various commands and switches used in this example, see "Defining the R/3-to-eLink Server (cr3aleout)."

Listing 5-5 Configuring Two Instances of R/3-to-eLink in cr3_ale.ubb

>     cr3aleout
>         SRVGRP=CR3 SRVID=5
>         CLOPT="-A -- -i cr3aleout1 -e cr3aleout.env"
>     cr3aleout
>         SRVGRP=CR3 SRVID=6
>         CLOPT="-A -- -i cr3aleout2 -e cr3aleout.env"

Then, cr3aleout.env must be appended so there are two matching sections, one for cr3aleout1 and one for cr3aleout2. All of the settings specified in "Setting Environment Variables for R/3-to-eLink" must be set. The first few lines of each server section are shown in Listing 5-6.

Listing 5-6 Settings for cr3aleout1 and cr3aleout2 in cr3aleout.env

>     [SERVER=cr3aleout1]
>     CR3_DESTINATION=delia
>     CR3_SOCKET=sapgw00
>     ...
>     [SERVER=cr3aleout2]
>     CR3_DESTINATION=delia
>     CR3_SOCKET=sapgw00
>     ...

Configuring Multiple Program IDs

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

The example shown in Listing 5-7 uses the same cr3_ale.ubb file as the load balancing example shown in "Configuring Load Balancing for R/3-to-eLink." Notice that the CR3_PROGRAM_ID for the cr3aleout1 server is bea.cr3.tim.ale, but the CR3_PROGRAM_ID for the cr3aleout2 server is bea.cr3.malay.ale.

Listing 5-7 Configuring for Multiple Program IDs in cr3aleout.env

>     [SERVER=cr3aleout1]
>     CR3_DESTINATION=delia
>     CR3_SOCKET=sapgw00
>     CR3_PROGRAM_ID=bea.cr3.tim.ale
>     ...
>     [SERVER=cr3aleout2]
>     CR3_DESTINATION=delia
>     CR3_SOCKET=sapgw00
>     CR3_PROGRAM_ID=bea.cr3.malay.ale
>     ...

See "Registering Multiple Program IDs" in Chapter 2, "Integrating with ALE," in this guide for more information.

Generating a Transaction Log

The eLink-to-R/3 and R/3-to-eLink servers use TUXEDO transactions. For these components, you need to create a transaction log (TLOG). The cr3_tlog file for your platform generates the transaction log (TLOG) when it is run with the following command:

>     > nmake -f cr3_tlog.nt (cr3_tlog.sh on UNIX)

Normally, this files does not need to be edited. Of course, there are always exceptions to the rule. For information on how this file should be edited, see the topic "crlog: Create the Transaction Log" in the "BEA Tuxededo /Q Guide." using TUXEDO administrative tools.

Configuring Queues

The following topics describe how to create and configure TUXEDO queues for ALE processing:

- TUXEDO Queues

- Setting Up Queues for eLink-to-R/3 IDOCs

- Setting Up Queues for R/3-to-eLink IDOCs

TUXEDO Queues

You must set up queues and queue spaces for both eLink-to-R/3 and R/3-to-eLink. You need to create and configure the Server Group (TMS_QM), Message Queue Server (TMQUEUE) and Message Forwarding Server (TMQFORWARD).

Using the cr3_queues Makefiles to Add Queues

The queue space QSPACE and the queues CR3_IDOC_IN, CR3_SUBMIT, and CR3_ERRQUE. The queues are generated inside the queue space QSPACE when the makefile described in Listing 5-8 is run with the following command:

>     > nmake -f cr3_queues.nt (cr3_queues.sh on UNIX)

Listing 5-8 cr3_queues.nt Makefile (Sample Supplied with Software)

>     all:	que
>     que:
>     	del /q $(APPDIR)\QUE
>     	(set QMCONFIG=$(APPDIR)\QUE) &
>     	qmadmin $(APPDIR)\QUE < <<
>     echo
>     crdl $(APPDIR)\QUE 0 400
>     # The following section adds queue spaces and queues.

>     qspacecreate
>     QSPACE
>     62849
>     100
>     6
>     4
>     9
>     20
>     y
>     16

>     qopen QSPACE
>     qcreate
>     CR3_IDOC_IN
>     fifo
>     none
>     2
>     30
>     80%
>     0%

>     qcreate
>     CR3_SUBMIT
>     fifo
>     none
>     2
>     30
>     80%
>     0%

>     qcreate
>     CR3_ERRQUE
>     fifo
>     none
>     2
>     30
>     80%
>     0%
>     #end of section that needs to be copied to create custom queues
>     q
>     <<NOKEEP
>     rmipc:
>     	(set QMCONFIG=$(APPDIR)\QUE) &
>     	qmadmin $(APPDIR)\QUE < <<
>     echo
>     ipcrm -y QSPACE
>     <<NOKEEP

Actually, this script uses the TUXEDO qmadmin utilities called qspacecreate and qcreate to create this queue space and these queues. If you need to create additional queues, you can do so by copying a portion of this script to a point in the cr3_queues makefile just above the single q, then changing the queue space and queue names to the names of the custom queue spaces and queues that you want to create.

In the following example, the queue space QS1 is created, and the queues Q1 and Q2 are created inside it (text that must be changed is marked in BOLD:

>     qspacecreate
>     QS1
>     62849
>     100
>     6
>     4
>     9
>     20
>     y
>     16

>     qopen QS1
>     qcreate
>     Q1
>     fifo
>     none
>     2
>     30
>     80%
>     0%

>     qcreate
>     Q2
>     fifo
>     none
>     2
>     30
>     80%
>     0%

For an explanation of queue space and queue parameters for the queue spaces and queues being created see the "Creating Queue Space and Queues" section of the /Q Guide in your BEA TUXEDO documentation.

Note: You can also create queue spaces and queues manually using the instructions described in the BEA TUXEDO /Q Guide.

Setting Up Queues for eLink-to-R/3 IDOCs

eLink-to-R/3 uses the following queues:

####

Queue Name | Description
--- | ---
CR3_SUBMIT | IDOC submit queue. Handles IDOC packets that a TUXEDO application or other application has submitted to the CR3_SUBMIT service for processing.
CR3_ERROR | IDOC error queue. Handles invalid IDOC packets that have failed validation by the CR3_SUBMIT service.
CR3_IDOC_IN | IDOC eLink-to-R/3 queue. Handles IDOC packets that the CR3_SUBMIT service has validated, assigned a TID, and queued. TMQFORWARD forwards each IDOC packet to the CR3_IDOC_IN service for submission to R/3.

Use the TUXEDO Queue manager administration utility (qmadmin) to create these queue spaces and queues. See the /Q Guide in your BEA TUXEDO documentation for instructions.

Defining the TMQUEUE and TMQFORWARD Servers in the UBB File

In the SERVERS section of your UBB file, define the TMQUEUE and TMQFORWARD servers:

Listing 5-9 Sample SERVERS Section of UBB File

>     TMQUEUE
>           SRVGRP=QUE SRVID=1
>        GRACE=0  RESTART=Y CONV=N  MAXGEN=10
>           CLOPT="-s QSPACE:TMQUEUE --  "
>     TMQFORWARD
>           SRVGRP=QUE SRVID=2
>        GRACE=0  RESTART=Y CONV=N  MAXGEN=10
>           CLOPT=" -- -i 10 -q CR3_IDOC_IN,CR3_SUBMIT"

Setting Environment Variables

After creating the error and eLink-to-R/3 queue spaces and queues, specify their names in environment variables:

Listing 5-10 Setting Environment Variables for Queues

>     CR3_ALEIN_IDOCIN_QUEUE=CR3_IDOC_IN
>     CR3_ALEIN_IDOCIN_QUEUE_SPACE=QSPACE
>     CR3_ALEIN_ERROR_QUEUE=CR3_ERROR
>     CR3_ALEIN_ERROR_QUEUE_SPACE=QSPACE

See Table 5-1 earlier in this topic for a description of these environment variables.

Setting Up Queues for R/3-to-eLink IDOCs

R/3-to-eLink can queue R/3-to-eLink IDOC messages into one or more queues. At a minimum, you must create at least one default queue. If you are using the cr3aleout.env file to queue IDOC messages to multiple queues, you must create all the target queues, including the default queue.

Use the TUXEDO Queue manager administration utility (qmadmin) to create these queue spaces and queues. See the /Q Guide in your BEA TUXEDO documentation for instructions.

After creating the R/3-to-eLink queues, specify the default queue space and queue name in environment variables by adding the following lines to your cr3aleout.env file:

>     CR3_ALE_TARGET_QUEUE=QUEUE_NAME
>     CR3_ALE_TARGET_QUEUE_SPACE=QUEUE_SPACE_NAME

Example:

>     CR3_ALE_TARGET_QUEUE=CR3_SUBMIT
>     CR3_ALE_TARGET_QUEUE_SPACE=QSPACE

See Table 5-2 earlier in this topic for a description of these environment variables.

Configuring the TID File Manager

The following topics describe the TID File Manager, a command line utility that manages the size of the TID file in the run-time environment:

- Command Line Options

- Running the TID File Manager

- How the TID File Manager Works

Command Line Options

The TID File Manager uses the command line options shown in Table 6-4:

####

Table 5-8 Command Line Options for the TID File Manager

Option | Description
--- | ---
-h or -? | Help text that describes each option.
-f | Name of the TID file (path is optional). Required.
-n | Number of lines to keep in the TID file. Default is 10 lines. If the date (-d) option is also specified, this setting overrides the date setting. The TID File Manager retains at least this number of lines in the original TID file.
-t | Frequency (in seconds) with which the TID File Manager periodically checks the TID file. Default is 60 seconds. If this option is omitted, then the TID File Manager runs once and exits. If this option is specified, the TID File Manager keeps running. Optional.
-d | Last save date. The TID File Manager removes any CONFIRMED entries that are older than the specified date. Valid date formats include: Jan/1/2000 2000,1,jan "1 JAN 2000"

Running the TID File Manager

To run the TID File Manager, enter the following command:

>     cr3tidmanager -f FileName [OptionalParameters]

where FileName is required and OptionalParameters include any of the other options in Table 5-8, "Command Line Options for the TID File Manager," on page 5-28.

Note: You must run a separate TID File Manager for each TID file used by instances of eLink-to-R/3 and R/3-to-eLink.

How the TID File Manager Works

Upon startup, the TID File Manager does the following:

- Locks the specified TID file.

- Creates a backup file using the original file name plus the date-time and a .bck extension.

- Removes from the TID log file only CONFIRMED entries that meet the configured criteria.

- Appends each removed entry to the backup file.

- Saves both files.

- Releases the file lock.

Because the TID File Manager locks the file while editing, be careful to specify a large enough frequency to contain the file size without slowing run-time performance.

Shutting Down the BEA eLink Adapter for R/3 ALE

The BEA eLink Adapter for R/3 ALE is a series of eLink Platform servers that are constantly running. If you change your configuration, you must stop or shutdown these servers, then restart them, or the servers will continue to operate according to the configuration under which they were started. For more information on reconfiguring and restarting the BEA eLink Adapter for R/3 ALE, see Configuration Quick Reference. Shutdown the eLink Platform servers by performing the following series of commands:

1. Shutdown all R/3-to-eLink (outbound) servers with the following command:

   >     > tmshutdown -i ServerID -k KILL

   where ServerID is the unique ID of the R/3-to-eLink server. This would be whatever is set as the SRVID parameter for all cr3aleout servers in cr3_ale.ubb. In the sample cr3_ale.ubb listed in Sample Configuration Files, the ServerID value is "4."

2. Shutdown the remaining eLink Platform servers with the command:

   >     > tmshutdown -y

3. Repeat the command to make sure that all of the eLink Platform servers are shut down:

   >     > tmshutdown -y

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.