Managing connections

A connection is a set of parameters, stored in an .hco file, used by ZIETrans to connect to host applications. There are two types of connections in ZIETrans, default (also referred to as transformation) and background. Each ZIETrans application has one default connection for the host application whose screens ZIETrans will transform. Background connections are any connections in a ZIETrans application other than the default connection, and they can be used by Integration Objects or a Perform macro transaction screen-event action. ZIETrans does not transform screens from background connections. It is possible, however, to dynamically choose which connection will be treated as the default connection. For more information, see Selecting the type of connection to use when overriding parameters.

Background connections can be different connection instances to the same host as the default connection, or they can be connections to entirely different backend hosts. Background connections allow you to interact with other hosts. You can gather data, enter data, or exchange data between hosts using prerecorded macros. This data can be combined with the default connection as well. In this way, you can automate transactions on other hosts as well as transform the default connection for your users. Background connections can be pooled.

VT hosts are limited to background connections. If you use the VT connection as one of the background connections, it can be used for recording macros and running Integration Objects. For more information, see Perform macro transaction.

Creating a connection

The Create a Connection wizard enables you to create more connection configurations. To access this wizard, you can use the pop-up menu in the ZIETrans Projects view, either the ZIETrans > New > Connection or the File > New > ZIETrans Connection selection on the menu bar, or the Create a ZIETrans Connection icon on the toolbar.

The Create a Connection wizard appears and enables you to select the target project from a drop-down list, name the connection, give it a description, and see where the connection definition is saved. Click Next when you have specified these items.

The Connection Settings page appears next. The wizard requires basic connection information such as host name, port, terminal type, code page and screen size. For details about these settings see Basic.

You can also specify some advanced connection settings using this wizard. The advanced connection settings that are shown depend on your connection type. If your connection is 5250, you can configure the workstation ID. If you use a 3270E connection, you can configure the LU or pool name. There is no workstation ID or LU setting support for 5250W, 3270, or VT connections. For details about these settings see Advanced.

Connection editor

The connection editor enables you to perform custom configurations to your connections and has the following tabs: Overview, Basic, Advanced, Printing, Screen Handling, Security, Pooling, Macros, User List, and Source.

Overview

The Overview tab of the connection editor summarizes most of the connection settings you specified when you created your connection. The only item you can modify on this tab is the description of your connection.

Each of the section headings on the Overview tab is a link to the other tabs of the connection editor.

Basic

On the Basic tab are the basic settings for the connection including those initially set up with the Create a Connection wizard. The following settings can be modified.

Host name
The name of the host to which your connection connects. This is either the name or IP address of the Telnet server.

Host On-Demand version 8 included Internet Protocol version 6 (IPv6) support. WebSphere® Application Server version 6 also provides IPv6 support. ZIETrans allows you to configure an IPv6 address to take advantage of this functionality on the platforms where it is supported.

Note:
ZIETrans can only support IPv6 on Linux, Solaris and AIX®. There are limitations in the Windows ZIETrans Toolkit environment with IPv6 addresses. Therefore, you will not be able to use the host terminal feature or test on a local test server if you use this type of address.
Type
The type of host session for the connection, such as 3270, 3270E, 5250, 5250W, VT hosts (VT52, VT100, VT420_7 and VT420_8).
Notes:
  1. ZIETrans supports only 3270, 3270E, 5250, and 5250W connection types for the transformation, or default, connection.
  2. A background connection can be of any type.
  3. VT220 and VT320 are subsets of VT420. To support VT220 or VT320 hosts in ZIETrans, specify either VT420_7 (if your VT host sends 7 bit commands) or VT420_8 (if your VT host sends 8 bit commands).
Port
The port number through which the connection connects. Typically, port 23 is used for Telnet servers. If a different port number is used, you must specify it here.
Code page
The code page used for the connection. Select the code page for your backend host.
Screen size
The screen size of the host connection. The screen size defines the number of rows and columns in the host screen.
Note:
The valid values for screen size change depending on the code page and type of host session you select.
Use host simulation instead of the live connection
Select this box to specify that any connect action for this connection, such as Open host terminal, Run, or Run on server, will use host simulation trace playback instead of a live connection. If you select this box, then also select which trace file to use from the drop-down list. See Using host simulation for more information.
Note:
This option is selectable only if a host simulation trace exists in the project.

Advanced

On the Advanced tab are advanced settings for the connection, excluding those initially set up with the Create a Connection wizard. Use the Basic tab for modifying the basic settings: host, session type, port, code page, and screen size. The following advanced settings can be modified on the Advanced tab.

For 3270E connections you can specify an LU name or LU Pool name for your connection. You have four options for specifying the LU name or LU Pool name. Select one of the following options:

None (server assigned)
Click this if you want the Telnet server to assign the LU. This option can be used with pooling.
Prompt user
Click this if you want to prompt the user for the LU name. If pooling is enabled, this option should not be used.
Use a specified value
Use this to specify the LU name or LU Pool name to be used. If you plan to use connection pooling, you may specify the name of an LU Pool large enough to support the connection pool you define.
Use an HTTP session variable  Web-only 
Click this if you want to specify the contents of the HTTP session variable as the LU name or LU Pool name. If pooling is enabled, this option should not be used.

For 5250 connections you can specify a Workstation ID for your connection. You have four options for specifying the workstation ID. Select one of the following options:

None (server assigned)
Click this if you want the Telnet server to assign the workstation ID. This option can be used with pooling.
Prompt user
Click this if you want to prompt the user for the workstation ID. If pooling is enabled, this option should not be used.
Use a specified value
Click this if you want to supply a string from which the workstation ID is created. This option can be used with pooling if a wildcard workstation ID is specified.

Workstation ID parameter for 5250 connections can use wildcard characters. The workstation ID defines the name of the workstation. The first character must be A-Z, $ (dollar sign), @ (commercial at sign), or # (number sign). The remaining characters can be A-Z, 0-9, $, @, #, . (period), and _ (underscore). If you do not complete this field, a workstation ID is automatically assigned by the host. The ZIETrans Server can generate a new and non-arbitrary workstation ID for a session. Keywords and special characters in the workstation ID field can cause some or all of the following information to be substituted into the workstation ID value that is sent to the Telnet server:

When specified, the Collision Avoidance ID enables the generation of a new workstation ID if the Telnet server rejects the previous name (which can occur when the old name is already in use on the IBM® i server).

Wildcard combinations in the workstation ID field allows the ZIETrans Server to automatically generate more ID variations for achieving connection acceptance from the host. This decreases the time required for session connection, as it decreases the number of times the host must reissue a request to the client for valid workstation ID.

Wildcard characters can be specified multiple times in the workstation ID field in any combination with other alphanumeric characters. (For example: N=A=M=E, NAME==, and so on.) With each use of the wildcard, you decrease the likelihood of generating a workstation ID already claimed by another session:

For example: Given the input of NA=ME for workstation ID, the one [=] can trigger generation of 36 unique IDs that use the alphanumeric characters specified (N, A, M, E). Adding a second [=] can trigger generation of approximately 1296 unique IDs, and so on.

Use an HTTP session variable  Web-only 
Click this if you want to specify the contents of the HTTP session variable as the workstation ID. If pooling is enabled, this option should not be used. You can also use wildcard characters in the specified string. For more information, see Use a specified value.

In the Configure optional, advanced connection settings section you can add, modify, or remove any additional IBM Host On-Demand session parameters using the buttons to the right of the table of parameters. If you click Add, you can select a parameter using the drop-down list next to the Name field and then type a value into the value field. Some parameters are set on other tabs of the connection editor. If you try to set them here, a warning message is displayed. For more information, go to the Host On-Demand Knowledge Center at http://www-01.ibm.com/support/knowledgecenter/SSS9FA_13.0.0/com.ibm.hod.doc/WebSphereHOD.htm and search on session parameters.

Notes:
  1. Parameters that have their own fields on the Basic and Advanced tabs cannot be entered in this table. They must be modified in their own specific fields.
  2. Print support parameters added here will be ignored. Add your print support parameters on the Printing tab. For more information see Printing.
  3. For 3270E connections, the negotiateCResolution parameter is set to true by default. See Contention resolution using z/OS Communications Server for more information and for when you might want to change this setting to false.

Other settings on the Advanced tab allow you to specify:

For DBCS considerations about displaying and printing user-defined characters (UDCs), see Working with user-defined characters.

Printing

Use the Printing tab to specify print support settings for the connection. Print support is available only for 3270E, 5250, and 5250W default connections.

Note:
Print support is not available and the Printing tab is not displayed in projects that are optimized for mobile devices.

Select the Enable print support check box if you want print support.

Print settings for 3270E connections

For 3270E connections, the default print settings are for Adobe Portable Document Format (PDF). If you are using PDF, in the Adobe PDF File Properties section you can select the paper size, page orientation, and font you want to use for printing jobs. The list of fonts from which you can select depends on the code page setting for the connection you are using. See Language support for more information about code page.

To specify other, non-default, print settings you can use the Initialize section and the Name/Value table.

Use the Initialize button to add a starter set of print settings into the Name/Value table based on the printing scenario you select from the drop-down box. Three printing scenarios are supplied as starter sets. The scenarios and the print settings they generate are:

Using the Initialize button is optional. If values exist in the table when the button is clicked, a warning message that the current settings will be replaced is issued. You can click to continue or cancel.

You can enter your own print settings, or modify settings already in the table using the Add, Edit, and Remove buttons. Clicking the Add button will present a combo box listing all of the supported settings from the list of WebSphere Host On-Demand printer settings.

For example to have more control over 3270E PDF print output you can add the following settings:

charsPerInch
Characters per inch. Specifies the number of characters printed per inch. On a Windows platform, three choices (10, 12, and 17) are available. The default value is 10.
linesPerInch
Lines per inch. Specifies the number of lines per inch. On a Windows platform, five choices (2, 3, 4, 6, and 8) are available. The default value is 6.
maxCharsPerLine
Maximum characters per line. Specifies the maximum number of characters per line, also called the Maximum Print Position or the Maximum Presentation Position (MPP). Enter a value from 1 to 255. The default value is 80.
maxLinesPerPage
Maximum lines per page. Specifies the maximum number of lines per page, including the top and bottom margins. This value is also called Maximum Page Length (MPL). Enter a value from 1 to 255. The default value is 66.
RTLfile
Printing right-to-left files. Specify "true" to print a file as it appears on a RTL screen. The default is "false."
Notes:
  1. Printing to a default Windows printer attached to the WebSphere Application Server is supported only by ZIETrans Web applications.
  2. ZIETrans 3270E printing does not support the Transparency command for sending unprocessed print data in the print job.
  3. For more information about Japanese JIS2004 support, see JIS2004 support for PDT printing and Print-to-File for 3270E sessions.

See Defining print support for your project for more information.

Print settings for 5250 and 5250W connections

For 5250 and 5250W connections, if you select the Enable print support check box, you must specify the Web address of the System i® Access for Web Printer Output window. The default Web address is http://hostname/webaccess/iWASpool, where hostname is the name of the 5250 or 5250W host. The user of your application can set print options in the IWA Printer Output window. See Defining print support for your project for more information.

Screen Handling

The Screen Handling tab allows you to determine how a blank screen is handled at connection startup and how screen settling is handled. These settings only apply if your connection is used as the default connection.

When the connect application event processes the obtain default connection action, ZIETrans attempts to open a connection to the host. If this connection attempt is not completed successfully, the application will end with an error page. If the connection attempt does complete successfully, the host screen is allowed to settle according to the screen timers specified on this page. These timers are also used to settle the host screen at the completion of a custom screen recognition event, the blank screen application event (if configured), and the unmatched screen event. For a detailed description of screen-settling algorithms and settings, refer to Appendix B. ZIETrans screen-settling reference.

The If blank screen is received at connection startup settings allow you to select what to do if the host screen remains blank after successfully connecting to the host, and allowing the host time to settle the screen as explained above. Your options are:

Wait until connect timeout before termination with an error
This option causes ZIETrans to terminate the application with an error page if the host screen remains blank after successfully connecting to the host.
Show blank screen
This option causes ZIETrans to proceed with screen recognition processing even if the host screen remains blank after successfully connecting to the host.

If you wish to ensure that a blank screen is not shown to your users, you may specify a screen recognition event in the Event Priority list for processing a blank screen, or you may add actions to the Blank screen Application Event to handle a blank screen. By default, the Unmatched screen application event will present the user with the blank host screen. For more information about screen recognition events, refer to Screen event priority. For more information about application events, refer to Application events.

Send the host key
This option will send a host function key to the host if the connection remains blank after successfully connecting to the host. This key will be sent once, the screen will be allowed to settle, and then ZIETrans will proceed with screen recognition processing. You can select which key to send from the drop-down list. This option is useful if your host always draws a blank initial screen, and users must submit a particular function key (SysReq, for example) before the host will present a new screen.

Screen timers allow you to configure the length of time to wait for the host to complete sending its screens to the ZIETrans runtime. To understand when these timers are used, refer to Appendix B. ZIETrans screen-settling reference. You can specify the following settings:

Minimum time to wait for initial host screen:
The default is 2000 milliseconds. This is the minimum amount of time that the application waits for the arrival of initial screen updates after the host connection becomes ready. Increase this amount if the host is slow to send the first screen, even if the connection has been in the ready state for some time.
Maximum time to wait for the screen to settle:
The default is 1200 milliseconds. This is the maximum amount that the application waits for the arrival of screen updates after the initial screen update. Increase this value if the host is slow to send the contents and you receive frequent partial screens.
Maximum time to wait for screen to settle (session using asynchronous update):
This value is only used if your application is using the asynchronous update applet (for Web applications). For more information see Using the server push (applet) method.

The initial default value is 400 milliseconds. You should increase this amount if the host is slow to send the screen and you receive frequent partial screens. This value can also be lower than the Maximum time to wait for the screen to settle if the browser specific settings in the com.ibm.common.AppletSettings class in the application.hap file are set to refresh.

Security

The Security tab contains configuration settings for Secure Socket Layer (SSL) and Web Express Logon (WEL). For more information about security settings, see Security and Web Express Logon.

Note:
To enable SSL for a connection in a ZIETrans EJB project, in the ZIETrans EJB Project view open the EJB project and the Connections folder and double-click on the connection. Then follow the directions below. For information about how to create a ZIETrans EJB project see the section, Creating and using a ZIETrans EJB application, in the ZIETrans Web Application Programmer's Guide.

Enable SSL
Select this check box to enable SSL.
Note:
If the Telnet server uses a valid well-known personal certificate, then selecting this box is all that is required.
Import PKCS12 keystore into project
Select this option to import a PKCS12 keystore file into your project. Click the Import button to browse for and import the keystore file into the project. A pointer to the imported keystore file is set in the configuration for this connection. Click the Remove button to remove the pointer to the keystore file from the connection configuration. The keystore file, itself, is not removed from the project. After importing the file, the file name appears in the Path to keystore file edit box. For more information about when this is necessary and how to create a PKCS12 keystore file see Enabling SSL security.
Note:
After importing a keystore file and saving the changes in the connection editor, refresh your project to ensure the keystore file is included in the project. To refresh your project, from the ZIETrans Projects view right-click the project and select Refresh. To set your project to automatically refresh, from the Rational® SDP menu bar select Window > Preferences > General > Workspace > Refresh automatically.
Use PKCS12 keystore at a specific path
Select this option to specify a keystore file that will not be contained within your project but will exist elsewhere on the target runtime system. In the Path to keystore file edit box, specify the complete path and file name for the keystore file on the target system. For more information about when this is necessary and how to create a PKCS12 keystore file see Enabling SSL security.
Notes:
  1. To use this file during testing on your development system, it must reside at the same location on your development system as it does on the target runtime system.
  2. For ZIETrans Web applications, if you use a keystore file that is not contained within your project .ear file, and Java™ 2 security is enabled at the target WebSphere Application Server system, you must update the was.policy file on WebSphere Application Server before your ZIETrans application tries to access it. The was.policy file is located in the Navigator view of the project .ear file in the META-INF directory. For example, to give read permissions for the keystore file, add the following statement to your was.policy file.
    permission java.io.FilePermission "c:\\myKeystores\\-", "read";
    Where myKeystores is the name of the folder containing the keystore file on the target WebSphere Application Server system. For more information see Java 2 security.
Path to keystore file
If you have imported a keystore file, this edit box contains the file name of the imported file. If you have selected the option to Use PKCS12 keystore at a specific path, then enter in this edit box the complete path and file name for the keystore file on the target runtime system.
Password
The password required to open the keystore file specified in the Path to keystore file edit box. Use the Verify button to test finding the keystore file and opening it with the password.
Notes:
  1. This is the same password that was used when the keystore file was created. For more information about how to create a PKCS12 keystore file see Enabling SSL security.
  2. To verify the location and password for a keystore file that is not contained within the project, the keystore file must reside at the same location on your development system as it does on target runtime system.
  3. The password is not stored in the clear. However, if after deploying your ZIETrans application, you want to change the password without having to redeploy the application, you can modify the password field in the .hco file that represents the connection on the runtime system. After editing the .hco file and making the modification, the password is stored in the clear until you redeploy the application.

Enable JSSE
Select this check box to enable JSSE.
Use JSSE
Selecting the ‘Use JSSE' check-box enables the use of TLS v1.0, TLS v1.1, or TLS v1.2 using the Java Secure Socket Extension (JSSE) security library, instead of SSLite, for the connection between the ZIETrans and the HOST system. The default option of using the SSLite library, can be overridden by selecting this radio button to use TLS v1.1 or TLS v1.2 for a connection.
Import Java keystore into project
Select this option to import a jks keystore file into your project. Click the Import button to browse for and import the keystore file into the project. A pointer to the imported keystore file is set in the configuration for this connection. Click the Remove button to remove the pointer to the keystore file from the connection configuration. The keystore file, itself, is not removed from the project. After importing the file, the file name appears in the Path to keystore file edit box.
Use jks keystore at a specific path
Select this option to specify a keystore file that will not be contained within your project but will exist elsewhere on the target runtime system. In the Path to keystore file edit box, specify the complete path and file name for the keystore file on the target system.
Path to keystore file
If you have imported a keystore file, this edit box contains the file name of the imported file. If you have selected the option to Use jks keystore at a specific path, then enter the complete path and file name for the keystore file on the target runtime system, in this edit box .
Password
The password required to open the keystore file specified in the Path to keystore file edit box. Use the Verify button to test if the keystore file can be found and opened using the password.
Add MSIE browser's keyring
This check-box can be used only when JSSE is enabled.

Enable this checkbox to support MSCAPI/Microsoft Cryptography API for ZIETrans. When this option is selected, the ZIETrans client accepts certificate authorities trusted by the Microsoft Internet Explorer browser.

When this option is enabled, the ‘SSLBrowserKeyringAdded' parameter will be set to true in the ‘Advanced' tab of connection file.

MSCAPI can be used only for ZIETrans toolkit..

Notes:
  1. MSCAPI is not supported for SSL.
  2. As MSCAPI is supported only for toolkit, users must add the jks file for ZIETrans web based application. Otherwise, when deployed in runtime, the connection to host fails while validating the certificate.

Use Web Express Logon  Web-only 
For ZIETrans Web applications, select this box and click the Configure button to enable and configure WEL. For more information see Using Web Express Logon (WEL).

Pooling

A pool is a group of host connections that are maintained in an initialized state, ready to be used without having to create and initialize them. This reduces the response time when starting and running an application.

You can enable pooling by clicking the Pooling tab and selecting the Enable pooling check box. If pooling is enabled, after the connection is released and determined to be in an acceptable state as defined by the checkin screen definition, it is kept in a list of active connections. When a new request for a connection is received, one of these idle pooled connections is used. If there are no idle pooled connections, a new one may be created based on other pool settings such as maximum connections. If connection pooling is disabled, after a connection has been released, it will be disconnected.

Because there is no guarantee that a user navigating screens on the default connection will navigate back to the checkin screen, it is recommended that you do not use pooling on the ZIETrans default connection. Pooling is efficient and effective for background connections used by Integration Objects or used in perform macro transaction actions, since these automated navigations can be programmed to navigate back to the checkin screen.

You also have the option of setting your Connection Timeouts and Connection Limits.

Macros

The Macros tab shows information about the Connect macro, the Disconnect macro, and the checkin screen. Both macros are optional. This information is on a separate tab from the pooling information because these macros can still be applied even if pooling is disabled.

Select the connect and disconnect macros from the Connect macro and Disconnect macro drop-down lists.

A Connect macro is run automatically when the connection is initially created. The only prompts allowed in a connect macro are those that can be satisfied by a user list or by using Web Express Logon. If pooling is enabled, the connect macro will be run when the ZIETrans server initializes, otherwise the connect macro will be run when a user makes the first request to the ZIETrans application (typically in the Connect event).

Note:
If you need to have an automatic sign-on macro run using the user's credentials, you can add a play macro action to the connect event instead of using a connect macro here. Macros run using the play macro action can satisfy prompts interactively or with global variables initialized during the start event, for example.

A Disconnect macro is run automatically when the connection is destroyed. No prompts are allowed in a disconnect macro. If pooling is enabled, the disconnect macro will be run when the ZIETrans server is shut down, otherwise the disconnect macro will be run when the ZIETrans application releases the connection back to the system (typically in the Disconnect event).

A Checkin screen describes the screen a connection must be on to be placed into the pool. It is only enabled if pooling is enabled. Typically, the checkin screen is the same as the exit screen of the connect macro, and this also matches the entry screen of the disconnect macro.

The checkin screen section will be available only if you have enabled pooling on the Pooling tab. If you have enabled pooling, the checkin screen section has three options:

You can also specify recognition criteria for the checkin screen. For instructions on how to define screen recognition criteria, see Screen Recognition Criteria or Begin Screen.

Note:
A poorly-defined checkin screen will render your pool useless. Adding definitive recognition criteria is highly recommended.

For more information about macros, see Macros and host terminal. If you use a connect macro, you can set up a user list to specify the list of users who can use the connection.

User List

The user list is a list of user profiles that each include a user ID and password. The user list can be used by a connect macro associated with the host connection. When the connect macro runs, a user ID and password is pulled from the list and placed into the user ID and password fields in the host screen. This allows a predefined list of user IDs and passwords to be used, and the user does not have to know or enter a user ID and password on the host screen.

User lists are useful for cases where many end users may concurrently access a ZIETrans Web application, EJB, or Web service that requires an automated login using a centralized list of generic user IDs.

Be sure to properly set the option, Only allow single connection with each user ID, on the Advanced tab of the Connection editor to reflect the type of host system associated with the user list. If this option is not selected, the system will reuse one user profile for all connections to the host.

The User List tab displays a table of user profiles with the capability to add, edit, or remove any one of them.

If you click Add , you are prompted to provide the user ID, a description, and password. All of these fields are required and any of these fields can be modified by clicking Edit. You can also delete the entry by selecting it and clicking Remove.

Select Encrypt user list properties to store the passwords for all of the user list entries in encrypted form. The passwords are displayed as encrypted when the Source tab is selected. Clear this box to store all of the passwords in unencrypted form. The passwords always display as asterisks (*), and the User ID and Description fields remain unencrypted, regardless of this setting.

To specify the use of profiles from the user list, as you record a connect macro, when you reach the user ID field, click the Add Prompt Action icon on the host terminal toolbar. On the Add Prompt Action page, select Set prompt to property from User List. For User Profile, select a profile from the dropdown, and for User List property, select _userid. For the password field, use the same process, select the same profile, and for User List property, select _password. The profile you select while recording the macro is the one used as you test the macro. All profiles in the list are used, as necessary, during runtime.

To associate a connect macro with a host connection, edit the connection. On the Macros tab, for Connect macro, select your macro from the dropdown.

When using user lists, you must also record a disconnect macro to log off the user ID so it can be reused. To associate a disconnect macro with a host connection, edit the connection. On the Macros tab, for Disconnect macro, select your disconnect macro from the dropdown.

Clustering and user lists

When you create multiple instances of WebSphere application servers running ZIETrans applications and sharing the same application files, you can use user lists on multiple-logon hosts without any special considerations. However, there are special considerations for the use of user lists with single-logon hosts:

Source

The Source tab displays the tags and values in the .hco file for many of the settings you selected, or for which you took the defaults, in the connection editor. As you make changes on other tabs in the connection editor, the tags and values displayed under the Source tab change to match.

You can also make changes to the tags and values in the .hco file directly by editing the source under the Source tab, and they will be reflected on the appropriate tabs of the connection editor.