$XJXVW

6$3&RQVROH,2(QJLQH

6$3$*

1HXURWWVWU

':DOOGRUI

&20,QWHUIDFH'RFXPHQWDWLRQ
SAPConsole I/O Engine


&RS\ULJKW
Copyright  1999 SAP AG. All rights reserved.
No part of this document may be reproduced or transmitted in any form or for
any purpose without the express permission of SAP AG.
The information contained herein reflects current planning and may be changed
without prior notice.

$XWKRUV ?
5HVSRQVLEOH3URGXFW0DQDJHU"
(GLWRU ?
7DUJHWJURXS ?
&RPSRQHQW ?
FRUUHVSRQGV WR VWUXFWXUH LQ
6$31HW


1DPLQJFRQYHQWLRQ

© SAP AG - English Page 2 of 13

SAPConsole I/O Engine

&RQWHQWV


 ,6DS7HUP&RQILJXUDEOH  

 ,6DS7HUP8VHV3URILOHV  
 &XUUHQW3URILOH6HW ................................................................................... 9
 ,6DS7HUP,2(QJLQH  
 ,QLW ........................................................................................................ 10
 7HUP7H[W6HW.......................................................................................... 11
 7HUP&XUVRU3RV6HW ............................................................................... 11
 7HUP&XUVRU9LV6HW ................................................................................ 12
 7HUP&OHDU ............................................................................................ 12
 7HUP8SGDWH.......................................................................................... 12
 7\SHG.H\*HW ........................................................................................ 12


© SAP AG - English Page 3 of 13

SAPConsole I/O Engine

 ,6DS7HUP&RQILJXUDEOH
An I/O Engine may offer several modes of work. It might also require the
gathering of some information from the user. To encourage the design of
flexible engines and facilitate their use by the end user, SAP has defined the
ISapTermConfigurable interface.
This interface enables the user to configure the engine in the correct way
through administrative utilities such as the ‘SAPConsole Administrator’.
The ISapTermConfigurable interface has one member function:

ShowCfgDialog

5HPDUNV:
Not only can an I/O Engine be configurable, it can also support multiple sets of
configurations. To provide such an advanced behavior engines implement the
interface ISapTermUsesProfiles. Before each call to show their
configuration dialog, engines that use profiles are notified by the SAPConsole
Administrator for which profile the call is made. For more information, please
see ISapTermUsesProfiles and the sample code provided there.


6KRZ&IJ'LDORJ

+5(68/76KRZ&IJ'LDORJ

Bring up the configuration dialog.

© SAP AG - English Page 4 of 13

SAPConsole I/O Engine

 ,6DS7HUP8VHV3URILOHV
An I/O Engine may offer several modes of work and multiple sets of
configurations. Such behavior is implemented in the SAPConsole framework
through profiles. A profile is one uniquely named set of configuration. It
defines the mode of work and supplies all information this mode requires.

SAPConsole uses profiles for its own configuration and I/O Engines can
smoothly integrate into this configuration mechanism by implementing the
ISapTermUsesProfiles interface.
It has one member function:

CurrentProfileSet

Integration is achieved by delegating the name of the profile used by a client,

SAPConsole or SAPConsole Administrator, to the server, the I/O Engine. In
both cases the profile name is delegated by calling the
CurrentProfileSet member function on the
ISapTermUsesProfiles interface of the engine.

That way such delegation is performed in the configuration phase and as part
of the initialization phase.

In SAPConsole Administrator, whenever a user defines a certain I/O Engine to

be used in a certain profile, the engine is queried whether it is configurable
(implements ISapTermConfigurable). If it is, the user gets a chance to
configure the engine’s behavior. If the user chooses to configure the engine,
then just before calling the engine to bring up its dialog, it is queried whether it
uses profiles (implements ISapTermUsesProfiles) and if it does, the
engine is notified for which profile it is being configured. That way, the engine
can display the right data if it has already been configured for that profile. It
can display its defaults otherwise. And most importantly, it can save its set of
configuration under that profile name. Where, how and what data is saved is
left completely to the engine’s discretion.

The following MFC sample code illustrates how the SAPConsole

Administrator uses and combines ISapTermUsesProfiles and
ISapTermConfigurable. The code is simplified and stripped out of
error handling, however it does show the general idea of the mechanism:

/**
* The main dialog box showed by the application
*/
Class CAdministratorDialog : public CDialog
{
...

© SAP AG - English Page 5 of 13

SAPConsole I/O Engine

ISapTermConfigurable * m_pConfigurable;
CString m_strSelectedEng;
CString m_strProfileName;
CButton m_btnConfigEngine;
...
void OnSelChangeEngine ();
void OnClickConfigEngine ();
...

};
/**
* Wherever the user changes the engine selected for
* the profile, the framework delegates the window
* notification message to this member function. The
* name of the newly selected I/O engine is loaded
* into the m_strProfileName member variable. The
* function checks if the new engine is configurable
* and updates the data members and the display
* accordingly.
*/
void CAdministratorDialog::OnSelChangeEngine ()
{
// Release previous configurable object
if(m_pConfigurable != NULL)
m_pConfigurable->Release();

// See if new engine is configurable, and get

// a pointer to it
m_pConfigurable =
GetConfigurableInterface(m_strSelectedEng);

// If the object is configurable, enable the

// button to allow the user to configure the
// engine
m_btnConfigEngine.EnableWindow(
m_pConfigurable != NULL);
}

/**
.* Triggers whenever a user clicks on the ‘Configure
.* I/O Engine’ button. The function calls the engine
.* to bring up its configuration dialog.
*/
void CAdministratorDialog::OnClickConfigEngine ()
{
// The button is enabled only when the engine
// is configurable thus on a click we are

© SAP AG - English Page 6 of 13

SAPConsole I/O Engine

// supposed to have a valid pointer to the

// ISapTermConfigurable interface of the
// selected engine.
ASSERT(m_pConfigurable != NULL);

// See if the engine supports also profiles

ISapTermUsesProfiles * pProfileUser = NULL;
m_pConfigurable->QueryInterface(
IID_ISapTermUsesProfiles,
(LPVOID*) &pProfileUser);

// If the engine supports profiles, notify it

// of the name of the profile it is configured
// for, before invoking its configuration
// dialog
if(pProfileUser != NULL)
{
// Set the current profile on the engine
pProfileUser->CurrentProfileSet(
(BSTR)m_strProfileName );

// Release the pointer to the

// ISapTermUsesProfiles interface. It is
// no longer needed, since real work is
// done by the ISapTermConfigurable
// interface, which we keep as member
pProfileUser->Release();
}

// Invoke the configuration dialog of the

// engine
m_pConfigurable->ShowCfgDialog();
}

Later, when SAPConsole is started and identifies in its profile that it needs to
use that engine, it loads it through COM. However, before initializing the
engine, SAPConsole queries to see whether the I/O Engine supports the use of
profiles (implements ISapTermUsesProfiles). If such support exists, the engine
is notified which profile to use. Only then does SAPConsole initializes it. That
way, the I/O Engine can load the data it saved under this profile name and
initialize the right working mode.

The following C++ code might illustrate the concept of how SAPConsole
delegates the profile name to its engine and only then initializes it. Again this
code is simplified and stripped out of error handling:

/**

© SAP AG - English Page 7 of 13

SAPConsole I/O Engine

* Triggers whenever a user clicks on the ‘Configure

* I/O Engine’ button. The function calls the engine
* to bring up its configuration dialog.
*/
Class CSAPconsole
{
...
ISapTermIOEngine * m_pIOEngine;
BSTR m_bstrProfileName;
...
BOOL InitEngine();
}

/**
* Loads the I/O engine into the m_pIOEngine member
* variable and initializes it. Returns TRUE on
* success, FALSE on error.
*/
BOOL CSAPconsole::InitEngine()
{
// Find and instantiate the right io engine. The
// work is done by an IOEngineLoader object
// which encapsulates both how to find the
// engine to load under the profile name, and
// how to load it.
m_pIOEngine =
IOEngineLoader().GetIOEngineForProfile(m_bs
trProfileName);

if(m_pIOEngine == NULL)
return FALSE;

// See if the engine supports profiles

ISapTermUsesProfiles * pProfileUser = NULL;
m_pIOEngine->QueryInterface(
IID_ISapTermUsesProfiles,
(LPVOID*)&pProfileUser);

// If the engine supports profiles, notify it

// of the name of the profile to use, before
// invoking its init method
if(pProfileUser != NULL)
{
// Set the current profile on the engine

pProfileUser->CurrentProfileSet(
m_bstrProfileName);

© SAP AG - English Page 8 of 13

SAPConsole I/O Engine

// Release the pointer to the

// ISapTermUsesProfiles interface.It is
// no longer needed, since real work is
// done by the ISapTermIOEngine interface
// pointer, which we keep as member
pProfileUser->Release();
}

// Initialize the engine. Note how the Init

// method is called first on the ISapTermIOEngine
// interface, right after the engine has been
// created. And how CurrentProfileSet call may
// peceed it if the engine implements the
// ISapTermUsesProfiles interface.
m_pIOEngine->Init();
}

 &XUUHQW3URILOH6HW

+5(68/7&XUUHQW3URILOH6HW%675EVWU3URILOH1DPH

Set the name of the profile to use.

© SAP AG - English Page 9 of 13

SAPConsole I/O Engine

 ,6DS7HUP,2(QJLQH
This interface encapsulates the core services expected from any I/O Engine
used by SAPConsole. All operation specified by this interface must be
completely supported by any engine implementation. It has these member
functions:

Init
TermTextSet
TermCursorPosSet
TypedKeyGet
TermCursorVisSet
TermClear
TermUpdate

An I/O Engine is required to implement the ISapTermIOEngine. This is

what makes it an engine, the ‘sine qua non’.
However, an engine may implement other interfaces as well. An I/O Engine
might be configurable. It might even support several sets of configurations.
Several other interfaces are defined to enable such advanced behaviors and to
facilitate the smooth integration of such behaviors in the overall SAPConsole
Framework. Please see ISapTermUsesProfiles and
ISapTermConfigurable for details.

 ,QLW

+5(68/7,QLW

This method will be called once, and only once. This method is guaranteed to
be the first to be called on the ISapTermIOEngine interface, and the I/O
Engine is expected to be fully operational after it returns.

Note that if the engine uses profiles the CurrentProfileSet member

function of the ISapTermUsesProfiles interface is called first.
Specifically, it is called even before the call to Init on the
ISapTermIOEngine interface. This collaboration between the interfaces
and the predefined order of function calls ensures the I/O Engine can load the
data it saved under this profile name and initialize to work in the right mode.

It is highly recommended that all engine-wide initializations such as memory

allocations and resource acquisition take place inside Init. Only then does

© SAP AG - English Page 10 of 13

SAPConsole I/O Engine

the engine have all the necessary information it needs for its initialization.
Also, only when being called toInit may it assume that its client intends to
actually use its I/O Engine, and not just query it for interface support.

 7HUP7H[W6HW

+5(68/77HUP7H[W6HW%675EVWU7H[W8,17Q6WDUW;8,17
Q6WDUW<8,17Q$WWULE0DVN

Displays a text string starting at the character cell position given by Q6WDUW;
and Q6WDUW<. The text display attributes are given by the bits of
Q$WWULE0DVN.

Parameters:

EVWU7H[W Text to be displayed.

Q6WDUW; Column in which to place the first character of the text.
Q6WDUW< Row in which to display the text.
Q$WWULE0DVN A bit mask defining the terminal oriented display attributes.

The Q$WWULE0DVNparameter can be any combination of the following:

$775B5(*8/$5 (0x0000) No bits are set. Default, regular

display.
$775B,19(56( (0x0001) First bit is set. Reverse video display.
$775B%2/' (0x0002) Second bit is set. Bold text.
$775B8/,1( (0x0004) Third bit is set. Underlined text.
$775B%/,1. (0x0008) Forth bit is set. Blinking text.

Remarks: The cell in upper left corner of the display is defined by (0,0).

 7HUP&XUVRU3RV6HW

+5(68/77HUP&XUVRU3RV6HW8,17Q/RF;8,17Q/RF<

Moves the cursor.

Parameters:

Q/RF; Column of the cursor’s desired location.

Q/RF< Row of the cursor’s desired location.

© SAP AG - English Page 11 of 13

SAPConsole I/O Engine

Remarks: The cell in upper left corner of the display is defined by (0,0).

 7HUP&XUVRU9LV6HW

+5(68/77HUP&XUVRU9LV6HW%22/E6KRZ

Shows or hides the cursor.

Parameters:

E6KRZ Defines whether to show or hide the cursor. A non-zero

value will cause cursor to be visible.

 7HUP&OHDU

+5(68/77HUP&OHDU

Clear the display of all text and non-default attributes. This is somewhat
similar to CLS command under DOS.


 7HUP8SGDWH

+5(68/77HUP8SGDWH

Flush all output. If an engine implements a caching mechanism, there are times
that the physical display differs from the logical one. It is used to override
caching and notify the engine that it should synchronize the logical and
physical view.

 7\SHG.H\*HW

+5(68/77\SHG.H\*HW:&+$5 S8QLFRGH&KDU:25' 
SZ9LUWXDO.H\&RGH':25' GZ&RQWURO.H\6WDWH:25' 
SZ5HSHDW&RXQW

© SAP AG - English Page 12 of 13

SAPConsole I/O Engine

Retrieve one key typed by the user. User typing is retrieved key at a time, in
the order in which the typing is performed.

The parameters to the function encapsulate information about the key typed.
The caller allocates them and the engine always fills all of them.

Parameters:

S8QLFRGH&KDU The Unicode value of the character typed. If no

SZ9LUWXDO.H\&RGH
GZ&RQWURO.H\6WDWH
SZ5HSHDW&RXQW
Unicode value is applicable, like in the case of
special keys, value is set to 0.
The Windows Virtual Key value of the key typed.
A bit mask defining special key state.
Number of times this key was typed. Typing is
retrieved a key at a time, thus this parameter value
will usually be set to 1.
However, if there are subsequent repetition of
exactly the same key (and state) the engine may
fill this parameter with the number of repetitions.
This might be the case when the user holds down
a key for a long time.

The GZ&RQWURO.H\6WDWH parameter can be zero or any combination of the

following:

5,*+7B$/7B35(66(' (0x0001) The right alt key is pressed.

/()7B$/7B35(66(' (0x0002) The left alt key is pressed.
5,*+7B&75/B35(66(' (0x0004) The right ctrl key is pressed.
/()7B&75/B35(66(' (0x0008) The left ctrl key is pressed.
6+,)7B35(66(' (0x0010) The shift key is pressed.

© SAP AG - English Page 13 of 13