Sample Program: SAMPLE.C 

This section describes the sample code provided with the GUILib.

Compile this program with the GUILib header file, link it with guilib.lib. Also make sure that the GUILib DLL is in the same directory as sample.exe or in the system directory.

The sample demonstrates how to write a program using the SAP GUILib library and how to implement functions that communicate with the R/3 System.

The program results in listing of the current users in a given R/3 system.

The program prompts the user to enter R/3 application server information and user information.

Analysis of the Sample Program

hHandle = It_NewConnection(Hostname, SystemID, SAPGUI_FRONT);

This function establishes a connection between the R/3 application server and GUILib. Flag is set as SAPGUI_FRONT to start SAPGUI with a connection to the R3 system at startup. FRONT will display screen information on SAPGUI while your application moves along. This function returns a non-zero handle to a SAP Automation GUILib session if successful. If the returned handle is zero, the connection to R/3 failed.

if ((It_Login (hHandle, Client, User, Passwd, Language))==0)
printf ( "\n Failed to log on\n");
return ;
} else
printf (" Successful Login as %s on %s\n",User,

This function logs in to an SAP system with a standard login screen using the specified client, user name, password, and language. If the login fails, the program should call It_StopSapGui to stop the SAP FRONT, then call It_FreeConnection to close the connection with R/3 system.

It_GetTransaction(hHandle, "se38")

It_GetTransaction invokes the specified transaction. The second parameter in this function is a pointer to a transaction code, such as transaction "se38".

It_GetEvent(hHandle, &pEvt)

pEvt must be initialized to zero before calling this function.

It_SetDumpHook(hHandle, putt)

This function provides the printing function to be used when It_ListControls is called.

The second parameter in this function is a pointer to the printing function putt. Putt is defined in the sample program that provides the standard printing function.


This function prints a list of control information using the printing function specified by It_SetDumpHook.

const char* PROGRAM_FIELD = "RS38M-PROGRAMM" ;
CtrlIndex = ItEv_FindControl(pEvt, PROGRAM_FIELD,
if (CtrlIndex < 0)
printf(" Failed to find a CTRL_MATCH control named \
return ;

This function looks up the first control with RS38M-PROGRAMM as the field name and with CTRL_MATCH as the type of control. The second parameter is a pointer to the control. By default, it accepts the field name of the control. The third parameter is a flag to control the search. In this example, we search the first control by field name and type of control, with the flag set as FC_FIND_TYPE(CTRL_MATCH) || FC_FIND_FIELD). If the control is found, a 0-based index of control will be returned. Otherwise, return –1.

ItEv_SetValue (pEvt, ITCTRL_IDX(CtrlIndex), PROGRAM)

This function fills the program name into the matchcode field, just as in R/3 system, you would enter the program name in se38.


It_SendReturn(hHandle, &pEvt)

Those two functions simulate pressing the "Execute" button on SAPGUI. ItEv_SetCurPosByCtrl is used to position the cursor on a pushbutton. It_SendReturn has the same effect as pushing the toolbar button "Execute" when using the SAPGUI.

It_GetEvent(hHandle, &pEvt)
/* print out the title menu on the screen */
for (k = 2; k < 17 ; k++)
printf("%s ", pEvt->screen.pCtrl[k].value);
/* print out the content of login informaton */
for (i = 1; i < (int) pEvt->screen.iCtrlCnt/15; i++)
for (j = i * 15+4; j < (i+1)*15 + 4; j += 2)
printf("%s | ", pEvt->screen.pCtrl[j].value);
printf("\n %s\n",

After executing the program, a user screen will be displayed. Each displayed field is a control. This part of the code formats the values of those controls and prints them out at the console.


The normal logoff consists of three steps: stop SAPGUI FRONT, logoff from R/3 as a user and disconnect from the R/3 system. It_FreeConnection includes freeing the allocated resources.