Mainframe Express installs the Requester automatically when you select the IMS Option installation.
The Requester is configured with a rmtims.ini file. This file contains a variety of settings. You can create and update this .ini file using any text file editor. A sample rmtims.ini file is installed into the \mfe\mfims\source folder. You can use this as a guide when creating your own version. The rmtims.ini file must be moved to the \mfuser\config folder in order to be used by the Requester.
The rmtims.ini file is much like .ini files used by other products. There are section headings surrounded by square brackets. Under each section there are keywords with values assigned.
The settings in this file are displayed when you run the Remote IMS test utility. You should run this test after making any changes to the .ini file to confirm the settings were made correctly. Any errors in the .ini file are reported in an error message box. The Remote IMS test utility is described in the chapter Test Remote IMS Connection.
Initially, you should only modify the minimum number of settings in the rmtims.ini file. Once you have successfully completed the first test you should review the other settings.
IMS Option first looks for rmtims.ini in the location defined in the IMS project settings. If the IMS project setting location is not defined or rmtims.ini is not found in that location, the search continues to the \mfuser\config folder. If rmtims.ini is not found there, the search continues to the software \mfe\config folder that is installed under the root software folder.
At no point does the search for rmtims.ini include the mfims\source folder.
The rmtims.ini file is similar to .ini files found in many other PC products. The syntax is more flexible to improve its readability. Any syntax errors in the .ini file result in a popup window error describing the specific error. The .ini file contains sections with its related settings following the section heading.
The section heading is the name of the section enclosed by square brackets [ ]. The brackets are required. The leftmost character on the line must be the left bracket, although it does not have to be in column one.
The section-name is not case sensitive. Extra spaces can appear on either side of the bracket character for readability. All blanks between the brackets are ignored.
Comments can follow the section heading one space after the right bracket. If the same section heading appears in the .ini file more than once, the settings in all sections with the same name are combined.
There are two types of sections in the rmtims.ini file, the BaseConfiguration section and a Server definition.
The BaseConfiguration section contains general settings for the Requester. The settings in this section are used regardless of which Server section is currently active.
The Server definition section defines a connection to a Remote IMS Server. There can be more than one Server section defined but only one is active at a time. The active Server definition is named by the ServerName setting in the BaseConfiguration section.
All settings belong to the section heading preceding it. The general
format is: keyword=value.
The keyword can begin in any column. Embedded spaces within a keyword are not allowed. Keywords are not case sensitive.
There can be any number of spaces before or after the equal sign delimiter. Values follow the equal sign delimiter. They are not case sensitive. Embedded spaces within a value are not allowed.
Any line whose first non-blank character is a semi-colon (;) or an asterisk (*) is a comment line.
Blank lines can appear anywhere. Comments can appear on the same line as
a keyword=value line by leaving at least one
space after the value and then entering a semi-colon. The semi-colon and
the remaining characters on that line are comments.
The BaseConfiguration section is required and contains a heading in the format:
[BaseConfiguration]
The following list shows the settings available for use in the BaseConfiguration section.
Specifies the size of the buffer used in the Requester for communicating with the Remote IMS Server. This is an optional setting.
CommsBufferLth=buffer-size
buffer-size
|
The size of the buffer, in bytes. This value can range from 100 to 32,000. See the section Optimizing Buffer Sizes for a description of packet sizes and memory utilization. The default is the maximum 32,000 (bytes). |
Specifies the .dll that contains the communication product's CPI-C support. This setting is required if you have set CommsProduct=GENERIC.
CommsDLLName=dll-name
dll-name |
The qualified or unqualified name of the .dll
file. This name has a maximum limit of 60 bytes in length. You do not
have to specify the drive and folder if the folder containing the .dll
file is specified by your PATH environment variable. If the folder
containing the .dll file is not on the PATH, you must specify
the drive and folder. If the .dll is in a drive and folder named by an environment variable you can use the $envvar syntax. For
example, if the variable VENDOR is set to the folder containing the .dll
you can specify the name as $vendor\the-cpic.dll |
See the section Generic Communication Products in the chapter Configure PC Communications for a complete description of this .dll and how to find its name and location.
Specifies the protocol and communications product the Requester uses to connect to the Remote IMS Server. Your rmtims.ini file must include this setting.
CommsProduct=protocol
protocol
|
The protocol and communications product to use. The
possible values of protocol are:
|
This setting enables debug diagnostic tracing for the Requester.
DebugTrace=options
options
|
Diagnostic options for use by Micro Focus Technical Support. |
Should you need to report any problems, you may be asked to set this value by a technical support person to gather further information. You should not set this value without specific instructions. The diagnostic information is written to the IMS Option DL/I Trace output file and/or screen.
Specifies the name of the Server section defined elsewhere in the .ini file. Your rmtims.ini file must include this setting.
ServerName=server-name
server-name
|
The name of the Server section. This name can be from 1 to 14 characters and is shown in error messages by the Requester and in the popup window displayed when connecting. This name is only used by Remote IMS and can be any name you want. It may be helpful to use a name which is meaningful to your staff such as "Test-System1" or "Prod-A". |
Defines the number of DL/I update calls an application can issue between syncpoints before the Requester issues a popup warning message. This is an optional setting.
UpdateLimit=limit
limit |
The number of DL/I update calls an application can issue between syncpoints before the Requester issues a popup warning message. This value can range from 1 to 9999. Setting this value to 9999 disables limit checking. The default value is 500. |
This controls when the Requester terminates the LU 6.2 TP instance used for communicating. This is an optional setting.
WhenStopTp=option
option |
When the TP instance is terminated. The possible
values of option are:
|
When the TP is stopped, the LU 6.2 session may also be stopped and other resources are freed. This is not the same as terminating the conversation. See the section LU 6.2 Session vs. Conversation in the chapter Communication Details for more details of this setting. All values are not available for all communication products.
This seting is used for SNA communications only. It is ignored for TCP/IP communications.
The Server section describes which Remote IMS Server the Requester connects to. There must be a server definition section which matches the ServerName keyword in the BaseConfiguration section. There can be multiple server definition sections listed in the .ini file, however, only the one named by ServerName is active. For example, if you connect to both a production and test IMS/ESA mainframe system, you can have one server definition for each. To switch from one to the other you need to change the ServerName value in the BaseConfiguration section.
The server definition section is identified by a section heading with
the value "Server:" followed by the ServerName value. For
example, [Server:IMSESA-system]. The names used in rmtims.ini
are not case sensitive.
The following list shows the settings available for use in the Server section.
Specifies how long the Requester waits for a connection to a Remote IMS Server. This is an optional setting.
ConnectTimeout=timeout
timeout
|
The number of seconds to wait. This value can range from 1 to 9,998 seconds. A value of 9,999 causes the Requester to wait indefinitely. The default is 60 seconds. |
At the end of the specified period a dialog box is displayed asking how to proceed. Your choices are to continue waiting for a connection or to terminate your application. See the section Suspended States - Requester in the chapter Communication Details for more information.
Specifies the CPI-C Side File defined in the communications product. Your rmtims.ini file must include this setting if you are using SNA.
CpicSideFile=name
name |
The CPI-C Side File. |
The CPI-C Side File is also referred to as the CPI-C Symbolic name. If you connect to more than one IMS/ESA system, you should create a unique CPI-C Side File for each system, then, create a Server definition section for each system and specify the corresponding CPI-C Side Filename.
This setting is ignored when using TCP/IP communications.
Specifies how long the Requester waits for the Remote IMS Server to respond to a DL/I call. This is an optional setting.
ConnectTimeout=timeout
timeout
|
The number of seconds to wait. This value can range from 1 to 9,998 seconds. A value of 9,999 causes the Requester to wait indefinitely. The default is 15 seconds. |
At the end of the specified period a popup is displayed asking how to proceed. Your choices are to continue waiting for the call to complete or to terminate your application. See the section Suspended States - Requester in the chapter Communication Details for more information.
Specifies when the conversation to the Remote IMS Server is deallocated. This is an optional setting.
KeepConversation=option
option |
When the conversation is deallocated. The possible
values of option are:
|
Specifies the IMSID name in the Target Server section of Mainframe Manager configuration. Your rmtims.ini file must include this setting if you are using TCP/IP.
MFMIMSID=name
name |
The Mainframe Manager IMSID name. |
See your Mainframe Manager documentation for details on its configuration.
This setting is used for TCP/IP communications only. It is ignored for SNA communications.
Specifies the IP name or IP address of the mainframe running Mainframe Manager. This is an optional setting.
MFMNode=IP-Details
IP-Details
|
The IP name or IP address of the mainframe running Mainframe Manager. |
This direct connection method requires that MFMPort is also specified.
This setting is used for TCP/IP communications only. It is ignored for SNA communications.
Specifies the port number assigned to Mainframe Manager. This is an optional setting.
MFMPort=port-no
port-no
|
The port number assigned to Mainframe Manager. |
This requires that MFMNode is specified.
This setting is used for TCP/IP communications only. It is ignored for SNA communications.
Specifies whether the Requester prompts for User ID and Password before connecting to Mainframe Manager. This is an optional setting.
MFMSecurity=prompt
prompt |
Whether or not the Requester prompts for User ID and
Password before connecting to Mainframe Manager. The possible values of
prompt are:
|
If security is enabled in IMS/ESA or MFM, set this value to Yes.
This setting is used for TCP/IP communications only. It is ignored for SNA communications. See the section Security Handling - User ID and Password for more information.
MFMServerName specifies the Mainframe Manager name as registered in the CCITCP2 daemon. This is an optional setting.
MFMServerName=name
name |
The Mainframe Manager CCITCP2 name. |
If CCITCP2 is not available, the direct connection method using MFMNode and MFMPort must be used.
This setting is used for TCP/IP communications only. It is ignored for SNA communications.
Controls the informational popup window that indicates when the Requester is connecting to the Server. This is an optional setting.
PopupWhenConnect=option
option |
When the popup window is dsiplayed. The possible
values of option are:
|
Specifies whether or not update calls are sent to the Remote IMS Server. This is an optional setting.
SendUpdates=option
option |
Whether or not update calls are sent. The possible
values of option are:
|
specifies a file where Remote IMS Security can save User ID and Password information. This is an optional setting.
UseridFile=filename
filename
|
The name of the file to save User ID and Password to. You must specify a valid filename, including path. For example, c:\temp\rmtims.usr. You should not use a folder which is shared by another user. |
Remote IMS will use the User ID and Password stored in this file for subsequent connections. The User ID and Password prompt will not appear again unless the existing credentials fail authorization. The password is stored encrypted to prevent unwanted disclosure. See the section Security Handling - User ID and Password for more information.
If no value is specified, User ID and Password are saved in memory and not on a disk file. When saved in memory, Remote IMS will not prompt for User ID and Password again until your operating system is restarted.
The CpicSideFile setting is required for SNA communications. The sample rmtims.ini lists a CPI-C Side File name of REMOTEDB which is consistent with previous Remote IMS versions. If you define your CPI-C Side File under a different name, you will have to change the CpicSideFile setting.
When configuring the rmtims.ini file for the built-in product MSSNA, the only other required setting is CommsProduct=MSSNA.
When configuring for a generic communications product, the settings WhenStopTP=Never and CommsDLLname=dllname are required in addition to CommsProduct=GENERIC.
For TCP/IP communications, the Mainframe Manager started task must be identified to the Requester. This is done either by using the CCITCP2 registration daemon or by direct addressing. The rmtims.ini file setting MFMServerName specifies the logical Mainframe Manager name registered in CCITCP2. When CCITCP2 is not available, direct addressing must be used by specifying both the rmtims.ini file settings MFMNode and MFMPort.
Remote IMS automatically prompts you for a User ID and Password when connecting to a remote system which requires them.
When using SNA communications, the Requester security handling is only used when you do not define a User ID and Password in the communication product's configuration or when that User ID and Password is not valid for the remote system. For example, most communication products allow you to save a User ID and Password with a security type of "Program" when creating the CPI-C side file. In this case the communication product automatically sends the User ID and Password when starting the conversation. See the chapter Configure PC Communications for more details of SNA security handling and its interaction with Remote IMS.
When using TCP/IP communications, the User ID and Password are sent to Mainframe Manager for authentication in "plain text" format. The Requester can be configured to either send logon credentials during initial connection or to attempt connection without them and reconnect if an authorization failure results. This is controlled by the MFMSecurity setting in the rmtims.ini file. The default behavior is to attempt initial connection without logon credentials, which is the same as the Requester behavior when using SNA communications. If security is enabled on the mainframe, it is recommended that the rmtims.ini file setting MFMSecurity=Yes be used.
Remote IMS prompts you for the User ID and Password in a popup window. This popup window includes an option to save the values for subsequent connections. You can save them in memory or in a disk file depending on whether you have set the UseridFile setting in the rmtims.ini file. The password is saved in encrypted form to avoid unwanted disclosure.
When the UseridFile setting names a valid filename, selecting the Save Password option on the popup saves the User ID and Password in that file. Once saved, Remote IMS obtains User ID and Password from this file for any subsequent connections that need it. You are not prompted again until the User ID or Password becomes invalid (normally when your password expires or is changed).
When the UseridFile setting is not specified, the popup offers a choice to save your password in memory. If saved, Remote IMS obtains User ID and Password for any subsequent connections from memory. You are not prompted again until you shutdown your PC or the User ID or Password become invalid. In addition, if you select Close programs and log on as a new user the values in memory are discarded and the popup prompts for a new user.
A work area (buffer) is required in the Requester and the Server to send and receive the messages they exchange. The Requester's buffer size is set in the CommsBufferLth setting. The Server's buffer size is a configurable value in the source for the Server program. By default, the size of this buffer is 32,000 bytes to provide for the largest message Remote IMS supports.
The Requester and the Server exchange these values when starting the conversation. The lowest value in either one is the maximum size message that can be sent or received for that conversation. If these values are different you are wasting some memory. The system with the largest buffer size does not use the memory which exceeds the smaller size. For example, if the Server's size is 8,000 bytes and the Requester's is 32,000, there are 24,000 bytes of buffer memory in the Requester which are not used. There is no danger of overflowing or corrupting the buffer area if they are different. If the maximum is exceeded on either system, you see a popup window error from the Requester. The only disadvantage of different sizes is the wasted memory.
If the amount of memory wasted is not a concern to you, there is no need to adjust the values. But, if you want to optimize these sizes, we suggest following these steps:
These steps give a reasonable configuration without spending too much effort. Further reduction can be made to the Requester's value depending on the databases to which you are connected. However, the effort in determining this is probably not worth the gain. That is, a Server's buffer must be large enough for the worst-case database access from any Requester. However, if you know a particular Requester rmtims.ini configuration is not used for this worst-case database you could reduce its size. If you want to calculate this size, you can use the same algorithm described for the Server DL/I Packet Size for the individual Requester configurations.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.