IMS Adapter Environment Properties
The IMS Adapter configuration parameters, accessed from the NetBeans Services window, are organized
into the following sections:
IMS Adapter 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 34 Environment TCP/IP Configuration Settings
|
|
|
|
Specifies
the name of the server host. This parameter is mandatory. |
The server host
name. |
|
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. |
|
IMS Adapter 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 35 Environment IRM Header Settings
|
|
|
|
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. |
|
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*. |
|
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:
|
|
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.
|
|
Specifies
the name of the client ID (character string) to be used by IMS
Connect. IMS Adapter supports both Serial and Parallel mode.
Note - In each deployment, the
ClientID must be unique.
|
The client ID to be used by IMS Connect. |
|
Specifies
whether the MFS Message Output Descriptor (MOD) is returned as part of the
output.
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. |
|
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.
|
|
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.
|
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. |
|
Specifies Flow Control properties. Oracle recommends using the default value No_Auto_Flow.
Note - :
Contact Oracle 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. |
|
Specifies the default IMS transaction code. |
A valid transaction code. |
|
Specifies where the
transaction code is taken.
|
Select one of the two options. The configured default is
CFG. |
|
Specifies the Datastore name (IMS destination ID). This field is required. |
String-set. A Datastore
name/IMS destination ID (character string). |
|
Specifies the IMS LTERM override name. This field
can be set to a name or blank. |
The appropriate LTERM name or blank. |
|
Specifies
the RACF Group Name. The client must provide the RACF group name if
RACF is to be used. |
The appropriate RACF group name. |
|
Specifies the RACF User
ID. The client must provide the RACF user ID if RACF is used. |
A
valid RACF user ID. |
|
Specifies the RACF PASSTICKET. The client must provide the
RACF PASSTICKET, if RACF is to be used. |
The appropriate RACF PASSTICKET. |
|
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. |
|
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).
|
|
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, “Oracle*”.
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):
- Set the IRM_F2 (commit mode) to COMMIT_MODE_0.
- 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, “OracleIMS”.
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):
- Set the IRM_SOCT to Transaction.
- Set the IRM_F2 (commit mode) to COMMIT_MODE_0.
- 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).
IMS Adapter 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 36 Outbound IMS Adapter Environment - Serial Mode Settings
|
|
|
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). |
|
IMS Adapter Connection Retry Settings
The Connection Retry Settings section of the Outbound IMS Environment contains the top-level
parameters displayed in the following table.
Table 37 Outbound IMS Adapter Environment - Connection Retry Settings
|
|
|
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). |
|
IMS Adapter 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 38 Outbound IMS Adapter Environment - Connection Pool Settings
|
|
|
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. |
|