SAP GUI Scripting API 6 - Innowerahelp.innowera.net/PR2008/2.00/SAP_Scripting_API.pdf · SAP GUI Scripting API Send comments on this topic. Introduction SAP GUI Scripting API Purpose

SAP GUI Scripting API Send comments on this topic.

Introduction

SAP GUI Scripting API

PurposeEver since the release of SAP system version 4.6C, there has been only very limited support for emulating userinteraction with a SAP system. Existing technologies, such as ITOLE or Guilib, connect to the SAP system at theprotocol level and have never been able to emulate the behavior of the compound controls introduced with 4.6C.For this reason, applications relying on emulating user input worked only on the decreasing number of transactionsusing only standard dynpro elements.Examples of affected applications are:

Automatic testing of SAP functionality

Customized front end applications replacing the SAP GUI

Tools to customize applications on the SAP GUI level -> GuiXT

E-Learning applications that guide a user through SAP transactions

IntegrationMany of the available SAP GUI controls were designed exclusively with user interaction in mind. As their businessfunctionality is closely coupled with the user interface they cannot be instantiated outside the SAP GUI in a batch-like fashion.We therefore decided not to add the business functionality of the SAP GUI controls to a low-level integrationcomponent such as Guilib. Instead the controls run within the SAP GUI, which itself exposes a new interfaceallowing the automation of tasks.

FeaturesWe developed an object model representing the SAP GUI at runtime as a hierarchy of objects. Most of these exposean interface to an element of the user interface. These interfaces can be used to perform all the actions a usercould do with the given element. In addition we offer outgoing interfaces through which an external application canreceive notifications about events occurring within the SAP GUI.Available uses for the scripting component include

Listening to the actions a user performs in the SAP GUI and record them as a script

Running a script that emulates user interaction

Logging the SAP system information, such as response time

Runtime hierarchy overview

Top level administrative objectsAll objects defined in the scripting component's object model are available at runtime as members of a hierarchicaltree with the root object being GuiApplication.

GuiApplication represents the process in which the SAP system activity takes place. Because of this there shouldalways be only one GuiApplication object within a process. The children of GuiApplication are all the connections ofclass GuiConnection to the SAP systems available for scripting.

Connections are opened manually from the SAPLogon dialog or using the openConnection andopenConnectionByConnectionString methods of GuiApplication from a script. As soon as a connection has beenestablished a first session is created as a child of the connection. Up to 5 additional sessions can be created. Again,this can be done manually using the 'Create Session' menu item or toolbar button, or from a script using theCreateSession method of GuiSession.

While GuiApplication represents the overall SAP GUI application, a GuiSession represents a specific task beingperformed. For any given session there is exactly one transaction currently executed, and most tasks performed inSAP GUI can be performed within the context of one GuiSession.These considerations determine the event model of the scripting component. A user's interactions are best recordedor logged in the context of one session, therefore the GuiSession exposes an outgoing interface that allows anapplication to listen to the user interaction.


Introduction

SAP GUI Scripting API

PurposeEver since the release of SAP system version 4.6C, there has been only very limited support for emulating userinteraction with a SAP system. Existing technologies, such as ITOLE or Guilib, connect to the SAP system at theprotocol level and have never been able to emulate the behavior of the compound controls introduced with 4.6C.For this reason, applications relying on emulating user input worked only on the decreasing number of transactionsusing only standard dynpro elements.Examples of affected applications are:

Automatic testing of SAP functionality

Customized front end applications replacing the SAP GUI

Tools to customize applications on the SAP GUI level -> GuiXT

E-Learning applications that guide a user through SAP transactions

IntegrationMany of the available SAP GUI controls were designed exclusively with user interaction in mind. As their businessfunctionality is closely coupled with the user interface they cannot be instantiated outside the SAP GUI in a batch-like fashion.We therefore decided not to add the business functionality of the SAP GUI controls to a low-level integrationcomponent such as Guilib. Instead the controls run within the SAP GUI, which itself exposes a new interfaceallowing the automation of tasks.

FeaturesWe developed an object model representing the SAP GUI at runtime as a hierarchy of objects. Most of these exposean interface to an element of the user interface. These interfaces can be used to perform all the actions a usercould do with the given element. In addition we offer outgoing interfaces through which an external application canreceive notifications about events occurring within the SAP GUI.Available uses for the scripting component include

Listening to the actions a user performs in the SAP GUI and record them as a script

Running a script that emulates user interaction

Logging the SAP system information, such as response time

Runtime hierarchy overview

Top level administrative objectsAll objects defined in the scripting component's object model are available at runtime as members of a hierarchicaltree with the root object being GuiApplication.

GuiApplication represents the process in which the SAP system activity takes place. Because of this there shouldalways be only one GuiApplication object within a process. The children of GuiApplication are all the connections ofclass GuiConnection to the SAP systems available for scripting.

Connections are opened manually from the SAPLogon dialog or using the openConnection andopenConnectionByConnectionString methods of GuiApplication from a script. As soon as a connection has beenestablished a first session is created as a child of the connection. Up to 5 additional sessions can be created. Again,this can be done manually using the 'Create Session' menu item or toolbar button, or from a script using theCreateSession method of GuiSession.

While GuiApplication represents the overall SAP GUI application, a GuiSession represents a specific task beingperformed. For any given session there is exactly one transaction currently executed, and most tasks performed inSAP GUI can be performed within the context of one GuiSession.These considerations determine the event model of the scripting component. A user's interactions are best recordedor logged in the context of one session, therefore the GuiSession exposes an outgoing interface that allows anapplication to listen to the user interaction.

On the other hand, the GuiApplication exposes an outgoing interface that raises administrative events, for examplewhen a session is created or destroyed.

Top level user interface objectsA session usually has a GuiMainWindow as its child. This window is the starting point for user interaction with asession.

The children of the GuiMainWindow are easily identified straightforward.

Please note that the availability of some of these objects depends on the design mode used. The titlebar, forexample, is available only in New Visual Design, not in classic mode, as can be seen in the following screenshot.

SAP AG. All Rights Reserved.


Project Overview

Description

SAP GUI Scripting API 6.40

The latest version of this document is available at ftp://ftp.sap.com/pub/sapgui/win/640/scripting/docs/

User Controls

Control Description

GuiApplication The GuiApplication represents the process in which all SAP GUI activitytakes place. If the scripting component is accessed by attaching to aSAPlogon process, then GuiApplication will represent SAPlogon.GuiApplication is a creatable class. However, there must be only onecomponent of this type in any process. GuiApplication extendsGuiContainer.

Classes

Class Module Description

GuiBarChart The GuiBarChart is a powerful tool to display and modify time scale diagrams.

The object is of a very technical nature. It should only be used for recordingand playback, as most of the parameters can not be determined in any otherway. GuiBarChart extends GuiShell.

GuiBox A GuiBox is a simple frame with a name. The items inside the frame are notchildren of the box. GuiBox extends GuiVComponent. The type prefix is box.The name property is the ABAP fieldname.

GuiButton GuiButton represents all push buttons that are on dynpros, the toolbar or intable controls. GuiButton extends GuiVComponent. The type prefix is btn, thename property is the fieldname taken from the SAP data dictionary There isone exception: for tabstrip buttons, it is the button id set in screen painter thatis taken from the SAP data dictionary.

GuiCalendar The calendar control can be used to select single dates or periods of time.GuiCalendar extends GuiShell.

GuiChart The GuiChart object is of a very technical nature. It should only be used forrecording and playback, as most of the parameters can not be determined inany other way.

GuiCheckBox GuiCheckBox extends GuiVComponent. The type prefix is chk, the name is thefieldname taken from the SAP data dictionary.

GuiCollection GuiCollection is similar to GuiComponentCollection, but its members are notnecessarily extensions of GuiComponent. It can be used to pass a collection asa parameter to functions of scriptable objects. An object of this class is createdby calling the CreateGuiCollection function of the GuiApplication.

GuiColorSelector GuiColorSelector displays a set of colors for selection. It extends GuiShell.

GuiComboBox The GuiComboBox looks somewhat similar to GuiCTextField, but has acompletely different implementation. While pressing the combo box button of aGuiCTextField will open a new dynpro or control in which a selection can bemade, GuiComboBox retrieves all possible choices on initialization from theserver, so the selection is done solely on the client. GuiComboBox extendsGuiVComponent. The type prefix is cmb, the name is the fieldname taken fromthe SAP data dictionary.

GuiComboBoxEntry Members of the Entries collection of a GuiComboBox are of typeGuiComBoxEntry

GuiComponent GuiComponent is the base class for most classes in the Scripting API. It wasdesigned to allow generic programming, meaning you can work with objectswithout knowing their exact type.

GuiComponentCollection The GuiComponentCollection is used for collections elements such as thechildren property of containers. Each element of the collection is an extensionof GuiComponent.

GuiConnection A GuiConnection represents the connection between SAP GUI and anapplication server. Connections can be opened from SAPlogon or fromGuiApplications openConnection and openConnectionByConnectionStringmethods. GuiConnection extends GuiContainer. The type prefix forGuiConnection is con, the name is con plus the connection number in squarebrackets.

GuiContainer This interface resembles GuiVContainer. The only difference is that it is notintended for visual objects but rather administrative objects such asconnections or sessions. Objects exposing this interface will therefore supportGuiComponent but not GuiVComponent. GuiContainer extends GuiComponent.

GuiContainerShell A GuiContainerShell is a wrapper for a set of GuiShell objects.GuiContainerShell extends GuiVContainer. The type prefix is shellcont, thename is the last part of the id, shellcont[n].

GuiContextMenu A GuiContextMenu may have other GuiContextMenu objects as children.GuiContextMenu extends GuiMenu. The type is mnu, the name is the functioncode that is sent to the system when the menu item is selected.

GuiCTextField If the cursor is set into a text field of type GuiCTextField a combo box button isdisplayed to the right of the text field. Pressing this button is equivalent topressing the F4 key. The button is not represented in the scripting objectmodel as a separate object; it is considered to be part of the text field.There are no other differences between GuiTextField and GuiCTextField.GuiCTextField extends GuiTextField. The type prefix is ctxt, the name is theFieldname taken from the SAP data dictionary.

GuiCustomControl The GuiCustomControl is a wrapper object that is used to place ActiveXcontrols onto dynpro screens. While GuiCustomControl is a dynpro elementitself, its children are of GuiContainerShell type, which is a container forcontrols. GuiCustomControl extends GuiVContainer. The type prefix is cntl, thename is the fieldname taken from the SAP data dictionary.

GuiDialogShell The GuiDialogShell is an external window that is used as a container for othershells, for example a toolbar. GuiDialogShell extends GuiVContainer. The typeprefix is shellcont, the name is the last part of the id, shellcont[n].

GuiEAIViewer2D The GuiEAIViewer2D control is used to view 2-dimensional graphic images inthe SAP system. Presently Webviewer2D supports 22 available image types.The user can carry out redlining over the loaded image. The scripting wrapperfor this control records all user actions during the redlining process andreproduces the same actions when the recorded script is replayed.

GuiEAIViewer2D extends GuiShell.

GuiEAIViewer3D

GuiFrameWindow A GuiFrameWindow is a high level visual object in the runtime hierarchy. It canbe either the main window or a modal popup window. See the GuiMainWindowand GuiModalWindow sections for examples. GuiFrameWindow itself is anabstract interface. GuiFrameWindow extends GuiVContainer. The type prefix iswnd, the name is wnd plus the window number in square brackets.

GuiGOSShell The GuiGosShell is only available in New Visual Design mode. GuiGOSShellextends GuiVContainer. The type prefix is shellcont, the name is the last partof the id, shellcont[n].

GuiGraphAdapt For the graphic adapter control only basic members from GuiShell areavailable. Recording and playback is not possible.

GuiGridView The grid view is similar to the dynpro table control, but significantly morepowerful. GuiGridView extends GuiShell.

GuiHTMLViewer The GuiHTMLViewer is used to display an HTML document inside SAP GUI.GuiHTMLViewer extends GuiShell.

GuiLabel GuiLabel extends GuiVComponent. The type prefix is lbl, the name is thefieldname taken from the SAP data dictionary.

GuiMainWindow This window represents the main window of a SAP GUI session.

GuiMainWindow extends GuiFrameWindow.

GuiMap For the map control only basic members from GuiShell are available.Recording and playback is not possible.

GuiMenu A GuiMenu may have other GuiMenu objects as children. GuiMenu extendsGuiVContainer. The type prefix is menu, the name is the text of the menuitem. If the item does not have a text, which is the case for separators, thenthe name is the last part of the id, menu[n].

GuiMenubar Only the main window has a menubar. The children of the menubar aremenus. GuiMenubar extends GuiVContainer. The type prefix and name arembar.

GuiMessageWindow

GuiModalWindow A GuiModalWindow is a dialog pop-up.

GuiModalWindow extends GuiFrameWindow.

GuiNetChart The GuiNetChart is a powerful tool to display and modify entity relationshipdiagrams. It is of a very technical nature and shoud only be used for recordingand playback, as most of the parameters can not be determined in any otherway.

GuiOfficeIntegration

GuiOkCodeField The GuiOkCodeField is placed on the upper toolbar of the main window. It is acombo box into which commands can be entered. Setting the text ofGuiOkCodeField will not execute the command until server communication isstarted, for example by emulating the Enter key (VKey 0). GuiOkCodeFieldextends GuiVComponent. The type prefix is okcd, the name is empty.

GuiPasswordField The only difference between GuiTextField and GuiPasswordField is that theText property can not be read for a password field. The returned text is alwaysempty. GuiPasswordField extends GuiTextField. The type prefix is pwd, thename is the fieldname taken from the SAP data dictionary.

GuiPicture The picture control displays a picture on a SAP GUI screen. GuiPicture extendsGuiShell.

GuiRadioButton GuiRadioButton extends GuiVComponent. The type prefix is rad, the name isthe fieldname taken from the SAP data dictionary.

GuiSapChart For the SAP chart control only basic members from GuiShell are available.Recording and playback is not possible.

GuiScrollbar The GuiScrollbar class is a utility class used for example in GuiScrollContaineror GuiTableControl.

GuiScrollContainer This container represents scrollable subscreens. A subscreen may be scrollablewithout actually having a scrollbar, because the existence of a scrollbardepends on the amount of data displayed and the size of the GuiUserArea.GuiScrollContainer extends GuiVContainer. The type prefix is ssub, the name isgenerated from the data dictionary settings.

GuiSession The GuiSession provides the context in which a user performs a certain tasksuch as working with a transaction. It is therefore the access point forapplications which record a users actions regarding a specific task or playback those actions. GuiSession extends GuiContainer. The type prefix is ses,the name is ses plus the session number in square brackets.

GuiSessionInfo GuiSessionInfo is a member of all GuiSession objects. It makes availabletechnical information about the session. Some of its properties are displayed inthe right corner of the SAP GUI status line.

GuiShell GuiShell is an abstract object whose interface is supported by all the controls.GuiShell extends GuiVContainer. The type prefix is shell, the name is is the lastpart of the id, shell[n].

GuiSimpleContainer This container represents non-scrollable subscreens. It does not have anyfunctionality apart from to the inherited interfaces. GuiSimpleContainerextends GuiVContainer. The type prefix is sub, the name is is generated fromthe data dictionary settings.

GuiSplit GuiSplit extends GuiShell.

GuiStage For the stage control only basic members from GuiShell are available.Recording and playback is not possible.

GuiStatusbar GuiStatusbar represents the message displaying part of the statusbar on thebottom of the SAP GUI window. It does not include the system and logininformation displayed in the rightmost area of the statusbar as these areavailable from the GuiSessionInfo object. GuiStatusbar extendsGuiVComponent. The type prefix is sbar.

GuiStatusPane

GuiTab The GuiTab objects are the children of a GuiTabStrip object. GuiTab extendsGuiVContainer. The type prefix is tabp, the name is the id of the tabs buttontaken from SAP data dictionary.

GuiTableColumn GuiTableColumn extends GuiComponentCollection.

GuiTableControl The table control is a standard dynpro element, in contrast to theGuiCtrlGridView, which looks similar. GuiTableControl extends GuiVContainer.The type prefix is tbl, the name is the fieldname taken from the SAP datadictionary.

GuiTableRow GuiTableRow extends GuiComponentCollection.

GuiTabStrip A tab strip is a container whose children are of type GuiTab. GuiTabStripextends GuiVContainer. The type prefix is tabs, the name is the fieldnametaken from the SAP data dictionary.

GuiTextedit The TextEdit control is a multiline edit control offering a number of possiblebenefits. With regard to scripting, the possibility of protecting text partsagainst editing by the user is especially useful.

GuiTextField GuiTextField extends GuiVComponent. The type prefix is txt, the name is thefieldname taken from the SAP data dictionary.

GuiTitlebar The titlebar is only displayed and exposed as a separate object in New VisualDesign mode. GuiTitlebar extends GuiVContainer. The type prefix and name ofGuiTitlebar are titl.

GuiToolbar Every GuiFrameWindow has a GuiToolbar. The GuiMainWindow has twotoolbars unless the second has been turned off by the ABAP application. Theupper toolbar is the system toolbar, while the second toolbar is the applicationtoolbar.

The children of a GuiToolbar are buttons. The indexes for toolbar buttons aredetermined by the virtual key values defined for the button.

GuiToolbar extends GuiVContainer. The type prefix and name are tbar.

GuiToolbarControl GuiToolbarControl extends GuiShell.

GuiTree

GuiUserArea The GuiUserArea comprises the area between the toolbar and statusbar forwindows of GuiMainWindow type and the area between the titlebar and toolbarfor modal windows, and may also be limited by docker controls. The standarddynpro elements can be found only in this area, with the exception of buttons,which are also found in the toolbars.

GuiUserArea extends GuiVContainer. The type prefix and name are usr.

GuiUtils

GuiVComponent The GuiVComponent interface is exposed by all visual objects, such aswindows, buttons or text fields. Like GuiComponent, it is an abstract interface.Any object supporting the GuiVComponent interface also exposes theGuiComponent interface. GuiVComponent extends GuiComponent.

GuiVContainer An object exposes the GuiVContainer interface if it is both visible and can havechildren. It will then also expose GuiComponent and GuiVComponent.Examples of this interface are windows and subscreens, toolbars or controlshaving children, such as the splitter control. GuiVContainer extendsGuiContainer and GuiVComponent.

Public Enumerations

Enumeration Description

GuiComponentType

GuiErrorType

GuiEventType

GuiImageType SAP GUI Image types

GuiMessageBoxOption SAP GUI Message Box Options

GuiMessageBoxResult SAP GUI Message Box Results

GuiMessageBoxType SAP GUI Message Box Types

GuiScrollbarType

GuiTableSelectionType

Remarks

SAP OSS Notes on SAP GUI Scripting

480149: Describes the ABAP and kernel patch level requirements

587202: Limitations of SAP GUI Scripting

548788: Creating trace files of SAP GUI Scripting problems to be send to SAP

527737: Composite SAP note on SAP GUI Scripting

612454: SAP GUI Scripting: Status and Lifetime

619459: SAP GUI Scripting support of SAP applications

692245 Additional server based security options for Scripting

SAP OSS Queue for SAP GUI Scripting

BC-FES-SCR

FAQ

Integration with Excel



Getting Started

Requirements

SAP SystemScripting support is available for the 3.1I, 4.0B, 4.5B, 4.6B, 4.6C, 4.6D, 6.10, and 6.20 releases and all subsequentreleases.For the releases 3.1I to 6.10 ABAP support packages and the SAP kernel patches are available to add the support,while they are already part of 6.20 and later releases. Note 480149 lists the required patch levels.

SAP GUIThe scripting interface can be installed with the SAP GUI release 6.20 and later releases.



GuiApplication Control

Description

The GuiApplication represents the process in which all SAP GUI activity takes place. If the scripting component isaccessed by attaching to a SAPlogon process, then GuiApplication will represent SAPlogon. GuiApplication is acreatable class. However, there must be only one component of this type in any process. GuiApplication extendsGuiContainer.

For a list of all members defined in this module, see GuiApplication members.

Object Model

Remarks

The type prefix and the value of the name property are 'app'.

Example

[Visual Basic] You can attach to a running instance of SAP GUI through the Running Object Table.

Rem Get the application object from the Running Object TableSet rotEntry = GetObject("SAPGUI")Set application = rotEntry.GetScriptingEngine

Rem Get the first session of the first connectionRem You may have to adjust this to access a different sessionSet connection = application.Children(0)Set session = connection.Children(0)

Rem Start a transactionsession.findById("wnd[0]/tbar[0]/okcd").text = "/nbibs"session.findById("wnd[0]").sendVKey 0

See Also

GuiApplication Members

Example

Using CreateObject



GuiApplication Control Members

Public Methods

AddHistoryEntry SAP GUI for Windows has an input history functionality, whichdisplays for text fields the entries made in the past as asuggestion. With this function, an entry can be added to thehistory database so that it will be available the next time the enduser accesses the text field with the given field name.

CreateGuiCollection Some functions accept collections as parameters. This functioncreates a collection object that is independent of the scriptinglanguage used, such as VBScript or JavaScript.

DropHistory Calling this function will delete all entries from the input history.The function returns True if the history data have been deletedsuccessfully.

FindById Search through the object's descendants for a given id. If theparameter is a fully qualified id, the function will first check ifthecontainer object's id is a prefix of the id parameter. If that isthe case, this prefix is truncated. If no descendant with the givenid can be found thefunction raises an exception unless theoptional parameter raise is set to False.

Ignore eCATT uses this function to prevent scripts from accessing thesession in which eCATT itself runs. Otherwise the the tokenhandling would cause a dead lock.

OpenConnection The parameter connectString should contain one of thedescriptions displayed in SAPlogon, for example "XYZ [PUBLIC]".If you want to create a new SAP GUI instance and place it withinyour application you may add the suffix /INPLACE.

This function will raise the exception E_ACCESSDENIED if thescripting support has been disabled by the administrator or theuser.

OpenConnectionByConnectionString The parameter connectionData is the connection string for theSAP server, for example /R/ALR/G/SPACE. See the descriptionof the openConnection method for a discussion of the sync andraise parameters.

RegisterROT Accessing the SAPGUI entry in the Running Object Table from aC++ application may fail unless the interface is registered with astrong reference. This is not required when using Visual Basic orscripting languages.The reference must be released using revokeRot before shuttingdown the Scripting component. Failing to do so will lead toundefined behaviour.Most applications do not need to use this method, and shouldntcall it.

RevokeROT This method must be called before shutting down the Scriptingcomponent if registerROT was used.

Public Properties

ActiveSession Returns the Session that the user is currently working with, which will bethe topmost window.

AllowSystemMessages System messages are displayed when an administrator invokes them onthe server to send a notification to users currently logged in. This mayhappen at any time and interfere with the recording or playback of ascript. Setting this property to FALSE will prevent system messages frombeing displayed.

ButtonbarVisible Setting this property to FALSE hides the application toolbar of the mainwindow.

Children This collection contains all direct children of the object.

ConnectionErrorText This property contains the text of a connection error message. IfopenConnection fails you can retrieve information about the cause of thefailure from this property.

Connections This property is another name for the Children property. It has been addedfor better readability as all the children of GuiApplication are connections.

ContainerType This property is TRUE, if the object is a container and therefore has thechildren property.

HistoryEnabled The local history function can be enabled or disabled using this property.Disabling it will significantly improve the performance of SAP GUI, whichmay be crucial during load tests, for example.

Id An object id is a unique textual identifier for the object. It is built in a URL-like formatting, starting at the GuiApplication object and drilling down tothe respective object.

MajorVersion Version of the SAP GUI release, for example 6.20.

MinorVersion Build number of the scripting component.

Name The name property is especially useful when working with simple scriptsthat only access dynpro fields. In that case a field can be found using itsname and type information, which is easier to read than a possibly verylong id. However, there is no guarantee that there are no two objects withthe same name and type in a given dynpro.

NewVisualDesign Returns whether New Visual Design or Classic mode are used for the userinterface.

Parent The parent of an object is one level higher in the runtime hierarchy. Anobject is always in the children collection of its parent.

Patchlevel Patchlevel of SAP GUI.

Revision Revision of the SAP GUI release. In SAP GUI for Windows this is thecompilation number.

StatusbarVisible Setting this property to FALSE hides the statusbar of the main window.

TitlebarVisible Setting this property to FALSE hides the titlebar of the main window.

ToolbarVisible Setting this property to FALSE hides the system toolbar of the mainwindow.

Type The type information of GuiComponent can be used to determine whichproperties and methods an object supports. The value of the type string isthe name of the type taken from this documentation.

TypeAsNumber While the type property is a string value, the typeAsNumber property is along value that can alternatively be used to identify an object's type . Itwas added for better performance in methods such as FindByIdEx.Possible values for this property are taken from the GuiComponentTypeenumeration.

Utils This property returns a global GuiUtils object.

Events

CreateSession This event is raised whenever a new session is created, irrespective ofwhether of the session being created manually, from ABAP or by a script.The event is only raised for a session if the scripting support has beenenabled for the corresponding backend.

DestroySession This event is raised before a session is destroyed . This can be done eitherby closing the main window manually, or by calling the closeSessionmethod of GuiConnection.

Error An error event is currently only raised, if the wrapper library required toaccess a SAP GUI ActiveX control from a script is not available. This eventis also available on the GuiSession in which the error occurred.

IgnoreSession The event is fired when a session is set to Ignored using IgnoreSessionfunction. This event is only fired when using SAP GUI Scripting whilerunning eCATT in parallel.

See Also

GuiApplication Overview



AddHistoryEntry Method

Description

SAP GUI for Windows has an input history functionality, which displays for text fields the entries made in the pastas a suggestion. With this function, an entry can be added to the history database so that it will be available thenext time the end user accesses the text field with the given field name.

Syntax

Public Function AddHistoryEntry( _

ByVal Fieldname As String, _

ByVal Value As String _) As Boolean

Parameters

Fieldname

Value

Remarks

For a given text field, the field name can be determined by positioning the cursor on the field and pressing F1. Anew window is then opened for the Performance Assistant, which has a Technical Information button. Using this willdisplay the dialog below. The field name is displayed at the bottom of the dialog as Screen field. The functionsreturns True if the entry was added successfully.

See Also




CreateGuiCollection Method

Description

Some functions accept collections as parameters. This function creates a collection object that is independent of thescripting language used, such as VBScript or JavaScript.

Syntax

Public Function CreateGuiCollection() As Object

See Also




DropHistory Method

Description

Calling this function will delete all entries from the input history. The function returns True if the history data havebeen deleted successfully.

Syntax

Public Function DropHistory() As Boolean

See Also




FindById Method

Description

Search through the object's descendants for a given id. If the parameter is a fully qualified id, the function will firstcheck if thecontainer object's id is a prefix of the id parameter. If that is the case, this prefix is truncated. If nodescendant with the given id can be found thefunction raises an exception unless the optional parameter raise is setto False.

Syntax

Public Function FindById( _

ByVal Id As String, _

Optional ByVal Raise As Variant _) As GuiComponent

Parameters

Id

Raise

Example

Unless there are several sessions or connections in use, the following calls are equivalent:Set Comp = UserArea.findById("/app/con[0]/ses[0]/wnd[0]/usr/txtHEADER-FBFOOTLINE")Set Comp = UserArea.findById("txtHEADER-FBFOOTLINE")

See Also




Ignore Method

Description

eCATT uses this function to prevent scripts from accessing the session in which eCATT itself runs. Otherwise the thetoken handling would cause a dead lock.

Syntax

Public Sub Ignore( _

ByVal WindowHandle As Integer _)

Parameters

WindowHandle

See Also




OpenConnection Method

Description

The parameter connectString should contain one of the descriptions displayed in SAPlogon, for example "XYZ[PUBLIC]". If you want to create a new SAP GUI instance and place it within your application you may add thesuffix /INPLACE.

This function will raise the exception E_ACCESSDENIED if the scripting support has been disabled by theadministrator or the user.

Syntax

Public Function OpenConnection( _

ByVal Description As String, _

Optional ByVal Sync As Variant, _

Optional ByVal Raise As Variant _) As GuiConnection

Parameters

Description

Sync

Raise

Remarks

When opening connections manually SAP GUI executes the request asynchronously, so that the SAPLogon dialogremains responsive after requesting a new connection. This behaviour is also the default for SAP GUI Scripting.

In the Scripting context it means that the call to openConnection may return before the new connection has beenopened. A side effect of this is that when opening a connection fails SAP GUI displays an error popup that can notbe handled from the script. This problem can be solved by setting the sync parameter to True. Then the call toopenConnection will not return until a connection has been established, or an error has been detected. If sync is setto True and an error occurs an exception is raised, unless the parameter raise is set to False.

Example

In the following example the scripting component has been placed on an HTML page and the connection wasopened in the pageLoad event handler using the /INPLACE switch.

See Also




OpenConnectionByConnectionString Method

Description

The parameter connectionData is the connection string for the SAP server, for example /R/ALR/G/SPACE. See thedescription of the openConnection method for a discussion of the sync and raise parameters.

Syntax

Public Function OpenConnectionByConnectionString( _

ByVal ConnectString As String, _

Optional ByVal Sync As Variant, _

Optional ByVal Raise As Variant _) As GuiConnection

Parameters

ConnectString

Sync

Raise

Remarks

Connection Strings

Connection String is a technical term used within SAP GUI. A connection string describes a connection address for adestination, e.g. an SAP system's application server, similar to an Internet URL describes a location for a web page.

Simple Connection StringsIn its simplest form, a connection string contains an IP address and a port number. This information is sufficient forSAP GUI to open a direct TCP connection to a destination, e.g. an application server. IP address and port numberare marked with the prefixes '/H/' (for host) and '/S/' (for service). Note that the port number for an SAPapplication server is by convention 3200 plus the two-digit SAP system number.

Example for a simple connection string with an application server's IP address (172.16.64.17) and port number(3200):/H/172.16.64.17/S/3200

If your network environment supports DNS (Domain Name Services), a hostname can be used instead of the IPaddress in all kinds of connection strings. (This requires a correct DNS configuration on the client, e.g. via the hostsfile).

Example with an application server's hostname (iwdf8997.wdf.sap-ag.de) and port number (3200):/H/iwdf8997.wdf.sap-ag.de/S/3200

If your network environment supports symbolic service names for well-known ports, the symbolic service name canbe used instead of the port number in all kinds of connection strings. (This requires a correct service configurationon the client, e.g. in the services file). Note that SAP application server ports are by convention named'sapdp', where is the SAP system id.

Example with host name (iwdf8997.wdf.sap-ag.de) and symbolic service name (sapdpIWD):/H/iwdf8997.wdf.sap-ag.de/S/sapdpIWD

Simple connection strings need not be resolved by the SAP GUI application. Resolution of host names and symbolicservice names is done by the operating system's network layer.

SAP Routers

In a WAN (Wide Area Network) environment, SAP routers are used to make connections to remote SAP systemsthat cannot be reached with a direct TCP connection. Passwords may be used for each SAP router to control access.

In order to make a connection, the client is responsible for providing the complete route to the destination, possiblyincluding a chain of several SAP routers. Path information is not provided by the routers. (Strictly speaking, a SAProuter is actually better described as an application level proxy with password capabilities and strict source routing).

The address for each router is specified by a simple connection string (with the router's host name and portnumber), optionally followed by '/P/' and the router password. The path from the current location to the destinationis described by concatenating all router addresses, followed by the address of the destination SAP system. Thus, aconnection string with SAP routers generally has the form ....

Example with two routers (gate.acme.com, port 3299, and gate.sap.com, port 3298), the first using a password(secret), for a connection to the application server iwdf8997.sap.com, port 3200):/H/gate.acme.com/S/3299/P/secret/H/gate.sap.com/S/3298/H/iwdf8997.sap.com/S/3200

Connection strings including SAP routers are passed to SAP GUI's communication layer and resolved step by step bythe routers on the path. If host names and symbolic service names are used, each router must have access tocorrect network configuration information to resolve them.

Message Servers and Logon Groups

For load balancing purposes, application servers from one SAP system are usually configured in logon groups,where each group serves a particular kind of user. The application servers in each group are assigned to users by aleast-heavily-loaded strategy. This load balancing is done by message servers. Each SAP system has exactly onemessage server, which can be reached via TCP on a specific message server port.

Care should be taken that the application server's port number is not confused with the message server's portnumber. Although the message server's host name may in small installations often be identical to the hostname ofan application server, the port number is always different. Symbolic service names for message servers byconvention have the form 'sapms', where is the SAP system id.

Message server and group information can be used to address a SAP system in a connection string. The address ofthe message server is specified as a combination of message server host name, message server port and groupname. This information is marked with the prefixes '/M/' (message server host name), '/S/' (message server port)and '/G/' (logon group).

Example with message server (hostname alrmain, port number 4253) and logon group (SPACE):/M/alrmain.wdf.sap-ag.de/S/4253/G/SPACE

Connection strings with message servers are resolved by SAP GUI by contacting the message server and retrievingthe (simple) connection string of an application server for the specified group. This requires network access to themessage server at the time the address is resolved.

SAP router connection strings may be used in combination with message server connection strings simply byspecifying the router address before the message server address. The router is then used for contacting themessage server as well as for contacting the resolved application server.

Symbolic System Names

The most user-friendly form of connection string addresses an SAP system only by its symbolic name (perconvention, the system id) and the logon group name. These information are marked with the prefixes '/R/' (for thesymbolic SAP system name) and '/G/' (for the logon group name).

Example with SAP system (ALR) and logon group (SPACE):/R/ALR/G/SPACE

Connection strings with symbolic system names are resolved by SAP GUI by looking up the symbolic SAP systemname in the Message Server List (a text file containing a mapping between symbolic system names and messageserver addresses) and replacing the /R/ part of the connection string with the resulting message server address.The result is a complete message server connection string which is then further resolved as explained above.

Formal syntax

For the technically interested reader, the following BNF grammar formally describes the syntax of connectionstrings: := [] := || := "/H/""/S/" := | := (any DNS hostname) := (any IP address, in dotted decimal form) := | := (any IP service name) := (any decimal number) := "/M/""/S/""/G/" := (any ASCII string not containing '/') := "/R/""/G/" := (any ASCII string not containing '/') := * := "/H/""/S/"["/P/"] := (any ASCII string not containing '/')

See Also




RegisterROT Method

Description

Accessing the SAPGUI entry in the Running Object Table from a C++ application may fail unless the interface isregistered with a strong reference. This is not required when using Visual Basic or scripting languages.The reference must be released using revokeRot before shutting down the Scripting component. Failing to do so willlead to undefined behaviour.Most applications do not need to use this method, and shouldnt call it.

Syntax

Public Function RegisterROT() As Boolean

See Also




RevokeROT Method

Description

This method must be called before shutting down the Scripting component if registerROT was used.

Syntax

Public Sub RevokeROT()

See Also




ActiveSession Property

Description

Returns the Session that the user is currently working with, which will be the topmost window.

Property type

Read-only property

Syntax (Visual Basic)

Public Property ActiveSession() As Object

See Also




AllowSystemMessages Property

Description

System messages are displayed when an administrator invokes them on the server to send a notification to userscurrently logged in. This may happen at any time and interfere with the recording or playback of a script. Settingthis property to FALSE will prevent system messages from being displayed.

Property type

Read-write property


Public Property AllowSystemMessages() As Boolean

See Also




ButtonbarVisible Property

Description

Setting this property to FALSE hides the application toolbar of the main window.

Property type

Read-write property


Public Property ButtonbarVisible() As Boolean

Remarks

Hiding the application toolbar may be useful if SAP GUI is displayed inplace, for example in a web page. Theproperty should not be used when displaying SAP GUI as a standalone application.

See Also




Children Property

Description

This collection contains all direct children of the object.

Property type

Read-only property


Public Property Children() As GuiComponentCollection

See Also




ConnectionErrorText Property

Description

This property contains the text of a connection error message. If openConnection fails you can retrieve informationabout the cause of the failure from this property.

Property type

Read-only property


Public Property ConnectionErrorText() As String

See Also




Connections Property

Description

This property is another name for the Children property. It has been added for better readability as all the childrenof GuiApplication are connections.

Property type

Read-only property


Public Property Connections() As GuiComponentCollection

See Also




ContainerType Property

Description

This property is TRUE, if the object is a container and therefore has the children property.

Property type

Read-only property


Public Property ContainerType() As Boolean

See Also




HistoryEnabled Property

Description

The local history function can be enabled or disabled using this property. Disabling it will significantly improve theperformance of SAP GUI, which may be crucial during load tests, for example.

Property type

Read-write property


Public Property HistoryEnabled() As Boolean

See Also




Id Property

Description

An object id is a unique textual identifier for the object. It is built in a URL-like formatting, starting at theGuiApplication object and drilling down to the respective object.

Property type

Read-only property


Public Property Id() As String

Remarks

Using fully qualified ids has one significant drawback: the index of both the connection and session become part ofthe id. If the id given above is used to search for the text field the search will only be successful if the session towhich the text field belongs is again the first session of the first connection. This problem can be circumventedusing relative ids. A relative id does not start with /. Instead it begins with the type prefix of the child of the objecton which the search is started. Therefore it is usually preferable to truncate the first part of the id up to the sessionindex and work with a relative id, such as wnd[0]/usr/ctxtRS38M-PROGRAMM. This relative id is still unique withrespect to a given session, but it is independent of the number of sessions or connections currently open.

Example

The id of the text field in transaction se38 is /app/con[0]/ses[0]/wnd[0]/usr/ctxtRS38M-PROGRAMM. It is createdthrough first taking the type specific prefix for the given component, which in this case is 'ctxt'. The name of thefield is then appended, if one exists. For dynpro fields the name is the field name defined in screen painter, in thiscase 'RS38M-PROGRAM'. In many cases, especially if there is no name available for an object, an index has to beappended for uniqueness. Finally, the id of the parent object is added as a prefix, separated by the '/' character.

Objects of type GuiShell do not have a name. So whenever there are several objects of this type on the same levelin the hierarchy, a one-dimensional index is appended for uniqueness. On the other hand, list and step-loop screensare set up in a two-dimensional grid, so the index string added to the id will have two components as well.

See Also




MajorVersion Property

Description

Version of the SAP GUI release, for example 6.20.

Property type

Read-only property


Public Property MajorVersion() As Long

See Also




MinorVersion Property

Description

Build number of the scripting component.

Property type

Read-only property


Public Property MinorVersion() As Long

See Also




Name Property

Description

The name property is especially useful when working with simple scripts that only access dynpro fields. In that casea field can be found using its name and type information, which is easier to read than a possibly very long id.However, there is no guarantee that there are no two objects with the same name and type in a given dynpro.

Property type

Read-only property


Public Property Name() As String

See Also




NewVisualDesign Property

Description

Returns whether New Visual Design or Classic mode are used for the user interface.

Property type

Read-only property


Public Property NewVisualDesign() As Boolean

Example

False: Classic mode

True: New Visual Design

See Also




Parent Property

Description

The parent of an object is one level higher in the runtime hierarchy. An object is always in the children collection ofits parent.

Property type

Read-only property


Public Property Parent() As GuiComponent

See Also




Patchlevel Property

Description

Patchlevel of SAP GUI.

Property type

Read-only property


Public Property Patchlevel() As Long

See Also




Revision Property

Description

Revision of the SAP GUI release. In SAP GUI for Windows this is the compilation number.

Property type

Read-only property


Public Property Revision() As Long

See Also




StatusbarVisible Property

Description

Setting this property to FALSE hides the statusbar of the main window.

Property type

Read-write property


Public Property StatusbarVisible() As Boolean

Remarks

Hiding the statusbar may be useful if SAP GUI is displayed inplace, for example in a web page. The property shouldnot be used when displaying SAP GUI as a standalone application.

See Also




TitlebarVisible Property

Description

Setting this property to FALSE hides the titlebar of the main window.

Property type

Read-write property


Public Property TitlebarVisible() As Boolean

Remarks

The titlebar is only available when SAP GUI is displayed in New Visual Design.

Hiding the titlebar may be useful if SAP GUI is displayed inplace, for example in a web page. The property shouldnot be used when displaying SAP GUI as a standalone application.

See Also




ToolbarVisible Property

Description

Setting this property to FALSE hides the system toolbar of the main window.

Property type

Read-write property


Public Property ToolbarVisible() As Boolean

Return Type

Hiding the system toolbar may be useful if SAP GUI is displayed inplace, for example in a web page. The propertyshould not be used when displaying SAP GUI as a standalone application.

See Also




Type Property

Description

The type information of GuiComponent can be used to determine which properties and methods an object supports.The value of the type string is the name of the type taken from this documentation.

Property type

Read-only property


Public Property Type() As String

See Also




TypeAsNumber Property

Description

While the type property is a string value, the typeAsNumber property is a long value that can alternatively be usedto identify an object's type . It was added for better performance in methods such as FindByIdEx. Possible valuesfor this property are taken from the GuiComponentType enumeration.

Property type

Read-only property


Public Property TypeAsNumber() As Long

See Also




Utils Property

Description

This property returns a global GuiUtils object.

Property type

Read-only property


Public Property Utils() As GuiUtils

See Also




CreateSession Event

Description

This event is raised whenever a new session is created, irrespective of whether of the session being createdmanually, from ABAP or by a script. The event is only raised for a session if the scripting support has been enabledfor the corresponding backend.

Syntax

Public Event CreateSession( _

ByVal Session As GuiSession _)

Parameters

Session

Example

The following script attaches itself to the SAPlogon process and displays a pop-up whenever a new session iscreated.

Dim objSapGuiSet objSapGui = GetObject("SAPGUI")

Dim objScriptingEngineSet objScriptingEngine = objSapGui.GetScriptingEngineWScript.ConnectObject objScriptingEngine, "Engine_"

Dim WaitingWaiting = 1

Do While (Waiting = 1) WScript.Sleep(100)Loop Set objScriptingEngine = NothingSet objSapGui = Nothing Sub Engine_CreateSession(ByVal Session) Dim result result = MsgBox("Session created", vbOKCancel) If result = vbCancel then Waiting = 0 End IfEnd Sub

See Also




DestroySession Event

Description

This event is raised before a session is destroyed . This can be done either by closing the main window manually, orby calling the closeSession method of GuiConnection.

Syntax

Public Event DestroySession( _

ByVal Session As GuiSession _)

Parameters

Session

Example

You can handle this event from VBScript by adding the following procedure to the sample script on previous page:Sub Engine_DestroySession(ByVal Session) Dim result result = MsgBox("Session destroyed",vbOKCancel) If result = vbCancel then Waiting = 0 End IfEnd Sub

See Also




Error Event

Description

An error event is currently only raised, if the wrapper library required to access a SAP GUI ActiveX control from ascript is not available. This event is also available on the GuiSession in which the error occurred.

Syntax

Public Event Error( _

ByVal ErrorId As Long, _

ByVal Desc1 As String, _



ByVal Desc4 As String _)

Parameters

ErrorId

Desc1

Desc2

Desc3

Desc4

See Also




IgnoreSession Event

Description

The event is fired when a session is set to Ignored using IgnoreSession function. This event is only fired whenusing SAP GUI Scripting while running eCATT in parallel.

Syntax

Public Event IgnoreSession( _

ByVal SessionMainWindowHandle As Integer _)

Parameters

SessionMainWindowHandle

See Also




GuiBarChart Object

Description

The GuiBarChart is a powerful tool to display and modify time scale diagrams.

The object is of a very technical nature. It should only be used for recording and playback, as most of theparameters can not be determined in any other way. GuiBarChart extends GuiShell.

For a list of all members defined in this module, see GuiBarChart members.

Object Model

Example

See Also

GuiBarChart Members



GuiBarChart Object Members

Public Methods

BarCount Returns the number of bars in the given chart.

DumpState This function dumps the state of the object. The parameterinnerObject may be used to specify for which internal object thedata should be dumped. Only the most complex components, suchas the GuiCtrlGridView, support this parameter. All othercomponents always dump their full state. All components thatsupport this parameter have in common that they return generalinformation about the controls state if the parameter innerObjectcontains an empty string.The format of the returned collection isdescribed in the chapter DumpState Collection Format of theappendix. The available values for the innerObject parameter arespecified as part of the class description for those components thatsupport it.

FindAllByName The methods findByName and findByNameEx return only the firstobject with matching name and type. There may however beseveral matching objects, which will be returned as members of acollection when findAllByName or findAllByNameEx are used.

FindAllByNameEx The methods findByName and findByNameEx return only the firstobject with matching name and type. There may however beseveral matching objects, which will be returned as members of acollection when findAllByName or findAllByNameEx are used.

FindById Search through the object's descendants for a given id. If theparameter is a fully qualified id, the function will first check ifthecontainer object's id is a prefix of the id parameter. If that isthe case, this prefix is truncated. If no descendant with the givenid can be found thefunction raises an exception unless the optionalparameter raise is set to False.

FindByName Unlike findById, this function does not guarantee a unique result.It will simply return the first descendant matching both the nameand type parameters.This is a more natural description of theobject than the complex id, but it only makes sense on dynproobjects as most other objects do not have a meaningfulname. If nodescendant with matching name and type can be found, thefunction raises an exception.

FindByNameEx This function has been introduced for performance reasons. Theparameter type is not a string as in findByName but rather anumber taken from GuiComponent.typeAsNumber.

GetBarContent Returns the content of the bar.

GetGridLineContent Returns the content of the grid line.

GridCount Returns the number of grids within the chart.

LinkCount Returns the number of links within the given chart.

SelectContextMenuItem Select an item from the controls context menu.

SelectContextMenuItemByPosition This method allows you to select a context menu item using theposition of the item. It is therefore independent of the menu itemtext.

SelectContextMenuItemByText Select a menu item of a context menu using the text of the itemand possible higher level menus.

SendData Send data to the server.

SetFocus This function can be used to set the focus onto an object. If a userinteracts with SAP GUI, it moves the focus whenever theinteraction is with a new object. Interacting with an object throughthe scripting component does not change the focus. There aresome cases in which the SAP application explicitly checks for thefocus and behaves differently depending on the focussed object.

ShowContextMenu Shows the context menu of the control.

Visualize Calling this method of a component will display a red frame aroundthe specified component if the parameter on is true. The frame willbe removed if on is false. Some components such asGuiCtrlGridView support displaying the frame around inner objects,such as cells. The format of the innerObject string is the same asfor the dumpState method.

Public Properties

AccDescription Accessibility description of the shell. This description can be used for shellsthat do not have a title element.

AccLabelCollection The collection contains objects of type GuiLabel that were assigned to thiscontrol in the ABAP Screen Painter.

AccText An additional text for accessibility support.

AccTextOnRequest An additional text for accessibility support.

AccTooltip An additional tooltip text for accessibility support.

Changeable An object is changeable if it is neither disabled nor read-only.

ChartCount Number of charts.

Children This collection contains all direct children of the object.

ContainerType This property is TRUE, if the object is a container and therefore has thechildren property.

CurrentContextMenu This property is only set when a context menu is available at the shellobject.

DefaultTooltip Tooltip text generated from the short text defined in the data dictionary forthe given screen element type.

DragDropSupported This property is True if the shell allows drag and drop operations.

Handle The window handle of the control that is connected to the GuiShell.

Height Height of the component in pixels.

IconName If the object has been assigned an icon, then this property is the name ofthe icon, otherwise it is an empty string.

Id An object id is a unique textual identifier for the object. It is built in a URL-like formatting, starting at the GuiApplication object and drilling down tothe respective object.

IsSymbolFont The property is TRUE if the component's text is visualized in the SAPsymbol font.

Left Left position of the element in screen coordinates

Modified An object is modified if its state has been changed by the user and thischange has not yet been sent to the SAP system.

Name The name property is especially useful when working with simple scriptsthat only access dynpro fields. In that case a field can be found using itsname and type information, which is easier to read than a possibly verylong id. However, there is no guarantee that there are no two objects withthe same name and type in a given dynpro.

OcxEvents Returns a collection containing the event ids of the ActiveX control. Theseare the events that the control may send to the server.

Parent The parent of an object is one level higher in the runtime hierarchy. Anobject is always in the children collection of its parent.

ParentFrame If the control is hosted by the Frame object, the value of the property isthis frame. Overwise NULL.

ScreenLeft The y position of the component in screen coordinates.

ScreenTop The x position of the component in screen coordinates.

SubType Additional type information to identify the control represented by the shell,for example Picture, TextEdit, GridView This property has the constantvalue sapbarc.

Text The value of this property very much depends on the type of the object onwhich it is called. This is obvious for text fields or menu items. On theother hand this property is empty for toolbar buttons and is the class id forshells. You can read the text property of a label, but you cant change it,whereas you can only set the text property of a password field, but notread it.

Tooltip The tooltip contains a text which is designed to help a user understand themeaning of a given text field or button.

Top Top coordinate of the element in screen coordinates.

Type The type information of GuiComponent can be used to determine whichproperties and methods an object supports. The value of the type string isthe name of the type taken from this documentation.

TypeAsNumber While the type property is a string value, the typeAsNumber property is along value that can alternatively be used to identify an object's type . Itwas added for better performance in methods such as FindByIdEx.Possible values for this property are taken from the GuiComponentTypeenumeration.

Width Width of the component in pixels.

See Also

GuiBarChart Overview



BarCount Method

Description

Returns the number of bars in the given chart.

Syntax

Public Function BarCount( _

ByVal chartId As Long _) As Long

Parameters

chartIdIndex of the chart

See Also

GuiBarChart Object



DumpState Method

Description

This function dumps the state of the object. The parameter innerObject may be used to specify for which internalobject the data should be dumped. Only the most complex components, such as the GuiCtrlGridView, support thisparameter. All other components always dump their full state. All components that support this parameter have incommon that they return general information about the controls state if the parameter innerObject contains anempty string.The format of the returned collection is described in the chapter DumpState Collection Format of theappendix. The available values for the innerObject parameter are specified as part of the class description for thosecomponents that support it.

Syntax

Public Function DumpState( _

ByVal InnerObject As String _) As GuiCollection

Parameters

InnerObject

Remarks

The DumpState method returns a hierarchy of collections of type GuiCollection, which is three levels deep.

- The top (first) level collection contains a second level collection for every property that is to be dumped.

- The second level collection contains the complete information for one property. There is a third levelcollection for every sub-expression that might be required to access inner objects.

- Finally, the third level collection contains the OpCode, the property or method name, the parametervalues and depending on the OpCode the return value to be checked.

The following OpCodes are used:

- GPR: Get property and compare return value.

- MR: Execute method and compare return value.

- GP: Get property and execute the next entry in the second level collection on the result.

- M: Execute the method and then execute the next entry in the second level collection on the result.

For example the calls

control.ItemCount = 42

control.GetItemValue(3, 2) = 'MyText'

control.GetItem('2','3').Property1.MethodY('XYZ').Text = 'ABC'

result in three entries of the top level collection:

First entry:

OpCode Name Parameter1/Property-Value

Parameter2 Parameter3

GPR ItemCount 42

Second entry:

OpCode Name Parameter1 Parameter2 Parameter3/Property-Value

MR GetItemValue 3 2 MyText

Third entry:

OpCode Name Parameter1 Parameter2 Parameter3

M GetItem 2 3

GP Property1

M MethodY XYZ

GPR Text ABC

As you can see in this example, for calls that contain return values (MR, GPR) the last value in the third levelcollection is the return value.

See Also

GuiBarChart Object



FindAllByName Method

Description

The methods findByName and findByNameEx return only the first object with matching name and type. There mayhowever be several matching objects, which will be returned as members of a collection when findAllByName orfindAllByNameEx are used.

Syntax

Public Function FindAllByName( _

ByVal Name As String, _

ByVal Type As String _) As GuiComponentCollection

Parameters

Name

Type

See Also

GuiBarChart Object



FindAllByNameEx Method

Description

The methods findByName and findByNameEx return only the first object with matching name and type. There mayhowever be several matching objects, which will be returned as members of a collection when findAllByName orfindAllByNameEx are used.

Syntax

Public Function FindAllByNameEx( _


ByVal Type As Long _) As GuiComponentCollection

Parameters

Name

Type

See Also

GuiBarChart Object



FindById Method

Description

Search through the object's descendants for a given id. If the parameter is a fully qualified id, the function will firstcheck if thecontainer object's id is a prefix of the id parameter. If that is the case, this prefix is truncated. If nodescendant with the given id can be found thefunction raises an exception unless the optional parameter raise is setto False.

Syntax

Public Function FindById( _

ByVal Id As String, _

Optional ByVal Raise As Variant _) As GuiComponent

Parameters

Id

Raise

Example

Unless there are several sessions or connections in use, the following calls are equivalent:Set Comp = UserArea.findById("/app/con[0]/ses[0]/wnd[0]/usr/txtHEADER-FBFOOTLINE")Set Comp = UserArea.findById("txtHEADER-FBFOOTLINE")

See Also

GuiBarChart Object



FindByName Method

Description

Unlike findById, this function does not guarantee a unique result. It will simply return the first descendant matchingboth the name and type parameters.This is a more natural description of the object than the complex id, but it onlymakes sense on dynpro objects as most other objects do not have a meaningfulname. If no descendant withmatching name and type can be found, the function raises an exception.

Syntax

Public Function FindByName( _


ByVal Type As String _) As GuiComponent

Parameters

Name

Type

Example

Set Comp = UserArea.findByName("HEADER-FBFOOTLINE", "GuiTextField")

See Also

GuiBarChart Object



FindByNameEx Method

Description

This function has been introduced for performance reasons. The parameter type is not a string as in findByNamebut rather a number taken from GuiComponent.typeAsNumber.

Syntax

Public Function FindByNameEx( _


ByVal Type As Long _) As GuiComponent

Parameters

Name

Type

See Also

GuiBarChart Object



GetBarContent Method

Description

Returns the content of the bar.

Syntax

Public Function GetBarContent( _

ByVal chartId As Long, _

ByVal barId As Long, _

ByVal textId As Long _) As String

Parameters


barId

Index of the bar within the given chart.

textIdInternal value, do be determined during recording.

See Also

GuiBarChart Object



GetGridLineContent Method

Description

Returns the content of the grid line.

Syntax

Public Function GetGridLineContent( _

ByVal chartId As Long, _

ByVal gridlineId As Long, _

ByVal textId As Long _) As String

Parameters


gridlineIdIndex of the grid line within the given chart.

textIdInternal value, do be determined during recording.

See Also

GuiBarChart Object



GridCount Method

Description

Returns the number of grids within the chart.

Syntax

Public Function GridCount( _


Parameters


See Also

GuiBarChart Object



LinkCount Method

Description

Returns the number of links within the given chart.

Syntax

Public Function LinkCount( _


Parameters


See Also

GuiBarChart Object



SelectContextMenuItem Method

Description

Select an item from the controls context menu.

Syntax

Public Sub SelectContextMenuItem( _

ByVal FunctionCode As String _)

Parameters

FunctionCode

See Also

GuiBarChart Object



SelectContextMenuItemByPosition Method

Description

This method allows you to select a context menu item using the position of the item. It is therefore independent ofthe menu item text.

Syntax

Public Sub SelectContextMenuItemByPosition( _

ByVal PositionDesc As String _)

Parameters

PositionDesc

Remarks

The parameter is a string containing the path to the item. If the context menu item is on the top level menu, this isjust the zero-base index of the item. Otherwise, the positions on the menu and respective submenus should beconcatenated, separated by "|".

See Also

GuiBarChart Object



SelectContextMenuItemByText Method

Description

Select a menu item of a context menu using the text of the item and possible higher level menus.

Syntax

Public Sub SelectContextMenuItemByText( _

ByVal Text As String _)

Parameters

Text

See Also

GuiBarChart Object



SendData Method

Description

Send data to the server.

Syntax

Public Sub SendData( _

ByVal Data As String _)

Parameters

DataInternal data stream. To be determined during recording.

See Also

GuiBarChart Object



SetFocus Method

Description

This function can be used to set the focus onto an object. If a user interacts with SAP GUI, it moves the focuswhenever the interaction is with a new object. Interacting with an object through the scripting component does notchange the focus. There are some cases in which the SAP application explicitly checks for the focus and behavesdifferently depending on the focussed object.

Syntax

Public Sub SetFocus()

Example

Pressing this button to display the details of an entry in the table control will only succeed if the focus has alreadybeen set on the respective entry.

See Also

GuiBarChart Object



ShowContextMenu Method

Description

Shows the context menu of the control.

Syntax

Public Sub ShowContextMenu()

See Also

GuiBarChart Object



Visualize Method

Description

Calling this method of a component will display a red frame around the specified component if the parameter on istrue. The frame will be removed if on is false. Some components such as GuiCtrlGridView support displaying theframe around inner objects, such as cells. The format of the innerObject string is the same as for the dumpStatemethod.

Syntax

Public Function Visualize( _

ByVal On As Boolean, _

Optional ByVal InnerObject As Variant _) As Boolean

Parameters

On

InnerObject

See Also

GuiBarChart Object



AccDescription Property

Description

Accessibility description of the shell. This description can be used for shells that do not have a title element.

Property type

Read-only property


Public Property AccDescription() As String

See Also

GuiBarChart Object



AccLabelCollection Property

Description

The collection contains objects of type GuiLabel that were assigned to this control in the ABAP Screen Painter.

Property type

Read-only property


Public Property AccLabelCollection() As GuiComponentCollection

See Also

GuiBarChart Object



AccText Property

Description

An additional text for accessibility support.

Property type

Read-only property


Public Property AccText() As String

See Also

GuiBarChart Object



AccTextOnRequest Property

Description

An additional text for accessibility support.

Property type

Read-only property


Public Property AccTextOnRequest() As String

See Also

GuiBarChart Object



AccTooltip Property

Description

An additional tooltip text for accessibility support.

Property type

Read-only property


Public Property AccTooltip() As String

See Also

GuiBarChart Object



Changeable Property

Description

An object is changeable if it is neither disabled nor read-only.

Property type

Read-only property


Public Property Changeable() As Boolean

See Also

GuiBarChart Object



ChartCount Property

Description

Number of charts.

Property type

Read-only property


Public Property ChartCount() As Long

See Also

GuiBarChart Object



Children Property

Description

This collection contains all direct children of the object.

Property type

Read-only property


Public Property Children() As GuiComponentCollection

See Also

GuiBarChart Object



ContainerType Property

Description

This property is TRUE, if the object is a container and therefore has the children property.

Property type

Read-only property


Public Property ContainerType() As Boolean

See Also

GuiBarChart Object



CurrentContextMenu Property

Description

This property is only set when a context menu is available at the shell object.

Property type

Read-only property


Public Property CurrentContextMenu() As GuiContextMenu

See Also

GuiBarChart Object



DefaultTooltip Property

Description

Tooltip text generated from the short text defined in the data dictionary for the given screen element type.

Property type

Read-only property


Public Property DefaultTooltip() As String

See Also

GuiBarChart Object



DragDropSupported Property

Description

This property is True if the shell allows drag and drop operations.

Property type

Read-only property


Public Property DragDropSupported() As Boolean

See Also

GuiBarChart Object



Handle Property

Description

The window handle of the control that is connected to the GuiShell.

Property type

Read-only property


Public Property Handle() As Long

See Also

GuiBarChart Object



Height Property

Description

Height of the component in pixels.

Property type

Read-only property


Public Property Height() As Long

See Also

GuiBarChart Object



IconName Property

Description

If the object has been assigned an icon, then this property is the name of the icon, otherwise it is an empty string.

Property type

Read-only property


Public Property IconName() As String

See Also

GuiBarChart Object



Id Property

Description

An object id is a unique textual identifier for the object. It is built in a URL-like formatting, starting at theGuiApplication object and drilling down to the respective object.

Property type

Read-only property


Public Property Id() As String

Remarks

Using fully qualified ids has one significant drawback: the index of both the connection and session become part ofthe id. If the id given above is used to search for the text field the search will only be successful if the session towhich the text field belongs is again the first session of the first connection. This problem can be circumventedusing relative ids. A relative id does not start with /. Instead it begins with the type prefix of the child of the objecton which the search is started. Therefore it is usually preferable to truncate the first part of the id up to the sessionindex and work with a relative id, such as wnd[0]/usr/ctxtRS38M-PROGRAMM. This relative id is still unique withrespect to a given session, but it is independent of the number of sessions or connections currently open.

Example

The id of the text field in transaction se38 is /app/con[0]/ses[0]/wnd[0]/usr/ctxtRS38M-PROGRAMM. It is createdthrough first taking the type specific prefix for the given component, which in this case is 'ctxt'. The name of thefield is then appended, if one exists. For dynpro fields the name is the field name defined in screen painter, in thiscase 'RS38M-PROGRAM'. In many cases, especially if there is no name available for an object, an index has to beappended for uniqueness. Finally, the id of the parent object is added as a prefix, separated by the '/' character.

Objects of type GuiShell do not have a name. So whenever there are several objects of this type on the same levelin the hierarchy, a one-dimensional index is appended for uniqueness. On the other hand, list and step-loop screensare set up in a two-dimensional grid, so the index string added to the id will have two components as well.

See Also

GuiBarChart Object

SAP AG

Documents

SAP GUI Scripting API 6 - Innowerahelp.innowera.net/PR2008/2.00/SAP_Scripting_API.pdf · SAP GUI Scripting API Send comments on this topic. Introduction SAP GUI Scripting API Purpose