Since the HLLAPI driver will only let one application connect to a 3270/5250 session at a time, each application needs to disconnect from a given session before another application can use it.  Try to ensure that the applications will not need to share a session.  If you can not avoid session sharing, then try method 1, otherwise see methods 2 and 3 below.  

Method 1: Session sharing

If the two applications need to share a 3270 or 5250 session then each application should release the session when not actually using it.  This solution may be impossible if either application is a session "hog".  Each application should:

•Connect to the Required session

•Verify the Session is in a good state (this may require logging off and then back on to ensure the session is in the proper login, application, etc.)

•Do whatever is required (execute transaction).

•Put session back in stable state (again, logoff may be required)

•Disconnect from session.

Method 2: Emulator sharing

It is possible to have two or more applications communicate through DDE (or some other mechanism) to coordinate the use of the 3270/5250 session.  If an application needs a particular session and the application is not currently connected, it would ask the other application to disconnect so it could make use of the session.

Method 3: Emulator sharing through a session manager

This is a more complicated architecture, that would probably work best if all the applications involved were ESL applications or supported DDE.  It also requires an additional ESL application that would handle all of the coordination of the sessions.

Variation 1:

Each application would request 3270/5250 services from the transaction server application, which would execute the proper 3270 routines and return the results to the client application through DDE.

Variation 2:

An additional ESL application keeps track of which applications are using which sessions.  This application is an invisible DDE server that doesn't do any actual 3270 communications, but manages the connections to the host sessions with EcsConnect and EcsDisconnect.  When an application needs a specific session it sends a message to the 3270/5250 server application.  The server application then checks to see if that session is in use or not and if it is in use, it sends a message to the application that has the session to request for it to disconnect.  Once the application disconnects and notifies the server then the server would tell the original application that the session is free.

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 that the EMUTYPE environment variable is set correctly before ESL starts, ensuring the value exactly matching the section heading in the ESLCMSRV.INI (including the case). If the EMUTYPE environment variable is not set, then ensure the "DEFAULT" section in the ESLCMSRV.INI has the parameters required by the emulator package you are using.

•It is recommended that the emulator is loaded before starting the ESL application.  The ESL application can load the emulator using the "invoke" statement, then use the EcsReStart routine to re-initialize the library.

•If possible, check the configuration is working using the Esl Fields utility, that is supplied with the Development Tools. If the processing fails, use the TroubleShoot option, 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 looking at the EMUTYPE environment variable and obtaining information from the file ESLCMSRV.INI, or if the EMUTYPE environment variable is not set, the DEFAULT section of the ESLCMSRV.INI will apply.

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

•You have not correctly set the EMUTYPE in your environment variables.

•The file ESLCMSRV.INI does not exist in your ESL sub directory.

•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!].  This is case sensitive, so be sure to match the entry exactly.

•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.

•The emulator is not loaded before starting the ESL application. You may use the EcsReStart routine, to re-initialize the library, if the first attempt to connect a session fails.

It is possible to call the HLLAPI function directly from an ESL application  This would allow for writing an extension to ESL's ECS routines that would allow an ESL application to watch for a specific string anywhere on the host screen.  To make a HLLAPI call directly to the emulator, there are several considerations to take into account:

1)    The EHLLAPI DLL provided with the Windows emulator (e.g. PCSHLL32), exports the following C function:

      void far pascal hllapi(int far *function,

            char far *data_string,

            short far *length,

            short far *return_code); 

2)     The ESL function prototype with all required structure and variable declarations is:

structure PSTRING is

      string StringChar using string size 75 

end structure 

structure PINT is

      integer Int using integer size 4

end structure 

structure PSTRING PLongString 

structure PSHORT  FuncNumber DataStringLength PSPosition 

subroutine HLLAPI(structure PINT:PINT1,

                  structure PSTRING:PCHAR1,

                  structure PINT:PINT2,

                  structure PSHORT:PINT3) library "PCSHLL32" 

integer Connect                 is 1 

integer Disconnect              is 2 

integer SendKey                 is 3  

integer QueryCursorLocation     is 7

integer SetSessionParams        is 9  

integer CopyStringToField       is 33  

integer SetCursor               is 40  

integer Send                    is 90 

integer Receive                 is 91 

integer ConvertPosition         is 99 

3)   The HLLAPI functions that would need to be called are:

Query Session Status (to get the screen size of the current connected session)

•Copy Presentation Space (to copy the entire screen to a buffer)

•For Copy Presentation Space, the following "Set Session Parameters" would be currently in effect (as set by the ECS DLL):

NOATTRB

NOEAB

NOXLATE

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 variable setting "EMUTYPE=Extra!" will cause ECSCMSRV.DLL to obtain the profile data from the "[Extra!]" entry in the ESLCMSRV.INI file. If the EMUTYPE variable is not set, then the profile data will be obtained from the "[DEFAULT]" entry in the ESLCMSRV.INI file.

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 using a series of regular expressions 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 a number of recommended and tested Emulator packages (including: IBM Personal Communications, Attachmate Extra! and Microfocus Rumba) predefined, Users will have to update the pattern matching, as the Emulator 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.

When developing an Esl application that accesses an emulator session, you occasionally need to trace the EHLLAPI functions to determine exactly what is happening.

To activate the trace facility, open the ECS configuration file, "ESLCMSRV.INI" located ESL program directory using the ESL Fields utility or a standard text editor.

Locate the section [EcsLogProfile]  of the file, this contains two parameters that are used by the debug version of the library.

Save the configuration files and start your ESL application. ESL will appear to run normally, although a bit slower, since the ECS Routines will be writing trace and debug information to a log file.

The log file will start with the prefix "ECS" followed by a number and has the file extension .log.

       Q1  Can you put nulls into a field with the Writefield command?

       Q2  What is the HLLAPI function call for EcsPressKey?

       Q3  What is the HLLAPI mnemonic for the KeyCode ECS_ATTN?

       Q4  What is the HLLAPI mnemonic for the KeyCode, ECS_FIELD_MARK?

       Q5  What is the HLLAPI function call for EcsTypeString?

       Q6  Does ECS support use the HLLAPI call Copy String to Presentation Space?

       Q7  How is the OIA checked when GetXStatus is called?

       Q8  What HLLAPI functions are used in a call to EmulateAndWatch?

       Q9 Is it possible to recognize host GDDM screens from a PC and if so, is there some way ESL could be extended to do this?

       Q10  Is EcsWatch on the same thread or on a separate thread from the ESL application?  For instance, if processing is intensive will EcsWatch have a fair share of processing?