| Testing Configuration - MFRMTTST | Advanced Server Configuration | |
The Requester is configured by using a file named rmtims.ini. The settings in this file are displayed when you run the MFRMTTST test program. You should run this test program 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. These message boxes occur when using the test program or when running applications making remote database calls.
The rmtims.ini file is much like other .ini files used by many other products. There are section headings surrounded by square brackets. Under each section there are keywords with values assigned. A sample rmtims.ini file was installed into the Source folder. You should use this .ini file as a guide when you create your own version.
There are two kinds of sections in the rmtims.ini file. One is the BaseConfiguration section and the other is 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 used (or active) at one time. The active Server definition is named by the ServerName setting in the BaseConfiguration section.
The BaseConfiguration section is required and has the following settings:
| Setting |
Description |
||||
|---|---|---|---|---|---|
| CommsProduct=MSSNA,GENERIC Required
|
This setting indicates which communications product Remote IMS connects to: MSSNA is the Microsoft SNA Server version 2.1 or later. GENERIC indicates another vendor's CPI-C implementation. | ||||
| ServerName=xxxxxxxxxxxxxx
Required |
This is the name of the Server section defined elsewhere in the .ini file. The Server section describes which Remote IMS Server the Requester connects to. This name can be from 1 to 14 characters and is shown in error messages by the Requester and in the "connecting" popup. This name is only used by Remote IMS and can be any name you want - it is not passed to the communications product. It may be helpful to use a name which is meaningful to your staff such as "Test-System1" or "Prod-A". | ||||
| UpdateLimit=nnnn
Optional |
This is the number of DL/I update calls an application can issue between syncpoints before the Requester issues a popup warning message. Setting this value to 9999 disables limit checking. The default value is 500. | ||||
| WhenStopTp=Never,Idle,Region
Optional |
This setting controls when the
Requester terminates the LU 6.2 TP instance used for communicating. 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. The available settings for the
corresponding CommsProduct's values are listed here:
|
||||
| CommsBufferLth=nnnn
Optional |
This setting sets the size, in bytes, of the buffer used in the Requester for communicating with the Remote IMS Server. The value can range from 100 to 32,000 bytes. See the section Optimizing Buffer Sizes for a description of packet sizes and memory utilization. The default is the maximum 32,000 bytes. | ||||
| CommsDLLname=dllname
Optional |
This is a required setting with
CommsProduct=GENERIC. It names the .dll
which contains the communication product's CPI-C support. This setting
is optional with all other CommsProduct settings since the Requester
knows how to locate those specific .dlls. This name has a
maximum limit of 60 bytes in length. 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. On Windows 95 and NT you do not have
to specify the drive and folder if the .dll is in your PATH. If
the .dll is not in the PATH you must provide the specific 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. Additional examples: CommsDLLname=WINCPIC.DLL |
||||
| DebugTrace=0,1,2,3
Optional |
This setting enables debug diagnostic tracing for the Requester. 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 intnstructions. The diagnostic information is written to the IMS Option DL/I Trace output file and/or screen. |
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 settings available in this section are:
| Server Definition Section
Setting |
Description |
|---|---|
| CpicSideFile=xxxxxxxx
Required |
Is the name of the CPI-C Side File defined in the communications product. This is a required setting. There is no default value. If you connect to more than one IMS/ESA system (that is, Remote IMS Server), you should create a unique CPI-C Side File for each one. Then, create a Server definition section for each system where you specify the corresponding CPI-C Side Filename. |
| PopupWhenConnect=Yes,Every,Never
Optional |
While you are in the process of connecting to a Remote IMS Server, a popup window appears with the message: "connecting ...". This popup automatically disappears when the connection is complete. This setting enables control of this popup. The default is "Every" which indicates every time you connect the popup is displayed. A value of "Never" suppresses this popup. A value of "Yes" can be used when KeepConversation=PSB to reduce the number of popups;with this combination, you only see the popup the first time you connect to a Remote IMS Server within an Application Region. |
| ConnectTimeout=nnnn
Optional |
Indicates how long the Requester waits for a connection to a Remote IMS Server. At the end of this period a dialog box is displayed asking how to proceed. Your choices are to continue waiting for a connection or to terminate your application. The default timeout is 60 seconds. The range is 1 through 9,998 seconds. A value of 9,999 causes the Requester to wait indefinitely. See the section Suspended States - Requester in the chapter Communication Details for more information. |
| DLITimeout=nnnn
Optional |
Indicates how long the Requester waits for the Remote IMS Server to respond to a DL/I call. At the end of this 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. The default timeout is 15 seconds. The range is 1 through 9,998 seconds. A value of 9,999 causes the Requester to wait indefinitely. See the section Suspended States - Requester in the chapter Communication Details for more information. |
| SendUpdates=Yes,No
Optional |
Controls whether or not update calls are sent to the Remote IMS Server. The default is "Yes". A value of "No" causes a popup to be displayed if an update call is tried. When you clear the popup your application is terminated. |
| KeepConversation=Region,PSB
Optional |
Controls when the conversation to the Remote IMS Server is deallocated. The default is "Region" which keeps the conversation to the Server until the IMS Option Application Region is terminated. While the conversation is active, the IMS/ESA dependent region is occupied and cannot be used by anyone else. A value of "PSB" causes the conversation to be deallocated as soon as the IMS Option application completes. With "PSB", a new conversation starts the next time an application makes a call to a Remote database. |
| UseridFile=filename
Optional |
This setting enables the user ID and password to be saved in a file from the Remote IMS security popup. When stored in this file the password is encrypted to prevent unwanted disclosure. See the section Security Handling - User ID and Password for details. Also, see the section for your communications product in the chapter Configure PC Communications for suggestions and recommendations. To allow the user ID and password to be saved in a file, specify a valid filename, including path. For example, c:\temp\rmtims.usr. You should not use a folder which is shared by another user. If no value is specified for this setting, your user ID and password are not saved in a file on disk. However, they can be saved in memory. See the section Security Handling - User ID and Password. When running the MFRMTTST test program, you see the UseridFile setting with a value of "*MEMORY" if you did not specify a filename but your system supports saving the values in memory. |
The search algorithm for rmtims.ini starts at the location that is defined in the IMS project settings. If the IMS project setting location is not defined or rmtims.ini is not found at that location, the search continues to the \mfuser\config folder. If rmtims.ini is not found there, the search continues to the software \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 results in a popup window error describing the specific error. The .ini 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 left most character on the line must be the left bracket. It does not have to be in column 1.
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.
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 blanks 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 ";" or "*" is a comment line.
Blank lines can appear anywhere. Comments can appear on the same line as a setting=<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.
Remote IMS automatically prompts you for a user ID and password when connecting to a remote system which requires them. The Requester security handling is only used when you do not define a user ID and password in your communication product's configuration or when that user ID and password is not valid for the remote system. For example, most communication products enable 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 its user ID and password when starting the conversation. See the chapter Configure PC Communications for more details of each communication product's security handling and its interaction with Remote IMS.
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. If saved, the password is encrypted to avoid unwanted disclosure.
If the UseridFile setting names a valid filename then selecting the "save password" option on the popup saves the user ID and password in that file. Once saved, Remote IMS obtains the 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).
If the UseridFile setting is not specified, the popup still offers a choice to save your password in memory. If saved, Remote IMS obtains the 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, if necessary.
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 is 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 © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Testing Configuration - MFRMTTST | Advanced Server Configuration | |