Configuring Java CAPS Environment Components for Communications Adapters

Configuring IMS Adapter Environment Properties

The IMS Adapter configuration parameters, accessed from the Environment Explorer tree, are organized into the following sections:

TCP/IP Configuration

The TCPIP Configuration section contains information for connecting to the Portal Infranet. This section contains the top level parameters, as displayed in the following table.

Table 65 Environment TCP/IP Configuration Settings


Name	Description	Required Value
Server	Specifies the name of the server host. This parameter is mandatory.	The server host name.
Port	Specifies the port that IMS Connect is listening on. This parameter is mandatory.	A number indicating the port on which IMS Connect is listening. The default is 7777.

IRM Header

The IRM (IMS Request Message) Header section contains the top-level parameters displayed in the following table.

Note –

For a full description of the IRM header, see IBM’s IMS Connect Guide and Reference (SC27-0946-00).

Table 66 Environment IRM Header Settings


Name	Description	Required Value
IRM_LEN	Specifies the length of the IRM structure. The user written exits minimum size is 36. HWSIMSO0 and HWSSMPL1 have a minimum IRM length of 80.	An integer indicating valid IRM structure length. The configured default is 80.
IRM_ID	Specifies the identifier (character string) of the user exit that is driven after the complete message is received. In a program, an exit is used to move from the called routine back to the calling routine. A routine can have more than one exit point, thus allowing termination based on various conditions. The following IDs are used by the IMS Connect-supplied user message exits: IRMREQ (for HWSIMSO0) SAMPL1 (for HWSSMPL1)	The appropriate identifier character string. The configured default is *SAMPL1*.
IRM_TIMER	Specifies the time delay for the receive to the Datastore after an ACK or RESUME TPIPE. One of following three predefined timer options can be selected: .25 SEC: .25 seconds. No_Wait: Timer is not set and no delay occurs. Block: The receive waits indefinitely. This setting is used to support the Auto option of the asynchronous output function. OR One of the following hex values can be entered as a timer value: X01 - X19: Range from 0.01 to 0.25 second, 0.01 second increments. X19 - X28: Range from 0.25 to 1 second, 0.05 second increments. X28 - X63: Range from 1 to 60 second, 1 second increments. X63 - X9E: Range from 1 to 70 minutes, 1 minute increments.	Select one of the three predefined options or enter a valid hex value. The configured default is .25 SEC. Note – The following hex values correspond to the three predefined choices in the drop-down menu: X00 = Default - .25 secs XE9 = No_Wait - Does not set the timer XFF = Block
IRM_SOCT	Specifies the socket connection type. Transaction: Transaction socket. The socket connection lasts across a single transaction. Persistent: Persistent socket. The socket connection lasts across multiple transactions. Non_Persistent: Non-persistent socket. The socket connection lasts for a single exchange consisting of one input and one output. Do not use Non_Persistent when implementing conversational transactions because this type causes multiple connects and disconnects.	Select one of the three options. The configured default is Persistent. Note – The default for this property was changed from the previous version.
IRM_CLIENTID	Specifies the name of the client ID (character string) to be used by IMS Connect. IMS Adapter supports both Serial and Parallel mode. Serial mode is supported by specifying a ClientID. Parallel mode is supported by specifying a ClientID with an . Note –* In each deployment, the ClientID must be unique.	The client ID to be used by IMS Connect.
IRM_F1 (MFS MOD Names)	Specifies whether the MFS Message Output Descriptor (MOD) is returned as part of the output. MFS: The user requests that MFS MOD name be returned. NO_MFS: The user requests that no MFS MOD name be returned. When MFS is specified, a Request Mod Message (RMM) is returned as the first structure of the output message. This structure contains an ID of REQMOD followed by the MFS MOD name. For details, see IBM’s IMS Connect Guide and Reference, (SC27-0946-00).	Select MFS or NO_MFS. The default is NO_MFS.
IRM_F2 (COMMIT MODE)	Specifies the Commit Mode. COMMIT_MODE_0 - Also known as commit-then-send. COMMIT_MODE_1 - Also known as send-then-commit. For a full description of the IRM header, see IBM’s IMS Connect Guide and Reference (SC27-0946-00).	Select COMMIT_MODE_0 or COMMIT_MODE_1. The default is COMMIT_MODE_1. Note – The default for this property was changed from the previous version.
IRM_F3 (Sync Level)	Specifies whether the message is to be confirmed with an ACK for Commit Mode 1 processing. For Commit Mode 0, IRM_F3 must be set to SYNC_LEVEL_CONFIRM. SYNC_LEVEL_CONFIRM: Must be used when the IRM_F2 parameter (commit mode) is set to COMMIT_MODE_0. SYNC_LEVEL_NONE: No Sync level.	Select SYNC_LEVEL_CONFIRM or SYNC_LEVEL_NONE. If the IRM_F2 property is set to COMMIT_MODE_0, the Sync level must be set to SYNC_LEVEL_CONFIRM. The default is SYNC_LEVEL_NONE. Note – The default for this property was changed from the previous version.
IRM_F4 (ACK/NAK/ Response)	Specifies the ACK/NAK (positive/negative acknowledgement) response expression sent to IMS Connect and forwarded to IMS. The ACK/NAK/DEALLOCATE /RESUME [A/N/D/R] values must be sent to IMS Connect with no data element. NO_ACK: No request for acknowledgment or deallocation. When a response mode transaction or conversational transaction is being sent to IMS Connect, IRM_F4 must be set to NO_ACK. ACK: Positive acknowledgment, used in response to a message sent to the client where the SYNC level is set to CONFIRM (SYNC _LEVEL_CONFIRM). DEALLOCATE: Deallocate connection. Used to terminate a conversation before the conversation is complete. NACK: Negative acknowledgment. Used in response to a message sent to the client where the SYNC level is set to CONFIRM (SYNC _LEVEL_CONFIRM). RESUME: Resume TPIPE. Used to request Asynchronous output data from IMS. Resume must execute on a transaction socket as COMMIT_MODE_0. SENDONLY: Send only, used for a non-response transaction and for sending data to IMS. SENDONLY must execute as COMMIT_MODE_0.	Select one of the six options. The configured default is NO_ACK.
IRM_F5 (Flow Control)	Specifies Flow Control properties. Sun recommends using the default value No_Auto_Flow. Note – : Contact Sun Support before using any value other than No_Auto_Flow. Client_Translation: Translation is done by the client. Single_Message: Returns only one message on receive following the resume TPIPE. No_Auto_Flow: No message auto flow (see meaning for No_Auto_Flow_Out). Auto_Flow_Out: Auto message flow. Returns all current messages, one at a time, and waits on the last receive for the next message for IRM_TIMER value. Set the IRM_TIMER high. Use this only for a dedicated output client. No_Auto_Flow_Out: No message auto flow. Returns all current messages one at a time, and waits on the last receive for the next message for IRM_TIMER value. Set the IRM_TIMER low. Use this only for a dedicated output client. This value is similar to Auto_Flow_Out, as described above, except that the IRM_TIMER causes the last receive to terminate.	The recommended default setting is No_Auto_Flow.
IRM_TRNCOD	Specifies the default IMS transaction code.	A valid transaction code.
IRM_TRNCOD_SRC	Specifies where the transaction code is taken. CFG: The transaction code is to be taken from the configuration file. MESSAGE: the transaction code is the first 8 bytes of the message.	Select one of the two options. The configured default is CFG.
IRM_DESTID	Specifies the Datastore name (IMS destination ID). This field is required.	String-set. A Datastore name/IMS destination ID (character string).
IRM_LTERM	Specifies the IMS LTERM override name. This field can be set to a name or blank.	The appropriate LTERM name or blank.
IRM_RACF_GRNAME	Specifies the RACF Group Name. The client must provide the RACF group name if RACF is to be used.	The appropriate RACF group name.
IRM_RACF_USERID	Specifies the RACF User ID. The client must provide the RACF user ID if RACF is used.	A valid RACF user ID.
IRM_RACF_PW	Specifies the RACF PASSTICKET. The client must provide the RACF PASSTICKET, if RACF is to be used.	The appropriate RACF PASSTICKET.
IRM_HEADER_ENCODING	Specifies the encoding of the IRM Header properties sent to IMS Connect. Set the value to ISO-8859-1 if the message body is ASCII text. The IMS Connect SAMPL1 user exit converts the data to EBCDIC. Set the value to an EBCDIC code set, such as cp500, if the message is EBCDIC text or binary data. No data translation occurs.	ISO-8859-1 for ASCII transaction content, or an EBCDIC code, such as cp500, for EBCDIC transaction content.
SEND_DATA_ENCODING	Specifies the encoding translation (if any) to apply to the message body sent to IMS Connect. Set to NO TRANSLATION to send the message body to IMS Connect without translation, or when using the SAMPL1 user exit when the IRM Headers and message body are in ASCII. Set to an EBCDIC code, such as cp500, to translate the message body from ASCII to EBCDIC before sending to IMS Connect. If the content is a double-byte character set such as Japanese, set to the EBCDIC code page for that language (for example, cp930 for Japanese).	Enter NO TRANSLATION or the appropriate code page as follows: Enter NO TRANSLATION when using the SAMPL1 user exit and IRM Headers and message content is in ASCII. Enter an EBCDIC code, such as cp500, to translate ASCII message content to EBCDIC before sending it to IMS Connect. For double-byte character sets, enter the appropriate code page for that language (for example, cp390 for Japanese).
REPLY_DATA_ENCODING	Specifies the encoding of the message body received back from IMS Connect. Set to ISO-8859-1 if the message text is ASCII. Set to an EBCDIC code, such as cp500, if the return message is EBCDIC and/or no content translation is needed. If the content set is a double-byte character, such as Japanese, set the appropriate EBCDIC code page for that language (for example, cp930 for Japanese).	The appropriate code page. For ASCII transactions, enter ISO-8859-1. For EBCDIC transactions, enter an EBCDIC code, such as cp500. For double-byte character sets, enter the appropriate code page for that language (for example, cp390 for Japanese).

Configuring the Client ID for the IMS Adapter

The following topics describe the configuration of Client IDs for the IMS Adapter.

To configure the IMS Adapter for Parallel Processing

In this mode, the IMS Adapter is configured to handle multiple requests simultaneously (parallel mode).

Set the Client ID in the IRM_Header section to a string which contains one or more trailing asterisks. For example, “SUN*”.

The Adapter will generate the rest of the Client ID string filling it with randomly generated alphanumeric characters. The length of the Client ID is 8. If you use a static Client ID, it must be unique (across deployments) if the IMS external systems which are being used are configured to connect to the same IMS Connect.

Set the IRM_SOCT in the IRM_Header section to Persistent.

This allows the Adapter to retain the physical connection so that it can leverage the use of connection pooling as a resource adapter. If this is not set to Persistent and the Client ID is configured to use dynamic generation (that is, with an “*”), then a protocol error will occur.

No other IRM_SOCT type can be used in parallel mode; as noted a protocol error will result if Persistent is not used.

For the acknowledgement response expression (IRM_F4 - ACK/NAK Response), the following additional parameters must be set (in addition to the above):
1. Set the IRM_F2 (commit mode) to COMMIT_MODE_0.
2. Set the IRM_F3 (sync level) to SYNC_LEVEL_CONFIRM.

To Configure the IMS Adapter for Serialized Processing

In this mode, the IMS Adapter is configured to handle one single request at a time. Multiple requests are serialized by the IMS Adapter through an internal locking mechanism.

Set the Client ID in the IRM_Header section to a string which does NOT contain an asterisk. For example, “SUNIMS”.

The Adapter will generate the rest of the Client ID string filling it with randomly generated alphanumeric characters. The length of the Client ID is 8. If you use a static Client ID, it must be unique (across deployments) if the IMS external systems which are being used are configured to connect to the same IMS Connect.

For the acknowledgement response expression (IRM_F4 - ACK/NAK Response), the following additional parameters must be set (in addition to the above):
1. Set the IRM_SOCT to Transaction.
2. Set the IRM_F2 (commit mode) to COMMIT_MODE_0.
3. Set the IRM_F3 (sync level) to SYNC_LEVEL_CONFIRM.

Duplicate Client IDs

When sending an IMS Connect interaction on a given port, an error will occur when using a ClientID which is already in use on that port. This can happen when you are executing an interaction with a ClientID, which is the same as that used by another interaction that ended as a result of a socket timeout. If this new interaction is received by IMS Connect while IMS Connect is still waiting for a response from IMS for the original interaction that received the socket timeout, a duplicate ClientID error could occur.

This can also occur if the socket timeout being used for the original interaction is set to a value which is less than the timeout set by the IRM_TIMER or the IMS Connect default timeout (set in the HWSCFGxx member). IMS Connect is not aware that the original socket has been disconnected as a result of the socket timeout until it does a subsequent read on that socket. This means it would consider the original socket still active, even though that socket has already been disconnected from the client end. Once you get to this situation, you will receive DUPECLNT errors until the IRM_TIMER expires on the IMS Connect side.

Note –

For a full discussion of Client ID and timer issues, refer to IMS Connectivity in the On Demand Environment - A Practical Guide to IMS Connectivity (IBM Publication SG24-6794-00).

Serial Mode Settings

The Serial Mode Settings section of the Outbound IMS Adapter Environment contains the top-level parameters displayed in the following table.

Table 67 Outbound IMS Adapter Environment - Serial Mode Settings


Name	Description	Required Value
Wait Timeout	When IRM_CLIENTID is static, which results in requests being serialized, multiple threads using the same Client ID will contend for a request lock. Threads contending for a request lock, being held by another thread, will wait until the pending request thread releases the lock. This parameter controls how long, in milliseconds, a request thread will wait for the lock.	An integer indicating the configured length of the time a thread will wait for the lock. The default is 6000 (milliseconds).

Connection Retry Settings

The Connection Retry Settings section of the Outbound IMS Environment contains the top-level parameters displayed in the following table.

Table 68 Outbound IMS Adapter Environment - Connection Retry Settings


Name	Description	Required Value
Maximum Retries	Specifies the number of retries to establish a connection with the IMS Adapter database upon a failure to acquire one.	An integer indicating the number of attempts allowed to establish a connection. The configured default is 5.
Retry Interval [ms]	Specifies the configured length of the pause before each reattempt to access the destination file. This property is used in conjunction with the property Maximum Retries.	An integer indicating the configured length of the time (in milliseconds) before each reattempt to access the destination file. The configured default is 5000 ( 1 second).

Connection Pool Settings

The Connection Retry Settings section of the Outbound IMS Adapter Environment contains the top-level parameters displayed in the following table.

Table 69 Outbound IMS Adapter Environment - Connection Pool Settings


Name	Description	Required Value
Steady Pool Size	Specifies the initial and minimum number of connections to be maintained.	A number indicating the initial and minimum number of connections to be maintained. The configured default is 2.
MaxPoolSize	The maximum number of physical connections the pool keeps available at all times. 0 (zero) indicates that there is no maximum.	A valid numeric value. The default is 10.