There are several things that you must do to set up a Windows workstation for 3270 or 5250 communications with ESL.

Check that the ESLCMSRV.INI file is in the base ESL directory.

•Make sure that base ESL directory is in the system PATH.

•Make sure that the HLLAPI DLL supplied with the emulator, defined by the HllapiDLLName parameter in the ESLCMSRV.INI, is in the system PATH.

•Check with the supplier of the Emulator package, whether the HLLAPI DLL supplied, supports the Enhanced 32bit Data Structures, or the older Classic 16bit Data Structures, then set the HllapiDLLType parameter to 16.

•Check that the EMUTYPE environment variable is set correctly before ESL starts, ensuring the value exactly matching the section heading in the ESLCMSRV.INI.

•Load the emulator before starting the ESL application.  The ESL application cannot load the emulator. You can have an ESL application launch the emulator, and have it change to the application that will be doing the 3270 communications.

•If possible, check the configuration is working using the ESLFields utility, that is supplied with the Development Tools. If the processing fails, use the TroubleShoot option in the Run dialog, to help trace the problem.

Error 13 (ECS_E_NOTAVAIL) means that the command you attempted to execute is not available.  This error only occurs with EcsEmulate, EcsEmulateAndWatch, and EcsSetEmulatorWindow.  Under ESL, all three of these commands require our DLL to obtain the window handle of the emulator.  This is done by obtaining information from the file ESLCMSRV.INI on the Window Title expected for the Emulator session.

You receive this error if one of the following situations occurs:

•The file ESLCMSRV.INI does not exist in a directory, which is in the PATH list.

•The value you specified for EMUTYPE does not correspond to any of the profiles specified in ESLCMSRV.INI.  The EMUTYPE variable should match one of the words specified in the square brackets.  An example for Attachmate would be set EMUTYPE=Extra! and will match the entry, [Extra!]. If the EMUTYPE is not set then the default section of the ESLCMSRV.INI will be used.

•The text in the emulators window title doesn't match any of the regular expressions listed in ESLCMSRV.INI.  These regular expressions appear in the WinTitlex= line in the ESLCMSRV.INI file.  If you are using an emulator that is not listed in the ESLCMSRV.INI file then you will have to create your own regular expressions.  Be especially careful of emulators like PC3270 which allow the user to determine what is displayed in the title bar. To aid the setting of the WinTitle parameter, use the Window Titles facility.

The system environment variable, EMUTYPE, specifies which assignment section within ESLCMSRV.INI is to take effect when 3270/5250 support initializes.  For example, the environment setting "SET EMUTYPE=Extra!" will cause ESL Communication Server library (i.e. ESLCMSRV.DLL) to obtain the profile data from the "[Extra!]" entry in the ESLCMSRV.INI file. If the environment variable, EMUTYPE, is not set, then the default section within the ESLCMSRV.INI will be used.

The name of the IBM standard HLLAPI DLL supplied with the emulator must be specified in the HllapiDLLName setting that appears in the ESLCMSRV.INI entry.  The ".DLL" extension should not be included with the name.  The default filename of the HLLAPI DLL is assumed to be PCSHLL32.  The following is an example of how this setting should appear in the initialization file:

HllapiDLLName=PCSHLL32

HllapiDLLType=32

Your Esl application must do what is called pattern matching in order to perform the EcsEmulate, EcsEmulateAndWatch, and EcsSetEmulatorWindow calls. The pattern matching is attempted on all of the applications that appear in the Windows task list. Whilst, the ESLCMSRV.INI is supplied with the 3 recommended and tested Emulator packages (IBM Personal Communications, Attachmate Extra! and NetManage Rumba) predefined, Users of Rumba and Extra! will have to update the pattern matching, as the window caption is dependant on the configuration file used to initialize the session. The following variables are used to define the regular expressions to be used for pattern matching on title bar caption strings:

NumWinTitles

WinTitle1

WinTitle2

...

WinTitle20

Up to 20 regular expressions can be defined.  NumWinTitles is assigned the value which  must be equal to the number of regular expressions that you have set up in the initialization file.  The following is an example of an entry for Attachmate Extra! with 2 window title matches:

[Extra!]

HllapiDLLName=PCSHLL32

HllapiDLLType=32

NumWinTitles=2

WinTitle1=~ - EXTRA! for Windows 95/NT *$

WinTitle2=~[^ ]* - EXTRA! for Windows 95/NT *$ 

The reason why more than one regular expression should be defined is because it is often impossible to represent all of the possible window captions using a single expression. Also, in some cases, the caption changes, depending upon whether the emulator window is minimized, maximized, or in its normal restored state. All of these possible captions must be represented in order for you to be able to consistently get direct access to the window.  When any of the defined regular expressions matches a window caption of any one of the top-level windows in the system, the window search terminates and the handle of the window containing that caption is used for subsequent window manipulation. It is essential that the regular expression does not match any other Application's window caption, other than the required Emulator window.

In situations where more than one host session might be active, it is essential that the short session ID be displayed somewhere within the window caption so that the correct emulator window for a given session can be recognized.  Most likely, the captions will be identical except for a single letter which is the short session ID.  The special match specifier '~' (tilde) is available for this purpose.

You might encounter an emulator, like Attachmate's Extra!, which doesn't display the short session ID within the window caption but does display the name of a configuration file that is used to initialize the session.  In this situation, it might be necessary to enforce a naming convention for the configuration files such that the names begin or end with a letter that is the same as the associated short session ID.  Each host session would need a unique emulator configuration file.

A regular expression is a sequence of characters used for pattern matching a target string.  Regular expressions consist of a sequence of one or more match specifiers.  Each match specifier is immediately followed by an optional repeat specifier.  A match specifier is often a single literal character that is compared with the next character in the target string.   There are special-case match specifiers, which have special meaning, unless they are immediately preceded by an escape character ('\').  Pattern matching always begins with the first character of the target string.   If no repeat specifier follows a match specifier, then the default repeat range is {1,1}.

The following pages have several examples of special match specifiers with examples and explanations of the usage for each.

The following is a list of the special case match specifiers:  

The following is a list of the regular expression repeat specifiers:  

The following are a number of regular expression examples: