Vous êtes sur la page 1sur 616

HELP.

BCMAS

Web Application Server

Release 621

SAP Online Help

25.10.2002

Copyright
Copyright 2002 SAP AG. All rights reserved.
No part of this publication may be reproduced or transmitted in any form or for any purpose
without
the express permission of SAP AG. The information contained herein may be changed
without prior notice.
Some software products marketed by SAP AG and its distributors contain proprietary
software components of other software vendors.
Microsoft, WINDOWS, NT, EXCEL, Word, PowerPoint and SQL Server are
registered trademarks of Microsoft Corporation.
IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390,
AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent
Miner, WebSphere, Netfinity, Tivoli, Informix and Informix Dynamic ServerTM are
trademarks of IBM Corporation in USA and/or other countries.
ORACLE is a registered trademark of ORACLE Corporation.
UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.
Citrix, the Citrix logo, ICA, Program Neighborhood, MetaFrame, WinFrame,
VideoFrame, MultiWin and other Citrix product names referenced herein are trademarks of
Citrix Systems, Inc.
HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C, World Wide
Web Consortium, Massachusetts Institute of Technology.
JAVA is a registered trademark of Sun Microsystems, Inc.
JAVASCRIPT is a registered trademark of Sun Microsystems, Inc., used under license for
technology invented and implemented by Netscape.
SAP, SAP Logo, R/2, RIVA, R/3, SAP ArchiveLink, SAP Business Workflow, WebFlow,
SAP EarlyWatch, BAPI, SAPPHIRE, Management Cockpit, mySAP, mySAP.com, and other
SAP products and services mentioned herein as well as their respective logos are
trademarks or registered trademarks of SAP AG in Germany and in several other countries
all over the world. MarketSet and Enterprise Buyer are jointly owned trademarks of
SAP Markets and Commerce One. All other product and service names mentioned are the
trademarks of their respective owners.

Web Application Server

620 SP 9

SAP Online Help

25.10.2002

Icons
Icon

Meaning
Caution
Example
Note
Recommendation
Syntax

Typographic Conventions
Type Style

Description

Example text

Words or characters that appear on the screen. These include field


names, screen titles, pushbuttons as well as menu names, paths and
options.
Cross-references to other documentation.

Example text

Emphasized words or phrases in body text, titles of graphics and tables.

EXAMPLE TEXT

Names of elements in the system. These include report names,


program names, transaction codes, table names, and individual key
words of a programming language, when surrounded by body text, for
example, SELECT and INCLUDE.

Example text

Screen output. This includes file and directory names and their paths,
messages, source code, names of variables and parameters as well as
names of installation, upgrade and database tools.

EXAMPLE TEXT

Keys on the keyboard, for example, function keys (such as F2) or the
ENTER key.

Example text

Exact user entry. These are words or characters that you enter in the
system exactly as they appear in the documentation.

<Example text>

Variable user entry. Pointed brackets indicate that you replace these
words and characters with appropriate entries.

Web Application Server

620 SP 9

SAP Online Help

25.10.2002

Web Application Server ........................................................................................................... 19


Architecture of the SAP Web Application Server................................................................. 19
SAP Web Application Server Components ...................................................................... 20
Internet Communication Manager (ICM) ...................................................................... 22
HTTP Plug-In ............................................................................................................ 24
Logging in the ICM .................................................................................................... 25
Binding Ports Lower Than 1024 on UNIX ................................................................. 25
Error Handling Using the ICM ................................................................................... 28
Examples of a Dynamic Error Page ...................................................................... 31
Internet Server Cache................................................................................................... 34
Cache Key................................................................................................................. 37
Identifying Objects..................................................................................................... 38
Manipulating Cache Properties................................................................................. 39
Invalidating Objects in the Cache ............................................................................. 39
Search Sequence in the ICM Server Cache ............................................................. 40
Storing Data Objects in the ICM Server Cache ........................................................ 41
Caching BSPs ........................................................................................................... 41
ICM Server Clipboard ................................................................................................... 44
Parameterizing the ICM and the ICM Server Cache........................................................ 45
Sample Profile for the ICM............................................................................................ 46
exe/icman...................................................................................................................... 49
rdisp/start_icman .......................................................................................................... 49
icm/plugin_<xx>............................................................................................................ 49
icm/server_port_<xx> ................................................................................................... 49
Binding Ports Lower Than 1024 on UNIX ................................................................. 51
icm/HTTP/j2ee_<xx> .................................................................................................... 53
icm/host_name_full....................................................................................................... 54
icm/min_threads ........................................................................................................... 54
icm/max_threads .......................................................................................................... 54
icm/min_spare_threads ................................................................................................ 55
icm/max_services ......................................................................................................... 55
icm/max_plugins ........................................................................................................... 56
icm/req_queue_len ....................................................................................................... 56
icm/listen_queue_len .................................................................................................... 56
icm/max_conn............................................................................................................... 57
icm/max_sleep.............................................................................................................. 57
icm/<PROT>/context_quota ......................................................................................... 57
icm/accept_remote_trace_level .................................................................................... 58
icm/ccms_monitoring .................................................................................................... 58
Web Application Server

620 SP 9

SAP Online Help

25.10.2002

icm/keep_alive_timeout ................................................................................................ 58
icm/conn_timeout.......................................................................................................... 58
icm/wp_mpi_available................................................................................................... 59
icm/wp_roll_timeout ...................................................................................................... 59
icm/dpj2ee..................................................................................................................... 59
icm/HTTP/file_access_<xx> ......................................................................................... 60
icm/HTTP/redirect_<xx> ............................................................................................... 60
icm/HTTP/logging_<xx> ............................................................................................... 61
Logging in the ICM .................................................................................................... 63
icm/HTTPS/verify_client ............................................................................................... 64
icm/HTTP/server_cache_<xx> ..................................................................................... 64
icm/HTTP/server_cache_<x>/max_entries .................................................................. 65
icm/HTTP/server_cache_<xx>/clear ............................................................................ 65
icm/HTTP/server_cache_<xx>/expiration..................................................................... 65
icm/HTTP/server_cache_<xx>/max_name_len............................................................ 66
icm/HTTP/server_cache_<xx>/max_ufo_entries.......................................................... 66
icm/HTTP/server_cache_<xx>/size_MB ...................................................................... 66
icm/HTTP/server_cache_<xx>/memory_size_MB ....................................................... 67
icm/HTTP/server_cache_<xx>/ufo_list......................................................................... 67
icm/HTTP/server_cache_<xx>/ufo_expiration.............................................................. 68
Memory Pipes............................................................................................................... 68
Monitoring the ICM with the ICM Monitor......................................................................... 68
Monitoring the State of the ICM .................................................................................... 71
Monitoring and Administrating the ICM Server Cache ................................................. 73
Displaying and Changing Services............................................................................... 74
Analyzing Problems and Searching for Errors.............................................................. 75
Administration of the ICM ............................................................................................. 77
SAP J2EE Engine Administration................................................................................. 78
SAP Web Dispatcher........................................................................................................ 79
Operating the SAP Web Dispatcher ............................................................................. 82
Server Selection and Load Balancing Using the SAP Web Dispatcher ....................... 84
Server Groups in the Internet Communication Framework ...................................... 86
The SAP Web Dispatcher Profile Parameter................................................................ 87
Example: Profile File of a SAP Web Dispatcher ....................................................... 91
Minimal Configuration for the SAP Web Dispatcher ................................................. 92
SAP Web Dispatcher as a URL Filter........................................................................... 93
SAP Web Dispatcher and SSL ..................................................................................... 95
High Availability of the SAP Web Dispatcher ............................................................... 96
HTTP Load Distribution Using SAP Message Server .................................................. 97
SAP Web Application Server: Web Server and Web Client............................................. 99

Web Application Server

620 SP 9

SAP Online Help

25.10.2002

Server Role ................................................................................................................... 99


Client Role .................................................................................................................. 100
Integrating the SAP J2EE Engine .................................................................................. 101
Using the SAP J2EE Engine with Standalone Dispatcher ......................................... 103
SAP J2EE Engine Administration............................................................................... 103
Profile Parameters for the SAP J2EE Engine............................................................. 104
Internet Communication Framework.................................................................................. 106
HTTP Communication Using the SAP System as a Server........................................... 107
HTTP Request Handler .............................................................................................. 107
Design......................................................................................................................... 108
Interaction Model..................................................................................................... 108
Calling the Function Module HTTP_DISPATCH_REQUEST (1) ........................ 110
Creating the Server Control Block (2) ................................................................. 110
Filling the Server Control Block (4)...................................................................... 110
Client Logon (6) ................................................................................................... 110
Selecting and Calling the HTTP Request Handler (HTTP Extension) ................ 111
Processing the Request Using the HTTP Extension (7) ..................................... 111
Sending Back the Response (9-10) .................................................................... 112
Stateless and Stateful Model .................................................................................. 112
Logging On to SAP Web Application Server........................................................... 113
Determining the Logon Language ....................................................................... 114
ICF Classes and Interfaces ........................................................................................ 115
IF_HTTP_SERVER................................................................................................. 117
Attributes ............................................................................................................. 117
Constants ............................................................................................................ 118
Methods ............................................................................................................... 119
IF_HTTP_RESPONSE and IF_HTTP_REQUEST ................................................. 119
IF_HTTP_ENTITY................................................................................................... 121
Accessing Header Fields..................................................................................... 123
Accessing Form Fields ........................................................................................ 127
Accessing Cookies .............................................................................................. 128
Accessing HTTP Body Data ................................................................................ 129
Accessing HTTP Multipart Data .......................................................................... 130
IF_HTTP_EXTENSION........................................................................................... 130
Attributes ............................................................................................................. 131
Constants for Describing the Control Flow.......................................................... 131
Constants for Describing Lifetime Control........................................................... 132
Methods ............................................................................................................... 133
IF_HTTP_UTILITY .................................................................................................. 133
Using the ICF.............................................................................................................. 134

Web Application Server

620 SP 9

SAP Online Help

25.10.2002

Implementing Handler Classes ............................................................................... 134


Linking a HTTP Request to an ICF Service ............................................................ 136
Virtual Hosts ........................................................................................................ 136
Virtual Hosts - Advantages .............................................................................. 139
Creating an ICF Service ...................................................................................... 140
Anonymous Logon Data .................................................................................. 143
Service Options................................................................................................ 144
Security Requirements..................................................................................... 145
Basic Authentication ........................................................................................ 146
Error Page........................................................................................................ 146
Activating and Deactivating an ICF Service ........................................................ 147
Internal Aliases .................................................................................................... 148
External Aliases................................................................................................... 151
Monitoring and Troubleshooting Functions............................................................. 151
Special Features ..................................................................................................... 154
Transporting ICF Services ...................................................................................... 155
HTTP Communication Using the SAP System as a Client ............................................ 155
Interaction Model ........................................................................................................ 156
Sample Program ..................................................................................................... 157
Connection Establishment Using Destination (SM59)................................................ 161
Parallel Processing Requests..................................................................................... 164
Redirecting Requests ................................................................................................. 165
Configuring Proxies .................................................................................................... 165
Interface IF_HTTP_CLIENT ....................................................................................... 167
Attributes ................................................................................................................. 168
Constants ................................................................................................................ 169
Methods................................................................................................................... 169
Web Applications and Business Server Pages.................................................................. 170
User Concepts................................................................................................................ 171
Logging onto BSP Applications .................................................................................. 171
Prerequisites ........................................................................................................... 173
Testing Security Settings ........................................................................................ 174
The Authentication Process .................................................................................... 177
Using BSP Application SYSTEM ............................................................................ 179
SYSTEM_PUBLIC .................................................................................................. 180
Enhancements ........................................................................................................ 185
Logging off BSP Applications.................................................................................. 188
Using a Default User for BSP Applications................................................................. 189
Creating a Default User........................................................................................... 190
Using an Internet User for BSP Applications.............................................................. 191

Web Application Server

620 SP 9

SAP Online Help

25.10.2002

Sample BSP Application for Using Internet Users.................................................. 192


Logging On as an Internet User .......................................................................... 193
Creating New Users ............................................................................................ 194
Programming Model ....................................................................................................... 197
What is a BSP Application? ........................................................................................ 197
Structure of a BSP Application................................................................................ 198
Accessing a BSP Application.................................................................................. 201
Starting and Ending a BSP Application................................................................... 204
System-Specific URL Parameters .......................................................................... 204
Processing a BSP Application ................................................................................ 206
Creating a BSP Application..................................................................................... 206
Application Class of a BSP Application................................................................... 207
BSP Components ....................................................................................................... 210
Properties................................................................................................................ 211
Layout...................................................................................................................... 212
Event Handler ......................................................................................................... 213
OnCreate ............................................................................................................. 213
OnRequest .......................................................................................................... 214
OnInitialization ..................................................................................................... 215
OnInputProcessing .............................................................................................. 216
OnManipulation ................................................................................................... 217
OnDestroy ........................................................................................................... 218
Page Attributes........................................................................................................ 218
Type Definitions ...................................................................................................... 221
BSP Directives............................................................................................................ 221
Page Directive......................................................................................................... 222
Inline Code .............................................................................................................. 223
Comments............................................................................................................... 224
Include Directive...................................................................................................... 224
OTR Directives........................................................................................................ 224
Transferring Variables............................................................................................. 225
Extension Directive ................................................................................................. 225
Classes and Interfaces ............................................................................................... 225
Class CL_BSP_APPLICATION .............................................................................. 226
Class CL_BSP_MESSAGES .................................................................................. 226
Class CL_BSP_SERVER_SIDE_COOKIE ............................................................. 230
Class CL_BSP_GET_TEXT_BY_ALIAS................................................................. 235
Class CL_BSP_CONTROLLER2............................................................................ 236
Interface IF_BSP_APPLICATION........................................................................... 240
Interface IF_BSP_APPLICATION_EVENTS .......................................................... 245

Web Application Server

620 SP 9

SAP Online Help

25.10.2002

Interface IF_BSP_NAVIGATION ............................................................................ 248


Interface IF_BSP_PAGE......................................................................................... 254
Interface IF_BSP_RUNTIME .................................................................................. 262
Interface IF_BSP_PAGE_CONTEXT ..................................................................... 266
IF_CLIENT_INFO Interface..................................................................................... 267
Global Objects ............................................................................................................ 278
Object application.................................................................................................... 279
Object navigation .................................................................................................... 280
Object runtime......................................................................................................... 281
Object request......................................................................................................... 282
Object response ...................................................................................................... 282
Object messages .................................................................................................... 282
Object page............................................................................................................. 283
Object page_context ............................................................................................... 284
BSP Extensions .......................................................................................................... 284
Button ...................................................................................................................... 287
TableView ............................................................................................................... 288
Defining Your Own BSP Extension......................................................................... 293
BSP Extension Framework.................................................................................. 295
Creating BSP Extensions .................................................................................... 296
Defining BSP Elements ....................................................................................... 297
Defining the Element Content.......................................................................... 299
User-Defined Validation ................................................................................... 301
Iteration Through Element Content.................................................................. 303
Manipulation of the Element Content............................................................... 304
Pass by Reference for Attributes ..................................................................... 305
Activating the BSP Extension.............................................................................. 306
Implementing Element Handler Classes ............................................................. 307
Generated Classes and Class Hierarchy......................................................... 307
Basis Class CL_BSP_ELEMENT .................................................................... 309
Entering Documentation ...................................................................................... 311
Using BSP Elements ........................................................................................... 312
Example: Using Extensions in BSP Pages...................................................... 313
Composite Elements ............................................................................................... 314
Creating Page before.htm ................................................................................... 315
Design Solution ................................................................................................... 317
Creating a New BSP Extension with Elements ............................................... 318
Creating Page after.htm................................................................................... 319
Dynamically Processing BSP Elements .......................................................... 320
Creating a New BSP Extension with Composite Elements................................. 324

Web Application Server

620 SP 9

SAP Online Help

25.10.2002

Step 1 a) Implementing <sf:SimpleFormItem> ................................................ 324


Step 1 b) Using <htmlb:SimpleFormItem>....................................................... 326
Step 2: Creating <sf:SimpleForm> .................................................................. 328
Step 3: Changes to the Look and Feel ............................................................ 331
Model View Controller (MVC) ..................................................................................... 331
MVC Design Pattern ............................................................................................... 335
Using MVC for BSP................................................................................................. 336
Creating a Controller ........................................................................................... 337
Creating a View ................................................................................................... 338
Testing Controllers .............................................................................................. 338
Calling (Sub) Controllers ..................................................................................... 339
Calling a View...................................................................................................... 340
Creating Error Pages........................................................................................... 341
From Pages to Controllers ...................................................................................... 342
Call Options of BSP Components........................................................................... 343
Navigation ............................................................................................................... 344
Lifetime.................................................................................................................... 345
Data Binding............................................................................................................ 346
Calling the Model Class by the Controller ........................................................... 349
Components............................................................................................................ 349
Process Flow ....................................................................................................... 351
Creating Your Own Components ........................................................................ 356
Creating the Top-Level Controller.................................................................... 357
Creating Components ...................................................................................... 358
Calling Components......................................................................................... 358
Determining Input Processing.......................................................................... 361
Class CL_BSP_CONTROLLER2............................................................................ 361
Examples of Architecture ........................................................................................ 365
BSP Application with Controllers and Views ....................................................... 365
BSP Application with Several Views per Controller ............................................ 366
Combination of the Previous Examples .............................................................. 367
Calling Controllers of Other Applications............................................................. 367
Calling Several Controllers from a View.............................................................. 368
Model View Controller Tutorial................................................................................ 369
Creating a Controller ........................................................................................... 370
Creating a View ................................................................................................... 372
Calling a Controller .............................................................................................. 375
Calling Java Beans ..................................................................................................... 377
The FLUSH Method ................................................................................................ 379
Possible Return Values........................................................................................... 380

Web Application Server

620 SP 9

10

SAP Online Help

25.10.2002

Session Handling........................................................................................................ 381


Stateful BSP Applications ....................................................................................... 381
Session Cookie.................................................................................................... 382
Stateless BSP Applications..................................................................................... 383
Server-Side Cookies and Data Persistency ........................................................ 384
Hybrid Forms........................................................................................................... 387
Setting Stateful or Stateless.................................................................................... 388
Stateful or Stateless Programming? ....................................................................... 388
A Sample BSP Application .................................................................................. 391
Control Flow of BSPs.................................................................................................. 391
BSP Only with Layout ............................................................................................. 395
BSP With Layout and Initialization .......................................................................... 396
BSPs with Layout, Initialization and Navigation...................................................... 398
BSPs with Layout, Initialization and Input Processing ............................................ 400
Caching BSPs............................................................................................................. 403
Page Layout................................................................................................................ 405
Accessibility ................................................................................................................ 406
Programming Environment............................................................................................. 407
Recommended Browser Settings ............................................................................... 407
Debugging................................................................................................................... 408
Breakpoints for BSP Page Fragments .................................................................... 409
Tracing HTTP Requests.......................................................................................... 409
Internationalization and Translation............................................................................ 412
Creating OTR Alias Text ......................................................................................... 413
Creating OTR Long Text ......................................................................................... 415
OTR Texts in ABAP ................................................................................................ 415
BSP Development Tools............................................................................................. 416
MIME Repository..................................................................................................... 416
Pretty Printer in the Web Application Builder .......................................................... 418
Implementing External Tools with WebDAV ........................................................... 420
Tag Browser............................................................................................................ 421
XSLT Editor............................................................................................................. 423
BAPI Explorer.......................................................................................................... 424
Online Text Repository............................................................................................ 425
Task Formatting.......................................................................................................... 426
Stylesheets ................................................................................................................. 426
Setting Stylesheets for HTMLB and XHTMLB ........................................................ 427
File Upload in BSP Applications ................................................................................. 429
Uploading Files and Manipulating their Content ..................................................... 433
Handling Incorrect Entries .......................................................................................... 434

Web Application Server

620 SP 9

11

SAP Online Help

25.10.2002

Outputting Error Messages for Auto Page Attributes.............................................. 436


Creating Page Attributes ..................................................................................... 436
Execute the Initialization...................................................................................... 437
Defining the Layout.............................................................................................. 437
Using Object messages....................................................................................... 439
Coding Alternative Error Output .......................................................................... 439
Adding Your Own Error Messages ......................................................................... 440
Sending E-Mails from BSP Applications..................................................................... 441
Creating Order Pages ............................................................................................. 442
Creating Application Classes .................................................................................. 442
Class Attributes ................................................................................................... 444
Class Methods..................................................................................................... 444
Method SET_ADDRESS ................................................................................. 444
Method SET_TIME .......................................................................................... 445
Method SEND .................................................................................................. 446
Calling the Mail Class .......................................................................................... 448
MIME Types of a Page ............................................................................................... 448
Mobile Extensions to the SAP Web Application Server ............................................. 449
Differences Between Mobile Devices ..................................................................... 450
Effects of the Differences Between WAP Browsers ............................................... 451
Device Recognition ................................................................................................. 452
IF_CLIENT_INFO Interface..................................................................................... 454
GET_ACCEPT Method........................................................................................ 465
GET_BACK_HARD_WIRED Method .................................................................. 467
GET_BACK_LABEL Method ............................................................................... 467
GET_CHAR_HEIGHT Method ............................................................................ 467
GET_BREAKING_SPACE Method ..................................................................... 468
GET_BROWSER_CATEGORY Method ............................................................. 468
GET_BROWSER_NAME Method ....................................................................... 468
GET_BROWSER_OS Method ............................................................................ 469
GET_CHAR_WIDTH Method .............................................................................. 469
GET_COOKIES_SUPPORTED Method ............................................................. 470
GET_CSS_SUPPORTED Method ...................................................................... 470
GET_DEFAULT_ACTION_DESIGN Method ...................................................... 470
GET_DEFAULT_BLOCK_SEPARATOR Method ............................................... 471
GET_DEFAULT_BULLET Method ...................................................................... 472
GET_DEFAULT_FORM_STYLE Method............................................................ 472
GET_DEFAULT_MENU_STYLE Method............................................................ 473
GET_DEVICE_CATEGORY Method .................................................................. 473
GET_DEVICE_NAME Method ............................................................................ 474

Web Application Server

620 SP 9

12

SAP Online Help

25.10.2002

GET_FIELDSET_LAYOUT Method .................................................................... 474


GET_FIELDSET_TITLE_VISIBLE Method ......................................................... 475
GET_FORM_FACTOR Method........................................................................... 475
GET_FORM_MENU_SUPPORTED Method ...................................................... 476
GET_FRAMES_SUPPORTED Method............................................................... 476
GET_HREF_WITH_PARAMS_SUPPORTED Method ....................................... 476
GET_IMAGE_LINKS_SUPPORTED Method...................................................... 477
GET_INPUT_SHOWN_WITH_CAPTION Method .............................................. 477
GET_LINKS_SEPARATED Method.................................................................... 477
GET_LINK_DECORATION Method .................................................................... 478
GET_LINK_TEXT_WIDTH Method ..................................................................... 478
GET_MARQUEE_LINK_SUPPORTED Method ................................................. 478
GET_MARQUEE_TEXT_SUPPORTED Method ................................................ 478
GET_MAX_LINK_LENGTH Method.................................................................... 479
GET_MEDIA_FORMATS Method ....................................................................... 479
GET_NEWLINE_AFTER_IMAGE Method .......................................................... 479
GET_NBSP_SUPPORTED Method.................................................................... 480
GET_NESTED_TABLES_SUPPORTED Method ............................................... 480
GET_NEWLINE_AFTER_INPUT Method ........................................................... 480
GET_NEWLINE_BEFORE_IMAGE Method ....................................................... 481
GET_NEWLINE_BEFORE_INPUT Method ........................................................ 481
GET_NEWLINE_BEFORE_LINK Method........................................................... 481
GET_NEWLINE_BETWEEN_IMAGES Method.................................................. 482
GET_NEWLINE_BETWEEN_LINKS Method ..................................................... 482
GET_NEWLINE_BETW_LINK_AND_TAG Method ............................................ 482
GET_PAGE_SIZE_MAX Method ........................................................................ 483
GET_PIXEL_HEIGHT Method ............................................................................ 483
GET_PIXEL_WIDTH Method .............................................................................. 483
GET_REDIR_RELATIVE_SUPPORTED Method............................................... 483
GET_SELECTION_MENU_SUPPORTED Method ............................................ 484
GET_SKIPPING_TO_INPUT Method ................................................................. 484
GET_SOFTKEY_NUM Method ........................................................................... 484
GET_SOFTKEY_STYLE1 Method...................................................................... 485
GET_SOFTKEY_STYLE2 Method...................................................................... 486
GET_SOFTKEY_TITLE_WIDTH Method............................................................ 487
GET_SCRIPT_SUPPORTED Method ................................................................ 488
GET_SUB_CATEGORY Method ........................................................................ 488
GET_TABLE_HAS_BORDERS Method ............................................................. 488
GET_TABLE_SUPPORTED Method .................................................................. 489
GET_TELEPHONY_LINKS_SUPPORTED Method ........................................... 490

Web Application Server

620 SP 9

13

SAP Online Help

25.10.2002

GET_TEXT_STYLES_SUPPORTED Method..................................................... 490


GET_TITLE_SUPPORTED Method.................................................................... 490
GET_TITLE_WIDTH Method .............................................................................. 491
GET_USER_AGENT Method.............................................................................. 492
Administrators Guide to Device Recognition.......................................................... 492
Data Retention for Device Recognition ............................................................... 493
Modifying Device Properties................................................................................ 494
Integrating Additional Mobile Devices ................................................................. 495
DDIC Services for BSP Applications .......................................................................... 497
Overview of the Type Properties............................................................................. 497
Technical Properties............................................................................................ 498
Output Properties ................................................................................................ 498
Language-Specific Texts ..................................................................................... 499
Services and Runtime Objects................................................................................ 499
GET_FIELD_LABEL............................................................................................ 500
GET_QUICKINFO ............................................................................................... 502
GET_DAY_COLLECTION................................................................................... 504
GET_MONTH_COLLECTION............................................................................. 504
GET_HISTORY_ID.............................................................................................. 505
GET_LOCAL_HISTORY_ID................................................................................ 506
GET_SIMPLE_HELPVALUES ............................................................................ 508
Use in BSP Applications ......................................................................................... 510
Application Help................................................................................................... 510
Field Labels ......................................................................................................... 511
Field History......................................................................................................... 512
Calendar .............................................................................................................. 514
Value Help ........................................................................................................... 514
Workplace 2.11 .............................................................................................................. 516
Preparing BSP Application for Integration in SAP Workplace.................................... 516
Adding a BSP Application to Your Favorites .............................................................. 517
Integrating a BSP Application in the Launchpad ........................................................ 517
Integrating a BSP Application as a MiniApp ............................................................... 518
Enterprise Portal 5.0....................................................................................................... 519
Portal and BSP Session Management ....................................................................... 520
Session Handling without Cookies ............................................................................. 522
Administration................................................................................................................. 523
Logon Ticket Cache.................................................................................................... 524
DNS Configuration for BSP Applications Under Windows 2000 ................................ 525
SAP Web Application Server Security ............................................................................... 527
Using the Secure Sockets Layer Protocol...................................................................... 528

Web Application Server

620 SP 9

14

SAP Online Help

25.10.2002

The Application Server's Personal Security Environments ........................................ 529


SSL Server PSE...................................................................................................... 530
SSL Client PSEs ..................................................................................................... 530
The SAP Cryptographic Library Installation Package ................................................ 531
Installing the SAP Cryptographic Library on the SAP Web AS .................................. 531
Setting the Profile Parameters for Using SSL ............................................................ 533
Configuring the SAP Web AS for Supporting SSL ..................................................... 534
Creating the SSL Server PSE................................................................................. 535
Generating Certificate Requests for the SSL Server PSEs .................................... 537
Sending the Certificate Requests to a CA .............................................................. 537
Importing the Certificate Request Response .......................................................... 539
Maintaining the SSL Server PSE's Certificate List.................................................. 540
Creating the Standard SSL Client PSE................................................................... 542
Creating the Anonymous SSL Client PSE .............................................................. 542
Creating Individual SSL Client PSEs ...................................................................... 543
Specifying that a Connection Should Use SSL....................................................... 544
Testing the SSL Configuration ................................................................................ 545
Making Sure the SSL Port is Set up Correctly .................................................... 545
Testing the Connection for SSL Server Authentication....................................... 546
Testing the Connection for SSL Client Authentication ........................................ 547
User Authentication ........................................................................................................ 547
Using Logon Tickets ................................................................................................... 547
Configuring the System for Issuing Logon Tickets ................................................. 549
Obtaining a Certificate Signed by the SAP CA ................................................... 549
Using a Self-Signed Certificate ........................................................................... 551
Changing from a Self-Signed Certificate to a Certificate Signed by the SAP CA 551
Configuring the System for Accepting Logon Tickets ............................................. 552
Protecting User Information .................................................................................... 555
Using X.509 Client Certificates ................................................................................... 555
Configuring the System for Using X.509 Client Certificates ................................... 557
Pluggable Authentication Services for External Authentication.................................. 557
Authentication Mechanisms Supported by the PAS ............................................... 560
Authentication Using Windows NTLM ................................................................. 561
Verifying User ID/Password on the Windows NT Domain Controller.................. 562
Authentication Using X.509 Client Certificates.................................................... 563
Authentication Using an LDAP Bind to a Directory Server.................................. 565
Authentication Using an Arbitrary Mechanism on the Web Server ..................... 566
Authentication Using a Mechanism Provided by a Partner ................................. 568
Prerequisites for Using PAS ................................................................................... 569
Logon Tickets ...................................................................................................... 569

Web Application Server

620 SP 9

15

SAP Online Help

25.10.2002

Prerequisites for Using Windows NTLM Authentication...................................... 570


Prerequisites for Verifying Users on the Domain Controller................................ 570
Prerequisites for Using X.509 Client Certificates ................................................ 571
Prerequisites for Using an LDAP Bind to a Directory Server .............................. 572
Prerequisites for Using an Arbitrary Mechanism on the Web Server.................. 573
Prerequisites for Using a Partner Mechanism..................................................... 573
Secure Network Communications ....................................................................... 574
Configuring the PAS................................................................................................ 574
Configuring the Use of Logon Tickets ................................................................. 575
Configuring Windows NTLM Authentication on the Web Server ........................ 577
Configuring SNC.................................................................................................. 577
Configuring SNC on the Application Server .................................................... 578
Configuring SNC on the AGate........................................................................ 579
Configuring SNC on the WGate....................................................................... 581
Installing the PAS ................................................................................................ 583
Configuring the PAS Service File ........................................................................ 583
Examples ......................................................................................................... 586
Specifying the HTTP Header Variable to Use ..................................................... 588
Maintaining the User Mapping in the SAP System ............................................. 589
Configuring the PAS for Providing the SAP User ID Directly .............................. 590
Troubleshooting ...................................................................................................... 590
Testing the Configuration Using the ITS Administration Tool ............................. 591
Testing the Use of SNC....................................................................................... 592
Testing Logon Tickets and PAS .......................................................................... 593
Checking the HTTP Header Variable .................................................................. 594
Sample Trace File: SNC Initialization.................................................................. 595
Sample Trace File (AGate): Successful PAS Using NTLM................................. 596
Sample Trace File (AGate): SAP User ID not Found.......................................... 596
Terminology and Abbreviations...................................................................................... 597
Certificate List ............................................................................................................. 597
Certification Authority (CA) ......................................................................................... 598
Credentials.................................................................................................................. 598
Logon Ticket ............................................................................................................... 598
Personal Security Environment (PSE)........................................................................ 599
Private Key.................................................................................................................. 599
Public Key ................................................................................................................... 599
Public-Key Certificate ................................................................................................. 600
Public-Key Infrastructure (PKI) ................................................................................... 600
Public-Key Technology ............................................................................................... 600
SAP Cryptographic Library (SAPCRYPTOLIB) .......................................................... 601

Web Application Server

620 SP 9

16

SAP Online Help

25.10.2002

SAP Security Library (SAPSECULIB) ........................................................................ 601


Secure Sockets Layer (SSL) Protocol ........................................................................ 601
Secure Store & Forward (SSF)................................................................................... 602
SSO Personal Security Environment (SSO PSE) ...................................................... 602
System PSE................................................................................................................ 603
Verification PSE.......................................................................................................... 603
FAQ.................................................................................................................................... 604
What is SAP Web Application Server? .......................................................................... 605
What is the Internet Communication Framework? ......................................................... 605
How Do I Create My Own HTTP Request Handlers? .................................................... 606
What is the BSP Runtime Environment? ....................................................................... 606
Can I Access a Web Server via HTTP? ......................................................................... 606
Is There a Server Cache for Storing Web Pages?......................................................... 606
What Are Business Server Pages?................................................................................ 607
Can I Generate BSPs Dynamically? .............................................................................. 607
How Do I Create a Basic BSP Application? ................................................................... 607
What Is an Application Class?........................................................................................ 608
How can I Transfer Data Between a View and a Page?................................................ 608
What Are BSP Directives and What BSP Directives Are There?................................... 609
Where Can I Store Pictures?.......................................................................................... 609
Can I Transfer Whole Tables as Page Attributes?......................................................... 609
How Can I Customize a BSP Application?..................................................................... 609
How Can I Determine the URL Path for my BSP? ......................................................... 610
How Can I Transfer Language or the Client to the URL? .............................................. 610
How Can I use Data Structures from a Different System?............................................. 610
What Do I Do If There is a Protocol Conflict? ................................................................ 611
How do I Handle DNS Configuration Problems? ........................................................... 611
How Can I Specify That My Application Does Not Require Log-In? .............................. 611
Can I Execute a User Switch for My BSP Application? ................................................. 612
How Do I Get My BSP Application into the Workplace? ................................................ 612
How Do I Get a BSP into a Portal Environment? ........................................................... 612
Can I Send E-mails from a BSP Application? ................................................................ 613
Can I Create BSP Applications for Mobile Terminals? .................................................. 613
Can I Create Pages with MIME Types Other Than Text and HTML?............................ 613
How Do You Determine the Display Language?............................................................ 613
How Can I Catch a Timeout for Long-Running Processes? .......................................... 614
How Can I Measure the Performance of My BSP Application? ..................................... 614
How Do I Administrate SAP Web Application Server? .................................................. 614
How Do I Configure SSL? .............................................................................................. 615
Is Single Sign-On supported for SAP Web Application Server? .................................... 615

Web Application Server

620 SP 9

17

SAP Online Help

25.10.2002

What Should I Know About the Network Configuration? ............................................... 615

Web Application Server

620 SP 9

18

SAP Online Help

25.10.2002

Web Application Server


Uses
The Web Application Server is a platform for efficient development and allows you to
implement Web applications. It builds upon proven and stable application server technology
and Internet-based infrastructure from SAP.
The Web Application Server combines reliability, scalability, multi-language support, remote
debugging, and connection to the Change and Transport System with open Internet
standards such as HTTP, HTTPS, SMTP, WebDav, HTML, XML and server-side scripting.

Introductory Comments
To facilitate the development of Web applications, the Web application server uses a pagebased programming model with server-side scripting as well as server page technology. The
result is a powerful but easy-to-learn programming model that supports the developer in the
design and implementation of Web applications. In the Web Application Server, the
presentation is separate from the business logic. This makes it possible to implement frontend technology.

The installation guide for SAP Web Application Server is available in the SAP
Service Marketplace under the alias instguides under SAP Web Application
Server and the relevant release. (http://service.sap.com/instguides).
For information on the technical infrastructure of SAP Web Application Server,
see the alias network under the Network Integration Guides in the SAP Service
Marketplace, or go straight to the website:
http://service.sap.com/network.

Integration
The Web Application Server offers HTTP client functionality, connection to DCOM, and Java,
by means of the SAP J2EE engine and the Java connector. This makes the Web Application
Server the perfect integration platform, even in heterogeneous environments.

Functions
This documentation is divided into the following parts:
Architecture of the Web Application Server [page 19]
Internet Communication Framework [page 106]
Web Applications and Business Server Pages [page 170]
SAP Web Application Server Security [page 527]
Frequently Asked Questions [page 604]

Architecture of the SAP Web Application Server


Uses
You can use SAP Web Application Server to implement both server-side and client-side Web
applications. Either the development environment integrated in SAP Web Application Server
or an external tool can be used to develop server applications (for example, online shops or

Web Application Server

620 SP 9

19

SAP Online Help

25.10.2002

portals). The Web sites you create using SAP Web Application Server can contain both static
HTML and dynamic script code. The scripting languages supported are ABAP and JavaScript.
For information on how to create Web applications, see Creating Web Applications with
Business Server Pages [page 170]. The general HTTP framework that provides the required
infrastructure is explained in Internet Communication Framework [page 106]. This section
deals with the technical architecture of the SAP Web Application Server. A basic
understanding of this is a prerequisite for the other sections.

Integration
From release 6.10 on, SAP Web Application Server is a component of mySAP.com.

Functions
The description of the architecture is divided into the following sections.
Components of the SAP Web Application Server [page 20] describes the following
components:

The Internet Communication Manager (ICM) [page 22] receives the HTTP requests from
the Internet and returns the response.

The Internet Server Cache [page 34] is used to cache static and dynamic contents with
Web applications.

The ICM Server Clipboard [page 44] is used for temporarily storing large data BLOBs
(Binary Large Objects).

We then describe how you can parameterize the ICM and the ICM server cache, and monitor
and administrate them from your SAP System (Transaction SMICM).
Profile Parameter of the ICM and the ICM Server Cache [page 45]
Monitoring the ICM with the ICM Monitor [page 68]
If you are using several SAP Web Application Servers, you can use the SAP Web Dispatcher
[page 79] to forward HTTP requests to the application server.
SAP Web Application Server: Webserver or Webclient [page 99] explains how the SAP Web
Application Server behaves as a server and a client. This subject is dealt with in more depth
in the section Internet Communication Framework [page 106].
You can also find documentation on Integrating the SAP J2EE Application Server [page 101]
in the SAP Web Application Server.

SAP Web Application Server Components


SAP Web Application Server is a further development of the SAP Application Server
technology. Based on the highly scalable SAP Application Server infrastructure, new
technologies have been implemented for directly processing HTTP requests (or other
protocols) coming from the Internet (that is, from a browser), and for sending HTTP requests
as HTTP client requests to the Internet.
To allow this additional functionality, the SAP kernel has been given an additional process,
the Internet Communication Manager (ICM). The ICM uses threads to communicate on the
Internet, as a server or as a client. If an incoming request is being processed by a work
process, memory pipes are used for data transfer. Memory pipes are located in shared
memory.
The following illustration shows an overview of the architecture of the SAP Web Application
Server, juxtaposing the traditional SAP architecture with that of the SAP Web Application
Server.
Web Application Server

620 SP 9

20

SAP Online Help

25.10.2002

SAP Web Application


Server Architecture

Traditional SAP Architecture


GUI

GUI

GUI

Work
Processes

Dispatcher
Queue

Gateway

Gateway

Dispatcher

Message
Server

SAP
App.
Server

et
n
er
t
In

Dispatcher

Dispatcher
Queue

Work
Processes

Memory
Pipes

ICM

Other App. Server or


SAP System

Message
Server

GUI

DB

DB

The individual components of SAP Web Application Server are explained in the following
sections:

Internet Communication Manager (ICM) [page 22]

ICM Server Cache [page 34]

ICM Server Clipboard [page 44]

The profile parameters required for configuring an SAP Web Application Server are described
under Parameterizing the ICM and the ICM Server Cache [page 45].
You can find additional, important information in the following sections:

Logging in the ICM [page 63]

Binding Ports < 1024 on UNIX [page 51]

Monitoring the ICM with the ICM Monitor [page 68]

Load balancing with the SAP Web Dispatcher [page 79]

Integration
The Internet Communication Framework represents the layer between the ICM and the
processing of requests in the work process. See the Internet Communication Framework
[page 106] documentation.
For information on using SAP Web Application Server to create Web applications using
Business Server Pages (BSP) and to implement the services of the Web Control Framework
(WCF), see Creating Web Applications with Business Server Pages [page 170].

Web Application Server

620 SP 9

21

SAP Online Help

25.10.2002

Internet Communication Manager (ICM)


Uses
The Internet Communication Manager ensures communication between the SAP system
(SAP Web Application Server) with the outside world using the HTTP, HTTPS and SMTP
protocols. In the server role, it can process requests from the Internet that have URLs with the
server/port combination which the ICM responds to. Independently of the URL, the ICM then
calls the corresponding local handlers. This is described for HTTP under HTTP Plug-In [page
24].

Introductory Comments
You need the ICM if you want your SAP Web AS to communicate with the Internet using
HTTP(S), SMTP or NNTP.

Integration
The ICM is part of the SAP Web AS. The ICM is implemented as an independent process,
and is started and monitored by the dispatcher. You can use profile parameters to set
whether the ICM should be started and how it should be configured (see also
Parameterization of the ICM and the ICM Server Cache [page 45]).

Functions
The ICM process uses threads to parallel process the load.
The following illustration shows a detailed overview of the ICM.

This illustration concentrates on the server role. For information on the client role
see Client Role [page 100].

te
n
I

et
n
r

ICM

Status

Dispatcher
Queue

Watchdog

Signal
Handler

Dispatcher

Conn. Info
...

Thread Control
Thread Pool
I/O
Handler
Plug-in
(e.g. HTTP)

En/Decryption
Handler

Worker
Thread

Conn.Handle
MPI
Handle
Plug-In
Data
per
Connection

Memory Pipes

Work
Processes

Req.Pipe Res.Pipe
OOB
OOB
Res.Pipe Req.Pipe

Request
Data

per Connection

Besides the pool of worker threads, which process incoming requests, the following ICM
components are also implemented as threads:

Web Application Server

620 SP 9

22

SAP Online Help

25.10.2002

Thread Control:
This thread accepts incoming TCP/IP requests and creates (or calls) a worker thread
from the thread pool to process the request. From this point on, thread control initializes
the connection info data.

Worker Threads:
These threads handle requests and responses for a connection. A worker thread contains
an I/O handler for network input and output, and various plug-ins for the different
protocols supported by the system (HTTP, SMTP, and so on). The plug-ins decide when
a sent packet is complete (this process is protocol-dependent).

Watchdog:
Usually, a worker thread waits for the response, regardless of whether the worker thread
is a server or a client. If a timeout occurs, the watchdog takes on the task of waiting for
the response. This makes the worker thread available for other requests. When the
watchdog receives the response, it informs the thread control components, which then
call a worker thread.

Signal Handler:
This thread processes signals sent from the operating system or from another process
(for example, the dispatcher).

Connection Info:
This table contains information about the state of the connection, the memory pipes, and
the plug-in data for every existing network connection.

Memory Pipes:
Memory pipes are memory-based communication objects that handle data transfer
between the ICM and the work processes. There are four pipes for every connection: one
data pipe per request and response and one out-of-band (OOP) pipe. The OOP pipe is
used for control information.

ICM Plug-Ins
The ICM contains plug-ins for the protocol-dependent tasks. The Internet protocols HTTP and
SMTP each have a plug-in. The plug-ins perform the following tasks:

All protocol-specific tasks

Input and output data handling, data manipulation

Local handling in the ICM or forwarding to the work process

The HTTP plug-in is described in more detail in HTTP Plug-In [page 24].
See also:
Logging in the ICM [page 63]
Binding Ports < 1024 on UNIX [page 51]
Internet Server Cache [page 34]
Parameterization of the ICM and the ICM Server Cache [page 45]
Monitoring the ICM with the ICM Monitor [page 68]
SAP Web Dispatcher [page 79]
Integration of the SAP J2EE Application Server [page 101]

Web Application Server

620 SP 9

23

SAP Online Help

25.10.2002

HTTP Plug-In
Definition
The HTTP plug-in handles HTTP requests and responses (see the graphic in the section
Structure of the ICM [page 22]). The URL and the port can be used to access a local handler
in the ICM. This increases system performance, as it renders it unnecessary to create a user
context in the work process for every request. The profile parameters are used to determine
which URL prefixes correspond to the various handlers. The handlers are called, and then
they either process the request themselves or forward it to the next handler.
See also: Parameterization of the ICM and the ICM Server Cache [page 45]

Structure
The following section describes the local handlers (subhandlers). They are called in the series
described below, provided that they are installed. Which subhandler generates the response
depends on how the profile parameters for the URL prefix of the request have been set. If a
subhandler created the HTTP response, the following subhandlers are no longer included in
the hierarchy. The exception to this is the logging handler, which executes HTTP logging and
then passes it on to the next subhandler.
1. Logging handler
This handler records HTTP requests. For a description of how to use it, see Logging
in the ICM [page 63].
2. Server cache handler
This handler reads and writes to the ICM Server Cache [page 34] and works as
follows:
a. Reads the request
b. If the requested object is in the cache, delivers the cache entry to the requesting
application.
c.

If the requested object is not in the cache, forwards the request to the next handler.

d. Stores the entry in the cache before sending the HTTP response to the client
3. File access handler
This handler returns a file from the file system (suitable for static files such as pictures
and HTML pages). Parameter icm/HTTP/file_access_<xx> [page 60] determines the
URL prefixes for which the static file access should be carried out.
4. Redirect handler
This handler forwards the HTTP request to another HTTP server (HTTP redirect).
Parameter icm/HTTP/redirect_<xx> [page 60] determines the ICM URL prefixes for
which the redirect should be executed.
5. SAP R3 handler
This handler forwards the request to the SAP System and waits for a response. This
is the default handler, that is, it processes a request if no other handler is processing
that request. A user context is created in the work process only if this handler is being
used.
6. J2EE handler
This handler passes the request to the integrated J2EE server (see also Integrating
the SAP J2EE Application Server [page 101]).

Web Application Server

620 SP 9

24

SAP Online Help

25.10.2002

Logging in the ICM


Use
The access log contains a log of accesses to the ICM from an intranet or the Internet, and
thus gives you an overview of the activity on the ICM.
You can use external analysis programs to analyze the log file.
A HTTP subhandler implements logging in the ICM. This subhandler statistically analyzes
HTTP requests and records requests.

The log handler uses the log file to serialize itself, which makes it a bottleneck. It
is therefore not usually activated.
The logging implementation procedure corresponds to the Apache Web Server
mod_log_config module.

Procedure
You configure logging using the parameter icm/HTTP/logging_<xx> [page 61].

Sample Log Entries for Default Format (CLF):


10.18.103.34 - - [08/Jan/2001:16:53:20 +0100] "GET
/sap/bc/bsp/sap/it00/default.htm HTTP/1.0" 200 336
10.18.103.34 - - [08/Jan/2001:17:01:15 +0100] "POST
/bc/bsp/sap/it00/transition_parameter.htm HTTP/1.0" 302 0
The following string creates the CLF format: %h %l %u %t "r" %s %b
Sample Log Entry for a Self-Defined Format
The following format
LOGFORMAT=%b %h %H %S %a %l %u %t %T Line=%r %f %U %s %{useragent}i
gives these kind of entries:
181 10.18.104.64 ls3022.wdf.sap-ag.de 8080 10.18.104.64 - [11/Apr/2001:14:01:08 +0200] 0 Line=GET /sap/bc/bsp/sap/it00
HTTP/1.1 /bc/bsp/sap/it00 /bc/bsp/sap/it00 500 Mozilla/4.0
(compatible; MSIE 5.01; Windows NT 5.0)

Binding Ports Lower Than 1024 on UNIX


Use
With the Internet Communication Manager (ICM) you can bind ports with numbers 0 up to and
including 1023 (well known ports) on Unix systems too. The external binding program
icmbnd included in the standard delivery is used for this.

Web Application Server

620 SP 9

25

SAP Online Help

25.10.2002

Usually the ICM itself binds the ports. If you want to use icmbnd to bind configured ports,
change the parameter specification for icm/server_port_<xx> [page 49] in the profile
(transaction RZ11).
icm/server_port_<xx> = PROT=<protocol>, PORT=<Port>, TIMEOUT=<timeout>,
EXTBIND=1

Integration
On Unix systems only users with superuser authorizations can bind ports with numbers lower
than 1024. For this reason either the ICM process must be provided with these authorizations,
or the port must be bound by an external program and then the listen socket transferred to the
ICM.

Prerequisites
For Release 6.10 you need a kernel patch level higher than 37. You can find out the patch
level of your kernel at operating system level using dw -V or icman -V.

Functions
For security reasons the ICM should run with the standard authorizations of the <sid>adm
SAP System user. With these authorizations all ports higher than 1023 can be bound,
provided they are not already bound by another program. To bind ports lower than 1024 the
ICM starts icmbnd directly, icmbnd binds the port, and the listen socket is forwarded to the
ICM. icmbnd must have the following superuser authorizations:
chown root icmbnd
chmod 4755 icmbnd

Activating External Binding


To ensure the ICM itself does not attempt to bind the port, you specify an additional option
when you are configuring ports with icm/server_port_<xx>: EXTBIND=1
The format of this parameter is:
PROT=<protocol name>, PORT=<port or service name> [, TIMEOUT=<keep alive timeout>,
EXTBIND=1]
TIMEOUT and EXTBIND are optional.

icm/server_port_1 = PROT=HTTP, PORT=8080, TIMEOUT=30,


EXTBIND=1

Usually icmbnd is called directly from the ICM, though the program can also be
called from external systems to make new ports known to the ICM. icmbnd can
also be used to bind ports >= 1024, but then the startup time of the ICM is longer.

icmbnd is also available for Windows NT. As the user <sid>adm can bind any
number of ports on this system, there is no need to use the icmbnd here.

Binding Program icmbnd


icmbnd is the ICM help program for binding ports.
Parameters
This program has the following parameters:

Web Application Server

620 SP 9

26

SAP Online Help

25.10.2002

Parameters

Description

Optional/mandatory

-S <server port>

ICM administration port via


which the listen socket of
icmbnd is transferred to the
ICM.

Mandatory

-l <listen port>

Port that is to be connected by


icmbnd. This can be a port
number or a port name (for
example, HTTP, SMTP,
NNTP).

Mandatory

-p <protocol>

Protocol specification for the


port you want to bound (for
example, HTTP, HTTPS,
SMTP).

Mandatory

-k <keep alive>

Specification of the keep alive


timeout (in seconds) for the
port you want to bind. If this
parameter is not specified, the
ICM standard value is used.

Optional

-t <trace level>

Specification of trace level (13). Standard value is 1.

Optional

-f <trace file>

Name of the trace file to be


used.
Standard value is
dev_icmbnd.

Optional

Error Messages
The following errors may occur and are logged by icmbnd:

Missing argument for option <option>


A required argument has not been entered in the command field.

Illegal option <option>


An invalid argument has been entered.

Missing values for service, listen port or protocol


One of the (mandatory) options -s -l or -p has not been specified.

IcmConnect to port %d failed (rc=%d)


A connection to the ICM to port number of argument S <server port> could not
be created. Please check the specification of parameter -S <server port>.

NiBuf2Listen failed(rc=%d)
The listen port could not be bound. Either the authorizations for binding ports are
missing or the port is already bound by a another program.

IcmBndSendHdl failed (rc = %d)

NiSendHandle failed (rc = %d)


The listen socket could not be transferred to the ICM (communication error).

See also:
For more information see the following pages:
chown, chmod, getuid, setreuid, seteuid, setfsuid

Web Application Server

620 SP 9

27

SAP Online Help

25.10.2002

Error Handling Using the ICM


If the ICM determines an error, in most cases it returns a static text to the browser:

You can also configure the ICM so that it returns dynamic error pages. The following section
describes how you do this.
The ICM recognizes the following errors.
Error Name

Meaning

ICMENOMEM

The SAP Web AS is out of memory to process the request

ICMETIMEOUT

The SAP Web AS did not return a response within a specified period
of time

ICMENOTAVAIL

A resource (file, service) is not available

ICMENOSESSION

The session for the session cookie no longer exists

ICMENOSSLREQ

SSL is expected on this port, no plaintext

Web Application Server

620 SP 9

28

SAP Online Help

25.10.2002

ICMEOVERLOAD

The SAP Web AS is overloaded and cannot accept any more


requests

ICMEPERM

Access is refused (for example, at the SAP Web dispatcher)

ICMEPROTERROR

HTTP protocol error (incorrect syntax, missing header fields,...)

ICMEINTERN

ICM internal error (unspecific)

For each of these errors, an HTML page can be created which is sent to the client when the
error occurs. You can define both static pages (ending .html) and dynamic pages (ending
.shtml).
If external resources (such as images) should be referenced in the error templates, these can
be delivered with the ICMs file access handler. See also icm/HTTP/file_access_<xx> [page
60].

Prerequisite for Using Your Own Error Pages


To use the ICMs dynamic error handling, you must set the profile parameter
icm/HTTP/error_templ_path to the directory with the error template files: For example:
icm/HTTP/error_templ_path = /usr/sap/B6M/D13/data/icmerror

Static Error Pages


If a static error page is defined for an error (ending .html), this is returned to the client.

Dynamic Error Pages


The dynamic pages support the following SSI commands (server-die includes, see
http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html).

For the dynamic substitutions, the whole file must be searched for the SSI tags
"<!--". The effort required to do this is related to the size of the file. The dynamic
pages cannot be stored in the cache either.
The following section explains the SSI commands that are supported.

ECHO
<!--#echo var="variable" -->
You can set the following variables:
Variable Name

Meaning

DATE_LOCAL

Current time/date: Tue Mar 26 17:15:32 2002

DATE_GMT

Current GMT time/date: Tue Mar 26 17:15:32 2002

LAST_MODIFIED

The time when the current file was last modified

FILE_SIZE

Size of the current file in Bytes

SERVER_SOFTWARE

SAP Web Application Server 6.30

SERVER_NAME

The name of the server

SERVER_PORT

The server port

PATH_TRANSLATED

URL path (without parameters)

ICM_SERVER

Host name and port through which this server can be reached.
For example: Is3022.wdf.sap-ag.de:1080

Web Application Server

620 SP 9

29

SAP Online Help

25.10.2002

ICM_INSTANCE

Instance name: ls3022_BIN_12

ICM_ERR_CODE

Error that occurred (numeric)

ICM_ERR_VERSION

ICM version

ICM_ERR_COMPONENT

Component

ICM_ERR_MODULE

Module name

ICM_ERR_LINE

Line

ICM_ERR_DETAIL

Detail on the error that occurred

Not all fields are available for all errors.


With error ICMEOVERLOAD, for example, the request has not yet been read,
which is why field PATH_TRANSLATED has not been set.

In your page you can write, for example:


<tr><td>Server:</td><td><!--#echo var="ICM_SERVER" -></td></tr>
</tr><tr><td background="http://<!--#echo var="ICM_SERVER"
-->/images/graybar_tile.jpg" height="31">

INCLUDE
You can use this command to include a different file at this point.
<!--#include file="file name" -->

Your error page can be framed, for example, by the two INCLUDE statements:
<!--#include file="header.html" -->
...
<!--#include file="footer.html" -->

The file must not include itself! Recursive inclusion causes the ICM to terminate.

You can find an example of a dynamic error page and the .shtml file in Examples of a
Dynamic Error Page [page 31].

Prioritizing Using the ICM


If parameter icm/HTTP/error_templ_path is not set, the ICM static error page is always
returned.
If parameter is set, when error <ERRNAME> occurs, the ICM first checks whether file
<ERRNAME>.html is located in the directory specified by icm/HTTP/error_templ_path,
and sends it to the client. If it cannot find this file, it searches for <ERRNAME>.shtml and
returns it.
If neither file is available for an error, the static page is returned (see above).

Web Application Server

620 SP 9

30

SAP Online Help

25.10.2002

Updating Error Pages


For reasons of performance, the ICM checks once the error templates that are available. This
is why you must restart the ICM if you add new templates (changes to the templates are
recognized). You can use the ICM Monitor to restart it (Transaction SMICM) (see Monitoring
the ICM Using the ICM Monitor [page 68]).

Examples of a Dynamic Error Page


A dynamic error page could look as follows:

Web Application Server

620 SP 9

31

SAP Online Help

25.10.2002

File ICMERR-ENOSESSION.shtml would then look as follows:


<html><head><title>SAP Web Application Server Error</title>
<style type="text/css">
body { font-family: arial, sans-serif;}

Web Application Server

620 SP 9

32

SAP Online Help

25.10.2002

</style>
</head>
<BODY text="#172972" link="#808080" vlink="#808080"
alink="#8e236b" bgcolor=white

leftmargin="0" topmargin="0"

marginheight="0" marginwidth="0">
<table height="61" width="100%" border="0" cellspacing="0"
cellpadding="0"><tr><td background="http://<!--#echo var="ICM_SERVER" ->/sap/public/icman/img/bluebar_tile.gif"
height="30"><table> <tr> <td width=5></td> <td width=20% nowrap><font
face=arial size="-1" color=white>SAP Web Application Server
</font></td><td width=75% align="right" nowrap><font face=arial
size="-1" color="white"><a href="http://help.sap.com/">Help
</font></td><td width=5% nowrap></font></td> </tr></table>
</td><td rowspan=2 width=122 height=61 valign=top><img src=
"http://<!--#echo var="ICM_SERVER" -->/sap/public/icman/img/theme.jpg"
width=122 height=61 border=0 alt="SAP"></td>
</tr><tr><td background="http://<!--#echo var="ICM_SERVER" ->/sap/public/icman/img/graybar_tile.jpg" height="31">
&nbsp;</td></tr>
</table>
<br><br>
<table width=100%>
<tr><td width=50 nowrap>
</td><td>
<H3><b>400 Session timed out - please log in again
</b></H3><hr><p>Application Server Session timed out (-11)</p>
<hr>
<p>
<b>Note:</b>
<br>
The SAP Web Application Server uses sessions which are terminated
automatically
after a defined time interval without input. Please repeat your last
action.
If you have been logged on, you have to log on again due to security
reasons.
</p>
<hr><!-- Comment -->
<br>
<table border="0">
<tr><td>Error:</td><td><!--#echo var="ICM_ERR_CODE" --></td></tr>

Web Application Server

620 SP 9

33

SAP Online Help

25.10.2002

<tr><td>Version:</td><td><!--#echo var="ICM_ERR_VERSION" --></td></tr>


<tr><td>Component:</td><td><!--#echo var="ICM_ERR_COMPONENT" -></td></tr>
<tr><td>Module:</td><td><!--#echo var="ICM_ERR_MODULE" --></td></tr>
<tr><td>Line:</td><td><!--#echo var="ICM_ERR_LINE" --></td></tr>
<tr><td>Server:</td><td><!--#echo var="ICM_INSTANCE" --></td></tr>
<tr><td>Detail:</td><td><!--#echo var="ICM_ERR_DETAIL" --></td></tr>
<tr><td>Server Software:</td><td><!--#echo var="SERVER_SOFTWARE" -></td></tr>
<tr><td>Server:</td><td><!--#echo var="ICM_SERVER" --></td></tr>
<tr><td>Server Name:</td><td><!--#echo var="SERVER_NAME" --></td></tr>
<tr><td>Server Port:</td><td><!--#echo var="SERVER_PORT" --></td></tr>
<tr><td>Path translated:</td><td><!--#echo var="PATH_TRANSLATED" -></td></tr>
<tr><td>Last modified:</td><td><!--#echo var="LAST_MODIFIED" -></td></tr>
<tr><td>File size:</td><td><!--#echo var="FILE_SIZE" --></td></tr>
<tr><td>Local Time:</td><td><!--#echo var="DATE_LOCAL" --></td></tr>
<tr><td>GMT Time:</td><td><!--#echo var="DATE_GMT" --></td></tr>
</table>
</td></tr></table>
<p></p>
<!--#include file="footer.html" -->
</BODY>

Internet Server Cache


Uses
The ICM server cache or ICM server cache saves HTTP(S) objects before they are sent to
the client. The next time an object is requested, then, the application gets the content directly
from the cache before sending it to the client.
The HTTP request handler uses the ICM Server Cache when, for example, response pages
need to be re-used, such as the entry page of an online shop application. The ICM server
cache saves the pages before they are sent to the client. When the page is next called, then
the application gets the page directly from the ICM and sends it to the client (provided that the
expiry period has not run out) (see icm/HTTP/server_cache_<xx>/expiration [page 65]), and
the work process does not have to be opened (see Interaction Model [page 108]).

Web Application Server

620 SP 9

34

SAP Online Help

25.10.2002

Objects in the MIME repository are saved to the cache by default. Method calls
are used to activate the ICM server cache. This is described later.

Introductory Comments
Using the ICM server cache can create considerable increases in performance.
Benchmarking tests for cache hits in the main memory have resulted in latent response times
of less than one millisecond per request, and a total run of under 3,000 requests per second
on a 4 CPU hardware.
These results are based on a strong parallel and multithreaded architecture that supports
simultaneous read and write accesses with versioning. Furthermore, a patented indexing
algorithm is used to access the cache directory quickly. This algorithm is particularly suitable
for long Web URLs as cache keys.

Integration
The ICM server cache is part of the Internet Communication Manager (ICM) [page 22].

Functions
The following graphic displays the architecture of the ICM server cache.
SAP Web AS
Dispatcher

ICM
ISC

Workprozess
Disk Cache

Memory
Cache

UFO Cache

zum
Client

ICM
Worker-Thread

MPI

BSP-Engine

< 1 ms
5 ms

Latenzzeiten fr Response-Requests
20-2000 ms

The ICM server cache contains the following:

Two-level cache hierarchy: Memory cache and disk cache

Dynamic caching technology

Active caching

UFO caching (unfound objects)

Browser-dependent caching

Two-level Cache Hierarchy


The ICM Server Cache [page 34] consists of a two-level hierarchy: A very fast main memory
repository (Memory Cache) built on a disk-drive-based Disk Cache. This has the advantage

Web Application Server

620 SP 9

35

SAP Online Help

25.10.2002

that both the speed of the main memory access and the large storage capacity of the hard
disk repository can be used.

Dynamic caching technology


Conventional Web-caching scenarios are based on HTTP proxies and usually only support
caching of static contents, such as GIF pictures. The Internet server cache, on the other
hand, can store dynamic Web content as well as static content, such as JSP and BSPs. This
is especially important as Web applications are becoming increasingly dynamic.

Active caching
An additional difference between the existing standard Web caching solutions and the
Internet server cache consists of the cache control technology, which is integrated in the
Internet Communication Framework [page 106] and in the BSP programming model [page
197].
Active caching means that the application has full control over how current the objects are
that are in the cache. This happens by using asynchronous content invalidation, which is
triggered by application-dependent events. Even this is contrary to the standard HTTP
caching, with which the application only has limited control over how current the objects in the
cache actually are. With the standard HTTP caching technology, expiry time heuristics are
usually used.

UFO Caching
The Internet server cache supports caching invalid requests. These are requests that lead to
errors on the application server or on the database backend, such as not found errors. As a
result, the backend is protected from overload situations in which the system is flooded with
invalid Web requests.

Note that this function is only used as general protection and cannot protect the
system from more polished attacks.
UFO caching can also cause the server to behave unexpectedly (HTTP polling).

Browser-dependent caching for BSPs


A Business Server Page may appear differently in different browsers, since the HTML code is
not always interpreted in the same way.
This is why the ICM server cache can store BSPs according to the browser type. If the same
page is requested by a different browser, the request cannot be retrieved from the cache. To
inform the runtime environment if the content is browser-dependent, you can set the relevant
flag in the BSP properties. By default the flag is not set.
See Caching BSPs [page 403].

How Does the ICM Server Cache Work?


The following documentation describes how the cache identifies objects, stores and
invalidates them.

Cache Key [page 37]

Identifying Objects [page 38]

Manipulating Cache Properties [page 39]

Invalidating Objects in the Cache [page 39]

Storing Data Objects in the ICM Server Cache [page 41]

Search Sequence in the ICM Server Cache [page 40]

Web Application Server

620 SP 9

36

SAP Online Help

25.10.2002

Profile Parameters for Configuring the ICM Server Cache


The following parameters are used to parameterize the ICM Server Cache:

icm/HTTP/server_cache_<xx> [page 64]

icm/HTTP/server_cache_<xx>/size_MB [page 66]

icm/HTTP/server_cache_<xx>/memory_size_MB [page 67]

icm/HTTP/server_cache_<x>/max_entries [page 65]

icm/HTTP/server_cache_<xx>/clear [page 65]

icm/HTTP/server_cache_<xx>/expiration [page 65]

icm/HTTP/server_cache_<xx>/max_name_len [page 66]

icm/HTTP/server_cache_<xx>/ufo_list [page 67]

icm/HTTP/server_cache_<xx>/max_ufo_entries [page 66]

icm/HTTP/server_cache_<xx>/ufo_expiration [page 68]

You can monitor the ICM Server Cache from the system using the ICM monitor. This is
described in Monitoring and Administrating the ICM Server Cache [page 73].

Cache Key
Definition
The cache key is the unique key that can be used to identify objects in the ICM server cache.

Structure
The cache key depends directly on the request URI.

Web Application Server

620 SP 9

37

SAP Online Help

25.10.2002

The following graphic displays how the cache key is generated from the request URI.

Syntax of the Cache Key


Query String with PseudoQuery Parameters

Request URI

http://myhost.wdf.sap-ag.de/
sap(bD1kZQ==)/bc/bsp/bookstore.bsp?author=knuth&year=1972&uagent=IE

HASH
translated path
SAP
Language

SAP
Theme

/sap/bc/bsp/bookstore.bsp&en&SAP_DEFAULT&AC13FFD45E
Cache Key

The URL path is translated, that is, the encoded information about the SAP language and
SAP theme, separated by & symbols, is added after the ICF path. This is then followed by
another & symbol and the query string with the pseudo query parameters. To restrict the
length of this string, a hash process is used on the query string.
See also:
Identifying Objects [page 38]

Identifying Objects
The following identify an object that is intended to be stored, manipulated, or invalidated in the
cache:

The fully specified Cache Key [page 37], which consists of the URL and the various
context-dependent fields, such as SAP language and SAP theme

/sap/bc/bsp/sap/public/bc/bsp/styles/sapbsp.css&de&&A6E90000
&

Although the application can identify objects using the cache key, this is not
recommended. Use the following methods that are described using the URL
prefix or e-tag.

A wildcard pattern <prefix>*, which selects all objects with a matching <prefix>

/sap/bc/bsp/sap/public/bc/bsp/styles/*

Web Application Server

620 SP 9

38

SAP Online Help

25.10.2002

The E-tag [External documentation], that is, a unique key (GUID) that is assigned to an
object when that object is created To create a unique GUID for your object, you can use
the ABAP function module GUID_CREATE.

The e-tag is required so that logically identical objects that are physically stored a
number of times under different URLs (but with the same e-tags) can be
identified. When the object is being invalidated, then, the application uses the etag to access all copies of the object simultaneously.

The e-tag is not automatically assigned to every object by the system (such as
the cache key), but is a GUID that the application programmer can assign if he or
she wants to access this object at a later date (to invalidate it, for instance).

Manipulating Cache Properties


Use
The Internet Communication Framework [page 106] is used to set the cachability, the
validity period, and the ETag [External documentation] of an existing object when the HTTP
response is being created.

Procedure
Use the following methods of the class IF_HTTP_RESPONSE [page 119] to set the cache
properties for an object.
SERVER_CACHE_EXPIRE_ABS
You use this method to set the expiration period for the ICM Server Cache. An absolute date
and time are given. The page contained in the cache is invalid after this date and time. The
input parameters for this method are an absolute date, time, and the ETag of the object in
question (optional).
SERVER_CACHE_EXPIRE_REL
Sets a relative expiration period (in seconds) for the ICM server cache The input parameters
are the seconds (from the current time) and the ETag (optional).
SERVER_CACHE_EXPIRE_DEFAULT
Activates the ICM server cache and sets the default expiry period.

Invalidating Objects in the Cache


Use
You must make it possible to invalidate an object in all the ICM Server Caches it is located in
in the SAP System. This may be necessary if, for example, a picture in the MIME repository
has changed.

Web Application Server

620 SP 9

39

SAP Online Help

25.10.2002

If an object has to be invalidated, all servers in the system must be notified by RFC that this
object is no longer up to date and should be invalidated. The next time the object is
requested, the up-to-date version of it must be re-loaded into each cache.
For a description of how to identify cache objects that have to be invalidated, see Identifying
Objects [page 38].

Procedure
You invalidate objects using method calls from the application (BSP application, HTTP
request handler) or from the system (ICM monitor).

Invalidation using Method Calls


To invalidate objects in the cache, you can use the following static methods of the class
CL_HTTP_SERVER. You can call the methods from your application.
SERVER_CACHE_INVALIDATE
Invalidates the object specified in the ICM Server Cache. This method has the following input
parameters:

The ID of the object to be invalidated

The ID type

The scope (local or global invalidation)

SERVER_CACHE_INVALIDATE_LIST
Invalidates a specified list of objects in the cache. The input parameters are a list of IDs and
scope.
SERVER_CACHE_INVALIDATE_ALL
Invalidates all objects in the ICM Server Cache.

Invalidation from the ICM Monitor


You can also invalidate individual entries or the entire cache from the ICM Monitor
(transaction SMICM). This is described in Monitoring and Administrating the ICM Server
Cache [page 73].

Search Sequence in the ICM Server Cache


When the ICM Server Cache (ISC) is being searched for a requested object, the following
steps are taken, in this order:

The application first checks the UFO List [External documentation] (provided that this is
active, see parameter icm/HTTP/server_cache_<xx>/ufo_list [page 67]), to establish
whether this request has already been rejected by the system, and whether it should be
rejected on this occasion.

The application then looks in the Main Memory of the ICM server cache (Memory Cache),
and icm/HTTP/server_cache_<xx>/memory_size_MB [page 67] establishes the size of
the part of the ISC in main memory.

The application then looks for the object in the File on the hard disk that the ISC is using
(Disk Cache). The parameter icm/HTTP/server_cache_<xx>/size_MB [page 66]
establishes the total size of the ISC (a part of which is instantly accessible as it is stored
in main memory).

See also:
Web Application Server

620 SP 9

40

SAP Online Help

25.10.2002

Cache Key [page 37]


Identifying Objects [page 38]

Storing Data Objects in the ICM Server Cache


Use
When programming your Web application, you can store large data BLOBs (binary large
objects) in the ICM server cache before requesting the page for a first time. As a result you
can avoid long wait times with the first call, since the object does not have to be fetched from
the database (MIME repository).

Procedure
Within your application (HTTP request handler or BSP application), call method
SERVER_CACHE_UPLOAD of class CL_HTTP_SERVER (compare the section about the
IF_HTTP_SERVER [page 117] interface). It is processed exactly as described in using the
ICM server clipboard [page 44].

Result
Your data BLOBs are in the ICM server cache before the browser requests them for the first
time. As a result, the response is quick and does not affect the backend (application server
and database).

Caching BSPs
Use
With the Internet Server Cache (see also ICM Server-Cache [page 34]) you can considerably
increase the performance and scalability of your BSP application. The ICM server cache
provides a dynamic and active content caching technology, resulting in the following
advantages for developing BSPs:

The resources required for creating BSPs are reduced

You do not have to repeatedly execute BSPs that are frequently requested

The possible performance improvements can be up to factor 20.

Performance and Scalability


Benchmarking tests for cache hits in the main memory have resulted in latent response times
of less than one millisecond per request, and a total run of under 3,000 requests per second
on a 4 CPU hardware.
These results are based on a strong parallel and multithreaded architecture that supports
simultaneous read and write accesses with versioning. Furthermore, a patented indexing
algorithm is used to access the cache directory quickly. This algorithm is particularly suitable
for long Web URLs as cache keys.

Web Application Server

620 SP 9

41

SAP Online Help

25.10.2002

Functions
The features and the architecture of the ICM server cache are described in Internet Server
Cache [page 34].
You have the following options to control BSP caching:

In the Web Application Builder (Transaction SE80), you can set the following properties
for caching on the Properties tab page:

Expiry date for caching in the Internet server cache

Expiry date for caching in the browser (client-side)

Flag whether page caching should be browser-dependent

In your BSP application you can control the behavior of the ICM server cache using
response object method calls.

The following section describes how you should proceed.

Activities
Setting Caching Properties in the Web Application Builder

You can set the caching properties for the page on the Properties tab page of a BSP:
For both the browser cache and the ICM server cache you can determine how long the page
should be held in the cache. If you do not enter any data, this means that the cache is not
used for the page. Set flag Browser Dependent if you want the ICM server cache to fetch the
page from the cache only if the request comes from the same browser type. If you do not set
the flag, note that all of the elements used by the page must not be browser-dependent.

Note that when you use the browser cache, the client cannot tell when a page
has changed. If the URL is the same, it always returns the same page from the
cache until the expiry date has passed. If you use the ICM server cache, by
using the invalidation methods you can ensure that the page stored in the cache
is up-to-date.

Setting Caching Properties Using Method Calls in the BSP


You have several options here. In addition to the relative expiry date and browserdependency, you can specify a final expiry date and invalidate cache entries. You can also
activate caching not just for the page in general, but also according to user input.
Set the expiry time for an HTTP response with the methods of class CL_HTTP_RESPONSE
(see also IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]):

SERVER_CACHE_EXPIRE_ABS

SERVER_CACHE_EXPIRE_REL

Web Application Server

620 SP 9

42

SAP Online Help

25.10.2002

Use appropriate automatic expiry times. For example, a banner displaying stock
market tickers is updated every n minutes, whilst a product catalog should be
updated only every n days or weeks.
You refresh (invalidate) objects asynchronously using the methods of class
CL_HTTP_SERVER (see also IF_HTTP_SERVER [page 117]):

You can use method SERVER_CACHE_INVALIDATE() to invalidate an individual object


that can be identified by the following data:

Complete name, that is, URI path, form fields and BSP application context

Prefix of the name (hierarchical wildcards)

E-tag, that is, the entity tag and the unique ID that was assigned at the time of
creation

You can use method SERVER_CACHE_INVALIDATE_LIST() to invalidate a list of


objects (internal tables).

The system automatically forwards this data to other application servers, thus ensuring cache
integrity.

You should avoid too frequent invalidations, so that system-wide transfers to


other application servers are avoided.
See also:
Manipulating Cache Properties [page 39]

Example
You can find a simple example in the system in BSP application TUTORIAL_4, BSP
results.htm in the event handler OnInitialization:
* cache result page in case Plattner's books are searched
if

'PLATTNER' cp author.

response->server_cache_expire_abs( expires_abs_time

= '180000'

browser_dependent = 'X' ).
endif.
The result list for querying the books from Hasso Plattner is only stored in the cache because
you know that these are requested especially often. The cache entry is invalidated every night
at 18.00. This function may be useful for things that must be recalculated every day (such as
current prices).
See also:
Further Developing the Online Bookshop [External documentation]

Web Application Server

620 SP 9

43

SAP Online Help

25.10.2002

ICM Server Clipboard


Definition
The ICM server clipboard is a service that is used to temporarily store data BLOBs (binary
large objects). If these are then requested in an HTTP request, they can be provided very
quickly.

Use
In addition to the ICM Server Cache [page 34] there is also the server clipboard in the ICM.
The data BLOBs that are stored in the ICM server clipboard are assigned a key that enables
them to be retrieved later in sequence requests. The same technology is used as that in the
ICM server cache, thus ensuring high performing access.
If you want to store objects in the ICM server clipboard within the framework of your Internet
application, you can use the method SERVER_CACHE_UPLOAD of class CL_HTTP_SERVER to
do this. This is described below.

The ICM clipboard should be used to store objects temporarily! You cannot
assume that the objects will still be available at a much later date!

Structure
The HTTP Request Handler [page 107], that wants to use this functionality creates a
temporary response object for each BLOB (GIF images, for example) that is embedded in the
output page. With the help of the class constructor, an empty response object is created,
which is then filled with contents using standard methods such as APPEND_DATA() (see also
IF_HTTP_ENTITY [page 121]). In this way, additional attributes such as the cache retention
period, compression and so on can be set using known methods (SERVER_CACHE_EXPIRES,
SET_COMPRESSION and so on).
Objects that were generated using SERVER_CACHE_UPLOAD can be uploaded to the server
clipboard using a uniquely assigned URL. At the same time, the links in the current output
page to the URLs that are assigned each time the SERVER_CACHE_UPLOAD is called are
serialized in the HTML data stream. Method SERVER_CACHE_UPLOAD has the following
import parameters:

URL: The URL under which the BLOB is stored in the ICM server cache.

Response: Reference to the response object

Scope: Specifies whether the data that should be stored locally in the cache of the
current ICM belongs to the current SAP Web AS, or if it should be stored globally in the
caches of all ICMs that belong to the system. The default is local.

The requests on the embedded objects in this page are therefore handled in the sequence in
which they are generated by the HTTP client (browser) from the ICM server clipboard.
See also:
IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]
Internet Communication Framework [page 106]

Integration
The ICM server cache is used. If an object is stored in the ICM server clipboard, it is located
in a special part of the ICM server cache. In contrast to normal cache entries, you must
ensure that the object is located in the clipboard. In the case of a cache miss, it cannot be
fetched from the server.

Web Application Server

620 SP 9

44

SAP Online Help

25.10.2002

Example
An application contains a personalized list that contains a lot of memory-intensive graphics.
They should be displayed after you have logged on, but it should not take a long time to
generate them. The application must be programmed in such a way that the data is stored in
the ICM clipboard server before the page should be generated.
A sample application is embedding XML/XSL documents. This function is not directly
supported by all browsers.

Parameterizing the ICM and the ICM Server Cache


Use
This section explains the profile parameters relevant to the operation of the ICM and the ICM
server cache.
You can display most of these parameters in the ICM monitor and change some of them
dynamically. To do this, on the initial screen choose Transaction SMICM Goto Parameters
Display or Change. On the Change screen you can go directly to the RZ11 parameter
documentation for the individual parameters.

You can find an example of the setting of the ICM parameter in the instance
profile in Sample Profile for the ICM [page 46].

ICM Parameters
exe/icman [page 49]
rdisp/start_icman [page 49]
icm/plugin_<xx> [page 49]
icm/server_port_<xx> [page 49]
icm/HTTP/j2ee_<xx> [page 53]
icm/host_name_full [page 54]
icm/min_threads [page 54]
icm/max_threads [page 54]
icm/req_queue_len [page 56]
icm/listen_queue_len [page 56]
icm/max_conn [page 57]
icm/max_sleep [page 57]
icm/accept_remote_trace_level [page 58]
icm/ccms_monitoring [page 58]

HTTP Subhandler Parameters


icm/HTTP/file_access_<xx> [page 60]
icm/HTTP/logging_<xx> [page 61]
icm/HTTP/redirect_<xx> [page 60]
Web Application Server

620 SP 9

45

SAP Online Help

25.10.2002

icm/HTTPS/verify_client [page 64]

ICM Server Cache Parameters


icm/HTTP/server_cache_<xx> [page 64]
icm/HTTP/server_cache_<x>/max_entries [page 65]
icm/HTTP/server_cache_<xx>/clear [page 65]
icm/HTTP/server_cache_<xx>/expiration [page 65]
icm/HTTP/server_cache_<xx>/max_name_len [page 66]
icm/HTTP/server_cache_<xx>/max_ufo_entries [page 66]
icm/HTTP/server_cache_<xx>/size_MB [page 66]
icm/HTTP/server_cache_<xx>/memory_size_MB [page 67]
icm/HTTP/server_cache_<xx>/ufo_list [page 67]
icm/HTTP/server_cache_<xx>/ufo_expiration [page 68]

Memory Pipes Parameter


Memory Pipes [page 68]

Timeout Handling Parameters


These parameters are used internally for optimizing the I/O throughput (network/MPI).
icm/keep_alive_timeout [page 58]
icm/conn_timeout [page 58]
icm/wp_mpi_available [page 59]
icm/wp_roll_timeout [page 59]

The profile parameters are usually also described and documented in the system
(transaction RZ11).

Sample Profile for the ICM


The following section specifies a few sample profiles of the SAP Web Application Server. It
displays only those parts that are relevant for the ICM and the ICM server cache.
You can transfer the following parameter values directly into the instance profile of a SAP
Wen Application Server.

Application Server with HTTP, HTTPS and SMTP Access


If you want to configure the SAP Web Application Server for HTTP, HTTPS and SMTP, add
(for example), the following lines to your instance profile.
# Port Definition
icm/server_port_0

= PROT=HTTP, PORT=1080

icm/server_port_1

= PROT=HTTPS, PORT=1443

icm/server_port_2

= PROT=SMTP, PORT=1025

Web Application Server

620 SP 9

46

SAP Online Help

25.10.2002

# Parameter Values for SSL Support


sec/libsapsecu

= $(DIR_EXECUTABLE)/libsapcrypto.so

ssl/ssl_lib

= $(DIR_EXECUTABLE)/libsapcrypto.so

See also:
icm/server_port_<xx> [page 49]

Application Server with an Anticipated Small Load


If the anticipated load for the ICM is low, you can keep the number of threads small.
# Number of usable threads
icm/min_threads

= 10

icm/max_threads

= 10

See also:
icm/min_threads [page 54]
icm/max_threads [page 54]

Application Server with a High Expected Load


If you anticipate too much load for your SAP Web Application Server, you can set the
following parameters to large values.
# Number of usable threads
icm/min_threads

= 50

icm/max_threads

= 100

# Increase the size of the MPI memory area


mpi/total_size_MB

= 80

# Number of maximum connections, length of the wait queue


icm/max_conn
icm/req_queue_len

= 1000
= 250

See also:
Memory Pipes [page 68]
icm/max_conn [page 57]
icm/req_queue_len [page 56]

Binding Ports Lower Than 1024 on UNIX


If you want to bind ports less than 1024 on UNIX, you can use the external additional program
icmbnd. For more information, see Binding Ports Lower Than 1024 on UNIX [page 51].
# Use default ports
# icmbnd must have superuser authorizations:
# "chown root icmbnd" and "chmod 4755 icmbnd
icm/server_port_0

= PROT=HTTP, PORT=80, EXTBIND=1

icm/server_port_1

= PROT=HTTPS, PORT=443, EXTBIND=1

icm/server_port_2

= PROT=SMTP, PORT=25, EXTBIND=1

See also:
icm/server_port_<xx> [page 49]

Web Application Server

620 SP 9

47

SAP Online Help

25.10.2002

Activating the HTTP Logfile


Working with an HTTP logfile is described in Logging in the ICM [page 63]. In the following
example, the file is rewritten every month.
# HTTP logfile: The file is rewritten when the file size is 4MB and
# at the start of each new month
icm/HTTP/logging_0

= PREFIX=/, LOGFILE=access_log,
MAXSIZEKB=4000, SWITCHTF=month, FILEWRAP=on

See also:
icm/HTTP/logging_<xx> [page 61]

Activating the SAP J2EE Application Server


The SAP J2EE Application Server is integrated into SAP Web Application Server Release
6.20, although it is not started automatically. In the following example, the parameters are set
so that the J2EE server is started automatically. For more information, see Integration of the
SAP J2EE Application Server [page 101].
# J2EE server should be automatically started by the dispatcher
rdisp/j2ee_start = 1
# J2EE server is running on the local host with port 33000,
# maximum 20 parallel connections
icm/HTTP/j2ee_0 = PREFIX=/, HOST=localhost, PORT=33000, CONN=0-20
See also:
icm/HTTP/j2ee_<xx> [page 53]

Web Application Server

620 SP 9

48

SAP Online Help

25.10.2002

exe/icman
This parameter sets the name of the Internet Communication Managers (ICM).
Default setting:
UNIX: /usr/sap/<SID>/SYS/exe/run/icman
NT :

\\<SAPGLOBALHOST>\sapmnt\<SID>\SYS\exe\run\icman.exe

rdisp/start_icman
For an application server to directly process external processes such as HTTP, the ICM must
be started. The parameter rdisp/start_icman is used to control the ICM startup:

rdisp/start_icman = true
ICM started

rdisp/start_icman = false
ICM not started

Default setting:
true

icm/plugin_<xx>
This parameter is used to specify the protocols supported by the ICM.
<xx> must be specified in ascending order from 0. A protocol is specified by the name of the
protocol (for example, HTTP, HTTPS) and a shared library (plug-in) for the protocol. The plugin can be associated with the parameter icm/server_port_<xx> [page 49] at one or several
ports.
Value Range

Unit

Character string in the form PROT=<protocol


name>, PLG=<filename of plug-in>.

Character string

Default Setting

PROT=HTTP,
PLG=$(DIR_EXECUTABLE)/httpplugin.so
PROT=SMTP,
PLG=$(DIR_EXECUTABLE)/smtpplugin.so

icm/server_port_<xx>
Use
You can use this parameter to specify the service/port that is to be used for a protocol. Either
the service name or the port number can be specified.

Web Application Server

620 SP 9

49

SAP Online Help

25.10.2002

You can also determine additional service properties. This is described in the procedure
below.

Prerequisites
A plug-in for the protocol must be specified in the parameter icm/plugin_<xx> [page 49], as
otherwise the service cannot be started. There cannot be more than one service allocated to
a single port. Also, a service cannot be started if another program is using the port or service.

Procedure
The protocol that is used and the service name or the port number must be specified.
Additional optional input is described below.

Timeout
If there is no activity on an active connection for more than a certain length of time, the
connection is terminated (see also icm/keep_alive_timeout [page 58]). The time period is
specified (in seconds) using the third parameter value <keep alive timeout>. A timeout
cannot have the value -1.
Value Range

Unit

Default Setting

10 - 32000

Seconds

30

The time limit applies in the following cases:

In the case of requests, the time between receipt of the TCP packets

The time between acknowledgments (responses sent by the server) of TCP packets

Depending on the type of network connection (internal, LAN, WAN, and so on), it can make
sense to increase the parameter values. However, the value should not be less than 10
seconds. If, on the other hand, a value is too high, the network connections will be very slow
and the performance of the server will suffer.

Using an External Binding Program


For connecting ports < 1024 to UNIX this parameter is extended by specifying EXTBIND=1
(optional) (see Connecting Ports < 1024 on UNIX [page 51]).

Not Binding the Port to all Host Names


You can use the optional parameter HOST=<host name or IP address> to specify that
the port should not be bound to all host names (default), but only to the specified host.

X.509 Certificate
Using the optional parameter VCLIENT you can specify whether the client should have an
X.509 certificate when you use SSL. There are three certification levels (0-2):

0: No certification is required and the server does not ask for one.

1: The server asks the client to produce a certificate. If the client does not send a
certificate, authentication is carried out by another method, for example, basic (default
setting).

2: The client must transfer a valid certificate to the server, otherwise access is denied.

This server-specific value overrides the value that is set with parameter
icm/HTTPS/verify_client [page 64].
Value Range

Unit

Default Setting

Character
string

PROT=<Protocol name>, PORT=<Port or service

Web Application Server

620 SP 9

50

SAP Online Help

25.10.2002

name>[, TIMEOUT=<keep alive timeout,


EXTBIND=1, HOST=<Host name>, VCLIENT=<SSL
Client verification>]

PROT=HTTP, PORT=8080, TIMEOUT=15


PROT=SMTP, PORT=80, TIMEOUT=45,
EXTBIND=1, HOST=prd.sap.de
PROT=HTTPS, PORT=443, TIMEOUT=15,
VCLIENT=0

For Binding Ports < 1024 on UNIX [page 51] this parameter looks like:
icm/server_port_<xx> = PROT=<Protocol>, PORT=<Port>,
[TIMEOUT=<timeout>,] EXTBIND=1 [, HOST=<Host name>]

Binding Ports Lower Than 1024 on UNIX


Use
With the Internet Communication Manager (ICM) you can bind ports with numbers 0 up to and
including 1023 (well known ports) on Unix systems too. The external binding program
icmbnd included in the standard delivery is used for this.
Usually the ICM itself binds the ports. If you want to use icmbnd to bind configured ports,
change the parameter specification for icm/server_port_<xx> [page 49] in the profile
(transaction RZ11).
icm/server_port_<xx> = PROT=<protocol>, PORT=<Port>, TIMEOUT=<timeout>,
EXTBIND=1

Integration
On Unix systems only users with superuser authorizations can bind ports with numbers lower
than 1024. For this reason either the ICM process must be provided with these authorizations,
or the port must be bound by an external program and then the listen socket transferred to the
ICM.

Prerequisites
For Release 6.10 you need a kernel patch level higher than 37. You can find out the patch
level of your kernel at operating system level using dw -V or icman -V.

Functions
For security reasons the ICM should run with the standard authorizations of the <sid>adm
SAP System user. With these authorizations all ports higher than 1023 can be bound,
provided they are not already bound by another program. To bind ports lower than 1024 the
ICM starts icmbnd directly, icmbnd binds the port, and the listen socket is forwarded to the
ICM. icmbnd must have the following superuser authorizations:
chown root icmbnd
chmod 4755 icmbnd

Web Application Server

620 SP 9

51

SAP Online Help

25.10.2002

Activating External Binding


To ensure the ICM itself does not attempt to bind the port, you specify an additional option
when you are configuring ports with icm/server_port_<xx>: EXTBIND=1
The format of this parameter is:
PROT=<protocol name>, PORT=<port or service name> [, TIMEOUT=<keep alive timeout>,
EXTBIND=1]
TIMEOUT and EXTBIND are optional.

icm/server_port_1 = PROT=HTTP, PORT=8080, TIMEOUT=30,


EXTBIND=1

Usually icmbnd is called directly from the ICM, though the program can also be
called from external systems to make new ports known to the ICM. icmbnd can
also be used to bind ports >= 1024, but then the startup time of the ICM is longer.

icmbnd is also available for Windows NT. As the user <sid>adm can bind any
number of ports on this system, there is no need to use the icmbnd here.

Binding Program icmbnd


icmbnd is the ICM help program for binding ports.
Parameters
This program has the following parameters:
Parameters

Description

Optional/mandatory

-S <server port>

ICM administration port via


which the listen socket of
icmbnd is transferred to the
ICM.

Mandatory

-l <listen port>

Port that is to be connected by


icmbnd. This can be a port
number or a port name (for
example, HTTP, SMTP,
NNTP).

Mandatory

-p <protocol>

Protocol specification for the


port you want to bound (for
example, HTTP, HTTPS,
SMTP).

Mandatory

-k <keep alive>

Specification of the keep alive


timeout (in seconds) for the
port you want to bind. If this
parameter is not specified, the
ICM standard value is used.

Optional

-t <trace level>

Specification of trace level (13). Standard value is 1.

Optional

-f <trace file>

Name of the trace file to be


used.
Standard value is
dev_icmbnd.

Optional

Web Application Server

620 SP 9

52

SAP Online Help

25.10.2002

Error Messages
The following errors may occur and are logged by icmbnd:

Missing argument for option <option>


A required argument has not been entered in the command field.

Illegal option <option>


An invalid argument has been entered.

Missing values for service, listen port or protocol


One of the (mandatory) options -s -l or -p has not been specified.

IcmConnect to port %d failed (rc=%d)


A connection to the ICM to port number of argument S <server port> could not
be created. Please check the specification of parameter -S <server port>.

NiBuf2Listen failed(rc=%d)
The listen port could not be bound. Either the authorizations for binding ports are
missing or the port is already bound by a another program.

IcmBndSendHdl failed (rc = %d)

NiSendHandle failed (rc = %d)


The listen socket could not be transferred to the ICM (communication error).

See also:
For more information see the following pages:
chown, chmod, getuid, setreuid, seteuid, setfsuid

icm/HTTP/j2ee_<xx>
You use this parameter to determine ICMs communication with the J2EE server.
<xx> stands for the number of the entry being specified. Several assignments between the
URI prefix and the J2EE server, numbered in ascending order from 0, can be specified.
Value Range

Unit

Default Setting

Character string of form


icm/HTTP/j2ee_<xx> = PREFIX=<uriprefix>, HOST=<host>, CONN=<Number of
connections>, PORT=<port>

icm/HTTP/j2ee_0 = PREFIX=/, HOST=localhost, CONN=0-10,


PORT=21

Web Application Server

620 SP 9

53

SAP Online Help

25.10.2002

icm/host_name_full
You use this parameter to specify the fully qualified host name of the host on which the ICM is
running, and which can be contacted for requests. For example, ls3022.wdf.sap-ag.de instead
of ls3022.
If this parameter is not set, the system queries the operating system for the host name. With
several host names, this parameter can override this value.

Example
A host has the two fully qualified host names saphost.sap.com and ls12345.sap.com. If the
parameter is not set, the operating system uses the name ls12345.sap.com because this is
the first one in etc/hosts. If, however, you want the host to be addressed externally by the
name saphost.sap.com, set parameter:
icm/host_name_full = saphost.sap.com.
If you want to address the host using a completely different name, you can use the following
mechanisms of the Internet Communication Framework [page 106]:
External Aliases [page 151]
Virtual Hosts [page 136]

icm/min_threads
This parameter specifies the minimum number of threads in the ICM.
This number is the same as the number of simultaneously running connections that can be
processed. The value for the minimum number of threads is created at ICM startup and also
applies during runtime.
Operating System Restrictions
The maximum number of available threads in a process can vary, depending on the operating
system. It must be possible to set the maximum number of threads at ICM startup.
Requirements
icm/min_threads must be smaller than icm/max_threads [page 54].
Value Range

Unit

Default Setting

1 - 32000

Integer

10

icm/max_threads
This parameter specifies the maximum number of threads in the ICM. The maximum number
of threads is therefore the same as the maximum number of connections than can be
processed at the same time. The set minimum number of threads (icm/min_threads [page

Web Application Server

620 SP 9

54

SAP Online Help

25.10.2002

54]) is set at ICM startup and also applies during runtime. If the network load is heavy, the
ICM starts more threads until the set maximum is reached.
Operating System Restrictions
The maximum number of available threads in a process can vary, depending on the operating
system. It must be possible to set the maximum number of threads at ICM startup. If the
network load is heavy, the set maximum is reached.
Value Range

Unit

Default Setting

5 - 32000

Integer

50

icm/min_spare_threads
Use
This parameter specifies the number of worker threads that the ICM tried to keep free. As a
result, it can quickly respond to incoming client requests one after another. This is only
possible if the ICM has not created the maximum number of threads (parameter
icm/max_threads [page 54]).

Procedure
You can also use this parameter to set up a buffer of spare threads.

You must set the parameter clearly less than icm/max_threads [page 54]!
Value Range

Unit

Default Setting

0 - 100

Integer

Example
The ICM starts with 20 threads (= icm/min_threads [page 54]), but can create a maximum of
100 (= icm/max_threads [page 54]) and icm/min_spare_threads is set to 5.
At the start, 20 threads are also available. If more than 15 threads are occupied by requests,
the ICM creates new threads. This continues until there are 100 threads, when the ICM
cannot create any new ones. From this point, the buffer of 5 threads can no longer be
guaranteed. All 100 threads are used for requests.

icm/max_services
This parameter determines the maximum number of ICM services (port/protocol on which the
ICM can accept requests) that can be created.
You can create and display the services in the ICM Monitor (Transaction SMICM) (see also
Displaying and Changing Services [page 74])
To determine permanently valid ICM services, use parameter icm/server_port_<xx> [page
49].

Web Application Server

620 SP 9

55

SAP Online Help

25.10.2002

Value Range

Unit

Default Setting

10 - 99999

Integer

30

icm/max_plugins
This parameter determines the maximum number of ICM plugins that can exist. There is a
plugin for each protocol that the ICM can process.
Parameter icm/plugin_<xx> [page 49] specifies which plugins should be used.
Value Range

Unit

Default Setting

10 - 99999

Integer

30

icm/req_queue_len
This parameter specifies the maximum number of waiting requests. All requests to the ICM
are kept in this queue before they are forwarded to worker threads. The value should be set
to a size that always allows enough space in the queue for all requests. The value of this
parameter must always be greater than the value of icm/max_threads [page 54].
Value Range

Unit

Default Setting

50 - 32000

Integer

100

icm/listen_queue_len
During connection establishment, the operating system must keep requests in a queue. This
parameter specifies the maximum number of requests that can have this status at any one
time.
If the network queue is full, the system rejects any additional connection requests without
notifying the sender.
Operating System Restrictions
This parameter is handled differently by different operating systems. The maximum value for
4.2 BSD was 5. Todays systems support various values. If the operating systems maximum
value is exceeded, the operating system reduces the parameter value to the maximum
supported value. See also the description of operating system call listen(), Parameter
backlog.
Value Range

Unit

Default Setting

5 - 1024

Integer

512

Web Application Server

620 SP 9

56

SAP Online Help

25.10.2002

icm/max_conn
Maximum number of simultaneously open connections in the ICM.
The parameter value can be greater than icm/max_threads [page 54], as inactive connections
require no thread in the ICM. The maximum number of open file handles in the operating
system determines the maximum value of this parameter.
Value Range

Unit

Default Setting

10 - 32000

Integer

300

icm/max_sleep
In the case of a slow network connection, the ICM must relieve scarce resources (work
processes, threads) of requests. This parameter is used to set the maximum period of
inactivity between network activity checks.
Value Range

Unit

Default Setting

1000 - 10000

Millisecond

2000

icm/<PROT>/context_quota
This parameter is available for each of the possible protocols.
icm/HTTP/context_quota
icm/HTTPS/context_quota
icm/SMTP/context_quota
Using these parameters, for each protocol the context use in the backend (SAP system) can
be restricted. You specify what percentage of all available contexts should be used for the
corresponding protocol. In the SAP system, the maximum number of contexts in the system is
restricted by the profile parameter value of rdisp/tm_max_no (this parameter restricts the
maximum number of users per instance).
If this quota is exceeded, the requests are rejected in the ICM (see Components of the SAP
Web Application Server [page 20]).
Value Range

Unit

Default Setting

0-100

Percentage

50

Using setting icm/SMTP/context_quota = 20 you can determine, for


example, that only 20% of the available contexts should be used for SMTP (mail
functions). You therefore have more capacity for HTTP(S) requests.

Web Application Server

620 SP 9

57

SAP Online Help

25.10.2002

icm/accept_remote_trace_level
This parameter determines whether an external client may change the trace level of the SAP
System. Such changes may be necessary for diagnostic purposes. However, such changes
should not be made as a rule, for security reasons.
Value Range

Unit

Default Setting

0: Trace not transferred

Boole

FALSE

1: Trace transferred

icm/ccms_monitoring
You can use this parameter to configure whether CCMS monitoring of the ICM is active. It can
be set to TRUE or FALSE, the default setting is TRUE.

icm/keep_alive_timeout
This parameter refers to the "keep-alive-feature" of HTTP1.1. This means that if within this
time interval new data arrives over the network from the partner, the ICM attempts to keep the
connection open once it has been established. If, for the existing connection, there is no
further communication within the specified time period, the ICM terminates the connection.
This avoids having to keep establishing and terminating expensive network connections.
Value Range

Unit

Default Setting

1 9,999,999

Seconds

60

Requirements
You can override the standard value of the timeout for each service using the
icm/server_port_<xx> [page 49] parameter.

icm/conn_timeout
This parameter determines the maximum duration of a connection to an external partner (in
milliseconds).
If the specified time period is exceeded, the connection is terminated and an error message is
sent to the caller.
Value Range

Unit

Default Setting

0 9,999,999

Milliseconds

5000

Web Application Server

620 SP 9

58

SAP Online Help

25.10.2002

icm/wp_mpi_available
At least as many MPI blocks must have been read by the network so that a rolled out context
can be rolled back into a work process (by the ICM).
To make sure that no work processes are occupied unnecessarily if the network connection is
slow, you can use this parameter to ensure that the context only occupies one work process if
data are also available.
Value Range

Unit

Default Setting

1-50

Number of MPI blocks

See also:
icm/wp_roll_timeout [page 59]

icm/wp_roll_timeout
You use this parameter to determine the maximum time that a work process can run on the
ICM when reading data, before the user context is rolled out.
With slow network connections and large volumes of data, the read time can become very
slow (> 600 seconds). This parameter can prevent the work process from being blocked for a
long period of time, even through it can only read small datasets. The context is then rolled
out and the work process is available for other tasks. The data affected can be collected in an
MPI and then fetched by a work process.
See also:
icm/wp_mpi_available [page 59]

You must set the parameter to be smaller than the value of parameter
rdisp/max_wprun_time (the default setting is 600 seconds), since processing in
the work process is terminated anyway after this time period.
Value Range

Unit

Default Setting

5-3600

Seconds

15

icm/dpj2ee
If the system is not started using the SAP dispatcher "disp+work", but using the standalone
dispatcher "dpj2ee" instead, the ICM must be informed about this using this parameter, and
the value of the parameter must therefore set to True. This informs the ICM that no ABAP
server is running, and therefore that no HTTP request should be forwarded to the ABAP.
If you try to start the standalone dispatcher although the parameter has the value FALSE, the
standalone dispatcher dpj2ee ends immediately.

Web Application Server

620 SP 9

59

SAP Online Help

25.10.2002

The parameter can have the values true or false (upper or lowercase). The default value
is FALSE.
See also:
Integration of the SAP J2EE Application Server [page 101]
Using the SAP J2EE Server with the Standalone Dispatcher [page 103]

icm/HTTP/file_access_<xx>
This parameter determines for which URL prefixes static file access should be set, and in
which directory the static files are stored.
If an access attempt is made on a page or file under virtual_root, virtual_root is replaced by
document_root. The handler then attempts to read the file from the file system and to send it
back to the client.
Value Range

Unit

Default Setting

icm/file_access_<xx> = PREFIX=<URL prefix>,


DOCROOT=<root directory of files>

Character
string

<xx> must be specified in ascending order from 0.


For example, icm/file_access_0 = PREFIX=/docs/,
DOCROOT=/tmp/documents

icm/HTTP/redirect_<xx>
This parameter is used to define a HTTP redirect (301). If the client attempts to access the
URL in question, the server sends a redirect. This forces the client to access the new
destination instead.
If this parameter is set, it calls the redirect subhandler of the HTTP plugin. The HTTP request
is therefore not sent to the backend (ABAP or J2EE server). HTTP Plugin [page 24] describes
the subhandler call sequence.
Value Range

Unit

Default
Setting

icm/redirect_<xx> = PREFIX=<URL prefix>, TO=<new


URL prefix > [, PROT=<protocol>, HOST=<host>,
PORT=<port number/name>]

Character
string

None

<xx> must be specified in ascending order from 0.


You can use optional parameters PROT, HOST and PORT to set the
destination address to a different protocol, a different host or a
different port. You can only specify the port once you have specified a
host name.
The default values for PROT, HOST and PORT are values, that are set
when an incoming request is received.

Web Application Server

620 SP 9

60

SAP Online Help

25.10.2002

icm/redirect_0 = PREFIX=/,
TO=/bc/bsp/demo/default.html
Access attempts on "/" are redirected to "/bc/bsp/demo/default.html".

icm/HTTP/logging_<xx>
This parameter has the following syntax:
icm/HTTP/logging_<xx> = PREFIX=<URL prefix>, LOGFILE=<log file name> [,
LOGFORMAT=<entry format>, MAXSIZE=<max. size of the log file>, SWITCHTF=<options
for the new trace file>, FILEWRAP=on]
This is explained below.

PREFIX
URL prefix that is called for this HTTP subhandler (for example, /). (See also HTTP Plugin
[page 24].)

LOGFILE
Name of the output file in the file system. So that you can assign the files meaningful names,
use the following options when entering the log file:
%d

Day of the month (1-31)

%m

Month (1-12)

%y

Year, in the format YYYY

%h

Hour (0-23)

%t

Minute (0-59)

%s

Second (0-59)

%%

% character

You can also add a timestamp to the file names making them easier to manage.

When setting parameter icm/HTTP/logging_<xx>, if you want to assign the


date and time to the file names, you can set the names as follows:
LOGFILE=access_log-%d-%m-%y_%h:%t:%s
This results in a log file with the name: access_log-15-12-2000_16:51:53

LOGFORMAT
The standard log file format is the common log file format (CLF) and has the form:
10.18.104.36 - - [15/Dec/2000:16:18:35 +0100] "GET /dummy HTTP/1.0"
200 86
If you want to use another format, this can be configured using the format string.
There are the following placeholders:
%b

Length of the response in bytes

%h

Name of the remote host (the client, such as the browser)

Web Application Server

620 SP 9

61

SAP Online Help

25.10.2002

%H

Name of local host

%S

Local port name or service

%a

IP address of the remote host

%l

Specifies the Remote Logname. This name is the result of an IDENT query
to the client. This only works if the identity check is activated there.

%u

User name of 401 authentication

%t

Time specification in CLF format: [15/Dec/2000:16:18:35 +0100]

%T

Duration of a request in seconds

%L

The duration of a request in milliseconds

%r

1. Row of an HTTP request: such as GET /bc/ping HTTP/1.0

%f

Name of requested object without form fields

%U

Whole URI of a request (with form fields)

%s

OK code of the response

%v

Name of the virtual host (IP address or name of the server with which the
client is linked)

%V

Fully-qualified host name (FQHN) of the server (value of parameter


icm/host_name_full or FQHN of the operating system).

%{name}i

Name of a request header field, e.g. %{user-agent}i

%{name}o

Name of a response header field, e.g. %{server}o

%{cookie}c

Output of a request cookie

%{cookie}c

Output of a response cookie

The following string creates the CLF format: %h %l %u %t "r" %s %b.

MAXSIZE
MAXSIZE is the maximum size of the log file in kilobytes.
If this size is exceeded, the current file is closed and a new one (with a new name) is opened.
The new file name is unique (this is achieved by specifying time and date fields, see above),
or else is made unique by adding _xx to the end (where xx is a number increasing from 0).

If FILEWRAP=on was selected, no new file is opened (see below).

SWITCHF
A new log file can not only be created if the file has reached a certain size, but also when the
time data changes:
hour

A new log file is opened every hour

day

A new log file is opened every day

month

A new log file is opened every month

FILEWRAP
If FILEWRAP=on is active, every time a new file is opened, the existing log file is reset and
overwritten. Therefore, there is always only one log file with the current log data.

Web Application Server

620 SP 9

62

SAP Online Help

25.10.2002

PREFIX=/, LOGFILE=dev_http_access_log, SWITCHTF=day,


FILEWRAP=on

Logging in the ICM


Use
The access log contains a log of accesses to the ICM from an intranet or the Internet, and
thus gives you an overview of the activity on the ICM.
You can use external analysis programs to analyze the log file.
A HTTP subhandler implements logging in the ICM. This subhandler statistically analyzes
HTTP requests and records requests.

The log handler uses the log file to serialize itself, which makes it a bottleneck. It
is therefore not usually activated.
The logging implementation procedure corresponds to the Apache Web Server
mod_log_config module.

Procedure
You configure logging using the parameter icm/HTTP/logging_<xx> [page 61].

Sample Log Entries for Default Format (CLF):


10.18.103.34 - - [08/Jan/2001:16:53:20 +0100] "GET
/sap/bc/bsp/sap/it00/default.htm HTTP/1.0" 200 336
10.18.103.34 - - [08/Jan/2001:17:01:15 +0100] "POST
/bc/bsp/sap/it00/transition_parameter.htm HTTP/1.0" 302 0
The following string creates the CLF format: %h %l %u %t "r" %s %b
Sample Log Entry for a Self-Defined Format
The following format
LOGFORMAT=%b %h %H %S %a %l %u %t %T Line=%r %f %U %s %{useragent}i
gives these kind of entries:
181 10.18.104.64 ls3022.wdf.sap-ag.de 8080 10.18.104.64 - [11/Apr/2001:14:01:08 +0200] 0 Line=GET /sap/bc/bsp/sap/it00
HTTP/1.1 /bc/bsp/sap/it00 /bc/bsp/sap/it00 500 Mozilla/4.0
(compatible; MSIE 5.01; Windows NT 5.0)

Web Application Server

620 SP 9

63

SAP Online Help

25.10.2002

icm/HTTPS/verify_client
This parameter specifies whether or not a client must produce a certificate. There are three
certification levels (0-2):

0: No certification is required and the server does not ask for one.

1: The server asks the client to produce a certificate. If the client does not send a
certificate, authentication is carried out by another method, for example, basic (default
setting).

2: The client must transfer a valid certificate to the server, otherwise access is denied.

Value Range

Unit

Default Setting

0-2

Integer

These settings apply to the entire server.


The system administrator can use icm/HTTPS/verify_client=2 to ensure that
users who attempt to log on to this server via HTTPS can only do so by producing
a valid certificate.
You can override the setting for individual ports by using the parameter
icm/server_port_<xx> [page 49] with option VCLIENT.

icm/HTTP/server_cache_<xx>
This parameter is used to determine the URI prefix and the destination directory for the
internal ICM HTTP server cache.
icm/HTTP/server_cache_<xx> = PREFIX=<uri-prefix>,
CACHEDIR=<dir>

Meaning

<xx>
This stands for the number of the entry being specified. Several assignments between the
URL prefix and the cache directory, numbered in ascending order from 0, can be
specified. (However, it is recommended that only one assignment be used).

<uri-prefix>
All HTTP URIs that begin with this character string are channeled through the ICM Server
Cache [page 34]. This is to check whether a suitable HTTP response to the request
already exists in the ICM cache. If this is the case, the response can be sent directly (in
other words, without passing through the SAP application server) from the cache to the
HTTP client (browser).

<dir>
Complete file system path details for the directory (in the local file system of the relevant
application server) in which the data stored in the cache can be saved.

icm/HTTP/server_cache_0= PREFIX=/foo/bar, CACHEDIR=/usr/cachedir

Web Application Server

620 SP 9

64

SAP Online Help

25.10.2002

This channels via the cache in the directory /usr/cachedir all HTTP requests
whose URI path begins with /foo/bar.

Default
icm/HTTP/server_cache_0 = PREFIX=/, CACHEDIR=$(DIR_DATA)/cache
The presetting dictates that all HTTP requests (prefix /) are channeled via the cache located
in the standard DATA directory on the application server.

icm/HTTP/server_cache_<x>/max_entries
Maximum number of entries in the ICM/HTTP server cache (see the documentation on
icm/HTTP/server_cache_<xx> [page 64]).
When dimensioning, make sure that the memory requirement for the cache entries does not
clash with the setting for the parameter icm/HTTP/server_cache_<xx>/size_MB [page 66]. A
rule of thumb for memory use is given in the documentation for this parameter.
Value Range

Unit

Default Setting

100 - 2 000 000 000

Integer

10 000

icm/HTTP/server_cache_<xx>/clear
If this parameter is set to the logical value TRUE, it causes the ICM cache content to be
deleted every time the server is re-started.
Value Range

Unit

Default Setting

TRUE, FALSE

Boole

TRUE

icm/HTTP/server_cache_<xx>/expiration
This parameter sets the default expiry time in seconds for ICM cache entries. After the expiry
time of an entry expires (expiry time is calculated from entry in the cache), the entry is marked
as invalid and can thus be overwritten by new entries.

This is purely a default value.


Usually, the expiry time for every cache entry is set individually by the relevant
HTTP request handler (see Internet Communication Framework [page
106]Fehler! Es wurde kein Textmarkenname vergeben.).
Value Range

Unit

Default Setting

0 - 2 000 000 000

Seconds

86400 (1 day)

Web Application Server

620 SP 9

65

SAP Online Help

25.10.2002

icm/HTTP/server_cache_<xx>/max_name_len
This parameter specifies the maximum length (in number of characters) of the HTTP URIs of
objects that are to be saved in the ICM cache (see also Error! No bookmark name
given.icm/HTTP/server_cache_<xx> [page 64]).
It is important that this value, in conjunction with the value of the parameter
icm/HTTP/server_cache_<x>/max_entries [page 65], has a direct effect on the main memory
requirements of the ICM cache.
For a rule of thumb for calculating the memory requirement, see
icm/HTTP/server_cache_<xx>/size_MB [page 66].
Value Range

Unit

Default Setting

100 - 1 000

Number of characters

256

icm/HTTP/server_cache_<xx>/max_ufo_entries
This parameter sets the maximum number of entries in the UFO list (un-found objects) of the
ICM server cache. For more information on this see icm/HTTP/server_cache_<xx>/ufo_list
[page 67] and icm/HTTP/server_cache_<xx> [page 64].
When configuring the UFO list, pay particular attention to the memory requirements for the
access index stored in main memory.

Rule of Thumb for Calculating Memory Requirements


Requirement (in bytes) = 2 * max_ufo_entries * max_name_len
In Unicode systems, the requirement is approximately twice as high.
Value Range

Unit

Default Setting

10 - 2 000 000 000

Integer

10 000

icm/HTTP/server_cache_<xx>/size_MB
This parameter sets the size of the ICM Server Cache in megabytes.
See also: icm/HTTP/server_cache_<xx> [page 64].

Rule of Thumb for Calculating (Virtual) Memory Requirement


memory_needed = 2 * (2N + U) * M + S Bytes
where:
N = icm/HTTP/server_cache_<x>/max_entries [page 65]
M = icm/HTTP/server_cache_<xx>/max_name_len [page 66]
U = icm/HTTP/server_cache_<xx>/max_ufo_entries [page 66]
S = icm/HTTP/server_cache_<xx>/memory_size_MB [page 67]
In Unicode systems, the requirement is approximately twice as high.

Value Range

Web Application Server

Unit

Default Setting

620 SP 9

66

SAP Online Help

10 - 4 000

25.10.2002

Megabytes

100

icm/HTTP/server_cache_<xx>/memory_size_MB
The size of the entire cache is set by the parameter icm/HTTP/server_cache_<xx>/size_MB
[page 66].
In other words, this parameter decides which part of the cache should be stored in main
memory and which on the hard disk.
If sufficient main memory is available, this parameter should be set to a high value, to ensure
maximum performance.
For a rule of thumb for dimensioning, see the parameter documentation under
icm/HTTP/server_cache_<xx>/size_MB [page 66].
Value Range

Unit

Default Setting

2 - 4000

Megabytes

50

icm/HTTP/server_cache_<xx>/ufo_list
This parameter is set to the logical value TRUE in order to activate the UFO (un-found
objects) list of the ICM/HTTP server cache. This list is a negative list of all HTTP URLs that
are invalid or unknown to the system.
The purpose of this list is to ensure that all HTTP requests that have been rejected by the
system in the past continue to be rejected in future rejected by the cache. In this way, such
requests do not add to the load on the application server the second time round (sporadic
errors, denial-of-service attacks).
It is therefore important that every entry in the UFO list has an expiry time attached, similarly
to the entries in the cache itself (see also icm/HTTP/server_cache_<xx>/ufo_expiration [page
68]).

When configuring the UFO list, pay particular attention to the memory
requirements for the access index stored in main memory.

Rule of Thumb for Calculating Memory Requirements


Requirement (bytes) = 2 * max_ufo_entries * max_name_len
In Unicode systems, the requirement is approximately twice as high.
Value Range

Unit

Default Setting

TRUE, FALSE

Boole

FALSE

Web Application Server

620 SP 9

67

SAP Online Help

25.10.2002

icm/HTTP/server_cache_<xx>/ufo_expiration
This parameter sets the expiration time in seconds for the entries in the UFO list in the ICM
cache (see also icm/HTTP/server_cache_<xx>/ufo_list [page 67]).
You should not set the value too high, however, as automatic expiry is the systems only way
of invalidating UFO entries (since all HTTP requests that refer to UFO entries have already
been rejected by the cache).
Value Range

Unit

Default Setting

1 - 2 000 000 000

Seconds

60

Memory Pipes
Data transfer between ICM (Internet Communication Manager) and the SAP work processes
goes via memory pipes (MPI). These work on the basis of shared memory.
The following parameters relate to memory pipes.

mpi/buffer_size
Data transfer within memory pipes is conducted in blocks of a set length. This parameter
defines the size of these blocks.
Do not change the values of this parameter.
Value Range

Unit

Default Setting

32768-256K

Bytes

65536

mpi/total_size_MB
This parameter specifies in megabytes the total size of the shared memory area used for the
MPIs.
Value Range

Unit

Default Setting

5-1000

Megabytes

40

Monitoring the ICM with the ICM Monitor


Use
You can use this transaction (SMICM) to monitor and administrate the Internet
Communication Manager, which sends and receives requests to and from the Internet.

Web Application Server

620 SP 9

68

SAP Online Help

25.10.2002

Prerequisites
The ICM is running on the server. In transaction SM51, you can see the work process types
provided on the server and the entry ICM.

Functions
In the initial screen you can see a list of the worker threads from the activities of the individual
threads.

The fields in the display have the following meaning:


Field

Meaning

No.

Thread number:
The threads that are available for processing (receiving or sending) requests
are numbered by the ICM (like the work processes by the dispatcher).

Thread ID

The thread ID that is assigned by the operating system (analogous to the PID
for processes).

Number

The number of requests that were processed by this thread.

Status

The current status of the thread.

Web Application Server

620 SP 9

69

SAP Online Help

25.10.2002

The following values are possible:


Free: The thread is waiting for a request.
Running: The thread is processing a request. In this case, you can display
detailed information by double-clicking on the line. Column Processed
Request also displays more information.
Processed
request

The type of request that the thread is currently processing.


Possible values are:
Blank field

The thread is not currently doing anything

Administration

Action that is triggered by Transaction SMICM


or program icmon, such as the list display. This
means that at least one thread always displays
administration when you call SMICM.

Read request

Reads the request (server)

Read response

Reads the response (client)

Write request

Writes the request (client)

Write response

Writes the response (server)

Open connection

Sets up the connection to a server

Close connection

Closes the connection to a partner

Accept connection

Accepts the connection from a client

Time-dependent action

Executes time-dependent (periodically


scheduled) events

Execute shutdown

Ends ICM

Wait for data

Waits for data from the network or from the


application server (SAP Web dispatcher)

Wait for response (SERV)

Waits for a response from the application


server (SAP Web AS is a server with active
connections)

Wait for response (CLNT)

Waits for a request from the application server


(SAP Web AS is a server with active
connections)

From the menu on this initial screen, you can use various functions. These are described in
detail in the following sections:
Monitoring the State of the ICM [page 71].
Monitoring and Administrating the ICM Server Cache [page 73]
Displaying Services [page 74]
Administration [page 77]

Activities
From the menu, choose Administration System Administration Monitor System
Monitoring Internet Communication Manager or enter transaction code SMICM.

Web Application Server

620 SP 9

70

SAP Online Help

25.10.2002

Monitoring the State of the ICM


Use
This transaction provides various functions for monitoring the state of the ICM and for
detecting any possible errors.

Prerequisites
The ICM is running on the application server.

Functions
You can find the functions described here in the Goto menu.

Trace Files
To display or reset the trace file, choose Go To Trace File or Go To Trace Level. You
can also set the trace level here (values can be between 0 and 3; the default is 1).

Parameters
Choose Goto Parameters to display or change the ICM profile parameters. If you want to
change them, you can display the Rz11 documentation for every parameter that is executed
by placing the cursor on the parameter name and choosing
Documentation.
The value field is ready for input for those parameters that can be changed dynamically.

Note that with dynamic changes, these are lost the next time the instance is
started.

Statistics
Choose Go to Statistics to activate, deactivate, display, and reset the ICM statictics.

Memory Pipes
Choose Go To Memory Pipes for information on the memory pipes that are used for data
exchange between the ICM and the work process.

Host Name Buffer


The mapping of host names to IP addresses or of service names to port numbers is buffered
in the SAP System, once they have been read from the file system. If a host name or a
service name that should be accessed is changed, the host name buffer must be reset.

Services
You can use this function to monitor and administer services (ports that are used for the ICM
connections). This is described in Displaying and Changing Services [page 74].

Release Information
Choose Goto Release Info or choose Release Info to display information about the version
of the ICM, the release and the patch level of the SAP kernel.
The first line contains general information on the ICM.
You can see the status of the SAP kernel from kernel information. As well as the
kernel release and compile information, you can find the following numbers.

Web Application Server

620 SP 9

71

SAP Online Help

25.10.2002

update level specifies the kernel status with which the kernel can run in an SAP
system. If different application servers should run in a system with different kernel patch
statuses, they must all have the same update level.

patch number specifies the last patch level that is relevant for the component ICM.

source id indicates (the numbers after the point) the actual kernel patch level.

Below you can find the patch comments on the kernel patches that affect the ICM component,
as well as additional detail information.

HTTP Server Cache


Here you can find functions for Monitoring and Administrating the ICM Server Cache [page
73].

HTTP Log
Choose Springen HTTP Log you can display the following information on HTTP logging.

Display entries: Display the entries in the logging file

Information: Name of the log file, format of the log file, terms for new log files, maximum
log file size, cyclical write (yes/no), current number of characters in the log file and the
current number of lines in the file.

Write buffer: The logging file entries are buffered and are regularly written to the hard
disk. Since you can only see the entries that are already on the hard disk with Display
Entries, you can use this function to force the buffer contents to be written to the hard
disk.

You can find additional information about HTTP logging in Logging in the ICM [page 63].

HTTP Application Server


By choosing Goto HTTP App Server you can display information on the HTTP application
server (information about the active ABAP or J2EE server, URL perfix table) as well as load
URL prefixes.
If no J2EE server has been configured, (J2EE Server configured = FALSE), then all
HTTP requests are passed to the ABAP server (to the ICF, see also . Server Roles [page
99]). If a J2EE server is connected, the URL prefix table is used to decide whether the
request is sent to the ABAP or the J2EE server. All URL prefixes in the table are sent to the
ABAP server, all others are sent to the J2EE server. The table is determined from the
possible prefixes (HTTP service tree and external aliases) of the Internet Communication
Framework [page 106].
If no J2EE server has been configured, the table is not loaded. You can however enforce this
using Load URL Prefixes.
See also:
Integration of the SAP J2EE Application Server [page 101]
Server Selection and Load Balancing Using the SAP Web Dispatcher [page 84]

Web Application Server

620 SP 9

72

SAP Online Help

25.10.2002

Monitoring and Administrating the ICM Server


Cache
Use
To monitor the ICM Server Cache, choose Go To Server Cache. The following functions
are available.

Prerequisites
The ICM is running on the application server.
The ICM Server Cache [page 34] has been correctly configured.

Functions
Display ICM Server Cache Content
Displays all objects currently contained in the cache. The following details are given for each
object:

File length

Creation details (date and time)

Validity period (see parameter icm/HTTP/server_cache_<xx>/expiration [page 65]),


default is one day

Version (shows whether the object was changed and re-saved to the cache)

You can search the list, sort the items in the list, double-click an object to display it in the
lower window, and display and invalidate individual cache entries. To invalidate an entry,
position your cursor on the entry and choose .
See below for details of how to invalidate all entries in the cache.

Web Application Server

620 SP 9

73

SAP Online Help

25.10.2002

The left-hand frame in the picture above shows the various server caches that were defined
using parameter icm/HTTP/server_cache_<xx> [page 64], as well as their URLs and port
numbers.

Display ICM Server Cache Statistics


The statistics provide information such as the size of the cache, how much cache memory is
in use, the total number of cache accesses, and so on.
To display the statistics, choose Go To Display Statistics.

Invalidate ICM Server Cache


You can invalidate all entries in the cache. This is possible both for the local server and the
entire system. To do this, choose Edit Invalidate Cache. Then choose either Only local or
Globally in system.
See also: ICM Server Cache [page 34]

Displaying and Changing Services


Choose Go To Services or the corresponding icon on the entry screen to display the
services configured for the ICM. A service consists of the following components:

The protocol that is used (HTTP, HTTPS, SMTP)

Service/port

Web Application Server

620 SP 9

74

SAP Online Help

25.10.2002

Timeout (in seconds)

Flag whether the service is currently active. The ICM does not accept requests on an
inactive port.

Flag whether the external binding program icmbnd should be used to bind the port (see
also Binding Ports < 1024 to UNIX [page 51])

On this screen, you can choose Go To Service to create a new service, and activate or
deactivate existing services.
You can display the ICM server cache statistics by choosing Goto Statistics This displays
details about accesses and hits and so on.
If you double-click a service, you branch to the detail display for that service.

Note that any changes you make here are lost when you restart. If you want to
create or change a service permanently, you must do this using the profile
parameter icm/server_port_<xx> [page 49].

Analyzing Problems and Searching for Errors


The following documentation describes frequent problems. You can search for the symptoms
and error messages here and find their cause.

Problem: You can see from the ICM monitor initial screen that the ICM is
not running.

The trace file will give you the reason for this. Choose Goto Trace File Display Trace
File or choose the
icon.
Possible reasons why the ICM is not running are:
The executable is not there, the dispatcher could not start the ICM. In the trace file of
dispatcher dev_disp (such as using Transaction ST11) you see the following messages.
*** ERROR => Internet Communication Manager (pid 13538) died
[dpxxdisp.c
11929]
*** ERROR => DpIcmCreate: execv ./icman (2: No such file or
directory) [dpuxdisp.c
635]
***LOG Q0C=> DpIcmCreate, execv (./icman) [dpuxdisp.c 636]
The ICM was stopped manually (either at operating system level or with Transaction
SMICM, see Administrating the ICM [page 77]). In the trace file of the Icm dev_icm, you
then see messages
[Thr 1024]IcmLoop: Shutdown request received
[Thr 1024]*** ICM shutdown completed(pid: 25714) ***
Es wird eine falsche Version vom ICM eingesetzt. The version must match the SAP
dispatcher (disp+work) version. If there is a conflict of versions, you see the following
messages in dev_icm:
[Thr 1024] ***LOG Q0Z=> DpSysACreate, bad version (mem=161
exe=156) [dpxxtool2_mt 503]
[Thr 1024] *** ERROR => IcmInit: IcmIPCInit failed (rc=-1)
[icxxman_mt.c 759]

Web Application Server

620 SP 9

75

SAP Online Help

25.10.2002

Resource problems:
The following tables describes possible resource bottlenecks and how to solve them.
Problem

Recognition

Solution

You cannot create a new


network connection to the
ICM.

On the initial screen of the


ICM monitor, you see that with
the connections used, peak
value = max. value applies.

Increase parameter
icm/max_conn (default 300).

This means that all


connections were used up at a
point in time.
The ICM queue for requests
has overflowed. (Before a
request is accepted, it is
written to the queue, the ICM
control then assigns a thread
to the request.)

On the initial screen of the


ICM monitor, you see that with
the queue entries used, peak
value = max. value applies.

The ICM has no MPI (buffer)


left. An error is returned to the
client.

Choose Goto Memory


Pipes Display Data to
check whether all MPIs or
buffers are used or have been
used.

You have either configured too


few threads or the threads are
blocked.

The value of #MPI Pipes used


should not exceed the limit of
2000, and the value of Peak
buffer usage should not reach
Total #Mpi Buffer.

In the first case, increase the


number of threads. In the
second case, double-click on
the hanging threads to
determine why they are
hanging.
You can change the MPI size
(parameter mpi/total_size_MB
and mpi/buffer_size), but not
the total number of the MPIs,
which is 2000 due to operating
system restrictions.

URL does not work


Check that you have entered the port correctly in the URL. In the ICM monitor, choose Goto

Services or choose the

icon on the initial screen.

You can now check whether the ICM stops at the port specified in the URL.

Web Application Server

620 SP 9

76

SAP Online Help

25.10.2002

Note:
Port 0 can only be used for outgoing connections (SAP Web AS as a client).
A service that is not active cannot accept any new requests. It processes all existing
connections.
Port cannot be bound
The following error messages are written in dev_icm if services cannot be offered by the ICM.
[Thr 12301] *** ERROR => NiIBind: service 80 in use [nixxi_r_mt.c
3889]
[Thr 12301] *** ERROR => NiIListen: NiBind (rc=-4) [nixxi_r_mt.c 553]
This message means that the port was already being used or that authorization was missing
to bind this port (see also Binding Ports < 1024 on UNIX [page 51]).
SSL error
The following messages indicate problems with SSL initialization.
ERROR in sec_get_PSEtype: (4129/0x1021) The PSE does not exist :
"/usr/sap/BIN/DVEBMGS53/sec/SAPSSLC.pse"
ERROR in aux_get_credentials_file: (17666/0x4502) Credential file not
found: "/usr/sap/BIN/D12/sec/cred_v2"
[Thr 12301] *** ERROR => Initialization of SSL library failed -- NO
SSL available!
The shared library or the certificate was not found here.
See also:
Using the Secure Sockets Layer Protocol [page 528]

Administration of the ICM


Choose Administration
ICM to soft-terminate (signal 2) or hard-terminate (signal 9) the
ICM. With a soft termination, the ICM tries to send responses to its existing clients and then to
close the connection. With a hard termination, the process is simply terminated. All existing
connections and, of course, all requests are lost.
Choose Administration
Dispatcher
Force restart to force the dispatcher to restart the
ICM if the ICM terminated due to an error.
Choose Administration J2EE Server to use the functions for managing the SAP J2EE
application servers. The functions are described in SAP J2EE Application Server
Administration [page 103].
See also:
Integration of the SAP J2EE Application Server [page 101]

Web Application Server

620 SP 9

77

SAP Online Help

25.10.2002

SAP J2EE Engine Administration


Use
You can manage the SAP J2EE Engine from the SAP Web Application Server, that is, you
can start and stop it in different ways. You can find the functions in the ICM monitor
(Transaction SMICM or by choosing Administration System Management Monitor
System Monitoring Internet Communication Manager).

Integration
You can use the SAP J2EE Engine with the SAP Web Application Server 6.20. The Java
connector JCo enables the two servers to be closely connected with each other.

Prerequisites
You are using the SAP Web Application Server with the integrated SAP J2EE Engine.

So that the dispatcher can start the SAP J2EE Engine, you must set parameter
rdisp/j2ee_start to 1. You can make this setting dynamically in Transaction
RZ11.

Functions
On the initial screen of the ICM monitor (Transaction SMICM), choose Administration
J2EE Server.
The following functions are available:

Sending a Soft Shutdown (With or Without a Restart)


The SAP Web Application Servers dispatcher sets the restart flag for the SAP J2EE Engine
and sends the SOFTSHUTDOWN message to the J2EE server. The dispatcher does not
actively close the connection, the SAP J2EE Engine must close itself instead. If the
application server is restarted, the SAP J2EE Engine is restarted by the dispatcher.

Sending a Hard Shutdown (With or Without a Restart)


The SAP Web Application Servers dispatcher sets the restart flag for the J2EE Engine and
sends the SOFTSHUTDOWN message to the SAP J2EE Engine. The dispatcher does not
actively close the connection, the SAP J2EE Engine must close itself instead. If the
application server is restarted, the SAP J2EE Engine is restarted by the dispatcher.

Ending the Process (With or Without a Restart)


The SAP Web Application Servers dispatcher sets the restart flag for the SAP J2EE Engine
and sends a signal to the process (shell or Java process). If the application server is
restarted, the SAP J2EE Engine is restarted by the dispatcher.

Restart Yes/No
This sets the SAP J2EE Engines restart flag.
See also:
Integrating the SAP J2EE Application Server [page 101]

Web Application Server

620 SP 9

78

SAP Online Help

25.10.2002

SAP Web Dispatcher


Uses
The SAP Web Dispatcher is used as a "software Web switch" between the Internet and your
SAP system, which consists of one or more Web Application Servers. You therefore have
only one point of access for HTTP(S) requests in your system. Furthermore, the SAP Web
dispatcher balances the load, so that the request is always sent to the server with the greatest
capacity.

Introductory Comments
The SAP Web dispatcher is recommended for when you use an SAP system with several
SAP Web Application Servers for Web applications.
The SAP Web dispatcher is a program that you can run on the machine that is connected
directly to the Internet. It is very easy to configure. The SAP Web dispatchers profile file only
needs to know the port on which it should accept HTTP(S) requests (parameter
icm/server_port_<xx> [page 49]), where it can find the SAP message server (parameter
rdisp/mshost) and on which port it accepts these HTTP requests (parameter
ms/http_port).
If you should be able to call the Web application externally, for example using the URL
www.shop.acme.com, this host name must be mapped internally to the SAP Web
Dispatcher. This then forwards the HTTP(S) request to a suitable SAP Web AS.
The prerequisites for operating the SAP Web Dispatcher are described in Operating the SAP
Web Dispatcher [page 82].
SAP Web Dispatcher [page 87] describes the SAP Web dispatchers profile parameter. The
settings should be suitable for normal operation. You can also find the parameters in
Transaction RZ11. You can find an example of the SAP Web dispatchers profile file in
Example: Profile File of a SAP Web Dispatcher [page 91].

Integration
The SAP Web dispatcher is located between the Web client (browser) and your SAP system
that is running the Web application.

Web Application Server

620 SP 9

79

SAP Online Help

25.10.2002

Load Balancing and


Configuration: Information from
the SAP Message Server

Message
Server
Central

http://shop.acme.com

RDBMS

Instance

SAP
Web
Dispatcher
Dialog
Instance

Single Point of
Access: one IP
Address, Port
and URL

DMZ
(Demilitarized
Zone)

Dialog
Instance

Intranet

It forwards the incoming requests (HTTP, HTTPS) around to the SAP Web AS of the SAP
system. The number of requests that are sent to a Web AS depends on its capacity, which is
linked to the number of dialog work processes that are configured. If the application is
stateful, the SAP Web dispatcher ensures that with the next request, the user is forwarded to
the server that is processing his or her application. To do this, it uses the session cookie with
HTTP connections, and the client IP address with HTTPS connections (with SSL) (see also
SAP Web Dispatcher and SSL [page 95]).
The procedure for this is described in detail in Server Selection and Load Balancing Using the
SAP Web Dispatcher [page 84].
Furthermore, the SAP Web dispatcher decides whether the incoming request should be
forwarded to an ABAP or J2EE server. For more information, see Integration of the SAP J2EE
Application Server [page 101].

Unlike HTTP Load Balancing Using the SAP Message Server [page 97], redirects
are not executed when the SAP Web dispatcher is used. This avoids the
associated disadvantages (several IP addresses must be known, bookmarking is
not possible, authentication after changing the application server).

Functions
The SAP Web dispatcher keeps information about the SAP system that it needs for load
distribution in the following tables:
Table

Information

Source of Information

Server Table

All SAP Web Application Servers that


process the HTTP(S) requests.

Message server of the SAP system


with the server list.

Group Table

Groups of these servers. Here there


are known groups that are maintained
in the system, as well as the following
internal groups:

You maintain logon groups in


Transaction SMLG in the system.
The SAP Web dispatcher can get
the information from any SAP Web
AS.

!ALL

Web Application Server

Group of all connected


application servers.

620 SP 9

80

SAP Online Help

URL Mapping Table

25.10.2002

!J2EE

Group of J2EE servers.

!DIAG

Group of ABAP servers that


provide the dialog work
processes.

Mapping of the path part that is


specified in the browser to the
information about the server (groups).

You maintain the URL path in


Transaction SICF as a service in the
HTTP service tree.

You can determine, for example, that


all requests that contain the path prefix
/sap/bc are only processed by the
servers that process logon group
GROUP_1.

The SAP Web Dispatcher Profile Parameter


SAP Web Dispatcher [page 87] describes the profile parameter for configuring the SAP Web
dispatcher.

When you set the maximum values, note that unnecessarily large values can
increase the SAP Web dispatchers memory consumption.

You can find an example of a SAP Web dispatchers profile file in Example:
Profile File of a SAP Web Dispatcher [page 91].

Starting and Stopping the SAP Web Dispatcher


Operating the SAP Web Dispatcher [page 82] describes how you start and stop the SAP Web
dispatcher.

Tracing the SAP Web Dispatcher


The SAP Web dispatchers trace file is called dev_webdisp and is located in the work
directory. If you want to change the trace level, you must first determine the SAP Web
dispatchers PID. You can then use command kill -USR1 <WebDisp PID> to increase
the trace level by one, or kill -USR2 <pid> to reduce it. By default, the trace level is
set to 1.

Rule of Thumb for the SAP Web Dispatchers Memory Requirement


Of course, the SAP Web dispatcher must reserve as much memory as possible to store large
tables.
A rough estimation for memory requirement provides the following formula:
Memory requirement = (S NS + G NG + U NU) 2 Bytes
where the letters have the following meaning:
Variable

Parameter value

wdisp/max_servers

NS

wdisp/max_server_name_len

wdisp/max_server_groups

NG

wdisp/max_server_group_name_len

Web Application Server

620 SP 9

81

SAP Online Help

25.10.2002

wdisp/max_url_map_entries

NU

wdisp/max_url_map_path_len

Additional SAP Web dispatchers are described in the following sections:

Operating the SAP Web Dispatcher [page 82]

Server Selection and Load Balancing Using the SAP Web Dispatcher [page 84]

The SAP Web Dispatcher Profile Parameter [page 87]

SAP Web Dispatcher and SSL [page 95]

Restrictions
The SAP Web dispatcher is only useful in the Web environment. In the classic SAP system,
load is balanced by the message server.
The SAP Web dispatcher forwards only incoming HTTP(S) requests to the Web application
server and the response is then returned to the client.
Outgoing requests (such as requests to a different SAP Web Application Server) are not sent
via the SAP Web dispatcher, but via the proxy that uses the appropriate intranet.

When you use HTTPS, the SAP Web dispatcher cannot read the request data as
this is encoded. It forwards the complete request to an application server that is
HTTPS-enabled. SAP Web Dispatcher and SSL [page 95] describes the
problems that this can cause and how you can solve them.

Operating the SAP Web Dispatcher


Use
The following information describes how you start and stop the SAP Web dispatcher, and the
prerequisites that your system must meet to enable you to use the SAP Web dispatcher.
SAP Web Dispatcher [page 79] describes how you use the SAP Web dispatcher.

Prerequisites
The prerequisites for operating the SAP Web dispatcher are:

SAP Web AS 6.20 with a 6.20 kernel

The HTTP port for the SAP message server is configured (profile parameter ms/http_port)

There is a profile file for the SAP Web dispatcher (see Example: Profile File of a SAP
Web Dispatcher [page 91] and Profile Parameters of the SAP Web Dispatcher [page 87])

The SAP Web dispatcher must be able to contact the HTTP port of the SAP message
server.

The following services must be activated in the HTTP service tree (Transaction SICF):
/sap/public/icman
/sap/public/icf_info/*

Web Application Server

620 SP 9

82

SAP Online Help

25.10.2002

(See also Creating an ICF Service [page 140] and Activating and Deactivating an ICF
Service [page 147])

Procedure
Starting the SAP Web Dispatcher
You start the SAP Web dispatcher with the command
sapwebdisp pf=<profile name> [-f <tracefile> -t <tracelevel> -cleanup -shm_attch_mode
<mode> -auto_restart -version]
The optional parameters have the following meaning.

You can use -f to determine the name of the trace file. The standard is dev_webdisp.

You can use option -t to set the trace level.

-cleanup means that common resources (shared memory and so on) are released. This
is necessary if the SAP Web dispatcher ran was not stopped in an orderly manner the
last time it ran, but was terminated by a crash.

-shm_attch_mode <mode> determines what should happen to the shared memory of


the SAP Web Dispatcher. Here, <mode> is a number that is a combination of the
following values (bit mask):
1: Delete the shared memory of the SAP Web dispatcher (cleanup)
2: Try to connect to the shared memory (attach)
4: Create a new shared memory (create)
This results in the following possible options:
1: The shared memory is cleaned up and the SAP Web dispatcher ends. The
behavior is the same as with the option of cleanup.
2: The SAP Web dispatcher connects to the existing shared memory (attach). If this
does not exist, the SAP Web dispatcher ends with an error.
3: Not useful
4: The SAP Web dispatcher creates a new shared memory. If this exists already, the
SAP Web dispatcher ends with an error. This is also the default value, that is, the
SAP Web dispatcher behaves in this way if the options -shm_attch_mode <mode>
and -cleanup are not used.
5: If a shared memory exists already, it is deleted. A new shared memory is then
created.
6: The system tries to attach it to an existing shared memory. If a shared memory
does not exist, a new one is created.
7: As 5

These settings are useful for managing SSL client IP addresses. With the
appropriate settings, this information does not get lost in the SHM, but can be
reused if the SAP Web dispatcher crashes. See also SAP Web Dispatcher and
SSL [page 95].

-auto_restart: With this option you can make the SAP Web dispatcher highly
available at process level. The process is described in the section High Availability of the
SAP Web Dispatcher [page 96].

-version displays the version of the SAP Web dispatcher. The program is not started.

Web Application Server

620 SP 9

83

SAP Online Help

25.10.2002

You usually start the SAP Web dispatcher as follows:


sapwebdisp pf=<Profile name>

Stopping the SAP Web Dispatcher


If you want to stop the SAP Web dispatcher, you determine the parameter ID and enter the
following command: kill -2 <pid> (UNIX) or sapntkill -2 <pid> (Windows NT).

You can take the PID of the SAP Web dispatcher from the trace file
dev_webdisp in the work directory.

Result
You start or stop the SAP Web dispatcher.

Server Selection and Load Balancing Using the


SAP Web Dispatcher
An HTTPS request is assigned to a server in two levels. HTTPS requests are discussed at
the end of this documentation.
1. First, the SAP Web dispatcher decides whether the incoming HTTP request should be
forwarded to an ABAP or a J2EE server. It determines a group of servers in the SAP
system that could execute the request.
2. The load is then balanced within this group.

Determining the Server Group


If no J2EE server is active, in the stateless case the request is passed to the next SAP Web
AS in the queue according to load balancing. The server group that can process the request
is the internal group !ALL of all SAP Web AS in the system. If it is a stateful connection, the
system selects the SAP Web AS that is processing the transaction.
If a J2EE server is active, the system looks through the list of ICF prefixes. If the URL starts
with a prefix that is in the HTTP service tree, the request is passed to the server group !DIAG.
If not, it is passed to the group !J2EE. The groups are described in SAP Web Dispatcher
[page 79] under Functions.
The start page and the root directory are handled in a special way, since when you search
through the list of prefixes, you cannot search through the root directory (it would always be
found because all URLs begin with /). If the URL is a root URL, the profile parameter
is/HTTP/default_root_hdl determines which root directory should be used. Permitted
values are abap and j2ee, although the value can also be changed dynamically using
Transaction RZ11 or SMMS.
The following flow diagram shows the algorithm that is used.

Web Application Server

620 SP 9

84

SAP Online Help

25.10.2002

Start

Session cookie
available?*

No

Compare URL prefix


with the URL mapping
table

Yes
Send request
to the server
that processes
this session

SAP prefix
(ICF)?

Yes

Prefix
assigned to a
logon group
(ICF)?

Yes Select this


group

No
No
Select internal
group !J2EE

Select internal
group !DIAG

Balance load between the servers of the selected group


(distributed around according to server capacity)
*in stateful operation, a session cookie is available,
not in the stateless case.

Server found

The decision whether it is a SAP prefix is described in detail below. With URL
http://hostname:port/A/B/C the prefix to be examined is the character string /A/B/C.
The SAP Web dispatcher must therefore decide whether it is an SAP prefix, which should be
sent to the ABAP server (the ICF), or if it is a prefix that is not recognized by the ICM, in which
case it is sent to the J2EE application server. To do this, the following process is used.
Start

Prefix found in
URL mapping
table?

Yes

No

Does
the prefix contain
one semi colon?
(/A)

No

Yes

abap

SAP Prefix
(Request sent to ICF)

What is the
value of parameter
is/HTTP/default_root_hdl?
(abap, j2ee)

j2ee

Not an SAP Prefix


(Request sent to J2EE server)

If you enter the URL http://saphost:8080/index.html, the prefix to be


checked is /index.html. This is not found on the URL mapping table and it
contains one oblique. If you now set parameter is/HTTP/default_root_hdl
to j2ee (default setting), the system searches the root directory of the SAP J2EE

Web Application Server

620 SP 9

85

SAP Online Help

25.10.2002

Application Server for file index.html. This is then returned to the client by the
ICM of the application server.

Working with Logon Groups in the SAP System


If the request should be sent to an SAP Web AS, then you must check whether a logon group
(maintained in Transaction SMLG) has been defined for this URL. The SAP Web dispatcher
checks the list of logon groups to see if one has been defined. If it does find one, the load
balancing must be executed within this logon group.

Since with HTTP there are many requests, this logon group must have the
attribute external RFC so that no one server is flooded with requests.

Load Balancing in the Server Group


Capacity is assigned to every application server. With the SAP Web AS ABAP server, this
depends on the number of dialog work processes. With the SAP J2EE application server, the
capacity is determined in a similar way. The requests are distributed in turn to the server,
depending on its capacity. If Server A has twice as much capacity as Sever B, then A will
receive twice as many requests as B.

Server Selection and Load Balancing for HTTPS Requests


Since with HTTPS requests the SAP Web dispatcher is unable to read the URL, it can only
distribute HTTPS requests in turn to the HTTPS-enabled servers in the system. This also
takes into consideration the capacity of each server. To be able to process J2EE requests,
each HTTPS-enabled server must have integrated the J2EE server.
The ICM of the server that receives the HTTPS request can encode the URL and then decide
whether the request should be sent to the ICF or to the integrated J2EE server.
See also:
SAP Web Dispatcher and SSL [page 95]

Server Groups in the Internet Communication


Framework
In the ICF (Internet Communication Framework [page 106], Transaction SICF) within the SAP
Web Application Server, all virtual host names that can be handled by the SAP Web AS (see
also Virtual Hosts [page 136]) are configured. Every virtual host name has a unique prefix
with which the URL begins.
You can find some services in the HTTP service tree (Transaction SICF) that provide
information about URL prefixes and logon groups. You can find these services in the tree
under sap/public/icf_info.

If you use HTTP Load Balancing Using the SAP Message Server [page 97],
/urlprefix outputs the list of URL prefixes that are handled in the ABAP part of the
SAP Web AS. This is how the message server finds out which URLs must be
forwarded where.

Web Application Server

620 SP 9

86

SAP Online Help

25.10.2002

/icr_urlprefix returns the same information, but for the SAP Web dispatcher, if this is
used for load balancing.

Since there can be no redirects when the SAP Web dispatcher is used, SAP
recommends this method.

/logon_groups specifies a list of URL prefixes for which a logon group is defined (in
Transaction SICF). The requests are only forwarded to the server that is defined in
this logon group. This is how a load distribution mechanism is implemented, based on
URLs.

/icr_groups outputs all servers (host names) and logon groups that you have
maintained in this system (Transaction SMLG).

The SAP Web dispatcher fetches this list from an SAP Web AS. It can use this list to:

decide whether it is an ABAP or a J2EE request

carry out load balancing for the server in question.

The procedure for this is described in detail in Server Selection and Load Balancing Using the
SAP Web Dispatcher [page 84].

Relevant Profile Parameters


The following parameters are described in Profile Parameter of the SAP Web Dispatcher
[page 87].

is/HTTP/default_root_hdl determined which root directory should be used: the ICF


(ABAP) root directory, or the J2EE server root directory. Permitted values are abap and
j2ee.

wdisp/max_server_groups specifies the maximum number of logon group entries


that can be managed in the message server. The default is 128.

wdisp/max_server_group_name_len specifies the maximum length of a logon group


entry; the default is 20.

wdisp/max_url_map_entries is the maximum length of the prefix entries that can be


managed in the SAP Web dispatcher; the default is 300.

wdisp/max_url_map_path_len specifies the maximum path length of the URL


mapping table of the SAP Web dispatcher. The default is 256.

wdisp/url_map_location The path in the HTTP service tree (Transaction SICF),


under which the URL mapping information for the SAP Web dispatcher is stored. The
default is /sap/public/icf_info/icr/urlprefix.

The SAP Web Dispatcher Profile Parameter


The following overview describes the profile parameter within the SAP Web dispatcher.

Use
The default values were selected so that you do not have to make any changes to these
parameters. You determine the point of access to your SAP system using parameter
icm/server_port_<xx> [page 49].

Web Application Server

620 SP 9

87

SAP Online Help

25.10.2002

You can however use the parameters to adapt the configuration to specific system
requirements.
See also: Example: Profile File of a SAP Web Dispatcher [page 91]

Prerequisites
Since the SAP Web dispatcher connects itself to the SAP message server and communicates
with it via HTTP, the following parameters must be set correctly in the SAP Web dispatcher
profile.

rdisp/mshost: Host name of the machine on which the message server is running

ms/http_port: The port on which the message server receives HTTP requests

Procedure
The following describes the parameters that you can use to configure the SAP Web
dispatcher. You can also find the parameters and documentation in Transaction RZ11.
Parameters

Meaning

Unit

Default
Value

wdisp/auto_refresh

The period of time after which the route


information tables of the SAP Web
dispatcher (server tables, group tables and
URL mapping tables) are periodically
updated.

Seconds

120

wdisp/max_servers

This parameter determines the maximum


number of entries in the SAP Web
dispatchers server table.

Whole
number
(between 64
and 4096)

128

wdisp/max_server_name_
len

This parameter specifies the maximum


length of an entry in the SAP Web
Dispatchers server table, that is, the
maximum length of an instance name (profile
parameter rdisp/myname of the individual
servers).

Whole
number
(between 32
and 128)

64

wdisp/max_server_group
s

This parameter determines the maximum


number of entries in the SAP Web
dispatchers group table.

Whole
number
(between 32
and 4096)

128

wdisp/max_server_group
_name_len

This parameter determines the maximum


length of an entry in the SAP Web
dispatchers group table.

Whole
number
(between 20
and 64)

20

You maintain logon groups in Transaction


SMLG.
wdisp/max_url_map_entr
ies

This parameter determines the maximum


number of entries in the SAP Web
dispatchers URL mapping table.

Whole
number
(between 100
and 10000)

300

wdisp/max_url_map_path
_len

This parameter determines the maximum


path length in the SAP Web dispatchers
URL mapping table.

Whole
number
(between 100
and 2048)

256

Web Application Server

620 SP 9

88

SAP Online Help

wdisp/server_info_loca
tion

wdisp/group_info_locat
ion

wdisp/url_map_location

wdisp/server_info
wdisp/group_info
wdisp/url_map_info

Wdisp/HTTPS/dest_logon
_group

25.10.2002

Specifies where the SAP Web dispatcher


obtains information about the SAP Web
Application Server, to which it can distribute
the Web requests.

Character
string

Specifies where the SAP Web dispatcher


obtains information about the server groups,
to which it can distribute the Web requests.

Character
string

Path in the HTTP service tree (Transaction


SICF), under which the URL mapping info for
the SAP Web dispatcher is stored.

URL path
name

You can use these parameters for testing


purposes. You can use them to have the
SAP Web dispatcher fetch information about
the servers, server groups and URL
mappings that are available from files and
not from the system (message server or
application server). You can then use these
parameters to specify the corresponding path
name.

Path name
(corresponds
to the
operating
system
convention)

This parameter is only relevant when


using HTTPS!

/msgserv
er/
text/logo
n
/sap/publ
ic/
icf_info/ic
r_groups
/sap/publ
ic/
icf_info/ic
r/urlprefix

Logon group
names

This parameter determines the logon group


for load balancing requests at the SAP Web
dispatcher. If a logon group is defined, the
requests are passed to the servers in this
group only. If no group is defined, the
requests can be passed to all of the servers
in the system.
You maintain logon groups in Transaction
SMLG in the system.
wdisp/HTTPS/sticky_mas
k

This parameter is only relevant when


using HTTPS!

Character
string

The last
12 bits of
the client
IP
address
are no
longer
significan
t (are not
distinguis
hed).

This parameter describes a bit mask for


client IP addresses. A clients IP address,
which connects with the Web dispatcher, is
linked using this bit mask (AND) and the
result is used for load balancing clients.
You can summarize groups of client IP
addresses.
This functionality is required because large
internet providers use several proxies (with
different IP addresses) but the clients must
be handled in the same way. This is
imperative for applications with server status
(stateful applications).

Web Application Server

620 SP 9

255.255.
240.0

89

SAP Online Help

wdisp/HTTPS/max_client
_ip_entries

25.10.2002

This parameter is only relevant when


using HTTPS!
This parameter specifies the maximum
number of entries in the mapping table
between the client IP address and the
application server.

Number of
entries
(integer
value)

50000

Number of
connections

32768

The memory for the mapping table is created


in the hosts shared memory.

The following specifies examples of memory


requirements with specific settings.
10000

entries

50000

entries

100000

entries

1048576

16777216

wdisp/HTTP/max_pooled_
con

entries

entries

1.8 MB

8.9 MB

17.8 MB

230 MB

3000 MB

This parameter determines the maximum


number of HTTPS connections in the
connection pool from the SAP Web
dispatcher to an SAP Web Application
Server.
You do not normally need to change the
default setting.

wdisp/HTTP/min_pooled_
con

Minimum number of HTTP connections that


are kept in the SAP Web dispatchers
connection pool for each application server.
This number of connections is kept before
the first HTTP request is received.

Number of
connections

wdisp/HTTPS/max_pooled
_con

This parameter determines the maximum


number of HTTPS connections in the
connection pool from the SAP Web
dispatcher to an SAP Web Application
Server.

Number of
connections

32768

You do not normally need to change the


default setting.

Web Application Server

620 SP 9

90

SAP Online Help

wdisp/HTTPS/min_pooled
_con

25.10.2002

Minimum number of HTTPS connections that


are kept in the SAP Web dispatchers
connection pool for each application server.
These connections are kept before the first
HTTPS request is received.

Number of
connections

Since for each HTTP connection in the pool


on the Web AS page, a thread is blocked in
the ICM, you should not change the default
value of 0!

When you set the maximum values, note that unnecessarily large values can
increase the SAP Web dispatchers memory consumption.
You can find a rule of thumb for memory consumption in SAP Web Dispatcher
[page 79].
You can find an example of a profile file in Example: Profile File of a SAP Web
Dispatcher [page 91].
Minimal Configuration for the SAP Web Dispatcher [page 92] describes a minimal
configuration for the SAP Web Dispatcher.

Example: Profile File of a SAP Web Dispatcher


A SAP Web Dispatchers profile file could be as follows:
In addition to the parameters that are only valid for the SAP Web Dispatcher, there are the
ICM parameters that are also valid for the SAP Web Dispatcher.
# SAPSYSTEMNAME must be set so that the default profile is
# read. If not, a warning is displayed on the console.
SAPSYSTEMNAME

= BIN

# SAPSYSTEM must be set so that the shared memory areas


# can be created.
# The number must be different from the other SAP instances
# on the host.
SAPSYSTEM

= 66

# Message Server Description


rdisp/mshost

= binmain

ms/http_port

= 8081

# SAP Web Dispatcher Parameters


wdisp/auto_refresh

= 120

wdisp/max_servers

= 100

# Parameters for the HTTPS Routing

Web Application Server

620 SP 9

91

SAP Online Help

25.10.2002

wdisp/HTTPS/dest_logon_group

= HTTPS

wdisp/HTTPS/max_client_ip_entries

= 100000

wdisp/HTTPS/sticky_mask

= 255.255.255.0

# Description of the Access Points


icm/server_port_0

= PROT=HTTP,PORT=80

icm/server_port_1

= PROT=ROUTER,PORT=443

# Description of the Resources


icm/min_threads

= 20

icm/max_threads

= 40

icm/max_conn

= 500

# Communication Buffer
mpi/total_size_MB

= 100

mpi/buffer_size

= 65536

See also:
You can find additional information about parameterization in the following sections.
Parameterizing the ICM and the ICM Server Cache [page 45]
The SAP Web Dispatcher Profile Parameter [page 87]

Minimal Configuration for the SAP Web Dispatcher


A minimal configuration file for the SAP Web Dispatcher contains the following parameters:

SAPSYSTEMNAME

SAPSYSTEM

rdisp/mshost:

ms/http_port

icm_server_port_<xx>

The profile file would then look as follows, for example:


# SAPSYSTEMNAME must be set so that the default profile is
# read. If not, a warning is displayed on the console.
SAPSYSTEMNAME

= BIN

# SAPSYSTEM must be set so that the shared memory areas


# can be created.
# The number must be different from the other SAP instances
# on the host.
SAPSYSTEM

= 10

# Message Server Description

Web Application Server

620 SP 9

92

SAP Online Help

25.10.2002

rdisp/mshost

= binmain

ms/http_port

= 8081

# Description of the Access Points


icm/server_port_0

= PROT=HTTP,PORT=80

icm/server_port_1

= PROT=ROUTER,PORT=443

See also:
You can find additional information about parameterization in the following sections.
Parameterizing the ICM and the ICM Server Cache [page 45]
The SAP Web Dispatcher Profile Parameter [page 87]
Example: Profile File of a SAP Web Dispatcher [page 91]

SAP Web Dispatcher as a URL Filter


Use
You can use the SAP Web dispatcher as a URL filter. This means requests are accepted or
rejected by the SAP Web dispatcher depending on their URL.

Motivation
This SAP Web dispatcher function provides additional security. In addition to the secure
configuration with a firewall and a demilitarized zone (see the graphic in SAP Web Dispatcher
[page 79]), you can use the URL filter to prevent external users from executing applications.
Even if users are able to log onto the SAP System without permission, you can set explicitly
which applications can be executed.

Prerequisites
You are using the SAP Web dispatcher as the only point of access for HTTP(S) requests.

Functions
Use the URI permission table to determine the rules according to which the SAP Web
dispatcher should handle incoming URLs. This is a file that lists the rules in rows.
The syntax is based on the syntax of the SAProuter route permission table (see also Route
Permission Table [External documentation]).

Each row has the form


P/D/S <URI pattern>
where the letter at the start of the row has the following meaning.

P lets the request through. It is forwarded by the SAP Web dispatcher to the
appropriate application server.

D refuses the request and sends a message to the client.

S only allows secure connections (HTTPS) for the URL prefix.

Web Application Server

620 SP 9

93

SAP Online Help

25.10.2002

<URI pattern> is the section of the URL that is labeled in the Cache Key [page
37] section as translated path.
You can use the wildcard character *, but only at the start or the end of the <URI
pattern> string.
In addition to profile parameter wdisp/permission_table there are further profile
parameters that you can use to control the size of the URI permission table. You can find
detailed information as well as the maximum and minimum values in the parameter
documentation (Transaction RZ11).
Parameters

Unit

Meaning

Default
Value

wdisp/max_permitted_uri_l
en

Integer

Maximum length of the URI (number of


characters)

2048

wdisp/permitted_uri_char_
range

n-m

The range in which the URL characters


must be located (ASCII). 32-127 are the
normal keyboard characters, for
example. No entry permits all
characters in the URL.

wdisp/max_permission_ta
ble_size

Integer

Maximum number of entries (rows) in


the URI permission table.

300

wdisp/max_permission_ta
ble_entry_size

Integer

Maximum number of characters (rows)


in the URI permission table.

256

n<m
Integer

Activities
If you want to use the SAP Web dispatcher as a URL filter, create a file <ptabfile> in
which you enter the rules. Note that every URL is evaluated according to the first match
strategy, that is, the first rule in the table that matches the URL is used. The table is no longer
searched for any (other) rules. Below is an example of such a file.
If you have maintained the table, you must maintain parameter wdisp/permission_table
in the SAP Web dispatcher profile:
wdisp/permission_table = <ptabfile>,
where <ptabfile> is the absolute or relative path of the file.
See also:
Example: Profile File of a SAP Web Dispatcher [page 91]

Example
A URI permission table could look like this:
# SAP Web Dispatcher test permission table
P

/sap/bc/test.cgi

*.cgi

/sap/bc/cachetest

/sap/bc/public/*

/sap/bc/ping

The table reflects the following configuration.


The CGI script test.cgi in /sap/bc may be executed (row 1), the request is forwarded
according to load balancing to the appropriate SAP Web AS (see also Server Selection and

Web Application Server

620 SP 9

94

SAP Online Help

25.10.2002

Load Balancing Using the SAP Web Dispatcher [page 84]). Otherwise, no CGI script may be
executed (row 2).

First match means that if the first 2 rows in the table were swapped,
/sap/bc/test.cgi could not be executed either: since the first row watches
for the URL prefix, the second is not evaluated at all.
The HTTP request handler behind ICF service /sap/bc/cachetest may be executed, as
can all ICF services in /sap/bc/public/ as well as the connection test service
/sap/bc/ping (rows 3-5). You should not execute any ICF services that have not explicitly
been mentioned here (row 6). The SAP Web dispatcher refuses this request.

SAP Web Dispatcher and SSL


Unlike HTTP, with HTTPS (end-to-end SSL) the SAP Web dispatcher cannot read any
request data and therefore cannot interpret any session cookies that may be available (with
stateful applications). The necessary information for forwarding the request to the correct
server is therefore missing. The SAP Web dispatcher cannot decide whether the request
belongs to a stateless or a stateful application.
As a result, the SAP Web dispatcher forwards the encoded data unchanged to the application
server, where the data is finally decoded.
The only distinguishing criterion that is available to the SAP Web dispatcher is the client IP
address. As a result, the SAP Web dispatcher manages a mapping table between the client
IP address and the application server. If a request from a client IP address is sent to
application server X, all subsequent requests from this client IP address must also be sent to
this sever, since it could well be a stateful application. Load balancing therefore only takes
place upon the very first client request.

Problems
This process hides the following problems.

All companies use proxies. This means that requests that are sent via a proxy are sent to
one server. As a result, this cancels load balancing with the first request.

Large companies use several parallel proxies (which in turn also balance load) as access
to the Internet. This means that a request from the same client is sent via proxy A, and a
later request from the same client, belonging to the same session, is sent via proxy B to
the SAP Web dispatcher, and therefore has a different client IP address.

Solution
You can use profile parameter wdisp/HTTPS/sticky_mask to group several client IP
addresses into a logical address. Profile Parameter of the SAP Web Dispatcher [page 87]
describes the exact functions of this parameter.
The default is: Mask 255.255.240.0 is joined with the real IP address UND; this hides the
lowest 12 Bits, that is, 124.94.55.1 and 124.94.55.99 are then interpreted as the same.

Mapping Table
The mapping table, which is used by the SAP Web dispatcher to manage client IP addresses
and the application severs that are assigned, has the following properties.

Web Application Server

620 SP 9

95

SAP Online Help

25.10.2002

The size of the mapping table depends on the sticky mask. The more bits that are hidden,
the smaller the mapping table becomes. Profile parameter
wdisp/HTTPS/max_client_ip_entries defines the maximum number of entries that
this table can hold. Profile Parameter of the SAP Web Dispatcher [page 87] describes the
exact functions of this parameter.

Note: If the mapping table is full, that is, the value of


wdisp/HTTPS/max_client_ip_entries has been reached, the SAP Web
dispatcher no longer balances the load! The parameter should therefore always
be set according to your needs and resources.

There is no timeout for the entries in the mapping table. If a server is shut down, the
context is deleted on this server. The system looks for a new server for the client IP
address.

Selecting a Suitable Application Server


HTTP-Enabled Application Server
With parameter wdisp/HTTPS/dest_logon_group (see Profile Parameter of the SAP
Web Dispatcher [page 87]) you define a logon group with HTTPS-enabled application
servers, to which all HTTPS request are then sent.
ABAP or J2EE Server
Since the SAP Web dispatcher cannot decide whether a request should be processed by an
ABAP or a J2EE server, all servers in the logon group for HTTPS requests must provide the
same services. Of course, all servers must be HTTPS-enabled, and one of the following
points must apply:

All servers offer J2EE and ABAP

All servers offer ABAP only

All servers offer J2EE only

High Availability of the SAP Web Dispatcher


You have different options to make the SAP Web Dispatcher highly available.

Monitoring the SAP Web Dispatcher with an External HA Tool


The tool monitors the SAP Web Dispatcher and restarts it if the SAP Web Dispatcher
crashes. See also the description of option -shm_attach_mode in Operating the SAP Web
Dispatcher [page 82].

Using Option -auto_restart


The following procedure applies to UNIX platforms only. This process is not possible on
Windows and iSeries since they do not support this type of high availability.

You can achieve high availability at process level with this option. It does not help
if the whole machine crashes.

Web Application Server

620 SP 9

96

SAP Online Help

25.10.2002

You start the SAP Web Dispatcher with the option -auto_restart to achieve the following
behavior.
The necessary resources (shared memories, sockets, administration structures) of the SAP
Web Dispatcher are loaded when it is started. This process is then duplicated by the system
call fork(), that is, there are now two processes that know exactly the same shared
memories, sockets and administration structures. The original process (father process F)
takes over the monitoring function (watchdog), whilst the new process (child process C) takes
care of the actual tasks of the SAP Web Dispatcher (forwarding requests, load balancing,).
The monitoring process V then checks every n seconds the status of the SAP Web
Dispatcher process C.
If the K process ends (whether this is required or unexpected), the watchdog V recognizes
this and the state of the process that was frozen after it was started is duplicated again (fork).
This has the following advantages:

Fast availability of the SAP Web Dispatcher, because the resources do not have to be
created for the first time

Zero downtime, because requests to the SAP Web Dispatcher do not get lost but are
stored in the system queue and can be processed after the process is duplicated by the
SAP Web Dispatcher work process (C). Requests that were being processed when the
crash happened will, of course, be lost.

Ending the highly available SAP Web Dispatcher


If you want to end the SAP Web Dispatcher, ensure that you end the watchdog process (V)
(this is started if you end the other process!). To do this, send a SIGINT to the watchdogs
PID. You can take this from the trace file dev_webdisp_watchdog.
Ending the watchdog also ends the SAP Web Dispatcher work process C.

If only the SAP Web Dispatcher work process is ended with SIGINT, the
watchdog starts this process again.

HTTP Load Distribution Using SAP Message


Server
SAP recommends that you use the SAP Web Dispatcher [page 79] as the
starting point for your Web queries. This is then used as the access point for your
network and also executes load balancing for HTTP requests.

Uses
Usually, an SAP System consists of several application servers which share the network load.
Load distribution is handled by the message server (there is one message server in an SAP
System). When a user logs on, the message server assigns him or her to the application
server that currently has the smallest load. This procedure is also used for incoming HTTP
requests.

Web Application Server

620 SP 9

97

SAP Online Help

25.10.2002

If you are using HTTP load distribution on your system, you cannot use additional
Virtual Hosts [page 136].

Process
Every application server that is participating in load sharing tells the message server how
many work processes it can provide and whether it accepts HTTPS connections. At the start
of a connection, an Internet client first connects to a message server (which must also be
HTTP-compatible). The message server tells the client via a redirect which application server
it should connect to. Obviously, HTTPS requests are only sent to HTTPS-compatible
application servers.
For this procedure to work, the message server has to open one or several additional ports.
The following profile parameters are used for this:

ms/http_port
This parameter refers to an additional HTTP port that the message server opens to
redirect HTTP requests. This parameter refers to an additional HTTP port that the
message server opens to redirect HTTP requests.
Default setting: no additional port

Therefore, you must set this parameter if you want to activate HTTP load
distribution.

ms/https_port
This parameter refers to a HTTPS port that the message server opens to redirect HTTPS
requests. This parameter refers to an additional HTTP port that the message server
opens to redirect HTTP requests.
Additional SSL parameters must be set for HTTPS, so that SSL can be used. Also, the
message server must be run as a multi-threaded program, as every HTTPS request is
processed in its own thread.

There are also other parameters with default values that do not need to be changed. These
parameters are as follows:

ms/http_max_ports:
Maximum number of additional HTTP ports that the message server can open. Default
20.

ms/http_max_clients:
Maximum number of HTTP clients that can log on simultaneously to the message server.
Default 1000.

ms/http_timeout:
Timeout for network operations. If there is no activity on the connection within this time
period, the connection to the HTTP client is terminated. The timeout value is expressed in
seconds. Default 20.

ms/http_bufferln:
Maximum readable length of the HTTP header. This value is expressed in bytes. Default
65636.

If SSL is being used, the SSL parameters must be set correctly (see SSL
documentation).

Web Application Server

620 SP 9

98

SAP Online Help

25.10.2002

SAP Web Application Server: Web Server and Web


Client
The SAP Web Application Server can function both as a Web server and as a Web client. In
its Web server role, it can accept HTTP requests from any Web client (for example, a
browser), process the requests, and send a response back to the client.
In its Web client role, the SAP Web Application Server creates HTTP requests in an ABAP
program, and sends the requests to a Web server. The client then receives the responses
and proceeds on the basis of the responses.
In both cases, both stateful (context is maintained) and stateless (context is terminated every
time) modes can be used (see Stateful and Stateless BSP Applications [page 381]).
Choose the links below for more information on SAP Web Application Server in both server
and client roles:
Server Role [page 99]
Client Role [page 100]

Server Role
The following illustration shows the entire process, from the sending of a HTTP request from
a Web client, to receipt of the response by the client.

Application Program
(e.g. BSP Application)

HTTP Extension, e.g. Business


Server Pages (CL_HTTP_EXT_BSP)

Internet Communication Framework

Response
t
ne
er
t
In

ABAP

Request

Task Handler

Dispatcher

ICM

Client (Web Browser)

e
rn
te
n
I

HTTP Server (SAP Web Application Server)

Memory Pipes

HTTP Client

The ICM receives the HTTP request, as the URL contains the combination of server name
and port to which the ICM responds.
The ICM decides on the basis of the URL whether local handlers need to be called, and if so,
which ones. The procedures for the handlers redirect handler, file access handler, server
cache handler, and CGI handler are described above. If the default handler, the SAP R/3
handler, is used, the following occurs:

The ICM stores the data it receives in a memory pipe (located in shared memory) and
informs the dispatcher.

Web Application Server

620 SP 9

99

SAP Online Help

25.10.2002

The dispatcher enters the ICM request in the dispatcher queue, creates a new context
(unless the system is in stateful mode and a context already exists), and chooses a work
process.

The work process (task handler) reads the data from the memory pipe, processes the
request (via ICF and the HTTP request handler), and writes the response back into the
MPI. Then, the work process signals to the ICM that it has finished processing the
request.

The ICM sends the response data back to the client.

For a detailed description of the ICF procedure, see Internet Communication Framework
[page 106].
The section Client Role [page 100] describes in detail the client role of SAP Web Application
Server.

Client Role
In its client role, the SAP Web Application Server creates HTTP requests in an ABAP
program, and processes the responses.

HTTPServer

HTTP Client (SAP Web Application Server)

et
rn
e
nt

Web Server

ICM

Memory Pipes

Dispatcher

Task Handler

ABAP

Internet Communication Framework

ABAP Application Program

Request
et
rn
e
t
In

Response

If the SAP System is the client, that is, if a work process wants to send a request to the
Internet, this procedure works in reverse.
The work process writes the data to be processed into an MPI and sends the request to the
ICM via a network connection, using TCP/IP. The ICM then processes the data it receives
from the MPI and writes a response back into the MPI. For a detailed description of the ICF
process, see Interaction Model [page 156].

Web Application Server

620 SP 9

100

SAP Online Help

25.10.2002

Integrating the SAP J2EE Engine


Uses
With the SAP Web Application Server 6.20, you can integrate the SAP J2EE Engine in your
system.
The architecture of this type of system looks as follows:
SAP Web Application Server with Integrated SAP J2EE Engine
GUI

GUI

Dispatcher

Req.
for
JAVA

ICM

In

t
ne
r
te

Req.
for
ABAP

Task
handler

Gateway

Client (Web Browser)

Message
server

ABAP

Work processes

SAP J2EE Engine

DB

You can configure the SAP Web AS so that it:

can only process ABAP requests (such as HTTP(S) requests that should be processed
by the ICF) (such as SAP Web AS 6.10)

can process both ABAP and J2EE requests (that is, HTTP(S) requests that should be
processed by the SAP J2EE AS) (as displayed in the graphic)

can only process J2EE requests (see also Using the SAP J2EE Engine with the
Standalone Dispatcher [page 103]).

The following graphic displays an SAP system that contains all three types of server.

Web Application Server

620 SP 9

101

SAP Online Help

25.10.2002

ICM
ICM

SAP Web Dispatcher

Client (Web Browser)

Task
handler

ABAP

SAP J2EE
Engine

Dispatcher

Task
handler

ABAP

DB

Gateway

Req.
for
ABAP
et
rn
e
t
In
Req.
for
JAVA

Dispatcher

Gateway

ICM

Whole SAP System: SAP Web AS Instances with SAP Web Dispatcher

Message
server

Standalone Dispatcher
dpj2ee
SAP J2EE
Engine

Integration
To operate the SAP J2EE Engine, the following services must be active in the HTTP service
tree (Transaction SICF):

/sap/public/icman The ICM uses this service to forward requests to the J2EE server

/sap/public/icf_info provides the SAP Web Dispatcher [page 79] with information about
the logon groups, server load and so on. These services must be activated so that server
selection and load balancing using the SAP Web dispatcher [page 84] can be carried out.

See also:
Activating and Deactivating an ICF Service [page 147]
Internet Communication Framework [page 106]

Functions
Distributing HTTP Requests Using the SAP Web Dispatcher
The SAP Web Dispatcher [page 79] must now decide which SAP Web AS will receive the
request. Is it a request for the WAS server (ABAP stack) or for the J2EE server (Java stack)?
The procedure for this is described in section Server Selection and Load Balancing Using the
SAP Web Dispatcher [page 84].

Processing HTTP Requests Using the ICM


In the case where the SAP Web AS can process both ABAP and Java requests, (as displayed
in the graphic at the beginning of the section), the ICM must decide for each incoming HTTP
request whether it should pass the request to the ABAP (the Internet Communication
Framework [page 106]) or to the SAP J2EE Engine for processing.
This is particularly unclear if no SAP Web dispatcher is available to the system. The ICM uses
the URL prefix to decide whether this request should be passed to the ICF (ABAP) or to the
SAP J2EE Engine. To do this it uses the same process as the SAP Web dispatcher.

Web Application Server

620 SP 9

102

SAP Online Help

25.10.2002

Caching in the ICM


You can also use the Internet Server Cache [page 34] with the J2EE server, in order to store
HTTP responses (such as HTML pages or images). The next time, the request can be
retrieved directly from the cache.
See also:
Using the SAP J2EE Server with the Standalone Dispatcher [page 103]
SAP J2EE Engine Administration [page 103]
Profile Parameters for the SAP J2EE Engine [page 104]

Using the SAP J2EE Engine with Standalone


Dispatcher
In the previously described scenario, an SAP Web AS must always run together with the SAP
J2EE Engine, so that the J2EE Engine can be involved in the load balancing mechanism of
the SAP Web Dispatcher [page 79].
If, however, you want to use the J2EE Engine without ABAP and the SAP Web ASs other
functions, you can use the standalone dispatcher (dpj2ee), which does not require a
database, any work processes or a SAP gateway. This dispatcher starts all of the necessary
processes (ICM, J2EE Engine), connects to the message server and sends this the logon
data for HTTP(S) and J2EE(S). The SAP Web dispatcher can get all of the information it
needs for load balancing from this dispatcher.
From the point of view of the SAP Web AS, this server is not visible and it is not displayed in
the server overview in Transaction SM51. This server can therefore take part in load
balancing but naturally only for those requests that should be forwarded to the J2EE Engine.
This server requires the same environment as the usual SAP Web AS, that is, a directory
structure, profile files and so on. The trace output is written to file dev_j2ee in the work
directory.

You must set profile parameter icm/dpj2ee [page 59] to TRUE to be able to
operate the standalone dispatcher.

SAP J2EE Engine Administration


Use
You can manage the SAP J2EE Engine from the SAP Web Application Server, that is, you
can start and stop it in different ways. You can find the functions in the ICM monitor
(Transaction SMICM or by choosing Administration System Management Monitor
System Monitoring Internet Communication Manager).

Integration
You can use the SAP J2EE Engine with the SAP Web Application Server 6.20. The Java
connector JCo enables the two servers to be closely connected with each other.

Web Application Server

620 SP 9

103

SAP Online Help

25.10.2002

Prerequisites
You are using the SAP Web Application Server with the integrated SAP J2EE Engine.

So that the dispatcher can start the SAP J2EE Engine, you must set parameter
rdisp/j2ee_start to 1. You can make this setting dynamically in Transaction
RZ11.

Functions
On the initial screen of the ICM monitor (Transaction SMICM), choose Administration
J2EE Server.
The following functions are available:

Sending a Soft Shutdown (With or Without a Restart)


The SAP Web Application Servers dispatcher sets the restart flag for the SAP J2EE Engine
and sends the SOFTSHUTDOWN message to the J2EE server. The dispatcher does not
actively close the connection, the SAP J2EE Engine must close itself instead. If the
application server is restarted, the SAP J2EE Engine is restarted by the dispatcher.

Sending a Hard Shutdown (With or Without a Restart)


The SAP Web Application Servers dispatcher sets the restart flag for the J2EE Engine and
sends the SOFTSHUTDOWN message to the SAP J2EE Engine. The dispatcher does not
actively close the connection, the SAP J2EE Engine must close itself instead. If the
application server is restarted, the SAP J2EE Engine is restarted by the dispatcher.

Ending the Process (With or Without a Restart)


The SAP Web Application Servers dispatcher sets the restart flag for the SAP J2EE Engine
and sends a signal to the process (shell or Java process). If the application server is
restarted, the SAP J2EE Engine is restarted by the dispatcher.

Restart Yes/No
This sets the SAP J2EE Engines restart flag.
See also:
Integrating the SAP J2EE Application Server [page 101]

Profile Parameters for the SAP J2EE Engine


The following overview describes the profile parameter within the SAP J2EE Engine.
You can also find the parameters and documentation in Transaction RZ11.
Parameters

Meaning

Unit

Default
Value

icm/HTTP/j2ee_<xx>

You use this parameter to determine the ICMs


communication with the J2EE server.

Characte
r string

Web Application Server

620 SP 9

104

SAP Online Help

25.10.2002

icm/HTTP/j2ee_<xx> = HOST=<host>,
PORT=<port>,
CONN=<Anzahl
Verbindungen>
Meaning:
<xx> stands for the number of the entry to be
specified. Several assignments between the
URI prefix and the J2EE server, numbered in
ascending order from 0, can be specified.
<port>: Port number or name of the list port
of the J2EE server to which the ICM should
connect.
<Number of connections>: The number of
network connections to the J2EE server can be
defined with this parameter. You can configure
either a fixed number of connections or an area
(min-max). If an area is specified, the ICM
opens min connections to the server. If
necessary, new connections are opened until
the maximum value is reached. If you specify a
fixed number (or if the minimum value is the
same as the maximum value), these
connections are already opened when the
server starts.

icm/HTTP/j2ee_0 = PREFIX=/,
HOST=localhost, CONN=0-30, PORT=21
icm/HTTP/j2ee_0 = HOST=192.55.76.20,
PORT=8080, CONN=50

This parameter only makes sense if the


parameter rdisp/j2ee_start is also set.
icm/dpj2ee

If the system is not started using the SAP


dispatcher "disp+work", but using the
standalone dispatcher "dpj2ee" instead, the
ICM must be informed about this using this
parameter, and the value of the parameter
must therefore set to True.

Logical
value

FALSE

Integer
(number
of
attempts)

10

Logical
value

If you try to start the standalone dispatcher


although the parameter has the value FALSE,
the standalone dispatcher dpj2ee ends
immediately.
rdisp/j2ee_error

Number of incorrect attempts to start a J2EE


server before the restart is deactivated.
By dynamically switching using parameter
rdisp/j2ee_start, you can reactivate the restart.

rdisp/j2ee_start

You can use this parameter to activate or


deactivate starting the J2EE Engine.
The start of the J2EE Engine is automatically
deactivated if a specific number of attempts
(rdisp/j2ee_error) to start the server failed.

Web Application Server

620 SP 9

105

SAP Online Help

25.10.2002

You can reactivate the start by dynamically


changing this parameter to the value of 1.
rdisp/j2ee_start_lazy

If this parameter is set to 1, the following


applies:

Logical
value

Seconds

60

If an SAP J2EE Engine should be started


(parameter rdisp/j2ee_start ), it is not started
until the ABAP runtime environment has been
fully initialized. This avoids problems that are
caused by a long initialization phase.
If the parameter has the value 0 (default), then
the SAP J2EE Engine can be started without
waiting for the ABAP initialization.
rdisp/j2ee_timeout

Within this time span, the J2EE Engine must


log on to the dispatcher. If not, it is assumed
that the J2EE Engine had problems starting
and it is started again. You can determine the
number of incorrect start attempts using
parameter rdisp/j2ee_error. If this number of
start attempts failed, this deactivates the J2EE
Engine from starting.
By dynamically switching using parameter
rdisp/j2ee_start, you can reactivate the restart.

Internet Communication Framework


Purpose
The Internet Communication Framework (ICF) provides the environment for handling HTTP
requests in work processes on an SAP System (server and client).
The ICF can, for the most part, use the same interfaces for the client side and the server side.
The interface IF_HTTP_SERVER [page 117] is used for the server side, and
IF_HTTP_CLIENT [page 167]for the client side. The interfaces IF_HTTP_RESPONSE and
IF_HTTP_REQUEST [page 119] remain unchanged and can be used in both roles.
If you are using the system as a server, you need a HTTP Request Handler [page 107], which
you can create yourself. Defining the HTTP request handler yourself allows you to use the
ICF flexibly in your application. However, HTTP request handlers are also shipped with the
SAP System.
The HTTP request handler for Business Server Pages (BSP) is particularly important here.
You can use this handler to develop Web applications. The functions of BSPs and how to
work with BSPs are explained in Creating Web Applications with Business Server Pages
[page 170]
This section deals with the ICF on a general level. It describes what HTTP request handlers
are and how you create them. It also describes the client role of the ICF.

Integration
For information on what layer the Internet Communication Framework occupies in SAP Web
Application Server, see the section Interaction Model, both for Server Side [page 108] and
Client Side [page 156].

Web Application Server

620 SP 9

106

SAP Online Help

25.10.2002

Features
The documentation first describes the server role, then the client role.
HTTP Communication Using the SAP System as a Server [page 107]
HTTP Communication Using the SAP System as a Client [page 155]

HTTP Communication Using the SAP System as a


Server
Purpose
You can use the Internet Communication Framework to enable the system to process HTTP
requests as a server.
The HTTP Request Handler [page 107] implements the application logic called by the
request.
The ICF provides interfaces that make it possible to use the HTTP connection. The interface
IF_HTTP_SERVER [page 117] models the entire HTTP connection. This interface is used to
access the request and the response.

Prerequisites
You have configured SAP Web Application Server so that it can receive requests from the
Internet. For more information on this, see SAP Web Application Server Architecture [page
19]. The parameter icm/server_port_<xx> [page 49] is used to parameterize the Internet
Communication Manager.

Process
First, you need a HTTP Request Handler [page 107]. (The HTTP request handler
CL_BSP_EXTENSION is delivered with the system so that you can use Business Server
Pages. For more information on this, see Creating Web Applications with Business Server
Pages [page 170].)
The section Design [page 108] describes the Interaction Model [page 108], which defines the
behavior of the ICF in the server role.
The section ICF Interfaces [page 115] describes the interfaces that the ICF provides for
working with a HTTP connection. You need these when implementing your HTTP request
handler.
See Using the ICF [page 134] for information on how to make the HTTP request handler
known to the ICF using transaction SICF.

HTTP Request Handler


Definition
A HTTP request handler is a program (or, to be more exact, an ABAP class). It is identified by
a Uniform Resource Locator (URL) and receives HTTP requests that use this URL. The HTTP
request handler receives the data sent in a request (for example, data coded in the URL as
query string information), executes certain handler-specific processes, and creates a
response to the HTTP request.

Web Application Server

620 SP 9

107

SAP Online Help

25.10.2002

Use
An example of a typical scenario involving a HTTP request handler is a handler that provides
a Web browser with SAP reports. The HTTP request handler usually reads the selection
criteria of the report, which are sent with the request (for example, in the URL), calls the
relevant report from the SAP System, converts the results to HTML, and returns them to the
requesting Web browser. To do this, the HTTP request handler must be able to access the
data and send a response back to the client.
The Internet Communication Framework must guarantee that all this is possible.
See also:
Design [page 108]
ICF Classes and Interfaces [page 115]
Using the ICF [page 134]

Design
This section describes the Interaction Model [page 108], which is the basis of the ICF.
This section also deals with the following topics:
Stateless and Stateful Model [page 112]
Logging On To SAP Web Application Server [page 113]

Interaction Model
To understand the design of the interfaces described in detail in ICF Interfaces [page 115], it
is first necessary to be familiar with the interaction model between the client (usually a Web
browser), the Internet Communication Framework (ICF), the HTTP request handler, and the
application.
The Internet Communication Framework (ICF) serves as the bridge between the C kernel in
the SAP System and the application program (in ABAP).
The following paragraphs deal only with the server role. The client role is dealt with separately
in HTTP Communication Using the SAP System as a Client [page 155].
When the ICM receives a HTTP request that is to be processed in a work process, the task
handler takes over (see graphic). This starts the ICF controller. From this point on, we are
only concerned with ABAP and the Internet Communication Framework. The Internet
Communication Framework consists of ABAP classes and interfaces.

Web Application Server

620 SP 9

108

SAP Online Help

25.10.2002

HTTP-Client

HTTP-Server (SAP Web Application Server)

Response
et
rn
e
t
In

10

ICF Controller

ABAP

Memory Pipes

Taskhandler

10

8
9

HTTP-Extension (CL_HTTP_EXT)

Request

ICF Manager (CL_HTTP_SERVER)

ICM

Client (Web Browser)

ne
er
t
In

Dispatcher

Internet Communication Framework

The following steps are involved in the interaction process (also refer to the graphic and the
additional notes below):
1. The function module HTTP_DISPATCH_REQUEST is called.
2. An object of the class CL_HTTP_SERVER is created (see IF_HTTP_SERVER [page 117]).
The object is flagged as a server control block.
3. The HTTP request is read.
4. The server control clock is filled with data from the HTTP request.
5. The desired HTTP request handler is selected using the URL (the URL is mapped to the
HTTP request handler in transaction SICF).
6. The client logs in.
7. The HTTP request handler is called (the handler can then process the request data, call
applications that need to access the response object, and so on).
8. The ICF controller resumes control at this point. The ICF controller may transfer control to
further handlers (depending on the settings in SICF).
9. Another HTTP stream is created (serialization of the response).
10. The result is written to memory pipes, and is sent back to the client via the ICM (see SAP
Web Application Server Components [page 20]).
In the graphic, the red arrows represent the control flow, and the blue arrows represent the
data flow.
These steps are described in detail in the following sections:

Calling the Function Module HTTP_DISPATCH_REQUEST (1) [page 110]

Creating the Server Control Block (2) [page 110]

Filling the Server Control Block (4) [page 110]

Selecting and Calling the HTTP Request Handler (HTTP Extension) [page 111]

Client Logon (6) [page 110]

Processing the Request Using the HTTP Extension (7) [page 111]

Web Application Server

620 SP 9

109

SAP Online Help

25.10.2002

Sending Back the Response (9-10) [page 112]

Calling the Function Module


HTTP_DISPATCH_REQUEST (1)
The purposes of this function module are to select the correct HTTP request handler, to
create a suitable representation for the HTTP request, and to transfer control to the selected
handler.
After the response is created, the function module becomes active again.
The function module fulfils the tasks if the ICF controller, as represented in the graphic.
The next step is to Create the Server Control Block (2) [page 110].

Creating the Server Control Block (2)


The server control block is an object in the class CL_HTTP_SERVER. This class implements
the interface IF_HTTP_SERVER.
The object encapsulates all information of a HTTP connection. It contain structures for HTTP
request and response, the session ID, and other information about the connection. Initially, all
fields are empty.
The structure is described in detail under IF_HTTP_SERVER [page 117].
The next step is Filling the Server Control Block (4) [page 110].

Filling the Server Control Block (4)


Once the incoming HTTP request has been read, the object that was created in step 1 above
is filled with content. At the beginning of the process, the attribute Request always has
content, while the attribute Response is always empty. During the processing procedure by
the HTTP request handlers, IF_HTTP_SERVER [page 117] calls the relevant methods and
the response object is thus filled or modified.
Then comes the Client Logon (6) [page 110].

Client Logon (6)


The client (Web browser) must identify itself in this step. Usually, basic HTTP authentication
is used, but this is not mandatory. In our example, the return code 401 is sent from the ICF
controller to the Web browser. The Web browser then creates a popup that is used for
authentication. The user enters his or her username and password, and this data is sent
Web Application Server

620 SP 9

110

SAP Online Help

25.10.2002

directly to the SAP System. When the client logs on to the SAP System, the default client and
the default language of the application server are used.
The logon data required for a HTTP request handler (or, to be more precise, for the service to
which this HTTP request handler is assigned) can also be set in the service table (via
transaction SICF). For details on this, see Logon Data [page 143].
If the logon procedure fails, further attempts are made before the procedure terminates.
Once logon has executed successfully, an authorization check is carried out.
Next comes Selecting and Calling the HTTP Request Handler (HTTP Extension) [page 111]

Selecting and Calling the HTTP Request Handler


(HTTP Extension)
The ICF controller now uses the URL to identify the virtual host and the HTTP request handler
maintained in transaction SICF (see Creating a Service [page 140]). For this to be possible,
the URL has to be parsed.
The parsing procedure involves the use of URL prefixes (a URL prefix is a sub-path within the
path specified in the URL).
If the URL is http://hostname:port/bc/ping, the system first checks whether
hostname:port is defined as a Virtual Host [page 136]. If it is not defined as a port, the
virtual host default_host is used. The system then looks in the corresponding service tree
in SICF for the service /bc/ping, and the relevant HTTP request handler is called.
Therefore, a HTTP request handler is always defined by a sub-path within the path specified
by the URL (also known as URL prefix). Also, a single URL prefix can define more than one
HTTP request handler.
The path components are processed from left to right in order to find the corresponding ICF
services.

Since any number of HTTP request handlers can be set for a service, *** For
details of this, see IF_HTTP_EXTENSION [page 130].
Next comes Processing the Request Using the HTTP Extension (7) [page 111]

Processing the Request Using the HTTP Extension


(7)
The programmer decides what the HTTP request handler does with the server control block,
and sets this in the request handling method HANDLE_REQUEST()of the interface
IF_HTTP_EXTENSION.
The following example gives an example of what the HTTP request handler can do.

First, the request handler gets the request object from the server control block.

Web Application Server

620 SP 9

111

SAP Online Help

25.10.2002

The method HANDLE_REQUEST() is called. A reference to the interface


IF_HTTP_SERVER is given as an argument, so that the HTTP request handler
can work with the request and response data.
The HTTP request handler can now execute its processes and create a
response. It can work on the data as much as required (with the given methods),
call other programs, use databases, and so on. During processing, the response
object (the attribute RESPONSE of the server control block) is filled with content; in
other words, the response is prepared for the HTTP client.
As soon as these processes are finished, the HTTP request handler returns
control to the ICF controller by exiting from the method HANDLE_REQUEST().
Finally comes Sending the Reply (9-10) [page 112].

Sending Back the Response (9-10)


The Internet Communication Framework now has control again.
Now the data that is currently located in the server control block (an object in the class
CL_HTTP_SERVER [page 117]) must be converted back to a HTTP data stream (see the
graphic in Interaction Model [page 108], serializing the response).
Once this is done, the ICF controller sends the data stream back to the client via the task
handler and the ICM.

Stateless and Stateful Model


The Internet Communication Framework supports both stateful and stateless communication
in the server role. The ICF can therefore extend the lifetime of a special HTTP request
handler beyond that of an individual request.
Stateless mode is the default setting, that is, the attribute STATEFUL of the server control
block has the value CO_DISABLED (see IF_HTTP_SERVER [page 117]). The programmer
should carefully consider whether stateful mode is required, as this mode places more
demands on the server, which can result in poorer performance.
You should note the following points when working in stateful mode:
1. In a single session, more than one HTTP request handler can be involved in a series of
requests (the session is restricted by the lifetime of the corresponding user context).
2. There is never more than one instance of a special HTTP request handler in existence at
any one time within the one session. In other words, a corresponding HTTP request
handler instance is either re-used for sequential requests (default) or is reinstantiated for
each individual request (if desired, by the HTTP request handler itself).
It is only possible to re-use the HTTP request handler instance if the URL is exactly
the same as in the last request. If the same request handler is being used by a
different URL, the object is reinstantiated.
Since HTTP requests differ from each other in their design, and do not provide any inherent
support for session contexts, this kind of context must be artificially constructed. Cookies are
used for this purpose.
See also:
Stateful and Stateless BSP Applications [page 381]
A Sample BSP Application [page 391]
Web Application Server

620 SP 9

112

SAP Online Help

25.10.2002

Logging On to SAP Web Application Server


Uses
When a client (for example, a Web browser) connects to SAP Web Application Server via a
URL, the SAP System usually has to be logged on to. Exceptions are pages that are retrieved
from the cache, as in this case the user is already logged on, and static file access.
There are a number of logon procedures. These are described below. They are described
here in the order in which the system tries to use them.

Prerequisites
You can specify for every ICF service what logon procedure must be used to execute it. For
information on how to do this using transaction SICF and what to look out for, see
Anonymous Logon [page 143].

Process
If a client is connected to SAP Web Application Server, and if this URL has a service
(Creating an ICF Service [page 140]), the system first checks whether Logon data mandatory
(set under Anonymous Logon [page 143]) or Client certificate with SSL (set under Security
Requirements [page 145]) is required. These logon types are mutually exclusive. Whichever
one of them is closest to the root node on the path pointing to the desired service remains
valid. (See below for example.)

If Logon data mandatory is valid, the logon procedure uses the anonymous logon data set
for this service. The attribute AUTHENTICATION_METHOD, which belongs to
IF_HTTP_SERVER [page 117] is set to AUTHMETHOD_SERVICE.

If Client certificate with SSL is valid, this is used for the logon procedure. The attribute
AUTHENTICATION_METHOD, which belongs to IF_HTTP_SERVER [page 117] is set to
AUTHMETHOD_ CERTIFICATE.

If neither service can be located in the ICF path, the system tries to log the user on using the
following methods, in this order:
1. Logon using HTTP fields (HTTP header fields or form fields): The fields are: saplanguage, sap-client, sap-user, sap-alias, and sap-password. (If sap-user is specified,
sap-alias is then unimportant, see Basic Authentication [page 146].) The attribute
AUTHENTICATION_METHOD, which belongs to IF_HTTP_SERVER [page 117] is set to
AUTHMETHOD_FIELD.
2. Logon using SSP ticket (MYSAPSSO2 cookie field). If no logon data is transferred as
form fields or header fields, the system then tries to log on using an SSO ticket. For this
to be possible, the cookie field MYSAPSSO2 must be set. The attribute
AUTHENTICATION_METHOD, which belongs to IF_HTTP_SERVER [page 117] is set to
AUTHMETHOD_SSO.
3. Logon using Basic Authentication. If the request contains the header field for Basic
Authentication, the user name is interpreted either as a standard SAP user (default) or as
an Internet user (user name alias, see transaction SU01), depending on the settings
made under Basic Authentication [page 146]. The attribute AUTHENTICATION_METHOD,
which belongs to IF_HTTP_SERVER [page 117] is set to AUTHMETHOD_BASIC.
4. Logon using SAP logon. This is a normal logon procedure using client, user, password,
and logon language. This method is used primarily between SAP Systems, and not so
much for logon via a Web browser. A header field is also used to indicate that this logon

Web Application Server

620 SP 9

113

SAP Online Help

25.10.2002

method should be used. The attribute AUTHENTICATION_METHOD, which belongs to


IF_HTTP_SERVER [page 117] is set to AUTHMETHOD_SAP.
5. Logon using client certifiate (HTTPS and certificate). In this case, the system attempts to
log on the user using a client certificate and SSL. Prerequisites for this are that the
corresponding header field is set, the HTTPS connection is configured, and the client
certificate is available. The attribute AUTHENTICATION_METHOD, which belongs to
IF_HTTP_SERVER [page 117] is set to AUTHMETHOD_CERTIFICATE.
6. Of none of these methods is possible because the request does not contain any
information regarding logon procedure, the default logon procedure is used. Logon via
service user account. If you have maintained the Anonymous Logon Data [page 143], the
logon procedure uses this user name, client, and logon language. If you have not entered
any data for an anonymous user, HTTP response 401 is sent back. If you are using a
Web browser, this response is displayed in a popup. The user can then log on to the SAP
System using HTTP Basic Authentication on this popup. The default client and logon
language of the user in question are used. The attribute AUTHENTICATION_METHOD,
which belongs to IF_HTTP_SERVER [page 117] is set to AUTHMETHOD_SERVICE.

Result
The user is logged on to the SAP System. If an anonymous user exists, the client uses this
user, although it does not recognize it. The correct authorizations must be set for the
anonymous user.
Determining the Logon Language [page 114] describes how the logon language is
determined.

Example
An example of choosing the logon procedure is given in Anonymous Logon Data [page 143].

Determining the Logon Language


When you log onto the SAP system, you must select a language. The following describes the
process according to which the logon language is determined.
The browser that is connected to the SAP Web Application Server as a client also has
language settings. With Internet Explorer, for example, you can set the language you require
by choosing Tools Internet Options Languages.
The logon language for the SAP Web Application Server is set according to the following
process.
1. In Transaction SICF, if the service has set the flag Mandatory Logon Data, the system
uses the language that was entered there. (For more information, see Logging On To
SAP Web Application Server [page 113]).
2. If this is not the case, but the HTTP request contains the language in the HTTP header
(as a header or a form field), you log onto the system using this language.
3. The system then takes the browser settings. The system selects as the logon language
the first language from the list that is maintained in the browser, and which is also
installed in the SAP system.
These are transferred using the HTTP header field accept-language.

Web Application Server

620 SP 9

114

SAP Online Help

25.10.2002

4. If no language is defined by this process, the classic SAP system mechanisms are used.
The logon language is based on the user settings (in Transaction SU01) and if nothing is
entered here, the default language of the SAP system is used.

ICF Classes and Interfaces


This section gives a detailed description of the ICF interfaces referred to in Design [page
108], and the classes that implement these interfaces.

Note that the ICF interfaces are guaranteed interfaces. SAP may change the
classes that implement these interfaces (such as CL_HTTP_SERVER,
CL_HTTP_EXTENSION) at any time. An interface for creating your own handlers
is made available.
The following interfaces are important for the operation of the ICF:
IF_HTTP_SERVER [page 117]
IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]
IF_HTTP_ENTITY [page 121]
IF_HTTP_EXTENSION [page 130]
IF_HTTP_UTILITY [page 133]
The UML diagram below shows the design of the various interfaces and their relationships to
one another.

Web Application Server

620 SP 9

115

SAP Online Help

25.10.2002

The interfaces that come with the ICF are grayed out in the diagram. Every IF_* is
implemented by an associated class, CL_*. The class shown in color in the diagram
implements the interface IF_HTTP_EXTENSION and represents the HTTP request handler
you can write yourself. SAP also provides a number of HTTP request handlers, for example,
the handler for Creating Web Applications with Business Server Pages [page 170].

Web Application Server

620 SP 9

116

SAP Online Help

25.10.2002

The interface IF_HTTP_CLIENT [page 167] is for using the ICF in the client role.
This interface uses the same request and response attribute and is described
under HTTP Communication Using the SAP System as a Client [page 155].

IF_HTTP_SERVER
Definition
This interface is implemented by the class CL_HTTP_SERVER.
The structure of the interface and its relationship to the other interfaces are shown in the
diagram in ICF Classes and Interfaces [page 115].
The attributes and methods are explained in this documentation.

Use
An object in the class CL_HTTP_SERVER, the control block, is created for every incoming
request. This object contains, among other things, the data structures for the HTTP request
and HTTP response data. Objects in the classes CL_HTTP_REQUEST and
CL_HTTP_RESPONSE implement the interfaces IF_HTTP_RESPONSE and
IF_HTTP_REQUEST [page 119]. The interface IF_HTTP_SERVER provides interface
references to these data structures: attributes REQUEST and RESPONSE.

Structure
The structure of the interface is described in the following sections:
Attributes [page 117]
Constants [page 118]
Methods [page 119]

Attributes
The interface IF_HTTP_SERVER contains the following attributes:
REQUEST

Interface reference to the request object

RESPONSE

Interface reference to the response object

SESSION_ID

HTTP session ID (generated by the SAP kernel)

VERSION

Version of the implementation of the Internet Communication


Framework

AUTHENTICATION_METHOD

Logon procedure. This attribute can take on the values


AUTHMETHOD_*, which are described in Constants [page 118].
The logon procedures are described in Logging on to the SAP Web
Application Server [page 113].

Web Application Server

620 SP 9

117

SAP Online Help

STATEFUL

25.10.2002

Defines whether the SAP session is to be maintained after the


request (STATEFUL= CO_ENABLED, stateful mode of operation), or
whether the session is to be closed after the request (STATEFUL=
CO_DISABLED, stateless mode of operation). The default mode is
stateless.
See also Stateless and Stateful Model [page 112].

TRANSACTIONAL

This can be used to define an application as transactional. This


means that either a commit (return codes CO_FLOW_OK and
CO_FLOW_OK_OTHERS_OPT) or a rollback (return codes
CO_FLOW_ERROR and CO_FLOW_OK_OTHERS_MAND) is executed,
depending on the return code of the last called HTTP request
handler. If the transactional flag is not set, the application itself
must execute the commit at the right time. Otherwise, the ICF
executes an implicit rollback. TRANSACTIONAL can accept the
values CO_DISABLED and CO_ENABLED, which are explained
below. CO_DISABLED is the default value.

SESSION_TIMEOUT
SSL_ACTIVE

Session Timeout
Sets Secure Socket Layer (SSL) as active.
See also Security Requirements [page 145]

See also:
You can find a description of the constants that are possible in Constants [page 118].

Constants
The components of the interface IF_HTTP_SERVER have the following constants:
CO_DISABLED and CO_ENABLED are possible values of the attributes STATEFUL and
TRANSACTIONAL.
The other constants are the possible values for the attribute AUTHENTICATION_METHOD.
Name of Constant

Meaning

CO_DISABLED

Not active (default setting)

CO_ENABLED

Active

AUTHMETHOD_NONE

No logon

AUTHMETHOD_BASIC

HTTP Basic Authentication

AUTHMETHOD_SSO

Authentication using Mysapsso2 cookie

AUTHMETHOD_SAP

SAP logon procedure

AUTHMETHOD_SERVICE

Service logon procedure

AUTHMETHOD_FIELD

Logon using form fields

AUTHMETHOD_CERTIFICATE

Logon using X.509 certificate.

Which logon procedure is used for SAP Web Application Server depends on the
corresponding setting.

Web Application Server

620 SP 9

118

SAP Online Help

25.10.2002

The order in which the system tries the various logon procedures is described in Logging on
to the SAP Web Application Server [page 113].

Methods
The following methods are defined by the interface IF_HTTP_SERVER:
CREATE_ABS_URL()

Creates the string representation of an absolute URL, based either on the


given arguments (such as protocol, server, port, path, query string) or on
the values indirectly defined by the current request (for example, the current
request always knows the server and port). The resulting URL can be used
in HTML pages to reference the current session and, by means of this, to
connect different dialog steps in the system to the same session.

CREATE_REL_URL()

The same as CREATE_ABS_URL(), but creates a relative URL (that is, no


protocol, server, or port can be specified).

APPEND_FIELD_URL()

Adds the given name/value pair to the given URL as a query string. The
name and value are automatically URL-escaped. When this method is
called in a loop, any number of name/value pairs can be simply and easily
added to the final URL.

ESCAPE_URL()

Use the method of the same name of the interface IF_HTTP_UTILITY


[page 133].

UNESCAPE_URL()

Use the method of the same name of the interface IF_HTTP_UTILITY


[page 133].

GET_EXTENSION_URL()

Returns URLs for which the given HTTP request handler is set in
associated services.

GET_EXTENSION_INFO()

Returns the protocol, the host name, the port, and the URL for a HTTP
extension.

ESCAPE_HTML()

Use the method of the same name of the interface IF_HTTP_UTILITY


[page 133].

DECODE_BASE64()

Use the method of the same name of the interface IF_HTTP_UTILITY


[page 133].

ENCODE_BASE64()

Use the method of the same name of the interface IF_HTTP_UTILITY


[page 133].

GET_LAST_ERROR()

Use the method of the same name of the interface IF_HTTP_UTILITY


[page 133].

IF_HTTP_RESPONSE and IF_HTTP_REQUEST


Definition
Interfaces IF_HTTP_RESPONSE and IF_HTTP_REQUEST can be reached by an HTTP
request handler using attribute RESPONSE or REQUEST of the interface IF_HTTP_SERVER
[page 117]. They are used to work with the data of the HTTP request or the HTTP response.

Web Application Server

620 SP 9

119

SAP Online Help

25.10.2002

Use
These interfaces can be used in both server and client roles. They allow easy access to data,
and have functions for modifying both HTTP header data and HTTP body data. This interface
is intended for both roles of HTTP server and client, and therefore has both requesting and
manipulating methods.
Both types of method enhance the interface IF_HTTP_ENTITY and provide additional
methods.

Web Application Server

620 SP 9

120

SAP Online Help

25.10.2002

Structure
List of Methods
IF_HTTP_RESPONSE
The following methods enhance the interface IF_HTTP_ENTITY [page 121] and are
implemented in the class CL_HTTP_RESPONSE.
GET_STATUS

Gets the currently set HTTP status code

SET_STATUS

Sets the given HTTP status code

DELETE_COOKIE_AT_CLIENT

Deletes the given cookie on the client side

REDIRECT

Executes a redirect to the given URL

SERVER_CACHE_EXPIRE_ABS

Sets the expiry period for the ICM server cache (see also ICM
Server Cache [page 34]). An absolute date and time are given. The
page contained in the cache is invalid after this date and time.

SERVER_CACHE_EXPIRE_DEFAULT

Activates the ICM server cache and sets the default expiry period.

SERVER_CACHE_EXPIRE_REL

Sets a relative expiration period (in seconds) for the ICM server
cache

SERVER_CACHE_BROWSER_DEPEND
ENT

Sets the indicator for browser-specific HTML in the ICM server


cache. The request is only taken from the cache if the request
comes from the correct browser type.

IF_HTTP_REQUEST
The following methods enhance the interface IF_HTTP_ENTITY [page 121] and are
implemented in the class CL_HTTP_REQUEST.
GET_AUTHORIZATION

Provides information from the authorization header field

SET_AUTHORIZATION

Sets the authorization header field for the request

GET_FORM_DATA

Puts form data into a complex data structure

GET_RAW_MESSAGE

Provides the complete HTTP message

GET_URI_PARAMETER

Provides the value of the required URI parameters

GET_USER_AGENT

Provides user agent information from the request

IF_HTTP_ENTITY
Definition
This interface does not contain any attributes. It consists of the methods explained below and
is contained in the interfaces IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119].

Use
The interface IF_HTTP_ENTITY is used as a basis for the interfaces IF_HTTP_RESPONSE
and IF_HTTP_REQUEST [page 119]. IF_HTTP_REQUEST and IF_HTTP_RESPONSE extend
IF_HTTP_ENTITY by adding request and response-specific methods.

Web Application Server

620 SP 9

121

SAP Online Help

25.10.2002

Also, the interface IF_HTTP_ENTITY is used as an interface for multipart [page 130]
segments, both in multipart requests and multipart responses.
See the sections listed below for descriptions of the various access methods:
Accessing Header Fields [page 123]
Accessing Form Fields [page 127]
Accessing Cookies [page 128]
Accessing HTTP Body Data [page 129]
Accessing HTTP Multipart Data [page 130]

Structure
The methods listed in the table are supported by the interface IF_HTTP_ENTITY. These
methods are also supported by the interfaces IF_HTTP_REQUEST and
IF_HTTP_RESPONSE. Therefore, in this section, the term HTTP entity signifies a HTTP
request, a HTTP response, or a multipart segment, depending on the purpose for which the
method is used.

Accessing Header Fields


Method Name

Use and Meaning

GET_HEADER_FIELD

Returns the value of the specified (pseudo) HTTP header field


(name is case-insensitive).

GET_HEADER_FIELDS

Returns a table of all (pseudo) HTTP header fields as name/value


pairs.

DELETE_HEADER_FIELD

Deletes the given header field from the list of header fields.

SET_HEADER_FIELD

Sets the specified (pseudo) header fields to the given value (name
is case-insensitive).

SET_HEADER_FIELDS

Sets all (pseudo) HTTP header fields in the request object to the
values specified as arguments in the name/value table.

You can find details about the access types as well as a list of the SAP-specific header fields
in Accessing Header Fields [page 123].

Accessing Form Fields


Method Name

Use and Meaning

GET_FORM_FIELD

Returns the value of the specified HTML form field (name is caseinsensitive).

GET_FORM_FIELDS

Returns a table of all name/value pairs from the HTML form fields.

DELETE_FORM_FIELD

Deletes the given form field.

SET_FORM_FIELD

Sets the specified HTML form field to the given value (name is
case-insensitive).

SET_FORM_FIELDS

Sets all HTML form fields in the request object to the given values.

For details, see Accessing Form Fields [page 127].

Accessing Cookies
Method Name

Use and Meaning

ADD_COOKIE_FIELD

Sets the given sub-field of the given cookie.

GET_COOKIE_FIELD

Returns the given sub-field of the given cookie.

Web Application Server

620 SP 9

122

SAP Online Help

25.10.2002

GET_COOKIE

Returns the value of the specified cookie (name is caseinsensitive).

GET_COOKIES

Returns a list of all cookies.

DELETE_COOKIE

Deletes the given cookie from the list of cookies.

SET_COOKIE

Sets the value of the specified cookie (name is case-insensitive).

For details, see Accessing Cookies [page 128].

Accessing HTTP Body Data


Method Name

Use and Meaning

APPEND_CDATA

Inserts the given character string into the body of the HTTP entity.

APPEND_CDATA2

Inserts the given character string into the body of the HTTP entity.

APPEND_DATA

Inserts the given binary string into the body of the HTTP entity.

FROM_XSTRING

Instantiates the HTTP entity using the given XSTRING.

GET_CDATA

Returns the data in the body of the HTTP entity as a character


string.

GET_DATA

Returns the data in the body of the HTTP entity as a binary string.

SET_CDATA

Inserts the content of the body of the HTTP entity into the given
character string.

SET_DATA

Inserts the content of the body of the HTTP entity into the given
binary string.

TO_XSTRING

Opposite of FROM_XSTRING. Changes a HTTP entity into an


XSTRING.

GET_LAST_ERROR

Returns the last error code.

For details, see Accessing HTTP Body Data [page 129].

Accessing HTTP Multipart Data

The following methods are only valid for HTTP multipart units!
Method Name

Use and Meaning

ADD_MULTIPART

Adds a multipart segment to the body of the HTTP entity.

GET_MULTIPART

Returns the multipart segment specified by an index.

NUM_MULTIPARTS

Returns the number of multipart segments in the request object.

For details, see Accessing HTTP Multipart Data [page 130].

Accessing Header Fields


Use
Using GET_HEADER_FIELD() / GET_HEADER_FIELDS(), the HTTP request handler can
access all attributes of the HTTP header (name/value pairs). Examples are the attributes
content-length and content-type.

Web Application Server

620 SP 9

123

SAP Online Help

25.10.2002

The methods SET_HEADER_FIELD() and SET_HEADER_FIELDS() can be used to modify


the request header, if necessary (for example, if the HTTP client role is active, or if a request
requires additional information or has to be sent back).

There are header fields that should not be set with method
SET_HEADER_FIELD(. The description of the individual header fields explains
how you should access them.
The methods mentioned above can be used to access all HTTP header fields that are sent as
part of a request. The fields can be addressed by means of their case-insensitive names (for
example, content-type for the content type attribute of the HTTP header). For a list of
typical fields in the HTTP header, see the HTTP/1.1 specification.
In addition to these fields, there are a number of other fields that are not pure field attributes
of the HTTP header, but that can be derived from the HTTP request line. These fields are
known as pseudo header fields. A typical example is the query string part of a URL, or the
method of the request (for example, GET or POST). Pseudo header fields are differentiated
from genuine header fields by the prefix ~ (tilda) in their names (for example,
~query_string).

Functions
The following SAP-specific HTTP header fields have been added in the framework of SAP
Web Application Server. These fields are only used in the HTTP request object and can be
called using the method IF_HTTP_REQUEST~GET_HEADER_FIELD(). The fields contain
server-specific environmental information obtained either directly or indirectly from the HTTP
request, but which are not covered by the standard HTTP header fields. Most fields are called
environment variables, in line with the Common Gateway Interface (CGI).
All header fields are case-insensitive and start with the reserved character ~.
The interface IF_HTTP_HEADER_FIELDS_SAP provides pre-defined string constants for all
SAP-specific header fields.

The SAP header fields that are written in italics should not be changed with
method SET_HEADER_FIELD()! The access type is specified at the end of the
description.
Header Field Name

Description

~content_data

In the case of multipart entities (for example, when uploading files


from HTML forms), contains the body of the non-binary multipart
segment.

~content_disposition

In the case of multipart entities, for example, when uploading files


from HTML forms, contains the content disposition (segment type,
segment name (filename of the segment)).
Do not change this value! You can use method
GET_HEADER_FIELD() to query the value.

~content_filename

In the case of multipart entities when uploading files from HTML


forms, contains the file name as it was entered in the HTML form or
selected from the choose file dialog.
Do not change this value! You can use method
GET_HEADER_FIELD() to query the value.

~content_name

Web Application Server

In the case of multipart entities for HTML forms, contains the name
of the input field or HTML control. The value of this field or control

620 SP 9

124

SAP Online Help

25.10.2002
can be obtained from ~content_data for the same entity
Do not change this value! You can use method
GET_HEADER_FIELD() to query the value.

~path

Contains the escaped path name from the request URI or URL
(without query string), for example,
/sap/bc/bsp/sap/it00/default.htm from
/sap(XYasfduy===)/bc/bsp/sap/it00/default.htm?x=1&y=2.
Compare with ~path_translated and
~path_translated_expanded.

~path_info

Within a HTTP request handler (see interface


IF_HTTP_EXTENSION [page 130]), contains the URL suffix that
comes after the URL prefix. The URL prefix is used to execute the
request handler. This results in:
~script_name + ~path_info = ~path_translated

If the request handler is registered under the URL /sap/bc/bsp


(see transaction Using the ICF [page 134]), this variable has the
value /sap/it00/default.htm for the request URL
/sap/bc/bsp/sap/it00/default.htm.
If an internal or an external alias, for example, myApp, points to
/sap/bc/bsp/sap, and if a request using this alias is used to gain
access, then this variable is set to the value /it00/default.htm (see
~path_info_expanded). The request would then read
/myApp/it00/default.htm.
~path_info_expanded

Within a HTTP request handler (see interface


IF_HTTP_EXTENSION [page 130]), contains the URL suffix that
comes after the expanded URL prefix. The URL prefix is used to
execute the request handler. This results in:
~script_name_expanded + ~path_info_expanded =
~path_translated_expanded

If the request handler is registered under the URL /sap/bc/bsp


(see transaction SICF), this variable has the value
/sap/it00/default.htm for the request URL
/sap/bc/bsp/sap/it00/default.htm.
If an internal or an external alias, for example, myApp, points to
/sap/bc/bsp/sap, and if a request using this alias is used to gain
access, then this variable is set to the value /sap/it00/default.htm
(see ~path_info). The request would then read
/myApp/it00/default.htm.
~PATH_TRANSLATED

Contains the unescaped path name from the request URI or URL
(without query string), for example,
/sap/bc/bsp/sap/it00/default.htm from
/sap(XYasfduy===)/bc/bsp/sap/it00/default.htm?x=1&y=2.
Compare with ~path_translated and
~path_translated_expanded.

~path_translated_expanded

Contains the expanded, unescaped path name that is derived from


the request URI or URL when the internal or external aliases are
resolved.

Web Application Server

620 SP 9

125

SAP Online Help

25.10.2002

If an internal or an external alias, for example, myApp, points to


/sap/bc/bsp, and if a request using this alias is used to gain
access, then this variable is set to the value
/sap/bc/bsp/sap/it00/default.htm. The request would then read
/myApp(XZasfduz===)/sap/it00/default.htm.
~query_string

Contains the URL-escaped query string from the request URI of a


HTTP request, that is, the string part after the first question mark,
for example, name=Walt+Whitman&street=Oxford+Street from
http://server:8080/sap/bc/ping?
name=Walt+Whitman&street=Oxford+Street.
If you want to change the query string, set the individual form
fields. To do this, use methods SET_FORMFIELD or
SET_FORMFIELDS of interface IF_HTTP_ENTITY.

~remote_addr

Contains the IP address of the HTTP client if the server is accessed


without a HTTP proxy, otherwise contains the IP address of the last
proxy in the chain of proxies outside the server.

~request_line

Contains the complete HTTP request line of the request, for


example, GET /sap/bc/ping?param=2 HTTP/1.1
If you want to make changes to the request line, use the
corresponding methods for manipulating the individual components
of the request line.

~request_method

Contains the HTTP method from the HTTP request line of the
request, for example, GET, POST or PUT.

~request_uri

Contains the complete URI from the HTTP request line of the
request, for example, /sap/bc/ping?param=2 from GET
/sap/bc/ping?param=2 HTTP/1.1.
If you want to make changes to the request URI, use the
corresponding methods for manipulating the individual components
of the request line.

~response_line

Contains the complete HTTP response line (status line) of a


received HTTP response, for example, HTTP/1.1 200 OK.
If you want to make changes to the response line, use the
corresponding methods for manipulating the individual components
of the response line.

~script_name

Within a HTTP request handler (see interface


IF_HTTP_EXTENSION [page 130]), contains the URL prefix that is
used to execute the request handler.
If the request handler is registered under the URL /sap/bc/bsp
(see transaction SICF), this variable has the value /sap/bc/bsp for
the request URL /sap/bc/bsp/sap/it00/default.htm.
If an internal or an external alias, for example, myApp, points to
/sap/bc/bsp, and if a request using this alias is used to gain
access, then this variable is set to the value /myApp (see
~script_name_expanded ). The request would then read
/myApp/sap/it00/default.htm.

~script_name_expanded

Web Application Server

Within a HTTP request handler (see interface


IF_HTTP_EXTENSION [page 130]), contains the URL prefix that is

620 SP 9

126

SAP Online Help

25.10.2002
used to execute the request handler.

If the request handler is registered under the URL /sap/bc/bsp


(see transaction SICF), this variable has the value /sap/bc/bsp for
the request URL /sap/bc/bsp/sap/it00/default.htm.

~server_name

If an internal or an external alias, for example, myApp, points to


/sap/bc/bsp, and if a request using this alias is used to gain
access, then this variable is not set to the value /myApp, unlike in
the case of the variable ~script_name, but is set to the expanded
prefix /sap/bc/bsp. The request would then read
/myApp/sap/it00/default.htm.
Contains the name of the server that received the request.

~server_port

Contains the number of the port on which the request came in.

~server_protocol

Contains the protocol from the HTTP request line, for example,
HTTP/1.0 or HTTP/1.1.

~status_code

In the case of a HTTP response (client), contains the HTTP status


code, for example, 200 (OK).
Do not use method SET_HEADER_FIELD() to set the HTTP
status. Use method SET_STATUS() of interface
IF_HTTP_RESPONSE.

~status_reason

In the case of a HTTP response (client), contains the description


text of the HTTP status code, for example, OK or Not found
(401). The interface IF_HTTP_STATUS contains a list of all status
texts in the form of constants.
Do not use method SET_HEADER_FIELD() to set the HTTP
status. Use method SET_STATUS() of interface
IF_HTTP_RESPONSE.

~uri_scheme

Contains the URI scheme of the URL, for example, http or https.
To be more exact: The field contains the string that is at the
beginning of the URL before the ://. This must not be the protocol
that is used when working with proxies.
It is not recommended that you use this field to differentiate
between HTTP and HTTPS! If you want to query whether it is an
HTTPS connection, use attribute SSL_ACTIVE of the server object
(see also IF_HTTP_SERVER [page 117]).

See also:
The HTTP header fields are defined in interface IF_HTTP_HEADER_FIELDS with initial
values, the SAP-specific header fields are in the interface IF_HTTP_HEADER_FIELDS_SAP.

Accessing Form Fields


GET_FORM_FIELD() / GET_FORM_FIELDS() allows the HTTP request handler access to all
HTML form fields (name/value pairs) that were sent with the request.
Web Application Server

620 SP 9

127

SAP Online Help

25.10.2002

The HTTP request handler handles these fields using encapsulation. A HTML page can
transfer the fields either in the URL as a query string (HTTP method GET) or in the HTTP
body (HTTP method POST, multipart is also possible).
All form fields are accessible via case-insensitive names. If desired, a complete table of
name/value pairs can be called.
Modifications are supported by the methods SET_FORM_FIELD() / SET_FORM_FIELDS() of
the interface IF_HTTP_REQUEST.

Ensure that you cannot set the form fields for response objects. If you call
SET_FORMFIELD to an HTTP response, however, then the value is not defined!
This is described in IF_HTTP_ENTITY [page 121].

Accessing Cookies
GET_COOKIE()and GET_COOKIES() are used to allow the HTTP request handler access to
cookies sent with the HTTP request. Cookie names are case-insensitive. If necessary, you
can use method SET_COOKIE().

SET_COOKIE()
You use this method to define new cookies (for example, in the HTTP client role), or to modify
existing cookies (for example, to modify request data in the HTTP server role).
The following section provides an overview of the parameters. These are always import
parameters.
Parameters

Syntax

Description

NAME

NAME = <Name>

Name of cookie
Mandatory parameter

VALUE

VALUE = <Value>

Name of cookie
Mandatory parameter

PATH

PATH = <Path name>

Determines the path attribute


for a specified cookie. If you
do not specify a value as a
pathname, the system uses
the path of the page that the
cookie generated.

DOMAIN

DOMAIN = <Domain name>

Determines the domain


attribute for a specified cookie.
If you do not specify a value
as the domain name, the
system uses the host name of
the server that generated the
cookie response.

EXPIRES

EXPIRES = <Wdy, DDMon-YY HH:MM:SS GMT>

Determines the timestamp


(date and time) when the
cookie lifetime ends. As soon
as the cookie lifetime expires,
it is no longer stored or
returned.
The timestamp has the
following format: Wdy, DD-

Web Application Server

620 SP 9

128

SAP Online Help

25.10.2002
Mon-YY HH:MM:SS GMT,
such as Tue, 15 Nov
1994 12:45:26 GMT.
If you do not set a date, the
cookie is stored as a session
cookie, otherwise it is stored
on the hard drive.
SECURE = 1 / 0

SECURE

The cookie is only transferred


if the communication channel
to the host is secure.
Currently, only those servers
that communicate via HTTPS
(that is, HTTP with SSL) are
secure. The default value 0
specifies an insecure
connection, 1 indicates the
connection is secure.

Example
data: cookie

type string,

expiry

type string,

ts

type bsptimestamp,

ttss(14)

type c.

ts-date

= sy-datum + 1.

ts-time

= sy-uzeit.

ttss

= ts.

cookie

= 'This is a test cookie'.

class cl_bsp_utility definition load.


expiry = cl_bsp_utility=>date_to_string_http( timestamp = ttss ).
*set the new cookie
call method response->set_cookie
exporting name
value

= 'testcookie'
= cookie

expires = expiry.

Accessing HTTP Body Data


In some cases, a HTTP request handler may have to access the unprocessed data in the
HTTP body. This may be the case if the content type is text/html or text/xml, and the

Web Application Server

620 SP 9

129

SAP Online Help

25.10.2002

HTTP body contains no form fields. Access is gained using the methods GET_CDATA() /
GET_CDATA(). These methods also allow you to modify the request data, if necessary.
This is described in IF_HTTP_ENTITY [page 121].
Whilst methodAPPEND_CDATA2() always works with raw data, method APPEND_CDATA2()
receives another parameter that contains data encoding. There are the constants
CO_ENCODING_RAW, CO_ENCODING_URL, CO_ENCODING_HTML and CO_ENCODING_WML.
The constants display how the text should be output. The text is usually output as it was
entered (CO_ENCODING_RAW). If, however, it occurs in a URL (for example, as a parameter),
it must have a specific coding (for example, blank characters are replaces by '+' or '%20'). In
this case, parameter CO_ENCODING_URL is used. If a text should appear on an HTML page
as it was entered, characters that have a special semantic (such as '<' ) must be replaced by
their html-encoded counterpart ( '&lt' ). (CO_ENCODING_HTML). The constants
CO_ENCODING_WML are available for the WML coding for WML.
This coding is mainly used in BSP pages by expressions such as '<%html= mystring %>'.
There are html, url and raw. The WML coding is executed if html is specified as coding,
and the page then has the MIME type of a WML document.

Accessing HTTP Multipart Data


Some HTTP requests keep their data not in their own body part, but in various segments
known as multiparts. Multiparts consist of their own HTTP (sub-)header and (sub-)body.
Multiparts can be accessed via the interface IF_HTTP_ENTITY, which consists of the
interfaces IF_HTTP_REQUEST and IF_HTTP_RESPONSE. The methods ADD_MULTIPART(),
GET_MULTIPART() and NUM_MULTIPARTS() of the interface IF_HTTP_ENTITY provide
the functionality for navigating in the multipart segment tree.
This is described in IF_HTTP_ENTITY [page 121].

IF_HTTP_EXTENSION
Definition
The interface IF_HTTP_EXTENSION must be implemented by all HTTP request handlers.
This interface guarantees that the Internet Communication Framework interacts consistently
with the HTTP request handlers, regardless of the handlers individual purposes.

Use
The only method belonging to this interface is HANDLE_REQUEST(). This method is called by
the ICF handler for an incoming request. A reference to the interface IF_HTTP_SERVER is
given as an argument, so that the HTTP request handler can access the request and
response data. As soon as the HTTP request handler has executed its processes for the
request, it simply exits the call for the method HANDLE_REQUEST() and passes control over
to the ICF controller.
The interface IF_HTTP_EXTENSION also has two other attributes. The purposes of these
additional attributes are to allow the HTTP request handler to influence its own behavior

Web Application Server

620 SP 9

130

SAP Online Help

25.10.2002

during its lifetime, and to decide how other HTTP request handlers associated with the
service should be executed. These attributes are described in other sections.

Structure
The structure of the interface IF_HTTP_EXTENSION is described in the following sections:
List of Attributes [page 131]
Constants for Describing Lifetime Control [page 132]
Constants for Describing the Control Flow [page 131]
List of Methods [page 133]

Attributes
The following attributes are supported by the interface IF_HTTP_EXTENSION:
Attribute

Meaning and Use

FLOW_RC

This attribute controls any possible subsequent HTTP request handlers and error
information. It can assume the values described above CO_FLOW_OK,
CO_FLOW_ERROR, CO_FLOW_OK_OTHERS_OPT, CO_FLOW_OK_OTHERS_MAND
(see also Constants for Describing the Control Flow [page 131]).

LIFETIME_RC

This attribute controls the lifetime of the instance of the HTTP request handler. It can
assume values CO_LIFETIME_KEEP and CO_LIFETIME_DESTROY (see also
Constants for Describing the Lifetime Control [page 132]).

Constants for Describing the Control Flow


Definition
HTTP request handlers can allow other HTTP request handlers to be called for the same
request. This may be necessary, for example, for a specific class of HTTP request handlers
(such as logging options), but is not necessarily carried out in exactly the same way for all
handlers, for example, the CRM HTTP request handler. A HTTP request handler therefore
needs to be able to signal the required mode of behavior to the framework.

Use
If the attribute IF_HTTP_EXTENSION~FLOW_RC is set to one of the following values, this
specifies what the ICF controller should do if the HTTP request handler returns control to the
ICF controller by exiting the method HANDLE_REQUEST().

Structure
CO_FLOW_OK

The HTTP request handler has successfully processed the request. No


further registered HTTP request handlers that are suitable for the request
URL may be called. The ICF controller must send the response to the
client immediately.
This is the default setting for all HTTP request handlers.

Web Application Server

620 SP 9

131

SAP Online Help

CO_FLOW_ERROR

25.10.2002

An error occurred while the HTTP request handler was processing the
request. No further registered HTTP request handlers that are suitable for
the request URL may be called. The ICF controller must send the
response to the client immediately.
This return code indicates serious errors which cause the session to be
terminated, if stateful mode is active.

CO_FLOW_OK_OTHERS_OPT

The HTTP request handler has successfully processed the request and
allows further HTTP request handlers that are suitable for the request
URL to be called. The response is then sent to the client.

CO_FLOW_OK_OTHERS_MAND

The HTTP request handler has successfully processed the request, and
requires that at least one other HTTP request handler also successfully
processes the request before the response can be sent to the client. A
typical example of the use of this return code is a HTTP request handler
that requires authentication.

See also: Constants for Describing Lifetime Control [page 132]

Constants for Describing Lifetime Control


Definition
As described in section IF_HTTP_EXTENSION [page 130], HTTP request handlers can
control the lifetime of their instances if they are operating in stateful mode. When a request is
being processed in stateless mode, the lifetime of any HTTP request handler instance is of
course restricted to a single request, and ends at the same time as the lifetime of the user
context (that is, it ends when HANDLE_REQUEST() is returned).

Use
If the attribute IF_HTTP_EXTENSION~LIFETIME_RC is set to one of the following values, the
HTTP request handler can specify whether the handler should be reinitiated for every request
in a session, or whether the handler should be retained and reused for subsequent HTTP
requests.

Structure
Name of Constant

Meaning

CO_LIFETIME_KEEP

This instance of the HTTP request handler is to be retained and reused for
subsequent requests in the same session. This means that data in instance
attributes of the implementation class are retained for several requests, and
can be used for local caching and optimization, or status handling. This is
the default for all HTTP request handlers.

CO_LIFETIME_DESTROY

The current instance of the HTTP request handler is terminated after the
request is processed. If stateful mode is active, a new instance of the HTTP
request handler is created. This means that local data belonging to the
instance is lost.

See also: Constants for Describing the Control Flow [page 131]

Web Application Server

620 SP 9

132

SAP Online Help

25.10.2002

Methods
The following method is supported by the interface IF_HTTP_EXTENSION:
Method Name

Meaning and Use

HANDLE_REQUEST

This method must be implemented by all HTTP request handlers in the ICF. It
contains the current code for request processing. It is called for every incoming
request if the HTTP request handler is registered for the request URL (or a prefix)
in question.

IF_HTTP_UTILITY
Definition
This interface provides general methods that can be used for HTTP data. They are not clientor server-specific.

Structure
There are the following methods for processing HTTP data:
DECODE_BASE64

Decodes a Base64 [External documentation]-encoded string.

ENCODE_BASE64

Encodes a Base64 [External documentation]

ESCAPE_HTML

Converts all letters in a string that could be interpreted as a HTML control


sequence in a HTML page. The conversion ensures that they are output
correctly. A typical example is the < character. This character could be
interpreted as the beginning of a HTML tag. It is therefore converted to the
character sequence '&lt;', which the browser interprets as '<'.

ESCAPE_URL

Replaces with '%xx' symbols in a string that could be URL control characters.
xx is the hex code of the character. Also, spaces are replaced by '+' characters.
Strings that have been thus changed are later processed to become URLs . For
example, the string 'Tom & Jerry' becomes 'Tom+%26+Jerry'.

UNESCAPE_URL

Opposite of ESCAPE_URL. Converts the characters back to URL control


characters (for example, the query string part of a URL) and returns the resulting
string.

GET_LAST_ERROR

Returns the last error code.

STRING_TO_FIELDS

Decodes a query string into a list of fields.

FIELDS_TO_STRING

Encodes a list of fields as a query string.

Integration
In some cases, the same methods are implemented in different interfaces (such as
IF_HTTP_SERVER [page 117], IF_HTTP_ENTITY [page 121]). In the long term, all general
HTTP tools should be collected into this interface.

Use the IF_HTTP_UTILITY methods, even if the same methods are implemented
in other interfaces.

Web Application Server

620 SP 9

133

SAP Online Help

25.10.2002

Using the ICF


Purpose
Other sections of this documentation have described the concept and design of the HTTP
request handler, and have thus laid the groundwork for you to create your own HTTP request
handlers. The tools involved are the Class Builder and the transaction used for ICF services,
SICF. The individual steps in the process of creating HTTP request handlers are described in
.

Process
The following sections explain the steps in the process:
Implementing Handler Classes [page 134]
Linking a HTTP Request Handler to an ICF Service [page 136]
Creating an ICF Service [page 140]
Monitoring and Troubleshooting Functions [page 151]
Special Features [page 154]
Transporting ICF Services [page 155]

Implementing Handler Classes


Use
The central task when creating a HTTP request handler is implementing the interface
IF_HTTP_EXTENSION [page 130]. A prerequisite for this is implementing the method
HANDLE_REQUEST () to make it possible to determine how the HTTP request handler
should process an incoming HTTP request.
The UML diagram in ICF Classes and Interfaces [page 115] shows the relationship between
the ICF classes and interfaces and the interface IF_HTTP_EXTENSION.

Procedure
In the class builder (transaction SE24), create a class that represents the HTTP request
handler, and assign it to the interface IF_HTTP_EXTENSION.
You can now implement the method HANDLE_REQUEST () (double-click on the method
name).
You can access the request and response data by using the reference to the interface
IF_HTTP_SERVER an argument of the method HANDLE_REQUEST (). The interface
IF_HTTP_SERVER also supports the attributes FLOW_RC and LIFETIME_RC. You can
assign content to these attributes using the method HANDLE_REQUEST. This allows you to
specify in greater detail how an incoming request should be processed. For details of the
attributes see the following sections:

Web Application Server

620 SP 9

134

SAP Online Help

25.10.2002

IF_HTTP_SERVER [page 117]


IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]
IF_HTTP_ENTITY [page 121]

The connection to the server must be checked for an incoming request.


To do this, enter the URL http://hostname:portname/pingservice in the
browser.
You can maintain the pingservice using Transaction SICF (see Creating a
Service [page 140]). As the HTTP request handler it has class
CL_HTTP_EXT_PING with the method HANDLE_REQUEST ().
A data type data of the type string is declared to interpret the body of the
outgoing HTTP response:
data: data type string.
As soon as the HTTP request handler is accessed, it is obvious that the
connection test to the server was successful. The next task is to send a HTTP
response back to the client to indicate the successful establishment of the
connection. The browser should simply output the HTML line connection to
server successful.
To do this, first the Header Field [page 123] content-type of the HTTP
response is set to the value text/html (the method set_header_field ()
is called to set header fields in the response):
server->response->set_header_field(
name

= 'Content-Type'

value = 'text/html' ).
Next, the HTTP string data is filled with the string connection to server
successful:
concatenate '<html>'
'<body>'
'connection to server successful'(001)
'</body>'
'</html
into data.
Finally, this string is transferred via a reference to the interface
IF_HTTP_SERVER of the method set_cdata, in order to fill the body of the
HTTP response with this string.
server->response->set_cdata( data = data ).
This triggers the output of text to the browser, and the client sees that the
connection test ran successfully.

Web Application Server

620 SP 9

135

SAP Online Help

25.10.2002

Linking a HTTP Request to an ICF Service


Use
You need to link a HTTP request to an ICF service so that the HTTP request handler is called
up in the browser when a URL is entered. Use transaction SICF to do this.

Prerequisites
You have implemented a class that represents the HTTP request handler. This class
implements the interface IF_HTTP_EXTENSION. You have implemented the method
HANDLE_REQUEST().

Procedure
Now link your HTTP request handler with an ICF service: Creating a Service [page 140]
If required, you can use Virtual Hosts [page 136].
For information on assigning aliases when creating links, see the following sections:
Internal Aliases [page 148]
External Aliases [page 151]
You must activate your service before you can call it from the browser. See Activating and
Deactivating an ICF Service [page 147].

Result
When the relevant URL is called, the HTTP request handler is called.

SAP Web Application Server is running on the host saphost on port 8080.
In transaction SICF, you have created the service sap/bc/ping in the HTTP
service tree, and entered your handler class CL_HTTP_MYHANDLER in the
handler list (see Implementing Handler Classes [page 134]).
If you enter the URL http://saphost:8080/sap/bc/ping, the method
handle_request(), which you created for your HTTP request handler, is
called.

Virtual Hosts
SAP Web Application Server offers virtual host functionality based on commercial Web
servers. The term virtual server is also sometimes used.
In other Web server systems, virtual hosts allow a host to be accessible via various
combinations of host names and ports. The host names here must be aliases. The computer
then acts differently depending on the method of access, for example, it takes different
locations in the file system as the root.

For detailed information on the concept underlying virtual hosts, see Virtual Hosts
- Advantages [page 139].
In the SAP System, a virtual host has ist own tree of ICF services.
The procedure is explained by means of the following example.

Web Application Server

620 SP 9

136

SAP Online Help

25.10.2002

ICM Configuration
An SAP Web Application Server is running on the computer with the host name saphost and
the IP address 1.2.3.4. The ICM is configured so that ports 1080 and 8080 can receive
HTTP requests (parameter icm/server_port_<xx>). The computer also responds to the alias
myhost. Therefore, both saphost and myhost are mapped to the IP address 1.2.3.4.
You define whethere there should be different virtual hosts using the profile parameter
is/HTTP/virt_host_<n> = <host1>:port1;<host2>:<port2>;...;
(<n> stands for numbers 0,1,...9). This parameter can be changed statically in the instance
profile or dynamically in transaction RZ11. Transaction RZ11 also contains parameter
documentation. Note that parameter
is/HTTP/virt_host_0 = *:*;
is set and cannot be changed. Therefore, if no other virtual host is found, the default host
number 0 is used. The default host shows up in the HTTP service tree for transaction SICF as
default_host. Initially, this is the only virtual server.
To avoid namespace conflicts, all other hosts provided by SAP begin with SAP.
Creating a Virtual Host
To create a new virtual host, take the following steps:
1. Call transaction RZ11 and set the parameter is/HTTP/virt_host_1 z. B. to the value
myhost:*; .

Note that the dynamic change to the parameter is lost at the next system restart. If
you want to set the parameter permanently, you have to set this in the profile file.
2. Call transaction SICF. Choose Virt. Choose Virtual Host Create Virtual Host, enter (for
example) virt_host1, and create services or aliases to existing services under this
virtual host. Creating a Service [page 140] describes how this works.
As a test, create a service under virt_host1 called virtping, which uses the
same handler as the service bc/ping under default_host, that is, the HTTP
request handler CL_HTTP_EXT_PING.
This means that under the host name myhost on all ports to which the ICM responds (that is,
1080 and 8080), the HTTP service tree under the virtual host is the basis for searches for an
appropriate URL path.
Therefore, entering http://myhost:1080/virtping would have the same effect, in this
example, as http://saphost:8080/bc/ping.
At this point, however, you can also assign different modes of behaviour to the various ping
services under the various virtual hosts.
The prerequisites for this are shown in the graphic below:

Web Application Server

620 SP 9

137

SAP Online Help

25.10.2002

Client: Web Browser

SAP Web Application Server


Host Name:

http://myhost:1080/virtping

http://myhost:1080/virtping

saphost
myhost
localhost

Request

ne
er
t
In

ICM Profile Parameter


icm/server_port_<xx>:
icm/server_port_0 =
PROT=HTTP, PORT=8080
icm/server_port_1 =
PROT=HTTP, PORT=1080

Server reached successfully

Response
ICF Service Tree

SICF
Host Data of
virt_host1
Profile Parameter
Number: 1
Parameter
is/HTTP/virt_host_#
Value: myhost:*;

Specifying a Default Service for a Virtual Host


You can specify a default service for a virtual host.

As with an internal alias (see Internal Aliases [page 148]) select a target element from the
HTTP service tree. If the URL then specifies the virtual host without any additional path
information, the target service that is defined will be called.

Web Application Server

620 SP 9

138

SAP Online Help

25.10.2002

Virtual Hosts - Advantages


The following example shows how working with virtual hosts can be advantageous.

A company called ACME has a host computer. The host has two network cards and two IP
addresses. 1.2.3.4 and 1.2.5.6.
The address 1.2.3.4 connects the host to the ACME Intranet, while the address 1.2.5.6
connects the host to the Internet.
These IP addresses are assigned to the host names shown in the table below.
IP Address

Host Name

1.2.3.4

myhost.acme.com
intranet.acme.com
mailhost.acme.com

1.2.5.6

acmegate.acme.com
acmenet.acme.com

If more than one host name is assigned to one IP addess, one host name is the default name,
and the others are aliases. In the table, the default name is in bold type.
Now, a virtual host can be set up in transaction SICF for each of the two addresses. Each
virtual host has its own HTTP service tree.
SAP Web Application Server
1.2.3.4

http:
//intranet.
acme.com:1080/
Sap/bc/ping

1.2.5.6

ICF Service Tree

http://
acmenet.acme.
com:1080/
sap/bc/ping

Profile Parameter Number:1


Parameter
is/HTTP/virt_host_1 =

acmenet.acme.com:*;

For example, you can assign requests coming from the Internet (which arrive via the host
name acmenet.acme.com) to the default host, and set up a virtual host internet_host which
contains the services for these Internet requests.
In this example, both servers provide the service sap/bc/ping. If the same HTTP request
handler, or an alias, is being used, this can be the same service for both servers. Different

Web Application Server

620 SP 9

139

SAP Online Help

25.10.2002

services, with different authorizations, access restrictions, and so on, can also exist under the
same name (see Creating a Service [page 140]).
Virtual hosts therefore make it possible to separate the available services at higher levels.
See also: Interaction Model [page 108]

Creating an ICF Service


Call transaction SICF. The initial screen displays the services that already exist. The existing
services are located under sap and are provided by SAP.

We recommend that customers and partners with their own namespace create in
the HTTP service tree a top-level node with the same name as the namespace,
and create all services under this node.

To create your own service, position your cursor on the object in the tree that you want to be
the parent of the new service. This can be an existing service or a Virtual Host [page 136].
Choose Service / Virt. Host / Create service (or click on it with the right mouse button and
choose New Subelement). In the following dialog box for your service or the alias for an
existing service, enter a name and decide whether you want to create a service (Independent
Service) or an internal alias [page 148] (Alias for an existing service):

Web Application Server

620 SP 9

140

SAP Online Help

25.10.2002

Note that the service name can be 15 characters maximum! Since services are
transported, they are subject to the transport systems restrictions.
If you choose Independent service, the screen shown below appears. Enter the properties for
this service (tab page Service Data) and enter the previously created HTTP request handler
in the handler list (tab page Handler list). (Internal Aliases [page 148] describes how you
create an alias.)

Web Application Server

620 SP 9

141

SAP Online Help

25.10.2002

You can create several HTTP request handlers for a single service. These are then called in
the order you specify. The programmer can use return codes to control whether other
handlers from the list should be called, and if so, which ones.
The following sections describe the properties you can define for a service:
Anonymous Logon Data [page 143]
Security Requirements [page 145]
Service Options [page 144]
Internal Aliases [page 148]
External Aliases [page 151]
More functions of transaction SICF are described in Special Features [page 154].

Web Application Server

620 SP 9

142

SAP Online Help

25.10.2002

Anonymous Logon Data


As already described in Interaction Model [page 108] the client (Web browser) must
authenticate itself.
Logging on to SAP Web Application Server [page 113] describes the various logon
procedures and how the system selects a logon procedure.
If HTTP Basic Authentication is used (this is the default setting), the return code 401 is sent
from the ICF controller to the Web browser. The Web browser then creates a popup for the
authentication procedure. The user enters his or her username and password, and this data is
sent directly to the SAP System. When you log on to the SAP System, the default client and
the default language of the application server are used. (The process for determining the
logon language is described in Determining the Logon Language [page 114].)
You now have the option of setting logon data for the service. This data will be automatically
read and processed when the service is called, in order to authenticate the client.
You can set the following logon data:
Client
User
Password
Language

Note that here, you should only create users that have been created in SU01 as
service users (collective users). If a dialog user is created, the system warns you
about this.

Client 001, user MrTrial, password Test, and language en are set for the
service Simple. When Simple is called, via a Web browser, for example, the
client is logged on directly to the SAP System, with client 001, as user MrTrial,
in language en, and using password Test to log on.

If the client and the language have not been pre-set, the client is logged on as
user MrTrial in the default client and in the default language of the application
server.

Cumulation of Logon Data Using ICF Path


If you have maintained a hierarchy of services with various logon data in SICF, the data is
cumulated, which means that the bottom-most service in the hierarchy overwrites the one
above it. In this way, empty fields are filled, starting from the bottom.
The cumulation is valid whether or not Mandatory logon data was selected.

You have created a service A, with subservice B, which in turn has subservice C, and set the
following logon data:
Service

Logon Data
Client

A
B

User and Password

Language

alfred/******

de

001

Web Application Server

en

620 SP 9

143

SAP Online Help

25.10.2002

charly/******

If you call up service C by adding the ICF path /A/B/C to the URL, the logon data is as follows:
Client 001: C: no client has been specified for C, so the Bs client is used.
User/password charly/******: as this is maintained in C, the system does not search for
user/password.
Language en: No language is specified for C, B has the language en. A does not need to
be considered in this case.

Service Options
SAP Authorization
You can set permissions for using the server.
If text has been entered in this field (for example, 'CHECK'), when this ICF service is used, the
users permissions are checked against the value entered in this field. The permissions object
used is S_ICF. In this example, the user must have the following permissions:

S_ICF-ICF_FIELD = 'SERVICE'

S_ICF-ICF_VALUE = 'CHECK'

The authorization object is S_ICF, and the field is 'SERVICE'.


For a detailed explanation of this procedure, see the documentation on permissions
administration.
Error Type
Here you can specify the value for handling ICF authorization errors.
This is a numeric key for handling authorization errors in the Internet Communication
Framework.
This is explained below.

1: An A message is displayed (program abort)

2: An X message is displayed (program error)

All other values in this field cause an E-message to be created if an error occurs.

Server Group
Here you can specify a logon group (or select one using F4 help). You maintain logon groups
in Transaction SMLG.
If a group is entered here, the HTTP requests that call this service are forwarded to the
servers in this group only.
The SAP Web Dispatcher [page 79] balances load and assigns requests to logon groups. Of
course, this is on the assumption that all HTTP requests are sent to the SAP Web dispatcher.

Compressing
If the checkbox is activated, the system tries to compress the response page (response
document). The gzip compression process is used for this.

Web Application Server

620 SP 9

144

SAP Online Help

25.10.2002

Currently, compression can only take place if the caller can use gzip
decompression. An HTTP caller uses the header field "accept-encoding" to
inform the server of this property with "gzip" as the value.
Currently gzip compression/decompression is only supported on NT and LINUX
platforms.

Special Options
This button is used for test purposes and should only be used by SAP.

Session Timeout
You can set a session timeout for stateful connections for a service. To do this, enter the
timeout period in the field Session Timeout. If the timeout period is passed during a stateful
connection, the session is terminated and the user context is cancelled.
If the timeout is set to 0, this means that the session timeout option is not active. In this case,
the session is maintained until the profile parameter rdisp/plugin_auto_logout
becomes active (default setting 30 minutes).
See also:
Stateless and Stateful Model [page 112]

Security Requirements
The following security requirements can be set for a service or an alias:

Standard (default)

SSL

Client certificate with SSL

For example, if SSL is set for a service, and if an attempt is then made to connect to this
service via HTTP, the request is refused.

Web Application Server

620 SP 9

145

SAP Online Help

25.10.2002

Basic Authentication
If Basic Authentication is used to log on to SAP Web Application Server (in other words, if no
Anonymous Logon Data [page 143] is set and the standard logon procedure is used, see
Logging On to SAP Web Application Server [page 113]), either the standard SAP user or an
Internet user can be used.
The default SAP user is the user name that is entered in Transaction SU01.
The Internet user is the alias name that can be longer than the normal SAP user name.
This is also set in SU01.
Depending on the settings, the input in the Basic Authentication popup is interpreted as either
a user name or an alias.

Error Page
In transaction SICF you can set what should be displayed if an error occurs. As before, the
possibilities are logon error HTTP 401 (logon failed) and application error HTTP 500
(application error, for example, ABAP short dump).

If either error occurs, either an explicit response page is sent to the browser, or a redirect to a
specific URL is executed.

Response Page
You can specify the header and body of the page that is sent to the client when an error
occurs. The page body contains an Online Text Repository (OTR) alias, which means it is
available in the OTR and is therefore incorporated into the translation process. Once the text
has been translated, it is then available in the users logon language.

Redirect to URL
You can specify a URL to which the entire request is sent if an error occurs. The form fields
can be either omitted, specified in text form, or Base64 [External documentation]-encoded.

Web Application Server

620 SP 9

146

SAP Online Help

25.10.2002

Activating and Deactivating an ICF Service


Use
A service in the HTTP service tree can be active (black font) or inactive (gray font). A client
(such as a Web browser) can only call active services. If you call an inactive service, you will
see a message that access to this page is locked.
All subnodes of an active service are similarly unavailable and are displayed in blue font.
There is an example at the end of this section.
If you do not want a service to be accessed, you can deactivate this service without having to
delete it.

Activated ICF services do not pose a security risk insofar that they can be access
directly over the Internet via HTTP protocol. You should therefore ensure that
access is restricted using appropriate methods, such as ensuring that the ICF
service can be accessed only by users with appropriate authorization.

Note that all services delivered by SAP (such as the sap/bc/bsp service for
executing BSP applications) are initially inactive. Similarly, each new service that
you create is also inactive. Before you work with the ICF, you must first activate
the services you require.

Procedure
To activate or deactivate a service, select the service and choose Service/Virt.Host
Activate or Deactivate. You can also use the context menu (by clicking on the right mouse
button).
If you want to reactivate an inactive service, you can either activate the service node that is
selected only (pushbutton Yes) or the service node that is selected, including all of its
subservices that were maintained in the SICF (pushbutton Yes with tree icon ).

Web Application Server

620 SP 9

147

SAP Online Help

25.10.2002

Example

In this example, the services bc and bc/bsp/sap/public were deactivated. As a result, the
services that were explicitly deactivated (gray) and all of their subservices (blue) are
unavailable.
If you now reactivate the bc service, you can select whether you want to activate the service
itself, or all inactive subservices as well. In the first case, bc/bsp/sap/public would still be
inactive (and as a result, bc/bsp/sap/public/bc would also be unavailable); in the second
case, all services would be available again.

Internal Aliases
If you select Reference to an existing service when creating a service, you create an alias.
Instead of using an HTTP request handler in the following screen, use the tab Alias-Target to
determine where the alias should point to in the HTTP service tree. Position the cursor on the
icon in the line and choose
(Save).

Web Application Server

620 SP 9

148

SAP Online Help

25.10.2002

If the string of the internal alias is found in the URL of the incoming request, the service
assigned to this alias, that is, the HTTP request handler defined in this service, is called. In
the URL, the alias is simply replaced by the path of the service to which the alias points.

Web Application Server

620 SP 9

149

SAP Online Help

25.10.2002

Let us assume that the HTTP service tree contains a service A with subservice B. B in turn
has an alias to another service, E, which is located in a different part of the tree.

URL: http://host:port/A/B/...

ICF Service Tree


Service

Doc.

Service A

Alias

Doc. For A

Alias B

Doc. For B DEFAULT_HOST//E

Service C

Doc. For C

Service D

Doc. For D

E Service E

Doc. For E

Now, if a request is received with the string A/B/, the service A/C/D/E is called, as B is simply
replaced by the complete path to E.

You cannot create more subservices or subaliases underneath an alias in the ICF
tree.

Internal Aliases and Logon Data


The logon data is accumulated in the sequence A/C/D/E/B, that is, the logon data from E
(which can be maintained there or which can be inherited from a parent node or accumulated
from several nodes) is overridden by the logon data from alias B.
Extending the Above Example
If the following properties apply to the above example, service F is executed with the
logon data for B (user Bert):

E has a subservice, F

No anonymous logon data has been entered for F

B has the anonymous user Bert

E has the anonymous user E

The URL contains the path A/B/F


Service F is then executed with the logon data from B (user Bert)

If logon data is being overridden, this can be a reason to create an alias. You may want to call
an existing service with other logon data, or call a different logon procedure.
For details on logging on to the SAP System, see the following sections:
Logging On To SAP Web Application Server [page 113]
Anonymous Logon Data [page 143]

Web Application Server

620 SP 9

150

SAP Online Help

25.10.2002

External Aliases
External aliases are used to make it possible to call services using any appropriate nontechnical name.
You can create external aliases that link to a service (use button External Aliases). External
aliases can have the form /name1/name2/... and can be used to create more meaningful
path names to services in the ICF service tree, for example, /SAP/mySAPdotcom/ping as
an external alias to the Ping service. Unlike internal aliases, external aliases may contain
slashes.
Otherwise, an external alias is handled as an internal alias [page 148]. Just like an internal
alias, it does not differentiate between upper and lowercase.
This means that if the string of the internal alias is found in the URL of the incoming request,
the service assigned to this alias, that is, the HTTP request handler defined in this service, is
called. The service data of the external alias override those of the target service.

An incoming URL is first checked against the external aliases, then against the
internal aliases.

Transporting External Aliases


To transport an external alias, position the cursor on it and choose
or choose External
Alias Transport. The system then displays a dialog box, and you can enter the transport
key. If you choose /test*, for example, then all external aliases that begin with /test are
transported. In the following section you must specify the transport request that should
contain the transport.

Monitoring and Troubleshooting Functions


Use
This transaction provides monitoring, analyzing, and troubleshooting functions.
This means that trace and debugging functions are available when accessing the SAP
System via HTTP. Use transaction SICF to access the functions.

Note that these functions can slow down system performance. Therefore, only
activate them when genuinely necessary.

Functions
The following functions are available.

HTTP Debugging
Use Edit Debugging to switch HTTP debugging on and off for a particular user in the
current client.

Web Application Server

620 SP 9

151

SAP Online Help

25.10.2002

If debugging is active, a new mode is created showing the ABAP debugger when the
corresponding URL is entered. The ABAP debugger can then be used to debug the handler.
You have two ways to set HTTP breakpoints, which you can also combine.

You can specify the virtual host and the path part. If this is contained in the URL, an
HTTP breakpoint is set for the service in the first line of the HTTP request handler.

If you specify a handler class, a n HTTP breakpoint is set in the first line of this class.

In the popup for activating debugging, you can also make the following entries:

Only calls from SAPGUI-IP. If this option is checked, debugging is only activated if
the HTTP client (usually the browser) is running on the same IP address as the
SAPGUI of the active system. This prevents many HTTP users from debugging
sessions other than their own.

Validity period: how long debugging should be active under the specified conditions.

There are the following types of breakpoints:

HTTP Breakpoints: The debugger is called if you have passed the location when
processing an HTTP request.

Session Breakpoints: These are the usual ABAP breakpoints. The debugger is
displayed if you pass the location when processing an ABAP program.

There are two ways of setting the HTTP breakpoints. In the ABA peditor, you can activate
HTTP debugging. With every breakpoint that you set, the system asks whether it should be
an HTTP or a session breakpoint.
The other option is described above.

Debugger Not Responding


Sometimes the debugger may not open, even though debugging is activated. There are a
number of possible causes of this. Try the following:

If you have selected Only Calls from SAPGUI-IP, deselect it.

Execute the report RSBREAKPOINTS in se38 and check the breakpoints set for your
users.

Specify the exact URL you want to debug.

Web Application Server

620 SP 9

152

SAP Online Help

25.10.2002

Also check the system debugging. The debugger should now open.

Trace
Use Edit Trace to switch on the trace for the current user. The details for the trace
correspond to the User Trace [External documentation] that you can activate in transaction
SM04. In the popup, you can set the following properties for the trace:

Protocol: you can use traces both for HTTP and SMTP communication.

URL path: prefix for the path where the trace should be created.

Validity duration: length of time the trace should be active for this path (if it is not
deactivated by Trace Deactivate).

Only calls from SAPGUI-IP. If this option is checked, debugging is only activtaed if the
HTTP client (usually the browser) is running on the same IP address as the SAPGUI of
the active system. This prevents many HTTP users from debugging sessions other than
their own.

Trace level: you can set trace level 2 or 3.

You can then deactivate the trace and view it using Edit Trace Display Trace.

Runtime Analysis
You can use Edit Runtime Analysis to activate runtime analysis for the current user. The
same popup appears as for the trace (exception: trace level).
If you want to display the runtime analysis, open transaction se30 and choose Other File on
the entry screen. Enter SAPSYS as the user. You can then select a request from the list and
view the runtime.
For details on runtime analysis, see the documentation: Runtime analysis [External
documentation].

Server Monitor
Use Edit Server Monitor to display which of the executed functions are activated, either for
the current server or for the entire SAP System.
Since these functions effect performance, it is recommended that you monitor the settings
and deactivate settings that are no longer needed.

Web Application Server

620 SP 9

153

SAP Online Help

25.10.2002

In this example, the local view has been selected. Trace and runtime analysis are both
activated for one user, and debugging is not active.

Note that the analysis tools can influence performance. Only implement an error
search, and do not forget to deactivate the tools (debugging, trace and runtime
analysis) after you have used them!

Special Features
Public Services
Services are defined under the node Public. These services are mainly intended for test
purposes. These services are different from other services in the tree in that although no user
data is set for these services, they require no logon to the SAP System. All actions in these
services are carried out under a standard system user. For this reason, you cannot create
your own service under the node Public.

Options
Special services are located under the node Options. These services are for SAP-internal
use.

Parse URL
Use Edit Parse URL to display details of how any URL is used in searches for services,
aliases, and so on.

Other Functions
Choose Go to to go to other functions used for configuring and analyzing HTTP
communication.
ICM Monitor
This is the monitoring transaction for the Internet Communication Maneger (ICM). It is
described in detail under Monitoring the ICM with the ICM Monitor [page 68].
Message Server Monitor
This is the monitoring transaction for the SAP Message Server. For documentation on this
see Message Server Monitor [External documentation].

Web Application Server

620 SP 9

154

SAP Online Help

25.10.2002

Maintain Profile Parameters


In this transaction you can display all profile parameters, and dynamically change many of
them.

Note that with dynamic changes, these are lost the next time the instance is
started. So that changes are still effective when the system is restarted, you must
include the changes in the profile file.

Transporting ICF Services


ICF services are transported in accordance with the transport and correction configuration,
provided that you created the ICF services as a package component and not as a local
object.

Note the following points in connection with transporting ICF services.

If you create a service, ensure that the service is always transported from the original
system.

The services delivered by SAP should never be deleted. If you want to prevent the
service from being used, you can deactivate it (see Activating and Deactivating an ICF
Service [page 147]).

If anonymous logon data exists for a service, this data is deleted when the service is
transported.

External aliases are not transferred without further processing. For information about
transporting external aliases, see External Aliases [page 151].

HTTP Communication Using the SAP System as a


Client
Uses
As already mentioned, it is also possible to use the SAP System as a client (see SAP Web
Application Server: Webserver or Webclient [page 99]).
This means that an ABAP application program can send requests to the Internet. Based on
the response returned by the HTTP server, the client can either produce output or further
process the request.

Process
In the next section, the Interaction Model [page 156] between the HTTP client (an SAP
System), the Internet Communication Framework (ICF), and a HTTP server (for example,

Web Application Server

620 SP 9

155

SAP Online Help

25.10.2002

another SAP System), is described. This makes it easier to understand the client interface
design. A Sample Program [page 157] shows you how to program a HTTP request.
The section Connection Establishment Using Destination (SM59) [page 161] describes how to
maintain destinations for HTTP connections.
Examples are used to explain how Parallel Processing [page 164] and Redirecting Requests
[page 165] are programmed.
Lastly, the Interface IF_HTTP_CLIENT [page 167], which is used for the client role, is
described.
You can use a proxy server to send your HTTP requests to the Internet. See Configuring
Proxies [page 165].

Interaction Model
In this section, the data and control flows for the client role are described using an illustration
similar to that in section Interaktionsmodell [page 108].
When an ABAP application program in the SAP System sends a HTTP request to the
Internet, the steps shown in the illustration are taken (see also the explanatory notes under
the illustration).

HTTP
Server

HTTP Client (SAP Web Application Server)

Request
et
rn
e
t
In

et
rn
e
nt

Web Server

ICM

Dispatcher

Memory Pipes

4
Task Handler

7
8

ABAP

ICF Manager (IF_HTTP_CLIENT)

ABAP Application Program

1
2
3

Response

1. An object in the class CL_HTTP_CLIENT is created. This object is referred to here as the
client control block (similarly to the server control block). The structure is described under
Interface IF_HTTP_CLIENT [page 167].
To do this, the method CL_HTTP_CLIENT=>CREATE and/or
CL_HTTP_CLIENT=>CREATE_BY_DESTINATION is called. The ABAP application
program that sends the request calls the method.

Note that the activities in points 2, 3, 5, 7, 8 and 9 must also be triggered by the ABAP
application program, that is, by calling the appropriate methods. The ABAP application
Web Application Server

620 SP 9

156

SAP Online Help

25.10.2002

program, therefore, uses the components of the class CL_HTTP_CLIENT so that it can
process the request and response data.

If you want to call the method CL_HTTP_CLIENT=>CREATE, the following information


must be available to the method: HOST (host name), SERVICE (port),
PROXY_HOST (host name of the proxy host), PROXY_SERVICE (port of the proxy
host) and SCHEME (specifies whether HTTP or HTTPS should be used; has the
default value SCHEMETYPE_HTTP).

If you want the method CL_HTTP_CLIENT=>CREATE_BY_DESTINATION to be


called, you have to make the corresponding entries in transaction SM59 for the HTTP
destination (node HTTP Connections to R/3 System or HTTP Connections to Ext..
Server). For details on the settings, see Connection Establishment Using Destination
(SM59) [page 161].

2. Filling the client control block you have created:


the attribute REQUEST is filled with the required request data.
3. The method SEND is called and the request is sent.
The connection is opened and the request is converted to a HTTP data stream
(serialized).
4. The request is sent to the HTTP server in question via task handlers and the Internet
Communication Manager.
5. If the HTTP server requires authentication (for example, if the server is also an SAP
System), the client must log on at this point.
If the server is also an SAP System, the client logs on via an SAP logon popup.
Otherwise, the client logs on via the HTTP standard popup. This query whether the SAP
logon popup or the HTTP standard popup should be used is executed within the method
RECEIVE (see 7).
This authentication is carried out in dialog processes, not in batch processes.
6. The HTTP server generates a response and sends it back.
7. The method RECEIVE is called and the response data is read in and the attribute
RESPONSE of the control block is filled.
8. The data is processed or output by means of accessing the response attribute.
It is also possible to transfer the output to the HTML control. In this case, the
response is displayed as it would be in a browser.
9. The method CLOSE is called and the connection is thus closed.

The following ABAP Sample Program [page 157] executes a HTTP request. The
request is sent to the same SAP instance (as SAP Web Application Server can
function as both server and client).

Sample Program
The following ABAP program executes a HTTP request. The requests destination is the
ABAP program itself, as the SAP Web Application Server can function both as a server and
as a client.
report HTTP_Test.
* data declarations
data: client type ref to if_http_client.

Web Application Server

620 SP 9

157

SAP Online Help

25.10.2002

The following parameters must be specified. If nothing is entered, the following default values
are used: host (default value: current host), service (default value: port 80 for HTTP and port
443 for HTTPS), protocol (default: HTTP/1.0), path to the required service, as described in
Implementation [page 134] (default: /sap/public/ping). If the connection using the Destination
(SM59) [page 161] is used when the client object is created, these parameters must be set
accordingly in the destination.
data: host type string value = host.wdf.sap-ag.de,
service type string value = 8080,
path type string value = '/sap/public/ping',
errortext type string. "used for error handling
The object of the type CL_HTTP_CLIENT is created (step 1). As described, there are two
possibilities here, which are juxtaposed below.

In one case, the create method is called; here you must enter the required host and
port, and you can also enter the proxy setting. This overrides any configuration that was
made in Transaction SICF (see also Configuring Proxies [page 165]).

In the other case, the destination that was maintained in Transaction SM59 is used
(method create_by_destination). Only the name of the destination and the client
need be specified here. In both cases, you have to define exceptions (not shown here)
and query the last error code.

The object client can be used to access all data (request, response, header field, and so
on).
The scheme determines whether HTTP or HTTPS is to be used.
* create HTTP client object(s)
call method
cl_http_client=>create
exporting host

call method
cl_http_client=>create_by_destination

= host_str

exporting destination = dest

service

= service_str

proxy_host

= proxy_host

importing client
exceptions

proxy_service = proxy_service
scheme

= scheme

importing client

= client

destination_not_found
internal_error

= client

= 1

= 2

argument_not_found = 3

exceptions

destination_no_authority = 4

argument_not_found = 1
internal_error

= 2

plugin_not_active

= 3

= 4.

plugin_not_active
= 6.

= 5

others

others

if sy-subrc <> 0.
write: / Create failed, subrc = ', sy-subrc.
exit.
endif.
Header fields for the requests are set here. Setting the HTTP request method to GET is
optional. (If this field is not set, the system uses GET if the HTTP request does not contain a
body. Otherwise, it uses POST.) You must set the request URI unless the whole path was
Web Application Server

620 SP 9

158

SAP Online Help

25.10.2002

specified as a path prefix using the Destination (SM59) [page 161]. Here you use method
set_request_uri of class cl_http_utility.
* set header fields
call method client->request->set_header_field
exporting

name = '~request_method'
value = 'GET'.

* Set request protocol


if protocol = 'HTTP/1.0'.
call method client->request->set_header_field
exporting

name

= '~server_protocol'

value = 'HTTP/1.0'.
else.
call method client->request->set_header_field
exporting

name

= '~server_protocol'

value = 'HTTP/1.1'.
endif.
cl_http_utility=>set_request_uri( request = client->request
uri

= uri ).

Any number of fields in the control block can be filled (step 2).
You can also request that the response is compressed with the gzip-process for sending:
* should server send its response in gzip, if possible
if cl_http_client=>c_compression_supported =
if_http_client=>co_enabled.
call method client->request->set_header_field
exporting name

= 'accept-encoding'

value = 'gzip'.
endif.
endif.

Additional Options

You can use method SET_COOKIE of IF_HTTP_ENTITY to set a cookie. You can use
this to maintain the status in the session.

You can deactivate attributes PROPERTYTYPE_LOGON_POPUP and


PROPERTYTYPE_REDIRECT which have the default value CO_ENABLED (set to
CO_DISABLED).

You can set PROPERTYTYPE_ACCEPT_COOKIE to different values. The default value is


CO_DISABLED, but values CO_ENABLED (always accept cookies), CO_PROMPT (send a
dialog box when cookies are received to ask if the cookie should be accepted) and
CO_EVENT (cookie handling using event EVENTKIND_HANDLE_COOKIE of interface
IF_HTTP_CLIENT [page 167]) are also available.

Before the request is sent, you can also enter the necessary logon data using the
AUTHENTICATE()method of interface IF_HTTP_CLIENT [page 167].

Web Application Server

620 SP 9

159

SAP Online Help

25.10.2002

Now, the request is sent (step 3).


* Send
call method client->send
exporting

timeout = timeout

exceptions http_communication_failure
http_invalid_state

= 2

http_processing_failed

= 3

others

= 1

= 4.

if sy-subrc <> 0.
call method client->get_last_error
importing code

= subrc

message = errortext.
write: / 'communication_error( send )',
/ 'code: ', subrc, 'message: ', dummy.
exit.
endif.
Here, the last error must be queried, using client->get_last_error.
Now, the response is received and the client object is filled with the response data (step 7).
* receive
call method client->receive
exceptions http_communication_failure
http_invalid_state

= 2

http_processing_failed

= 3

others

= 1

= 4.

if sy-subrc <> 0.
call method client->get_last_error
importing code

= subrc

message = errortext.
write: / 'communication_error( receive )',
/ 'code: ', subrc, 'message: ', dummy.
exit.
endif.
Exceptions and error queries must be inserted here too.
If the connection is no longer being used, you must close the client object and the connection,
as follows:
* close
call method client->close
exceptions http_invalid_state

= 1

others

= 2.

To document the successful test, the output routine is called at this point.

Web Application Server

620 SP 9

160

SAP Online Help

25.10.2002

* output
perform write_document.

The ABAP code above is only a simple example, and is not an example of
professional work!

Connection Establishment Using Destination


(SM59)
For the system to be able to establish a connection using a destination by means of the
method CL_HTTP_CLIENT=>CREATE_BY_DESTINATION, the appropriate entries must be
made for the HTTP connection in transaction SM59.
There are two types of HTTP connection in SM59:

The HTTP connection to the external server and the HTTP connection to the R/3 system are
different only in their logon procedures. Their technical settings are the same.

Web Application Server

620 SP 9

161

SAP Online Help

25.10.2002

You can make the following entries:


Target host This is the destination of the connection.

Note that if you are using HTTPS as a protocol, you have to specify the full host
name (with domain).
Service No. Here, you specify the port. The destination host must of course be configured
in such a way that the specified port understands the corresponding protocol (HTTP or
HTTPS). See Parameterizing the ICM and the ICM Server Cache [page 45].
PathPrefix At the time when the connection to this destination is initiated, the system
inserts this sub-path before ~request_uri.
HTTP Proxy Options Here you can configure a proxy for HTTP connections: You can
determine the proxy host and service, as well as users and passwords for the HTTP
connection.
The tabstrip Logon/Security is different, depending on whether you choose HTTP Connection
to ext. Server or HTTP Connection to an R/3 System.

HTTP Connection to Ext. Server

Here, you can activate SSL to ensure that HTTPS is the protocol used (if you select SSL,
make sure that the correct port is entered under Technical settings). In the security
transaction you can determine which type of SSL client is used.

Web Application Server

620 SP 9

162

SAP Online Help

25.10.2002

You can also set permissions for using the destination and specify a user name and
password.

HTTP Connection to an R/3 System


Here, you can specify more settings for authentication on the destination system.

As with an external server, SSL can be activated or deactivated, and permissions can be set
for it.
Because the destination system is an SAP System, you can set the client and language for
the logon as well as the user name and password. If you check Current User, you have to
specify the password.
The following authentication procedures are available: Basic Authentication, SAP Standard,
and SAP Trusted System.
HTTP Basic Authentication: Standard HTTP 410 logon
SAP Standard: This procedure uses an RFC logon procedure. The RFC Single Sign-On
(SSO) procedure is valid within the one system. The same SAP user (client, language,
and user name) is used for logon.
SAP Trusted System: Trusted RFC logon to a different SAP System

Web Application Server

620 SP 9

163

SAP Online Help

25.10.2002

Parallel Processing Requests


Use
It is possible to send requests to various servers in parallel and to wait for all the responses
simultaneously. The method LISTEN is then used to find out which request is being
responded to.
This is worthwhile if several requests have been assigned to different servers with widely
differing response times.

Activities
Extend the program above by adding the following lines.
The following is an extra parameter with which you can specify whether the method LISTEN
should be used and how many requests should be sent:
parameters: listen type c default space,
times

type i default '1',

Now the system waits for the responses to the requests. The responses are received in the
order in which the server sends them.
* receiving with listen (parallelizing #times requests)
do times times.
if not listen is initial.
call method client->listen
receiving

client = cclient

exceptions http_communication_failure

= 1

http_no_open_connection

= 2

others

= 3.

if sy-subrc <> 0.
call method client->get_last_error
importing code

= subrc

message = dummy.
write: / listen,
/ 'code: ', subrc, 'message: ', dummy.
exit.
endif.
The incoming responses are re-assigned to the requests.
* Assigning responses to requests
* If there are more requests, accept all responses
client = cclient.
call method client->receive

Web Application Server

620 SP 9

164

SAP Online Help

25.10.2002

exceptions http_communication_failure
http_invalid_state

= 2

http_processing_failed

= 3

others

= 1

= 4.

if sy-subrc <> 0.
call method client->get_last_error
importing code

= subrc

message = dummy.
write: / 'communication_error( receive )',
/ 'code: ', subrc, 'message: ', dummy.
exit.
endif.
...
enddo.
You can then specify how often a request should be dropped (parameter times). You can
see in the output the order in which the responses were received. This does not have to be
the order in which the requests were sent.

The ABAP code above is only a simple example, and is not an example of
professional work!

Redirecting Requests
Use
If a request is sent to a server whose location has changed, a new connection is opened and
the request is sent to the new address. This ensures that not only the fields in the URL, but
also any XML document that may be contained in the request, are sent to the new address.
The redirect is active in the default setting. To deactivate the function, set the attribute
PROPERTYTYPE_REDIRECT in the client control block to CO_DISABLED.
See also: Interface IF_HTTP_CLIENT [page 167]

Configuring Proxies
Use
If you use the SAP Web Application Server as an HTTP client, you can determine a proxy that
is used for outgoing HTTP requests.

Web Application Server

620 SP 9

165

SAP Online Help

25.10.2002

A proxy server is used as a security barrier between the internal network (intranet) and the
Internet, by preventing other persons on the Internet from having access to the confidential
information in the intranet.

Procedure
The following describes how you can configure a proxy server in Transaction SICF. You can
also make the configuration in your client ABAP program when you generate the client object.
You can find an example of this in Sample Program [page 157].
1. Enter Transaction code SICF (see also Creating an ICF Service [page 140]) or choose
Administration System Administration Administration Network Maintain the
HTTP Service Tree.
2. Choose Goto HTTP Client Proxy.
The following screen appears:

Here you can configure the proxy server that should be used.

Use the Proxy setting is active checkbox to determine whether the connection to the
Internet should be made via a proxy server using the configuration that you have
determined here.

If you activate No proxy setting for local servers, you determine that the proxy server
should be used for all local (intranet) addresses. Those servers with hostnames that do
not contain any domains, such as PC01 instead of PC01.sap.com, count as local servers.

Since a proxy server works as a security barrier between the internal network
(intranet) and the Internet, you may require special authorization from the system
administrator to access websites with the proxy server. It may be easier and
faster to access local addresses if you do not use the proxy server.

You can use the field Authorization as follows: When you enter a text (such as 'CHECK')
in this field, when you use the global proxy setting the system checks the users
authorization for this value. The authorization object used is S_ICF. In this example, the
user must have the following authorization: S_ICF-ICF_FIELD = 'PROXY' and S_ICFICF_VALUE = 'CHECK'. If the user does not have this authorization, the settings that
were maintained are not evaluated for the HTTP request.

Web Application Server

620 SP 9

166

SAP Online Help

25.10.2002

In No Proxy for the Following Addresses, you can maintain the Web addresses (host
names) that should not be accessed using the proxy server. If you want to connect to a
server in the intranet, ensure that its address is entered here. If, for example, the server is
called PC01, enter PC01 in the field.

You can use placeholders to assign domain and host names, such as
www.*.com; *x* and so on.
The ABAP language element CP compares addresses to assess individual
entries for the use of the proxy setting.
The individual entries must be closed by a semi colon (;).
Furthermore, for the HTTP and HTTPS protocols, you can store the host name and the proxy
server port, as well as users and passwords for logging onto the proxy server.

Ensure that the proxy settings are not transported!

Interface IF_HTTP_CLIENT
Definition
If the SAP System is in the client role, the interface IF_HTTP_CLIENT of the class
CL_HTTP_CLIENT is implemented. IF_HTTP_CLIENT serves as an interface for gaining
access to data structures, so that request and response data can be processed. It also
ensures communication between client and server, in this case from the perspective of the
client.

Use
An object of the class CL_HTTP_CLIENT, a client control block, is created for every outgoing
request, as described above. Just like an object of the class CL_HTTP_SERVER, this object
contains the data structures IF_HTTP_REQUEST and IF_HTTP_RESPONSE for the HTTP
request and HTTP response data. It also provides interface references in its own interface to
these data structures: attributes REQUEST and RESPONSE. In this case, the response part is
empty when the request is sent.
The interface IF_HTTP_CLIENT contains its own attributes and methods, which are different
from the server interface, or else do not occur there. These attributes and methods are
described below.

Structure
The following graphic shows an overview of the instance attributes and the interface methods.
The interfaces for HTTP request and response are the same as in the server case for
IF_HTTP_SERVER [page 117]. These are described in IF_HTTP_RESPONSE and
IF_HTTP_REQUEST [page 119].

Web Application Server

620 SP 9

167

SAP Online Help

25.10.2002

This interface can also be used to access the following components:


Attributes [page 168]
Constants [page 169]
Methods [page 169]

Attributes
The interface IF_HTTP_CLIENT contains the following attributes:
Attribute Name

Use and Meaning

REQUEST

See IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]

RESPONSE
PROPERTYTYPE_LOGON_POPUP

Logon screen display (default: CO_ENABLED)

PROPERTYTYPE_REDIRECT

Document redirect (default: CO_ENABLED)

PROPERTYTYPE_ACCEPT_COOKIE

Accept cookie fields from the response (default: CO_DISABLED)

The PROPERTYTYPE_* attributes can take on the values CO_DISABLED, CO_EVENT,


CO_PROMPT and CO_ENABLED (see Constants [page 169]).
See also:
Web Application Server

620 SP 9

168

SAP Online Help

25.10.2002

IF_HTTP_SERVER [page 117]

Constants
The following constants are implemented in the interface IF_HTTP_CLIENT:
Name of Constant

Meaning

VERSION

Version of HTTP client (user agent)

CO_DISABLED

Inactive

CO_EVENT

Cookie handling: a specially programmed event


handler takes control
Event EVENTKIND_HANDLE_COOKIE is triggered
each time a cookie should be set. The application
must be programmed in such a way that the cookies
can be accepted or rejected as required.
Cookie handling: the prompt popup of the Web
browser opens, asking if cookies should be accepted.

CO_PROMPT

In background operation (communication without the


SAP GUI) this is not practical; use CO_EVENT instead.
CO_ENABLED

Active

CO_TIMEOUT_DEFAULT

Timeout standard value (instance timeout)

CO_TIMEOUT_INFINITE

No timeout

CO_COMPRESS_BASED_ON_MIM
E_TYPE

Compression only for defined MIME types.

CO_COMPRESS_IN_ALL_CASES

Compression of all documents

CO_COMPRESS_NONE

No compression

Methods
The interface contains the following methods. These are partly the same as in the server role.
ESCAPE_HTML

See IF_HTTP_SERVER [page 117]

ESCAPE_URL

See IF_HTTP_SERVER [page 117]

UNESCAPE_URL

See IF_HTTP_SERVER [page 117]

AUTHENTICATE

Authenticates the HTTP server.


If an SAP System is being used, this method allows authentication
via the SAP logon screen. User, password, client, and language
must be entered.
Otherwise, authentication proceeds in accordance with the HTTP
server in question.

Web Application Server

620 SP 9

169

SAP Online Help

25.10.2002

APPEND_FIELD_URL

See IF_HTTP_SERVER [page 117]

CREATE_ABS_URL

See IF_HTTP_SERVER [page 117]

CREATE_REL_URL

See IF_HTTP_SERVER [page 117]

CLOSE

Closes the HTTP connection.


This method is called when the HTTP connection, that is, the control
block, is no longer needed.

RECEIVE

Enters the response in the RESPONSE structure.


This method must be called for every HTTP request, so that the data
received can be further processed.

GET_LAST_ERROR

See IF_HTTP_SERVER [page 117]

LISTEN

Only used if several requests must be sent at the same time. When
a response arrives, this method is used to determine which request it
corresponds to.
Then, the method RECEIVE (see above) can be called.

SEND

When the REQUEST attribute is filled with the request data, the HTTP
request can be sent to the HTTP server, by calling the method
SEND.
The method converts the data to a HTTP data stream and sends the
data stream to the server.
The timeout for the waiting period for the response is communicated
to the method in the form of seconds. The Constants [page 169]
CO_TIMEOUT_DEFAULT and CO_TIMEOUT_INFINITE can also be
used here.

REFRESH_COOKIE

Reset the cookie object (the object still exists, just has no content)

REFRESH_REQUEST

Reset the request object

REFRESH_RESPONSE

Reset the response object

SET_COMPRESSION

Activate/deactivate the compression. This uses constants


CO_COMPRESS_BASED_ON_MIME_TYPE,
CO_COMPRESS_IN_ALL_CASES and CO_COMPRESS_NONE.

The section Interaction Model [page 156] gives an example which illustrates the use of some
of these methods.
For sample programs, see Sample Program [page 157] and Parallel Processing Requests
[page 164].

Web Applications and Business Server Pages


Uses
You can use the SAP Web Application Server to develop Web applications that are based on
the Internet Communication Framework [page 106] and the HTTP request handler
IF_HTTP_EXT_BSP. These Web applications are also known as BSP applications (Business
Server Page applications).

Web Application Server

620 SP 9

170

SAP Online Help

25.10.2002

Functions
The SAP development environment (transaction SE80) has been enhanced with the Web
Application Builder for BSP applications (see documentation on the Web Application Builder
[External documentation]).
You can create HTML pages or Business Server Pages (BSPs) with server-side scripting in
ABAP or JavaScript.
The documentation for creating BSP applications is divided into the following sections:
User Concepts [page 171]
Programming Model [page 197]
Programming Environment [page 407]
Workplace 2.11 [page 516]
Enterprise Portal 5.0 [page 519]
Administration [page 523]

User Concepts
When a client (Web browser) connects with the SAP Web Application Server (by URL call),
the logon is completed in the underlying SAP System.
The section Logging On To SAP Web Application Server [page 113] describes the procedure
involved and how it can be set up.
We distinguish between different concepts here:

Using a Default User for BSP Applications [page 189]

Using a Default Internet User for BSP Applications [page 191]

You can also let a BSP application run under the public user and switch to an
already known User ID later. You can find further information about this type of
delayed logon in Note 429165 (User Switch (Delayed Logon) in the HTTP
Framework).
Logging onto BSP Applications [page 171]explains how you can use a logon screen in your
own BSP application without using basic authentication, and how you can adjust this screen
individually.

Logging onto BSP Applications


Use
When creating Web applications, you can define logon screens for end users in your system.
For the sake of simplicity you can use a logon screen which is similar to the classic logon
screen, where you must enter the client, user name, password and language. You can
determine which fields should be available for your BSP application.

Web Application Server

620 SP 9

171

SAP Online Help

25.10.2002

In addition to logging on to the BSP application, it is also extremely important


that you log off [page 188]correctly.

This is an example of a classic SAP System logon screen:

This is an example of a logon screen for a BSP application defined with SYSTEM.

See also:
Logging On To SAP Web Application Server [page 113]
Authentication [page 177]
Enhancements [page 185]

Prerequisites
You can find the absolutely essential steps that you must carry out in order to
ensure that the logon functionality works smoothly in Reqrequisites [page 173].
See also Note 51006 Setting Up SSL On the Web Application Server.
You should then test [page 174] the security functions.

Web Application Server

620 SP 9

172

SAP Online Help

25.10.2002

Functions
You can find current information about this logon functionality in Note 517860.
The following BSP applications are available for creating your own logon screens and
enhancing them.

SYSTEM [page 179]


Application for the logon

SYSTEM_PRIVATE
Your own application. This is only a sample BSP application that represents your own
application.

SYSTEM_PUBLIC [page 180]


Test application to test user-specific settings

If you want to use one of the additional functions such as Need password hint?
Or Forgotten password?, then as an application developer you must create your
own PUBLIC BSP application, which contains pages with this information.

Prerequisites
This section provides an overview of the absolutely essential steps that you must
carry out to ensure the logon functionality runs smoothly.

SAP Web AS System


You are using an SAP Web AS 6.20 system and have implemented at least Support Package
3.

Checklist for configuration in the system


The following is set in the SAP Web AS System.
Short instructions for configuring the security functionality (SSO2)
1. Profile parameters login/accept_sso2_ticket and login/create_sso2_ticket
are set to 1.
You can find details in configuring the system so that is displays logon tickets [page
549].
2. The SAP Cryptographic Library is installed.
You can find details in Installing SAP Cryptographic Library on the SAP Web AS
[page 531].
3. The system is now restarted.
4. The SAP Web AS is configured for using SSL [page 534]:
a. A PSE was generated.
You can find details in Creating SSL Server PSE [page 535].

Web Application Server

620 SP 9

173

SAP Online Help

25.10.2002

b. A certificate requirement was created for the PSE.


You can find details in Creating Certificate Requirements for the SSL Server PSEs
[page 537].
c.

The certificate requirement was sent to a certification authority (CA)


You can find details in Sending Certificate Requirements to a CA [page 537].

d. The generated PSE was imported.


You can find details in Importing Certificate Replies [page 539].
e. The certificate list of the PSE was entered.
You can find details in Maintaining the SSL Server PSE Certificate List [page 540]

These settings are all explained in Security on the SAP Web Application Server
[page 527].
See also Note 51006 Setting Up SSL On the Web Application Server.
Configuring the Internet Communication Manager (ICM)
In the Internet Communication Manager [page 22] you have configured the HTTPS service (in
Goto Services in Transaction SMICM), see also Displaying and Changing Services [page
74].
Testing the settings
See Testing Security Settings [page 174]

Testing Security Settings


Use
Once you have gone through the checklist [page 173] for the configuration of the security
function and the ICM, you should test your settings.
Initial situation
Browser

Server

GET /URL1

Step 1
Authentication
Request (401)
Dialog Box with
User and Password
Query

GET /URL1 with


Basic Authentication
Content

Step 2
OK (200)

and SSO2 (?)

GET /URL2 mit


Basic Authentication
and SSO2 (?)
Content

Web Application Server

Step 3
OK (200)

620 SP 9

174

SAP Online Help

25.10.2002

The initial situation is represented as follows:


Step 1

When a URL is called (such as a page of a BSP application), the browser sends a GET
request to the server. The server does not have any authentication information and
therefore requests it (return code 401).
It displays a dialog box in the browser, requesting the user name and password.

Step 2

As soon as the user has been authenticated using this data (basic authentication), the
information is specified in the header with the next GET request.
The server therefore recognizes that the user is authorized to display the URL and
therefore displays the page contents (return code 200). It is also possible that the server
sends additional SSO2 information, although this cannot be verified.

As soon as basic authentication has been used once, it is always user afterwards.

Step 3

If a different URL is now called (such as a page of a different BSP application), this
means that an additional GET request is sent to the server with a new URL. The basic
authentication information is also sent with the header. Theoretically, SSO2 information
can also be specified, but again this cannot be verified.
Due to the basic authentication information, the requested page is always displayed in
the browser (return code 200).

It is not possible to find out here whether SSO2 information is transmitted, or whether SSO2
is used at all. You must therefore suppress basic authentication in the following test scenario.
Test scenario
Browser

Server
GET /URL1?name + password

Step 1
Content and SSO2 (?)

OK (200)

GET /URL2 with SSO2


(?)

200 or 401

Step 2

OK (200)

Authentication

With
Content

Request
(401)

The test scenario is as follows:


Step 0

All browser windows are closed in order to get rid of all previous basic
authentication information.

Web Application Server

620 SP 9

175

SAP Online Help

Step 1

25.10.2002

Server authentication is then enforced without using basic authentication. This is


done by transferring the name and password directly to the first URL.
The contents of the URL are returned (return code 200) as well as hopefully
the SSO2 information.

Step 2

A new GET request is now sent to the server. With this second URL, however, the
name and password are not explicitly transferred. Instead, this information is
implicitly available in the SSO2 cookie if everything is running correctly.
The system returns either return code 200 or return code 401:

If SSO2 is working, then return code 200 is sent and the content is displayed in
the browser.

If, however, SSO2 is not working correctly, then return code 401 is sent with
an authentication request, since the server does not have any authentication
information and must explicitly request this first.

Procedure
1. Close all browser windows.
2. Select a BSP application for testing, such as BSP application TUTORIAL_1.

Ensure that this is not a BSP application that has an anonymous display user in
Transaction SICF.
3. Select a page of this BSP application that you want to execute for the test and call it up in
a browser.
Example of a page:
http://ls0028.wdf.sapag.de:1080/sap/bc/bsp/sap/tutorial_1/default.htm
4. Choose Cancel for the authentication query that follows.
5. Now manually extend the URL in the browser with the user name and password data.
Example of an extended URL:
http://ls0028.wdf.sapag.de:1080/sap/bc/bsp/sap/tutorial_1/default.htm?sapclient=000&sap-user=testuser&sap-password=test
6. Choose Enter.
The browser displays the page you requested.
7. Now choose a different BSP application whose page you want to display for the test, and
enter the corresponding URL in the browser.

Ensure that this too is not a BSP application that has an anonymous display user in
Transaction SICF.
This time do not enter the user name and password information.
Example of a page:
http://ls0028.wdf.sapag.de:1080/sap/bc/bsp/sap/tutorial_3/search.htm
8. Choose Enter.

Result
Two cases can occur as a result:

Web Application Server

620 SP 9

176

SAP Online Help

25.10.2002

The application is displayed correctly (return code 200).


The security settings (SSO2) in your SAP Web AS System are configured correctly.

The application is not displayed, instead you receive return code 401
(authentication request).
In this case, you should check the settings for security and for the ICM in your system
(see Prerequisites [page 173]).

The Authentication Process


Uses
If a browser requests a page from a Web server, it usually uses an HTTP GET command to
fetch the page, provided that the page can be accessed publicly. Initial access to an open
Web page typically looks as follows:

GET

return code = 200 (OK)


and page contents

In principle an SAP Web AS System behaves like a usual R/3 System, in which each R/3
session must be assigned to a specific user ID. Even if PUBLIC pages are supported, they
are not considered normal.

PUBLIC pages run under the SAPSYS service user. It is recommended that you
only use these public pages to access style sheets from the MIME repository and
for special application cases.
Usually, if a browser access a BSP application, the SAP Web AS will return the HTTP request
and ask for authentication information. The browser displays a small dialog box that requests
the user name and the password. This information is then returned with the next request as
an authentication header (in basic authentication format).
The usual process is then as follows:

GET

return code = 401


(authentication required)

GET (with authentication: header)

return code = 200 (OK)


and page contents

Note the following with basic authentication:

The browser dialog box can only request the name and password. You cannot enter any
information about the SAP clients or the language. (This information can also be
transferred using URL parameters.)

The information is entered via the browser and, as soon as it is received from the user, it
is sent to the server with every request.

The user name and password are only coded with a Base64 routine and are therefore not
secure.

You have no option of changing the information or deleting it from the server. As soon as
the browser receives this information, it sends it with each request. As a result the
request is accepted from the SAP Web AS for further processing (provided that the logon

Web Application Server

620 SP 9

177

SAP Online Help

25.10.2002

information is correct). This means that it is not possible to log off if you are using basic
authentication.
The SAP Web AS supports SSO2 cookies for the authentication (see also Using Logon
Tickets [page 547]). This has many advantages:

As soon as the first authentication is made using the SAP Web AS (it is recommended
that you execute this using HTTPS), a digitally signed is output and the user name and
password are not transferred using Base64 coding.

SSO2 cookies can be used to log on once, if many servers of this type were configured,
so that they can all accept the same logon ticket.

SSO2 cookies help with implementing a logoff option, where the Sso2 cookies are simply
deleted.

Note that an SSO2 cookie is approximately 1 KB and this information is


transmitted to the server with every request from the browser.
The logon application SYSTEM [page 179] requires SSO2 cookies and only supports logon
using SSO2 cookies. The SYSTEM itself must be declared as a publicly accessible
application, so that the user is presented with an initial screen in which all information that is
relevant for the logon can be entered.
At the next request, the system tries to log on the user with his or her own data. It then sets
an SSO2 cookie and starts the requested BSP application.
The usual logon process is then as follows:

GET /bsp/XYZ

return code = 302 (Redirect)


to /bsp/system/logon.htm

GET /bsp/system/logon.htm

return code = 200 (OK)


and logon screen

POST /bsp/system/logon.htm

return code = 302 (Redirect)


to /bsp/XYZ with SSO2 cookie

If a logoff sequence is required, only the SSO2 cookie must be deleted and, in the case of
stateful applications, the application must be changed back to stateless mode, in order to
clean up the roll area. In this context logoff means that the authentication information must be
deleted, so that at the next request the user is asked to enter this information.
In order to provide help for logon screens, you can use the logoff.htm page in SYSTEM.
The BSP application must define one logon button and place the URL of the logoff page as
HREF. The demo BSP application SYSTEM_PRIVATE contains an example of this.

Logoff Example
The logon application SYSTEM also contains a logoff.htm page, which can be used to delete
the SSO2 cookie and also to return the application to stateless mode, so that the roll area is
clean.
This is usually integrated in a BSP application as a logoff button, which contains a reference
to the logoff page, such as:
<a href="<%=CL_BSP_LOGIN_APPLICATION=>
SET_LOGOFF_URL_PARAM( page = page )%>" >Logoff</a>

Web Application Server

620 SP 9

178

SAP Online Help

25.10.2002

Using BSP Application SYSTEM


Use
BSP application SYSTEM is a standard application for BSP application developers, which
enables you to use an adapted version of the SAP standard logon screen.

Under no circumstances whatsoever should you make changes to BSP


applications SYSTEM or SYSTEM_PRIVATE!
You can precede your own BSP application with BSP application SYSTEM, so that the logon
screen is called automatically before the application itself is started.

Integration
In addition to BSP application SYSTEM, also available are application SYSTEM_PUBLIC for
testing user-specific settings for the final URL (integration takes place using Transaction
SICF) and SYSTEM_PRIVATE as a placeholder for your own application.

Activities
1. Create your BSP application.
2. Call transaction SICF.
3. In the SICF service tree, branch to the node for your new application.
4. Double-click on the node for your application.
5. On the Service Data tab, you can determine whether you want to execute the logon using
an Internet User [page 191] or a Standard SAP User [page 189].
6. Branch to the Error Pages tab page.
7. In Logon Errors, activate Redirect to URL and enter in the field below the correct URL for
the redirect to SYSTEM, such as:
/sap/public/bsp/sap/system/login.htm?sap-url=<%=PATHTRANS%>
This URL can of course be longer, it is only a minimal URL.
Parameter sap-url uses script expression <%=PATHTRANS%> to determine that
when your application is called, the request is redirected to the specified path.
Furthermore, all parameters that you also assigned to your application are similarly
passed through.
A more complex URL could be:
/sap/public/bsp/sap/system/login.htm?sap-url=<%=PATHTRANS%>&
BspClient=000&
BspLanguage=EN&
BspTermsOfUse=/sap/bc/bsp/sap/test00/termsofuse.htm&
BspForgotPass=/sap/bc/bsp/sap/test00/forgotpass.htm&
BspSysId=X
For an explanation of this and other possible parameters, see SYSTEM_PUBLIC
[page 180].
Activate option Form Fields (Base64). You can use this to determine that the form
fields are not coded in plain text.
8. Save your data. The system sets the service node to inactive.
9. Activate your service node.

Web Application Server

620 SP 9

179

SAP Online Help

25.10.2002

SYSTEM_PUBLIC
Definition
BSP application SYSTEM_PUBLIC is a sample application for BSP application developers
who want to adapt the individual fields of their logon screen, which is switched using the
redirect to SYSTEM [page 179], user-specific to their BSP application.

Under no circumstances whatsoever should you make changes to BSP


applications SYSTEM or SYSTEM_PUBLIC!

Use
you are using SYSTEM_PUBLIC to construct the URL that you enter as the redirect URL in
Transaction SICF for your node in the service tree.

Prerequisites
1. Close all browser windows so that the browser can save no authentication information
whatsoever.
2. Before you start SYSTEM_PUBLIC, ensure that you are not logged on to PSE
management (Single Sign On).
If you are already logged on, then log off PSE management, by clicking on the
appropriate symbol on your desktop and choosing Log off.

3. In the Object Navigator (Transaction SE80) enter SYSTEM_PUBLIC as the BSP


application and choose Display.
4. Position the cursor on page default.htm of SYSTEM_PUBLIC and choose function key
F8 (Test/Execute).

Web Application Server

620 SP 9

180

SAP Online Help

25.10.2002

5. The browser logon screen is displayed, such as:

Choose Cancel.

You must not log on here, so that the browser does not store your basic
authentication.
6. You branch to a browser window with an address, such as:

7. In the URL, replace bc with public.

SYSTEM_PUBLIC is now displayed.

BSP application SYSTEM_PUBLIC runs under the general display user SAPSYS.
This has the advantage that the browser has no authentication information and that
each initial request for a private BSP application results in an authentication process.
If BSP application SYSTEM is used, it is then started.

Structure
SYSTEM_PUBLIC looks as follows:

Web Application Server

620 SP 9

181

SAP Online Help

25.10.2002

From this interface you can try the different design options for a logon screen. You can hide
and display individual fields, or assign them with default values. The aim is to construct a URL
which you can then save in SICF with the redirect URL.
Parameters on the logon screen
Parameters

Example

Meaning

BspApplication

/sap/bc/bsp/sap/test01/default.htm

Name of your BSP application.


Enter the complete URL here
(from the root node /).

BspHandlerClass

Internal class that is not usually


used.
You can overwrite this class to
make enhancements [page 185].

BspPrivacyStatement

../<public BSP-App>/<page name.htm>


See below

Page with copyright information.

BspTermsOfUse

../<public BSP-App>/<page name.htm>


See below

Page with general terms of use.

BspForgotPass

../<public BSP-App>/<page name.htm>


See below

Page with information on what


should be done if users forget
their password. Users can have a
new password generated here.

Web Application Server

620 SP 9

182

SAP Online Help

25.10.2002

BspPasswordHint

../<public BSP-App>/<page name.htm>


See below

Page with indirect information on


passwords. If a user has forgotten
his or her password, he or she
can have a hint for the correct
password sent.

BspPasswordViaEmail

../<public BSP-App>/<page name.htm>


See below

Page with information about the


option of having a password sent
by e-mail.

BspSignUpHere

../<public BSP-App>/<page name.htm>


See below

Page with the option of registering


for a specific SAP Web AS
System.
Registration always refers to a
SAP Web AS System as a whole.
As soon as authentication
information is available, users can
see all available BSP applications.

BspClient

BspClient=100
BspClientVisible=X

Client and client visibility.


The client must always be
specified; it can also be hidden on
the logon screen.
If you do not want to display the
client, then write:
BspClient=100
for example, so that client 100 is
saved as an invisible field.

To override the hard-coded client,


use bspClient=<%=SYMANDT%>
in Transaction SICF.
This is available if bspClient=100
is entered in Transaction SICF,
although the production system
should run in client 200.
BspLanguage

BspLanguage=EN
BspLanguageVisible=X

Language and language visibility


setting.
If you do not want to display the
language, then write:
BspLanguage=DE
for example, so that the language
German is saved as an invisible
field.

BspSysId

Web Application Server

BspSysIdVisible=X

620 SP 9

System ID visibility. The system


ID is the name of the SAP Web
AS System.

183

SAP Online Help

25.10.2002

BspAccessibility

BspAccessibility=X

Specify the accessibility [page


406] and visibility of a checkbox.

BspAccessibilityCheckbox
Visible

BspAccessibilityVisible=X

BspChangePassword

BspChangePasswordVisible=X

Data for changing the password.

BspUserLongNames

BspUserLongNames=

Specifies long user names.


This function is deactivated by
default.
Logon can occur using either
short or long user names and the
logon can be attempted only
once. You must therefore define
which format should be used.

BspDumpFields

BspDumpFields=

Additional information which is


listed under the SYSTEM logon
screen and which is used for
testing and debugging.

This option sets a flag in the BSP


runtime, which can be used by
BSP applications to output
additional information in the HTML
output stream, so that screen
reader programs can better
present the visual information on
the screen.
BSP extension HTMLB uses this
flag to change its rendering
behavior.

Always switch these dump fields


off before you generate your URL.

With parameters BspPrivacyStatement, BspTermsOfUse, BspForgotPass,


BspPasswordHint, BspPasswordViaEmail and BspSignUpHere, always enter the
relative or absolute path for the page that you want to jump to.
Ensure that it should be a page that is located in an active application (PUBLIC),
which can also be reached using an anonymous display user. This page must not
be located in the BSP application entered above, which uses SYSTEM.
Note that SAP does not provide the pages specified above with functionality for
creating new users or resetting a password, for example. Whilst these pages are
available in SYSTEM_PRIVATE, they are only empty shells for the type of
services that are usually provided as Internet applications. Each application must
decide which services it wants to provide behind these empty exit URLs, or if it
wants to use them at all.
You can use pushbutton execute login to display how the logon screen will appear after you
have made your modifications and to determine the correct URL for SICF.

Sample URL (broken up to make it legible) and the logon screen


/sap/public/bsp/sap/system/login.htm?sap-url=<%=PATHTRANS%>
BspHandlerClass=&
BspPrivacyStatement=&

Web Application Server

620 SP 9

184

SAP Online Help

25.10.2002

BspTermsOfUse=../system_public/termsofuse.htm&
BspForgotPass=../system_public/forgotpassword.htm&
BspPasswordHint=&
BspPasswordViaEmail=../system_public/passwordviaemail.htm&
BspSignUpHere=&
BspClient=000&
BspClientVisible=X&
BspLanguage=EN&
BspLanguageVisible=X&
BspSysIdVisible=X

Enhancements
BSP application SYSTEM [page 179] is divided into two large areas, so that user-specific
adjustments or enhancements are easier to make:

Own BSP application

Application Class [page 207] CL_BSP_LOGIN_APPLICATION

Own BSP Application


The BSP application contains the layout for the application.

Application Class CL_BSP_LOGIN_APPLICATION


The application class contains the business logic for an application.
The BSP application class is configured once for the whole BSP application. With this
configuration, a reference to the application class is available for the duration of the stateful
session within all pages, using parameter APPLICATION.

To simplify enhancements, both language-dependent text strings and all data required for the
BSP application are written to the application class. The BSP application itself contains

Web Application Server

620 SP 9

185

SAP Online Help

25.10.2002

references to this information only using the syntax.


application->
Interface IF_BSP_APPLICATION_EVENTS [page 245] was implemented to make it even
easier to integrate the application class in the BSP application. This means that the
application class has control both before and after processing and as a result it can integrate
specific logon logic without large coding changes to the pages being necessary.

Possible Adjustments
Under no circumstances whatsoever should you make changes to BSP
applications SYSTEM or its application class CL_BSP_LOGIN_APPLICATION!
For the enhancements, note the following points:

Layout changes

Smaller changes to the logic

Enhance the SYSTEM application class.

If you want to use one of the exit URLs, such as page TermsOfUse.htm, then additional
pages are required as destinations. These pages must be publicly accessible. A possible
implementation would be analogous to the method with layout changes. You could then write
the pages that are additionally required directly in your new SYSTEM application.

Layout changes
It is recommended that you copy BSP application SYSTEM to a new BSP application.

If the copy process terminates with the error message that the name SYSTEM is
reserved, proceed as described in Note 531028.
Continue to use the same application class, CL_BSP_LOGIN_APPLICATION, since it
contains the whole logon logic.
Use your new BSP application to change the layout according to your requirements. For
example, you could add your company logo to every page.
Note the following different settings that are required depending on the release status:
Area

SAP Web AS 6.10

SAP Web AS 6.20 and above

ICF service tree

First, in Transaction SICF (see


also Creating an ICF service
[page 140]) you must create the
actual entry for your copies
SYSTEM application in the ICF
service tree, in path
sap/bc/bsp/sap/<copied
SYSTEM>.

The entry for your copied


SYSTEM application is
automatically made in the ICF
service tree in Transaction
SICF as part of the copy
process.

MIME objects

Web Application Server

Then make a new alias entry in


the public path, so that your
new SYSTEM application can be
accessed publicly (using the
SAPSYS user). The exact path for
this in the ICF service tree is
sap/public/bsp/sap/<copie
d SYSTEM>.

You only need to make a new


alias entry in the public path
of the ICF service tree, so that
your new SYSTEM application
can be accessed publicly
(using the SAPSYS user). The
exact path for this in the ICF
service tree is
sap/public/bsp/sap/<co
pied SYSTEM>.

As part of the copy process, only


the pages are copied, not the

During the copy process, you


can copy MIME objects as well

620 SP 9

186

SAP Online Help

25.10.2002
MIME objects. This is why you
must transfer the MIME objects to
your new SYSTEM application after
you copy the SYSTEM. Proceed as
follows:

as pages. To do this, in the


copy dialog box for the subobjects to be copied, select
the options for the MIME
objects as well as the pages.

1. In the MIME repository below


the SAP tree, branch to the
folder for the SYSTEM
application.
2. Select here all of the MIME
objects for the SYSTEM
application.
3. Hold down the Control key
and then drag the objects you
selected to your new SYSTEM
application.
In doing so, ensure that
you objects are copied
that is, duplicated (by
holding down the Control
key) and not merely
moved from the SYSTEM
to your copied application.
Pages that cannot be
activated

There are three pages in your


copied SYSTEM application that
cannot be activated.
These pages do not have any
additional influence on the
functionality of the remaining
SYSTEM application. We therefore
recommend that you manually
delete the following three pages
from your copy of the SYSTEM
application:

hidden_buffered.htm

session_buffered_frame.htm

session_single_frame.htm

No changes required.

Once you have copied the SYSTEM application, use the name of your copied SYSTEM
application for the redirect with the error pages and not the SYSTEM application itself.

Small changes to the logic


The special class CL_BSP_LOGIN_HANDLER is available for this. Implement your own class,
which is derived from CL_BSP_LOGIN_HANDLER and, if necessary, overwrite all methods
that you require for your application in a modified form. Then configure SYSTEM so that it uses
your new handler class (BspHandlerClass). If the new application class is started, the
specified handler class is also created and the handler class is also called.
Since all application-relevant information is available as public attributed in the application
class, the handler class can overdefine specific information. Typical application areas for the
handler classes are:

Replace language-related strings application->TXT_*(variables)

Web Application Server

620 SP 9

187

SAP Online Help

25.10.2002

Complete configuration options: application->BSP_*(variables)


This particularly useful if you need a longer configuration URL than SICF supports.
In this case, configure a handler class in which all required exit URLS are set, such
as BspTermsOfUse.

Add additional application logic.


An example is setting and resetting cookies which are required for the duration of the
application. Further examples are executing additional authorization checks and
writing logging information.

Enhance the SYSTEM application class.


This is not usually recommended, but may be necessary in extreme cases. Implement your
own application class which is derived from CL_BSP_LOGIN_APPLICATION and overwrite
the required methods. Then copy SYSTEM to your own application and configure the new
application class.

Logging off BSP Applications


Use
A logging off scenario is vitally important for stateful [page 381] BSP applications, since the
BSP runtime is not able to carry out session management itself. The BSP runtime cannot
determine when an application has ended.
Without a logging off scenario, numerous SAP Web AS sessions could remain open and
therefore use up memory capacity and similar system resources, even if they are not actually
required. The open and inactive sessions remain to exist until they are closed by default by
the Internet Communication Manager [page 22]. This then overloads the application servers.
The cure for this problem is a simple logging off scenario that is created as a protective frame
for the session around the respective BSP application. If you implement the logoff scenario,
the SAP Web AS session is ended when a user calls up a different URL in the browser, for
example, or closes the browser. The session is ended using the automatic send command
sessioncmd=close to the SAP Web AS in a new frame, which is then automatically closed
afterwards.

Integration
The pages for the logoff are components of the BSP application SYSTEM.

Prerequisites

You are using an SAP Web AS 6.20 system and have implemented at least Support
Package 4.

Your BSP application is running in stateful mode.

Functions
BSP application SYSTEM contains the following sample pages for logging off:

session_single_frame.htm
The BSP application is processed in the browser in its own browser frame. If you
close the browser or call a different URL, this closes the session that is running in the
background.

Web Application Server

620 SP 9

188

SAP Online Help

25.10.2002

session_buffered_frame.htm
The BSP application in the browser consists of two different browser frames, where
the system always switches between the two frames, which minimizes setting up the
screen repeatedly. If you close the browser or call a different URL, this closes the
session that is running in the background.

Activities
1. Copy one of the two logoff pages (either session_single_frame.htm or
session_buffered_frame.htm) to your own BSP application, such as in the name
session.htm.
2. Change the line after the page directive so that target_uri points to the actual start
page of your BSP application, which should be executed in the browser frame:
<%
DATA: target_uri TYPE STRING VALUE 'default.htm'.
%>
3. Now branch to the Properties tab in your BSP application and specify the logoff page (in
this example it is session.htm) as the Initial BSP for your BSP application.
4. If necessary, replace the default simple Loading layout with a more complex layout that
is suitable to your application.
5. Save and activate your page and the BSP application.

Using a Default User for BSP Applications


Motivation
The first HTTP Request of a client (usually the Web browser) to a BSP application requires
the user to log on via the browser with user name and password. This presupposes that the
user is known to the system and is entered in transaction SU01 (cf. Using Internet Users in
BSP Applications [page 191]).
Most Web applications on the other hand, require free access with no browser logon window,
whereby the public sections (catalog, overview and so on) should be directly accessible to
any number of users. These anonymous requests should be executed with a limited
authorization that can be maintained in the system.

Anonymous Default User


For this purpose, it is possible to store a default user for a BSP application in the system. The
BSP application is then executed with this users authorizations.
The section Creating a Default User [page 190] describes how to create a default user with
transaction SICF.
See also:
Logging On To SAP Web Application Server [page 113]
Anonymous Logon Data [page 143]

Web Application Server

620 SP 9

189

SAP Online Help

25.10.2002

Creating a Default User


Use
Use transaction SICF to create and maintain virtual hosts and services. The logon data to the
SAP Web Application Server in particular is stored with the service. For details, refer to
Logging On To SAP Web Application Server [page 113].
If a request is sent to the SAP Web Application Server, there are two options:
1. If all of the user data is stored with the service, this data is used by the system for logon
to the SAP Web Application Server without any user logon dialog. We refer to this as an
anonymous logon with a default user.
2. If either the user name or the password is not stored, the browser sends a dialog box the
first time the user submits a request, where the user must enter user name and
password. The browser then generates a cookie in accordance with the Basic
Authentication Standard that remains valid for the duration of the browser session. If the
browser is restarted, the system queries the user data once again. Basic Authentication
does not query client or language data. This information is stored with the service. If no
language is stored there, the logon language is automatically taken. The same applies to
the client.
See Also: Anonymous Logon Data [page 143]

Procedure
If the BSP application should be accessible without logging on, you can store a default user
for the application. You do so by creating a new ICF Service in transaction SICF with the
name of the BSP application under the relevant handler for BSP applications (for SAP
applications /sap/bc/bsp/sap). For details on how to create a new ICF Service, refer to
Creating an ICF Service [page 140].
You can assign this service user information such as name, password, and default language.
All HTTP requests to the BSP application are then automatically executed using the
authorizations of the user stored. The user stored should be of the type Standard SAP User,
which has the required attributes:

The password is retained

Multiple logons are possible

A dynamic user switch to an Internet user is possible

Web Application Server

620 SP 9

190

SAP Online Help

25.10.2002

Please note when setting up a default user for an application, this user is only
used for URLs that reference this application. If the HTML pages receive
references to other applications or images in other paths such as style sheets or
graphics in the PUBLIC directory in the MIME Repository, these paths must also
be provided with default users. Otherwise, when it attempts to request the style
sheets or images, the browser will be refused and the logon dialog box displayed.

Example
You created a BSP application entitled bookstore that contains the page default.htm as the
initial BSP. If you then call the application in the browser with the URL
http://<host>:<port>/sap/bc/bsp/<namespace>/bookstore/default.htm
you will have to log on to the SAP System with the Basic Authentication in the dialog box that
appears.
To avoid this, carry out the following steps:
1. In SICF, create a service bookstore under the ICF Service sap/bc/bsp/<namespace>
as described in Creating an ICF Service [page 140].
2. Under Service Attributes, enter a user known to the system (that has the required
authorizations) and the password. You can also specify a language and a client here.
The logon dialog will now be omitted when you call the URL.

Using an Internet User for BSP Applications


Motivation
Typical Internet applications need to be able to support a large number of registered online
users. As a rule, it should be possible that new users can log on and register themselves or
that certain users are authorized to create new users.
The data of the logged on user must be stored and must be able to be maintained. Users
Web Application Server

620 SP 9

191

SAP Online Help

25.10.2002

need to have authorizations where relevant different authorizations that can be


maintained based on the SAP authorization concept.

Previous Internet Users with Transaction SU05


Up to now Internet users for Internet Application Components, which presupposed the
existence of an additional account, were created and maintained in transaction SU05. Now
Internet users are created and maintained in the general user maintenance transaction
(SU01).

Internet users that were created using transaction SU05 should no longer be
used.

Creating New Internet Users with Transaction SU01


Internet users are SAP users that are created and managed just like ordinary users in SU01.
Unlike other users however, they are created with an alias. Only personal data (password,
address, e-mail and so on) is assigned individually. Technical data (authorizations or profile)
is inherited from a reference user.
Reference User
Reference users are used for authorization assignment to equip Internet users with identical
authorizations. You can create one or more reference users, depending on what
authorizations you want to assign your users. You create one reference user per target group
and assign this user authorizations for all of the Internet transactions allowed for the target
group.
You can find out how to set up the logon to the SAP System for this user under Anonymous
Logon Data [page 143] and Basic Authentication [page 146].
You can find a general description of using the concept in the section Sample BSP
Application for Using Internet Users [page 192]. This is followed by information on Logging On
as an Internet User [page 193] and Creating New Users [page 194].

Sample BSP Application for Using Internet Users


A simple application containing a publicly accessible initial page, a page for logging on and
creating new users, and an area that is only accessible to logged on users should serve as an
example.

INT_GUEST
In order for the publicly accessible initial page to be displayed directly in the browser without
logon, you create a default user INT_GUEST in the system and assign it to the application
using transaction SICF (see also Creating an ICF Services [page 140]).

This user must be of the type Service User. It has only limited authorizations in
the system and has no access to secure areas of the application.

INT_ADMIN
A second user, INT_ADMIN, serves as an administration user that has authorization to
create new users. It is created with the alias administrator (see also Internal Aliases
[page 148], External Aliases [page 151]).

Web Application Server

620 SP 9

192

SAP Online Help

25.10.2002

INT_USER
A third user, INT_USER, serves as a reference user for the new Internet users created by the
administrator. This user has the authorizations it requires to display and use the complete
application.
For more information, refer to:

Logging On as an Internet User [page 193]

Creating New Users [page 194]

Logging On as an Internet User


The logon page login.htm is openly accessible under the account of the INT_GUEST. The
page contains a user name and password query. In OnInputProcessing of the page, the
function module SUSR_INTERNET_USERSWITCH is called, which switches to the pertinent
user. All subsequent steps take place on the account of the logged on user.

Page Attributes
Attribute Name

Auto

err_msg

Typing Type

Reference Type

Description

TYPE

STRING

Error message

Layout
<%@ page language="abap" %>
<html>
<body>
<h3> Login </h3>
<%= err_msg %>
<form>
<table>
<tr>
<td> User </td>
<td> <input type=text name="username"> </td>
<td></td>
</tr>
<tr>
<td> Password </td>
<td> <input type=password name="password"> </td>
<td> <input type=submit name="OnInputProcessing" value="login"> </td>
</tr>
</table>
</form>
</body>
</html>

Event Handler OnInputProcessing


data: usr type bapialias,
pwd type bapipwd.

Web Application Server

620 SP 9

193

SAP Online Help

25.10.2002

data: return type table of bapiret2,


wa_return type bapiret2,
bname type USUSERNAME.
usr = request->get_form_field( 'username' ).
pwd = request->get_form_field( 'password' ).
CALL FUNCTION 'SUSR_INTERNET_USERSWITCH'
EXPORTING
ALIAS
= usr
PASSWORD
= pwd
IMPORTING
BNAME_AFTER_SWITCH
= bname
TABLES
RETURN
= return.
.
loop at return into wa_return.
err_msg = wa_return-message.
endloop.
if bname is not initial.
navigation->goto_page( 'userdata.htm' ).
endif.
After the logon is authenticated, the example again displays the initial page, this time called
with the logged on users account. If the logon is not authenticated, the page is displayed
again where the error message from the return structure of the call can be displayed.

Creating New Users


You create new users with the page create.htm. A check performed at page initialization
ensures that this page can only be called by an administrator.

The authorization check performed at function call already ensures that no


unauthorized user can create a new Internet User, but it makes sense that
unauthorized users should not even be able to display the Create page.
You enter the required user data for a new user on this page.
The figure below displays the screen on which you create a new Internet user:

Web Application Server

620 SP 9

194

SAP Online Help

25.10.2002

In OnInputProcessing of the page, the function module SUSR_USER_INTERNET_CREATE is


called. This function module creates the new user. The INT_USER serves as a reference user
here. The new Internet user has the same authorizations as the reference user. The user
name queried is used as a alias, the function module generates a SU01 user name.

Page Attributes
Attribute Name

Auto

err_msg

Typing Type

Reference Type

Description

TYPE

STRING

Error message

Layout
<%@ page language="abap" %>
<html>
<body>
<h3> Create new user </h3>
<form>
<table>
<tr>
<td> User Name </td>
<td> <input type=text name="username"> </td>
</tr>
<tr>
<td> Password </td>
<td> <input type=password name="pwd1"> </td>
</tr>
<tr>
<td> verify Pwd</td>
<td> <input type=password name="pwd2"> </td>
</tr>
<tr>
<td> First Name </td>
<td> <input type=test name="firstname"> </td>

Web Application Server

620 SP 9

195

SAP Online Help

25.10.2002

</tr>
<tr>
<td> Last Name </td>
<td> <input type=test name="lastname"> </td>
</tr>
<tr>
<td> Email </td>
<td> <input type=test name="email"> </td>
</tr>
<tr>
<td></td>
<td> <input type=submit name="OnInputProcessing(create)" value="logon">
<input type=submit name="OnInputProcessing(reset)" value="reset"> </td>
</tr>
</table>
</form>
</body>
</html>

Event Handler OnInputProcessing


data: newuser type bapialias,
pwd1 type bapipwd,
pwd2 type bapipwd,
refuser type bapibname,
address type bapiaddr3,
newuserid type bapibname.
data: return type table of bapiret2,
wa_return type bapiret2.
newuser = request->get_form_field( 'newuser' ).
pwd1 = request->get_form_field( 'pwd1' ).
pwd2 = request->get_form_field( 'pwd2' ).
address-firstname = request->get_form_field( 'firstname' ).
address-lastname = request->get_form_field( 'lastname' ).address-e_mail = request>get_form_field( 'email' ).
refuser = 'INT_USER'.
CALL FUNCTION 'SUSR_USER_INTERNET_CREATE'
EXPORTING
ALIAS
= newuser
PASSWORD
= pwd1
PASSWORD2
= pwd2
ADDRESS
= address
REF_USER
= refuser
IMPORTING
GENERATED_BNAME
= newuserid
TABLES
RETURN
= return
.
loop at return into wa_return.
concatenate err_msg ' <br> ' wa_return-message into err_msg.
endloop.
You can of course use multiple reference users for different purposes. This enables you to
create scenarios where selected Internet users have authorization to create other Internet
users.

Web Application Server

620 SP 9

196

SAP Online Help

25.10.2002

It is also conceivable that you would have applications where new users may create their own
users and register themselves. In this case, the guest user, used to display the public pages,
would have to have authorization to create Internet users.

Programming Model
The following documentation describes the BSP programming model:
BSP Applications [page 197]
BSPs [page 210]
BSP Directives [page 221]
Central Classes and Interfaces [page 225]
Important Global Objects [page 278]
BSP Extensions [page 284]
Model View Controller (MVC) [page 331]
Java Call [page 377]
Stateful and Stateless [page 381]
Control Flow and Lifetime [page 391]
Caching [page 403]
Page Design [page 405]
Accessibility [page 406]

For SAP Web AS 6.20, the BSP programming model was enhanced with the
MVC design pattern as well as the paradigm of the BSP extensions.

What is a BSP Application?


Overview
A Business Server Page (BSP) application is a complete functional application as is a classic
SAP R/3 transaction. Instead of being displayed using SAP GUI, these applications are
displayed in a Web browser or a mobile device browser, such as a WAP cell phone (see also
Mobile Enhancements of the SAP Web Application Server [page 449]). HTTP or HTTPS is
used to access the application across the network, which means that standard products like
firewalls and proxy servers can be used.
The Business Server Pages programming model is similar to the Server Page Technology.
This technology has been widely used in the field of Web development. The focus of the BSP
programming model are points that ensure optimum structure in interfaces and business
logic.
For more information about BSP applications, see:

The components of a BSP application and how they interact, see Structure of a BSP
Application [page 198]

Web Application Server

620 SP 9

197

SAP Online Help

25.10.2002

How to call an existing BSP application from a Web browser, see Accessing a BSP
Application [page 201]

How to start and end a BSP application, see Starting and Ending a BSP Application [page
204]

How a BSP application is processed, see Processing a BSP Application [page 206]

How to create a BSP application, see Creating a BSP Application [page 206]

The URL parameters you can use to access the BSP runtime environment and BSP
applications, see System-Specific URL Parameters [page 204]

The concept of an application class for encapsulating the business logic of a BSP
application, see Application Class of a BSP Application [page 207]

Tutorials
For information about how to create BSP applications, see the following tutorials:

First Steps with Business Server Pages [External documentation]

A Simple BSP Application [External documentation]

Online Bookshop [External documentation]

Further Developing the Online Bookshop [External documentation]

Structure of a BSP Application


A Business Server Page (BSP) application is an independent development project that is
created and edited in the SAP development environment (transaction SE80). External design
tools, such as Adobe GoLive, Dreamweaver, or Microsoft FrontPage 2000 can be used to
design the BSP application, as well as BSP extensions [page 284].

Web Application Server

620 SP 9

198

SAP Online Help

25.10.2002

Analog to a classic transaction, a BSP application consists of a user interface and business
logic that is assigned to a logical unit, in this case the BSP application.
The user interface of a BSP applications includes:

Static Web sites

Dynamically generated Web sites, which are BSPs or templates that contain server-side
scripting that is executed dynamically at runtime to generate a static Web site BSPs can
either be pages with flow logic or views.
There can also be controllers if the MVC [page 331] design pattern is used

Various MIME objects, such as pictures, icons, sound files, style sheets, and so on, that
are parts of a typical Web application

All of these objects are integrated in the Change and Transport Organizer as parts of the BSP
application and are handled as a logical unit. This allows all objects that are part of a BSP
application to be fully and consistently transported between all the systems in an SAP system
landscape.
The business logic can be accessed from the BSP application using the typical methods,
such as BAPIs, function modules, or class libraries. In addition, the BSP programming model
provides a structuring tool, the BSP-Application class [page 608] , that can be used to
encapsulate the business logic functionality in the BSP application.

Web Application Server

620 SP 9

199

SAP Online Help

25.10.2002

BSP Application

Seite mit Ablauflogik


Seite mit Ablauflogik
Page with Flow Logic
Layout
Layout
Layout
Eventhandler
Eventhandler
Event Handler
Auto-/Seitenattribute
Auto-/Seitenattribute

Navigation Structure

Application Class

Auto-/Page Attributes

Controller
Controller Class

View
View
View

URL

Layout
Layout
Layout
Seitenattribute
Seitenattribute
Page Attribute

Business
Server Page
(BSP)

Seitenfragment
Page
Fragment
Seitenfragment

MIME-Objekt
MIME-Objekt
MIME Object

Theme

Layout

A BSP application consists of the following components:

Controllers
Controllers contain business logic and application data. Controllers assess the
data of an incoming request based on a model and then select a suitable view for
rendering the reponse to the user, see also Model View Controller (MVC) [page
331].

Business Server Pages (BSPs)


BSPs are the Web sites that are displayed in the browser when the application is in
use. BSPs can contain static HTML code and dynamic scripting code (ABAP or
JavaScript). The scripting code is interpreted on the server. The exact structure of a
BSP is described in Building an BSP [page 210].
A page can have the following versions:

Page with flow logic


These are simple pages with event handlers, but without much application logic
or visualization elements. It is possible to build a BSP application exclusively out
of pages with flow logic and event handlers.

View
Views are used to visualize data, see also Model View Controller (MVC) [page
331].

Page fragment
These are created in the same way as normal BSPs, but are then marked as
page fragments. Other BSPs can also include these fragments using the
include directive (see Include Directive [page 224]).

Navigation structure
The navigation structure determines which navigation request is used to direct the
navigation process from which page to which subsequent page.

Application class

Web Application Server

620 SP 9

200

SAP Online Help

25.10.2002

The business logic of a BSP application is encapsulated in an application class. The


application class is implemented using a global ABAP class. This global class
implements access to business data, for example, via BAPI calls. Every page of a
BSP application can directly reference the components of this class (attributes,
methods, and so on) using the predefined Object application [page 279].
You can also assign several BSP applications to an application class.
For more information, see Applications Class of a BSP Application [page 207].

MIME objects
In the SAP system, all MIMEs, such as graphics, style sheets (used to define
formatting properties of individual HTML tags), audio files, video files, and so on, are
stored and administered in a central repository, the MIME repository.
For every new BSP application, a directory of the same name is created in the MIME
repository. This directory is used as a storage location for all application-specific
MIMEs.

Theme
A theme is a container for MIME objects. These MIME objects can be used to
modify the appearance of one or more BSP applications after the application has
been created. You can replace every MIME object in your application with
another object from the file system.
A theme is created as an independent development object in the Web Application
Builder. A theme can be assigned to BSP applications in order to redefine style
sheets and MIMEs in the pages of a BSP application after they have been
created. The theme concept is a powerful tool for easily changing the layout of
your pages in accordance with your needs, without the need for modifying the
layout source code.
See also: Tailoring Layouts to BSP Applications [External documentation]

See also:
Accessing a BSP Application [page 201]
Starting and Ending a BSP Application [page 204]
Building a BSP [page 210]

Accessing a BSP Application


As we have already explained, you access a BSP application using the HTTP or HTTPS
(Secure HTTP) protocol. The BSP runtime environment uses the HTTP framework of the SAP
Web Application Server (compare Interaction Model [page 108]). In the Internet
Communication Framework (ICF), for a BSP application to function smoothly you need a
node, that is, a service in the service tree (see also Creating a BSP Application [page 206]).

Ensure that after a SAP Web AS has been installed, that all services are inactive
and that they must be activated accordingly. For additional information about
activating services, see Activating and Deactivating an ICF Service [page 147]
and Note 517484.
As part of automatically creating the corresponding node in the service tree, the
node is also activated only in the case of BSP applications that are newly created
for SAP Web AS 6.20.

Web Application Server

620 SP 9

201

SAP Online Help

25.10.2002

A BSP application is addressed and executed through HTTP using a Uniform Resource
Locator (URL). The URL of a BSP application has the following structure (default
configuration):
<Prot>://<Host>.<domain>.<extension>:<Port>/sap/bc/bsp/<namespace>/<application name>
The protocol Prot is http or https (if configured). Host is the name of the application
server that should execute the application. Domain and the Extension comprises several
hosts under a common name, although they can either be made up of an individual host or a
network. The Port number can be omitted if the default port 80 (http) or 443 (https) is used.
For SAP Web Application Server, the default port number is 1080 (HTTP) or 1443 (HTTPS).
The namespace is the namespace ID of the BSP application. SAP applications are delivered
in the sap namespace. If you created your BSP application in its own namespace, you must
use this namespace in the URL. The application name is the name of the BSP application as
defined in the development environment.
Here is an example of a URL for BSP test application IT00:
http://myServer.sap-ag.de:1080/sap/bc/bsp/sap/it00

The full name of the server is specified, including the network domain (here:
sap-ag.de). Otherwise, the BSP runtime environment returns an error. The full
domain must be specified as otherwise there may be problems with HTTP
cookies (such as Single Sign On).
Windows 2000 may cause problems with the DNS configuration. In this case, see
DNS Configuration for BSP Applications in Windows 2000 [page 525]

Web Application Server

620 SP 9

202

SAP Online Help

25.10.2002

When this URL is started in the Web browser, the BSP application is started and the initial
page is displayed (by default this is default.htm).
To determine the URL of a BSP or BSP application within the SAP development environment,
look on the Properties tab at the right side of the SAP GUI screen.

Example of page default.htm of BSP application IT00:

See also:
Starting and Ending a BSP Application [page 204]
Cache Key [page 37]

Web Application Server

620 SP 9

203

SAP Online Help

25.10.2002

Starting and Ending a BSP Application


Use
URL parameters can be used to inform the BSP runtime environment to start or end a BSP
application (corresponds to the OK code /n in SAP GUI) To do this, the Query String
[External documentation] parameter sap-sessioncmd is added to the URL and the HTTP
request is sent to the server. Compare System-Specific URL Parameters [page 204]

To be compatible with SAP Internet Transaction Server (ITS) and the Workplace,
you can also use ~SAPSessionCmd.

Procedure
The following commands are supported:

open: Restarts a BSP application that is running. The application is started if it is not
running already. To be compatible with the Internet Transaction Server (ITS), the
following abbreviated format is supported, whereby the page name is replaced by an
exclamation mark (!):
http://myServer.sap-ag.de:1080/sap/bc/bsp/sap/it00/!

This is the same as the following URL:


http://myServer.sap-ag.de:1080/sap/bc/bsp/sap/it00?sap-sessioncmd=open

close: Ends a running BSP application and either tells the system to display a blank page
or go to a specific Web site (exit URL). The exit URL is specified using an additional URL
parameter, sap-exiturl, and must contain a full HTTP URL.

To be compatible with SAP Internet Transaction Server (ITS) and the Workplace,
you can also use ~SAPSessionCmd.

Example

Restart of BSP test application IT00:


http://myServer.sap-ag.de:1080/sap/bc/bsp/sap/it00?sapsessioncmd=open
or
http://myServer.sap-ag.de:1080/sap/bc/bsp/sap/it00/!

Ending the application externally:


http://myServer.sap-ag.de:1080/sap/bc/bsp/sap/it00?sapsessioncmd=close&sap-exiturl=http://www.sap.com

For a list of all system-specific URL parameters that can be used in the BSP application
environment, see System-Specific URL Parameters. [page 204]

System-Specific URL Parameters


To control the BSP runtime environment and the BSP application, you can use the following
URL query string parameters in a request URL.
URL Parameter

Value

Web Application Server

Description

620 SP 9

204

SAP Online Help

sap-sessioncmd

25.10.2002

open:

Restarts the BSP application named in the URL

close:

Ends the BSP application named in the URL and sends the
browser, if specified, to the Web site defined by sap-exiturl.
If you want the user to be able to end the application, this option
should be available in a BSP application as part of the user
interface (as a pushbutton or hyperlink).

sap-exiturl

Specifies the URL to which the browser is directed when the


BSP application ends (for example, http://www.sap.com)

sap-theme

Overrides the theme for a BSP application to use other MIME


objects, such as pictures and Stylesheets [page 426] for
visualization.

sap-themeRoot

Used to handle paths to other locations from where stylesheets


are taken.
See also:
Changing Stylesheets for HTMLB and XHTMLB [page 427]

This parameter is available from SAP Web AS 6.20 Support


Package 7.
sap-client

Specifies the client for a logon to the SAP Web Application


Server; can be used in the URL or in HTML forms to override
the default client.

sap-user

Specifies the user for a logon to the SAP Web Application


Server; can be used in the URL or in HTML for forms.

sap-password

Specifies the password for logon; can be used in HTML forms.

Do not enter this directly in the URL as Web browser URLs are
stored in a History list and the password would be visible in plain
text, even after the browser is closed.
sap-language

Specifies the language (ISO language ID, such as en or de)


for a logon to the SAP Web Application Server; can be used in
the URL or in HTML forms to override the default logon
language.

The parameter names are not case sensitive, nor are the parameter values (exception: sapexiturl, if it is pointed to a case-sensitive server). You can combine several parameters in
one URL.

Here is an example of how to restart a BSP application in client 800 with logon
language English.
http://myServer.sap.com:1080/bc/bsp/sap/it00?sapsessioncmd=open&sap-language=en&sap-client=800

Web Application Server

620 SP 9

205

SAP Online Help

25.10.2002

Processing a BSP Application


Uses
When a BSP application is being processed, the individual BSPs and their components are
run, and the corresponding processing steps are executed according to the code.

Process
If an HTTP request is sent to a BSP, that is, if a page (in stateless case: for the first time) is
called, the page in instantiated in OnCreate. Next, OnRequest is called.
The handler is then run that is most appropriate for the request, that is, OnInitialization for
URL input, OnInputProcessing for HTML input, or another individual event handler if controls
are used.
If it hasnt already, OnInitialization is run, so that the initialization phase data is assessed.
Data in the SAP system, such as table contents or BAPIs, can be accessed in this phase.
Then, the layout part (the hidden part of the event handler OnLayout) is processed, which
determines the design and presentation logic of a page. This code consist of static parts (for
example, HTML) and scripting code. To ensure clean programming, no business logic or data
retrieval is carried out in the layout part. The manipulation part becomes important if the
HTTP data stream should be modified later. The manipulation code should likewise contain
no business logic or statements for data retrieval functionality. If there are no subsequent
changes, the manipulation part is not required.
On the basis of all this data, the first page is built and sent to the user.
Next comes the user interaction phase, in which the user inputs data. The user input is sent
back to the BSP. This input triggers an additional HTTP request.
You can specify for every page whether stateful or stateless mode is required. This is done in
the input processing part. For example, incorrect input can be checked, data can be read from
the database, and the succeeding page can be determined.
The subsequent page for the navigation request is determined in the navigation part of the
application. If no succeeding page is set, the first page is reprocessed.
Then, processing of the initialization part continues.
For more information, see Control Flow of BSPs [page 391]

Creating a BSP Application


You create your Web application in the form of a BSP application.
For information about creating BSP applications, see the various tutorials (Creating Web
Applications with BSPs [External documentation]) and the documentation on Web Application
Builder, specifically the sections under Basic Functions [External documentation].

Extending Security Aspects with BSP Applications


So that a BSP application can function correctly, there must be a node that corresponds to
each BSP application in the service tree (Transaction SICF) of the Internet Communication
Framework (ICF).
From SAP Web AS 6.20, when you create a BSP application in the Web Application Builder,
this type of node is created and activated in the appropriate part of the ICF service tree (see
also Creating an ICF Service [page 140]). If necessary, you can add permissions for this node
(see also Service Options [page 144]).

Web Application Server

620 SP 9

206

SAP Online Help

25.10.2002

For BSP applications that were created before SAP Web AS 6.20 and which therefore do not
have any nodes in the ICF service tree, this node is generated automatically by the system as
soon as you branch to the corresponding BSP application in change mode.

There may be conflict with old BSP applications with names that are longer than
15 characters. Before SAP Web AS 6.20 you could create BSP applications
whose names could exceed the length of the service name in Transaction SICF.
In this case, we recommend that you copy all of the old BSP application to a new
BSP application with a shorter name, so that the node is automatically created.

Application Class of a BSP Application


Overview
A BSP application can include a multitude of different development objects. One of these
objects is the application class of the BSP application.
The application class is a regular ABAP Objects class. As such, the application class can
include any methods, attributes, and events the developers wants.
The application class is usually used to store data and make it available across BSP pages.
This data is stored as attributes. In addition, the application class encapsulates BSP
application logic in methods. This allows several BSP applications to use the same
application class and provide one business application that contains different interfaces, such
as for various devices, without having to replicate the business or application logic.
This also means the global Object application [page 279] can be used in the BSP application
to access the attributes and methods of the application class.
You do not have to use an application class in your BSP application. It is an optional way for
you to structure your BSP application.
You use the Web Application Builder in transaction SE80 to assign an application class to a
BSP application.

Web Application Server

620 SP 9

207

SAP Online Help

25.10.2002

A simple example of where an application class could be useful would be a class


for controlling dialog logic and maintaining data consistency in a BSP application
for shopping. This application class would include a shopping basket (internal
table or other object) as an attribute. There would also be methods for changing
and processing the shopping basket, such as to add, change, or delete articles.
Methods for determining prices, creating offers, and posting orders would also be
helpful.
For an example of the use of an application class, see Extending the Online
Bookshop [External documentation].
In many cases, the application class is only used to encapsulate existing
application functions, such as from SAP Customer Relationship Management
(SAP CRM), and then access the function through BAPI interfaces. Using an
application class to encapsulate the functions ensures that the BSP application
functions are stored in a central location (in the application class) and that both
implementation and distribution are transparent (local method call but remote
BAPI call internally). If a customer or developer wants to change or adapt a BSP
application or use the application for an additional device, they have the full
functions of the original BSP application available in the interface of the
application class.

Runtime Behavior
Any ABAP Objects class can potentially be used as an application class of a BSP application.
However, the BSP runtime environment must treat the class as a singleton, that is, a class for
which there is only one instance per session.
The lifetime of an application class depends on the state model of the BSP application. A BSP
application can be stateful or stateless.

Stateful BSP Application


In Stateful BSP Applications [page 381] the only instance of the application class, the
application object, is generated at the first request sent to the BSP application. The object is
then available for the entire lifetime of the session. The end lifetime of the application object
ends when the session ends.
In stateful mode, the application class provides local buffering for data sets that are difficult to
determine.

Stateless BSP Application


In Stateless BSP Applications [page 383], the application context (roll area) is only available
for the lifetime of a single request and is released at the end of the request. When the
application context is released, all data and objects held by the session on the application
server are also released. This includes the application object.
This means the lifetime of the application object starts when the request is received and ends
when a response is sent. The application objects is not available across several pages. Each
page and each request interacts with a different instance of the application class.
In stateless mode, the application object cannot hold data across requests. For stateless
applications, application classes are usually used to store the business logic in methods, but
do not buffer data.

Accessing the Application Object


To access the application object, you use a typed object reference that is stored as the
parameter application [page 279] in all event handlers of a BSP. Of course, you must ensure,
however, that the parameter only exists if an application class is defined for a BSP
application.

Web Application Server

620 SP 9

208

SAP Online Help

25.10.2002

Requirements for an Application Class


The only requirement for an application is that the constructor is parameter-less. If not, the
application class cannot be generically instantiated by the BSP runtime environment.
Otherwise there are no other restrictions. You do need to ensure that the internal
implementation of methods is chosen correctly, depending on the state mode where the class
is implemented. For stateless applications, for example, it would be useless to implement
expensive data gathering routines as these would be lost after every request. Instead, just get
the exact data you need at that time. In stateful applications, you can implement an
initialization phase where you get a large amount of data at one time, which can improve
performance.

Application Events: The IF_BSP_APPLICATION_EVENTS


Interface
In stateless BSP applications, an application often needs centralized control at certain times
in the lifetime of the application. The BSP model provides this function for the application
class in the predefined interface IF_BSP_APPLICATION_EVENTS.
When an application class implements the optional interface
IF_BSP_APPLICATION_EVENTS, the BSP runtime environment calls the interface methods
at the relevant times. The following describes the methods and times:
IF_BSP_APPLICATION_EVENTS~ON_STAR
T

This method is called by the BSP runtime environment


when the corresponding BSP application is first started at
the start of the BSP session. This applies to both
stateless and stateful applications.
Typically, this time point is used to carry out authorization
checks that apply to the entire application, or for
preliminary data retrieval (in stateful applications).

IF_BSP_APPLICATION_EVENTS~ON_STOP

This method is called by the BSP runtime environment


when the corresponding BSP application is explicitly
ended. This applies to both stateless and stateful
applications.

Please note that this time point is not available after


every request in stateless BSP applications. In addition
this time is not evaluated if the session is implicitly
terminated by a timeout. Consequently, in this method it
is only possible to execute optional operations that are
not critical.
Typically, this is a good time for cleanup operations such
as deleting browser cookies or server-side cookies, if the
application generated them.
IF_BSP_APPLICATION_EVENTS~ON_REQU
EST

This method is called by the BSP runtime environment for


every incoming request to a BSP before the BSP is given
control (in the OnRequest [page 214] event handler).
This time can be used by the application class, for
example, to restore attributes that were rescued in clientor server-side cookies in a previous request.

IF_BSP_APPLICATION_EVENTS~ON_RESP
ONSE

Web Application Server

This method is called by the BSP runtime for every


outgoing response of a BSP after the BSP has been
processed (after the OnManipulation [page 217]event
handler).

620 SP 9

209

SAP Online Help

25.10.2002

This time can be used by a stateless application


class for tasks such as rescuing attributes in clientside or server-side cookies.
See also:
You can find details of interface IF_BSP_APPLICATION_EVENTS in the reference
documentation: Interface IF_BSP_APPLICATION_EVENTS [page 245]

Application Basis Class CL_BSP_APPLICATION


If an application class does not already have a super class, it can be derived from the
predefined base class CL_BSP_APPLICATION. This class provides methods that are
typically required by a BSP application for embedding in a Web environment. This is how
information about the current BSP application (such as session timeout, current URL of BSP
application, state mode, and so on) can be called or set.
As the application object is an application attribute in every BSP event handler, the
methods of the CL_BSP_APPLICATION class are also available with the corresponding
inheritance. This makes it easy to provide the relevant functionality to lower application levels
using a single object reference.
See also:
You can find details of basis class CL_BSP_APPLICATION in the reference documentation:
Class CL_BSP_APPLICATION [page 226]

BSP Components
Business Server Pages (BSPs) are HTML pages that contain the actual application logic and
presentation logic. BSPs define the Web user interface and determine the elements of user
interaction.
BSPs consist of the following components:

Business Server Pages


Layout
Processing
Scripting

Page
Attributes
Data

Tables
Parameter
...

Web Application Server

Event Handler

OnCreate

OnRequest

Administration
Attributes
URL

Packet

OnInitialization
Created by
OnInputProcessing
HTTPS

Type
Definitions

OnManipulation

Preview

OnDestroy

620 SP 9

...

210

SAP Online Help

25.10.2002

Server-side scripting determines the presentation logic as part of layout processing [page
212]. In the preview, you can check the appearance of your pages, without having to call up
the browser.
Page attributes [page 218] are visible in the layout processing as well as in the event handlers
of a page. They can be used to store data obtained in the standard handler OnInitialization,
and to make this data accessible for the layout processing and the other event handlers.
Predefined event handlers [page 213] are available for the different events.
You can use type definitions [page 221] to define local types.
Similar to every object in the SAP System, BSPs also have different administration attributes
[page 211].

Properties
BSPs have a number of general properties or attributes. For example, each BSP is assigned
to a package in the SAP system, and each BSP has a URL used to call up the BSP in a Web
browser. The following describes the most important additional properties.

Page Type
You can find additional information about the different features of a page in Structure of a
BSP Application [page 198].

Error Handling
For more information see Creating Error Pages [page 341].

Status
A BSP can be stateful or stateless. For more information see Stateful and Stateless [page
381].

Caching
For more information see Caching BSPs [page 403].

Transmission Options
You can set the flags Compression and HTTPS as the transmission options.

Compressing
If you set this flat, the page is sent compressed to the browser, provided that the
browser supports compression.

Note that it only makes sense to activate compression for large pages. It is
considerably more efficient to send small pages uncompressed.
It is considerably more efficient to send small pages uncompressed.

HTTPS
By selecting this flag, you can determine that a BSP should be accessed using
HTTPS, that is, a secure connection. The BSP runtime then checks the URL. In the
case of http://... it redirects the browser immediately to https://... .

Web Application Server

620 SP 9

211

SAP Online Help

25.10.2002

Not the following browser-specific feature: As soon as you activate HTTPs, all
other BSPs of your BSP application are accessed using HTTPS.
It is considerably more efficient to send small pages uncompressed.

Layout
Use
You determine the presentation logic for your BSP using server-side scripting in the layout.
To ensure clean development, layout and presentation must be separated from processing
logic. Therefore, scripting for the static details of a page is part of layout processing, while the
dynamic processing steps are set in the different event handlers (see Event Handlers [page
213]).
The layout can also be regarded as an internal event handler for the presentation.

You can create your own stylesheets [page 426] or use predefined ones.

Functions
You can access the following objects in the implementation:
Object

Reference Type

Description

APPLICATION

type ref to application class

Application cla
individual appl
specified in the
application cla
means that the
not available.

RUNTIME

type ref to IF_BSP_RUNTIME

The runtime o
interface IF_B

REQUEST

type ref to IF_HTTP_REQUEST

The request o
interface IF_H

RESPONSE

type ref to IF_HTTP_RESPONSE

The response
interface IF_H

PAGE

type ref to IF_BSP_PAGE

Page object [p
IF_BSP_PAGE

PAGE_CONTEXT

type ref to IF_BSP_PAGE_CONTEXT

Page context o
interface IF_B
266].

Example
BSP only with Layout [page 395]

Web Application Server

620 SP 9

212

SAP Online Help

25.10.2002

Event Handler
Event handlers allow the separation of static and dynamic code in a page. The layout
processing deals with the static data, while the event handlers deal with the dynamic data.
The following predefined event handlers are available in the SAP system:
Event Handler

Description

OnCreate [page 213]

OnCreate is called once when the page is first created (stateful


mode), and performs a once-off data initialization or object
creation.

OnRequest [page 214]

OnRequest is called whenever a request is made for a


particular page and is used to restore the internal data
structures from the request. This is important when working in
stateless mode.

OnInitialization [page 215]

This event handler is mainly used for data retrieval. For


example, it allows data required for displaying the BSP to be
read from the database. It can also execute any program.

OnInputProcessing [page 216]

This event handler checks and processes user input. It can


also define navigation, that is, whether the user should be taken
to the same page or another when the BSP is called.

OnManipulation [page 217]

You can use this event handler to manipulate the HTTP data
stream later.

OnDestroy [page 218]

This event handler is available for special functions.

The ABAP syntax checks that apply in the context of ABAP Objects also apply to
event handlers.
Read and modify access to page attributes is available in all handlers. Global objects [page
278] are also available.

Global objects and their signatures for individual event handlers are displayed if
you choose

in the Web Application Builder.

The use of the individual event handlers is explained in more detail in the individual sections
of the documentation.
See also:
Control Flow of BSPs [page 391]

OnCreate
Use
OnCreate is used when a page is called for the first time, and performs a once-off data
initialization or object creation.
OnCreate is called each time that the BSP page class [page 254] is created. You can
therefore initialize the page object (in object-oriented thought, this corresponds to the

Web Application Server

620 SP 9

213

SAP Online Help

25.10.2002

constructor). OnCreate initializes the parts of the object that are created once and then used
for the entire lifetime of the object, such as the online shopping basket.
create object shopbasket.
The data that is used to fill the object is read in the event handler OnInitialization [page 215]
The BSP application is called in the following cases:

Single call, if the BSP application is staeful.


In this case, the the normal ABAP OO constructor.

Call each time if the BSP page class is created in the stateless case.

The opposite of OnCreate is OnDestroy [page 218].

Integration
OnCreate is useful mainly in stateful applications, because in stateless mode, the page object
is reinitialized every time the page is called. In you are working in stateful mode without an
explicit navigation path, and if you run the page a second time (reuse the page), the page
instance remains constant. OnCreate is not run the second time.
See also: Stateful and Stateless BSP Applications [page 381]

Functions
You can access the following objects in the implementation:
Object

Reference Type

Description

APPLICATION

type ref to application class

Application cla
individual appl
specified in the
application cla
means that the
not available.

RUNTIME

type ref to IF_BSP_RUNTIME

The runtime o
interface IF_B

PAGE

type ref to IF_BSP_PAGE

Page object [p
IF_BSP_PAGE

PAGE_CONTEXT

type ref to IF_BSP_PAGE_CONTEXT

Page context o
interface IF_B
266].

OnRequest
Use
OnRequest is run when a request comes to access the current page. This request can be
made in the following ways:

The URL is entered in the browser. In this case, OnInitialization is run after OnRequest.

The user inputs data on a page (current page or other pages). In this case,
OnInputProcessing is run after OnRequest.

See also: Event Handlers [page 213]

Web Application Server

620 SP 9

214

SAP Online Help

25.10.2002

Integration
OnRequest is the second handler (after OnCreate [page 213]) to be called when a BSP is
being processed.
The only exception to this occurs when a page is recalled in stateful mode without explicit
navigation. In this case, OnCreate is skipped and OnRequest is called straight away.

Functions
You can access the following objects in the implementation:
Object

Reference Type

Description

APPLICATION

type ref to application class

Application cla
individual appl
specified in the
application cla
means that the
not available.

RUNTIME

type ref to IF_BSP_RUNTIME

The runtime o
interface IF_B

REQUEST

type ref to IF_HTTP_REQUEST

The request o
interface IF_H

EVENT_ID

type STRING

NAVIGATION

type ref to IF_BSP_NAVIGATION

The navigation
interface IF_B

PAGE

type ref to IF_BSP_PAGE

Page object [p
IF_BSP_PAGE

PAGE_CONTEXT

type ref to IF_BSP_PAGE_CONTEXT

Page context o
interface IF_B
266].

Example
Persistency of Data Using Serverside Cookies [page 384]

OnInitialization
Use
This event handler is processed directly after OnRequest during page processing.
This handler implements data retrieval. The data is stored in page attributes and is therefore
accessible in the layout and in the other event handlers.

Integration
While the event handler OnCreate [page 213] is used to initialize objects needed for entire
page, OnInitialization is used for getting data from database tables.
If you develop a BSP for managing a shopping basket, the shopping basket object is
initialized using OnCreate and then filled with selected products. Here, this would be the

Web Application Server

620 SP 9

215

SAP Online Help

25.10.2002

catalog ID and the number of objects. You use OnInitialization to read the short texts from the
database, calculate the current subtotal, and so on.

Functions
You can access the following objects in the implementation:
Object

Reference Type

Description

APPLICATION

type ref to application class

Application cla
individual appl
specified in the
application cla
means that the
not available.

RUNTIME

type ref to IF_BSP_RUNTIME

The runtime o
interface IF_B

REQUEST

type ref to IF_HTTP_REQUEST

The request o
interface IF_H

RESPONSE

type ref to IF_HTTP_RESPONSE

The response
interface IF_H

NAVIGATION

type ref to IF_BSP_NAVIGATION

The navigation
interface IF_B

PAGE

type ref to IF_BSP_PAGE

Page object [p
IF_BSP_PAGE

PAGE_CONTEXT

type ref to IF_BSP_PAGE_CONTEXT

Page context o
interface IF_B
266].

Example
BSPs with Layout, Initialization and Navigation [page 398]

OnInputProcessing
Use
This event handler is run after the user dialog has been opened. It checks input and triggers
navigation to a subsequent page.
The form field OnInputProcessing is available (see also Control Flow of BSPs [page
391]).

Functions
You can access the following objects in the implementation:
Object

Reference Type

Description

APPLICATION

type ref to application class

Application cla
individual appl
specified in the
application cla
means that the
not available.

Web Application Server

620 SP 9

216

SAP Online Help

25.10.2002

RUNTIME

type ref to IF_BSP_RUNTIME

The runtime o
interface IF_B

REQUEST

type ref to IF_HTTP_REQUEST

The request o
interface IF_H

EVENT_ID

type STRING

NAVIGATION

type ref to IF_BSP_NAVIGATION

The navigation
interface IF_B

PAGE

type ref to IF_BSP_PAGE

Page object [p
IF_BSP_PAGE

PAGE_CONTEXT

type ref to IF_BSP_PAGE_CONTEXT

Page context o
interface IF_B
266].

Example
BSPs with Layout, Initialization and Input Processing [page 400]

OnManipulation
Use
This event handler is processed after the WCF controls embedded in the page are generated.
You can use OnManipulation to manipulate the HTTP data stream again (in particular for
XSLT processing).

Functions
You can access the following objects in the implementation:
Object

Reference Type

Description

APPLICATION

type ref to application class

Application cla
individual appl
specified in the
application cla
means that the
not available.

RUNTIME

type ref to IF_BSP_RUNTIME

The runtime o
interface IF_B

REQUEST

type ref to IF_HTTP_REQUEST

The request o
interface IF_H

RESPONSE

type ref to IF_HTTP_RESPONSE

The response
interface IF_H

PAGE

type ref to IF_BSP_PAGE

Page object [p
IF_BSP_PAGE

PAGE_CONTEXT

type ref to IF_BSP_PAGE_CONTEXT

Page context o
interface IF_B
266].

Web Application Server

620 SP 9

217

SAP Online Help

25.10.2002

Example
Persistency of Data Using Serverside Cookies [page 384]

OnDestroy
Use
This event handler runs immediately before the page instance is deleted and is therefore the
exact opposite of OnCreate [page 213]. You can use it to execute closing actions for a page.

Since locks and so on are reset in ABAP, this event handler is not usually
required and is therefore rarely used.
With stateful processing, the event handler OnDestroy is not called in every request-response
cycle and the page object is not destroyed. OnDestroy is only called right at the end when
you switch back to stateless processing. With stateless processing, both OnCreate and
OnDestroy are called for every request-response cycle.
This event handler is therefore called in very rare cases, for example if an application is
stateful and the controllers lifetime is shorter. The system then explicitly destroys the
controller and calls the corresponding method.
You can use this event handler in connection with server-side cookies, for example: Using
OnCreate you can load the cookie and then (at the end of the process flow) you use
OnDestroy to store it again so that the information held in the cookie does not get lost.

Functions
You can access the following objects in the implementation:
Object

Reference Type

Description

APPLICATION

type ref to application class

Application cla
individual appl
specified in the
application cla
means that the
not available.

RUNTIME

type ref to IF_BSP_RUNTIME

The runtime o
interface IF_B

PAGE

type ref to IF_BSP_PAGE

Page object [p
IF_BSP_PAGE

PAGE_CONTEXT

type ref to IF_BSP_PAGE_CONTEXT

Page context o
interface IF_B
266].

Page Attributes
Page attributes are parameters that are declared explicitly for one page. You can access
page attributes from the layout and from all event handlers. You use page attributes to store

Web Application Server

620 SP 9

218

SAP Online Help

25.10.2002

data that is determined in the event handler OnInitialization, and you can use the page
attributes to make the data accessible to layout processing and the remaining event handlers.
Access to the contents of the page attribute is not, however, given automatically at any time.
If, for example, you fill an internal table in OnIntialization that you have defined as a page
attribute, although this definition is known in OnInputProcessing, the table contents is not
known if you are working in stateless mode. Additional information is described below.
There are two types of page attributes:
Automatic page attributes
Non-automatic page attributes

Automatic Page Attributes


If you mark a page attribute as automatic (auto in the system), the attribute automatically
gets its values via the calling URL or via the navigation process from other pages. This kind of
attribute only has to be declared for one page. It is identified by its name equivalence. If
another page uses a parameter with the same name, at runtime that parameter automatically
gets the same values as the attribute.

navigation -> set_parameter(name = 'FLIGHT' value = 'LH' )


Let us assume that you have defined FLIGHT as an automatic page attribute and
assigned it a value from the navigation process.
If you then use a parameter of the same name on another page, this parameter
will automatically get the value ' LH' (Lufthansa) at runtime.
Possible Types for Automatic Page Attributes
Before SAP Web Application Server 6.10, auto page attributes could only have the type
STRING.
Now, other types are available:
Elementary types except for XSTRING
Structures
Tables

If firstname is a field in a structure called myaddress of the type address,


and myaddresses is a table of addresses, you can access firstname in the
layout as follows:
<input type=text name="myaddress.firstname">
myadresses[i].firstname allows you to specify the first name in question in
the line of the table represented by i, that is, if i=6, the first name used in line 6
of the table is being referred to.

Non-automatic page attributes


If you flag a page attribute as non-automatic, the attribute gets its values from the class
attribute.

Transferring Parameters Between Pages: Visibility of Page


Attributes
The visibility of page attributes when parameters are transferred between BSP pages
depends on whether the navigation is explicit or implicit.
Explicit navigation

Web Application Server

620 SP 9

219

SAP Online Help

25.10.2002

For example, if navigation->goto_page(page.htm) is called, this is explicit


navigation. It does not matter if the navigation takes you to the same page from which
you came.
In explicit navigation, the page object is always reinstantiated. When the page object
is being reinstantiated, in both stateful and stateless mode, the attributes with
navigation->set_parameter must be transferred to auto page attributes of the
same name, so that the values that were set are not lost.
Implicit navigation
User input triggers the sending of a request. Because no explicit navigation has been
provided, the same page is run again.
With implicit navigation, the page attributes are transferred automatically from
OnInputProcessing to OnInitialization, both in stateful and stateless mode.
The auto page attributes are refilled by the request, both in stateful and stateless
mode.
The difference is that, in stateful mode, any non-auto page attributes that may have
changed retain the changed value, whereas in stateless mode, the values are reset to
the original values. This is because the page instance stays alive in stateful mode,
but is reinstantiated in stateless mode.

Lifetime of Page Attributes


When you navigate between pages, there are the following cases of different lifetimes for
automatic and non-automatic page attributes:
Lifetime of attributes remaining on the same page
Lifetime of attributes with navigation to the same page
Lifetime of attributes with navigation to a different page

Lifetime of attributes remaining on the same page


No navigation takes place.
Attribute Type

Value in
Request
(Example Value)

Value in
OnInputProcess
ing

Explicit
Transfer

Value in
OnInitialization

automatic

SAP

SAP

No

SAP

automatic

SAP

SAP

Yes

SAP

Non-automatic

SAP

No

SAP

Non-automatic

SAP

Yes

SAP

Lifetime of attributes with navigation to the same page


The navigation object is used (navigation->goto_page(samepage.htm)) to navigate to
the same page.
Attribute Type

Value in
Request
(Example Value)

Value in
OnInputProcess
ing

Explicit
Transfer

automatic

SAP

SAP

No

automatic

SAP

SAP

Yes

Non-automatic

SAP

No

Non-automatic

SAP

Yes

Web Application Server

620 SP 9

Value in
OnInitialization

SAP

220

SAP Online Help

25.10.2002

Lifetime of attributes with navigation to a different page


The navigation object is used (navigation->goto_page(otherpage.htm)) to navigate
to a different page.
Attribute Type

Value in
Request
(Example Value)

Value in
OnInputProcess
ing

Explicit
Transfer

automatic

SAP

SAP

No

automatic

SAP

SAP

Yes

Non-automatic

SAP

No

Non-automatic

SAP

Yes

Value in
OnInitialization

SAP

Type Definitions
You can create type definitions for pages with flow logic. Type definitions are not available for
views, however.
If you want to use a page attribute that should only be used within a page and in the different
methods of the page (event handler and layout), you can create a local type for this. Type
definitions are therefore local types visible in all event handlers of a BSP and the BSP itself.
Type definitions are also relevant when BAPIs are used (see BAPI Explorer [page 424]). In
the page editor, you call the BAPI browser through which you cut & paste the type definitions
and a template for the requested BAPI call to the Type Definition and Event Handler tabs in
your BSP.

You define local types only for those objects that are necessary within a BSP for
the processing process. Types that are used several times or that can be
implemented universally should be defined in the Data Dictionary.

BSP Directives
Overview
BSP directives are enclosed in tags: <% Directive %>
The directives described in the following sections are supported by Business Server Pages
(BSP). The syntax is compatible with the familiar server page technology.
The following BSP directives are available:
Page Directive [page 222]
Inline Code [page 223]
Comments [page 224]
Include Directive [page 224]
OTR Directives [page 224]
Web Application Server

620 SP 9

221

SAP Online Help

25.10.2002

Extension Directive [page 225]

You use the Tag Library [page 421] to add BSP directives to your code using
Drag & Drop.
For more information see Transferring Variables [page 225].

Special Programming Features


The following code sections for the layout of a BSP are not equivalent:
<% read table itab index lv_index. %>
<% if sy-subrc ne 0. clear workarea. endif. %>
and:
<% read table itab index lv_index.
if sy-subrc ne 0. clear workarea. endif. %>
The first code extract above contains a function module call between the two ABAP
commands. The second code extract does not:
....
* BSP SCRIPT source
read table itab index lv_index.
* BSP STATIC source
* HTML begin: #### ######
CALL METHOD %_IF_PM->ADD_STATIC_REF
exporting
encoding = 0
source = %_HTML_POOL
offset = 0000018407 length = 0000000039 .
* BSP SCRIPT source
if sy-subrc ne 0. clear workarea. endif.
....
This means that the sy-subrc set when the internal table is read is overwritten by the
function module call. The two pieces of code therefore behave differently.

Page Directive
Definition
This directive is used to specify the script language.
ABAP and JavaScript are currently supported.

<%@ page language=("ABAP" | "JAVASCRIPT") %>

otrTrim
From SAP Web AS 6.20 Support Package 7, the attribute otrTrim is also available for the
page directive.

Web Application Server

620 SP 9

222

SAP Online Help

25.10.2002

<%@ page language=("ABAP" | "JAVASCRIPT") otrTrim=("TRUE |


"FALSE) %>
This attribute is a boolean value, that is, it can have the values TRUE and FALSE. The default
value is FALSE. If it is set to TRUE, all OTR texts on a page are condensed by removing all
blank characters from the start and end of a string.
An example of switched on attribute (otrTrim=true):
<%@page language="abap" otrTrim="true" %>
<%
DATA: s TYPE STRING VALUE 'test'.
%>
[<otr> test line </otr>]<br>
[<otr> before <%= s%> middle <%= s%> end. </otr>]<br>
[<%= otr(sbsp_test/it00_otr_1) %>]
The output generated using this coding then looks as follows:
[test line]
[before test middle test end.]
[This is a test for an alias text]
Example of the case when otrTrim is switched off (otrTrim=false):
<%@page language="abap" otrTrim="false" %>
<%
DATA: s TYPE STRING VALUE 'test'.
%>
[<otr> test line </otr>]<br>
[<otr> before <%= s%> middle <%= s%> end. </otr>]<br>
[<%= otr(sbsp_test/it00_otr_1) %>]
The output generated using this coding then looks as follows:
[ test line ]
[ before test middle test end. ]
[This is a test for an alias text]

Inline Code
Definition
With this directive you can embed the script code into the page.
The inline code is written in the language specified with the Page [page 222] directive.

<% inline code %>

<%@ page language="javascript"%> <% inline code javascript


%>

Web Application Server

620 SP 9

223

SAP Online Help

25.10.2002

Comments
Definition
You can write comments on the code on the server.
Unlike code that includes HTML comments, server-side comments are not included in the
page sent to the client /browser.
When you use HTML comments, however, they require longer processing times as well as
larger bandwidths. This is why you should not use HTML comments with BSPs or views.

<%-- code comments or text --%>

Include Directive
Definition
With this directive you can paste in existing pages or pages fragments into the page.
Enter the URL of the page to be pasted in relative to the URL of the current page.

<%@ include file="relative URL"%>

OTR Directives
Definition
The Online Text Repository (OTR) is a repository for all HTML texts, which are accessed
using an alias. OTR texts can be translated into other languages using translation tools. At
runtime, the OTR directive is replaced by the text defined for the logon language.

Use
There are two ways of using the OTR.
1. You can first write the text in the OTR and give it an alias that should be as meaningful as
possible.
Then you can display the text with the following syntax: <%=otr(alias)%>.
2. You can however also specify the text in the page layout:
<otr> HTML text, can also contain scripting code </otr>
This is an auto-OTR text that is automatically transferred to the OTR and translated
there. If the user logs on in a different language, they see the translated text.

Web Application Server

620 SP 9

224

SAP Online Help

25.10.2002

The text is only automatically transferred if it was entered in the original


language.
See also:
Internationalization and Translation [page 412]
Online Text Repository (OTR) [External documentation]

Transferring Variables
You can transfer expressions, for example variables, with the following syntax:

Value transfer: object = <%=varname%>

bgcolor = "green" creates a green background by transferring the value


green. With bgcolor = <%=color%> the current value of the variable
color is assigned to the attribute bgcolor.

Extension Directive
Definition
You can use the extension directive to import a BSP extension into your BSP. As a result you
can access all elements of the extension in your BSP. The extension directive is always
located immediately after the page directive [page 222].

<%@extension name="<Name>" prefix="<Prfix>"%>


The prefix is used as the namespace for all elements in the BSP extension. The prefixes sap
and bsp are reserved.
See also:
BSP Extensions [page 284]

Classes and Interfaces


The following classes and interfaces are central components of the BSP programming model.
Classes:
Class CL_BSP_APPLICATION [page 226]
Class CL_BSP_MESSAGES [page 226]
Class CL_BSP_SERVER_SIDE_COOKIE [page 230]

Web Application Server

620 SP 9

225

SAP Online Help

25.10.2002

Class CL_BSP_GET_TEXT_BY_ALIAS [page 235]


Class CL_BSP_CONTROLLER2 [page 361]
Interfaces:
Interface IF_BSP_APPLICATION [page 240]
Interface IF_BSP_APPLICATION_EVENTS [page 245]
Interface IF_BSP_NAVIGATION [page 248]
Interface IF_BSP_PAGE [page 254]
Interface IF_BSP_RUNTIME [page 262]
Interface IF_BSP_PAGE_CONTEXT [page 266]
These classes and interfaces are the basis for the corresponding global objects [page 278].

To develop BSP applications with the focus on representing Web pages on


different mobile end devices, you can use interface IF_CLIENT_INFO [page 454].

Class CL_BSP_APPLICATION
Overview
Class CL_BSP_APPLICATION is an optional superclass for BSP application classes [External
documentation]. Each application has the option of deriving its own application class from
CL_BSP_APPLICATION. If the application class has not already been derived in an
inheritance hierarchy, we recommend that it is derived from CL_BSP_APPLICATION.
Class CL_BSP_APPLICATION has methods that are typically required by a BSP application
for embedding in a Web environment. This is how information about the current BSP
application (such as session timeout, current URL of BSP application, state mode and so on)
can be called or set.

All of the methods of class CL_BSP_APPLICATION can be accessed via the


interface IF_BSP_APPLICATION and are described in the corresponding
reference documentation.
See Also:

IF_BSP_APPLICATION [page 240]

Object application [page 279]

Class CL_BSP_MESSAGES
Overview
You can use class CL_BSP_MESSAGES in BSPs for outputting error and information
messages.

Web Application Server

620 SP 9

226

SAP Online Help

25.10.2002

You can flag each message with a condition that serves as a key for the message. The effect
of this is that a message is only output in a BSP if the pertinent condition is fulfilled. This
makes it easy to place input-specific messages directly beside the relevant input fields.
Each BSP has an instance of this class that contains the current messages of the class. The
object is reset after every HTTP request/response cycle. The object is accessed from a BSP
via the parameter page of the event handler as page->messages or via the self-reference
me in the form of interface qualification me->if_bsp_page~messages.

Inheritance Hierarchy/Interface Composition


Implemented Interface
-

Superclass
-

Attributes
Attribute Name

Declaration Type

Description

co_severity_error

Constants

Error severity: error

co_severity_fatal_error

Constants

Error severity: Fatal error

co_severity_info

Constants

Error severity: Information

co_severity_success

Constants

Error severity: Confirmation of


success

co_severity_warning

Constants

Error severity: Warning

Methods
Method add_message
Signature

method add_message
importing
condition type string
message type string optional
otr_alias type string optional
severity type i
default co_severity_error
.

Description

This method inserts the message on the


condition specified into the list of messages. If
there is already a message with the condition,
it is overwritten.
One of the two parameters message or
otr_alias must be specified (exclusive or). If
message is used, the message text is
transferred directly, if otr_alias is used, the
alias name of an OTR text is transferred. This
makes it easy to address language-dependent
messages from the OTR.

Web Application Server

620 SP 9

227

SAP Online Help

Parameters

25.10.2002

CONDITION

Message condition

MESSAGE

Message text (if


otr_aliasparameter is not
used)

OTR_ALIAS

Alias name of an OTR


text to be used as
message text (if
message parameter
is not used)

SEVERITY

Message severity
(see constants
co_severity_...)

Return Values/Exceptions

Cross References

See also: assert, assert_message,


assert_severity

Method assert
Signature

method assert
importing
condition type string
returning
index type i
.

Description

This method returns the message index (1..n)


for the condition specified or 0 if there is no
message for this condition.
Thus, you can use this method in BSPs in if
statements if, for example, you want to insert
HTML areas in the output on a messagedependent basis.
Example:
...
<% if page->messages->assert( 'invaliduser' )
<> 0. %>
<img src="stop.gif">
<%= page->messages->assert_message(
'invaliduser' ) %>
<% endif %>

Parameters

CONDITION

Message condition

Return Values/Exceptions

INDEX

=0: no message for


condition
>0: Message index

Cross References

See also: assert_message,


assert_severity

Method assert_message
Signature

Web Application Server

method assert_message
importing

620 SP 9

228

SAP Online Help

25.10.2002
condition type string
returning
message type string
.

Description

This method returns the message for a


specified condition. If there is no message for
the condition, it returns an empty string.

Parameters

CONDITION

Message condition

Return Values/Exceptions

MESSAGE

Message

Cross References

See also: assert, assert_severity

Method assert_severity
Signature

method assert_severity
importing
condition type string
returning
severity type i
.

Description

This method returns the message severity (see


constants co_severity_... ) for the
specified condition, or 0 if there is no message
for the condition.

Parameters

CONDITION

Message condition

Return Values/Exceptions

SEVERITY

=0: no message for


condition
>0: Message severity
(see constants
co_severity_...)

Cross References

See also: assert, assert_message

Method get_message
Signature

method get_message
importing
index type I
exporting
severity type I
condition type string
message type string
.

Description

This method returns information about the


message for the specified index (1..n). If there
is no message for the index, in other words, if
index > num_messages(), this is indicated
by severity = 0 .

Parameters

INDEX

Message index
(1..num_messages())

Return Values/Exceptions

message

Message text

condition

Message condition

Web Application Server

620 SP 9

229

SAP Online Help

25.10.2002

severity

Cross References

Message severity
(see constants
co_severity_...)

See also: add_message, num_messages

Method num_messages
Signature

method num_messages
returning
count type I
.

Description

This method returns the number of messages


that were defined using add_message().

Parameters

Return Values/Exceptions

count

Cross References

See also: add_message

Number of currently
existing messages

Class CL_BSP_SERVER_SIDE_COOKIE
Overview
Class CL_BSP_SERVER_SIDE_COOKIE provides methods for setting, getting, deleting, and
managing cookies on the server.
Server-side cookies are persistent data, similar to the usual client-side cookies. However,
while on the client-side, there are restrictions that limit the size of cookies to around 4
kilobytes per cookie, the number of cookies to 300 in total and 20 per server or domain,
server-side cookies are subject to no such restrictions. A server-side cookie is stored on the
database.
For technical reasons, each individual cookie can be stored in one of the following ways:
as a field or
as a structure or
as an internal table

When you get a cookie, please note that it must be returned to the same data
structure. Otherwise, an error will occur, which you can query using an error
method.
The parameters username and session_id deserve special attention. Setting username
to sy-user is ambiguous in cases where an application is started by an anonymous user
stored on the server. It would be better to use session_id (see example) since runtime>session_id indicates the browser session.
When you design an application, you should give careful consideration to whether the
application should be stateless and the required context data be retained from page to page
in cookies (client-side or server-side), or whether the application should be stateful. A stateful
application makes sense when there is a large amount of context data that would otherwise
have to be read from or written to the database using cookies and thus slow down
performance (see also Stateful or stateless programming? [page 388]).

Web Application Server

620 SP 9

230

SAP Online Help

25.10.2002

The program BSP_SHOW_SERVER_COOKIES provides an overview of all of the cookies set in


the system. The program BSP_CLEAN_UP_SERVER_COOKIES deletes all expired cookies to
the day.

The system administrator should schedule the program


BSP_CLEAN_UP_SERVER_COOKIES to run in the background on a regular basis.
Class CL_BSP_SERVER_SIDE_COOKIE is contained in the package SBSP_RUNTIME.

Inheritance Hierarchy/Interface Composition


Implemented Interface
-

Superclass
-

Attributes
Attribute Name

Declaration Type

Description

CC_OK

Constants

Action was successful.

CC_WRONG_DATA_OBJECT

Constants

The data object of the cookie


to be read does not match the
data object of the set cookie.

CC_PARAMETER_MISSING

Constants

Call parameters are missing.

CC_NOT_EXISTS

Constants

Cookie does not exist.

Methods
All of the methods are in the visibility section public section.

Method get_server_cookie
Signature

method GET_SERVER_COOKIE
exporting
NAME
EXPIRY_TIME
EXPIRY_DATE
SESSION_ID
USERNAME
APPLICATION_NAMESPACE
APPLICATION_NAME
DATA_NAME
DATA_VALUE

Description

This method gets a server cookie.

Parameters

EXPIRY_TIME

Validity date (time):


to time

EXPIRY_DATE

Validity date (date):


to date

DATA_NAME

Data object name

Web Application Server

620 SP 9

231

SAP Online Help

25.10.2002

SESSION_ID

Session ID

USERNAME

Name of user

APPLICATION_NAMESPA
CE

Name space of BSP


application

APPLICATION_NAME

Name of BSP
application

NAME

Name of cookie

DATA_VALUE

Data object content

data: sorders type sales_orders,


edate
type d,
etime
type t,
usr
type string.
clear sorders.
call method cl_bsp_server_side_cookie=>get_server_cookie
exporting
name
= 'SALESORDER_GETLIST'
application_namespace = runtime->application_namespace
application_name
= runtime->application_name
username
= usr
session_id
= runtime->session_id
data_name
= 'SORDERS'
importing
expiry_date
= edate
expiry_time
= etime
changing
data_value
= sorders.

Method delete_server_cookie
Signature

method DELETE_SERVER_COOKIE
exporting
NAME
APPLICATION_NAME
APPLICATION_NAMESPACE
USERNAME
SESSION_ID

Description

This method deletes a server cookie.

Parameters

NAME

Name of cookie

APPLICATION_NAME

Name of BSP
application

APPLICATION_NAMESPA
CE

Name space of BSP


application

USERNAME

Name of user

SESSION_ID

Session ID

data: usr

type string.

call method cl_bsp_server_side_cookie=>delete_server_cookie


exporting
name
= 'SALESORDER_GETLIST'
application_namespace = runtime->application_namespace
Web Application Server

620 SP 9

232

SAP Online Help

25.10.2002
application_name
username
session_id

= runtime->application_name
= usr
= runtime->session_id.

Method set_server_cookie
Signature

method SET_SERVER_COOKIE
importing
DATA_VALUE
exporting
EXPIRY_DATE_ABS
EXPIRY_TIME_ABS
DATA_NAME
SESSION_ID
USERNAME
EXPIRY_TIME_REL
EXPIRY_DATE_REL
APPLICATION_NAMESPACE
APPLICATION_NAME
NAME

Description

This method sets a server cookie.

Parameters

DATA_VALUE

Data object content

EXPIRY_DATE_ABS

Valid to date

EXPIRY_TIME_ABS

Absolute validity
duration

If you do not specify


a value, the system
sets the absolute
validity duration to
23.59.
DATA_NAME

Data object name

SESSION_ID

Session ID if required

USERNAME

Name of user, and email address

EXPIRY_TIME_REL

Relative validity
duration in seconds

If you do not specify


a value, the system
sets the relative
validity duration to
23.59.

Web Application Server

EXPIRY_DATE_REL

Validity duration in
days

APPLICATION_NAMESPA
CE

Name space of BSP


application

APPLICATION_NAME

Name of BSP
application

NAME

Name of cookie

620 SP 9

233

SAP Online Help

25.10.2002

data: sorders type sales_orders,


edate
type d,
usr
type string.
call function 'BAPI_SALESORDER_GETLIST' destination 'ABC'
exporting
customer_number
= '0000001000'
tables
sales_orders
= sorders.
edate = sy-date.
add 1 to edate.

valid for one day

call method cl_bsp_server_side_cookie=>set_server_cookie


exporting
name
= 'SALESORDER_GETLIST'
application_namespace = runtime->application_namespace
application_name
= runtime->application_name
username
= usr
session_id
= runtime->session_id
expiry_date_abs
= edate
expiry_time_abs
= sy-uzeit
data_name
= 'SORDERS'
data_value
= sorders.

Method get_last_error
Signature

method GET_LAST_ERROR
importing
RC

Description

This method returns the return code of the last


call.

Parameters

RC

Returncode

data: rc type i,
txt type string.
rc = cl_bsp_server_side_cookie=>get_last_error( ).

Method get_last_error_name
Signature

method GET_LAST_ERROR_NAME
importing
NAME

Description

This method returns the internal name of the


exception of the last call.

Parameters

NAME

Internal error text

data: rc type i,
txt type string.
rc = cl_bsp_server_side_cookie=>get_last_error( ).
if rc ne 0.
txt = cl_bsp_server_side_cookie=>get_last_error_name( ).

Web Application Server

620 SP 9

234

SAP Online Help

25.10.2002
endif.

Method get_server_cookie_info
Signature

method GET_SERVER_COOKIE_INFO
exporting
COOKIES
APPLICATION_NAMESPACE
APPLICATION_NAME
SESSION_ID
USERNAME
NAME

Description

This method returns information about server


cookies.

Parameters

COOCIES

List of all cookies.

APPLICATION_NAMESPA
CE

Name space of BSP


application

SESSION_ID

Session ID

USERNAME

Name of user

NAME

Name of cookie

APPLICATION_NAME

Name of BSP
application

data: usr
type string,
cookie_info type tsscookiei.
call method
cl_bsp_server_side_cookie=>get_server_cookie_info
exporting
application_name = runtime->application_name
username
= usr
importing
cookies
= cookie_info .

Class CL_BSP_GET_TEXT_BY_ALIAS
Overview
Class CL_BSP_GET_TEXT_BY_ALIAS provides a method to fetch OTR alias texts.

Inheritance Hierarchy/Interface Composition


Implemented Interface
-

Superclass
-

Attributes
-

Web Application Server

620 SP 9

235

SAP Online Help

25.10.2002

Methods
Method GET_TEXT
Signature

method GET_TEXT
importing
LANGUAGE
ALIAS
returning
ALIAS_TEXT.

Description

This method fetches an OTR alias text for a specified OTR


alias name.

Parameters

LANGUAGE

Current language of SAP


System

ALIAS

Name of alias in form


<Paket>/<Aliasname>

ALIAS_TEXT

Text of the alias

Cross References

See also:
Internationalization and Translation [page 412]
Method GET_OTR_TEXT of IF_BSP_RUNTIME [page 262]

report OTRTEST.
class CL_BSP_RUNTIME definition load.
data TEXT type STRING.
TEXT = CL_BSP_RUNTIME=>GET_OTR_TEXT(
ALIAS = 'sbsp_test/it00_otr_1' ).
write / TEXT.

Class CL_BSP_CONTROLLER2
Overview
Class CL_BSP_CONTROLLER2 is used to create controllers and components [page 349].
Every controller class automatically inherits all methods and attributes from this central basic
class.

If the basic class of your controller class displays CL_BSP_CONTROLLER instead


of CL_BSP_CONTROLLER2, change the inheritance hierarchy accordingly.
Class CL_BSP_CONTROLLER2 enables you to:

Retain a list of sub-controllers

Create unique IDs for the sub-controllers, where the sub-controller is assigned the
controller ID prefix

Use models

Forward data to the correct controller as well as fill model classes (if they exist)

Web Application Server

620 SP 9

236

SAP Online Help

25.10.2002

Methods
Below you can find an overview of all methods in a controller class. Processing Process
provides details on the most important methods.
The individual methods can be separated into different categories:

Functions where overwriting is required


DO_REQUEST is the central method in a controller class.

You must overwrite this method.


In DO_REQUEST you specify the request processing, that is, this method is called for every
request. This method does the main work; in particular it should branch to the correct view.
DO_REQUEST can be used in two different areas:

If it is the top-level controller of a component, then this method handles both input and
output processing.

If it is a sub-controller of a component, then this method only handles output processing.

Functions where overwriting is recommended


You should overwrite these methods in order to determine input processing.
Method

Description

DO_HANDLE_DATA

Reacts to user input.


Processes data input for this component.

DO_HANDLE_EVENT

Reacts to user input.


Processes events if the component contains them.
Exactly one view controller is called to handle the
event, which contains an event such as a save
button, for example.

DO_FINISH_INPUT

Ends the input processing.

Functions where overwriting is possible


You can overwrite these methods in order to determine input processing.
Method

Description

DO_INIT

This method is called once at the start and is used


for initialization.
This method behaves like a constructor method.

DO_INITATTRIBUTES

This method is called with every request and is used


to initialize the attributes. The parameters are read
from the request. In this method, you can also
execute initializations that are required for each
request.
You can also use this method to set additional
attributes. This method is not absolutely necessary,
since you can use DO_REQUEST to solve everything
that you can (theoretically) handle here.

Web Application Server

620 SP 9

237

SAP Online Help

25.10.2002

Service functions
You can call these methods:
Method

Description

CREATE_VIEW

Creates or fetches a view instance


Use either the name of the view, or the object
navigation [page 280].

A view must always belong to the same BSP


application as its controller.
CALL_VIEW

Calls the request handler of the view instance.

CREATE_CONTROLLER

Creates or fetches a controller instance

CALL_CONTROLLER

Calls the request handler (method DO-REQUEST) of


the controller instance.

GET_ATTRIBUTE

Returns the specified page attributes.


Generic method for reading an attribute value.

GET_LIFETIME

Returns the lifetime of this page (only for the toplevel controller)

GET_PAGE_URL

Returns the URL of the page or the current controller

SET_ATTRIBUTE

Sets the specified page attributes.


Generic method for setting an attribute value.

SET_LIFETIME

Changes the lifetime of this page (only for the toplevel controller)

TO_STRING

Creates a formatted string

WRITE

Writes a formatted string in the output

GET_OUT

Fetches the current output writer

SET_MIME_TYPE

Changes the MIME type of the page or the content


type of the header field

INSTANTIATE_PARAMETER

Instantiates the parameter from the request using


the request data

SET_CACHING

Changes the caching values


There are two types of caching:

Browser cache

Server cache

See also Caching BSPs [page 403].

You can only use limited caching here.


Note that the server cache is not user-specific.
If you change the page, you should reset the cache
that may be set.
DISPATCH_INPUT

Dispatches the input processing (only for the toplevel controller).


For each input, DISPATCH_INPUT calls the correct
methods in the correct sequence.

Web Application Server

620 SP 9

238

SAP Online Help

25.10.2002
This method fetches data from the request.

This method does not have any attributes.


GET_ID

Calculates the ID from the specified ID and the


component ID

SET_MODEL

Creates and registers a model instance

CREATE_MODEL

Creates and registers a model instance

GET_CONTROLLER

Fetches a sub-controller

CONTROLLER_SET_ACTIVE

Sets a controller to active/inactive.


This is relevant with input processing, since you can
use it to hide a controller.
See also Lifetime [page 345]

DELETE_MODEL

Deletes a model instance

FILL_MODEL_DATA

Fills the model data

DELETE_CONTROLLER

Deletes a sub-controller

GET_MODEL

Fetches a model instance

IS_TOPLEVEL

Is this controller a top (main) controller (0: no, 1:


yes)?

IS_NAVIGATION_REQUESTED

Has a controller requested a navigation (0: no, 1:


yes)?

Framework functions
These methods are provided as part of the framework and are only included here for the sake
of completeness. They are not usually relevant for application development.
Method

Description

IF_BSP_DISPATCHER~REGISTER

Registers a sub-components

IF_BSP_CONTROLLER~FINISH_INPUT_PROCE
SSING

Processes or dispatches: end of input processing.

IF_BSP_CONTROLLER~FILL_VALUES

Processes or dispatches: handling values

IF_BSP_CONTROLLER~HANDLE_EVENT

Processes or dispatches: Handle event

GET_FIELD_COMPONENT

Finds components for a field name

GET_FIELD_MODEL

Finds model for a field name

Methods DO_DESTROY and SUBSCRIBE are not relevant.

Web Application Server

620 SP 9

239

SAP Online Help

25.10.2002

Interface IF_BSP_APPLICATION
Overview
The interface IF_BSP_APPLICATION is implemented using class CL_BSP_APPLICATION. It
provides methods that enable a BSP application to call up information about its runtime
environment or influence this environment.

Inheritance Hierarchy/Interface Composition


Implementing Classes
CL_BSP_APPLICATION

Enhanced Interface
-

Specializing Interfaces
-

Attributes
-

Methods
Method get_application_name
Signature

method get_application_name
returning
name type string
.

Description

This method returns the name of the BSP


application as defined in the development
environment (transaction SE80).

Parameters

Return Values/Exceptions

NAME

Name of the BSP


application

Method get_application_namespace
Signature

method get_application_namespace
returning
namespace type string
.

Description

This method returns the name space of the


corresponding BSP application as defined in
the development environment (transaction
SE80). For BSP applications that have no

Web Application Server

620 SP 9

240

SAP Online Help

25.10.2002
explicit name space specified, this is the SAP
name space, in other words, the method
returns sap.

Parameters

Return Values/Exceptions

NAMESPACE

Name space of the


BSP application

Method get_application_start_page
Signature

method get_application_start_page
returning
start_page type string
.

Description

This method returns the start page of the


corresponding BSP application as defined in
the development environment (transaction
SE80). If no page was explicitly specified, the
method returns the name default.htm.
The start page of a BSP application is called if
no specific page is included in the URL when
the application is started, in other words, when
the URL ends with the application name.

Parameters

Return Values/Exceptions

START_PAGE

Start page of the BSP


application

Method get_application_theme
Signature

method get_application_theme
returning
theme type string
.

Description

This method returns the name of the theme of


the BSP application as defined in the
development environment (transaction SE80).
If there is no theme explicitly associated with
the BSP application, the method returns an
empty string (default theme).
Themes can be used together with BSP
applications to customize the look and feel, see
also Layout Adjustments to BSP Applications
[External documentation].

Web Application Server

620 SP 9

241

SAP Online Help

25.10.2002

Parameters

Return Values/Exceptions

THEME

Name of the theme


associated with the
BSP application

Method get_application_url
Signature

method get_application_url
returning
url type string
.

Description

This method returns a server-specific URL that


references the current BSP application, for
example /sap/bc/bsp/sap/retailstore.

Parameters

Return Values/Exceptions

URL

Server-specific URL
of current BSP
application

Method get_request
Signature

method get_request
returning
request type ref to if_http_request
.

Description

This method returns an interface reference to


the current HTTP request object.

Parameters

Return Values/Exceptions

REQUEST

Interface reference to
the HTTP request
object

Method get_response
Signature

method get_response
returning
request type ref to if_http_response
.

Description

This method returns an interface reference to


the current HTTP response object.

Parameters

Return Values/Exceptions

RESPONSE

Web Application Server

620 SP 9

Interface reference to
the HTTP response

242

SAP Online Help

25.10.2002
object

Method get_runtime
Signature

method get_runtime
returning
runtime type ref to if_bsp_runtime
.

Description

This method returns an interface reference to


the current BSP runtime object.

Parameters

Return Values/Exceptions

RUNTIME

Interface reference to
the BSP Runtime
Object

Method get_timeout
Signature

method get_timeout
returning
timeout type t
.

Description

This method returns the current timeout value


(length of time). The timeout value is only
important for stateful BSP applications. Stateful
applications use this value to determine after
what length of time the server should terminate
a running application when no further requests
are received.

You can set timeout values in Transaction


SICF for BSP applications, see also
Creating an ICF Service [page 140].
Parameters

Return Values/Exceptions

TIMEOUT

Cross References

set_timeout

Maximum length of
time which a BSP
application may
continue to run in the
absence of requests.
After this time the
application is
automatically
terminated.

Method is_stateful
Signature

Web Application Server

method is_stateful
returning
stateful type i

620 SP 9

243

SAP Online Help

25.10.2002
.

Description

You can use this method to determine whether


a BSP application is working stateful or
stateless.

Parameters

Return Values/Exceptions

STATEFUL

0: Application is
stateless
1: Application is
stateful.

Cross References

See also: set_stateful, set_stateless

Method set_stateful
Signature

Method set_stateful

Description

This method sets the BSP application to


stateful processing.

Parameters

Return Values/Exceptions

STATEFUL

0: Application is
stateless
1: Application is
stateful.

Cross References

See also: is_stateful, set_stateless

Method set_stateless
Signature

method set_stateless.

Description

This method sets the BSP application to


stateless processing.

Parameters

Return Values/Exceptions

STATEFUL

0: Application is
stateless
1: Application is
stateful.

Cross References

See also: is_stateful, set_stateful

Method set_timeout
Signature

method set_timeout
importing
timeout type t
.

Description

This method sets the current timeout value


(length of time) of the BSP application. The

Web Application Server

620 SP 9

244

SAP Online Help

25.10.2002
timeout value is only important for stateful BSP
applications. Stateful applications use this
value to determine after what length of time the
server should terminate a running application
when no further requests are received.

You can set timeout values in Transaction


SICF for BSP applications, see also
Creating an ICF Service [page 140].
Parameters

TIMEOUT

Return Values/Exceptions

Cross References

See also: get_timeout

Maximum length of
time which a BSP
application may
continue to run in the
absence of requests.
After this time the
application is
automatically
terminated.

Interface IF_BSP_APPLICATION_EVENTS
Overview
The interface IF_BSP_APPLICATION_EVENTS can be implemented by a BSP Application
Class [page 608] if it wants to have control over executing its own functions at specific points
in the lifecycle of a BSP application. The possible time points for doing so are at application
start and end, and at HTTP Request Input and HTTP Response Output. Typically, these time
points are used to carry out authorization checks, data persisting, or data restoration in
stateless BSP applications.

Inheritance Hierarchy/Interface Composition


Enhanced Interface
-

Specializing Interfaces
-

Attributes
-

Methods
Method on_start
Signature

Web Application Server

method on_start
importing
runtime type ref to if_bsp_runtime

620 SP 9

245

SAP Online Help

25.10.2002
request type ref to if_http_request
response type ref to if_http_response
.

Description

This method is called by the BSP runtime


environment when the corresponding BSP
application is first started at the start of the
BSP session. This applies to both stateless
and stateful applications.
Typically, this time point is used to carry out
authorization checks that apply to the entire
application, or for preliminary data retrieval (in
stateful applications).

Parameters

Return Values/Exceptions

RUNTIME

Reference to the BSP


runtime

REQUEST

Reference to the
current HTTP
Request

RESPONSE

Reference to the
current HTTP
Response

Method on_stop
Signature

method on_stop
importing
runtime type ref to if_bsp_runtime
request type ref to if_http_request
response type ref to if_http_response
.

Description

This method is called by the BSP runtime


environment when the corresponding BSP
application is explicitly ended. This applies to
both stateless and stateful applications.

Please note that this time point is not


available after every request in stateless
BSP applications.
Moreover, the time point is not evaluated if
the session is implicitly terminated by a
timeout. Consequently, in this method it is
only possible to execute optional
operations that are not critical.
Typically, this is a good time for cleanup
operations such as deleting browser cookies or
server-side cookies, if the application
generated them.
Parameters

Web Application Server

RUNTIME

Reference to the BSP


runtime

REQUEST

Reference to the
current HTTP
Request

620 SP 9

246

SAP Online Help

25.10.2002

RESPONSE

Return Values/Exceptions

Reference to the
current HTTP
Response

Method on_request
Signature

method on_request
importing
runtime type ref to if_bsp_runtime
request type ref to if_http_request
response type ref to if_http_response
.

Description

This method is called by the BSP runtime


environment for every incoming request to a
BSP before the BSP is given control (in the
OnRequest [page 214] event handler).
This time can be used by the application class,
for example, to restore attributes that were
rescued in client- or server-side cookies in a
previous request.

Parameters

Return Values/Exceptions

RUNTIME

Reference to the BSP


runtime

REQUEST

Reference to the
current HTTP
Request

RESPONSE

Reference to the
current HTTP
Response

Method on_response
Signature

method get_parameter
importing
name type string
returning
value type string
.

Description

This method is called by the BSP runtime for


every outgoing response of a BSP after the
BSP has been processed (after the
OnManipulation [page 217]event handler).
This time can be used by a stateless
application class for tasks such as rescuing
attributes in client-side or server-side cookies.

Parameters

Web Application Server

RUNTIME

Reference to the BSP


runtime

REQUEST

Reference to the
current HTTP
Request

RESPONSE

Reference to the
current HTTP
Response

620 SP 9

247

SAP Online Help

Return Values/Exceptions

25.10.2002

Interface IF_BSP_NAVIGATION
Overview
The interface IF_BSP_NAVIGATION controls the transition between BSPs in a BSP
application.
The relevant interface reference is available in all event handlers of a BSP via the parameter
NAVIGATION.
There are two possible options for navigating between BSPs:
1. In the BSP layout, the subsequent page is addressed directly in the relevant HTML
elements such as <form> or <a>.
2. In the layout of a BSP only the page itself is referenced (for example, in <form> or <a>HTML elements with <%= page->page_name( ) %>) and a page change is triggered
(per HTTP Redirect) by means of the navigation object (see also Object navigation
[page 280]) that corresponds to the event. This is the preferred method in BSP
applications.
Page control via the navigation interface requires in some cases transfer of arguments to the
auto page attributes [page 218] of the subsequent page. There are methods available for this
purpose in the navigation interface.

Please note that the amount of data to be transferred is restricted by Web


Browser limitations (typically to 1KB). You should not try to transfer large
amounts of data, but rather where possible selection IDs that lead to the data
concerned.
If this is not possible in every case, you can use the mechanism "Auto-SubmitForms" as an alternative (see
IF_BSP_NAVIGATION~USE_AUTO_SUBMIT_FORM() ). This lifts the data
volume restriction. However, we recommend that you do not use this mechanism
as a general rule since it causes problems with the browser history and it is not
available for all devices (for example, WAP).

Inheritance Hierarchy/Interface Composition


Implementing Classes
CL_BSP_NAVIGATION

Enhanced Interface
-

Specializing Interfaces
-

Attributes
-

Web Application Server

620 SP 9

248

SAP Online Help

25.10.2002

Methods
Method call_application
Signature

method call_application
importing
url
type string
return_url_parameter type string default 'sap-exiturl'
return_event_id
type string optional
.

Description

You can use this method to call an external


application. The application is accessed via the HTTP
Redirect mechanism.
You must specify the external application in the
parameter URL.
There are two prerequisites for returning to the calling
application from the external application: 1. The calling
application must be implemented accordingly and 2.
The required return address must be specified.
The current page from which the external application
was accessed is taken as the return URL. The
parameter return_event_id lets you select an
additional event ID that should be triggered on return
as the event ID in the onInputProcessing event
handler of this BSP.
Since we cannot assume that all external applications
have the same prerequisites for transferring the return
address, you have the option of selecting this in the
parameter return_url_parameter as required.
The default name is sap-exiturl, whereby BSP
applications are able to call each other easily. For ITSbased applications, the address ~exitURL should be
used.

Actual navigation is not triggered at this point. It is


triggered on return from the BSP event handler!
Parameters

Return Values/Exceptions

URL

URL of external
application

RETURN_EVENT_ID

Name of the parameter


used to transfer the
return address/URL to
the calling application

RETURN_URL_PARAME
TER

Event ID used to
address the
onInputProcessing event
handler of the calling
page on return from the
calling application

Method encode_parameters
Signature

Web Application Server

method encode_parameters
importing
620 SP 9

249

SAP Online Help

25.10.2002
encoded type i value 1
.

Description

This method controls whether the parameters


defined using set_parameter() should be
passed uncoded in plaintext as name/value
pairs in the query string of the URL, or coded,
that is, BASE64-coded as a value of the URL
parameter sap-params.
Parameters are passed in coded form by
default.

Note that we are talking of coded form here,


not encrypted
Parameters

ENCODED

0: Parameter is
passed in plaintext as
name/value pairs
1: Parameter is
BASE64-coded

Return Values/Exceptions

Method exit
Signature

method exit
importing
exit_url type string optional
.

Description

This method terminates this BSP application


regardless of whether the application is
working stateful or stateless.
In particular, the event handler
if_bsp_application_events~on_stop is
triggered if the interface
IF_BSP_APPLICATION_EVENTS [page 245]
is implemented by the application class.
You can use the optional parameter exit_url
to branch to any end page or URL per HTTP
Redirect.

Actual navigation is not triggered at this point. It


is triggered on return from the BSP event
handler!
Parameters

EXIT_URL

Return Values/Exceptions

URL to which a HTTP


Redirect should
branch as the "end
page".

Method get_parameter
Signature

Web Application Server

method get_parameter
importing
name type string

620 SP 9

250

SAP Online Help

25.10.2002
returning
value type string
.

Description

This method returns the value of the requested


parameter from the navigation object [page
280].

Unlike set_parameter(), this method


always returns the value as a string.
Parameters

NAME

Parameter name

VALUE

Parameter value

Return Values/Exceptions

Cross Reference

set_parameter

Method goto_page
Signature

method goto_page
importing
url type string
.

Description

This method handles navigation to the


specified URL.
In most cases, this is a relative URL and
contains only the name of the subsequent
page, for example navigation>goto_page( 'confirm.htm' ).
Unlike the method next_page(), here the
subsequent page is specified directly.

Actual navigation is not triggered at this point. It


is triggered on return from the BSP event
handler!
Parameters

URL

Return Values/Exceptions

Cross Reference

next_page

URL of the
subsequent page,
typically a relative
URL or only the page
name

Method has_parameters
Signature

method has_parameters
returning
has_parameters type i
.

Description

This method indicates whether parameters


have been set for the current navigation object
(0: no, 1: yes).

Parameters

Web Application Server

620 SP 9

251

SAP Online Help

Return Values/Exceptions

25.10.2002

HAS_PARAMETERS

0: No parameters set
1: Parameters set

Cross Reference

set_parameter

Method next_page
Signature

method goto_page
importing
url type string
.

Description

This method defines the subsequent page by


specifying a page exit.
You can define page exits of a navigation
graph in the development environment
(transaction SE80) of a BSP application. When
you do so, starting from the current page, you
assign a target page via a page exit (that is, a
"link" identified by a unique name). Then, for
navigating between pages, the subsequent
page is not directly defined in ABAP code, an
indirection is inserted instead. The name of the
page exit is used to determine the subsequent
page currently assigned to the page exit. This
can be changed easily without having to adapt
all of its usages in the code.

Actual navigation is not triggered at this point. It


is triggered on return from the BSP event
handler!
Parameters

EXIT

Return Values/Exceptions

Cross Reference

goto_page

Name of page exit in


the navigation graph
(case-insensitive)

Method response_complete
Signature

Method response_complete

Description

You can use this method to indicate to the BSP


runtime that no further event handlers/sections
should be addressed on return from the BSP
event handler in which it was called. On the
contrary, the HTTP Response has already
been completely generated and can be sent
back to the client/browser.
This method is typically called in the
OnRequest or OnInitialization section of a BSP,
when the HTTP Response was generated
differently from the OnLayout section (for
example, MIME Object from the database or
generated XML Output) and was written
directly to the HTTP Response object. Calling
the OnLayout section would, in such cases,
include unwanted output in the response (for

Web Application Server

620 SP 9

252

SAP Online Help

25.10.2002
example, blanks that are of critical importance
in binary document). The call can be
suppressed here.

Parameters

Return Values/Exceptions

Method set_parameter
Signature

method set_parameter
importing
name type string
value type any optional
.

Description

This method sets the specified parameter for


the transfer to the subsequent page.
As a rule, the name of the parameter is the
same as an auto page attribute of the
subsequent page. Otherwise, it can be read on
the subsequent page using Request Object
and the method
if_http_request~get_form_field().
In certain circumstances, the value of the
parameter can be omitted. This would be the
case if a form field of the same name was sent
in the current request to be passed on to the
subsequent page. The parameter value is then
simply taken over from the current request and
passed to the subsequent page.
Since it is possible to transfer any ABAP data
types with the exception of references, the
parameter VALUE can only be untyped.

Parameters

NAME

Parameter name

VALUE

Parameter value. If
the parameter is not
specified; the value of
the form field of the
same name of the
HTTP Request is
taken.

Return Values/Exceptions

Cross Reference

get_parameter, has_parameters

Method use_auto_submit_form
Signature

method use_auto_submit_form
importing
target_frame type string optional
.

Description

With this method, when navigating to a subsequent


page, no HTTP redirects can be used, but insread
an HTML page is used with an embedded form.
The parameters to be transferred are mixed into the
form as hidden fields, and the form is automatically
returned to the subsequent page (auto submit) after

Web Application Server

620 SP 9

253

SAP Online Help

25.10.2002
it is received in the browser.
Using this method, you can circumnavigate the
dataset restrictions with query string parameters.
Note however, that auto submit forms can cause
problems in the browser history and that this
mechanism canot be used with WAP devices, for
example.
You can use parameter target_frame to control
in which HTML frame (or new browser window) the
subsequent page should be displayed.

Parameters

target_frame

Name of frame in
which subsequent
page is to be
displayed.

Return Values/Exceptions

cx_bsp_inv_param_type

Exception: the
parameter type is
not allowed.

Interface IF_BSP_PAGE
Overview
The interface IF_BSP_PAGE gives access to information about a BSP such as the page
names, the lifetime, the corresponding BSP application, the URL of the page, and so on.
IF_BSP_PAGE is implemented using the class CL_BSP_PAGE, which is the base class of all
BSPs. Consequently, the methods and attributes of this interface are indirectly available by
inheritance in all BSPs and can be accessed with the appropriate qualification via the
interface name (for example "name = if_bsp_page~get_page_name( ).").
The interface can also be addressed in all BSP event handlers [page 213] by means of the
parameter page [page 283] and can be extended to lower application levels if required. In
particular, the BSP page attributes can be read and set using the methods
get_attribute() and set_attribute().

Inheritance Hierarchy/Interface Composition


Implementing Classes
CL_BSP_PAGE

Enhanced Interface
-

Specialized Interfaces
-

Attributes
Attribute Name

Web Application Server

Declaration
Type

Description

620 SP 9

254

SAP Online Help

25.10.2002

co_format_currency

Constants

write()- or to_string()-method: Output as


currency

co_format_long

Constants

write()- or to_string()-method: long output

co_format_lower

Constants

write()- or to_string()-method: output in


lower-case letters

co_format_none

Constants

write()- or to_string()-method: standard


formatting

co_format_short

Constants

write()- or to_string()-method: short


output

co_format_upper

Constants

write()- or to_string()-method: output in


upper-case letters

lifetime_page

Constants

Page is valid until explicit navigation away from


this page

lifetime_request

Constants

Page is only valid for this HTTP Request

lifetime_session

Constants

Page is valid for the complete session (only for


stateful BSP applications)

messages

Instance attribute

Reference to the messages [page 282]-object of


this BSP

Methods
Method get_application
Signature

method get_application
returning
application type ref to object
.

Description

This method returns the application object [page 279] for this BSP.
If no application class was defined for the BSP application of this page,
a zero (0) reference is returned.

Parameters

Return
Values/Exceptions

application

Cross References

Application Class of a BSP Application [page 207]

Name of the BSP application

Method get_application_name
Signature

method get_application_name
returning
name type string
.

Description

This method returns the name of the BSP application of this page as
defined in the development environment (transaction SE80).

Parameters

Web Application Server

620 SP 9

255

SAP Online Help

25.10.2002

Return
Values/Exceptions

name

Cross References

Name of the BSP application

Method get_application_start_page
Signature

method get_application_start_page
returning
start_page type string
.

Description

This method returns the start page of the corresponding BSP


application as defined in the development environment (transaction
SE80). If no page was explicitly specified, the method returns the
name default.htm.
The start page of a BSP application is called if no specific page is
included in the URL when the application is started, in other words,
when the URL ends with the application name.

Parameters

Return
Values/Exceptions

start_page

Cross References

Start page of the BSP application

Method get_application_theme
Signature

method get_application_theme
returning
theme type string
.

Description

This method returns the name of the theme of the BSP application as
defined in the development environment (transaction SE80). If there is
no theme explicitly associated with the BSP application, the method
returns an empty string (default theme).
Themes can be implemented in connection with BSP applications for
Look & Feel customizing.

Parameters

Return
Values/Exceptions

theme

Cross References

Tailoring Layouts to BSP Applications [External documentation]

Name of the theme associated with the


BSP application

Method get_application_url
Signature

method get_application_url
returning
url type string
.

Description

This method returns a server-specific URL that references the current


BSP application, for example /sap/bc/bsp/sap/retailstore.

Web Application Server

620 SP 9

256

SAP Online Help

25.10.2002

Parameters

Return
Values/Exceptions

url

Cross References

Server-specific URL of current BSP application

Method get_attribute
Signature

method get_attribute
importing
name type string
exporting
value type any
.

Description

This method returns the value of the requested attribute.


Since attributes can be of any type, the return value can only be
untyped and must be integrated type-related when called.

ABAP move logic plays a role in the assignment of the attribute value
to the return value to enable the type conversion to take place. The
ABAP restrictions regarding type conversion apply so that exceptions
may occur in the event of incompatible type assignments.
Parameters

name

Return
Values/Exceptions

value

Attribute value

cx_bsp_inv_attr_name

Exception: Attribute does not exist

Cross References

Name of attribute (case-insensitive)

set_attribute()

Method get_lifetime
Signature

method get_lifetime
returning
lifetime type i
.

Description

This method returns the current settings of the lifetime of this BSP
page (see lifetime_..-constants of the IF_BSP_PAGEINTERFACE).
This method has no effect on stateless applications and always returns
the value lifetime_request.

Parameters

Return
Values/Exceptions

lifetime

Cross References

set_lifetime, lifetime_page, lifetime_request, lifetime_session

Web Application Server

Current lifetime of the BSP (see lifetime...constants of the IF_BSP_PAGE):


lifetime_page | lifetime_request |
lifetime_session

620 SP 9

257

SAP Online Help

25.10.2002

Method get_page_name
Signature

method get_page_name
returning
name type string
.

Description

This method returns the name of this BSP.

Parameters

Return
Values/Exceptions

name

Cross References

Name of the BSP

Method get_page_url
Signature

method get_page_url
returning
url type string
.

Description

This method returns the server-specific URL for this BSP.

Parameters

Return
Values/Exceptions

url

Cross References

Server-specific URL of the BSP

Method get_request
Signature

method get_request
returning
request type ref to if_http_request
.

Description

This method returns an interface reference to the current HTTP


Request Object.

Parameters

Return
Values/Exceptions

request

Cross References

IF_HTTP_SERVER [page 117]

Interface reference to the HTTP Request Object

IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]

Method get_response
Signature

Web Application Server

method get_response
returning
response type ref to if_http_response
.

620 SP 9

258

SAP Online Help

25.10.2002

Description

This method returns an interface reference to the current HTTP


Response Object.

Parameters

Return
Values/Exceptions

response

Cross References

IF_HTTP_SERVER [page 117]

Interface reference to the HTTP Response Object

IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]

Method get_runtime
Signature

method get_runtime
returning
runtime type ref to if_bsp_runtime
.

Description

This method returns an interface reference to the current BSP Runtime


Object.

Parameters

Return
Values/Exceptions

runtime

Cross References

Interface reference to the BSP Runtime Object

Method serialize
Signature

method serialize
returning
data type string
.

Description

This method serializes the content of this page (after processing in the
layout [page 212] event handler) in a string.
This method is typically only called in the OnManipulation [page 217]
section of the BSP when the generated output needs to be
postprocessed. However, for performance reasons this is not
recommended unless absolutely necessary.

The output of a BSP is no longer automatically returned to the client in


the HTTP Response when this method is called explicitly. Instead, the
developer is responsible for sending it. This can be done with the
method if_http_response~set_cdata() and the HTTP
Response Object.
Parameters

Return
Values/Exceptions

data:

Cross References

IF_HTTP_SERVER [page 117]

Serialized response of the BSP after the layout


section is processed.

IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]

Web Application Server

620 SP 9

259

SAP Online Help

25.10.2002

Method set_attribute
Signature

method set_attribute
importing
name type string
value type any
.

Description

This method sets the value of the specified attribute.


Since attributes can be of any type, the return value can only be
untyped and must be integrated type-related when called.

This method does not let you define new attributes dynamically at
runtime. On the contrary, only attributes that were defined in the
development environment (SE80) statically for the BSP page can have
values assigned. Otherwise, the method will terminate with the
exception cx_bsp_inv_attr_name.

ABAP move logic plays a role in the assignment of a value to the


attribute to enable the type conversion to take place. The ABAP
restrictions regarding type conversion apply so that exceptions may
occur in the event of incompatible type assignments.
name

Name of attribute (case-insensitive)

value

Value of attribute (appropriately typed)

Return
Values/Exceptions

cx_bsp_inv_attr_name

Exception: Attribute does not exist

Cross References

get_attribute()

Parameters

Method set_lifetime
Signature

method set_lifetime
importing
lifetime type i
.

Description

This method returns the current lifetime of this BSP page (see
lifetime_..-constants of the IF_BSP_PAGE).
This method has no effect on stateless applications.

Parameters

lifetime

Return
Values/Exceptions

Cross References

get_lifetime, lifetime_page, lifetime_request, lifetime_session

New lifetime of the BSP (see lifetime...-constants


of the IF_BSP_PAGE):
lifetime_page | lifetime_request |
lifetime_session

Method to_string
Signature

Web Application Server

method to_string
importing
l
t
620 SP 9

260

SAP Online Help

25.10.2002
value
type any
format
type i optional
outputlength type i optional
num_decimals type i optional
reference_value type c
returning
string
type string
.

Description

This method formats as a string the value of a scalar ABAP variable


with any type. There are several optional parameters available to let
you control the formatting.
The string generated can be easily integrated in the output in a BSP
using the output directive <%= .. %>.
value

Value to be formatted

format

Output format (see


if_bsp_page~co_format_..constants)

outputlength

Maximum output length (in characters)

num_decimals

Number of decimal places

reference_value

Reference value (for example, the


currency)

Return
Values/Exceptions

output

Formatted output string

Cross References

write()

Parameters

Method write
Signature

method write
importing
value
type any
format
type i optional
outputlength type i optional
num_decimals type i optional
reference_value type c
.

Description

This method outputs as a string the value of a scalar ABAP variable


with any type. Output is at the current write position in the BSP.
There are several optional parameters available to let you control the
formatting.
This method can be used for output in a BSP for example, in script
directives <% .. %>.

Parameters

Web Application Server

value

Value to be formatted

format

Output format (see


if_bsp_page~co_format_..constants)

outputlength

Maximum output length (in characters)

num_decimals

Number of decimal places

reference_value

Reference value (for example, the


currency)

620 SP 9

261

SAP Online Help

25.10.2002

Return
Values/Exceptions

Cross References

to_string

Method otr_trim
Signature

method otr_trim
importing alias
returning
text
.

Description

This method returns the language-dependent text for an OTR alias


(short text)
This method is available from SAP Web AS 6.20 Support Package 7.

Parameters

alias

Name of the defined OTR alias

Return
Values/Exceptions

text

Text in current language

Cross References

Internationalization and Translation [page 412]

Interface IF_BSP_RUNTIME
Overview
The interface IF_BSP_RUNTIME gives you access to information contained in the current
runtime environment of a BSP application. It gives you access to the most important objects
and information in the form of attributes.

Accessibility [page 406] is integrated in the BSP runtime.

Inheritance Hierarchy/Interface Composition


Implementing Class
CL_BSP_RUNTIME

Attributes
Attribute Name

Declaration Type

Description

application_name

Instance attribute

Name of BSP application

application_namespace

Instance attribute

Name space of BSP application

application_theme

Instance attribute

Theme of BSP application

Web Application Server

620 SP 9

262

SAP Online Help

25.10.2002

application_url

Instance attribute

URL prefix of BSP application

ddic_utils

Static attribute

Dictionary services

keep_context

Static attribute

Stateful/stateless BSP application (0/1)

page_name

Instance attribute

Name of the BSP

page_url

Instance attribute

URL prefix of BSP

runtime_url

Static attribute

URL prefix of BSP runtime

server

Static attribute

HTTP Server

session_manager

Static attribute

Workplace Session Manager

client_info

Static attribute

Device properties for the current


request

session_id

Static attribute

BSP Session ID
This attribute uniquely labels the user
session. The backend is therefore
completely independent, that is, the
value of this attribute is set
independently of the context at the
server.
The value of this attribute does not
change:
If you set keep_context
from 0 to 1 and
If you already have a browser
open and you open a new one
(using File New Window,
for example)
The value of this parameter does

Web Application Server

620 SP 9

263

SAP Online Help

25.10.2002
change if you close the browser and
open a new one.

Methods
Method construct_bsp_url
Signature

class-method construct_bsp_url
importing
in_protocol
type string
default 'http'
in_host
type string
optional
in_port
type string
optional
in_application_ns
type string
optional
in_application
type string
in_page
type string
optional
in_parameters
type tihttpnvp
optional
in_suppress_rewrite type I
default 0
exporting
out_protocol
type string
out_host
type string
out_port
type string
out_local_url
type string
out_abs_url
type string
.

Description

This method builds a server-specific, absolute URL for a


BSP application or BSP.
You can use the parameter in_protocol to control
whether a HTTP- or HTTPS URL should be generated.

This method can be expensive at runtime, You are


recommended not to call it unnecessarily often. At
runtime, instead of using this static method, you can use
the instance attribute runtime_url, application_url
or page_url as an alternative.
Parameters

Web Application Server

in_protocol

Requested protocol (HTTP


or HTTPS)

in_host

Requested Host

in_port

Requested Port Number

in_application_ns

Namespace of the BSP


application (if not 'sap')

in_application

Name of BSP application

in_page

Name of the BSP

620 SP 9

264

SAP Online Help

Return Values/Exceptions

25.10.2002

in_parameters

Table with name/value pairs


that are to be integrated in
the URL as query-string
parameters

in_suppress_rewrite

0: Allow URL rewriting of


the BSP runtime
1: Suppress URL rewriting
of the BSP runtime

out_protocol

Actual protocol (HTTP or


HTTPS), which can differ
from in_protocol if not
supported by the server

out_host

Domain name of the


application server

out_port

Port number of protocol on


the application server

out_local_url

URL relative to current


application server

out_abs_url

Absolute URL, that is,


including protocol,
application server name,
port number etc.

Method get_otr_text
Signature

method get_otr_text
importing
alias type string
returning
text type string
.

Description

This method returns the OTR text in the current


langauge (sy-langu) for the alias specified.
If there is no such alias, an empty string is
returned.
If there is no text for the alias in the current
language, the secondary (or fallback) language
is used.

Parameters

alias

OTR alias including


name space (caseinsensitive)

Return Values/Exceptions

text

OTR text for alias in


the current language
or empty string if no
alias exists

Method with_accessibility
Signature

Web Application Server

method with_accessibility
returning
access type boolean

620 SP 9

265

SAP Online Help

25.10.2002
.

Description

You determine the accessibility using this


method.

Parameters
Return Values/Exceptions

access

This return value


states whether
accessibility [page
406] is active or not.

Interface IF_BSP_PAGE_CONTEXT
Overview
Interface IF_BSP_PAGE_CONTEXT forms a wrapper around a BSP and is based on the Page
Context Object [page 284].

Inheritance Hierarchy/Interface Composition


Implementing Classes
Enhanced Interface
Specializing Interfaces
-

Attributes
-

Methods
Method GET_OUT
This method outputs the current, active writer to the stack.

Method GET_RUNTIME
This method returns the runtime object.

Method GET_NAVIGATION
This method returns the navigation object.

Method GET_REQUEST
This method returns the request object.

Method GET_RESPONSE
This method returns the response object.

Method GET_PAGE
This method returns the page object.

Web Application Server

620 SP 9

266

SAP Online Help

25.10.2002

Method POP_WRITER
This method takes the first writer off the stack and returns it.

Method PUSH_WRITER
This method sets a new writer on the stack and returns it as a response.

Method ELEMENT_PROCESS
You can use this method to process other BSP elements dynamically. You can use this when
you create Composite Elements [page 314] for example.

IF_CLIENT_INFO Interface
Definition
The IF_CLIENT_INFO interface provides a range of methods that take into account the
different display options for Web applications on different browsers, along with other devicespecific properties such as screen size or input method.

Use
In this way, you can use the methods of the IF_CLIENT_INFO interface when you create
Web applications like BSP application, and thus take the often substantial differences in
the display of Web pages on different devices into account.

You can also use this Device Recognition Process [External documentation] and
the comparable ClientInfo Interface [External documentation] when developing
Java applications.
So that you can estimate the significance for your Web application of the methods described
in the following table, some of them have been assigned a priority. For those device
properties not assigned a priority, you can decide yourself whether or not you want to use
them in your Web application.
Device properties can be categorized by their significance as follows:
Prio.

Title

Description

Prerequisite

This property is prerequisite for running the mobile application at all. In general, these
conditions are fulfilled by all real devices that fulfil the HTML or WAP standard.
Emulators, however, do not fulfil these prerequisites. Thus this property need not be
checked in the application. At most, you need a check program that ascertains whether
or not an emulator is suitable for executing the application

Application does not


work

If this property is not assigned a value, the application may crash on some devices
that is, may not be executable

Loss of information

If this property is not assigned a value, the application may not show all its information
For example, a loss of information may occur if the paragraph attribute for automatic
line breaks is switched off (<p mode=nowrap>) and the paragraph (in a WML page)
contains text that does not fit on one line. If the mobile device does not support the

GET_MARQUEE_TEXT_SUPPORTED [page 478] property, it is possible that


the end of the text is simply truncated. For this reason we advise you to think
carefully before switching off the automatic line break property even if doing so would
allow you, for example, to make better use of a small screen on a mobile telephone.
4

Unacceptable
di l

Web Application Server

If this property is not assigned a value, the application may be displayed in a way that
d
t d j ti t th l k d f l f th d i

620 SP 9

267

SAP Online Help

25.10.2002

display

does not do justice to the look and feel of the device

Inappropriate display

If this property is not assigned a value, the application may not be displayed at its best.
However, the display should not actually disturb the user significantly.

Similarly, some properties are assigned to the markup languages WML (Wireless Markup
Language) and HTML (Hypertext Markup Language) that is, you specify the markup
language for which each method is relevant and thus how it can meaningfully be used. For
example, the method GET_FRAMES_SUPPORTED is only significant in HTML, since only
HTML-enabled browsers can interpret frames. In general, it is HTML browsers on handheld
devices like PDAs and pocket PCs, WAP-enabled mobile telephones with small screens
cannot display frames, because of their screen interfaces. If the appropriate table column
does not contain a value, the method can be used in both markup languages.
The following source code fragment shows how you can access the methods of the
IF_CLIENT_INFO interface:
<%@page language=abap%>
<%
...
data client_info type ref to IF_CLIENT_INFO.
client_info = runtime->client_info.
if client_info->get_title_supported( ) = X.
...
%>

To obtain more information on using some of the methods of the


IF_CLIENT_INFO interface in your Web application, use the links in the table.

Methods
Method

Signature

Description

GET_ACCEPT [page
465]

method
get_accept
returning
value type string

Equivalent to the HTTP


request-header
userAgent.

GET_ALERTING_SUP
PORTED

method
get_alerting_supp
orted
returning
value type flag

Specifies whether or not


the device supports
messaging for example,
using SMS.

X or
space

GET_ANCHOR_SUPP
ORTED

method
get_anchor_suppo
rted
returning
value type flag

Specifies whether or not


the <anchor> tag is
supported

X or
space

WML

GET_ANCHOR_PREV
_SUPPORTED

method
get_anchor_prev_
supported
returning
value type flag

Specifies whether or not


the anchor tag supports a
Back action

X or
space

WML

GET_APP_LINKS_SUP
PORTED

method
get_app_links_su
pported
returning
value type flag

Specifies whether or not


you can call a local
application on a device
using a special link

X or
space

HTML

GET_APP_LINK_TYPE

method
t
li k t

Specifies what type of


li ti li k th d i

Web Application Server

620 SP 9

Possible
values

Conte
nt
type

Prio
.

HTML

268

SAP Online Help

25.10.2002

get_app_link_type
s
returning
value type string

application links the device


supports

GET_BACK_HARD_WI
RED [page 467]

method
get_back_hard_wi
red
returning
value type flag

Specifies whether or not


you can execute the Back
function using a fixed key
without an associated tag

X or
space

WML

GET_BACK_LABEL
[page 467]

method
get_back_label
returning
value type flag

Specifies whether or not a


label attribute must be
specified in the <do
type=prev> tag to display a
label

X or
space

WML

GET_BACK_TO_ANY_
URL_SUPPORTED

method
get_back_to_any_
url_supported
returning
value type flag

Specifies whether the <do


type=prev> tag can lead
to any Web address

X or
space

WML

GET_BIG_SUPPORTE
D

method
get_big_supported
returning
value type flag

Specifies whether or not


text can be formatted as
large

X or
space

WML

GET_BOLD_SUPPOR
TED

method
get_bold_supporte
d
returning
value type flag

Specifies whether or not


text can be formatted as
bold

X or
space

WML

GET_BREAKING_SPA
CE [page 468]

method
get_breaking_spa
ce
returning
value type string

Returns the smallest


character string for an
empty space

GET_BROWSER_CAT
EGORY [page 468]

method
get_browser_cate
gory
returning
value type string

Returns the browser


category

unknown
pocketie
avantgo
imode
palm
wap
epoc

GET_BROWSER_NAM
E [page 468]

method
get_browser_nam
e
returning
value type string

Returns the browser name

unknown
InternetExpl
orer
NetscapeN
avigator
mobile

GET_BROWSER_NAM
E [page 469]

method
get_browser_os
returning
value type string

Returns the operating


system running on the
device

unknown
HPUX
Linux
MacPPC
SunOS
Win32
mobile

GET_BROWSER_VER
SION

method
get_browser_versi
on
returning
value type int4

Returns the browser


version, for example 5.5

GET_CACHE_ENABLE
D_BY_DEFAULT

method
get_cache_enable
d b d f lt

Specifies whether or not


cache memory on the
b
i
ti t d b

Web Application Server

620 SP 9

X or
space

269

SAP Online Help

25.10.2002

D_BY_DEFAULT

d_by_default
returning
value type flag

browser is activated by
default

GET_CERTIFICATES_
SUPPORTED

method
get_certificates_s
upported
returning
value type flag

Specifies whether or not


the device supports client
certificates

GET_CHAR_HEIGHT
[page 467]

method
get_char_height
returning
value type int4

Returns the screen height


in rows

GET_CHAR_WIDTH
[page 469]

method
get_char_width
returning
value type int4

Returns the screen width in


characters

GET_COLOR_DEPTH

method
get_color_depth
returning
value type float

Returns the color depth, for


example 256 colors

GET_COLOR_SUPPO
RTED

method
get_color_support
ed
returning
value type flag

Specifies whether or not


the device has a color
screen

GET_CONTENT_TYPE

method
get_content_type
returning
value type string

Returns the content type,


for example HTML or WML

GET_CONTENT_TYPE
_VERSION

method
get_content_type_
version
returning
value type int2

Returns the version of the


content type for example,
3.2 for HTML 3.2 or 1.1 for
WML 1.1

GET_COOKIES_SUPP
ORTED [page 470]

method
get_cookies_supp
orted
returning
value type flag

Specifies whether or not


browser cookies are
supported

X or
space

GET_CSS_SUPPORT
ED [page 470]

method
get_css_supporte
d
returning
value type flag

Specifies whether or not


the browser supports CSSs
(Cascading Style Sheets).

X or
space

GET_CSS_VERSION

method
get_css_version
returning
value type int4

Returns the CSS version

GET_DEFAULT_ACTI
ON_DESIGN [page
470]

method
get_default_action
_design returning
value type string

Returns the default design


for user interface elements
representing an action

GET_DEFAULT_BLOC
K_SEPARATOR [page
471]

method
get_default_block
_separator
returning
value type string

Returns the default string


used to separate
paragraphs

Web Application Server

620 SP 9

X or
space

HTML

X or
space

HTML

HTML

HTML

link
button
softkey
linkAndSoft
key"

WML

270

SAP Online Help

25.10.2002

GET_DEFAULT_BULL
ET [page 472]

method
get_default_bullet
returning
value type string

Returns the default symbol


used to indicate points in a
list

GET_DEFAULT_FORM
_STYLE [page 472]

method
get_default_form_
style
returning
value type string

Returns the default display


type for input masks

onePage
menu
wizard

WML

GET_DEFAULT_MENU
_STYLE [page 473]

method
get_default_menu
_style
returning
value type string

Returns the default display


type for menus

selectionLis
t
linkList

WML

GET_DEVICE_CATEG
ORY [page 473]

method
get_device_categ
ory
returning
value type string

Returns the device


category

unknown
Phone
PDA
Voice
PC

GET_DEVICE_NAME
[page 474]

method
get_device_name
returning
value type string

Returns the device name


Unique ID for a set of
device properties

GET_DOM_SUPPORT
ED

method
get_dom_support
ed
returning
value type flag

Specifies whether or not


the browser supports a
Document Object Model
(DOM)

GET_DOM_VERSION

method
get_dom_version
returning
value type int4

Returns the Document


Object Model (DOM)
version supported

GET_EMPHASIZED_S
UPPORTED

method
get_emphasized_
supported
returning
value type flag

Specifies whether or not


text can be formatted as
highlighted

X or
space

GET_EMULATOR

method
get_emulator
returning
value type flag

Specifies whether or not


the device is to be
categorized as an emulator

X or
space

GET_FIELDSET_LAYO
UT [page 474]

method
get_fieldset_layou
t
returning
value type string

Specifies how input fields


that belong together are to
be laid out using the
<fieldset> tag

GET_FIELDSET_TITLE
_VISIBLE [page 475]

method
get_fieldset_title_v
isible
returning
value type
boolean

GET_FONT_PROPOR
TIONAL

method
get_font_proportio
nal
returning
value type flag

Web Application Server

WML

X or
space

HTML

HTML

WML

notSupporte
d
ignored
beneath
beneathWit
hIndent
sideBySide

WML

Specifies whether or not


the title attribute of the
<fieldset> tag is used as
label.

X or
space

WML

Specifies whether or not


the default font of the
device is a proportional font

X or
space

620 SP 9

271

SAP Online Help

25.10.2002

GET_FORM_FACTOR
[page 475]

method
get_form_factor
returning
value type string

Returns the screen format


of the device

PC
VGA
halfVGA
mediumLan
dscape
mediumPort
rait
phone
unknown

GET_FORM_MENU_S
UPPORTED [page 476]

method
get_form_menu_s
upported
returning
value type flag

Specifies whether or not


the browser supports the
technique of displaying a
selection menu with the
input mask

X or
space

WML

GET_FRAMES_SUPP
ORTED [page 476]

method
get_frames_suppo
rted
returning
value type flag

Specifies whether or not


frames are supported

X or
space

HTML

GET_GRAY_LEVEL

method
get_gray_level
returning
value type float

Returns the number of


shades of gray supported
in grayscale pictures

X or
space

GET_HORZ_SCROLLI
NG_SUPPORTED

method
get_horz_scrolling
_supported
returning
value type flag

Specifies whether or not


the device has a horizontal
scroll bar

X or
space

GET_HREF_WITH_PA
RAMS_SUPPORTED
[page 476]

method
get_href_with_par
ams_supported
returning
value type flag

Specifies whether or not an


Href attribute in a link can
contain URL parameters.

X or
space

WML

GET_HTTP_GET_SUP
PORTED

method
get_http_get_supp
orted
returning
value type flag

Specifies whether or not


the HTTP GET is
supported

X or
space

WML

GET_HTTP_POST_SU
PPORTED

method
get_http_post_sup
ported
returning
value type flag

Specifies whether or not


the HTTP POST is
supported

X or
space

WML

GET_IMAGE_ALIGNM
ENT_SUPPORTED

method
get_image_alignm
ent_supported
returning
value type flag

Specifies whether or not a


graphic can be aligned (left,
right, or centered)

X or
space

WML

GET_IMAGE_LINKS_S
UPPORTED [page 477]

method
get_image_links_s
upported
returning
value type flag

Specifies whether or not a


graphic can be used as
link.

X or
space

GET_IMAGE_SIZE_MA
X

method
get_image_size_
max
returning
value type float

Returns the maximum


memory size of a graphic

WML

GET_INPUT_FORMAT
DATE

method
get_input_format_

Returns the character


string used to format date

WML

Web Application Server

620 SP 9

272

SAP Online Help

25.10.2002

_DATE

date
returning
value type string

values

GET_INPUT_FORMAT
_NUMERIC

method
get_input_format_
numeric
returning
value type string

Returns the character


string used to format
numeric values

GET_INPUT_METHOD
_HAND_WRITING

method
get_input_method
_hand_writing
returning
value type flag

Specifies whether or not


the device supports
handwritten input

X or
space

GET_INPUT_METHOD
_KEYBOARD

method
get_input_method
_keyboard
returning
value type flag

Specifies whether or not


the device supports input
using a keyboard

X or
space

GET_INPUT_METHOD
_KEYPAD

method
get_input_method
_keypad
returning
value type flag

Specifies whether or not


the device supports input
using a telephone keypad

X or
space

GET_INPUT_METHOD
_KEYPAD_INTELL

method
get_input_method
_keypad_intell
returning
value type flag

Specifies whether or not


the device supports input
using T9 text input or
similar

X or
space

GET_INPUT_METHOD
_VOICE

method
get_input_method
_voice
returning
value type flag

Specifies whether or not


the device supports speech
input

X or
space

GET_INPUT_SHOWN_
WITH_CAPTION [page
477]

method
get_input_shown_
with_caption
returning
value type flag

Specifies whether or not


the browser uses the title
attribute of the <input> tag
is used as a label

X or
space

WML

GET_ITALIC_SUPPOR
TED

method
get_italic_support
ed
returning
value type flag

Specifies whether or not


text can be formatted as
talic

X or
space

WML

GET_JAVA_SUPPORT
ED

method
get_java_supporte
d
returning
value type flag

Specifies whether or not


the device supports the
Java programming
language

X or
space

HTML

GET_JAVA_VERSION

method
get_java_version
returning
value type int4

Returns the Java version


supported

GET_LINKS_SEPARA
TED [page 477]

method
get_links_separat
ed
returning
value type flag

Specifies whether or not


two consecutive links are
visibly separated

GET_LINK_DECORATI
ON [page 478]

method
get_link_decoratio
n

Returns the delimiters that


are automatically added to
the link text by the device

Web Application Server

620 SP 9

WML

HTML

X or
space

WML

WML

273

SAP Online Help

25.10.2002
n
returning
value type string

the link text by the device


for example [ ] or < >.

GET_LINK_TEXT_WID
TH [page 478]

method
get_link_text_widt
h
returning
value type int2

Returns the maximum


number of characters that a
link can have to fit into one
line.

GET_LOCAL_IMAGES
_SUPPORTED

method
get_local_images
_supported
returning
value type flag

Specifies whether or not


the device supports locally
stored graphics or symbols

X or
space

GET_LOCAL_VARIABL
ES_SUPPORTED

method
get_local_variable
s_supported
returning
value type flag

Specifies whether or not


the browser supports local
variables

X or
space

WML

GET_MARQUEE_LINK
_SUPPORTED [page
478]

method
get_marquee_link
_supported
returning
value type flag

Specifies whether or not a


long link can be displayed
in one line, for example as
a ticker-tape.

X or
space

WML

GET_MARQUEE_TEX
T_SUPPORTED [page
478]

method
get_marquee_text
_supported
returning
value type flag

Specifies whether or not a


long text can be displayed
in one line, for example as
a ticker-tape.

X or
space

WML

GET_MAX_LINK_LEN
GTH [page 479]

method
get_max_link_len
gth
returning
value type int4

Returns the maximum size


of the Href attributes of a
link.

GET_MEDIA_FORMAT
S [page 479]

method
get_media_format
s
returning
value type string

Returns the list of


multimedia formats
supported such as .agif
(animated .gif format), .gif,
.jpg, .png, .wbmp

GET_MEMORY

method
get_memory
returning
value type float

Returns the maximum


memory capacity of the
device

GET_MODEL

method get_model
returning
value type string

Returns the name of the


device type such as 7110
for the Nokia 7110 mobile
telephone

GET_NBSP_SUPPOR
TED [page 480]

method
get_nbsp_support
ed
returning
value type flag

Specifies whether or not


the device supports nonbreaking blank characters

X or
space

WML

GET_NESTED_TABLE
S_SUPPORTED [page
480]

method
get_nested_tables
_supported
returning
value type flag

Specifies whether or not


the browser supports
nested tables

X or
space

HTML

GET_NEWLINE_AFTE
R IMAGE [page 479]

method
get_newline_after

Specifies whether or not a


line break is inserted

X or
space

WML

Web Application Server

620 SP 9

WML

HTML

274

SAP Online Help

25.10.2002

R_IMAGE [page 479]

_image
returning
value type flag

automatically after an
<img> tag.

space

GET_NEWLINE_AFTE
R_INPUT [page 480]

method
get_newline_after
_input
returning
value type flag

Specifies whether or not a


line break is inserted
automatically after an
<input> tag on a specific
mobile device.

X or
space

WML

GET_NEWLINE_AFTE
R_LINK

method
get_newline_after
_link
returning
value type flag

Specifies whether or not a


line break is inserted
automatically after a link

X or
space

WML

GET_NEWLINE_AFTE
R_SELECT

method
get_newline_after
_select
returning
value type flag

Specifies whether or not a


line break is inserted
automatically after an
<select> tag.

X or
space

WML

GET_NEWLINE_BEFO
RE_IMAGE [page 481]

method
get_newline_befor
e_image
returning
value type flag

Specifies whether or not a


line break is inserted
automatically before an
<img> tag.

X or
space

WML

GET_NEWLINE_BEFO
RE_INPUT [page 481]

method
get_newline_befor
e_input
returning
value type flag

Specifies whether or not a


line break is inserted
automatically before an
<input> tag.

X or
space

WML

GET_NEWLINE_BEFO
RE_LINK [page 481]

method
get_newline_befor
e_link
returning
value type flag

Specifies whether or not a


line break is inserted
automatically before a link

X or
space

WML

GET_NEWLINE_BEFO
RE_SELECT

method
get_newline_befor
e_select
returning
value type flag

Specifies whether or not a


line break is inserted
automatically before an
<select> tag.

X or
space

WML

GET_NEWLINE_BETW
EEN_IMAGES [page
482]

method
get_newline_betw
een_images
returning
value type flag

Specifies whether or not a


line break is inserted
automatically after an
<image> tag

X or
space

WML

GET_NEWLINE_BETW
EEN_LINKS [page 482]

method
get_newline_betw
een_links
returning
value type flag

Specifies whether or not a


line break is inserted
automatically between two
<image> tags

X or
space

WML

GET_NEWLINE_BETW
_LINK_AND_TAG
[page 482]

method
get_newline_betw
_link_and_tag
returning
value type flag

Specifies whether or not a


line break is inserted
automatically between a
link and a tag

X or
space

WML

GET_OFFLINE_BROW
SING_SUPPORTED

method
get_offline_browsi
ng_supported
returning
value type flag

Specifies whether or not


the browser supports offline
browsing through locally
stored pages (that is,
cached pages)

X or
space

HTML

Web Application Server

620 SP 9

275

SAP Online Help

25.10.2002

GET_OFFLINE_FORM
S_SUPPORTED

method
get_offline_forms_
supported
returning
value type flag

Specifies whether or not


the browser allows the user
to fill out input forms offline
on the device

GET_PAGE_SIZE_MA
X [page 483]

method
get_page_size_m
ax
returning
value type float

Returns the maximum page


size that can be processed
in a mobile device.

GET_PIXEL_HEIGHT
[page 483]

method
get_pixel_height
returning
value type float

Specifies the screen height


in pixels.

GET_PIXEL_WIDTH
[page 483]

method
get_pixel_width
returning
value type float

Specifies the screen width


in pixels.

GET_REDIR_ABSOLU
TE_SUPPORTED

method
get_redir_absolute
_supported
returning
value type flag

Specifies whether or not


the browser supports the
redirection of an absolute
URL address.

X or
space

GET_REDIR_RELATIV
E_SUPPORTED [page
483]

method
get_redir_relative_
supported
returning
value type flag

Specifies whether or not


the browser supports the
redirection of a relative
URL address.

X or
space

GET_SCRIPT_SUPPO
RTED [page 488]

method
get_script_support
ed
returning
value type flag

Specifies whether or not


the browser supports
scripting

X or
space

GET_SCRIPT_VERSIO
N

method
get_script_version
returning
value type int4

Returns the script version


supported

GET_SECURE_PROT
OCOLS_SUPPORTED

method
get_secure_protoc
ols_supported
returning
value type flag

Specifies whether or not


the browser supports SSL
(Secure Socket Layer) or
WTLS (Wireless Transport
Layer Security)

GET_SECURE_PROT
OCOLS_NAMES

method
get_secure_protoc
ols_names
returning
value type string

Returns the names of the


security protocols
supported The names are
separated by semicolons

GET_SELECTION_ME
NU_SUPPORTED
[page 484]

method
get_selection_me
nu_supported
returning
value type flag

Specifies whether or not


the menu layout type
selectionList [page
473] is supported

X or
space

WML

GET_SETVAR_ON_EV
ENT_SUPPORTED

method
get_setvar_on_ev
ent_supported
returning
value type flag

Specifies whether or not


the <setvar> tag can be
used within the <onevent
type=onenterforward>
event handler

X or
space

WML

GET_SKIPPING_TO_I
NPUT [page 484]

method
get_skipping_to_i
nput

Specifies whether or not


the browser automatically
skips to the first <input> tag

X or
space

WML

Web Application Server

620 SP 9

X or
space

HTML

X or
space

276

SAP Online Help

25.10.2002
nput
returning
value type flag

skips to the first <input> tag


and displays a screen
extract starting from this
tag

GET_SMALL_SUPPOR
TED

method
get_small_support
ed
returning
value type flag

Specifies whether or not


text can be formatted as
small

GET_SOFTKEY_NUM
[page 484]

method
get_softkey_num
returning
value type int1

Returns the number of


Soft Keys [page 467]
supported by the device

GET_SOFTKEY_STYL
E1 [page 485]

method
get_softkey_style1
returning
value type string

Specifies how soft key 1 is


displayed on the screen

GET_SOFTKEY_STYL
E2 [page 486]

method
get_softkey_style2
returning
value type string

Specifies how soft key 2 is


displayed on the screen

GET_SOFTKEY_TITLE
_WIDTH [page 487]

method
get_softkey_title_
width
returning
value type int2

Returns the number of


displayed characters for a
soft key title.

GET_SOUND_SUPPO
RTED

method
get_sound_suppor
ted
returning
value type flag

Specifies whether or not


the device can play sounds

X or
space

HTML

GET_STRONG_SUPP
ORTED

method
get_strong_suppo
rted
returning
value type flag

Specifies whether or not


text with the <strong>can
be formatted as
highlighted

X or
space

WML

GET_SUBMIT_ONEVE
NT_SUPPORTED

method
get_submit_oneve
nt_supported
returning
value type flag

Specifies whether or not


Submit is supported
within the <onevent
type=onenterforward>
event handler

X or
space

GET_SUB_CATEGOR
Y [page 488]

method
get_sub_category
returning
value type string

Allows you to split devices


into different subcategories

Any text

GET_TABLE_HAS_BO
RDERS [page 488]

method
get_table_has_bor
ders
returning
value type flag

Specifies whether or not


tables are displayed with
gridlines

X or
space

GET_TABLE_SUPPOR
TED [page 489]

method
get_table_support
ed
returning
value type flag

Specifies whether or not


the browser supports tables
with several columns

X or
space

GET_TELEPHONY_LI
NKS_SUPPORTED
[page 490]

method
get_telephony_lin
ks_supported
returning

Specifies whether or not a


telephone can be dialed
directly using a link

X or
space

Web Application Server

620 SP 9

X or
space

WML

WML

notShown
key
menu
screen

WML

notShown
key
menu
screen

WML

WML

277

SAP Online Help

25.10.2002
value type flag

GET_TEXT_ALIGNME
NT_SUPPORTED

method
get_text_alignmen
t_supported
returning
value type flag

Specifies whether or not


text within a paragraph can
be aligned left, right, or
centered

X or
space

WML

GET_TEXT_STYLES_
SUPPORTED [page
490]

method
get_text_styles_su
pported
returning
value type flag

Specifies whether or not


the browser can format text
using tags such as <b> or
<small>

X or
space

WML

GET_TITLE_SUPPOR
TED [page 490]

method
get_title_supporte
d
returning
value type flag

Specifies whether or not a


label is to appear on the
top of the screen using the
title property of the
<card> WML tag.

X or
space

WML

GET_TITLE_WIDTH
[page 491]

method
get_title_width
returning
value type int2

Returns the maximum


number of characters of the
title

GET_UNDERLINE_SU
PPORTED

method
get_underline_sup
ported
returning
value type flag

Specifies whether or not


text can be formatted as
underlined

GET_USER_AGENT
[page 492]

method
get_user_agent
returning
value type string

Equivalent to the HTTP


request header userAgent

GET_VARS_ACROSS_
CARD_SUPPORTED

method
get_vars_across_
card_supported
returning
value type flag

Specifies whether or not


browser variables passed
to a card can also be used
for different cards

GET_VENDOR

method
get_vendor
returning
value type string

Returns the manufacturers


name

GET_XSL_SUPPORTE
D

method
get_xsl_supported
returning
value type flag

Specifies whether or not


the browser supports
Extensible Stylesheet
Language (XSL)

GET_XSL_VERSION

method
get_xsl_version
returning
value type int4

Returns the XSL version


supported

X or
space

WML

X or
space

WML

X or
space

HTML

HTML

Global Objects
Certain global objects can be accessed from all parts of a BSP (initialization, layout, input
processing). For example, the request and response object, the application object (if an
application class was defined for the BSP application), the navigation object, and the runtime
object, can be accessed.
The following global objects are available:

Web Application Server

620 SP 9

278

SAP Online Help

Object application [page 279]

Object navigation [page 280]

Object messages [page 282]

Object runtime [page 281]

Object request [page 282]

Object response [page 282]

Object page [page 283]

Object page context [page 284]

25.10.2002

This is described in more detail below.

The objects and their signatures for the individual event handlers [page 213] are
displayed if you choose

in the Web Application Builder.

Example:

Object application
Definition
The object application refers to the application class [page 207] of a BSP application.
See also:

Class CL_BSP_APPLICATION [page 226]

Interface IF_BSP_APPLICATION [page 240]

Web Application Server

620 SP 9

279

SAP Online Help

25.10.2002

Integration
This object is only available if an application class was defined for the BSP application. If so,
the methods defined there can be accessed.

Do not set parameters for the constructor.

Object navigation
Definition
The object navigation has the same type as interface IF_BSP_NAVIGATION [page 248].
The following methods are available for navigation between BSP pages. They collect
information required for the presentation of the subsequent page. After the subsequent is
navigated to, the navigation object is deleted.
The class contains methods which are used to determine the characteristics of the
subsequent page, and methods which can be used for transferring parameters between
pages.

Methods for Constructing the Subsequent Page


next_page
When called, this method determines the subsequent page from the navigation structure.

navigation->next_page( 'TOORDER' ).
This call triggers a search for the navigation request TOORDER in the navigation
structure of the BSP application, and the subsequent page is opened.

goto_page
When this method is called, the URL of the page that is to be navigated to next is displayed.

navigation->goto_page( 'error.htm' ).

exit
This method ends the current session in the active application and navigates to the given
URL. If no exit URL is given, the exit URL of the BSP application is used.

navigation->exit( exit_url = 'http://www.sap.com' ).

call_application
You can use this method to navigate to a page (specified by the URL) in another application.
If the BSP application in which the method was called is running in stateful mode, the current
context is maintained. The foreign application receives the URL as a parameter.

Web Application Server

620 SP 9

280

SAP Online Help

25.10.2002

Methods for Transferring Parameters to the Subsequent Page


A page can transfer parameters to a subsequent page. The following methods exist for this
purpose.

set_parameter
Using the call
navigation->set_parameter( name='myparameter' value = myvalue ).
you can set the page parameter myparameter to the value myvalue. This value can then
be used for processing in the subsequent page.
If the form field (in the layout part) and the page parameter are of the type string and are
specified by the same name (in this case, myparameter), the following abbreviation can be
used:
navigation->set_parameter( 'myparameter' ).

get_parameter
You can use this method to obtain the value of a parameter.

This method is not recommended for BSP applications. It is used when the users
own HTTP request handlers are implemented.

has_parameters
This method returns 1 if at least one parameter was specified. Otherwise, the method returns
0.

Object runtime
Definition
The runtime object refers to the interface IF_BSP_RUNTIME [page 262]. The following
attributes can be set:

runtime->keep_context

0: stateless mode

1: stateful mode

See also:

Stateful and Stateless BSP Applications [page 381]

A Sample BSP Application [page 391]

Web Application Server

620 SP 9

281

SAP Online Help

25.10.2002

Object request
Definition
The request object is of the type IF_HTTP_REQUEST [page 119]. This interface contains the
interface IF_HTTP_ENTITY.
The methods are explained in the section IF_HTTP_ENTITY [page 121].

Object response
Definition
The request object is of the type IF_HTTP_REQUEST [page 119]. This interface contains the
interface IF_HTTP_ENTITY.
The methods are explained in the section IF_HTTP_ENTITY [page 121].

Object messages
Definition
The object messages is the same type as the class CL_BSP_MESSAGES [page 226]. This
object is a message contained and outputs different types of error messages. It contains a list
of error messages with details of severity, condition, and the corresponding text.

Use
You use the object to handle users incorrect entries in BSP applications. For more
information see Handling Incorrect Input [page 434].
An entry is made in the list if syntax errors occur in automatic page attributes, for example,
when the entry cannot be converted to a specific format. The attribute name must be
available.
You can add additional entries to the messages object during input processing [page 216].
Texts and conditions are user-definable in this case.

Structure
The following methods are available:

NUM_MESSAGES
This method returns the number of messages when it is called.

ADD_MESSAGE
This method adds a single message when it is called.

GET_MESSAGE
This method returns the requested message when it is called.

ASSERT

Web Application Server

620 SP 9

282

SAP Online Help

25.10.2002

This method returns the message index for a specific condition or 0 when it is called.

ASSERT_SEVERITY
This method returns the severity of the error for a specific condition or 0 when it is
called.

ASSERT_MESSAGE
This method returns the message for a specific condition or an empty string when it is
called.

The conditions specify the message types or error levels. The following error levels are
available:
Attribute Name

Initial Value

Description of Error Level

CO_SEVERITY_ERROR

Normal error

CO_SEVERITY_FATAL_ERROR

Fatal error

CO_SEVERITY_INFO

Information

CO_SEVERITY_SUCCESS

Success message

CO_SEVERITY_WARNING

Warning

The messages are grouped together in a table (attribute M_MESSAGES).

Example
There is an example showing the use of this object in the SAP System in the BSP application
bsptutorialmessages, in the package SBSP_DOCU.

Object page
Definition
The object page accesses information about a BSP. It is the same type as class
CL_BSP_PAGE or the interface IF_BSP_PAGE [page 254]

Structure
The following methods are the most important:
Method

Use in Source Code

Output (Example)

get_page_name

<%= page->get_page_name( )
%>

basic_page_object.htm

get_page_url

<%= page->get_page_url( ) %>

/sap(bD1kZQ==)/bc/bsp/sap/it00/bas

get_application_namespace

<%= page>get_application_namespace(
) %>

sap

get_application_name

<%= page>get_application_name( ) %>

it00

get_application_url

<%= paget
li

/sap(bD1kZQ==)/bc/bsp/sap/it00

Web Application Server

620 SP 9

ti

l( ) %
283

SAP Online Help

25.10.2002
>get_application_url( ) %>

get_application_theme

<%= page>get_application_theme( ) %>

SAP_DEFAULT

get_application_start_page

<%= page>get_application_start_page(
) %>

default.htm

Object page_context
Definition
Based on the interface IF_BSP_PAGE_CONTEXT [page 266], the page context object
provides information that is sent to all BSP elements.

This object is not used in the BSPs themselves, but only in connection with BSP
extensions [page 284] or elements.

BSP Extensions
Introduction
The BSP programming model, which is based on the server pages technology, provides
developers with additional scope regarding the HTML coding that they can create, from an
empty page right up to complex applications. However, repeatedly creating complex HTML
coding is often a lengthy process that can easily result in errors. As an example, a simple
HTML pushbutton can be implemented very easily: <input id=btn type=submit>. If you
now start to use additional styles and other attributes for the size and the status of the button,
the original simple HTML coding becomes considerably more complex and unclear. Here an
abstraction technology can be used to express both the syntax and the semantics of a
specific section of HTML coding simply. This mechanism is structured so that it can also be
used by other types of BSPs, XML, WML and so on. With this technology you call them BSP
extensions.
A BSP extension contains a collection of BSP elements. In the BSP context, each element is
assigned to an ABAP class to represent the element functionality, which the generation of the
HTML coding usually contains. Defining the elements and mapping them to the ABAP classes
is so flexible that you can use this technology to solve many additional problems and
difficulties.
SAP provides an infrastructure that developers can use to implement BSP extensions within
BSP applications. SAP delivers a set of predefined extensions such as HTML Business for
BSP (htmlb), which are available and can be used in every SAP Web Application Server
6.20 system. In addition you can define your own extensions to meet specific requirements.

Web Application Server

620 SP 9

284

SAP Online Help

25.10.2002

You can create these using an editor that is integrated in the development environment
(Transaction SE80).
You include an extension in a BSP using the extension directive [page 225].
For more information see Creating Your Own BSP Extensions [page 293].

You can also create composite elements [page 314] to facilitate layout changes
with complicated BSP applications.

BSP Extensions and BSP Elements


Each BSP extension consists of a collection of BSP elements. Each element has specific
attributes and is assigned to an ABAP class. The usual notation for XML elements is used
when elements are written to BSPs. The attributes available in the element are used as input
parameters for the ABAP class that is assigned to the element.

You can define a simple pushbutton on a BSP as follows, for example:


<htmlb:button id=btn1 text=Hit Me! />
Here htmlb is the XML namespace, button is the element and id and text
are attributes. If the BSP compiler sees the element, it generates the following
pseudocode.
data: btn1 type ref to CL_HTMLBL_BUTTON.
create object btn1.
btn1->writer = current_output_writer.
btn1->id = btn1.
btn1->text = Hit Me!.
btn1->begin_tag( ).
btn1->end_tag( ).
The element class writes the HTML to the HTML output stream based on the
functionality that the element provides. This is based on the assumption that all
elements in an extension support a common output style.

In the sample pushbutton above, the start tag is followed immediately by the end tag. No body
components whatsoever are available or required (by the pushbutton). For other examples, it
may be useful to manipulate the body or to process more detailed input.

A typical element, for example, could be an HTML link for creating a small text
segment. In this case, the element has a body, which is first rendered in a string
and then passed as a parameter to the element for further processing.
<htmlb:link id=link1 reference=http://www.sap.com>
Homepage of the e-company!
</htmlb:link>
This results in:

The link element takes the Internet address as the reference. Furthermore, the
link element provides formatting based on the style that is provided by the BSP
extension. The body is used as input for the element.

Web Application Server

620 SP 9

285

SAP Online Help

25.10.2002

Even if using elements and their resulting ABAP class calls seems to be fairly complex for this
type of simple HTML element, using and supporting BSP extensions provides several
advantages that should not be underestimated:

The standard XML syntax that is used can be parsed and checked during the BSP
compile time.

The returned HTML coding need only be generated once (by an expert) in the ABAP
element class, thereby ensuring that the coding is correct.

The element class can contain additional logic for generating browser-dependent HTML
code.

The HTML coding that is generated contains correct references to the style sheets that
are available.

In addition to a BSP extension for standard HTML elements such as pushbuttons, input fields,
dropdown lists and so on, you can also implement highly specialized extensions.

For example, you could develop an extension to map a companys corporate


identity to an HTML page. In this case, the users coding for this extension, for
example, could be as follows:
<%@extension name=SAP_Corporate_Identity_Extension
prefix=corp %>
<corp:logo/>
<corp:stock_ticker/>
This could look as follows on the HTML page:

Examples
Different examples of BSP applications that use BSP extensions are available in the system.
You can find simple examples of using BSP extensions HTMLB and XHTMLB in the BSP
applications SBSPEXT_HTMLB and SBSPEXT_XHTMLB, and further examples in BSP
extension HTMLB_SAMPLES.

As part of the tutorials for creating Web applications with BSP, a Tutorial for a
Small Online Bookshop [External documentation] is also available, whose layout
is implemented using HTMLB.
The following sections provide two simple examples of the HTMLB elements button and
tableView:
Button [page 287]
TableView [page 288]

Web Application Server

620 SP 9

286

SAP Online Help

25.10.2002

Button
You can find this example in the system under BSP application SBSPEXT_HTMLB, page
button.bsp (package SBSPEXT_HTMLB).

Layout
<%@page language="abap"%>
<%@ extension name="htmlb" prefix="htmlb"%>
<htmlb:content>
<htmlb:page title = "BSP Extension: HTMLB / Element: Button">
<htmlb:form>
<htmlb:button
text

id

= "myButton1"

= "standard"

/>
<br><br>
<htmlb:button
text

id

= "myButton2"

= "Emphasized button"

tooltip

= "button quick info: Please click me"

onClick

= "MyButtonClick"

design

= "emphasized"

/>
<br><br>
<htmlb:button
text

id

= "Small button with fixed size "

tooltip

= "button tooltip: Please click me"

onClientClick
design
width

= "myButton3"

= "alert('myButton3 Clicked')"

= "small"
= "300"

/>
</htmlb:form>
</htmlb:page>
</htmlb:content>

Web Application Server

620 SP 9

287

SAP Online Help

25.10.2002

OnInputProcessing
CLASS CL_HTMLB_MANAGER DEFINITION LOAD.
* Optional: test that this is an event from HTMLB library.
IF event_id = CL_HTMLB_MANAGER=>EVENT_ID.
* Scenario 1: Read event from manager.
DATA: event TYPE REF TO CL_HTMLB_EVENT.
event = CL_HTMLB_MANAGER=>get_event( runtime->server->request ).
IF event->name = 'button' AND event->event_type = 'click'.
DATA: button_event TYPE REF TO CL_HTMLB_EVENT_BUTTON.
button_event ?= event.
ENDIF.
* Scenario 2: Dispatch event directly onto event class
DATA: event_handler TYPE REF TO CL_HTMLB_EVENT_EXAMPLE.
CREATE OBJECT event_handler.
CL_HTMLB_MANAGER=>dispatch_event(
request
= runtime->server->request
event_handler = event_handler
page_context = page_context
).
ENDIF.

Output

TableView
You can find this example in the system under BSP application SBSPEXT_HTMLB, page
TableView.bsp (package SBSPEXT_HTMLB).

Web Application Server

620 SP 9

288

SAP Online Help

25.10.2002

Layout
<%@page language="abap"%>
<%@ extension name="htmlb" prefix="htmlb"%>
<htmlb:content>
<htmlb:page title = "BSP Extension: HTMLB / Element: tableView">
<htmlb:form>
<htmlb:tableView id
headerText
headerVisible
design
visibleRowCount
fillUpEmptyRows
onHeaderClick
onRowSelection
selectionMode
table

=
=
=
=
=
=
=
=
=

= "tv1"
"Connections"
"true"
"alternating"
"8"
"true"
"MyEventHeaderClick"
"MyEventRowSelection"
"multiselect"
"<%=sflight%>" >

<htmlb:tableViewColumns>
<htmlb:tableViewColumn columnName
= "carrid"
wrapping
= "true"
width
= "100"
onCellClick
= "MyCellClickCarrid__"
horizontalAlignment="center"
title
= "&nbsp;"
type
= "user" >
<htmlb:textView id="$TVCID$"
text
= "$TVCVALUE$"
design
= "LABELSMALL"
layout
= "PARAGRAPH"
required
= "TRUE"
width
= "100%"
tooltip
= "$CARRNAME$"
encode
= "FALSE"
wrapping
= "TRUE" />
</htmlb:tableViewColumn>
<htmlb:tableViewColumn columnName
= "myicon"
type
= "user"
title
= "Image"
horizontalAlignment="center" >
<htmlb:link
id
= "$TVCID$"
onClick
= "$CARRNAME$"
tooltip
= "$CARRNAME$">
<htmlb:image
src
= "$TVCVALUE$"
alt
= "$TVCVALUE$"
tooltip
= "$CARRNAME$" />
</htmlb:link>
</htmlb:tableViewColumn>
<htmlb:tableViewColumn columnName
= "myinputfield"
type
= "user"
title
= "Input Field"
cellInvalidKey
= "invalid"
cellDisabledKey = "disabled"
horizontalAlignment="center" >
<htmlb:inputField
id
= "$TVCID$"
width
= "100%"
value
= "$myinputfield$"
Web Application Server

620 SP 9

289

SAP Online Help

25.10.2002

type
showHelp
firstDayOfWeek
</htmlb:tableViewColumn>

= "Date"
= "true"
= "2" />

<htmlb:tableViewColumn columnName
= "mybutton"
type
= "button"
title
= "Button"
cellDesignKey
= "design"
onItemClick
= "MyButton__"
horizontalAlignment="center" />
<htmlb:tableViewColumn columnName
= "fldate"
onCellClick
= "MyCellClickFldate__"
title
= "Datum"
wrapping
= "true"
width
= "100"
horizontalAlignment="center" />
<htmlb:tableViewColumn
columnName
= "DDLKEY"
title
= "User defined: List Box"
type
= "user" >
<htmlb:dropdownListBox id
= "$TVCID$"
table
= "<%=sflight%>"
nameOfKeyColumn
= "DDLKEY"
nameOfValueColumn = "CARRNAME" />
</htmlb:tableViewColumn>
<htmlb:tableViewColumn
columnName
title
= "Link"
type
= "link"
linkColumnKey
= "linkcarrid"
linkClickTarget
= "_blank"/>
<htmlb:tableViewColumn
onItemClick
title
type
linkColumnKey

= "linktextid"

columnName="linkstextid"
= "MyLink__"
= "Link with Handler"
= "link"
= "linkcarrid"/>

<htmlb:tableViewColumn columnName="linkid"
horizontalAlignment = "center"
type
= "imagelink"
linkColumnKey
= "linkcarrid"
linkClickTarget
= "_blank"
title
= "ImageLink" />
</htmlb:tableViewColumns>
</htmlb:tableView>
</htmlb:form>
</htmlb:page>
</htmlb:content>

Attributes
Attribute
rowSelection

Web Application Server

Auto

Typing Type

Reference Type

TYPE

STRING

620 SP 9

290

SAP Online Help

25.10.2002

rowSelectionEvent

TYPE

STRING

sflight

TYPE

MYSFLIGHT

OnInitialization
* event handler for data retrieval
data:

wa
name
value
str
scol
srow
id
mod
sytabix
sflightlink

like line of sflight,


type string,
type string,
type string,
type string,
type string,
type string,
type i,
type sytabix,
type table of sflightlink.

field-symbols: <wa>
like line of sflight,
<waLink> type sflightlink.
select * from sflight into corresponding fields
of table sflight.
select * from sflightlink into table sflightlink.
loop at sflight assigning <wa>.
sytabix = sy-tabix.
read table sflightlink assigning <waLink> with key carrid = <wa>carrid.
<wa>-LINKCARRID

= <waLink>-HTTPLINK.

<wa>-linktextid

= <waLink>-CARRNAME.

<wa>-linkstextid

= <waLink>-CARRNAME.

<wa>-myinputfield = sy-cdate. "<wa>-FLDATE


<wa>-mybutton

= <waLink>-CARRNAME.

<wa>-FLOATT

= 2000000.

str = <wa>-FLDATE.
concatenate <wa>-CARRID <wa>-CONNID str into <wa>-DDLKEY.
str = page->to_string( value = <wa>-FLDATE ).
concatenate <waLink>-CARRNAME ' (' <wa>-CONNID '/' str ')' into <wa>CARRNAME.
if <wa>-carrid eq 'AA'.
<wa>-linkid = '../HTMLB_SAMPLES/aa.gif'.
else.
concatenate '../HTMLB_SAMPLES/' <waLink>-CARRNAME '.gif'
into <wa>-linkid.
endif.
mod = sytabix mod 8.

Web Application Server

620 SP 9

291

SAP Online Help

25.10.2002

case mod.
when 0.

<wa>-myicon = 'ICON_WF_WORKITEM_READY'.

when 1.

<wa>-myicon = 'ICON_WF_WORKITEM_RESERVED'.

when 2.

<wa>-myicon = 'ICON_WF_WORKITEM_STARTED'.

when 3.

<wa>-myicon = 'ICON_WF_WORKITEM_COMMITTED'.

when 4.

<wa>-myicon = 'ICON_WF_WORKITEM_WAITING'.

when 5.

<wa>-myicon = 'ICON_WF_WORKITEM_COMPLETED'.

when 6.

<wa>-myicon = 'ICON_WF_WORKITEM_ERROR'.

when 7.

<wa>-myicon = 'ICON_WF_WORKITEM_CANCEL'.

endcase.
mod = sytabix mod 5.
case mod.
when 0.

<wa>-invalid = 'X'.

<wa>-disabled = 'X'.
when 1.

<wa>-disabled = 'X'.

when 2.

<wa>-invalid = 'X'.

endcase.
mod = sytabix mod 3.
case mod.
when 0.

<wa>-design = 'STANDARD'.

when 1.

<wa>-design = 'EMPHASIZED'.

when 2.

<wa>-design = 'SMALL'.

endcase.
endloop.

OnInputProcessing
* event handler for checking and processing user input and
* for defining navigation
CLASS CL_HTMLB_MANAGER DEFINITION LOAD.
* Optional: test that this is an event from HTMLB library.
IF event_id = CL_HTMLB_MANAGER=>EVENT_ID.
* Scenario 1: Read event from manager.
DATA: event TYPE REF TO CL_HTMLB_EVENT.
event = CL_HTMLB_MANAGER=>get_event( runtime->server->request ).

Web Application Server

620 SP 9

292

SAP Online Help

25.10.2002

IF event->name = 'tableView'.
DATA: tableview_event TYPE REF TO CL_HTMLB_EVENT_TABLEVIEW.
tableview_event ?= event.
ENDIF.
* Scenario 2: Dispatch event directly onto event class
DATA: event_handler TYPE REF TO CL_HTMLB_EVENT_EXAMPLE.
CREATE OBJECT event_handler.
CL_HTMLB_MANAGER=>dispatch_event(
request
= runtime->server->request
event_handler = event_handler
page_context = page_context
).
ENDIF.

Output

Defining Your Own BSP Extension


BSP Extensions and BSP Elements
With the BSP extension concept, you can develop your own tags for dynamic pages of BSP
applications.
A BSP extension is represented by means of a special development object in the workbench.
This object includes a record of related BSP elements with the corresponding attributes, and it
also covers references to the appropriate element handler classes. Each BSP element has an
element handler class assigned to it that implements its specific functions.

Web Application Server

620 SP 9

293

SAP Online Help

BSP Application

25.10.2002

BSP Extension

Pages

BSP Elements

Element Handler Classes

The figure below [page 295] explains these connections with a relatively simple
example.

Advantages for Using BSP Elements

Reduces the complexity of the BSP pages.


The encapsulation of the functions into BSP elements can contribute greatly to
reducing the script part in BSP pages.

Reuse
Generally speaking, a BSP element can be used by each BSP page.

Clear-cut role distribution


As a developer, you define the BSP extensions and implement the respective
element handler classes; as a designer, on the other hand, you use the BSP
elements in the page layout of BSP applications.

Tool support within the workbench by the BSP extension editor

Tool Support
In addition to the usual infrastructure (transport, where-used list, and so on), the workbench
provides the following functions in order to ensure efficient processing of BSP extensions:

Creating and editing BSP extensions


In the Object Navigator (SE80), you first create a BSP extension as a new
development object. Then you create one or several BSP elements and declare the
individual element attributes.

Generating the element handler class


For each BSP element, you can generate a corresponding element handler class and
its basis class in the Class Builder.

Integration in the Tag Browser

Web Application Server

620 SP 9

294

SAP Online Help

25.10.2002

Through activation, each new BSP extension is copied, without additional effort, as
an entry into the Tag Browser in SE80. On the BSP application pages, you can then
place the corresponding tags and their attributes wherever you want them in the
editor using Drag&Drop. See also: Using BSP Extensions [page 312].

Process Flow
Complete implementation of a BSP extension takes place in the following steps:
1. Creating a BSP Extension [page 296]
2. Defining the Corresponding BSP Elements [page 297]
3. Implementing the Element Handler Class [page 307]
4. Activating the BSP Extension [page 306]
5. Entering Documentation [page 311]

BSP Extension Framework


In the following example, a BSP page uses the elements of the BSP extension myExtension.
All the BSP elements in this extension are identified, in this case, by the prefix ext.
The BSP elements are defined within the Workbench using the BSP extension editor. Here,
the BSP extension was created as a container for the corresponding elements. In addition,
specific attributes can be assigned to each element.
The specific functions of a BSP element are implemented with the help of a global element
handler class myElementClass in the Class Builder.

Web Application Server

620 SP 9

295

SAP Online Help

25.10.2002

<%@ extension name="myExtension" prefix="ext" %>

BSP Page

...
<ext:doSomething

attr_1 = "..."
...
attr_n = "..."/>

...

Extension:

myExtenion

Element:

...

Element:

doSomething ( attr_1| ...| attr_n )

Definition:
BSP Extension

...

Class:

myElementClass

Attributes:

... | attr_1|...|attr_n

Methods:

doAtBeginng

Element Handler Class

...

Creating BSP Extensions


Use
Whenever you wish to define and implement your individual tags for Business Server Pages,
you first need a BSP extension as a separate workbench. This object then serves as a
container for several BSP elements, as a rule.

Procedure
To create a new BSP extension:
1. Open the Object Navigator (transaction: SE80).

Alternatively (to steps 1-4), you can create a new BSP extension by selecting the
Create function from the context menu of a BSP extension that already exists within
an object list.

Web Application Server

620 SP 9

296

SAP Online Help

25.10.2002

2. Choose the BSP Extension category from the object list selection and enter a name for
the BSP extension you want to create.
3. Click the

button or press ENTER.

The system checks whether a BSP extension with the specified name already exists
in the R/3 System. If there is none, the Create Object dialog box appears.
4. Choose Yes to create the BSP extension.
The system displays the Create BSP Extension dialog box.
5. Enter the default prefix without blanks or other special characters and also a meaningful
description for the BSP extension as a short text.

The default prefix is a prefix that is entered into the BSP page in the standard version
during Drag&Drop of the extension or one of your BSP elements from the Tag
Browser [page 421] into the BSP page Within a particular page, the prefix references
the corresponding BSP extension that is assigned through the extension directive.
The predefined default prefix can be overwritten on the page of the BSP application
by renaming the prefix attribute for the extension directive.
6. Choose

Continue to confirm your entries.

The system displays the Object Directory Entry dialog box.


7. Assign a package.
The new BSP extension is copied into the object list of the package.

Result
With the new BSP extension, you create a separate development object in the R/3 Repository
that appears in inactive status in your worklist.
You can now create one or several BSP elements [page 297] for this BSP extension and
declare the appropriate element attributes.

Defining BSP Elements


Use
You create individual elements for a BSP extension and these are inserted later on as tags in
BSP pages. Each BSP element has a handler class assigned to it that implements its specific
functions. Also, you can create and declare attributes for each BSP element.

Prerequisites
The BSP extension already exists.

Procedure
Creating BSP Elements
1. Choose the required BSP extension from the object list.
2. Choose the function Create BSP Element from the context menu.
The system displays the Create BSP Element dialog box.

Web Application Server

620 SP 9

297

SAP Online Help

25.10.2002

3. Enter the name of the BSP element, a valid name for the Element Handler Class, and a
meaningful description for the BSP extension as a short text.

You can specify an existing, valid ABAP class as the element handler class. A valid
class must support the interface IF_BSP_ELEMENT.
We recommend that you derive this class from the automatically-generated basis
class [page 307](Z)CLG_<name of BSP extension>_<name of BSP
elements>. This basis class already contains a standard implementation of the
interface methods and is automatically updated whenever changes are made to the
element data.
As a rule, you enter the name of a non-existing class as the element handler class
into the respective input field. Then you have this generated, together with the
corresponding basis class.
4. Choose

Continue to confirm your entries.

The properties of the created BSP element are displayed in the editor.

Defining Attributes of the BSP Element


You can enhance the definition of a BSP element with a series of attributes. On the one hand,
you can change the element content from the standard value. On the other hand, it is possible
to access the element content through Further Options for the element and change it, thus
influencing the flow logic.
For more details, refer to the section:

Defining Element Content [page 299].

Furthermore, you have the following options available to you:

User-Defined Validation [page 301]

Iteration Through Element Content [page 303]

Manipulation of the Element Content [page 304]

Declaring Attributes for a BSP Element


To create attributes for a BSP element, choose the Attributes tab in the element view and, if
necessary, switch to change mode.
To create and declare an attribute, make the following specifications:

Attribute

In this column, enter a name that uniquely identifies the


attribute.
After you have activated the BSP extension [page 306] ,
the system generates a public attribute with the same
name in the basis class (CLG_* or ZCLG_*).

Required

By setting this flag, you define that the attribute must be


defined whenever the BSP element is used in a BSP
page.

Dynamic value allowed

By setting this flag, you define that the value of the


attribute in a BSP page may also be specified
dynamically through a BSP expression (<%= ...%>).
Otherwise, only static values are possible in the form of
a string.

Pass by reference

By setting this flag, you define that the attribute is


passed to the event handler class as a reference.
Otherwise, no value is passed.

Web Application Server

620 SP 9

298

SAP Online Help

25.10.2002

For more information, refer to the section Pass by


Reference for Attributes [page 305].

Kind of typing

You have at your disposal the two types TYPE and


TYPE REF TO, depending on whether you have data or
object references.
Note that the selection TYPE REF TO is only
appropriate in combination with the active option
Dynamic Value Allowed. The reason for this is that
object references in BSP pages can only be passed with
the help of BSP expressions, not statically in the form of
a string.

Reference type

As reference type, you can use the elementary ABAP


types (however, no generic types) or object types
(classes and interfaces). Generic types such as C, N, X,
P, and so on are not allowed because generically-typed
attributes are not allowed in ABAP classes either. There
is a 1:1 relationship between the attributes of the BSP
element and the class attributes.

Default value

Here you always enter a value if the attribute is to be


predefined with a value. This value is copied from the
Tag Browser into the BSP page when you insert the
attribute or the entire BSP element.

Description

Here you enter an explanatory attribute description.

The specifications marked with X are absolutely mandatory for each attribute.

Result
The new BSP element is assigned as a subobject to the BSP extension and copied inactive
into the object list.
With the new BSP element, the basis class (Z)CLG_<name of BSP extension>_<name
of BSP elements> is automatically created itself, and possibly also the specified element
handler class, provided this does not yet exist.
Also, you have specified the BSP element behavior at runtime through further properties, and
have also declared the corresponding attributes. In the next workstep, you can activate the
BSP extension [page 306]

Defining the Element Content


In general, BSP elements have a particular content. This means that the resulting tags consist
of a start and an end tag, and between these two there are either further (embedded) tags,
script elements, or even simply just text. By selecting the option for the Element Content in
the attribute display of the BSP element, you can define whether content should be
embedded in the element or not, and if so which content.
The display options comprise the following:

Empty

Web Application Server

620 SP 9

299

SAP Online Help

25.10.2002

You select this option if the BSP element is not to have any content.

Example: Input field from the BSP extension HTMLB


<ui:inputField id="myID" value="" />
or
<ui:inputField id="myID" value="" > </ui:inputField >

Solely BSP Elements


By selecting this option, you define that the BSP element is only to contain further
BSP elements. Any existing HTML part will be ignored by the runtime
environment. This reduction enables you to achieve performance optimization
during runtime.

Example: Tree element from HTMLB


<ui:tree id="myTREE">
<ui:treeNode id="ROOT" text="Root node">
<ui:treeNode id="N1" text="Node 1"/>
<ui:treeNode id="N2" text="Node 2"/>
</ui:treeNode>
</ui:tree>

BSP Elements and Static HTML


This element can include both further BSP elements as well as any HTML part.

Example: Form element from HTMLB


<ui:form id="myFormID" method="POST">
<ui:inputField id="myID" value="" size="24"/>
<br> <br>
Some Text ...
<a HREF="" ...> ...</a>
</ui:form>

Element Interprets the Content Itself

Web Application Server

620 SP 9

300

SAP Online Help

25.10.2002

With this selection, you define that the content of the element is to be passed on
unchanged, without previous parsing, to the element handler class. This is
appropriate whenever an interpretation of the element content is not required by
the runtime environment.

Example: The BSP element executes an SQL statement that must be


specified in the element content.
<sql:selectStatement>
SELECT * from SFLIGHT into table myFlights
</sql:selectStatement >

User-Defined Validation
Use
Activate this option in the Attributes display for the BSP element if you wish to execute a userdefined validation of the element call. This can be the case, for example, if you wish to check
the correct type of attribute values. Generally speaking, validation can take place both at
compile time and at runtime. Runtime validation is particularly appropriate if attributes for
BSP elements are assigned through BSP expressions (<%=...%>) only at runtime, or for
attributes whose values are transformed into another data type (String -> I) at runtime.
Validation at compile time, on the other hand, is done by the BSP compiler and takes place
whenever values are passed using static attributes.

Activities
In addition to activating the option User-Defined Validation , you need to redefine the methods
COMPILE_TIME_IS_VALID (for validation at compile time) and/or RUNTIME_IS_VALID (for
validation at runtime) in the element handler class.

You must set the return parameter valid within the method
COMPILE_TIME_IS_VALID. When determining this value, you use the
predefined attributes and utilities belonging to the validation object validator.
This object has corresponding conversion methods that identify attributes at
compile time through the attribute name (see first example). The validation object
validator is already contained in the interface for COMPILE_TIME_IS_VALID
as an input parameter.
The RUNTIME_IS_VALID method, on the other hand, does not define any
return parameter. The runtime validation triggers an appropriate runtime
exception if there is an error. The validation object m_validator.is an important
part of the method implementation. This object is already defined as an attribute
of the element handler class and also has conversion methods that identify the
attributes through their names and also through their value (see second
example). The attributes to be checked (runtime attributes) are supplied as
argument for calling the method RUNTIME_IS_VALID. This argument consists of

Web Application Server

620 SP 9

301

SAP Online Help

25.10.2002

a string in which the names of the attributes to be checked are listed, separated
by / .

It can happen that the string with the runtime attributes to be checked exceeds
the maximum length of 200 characters when <Elementname>>RUNTIME_IS_VALID(attr_1/attr_2/ .../attr_n) is called that is, if
there is a large number of attributes. In such cases, you should pass the string / *
/ instead of the attribute name in order to avoid termination during activation.

Example: Validation at Compile Time


In the example below, the system is to check at compile time whether the value of the
attribute required is a correct Boolean value and whether the two attributes size and
maxlength contain integer values.
For this purpose, the interface method COMPILE_TIME_IS_VALID is overwritten. The
corresponding methods of the object validator for the attributes concerned are called for
the conversion of the string value from the HTML data stream into Boolean and integer
values. If all the checked attribute values are valid, the return value valid is filled
accordingly with m_all_values_valid.
method IF_BSP_ELEMENT~COMPILE_TIME_IS_VALID .
validator->to_boolean( name = 'required' ).
validator->to_integer( name = 'size' ).
validator->to_integer( name = 'maxlength' ).
valid = validator->m_all_values_valid.
endmethod.

Example: Validation at Runtime


In the example below, the system is to check at runtime whether the value of the attribute
visible is a correct Boolean value and whether the two attributes axisMinVal and
axisMaxVal contain values of the type Float.
In this case, the interface method RUNTIME_IS_VALID is overwritten. The parameter list
m_visible, m_axisMinVal, m_axisMaxVal is passed to this method. The
corresponding result of the attribute check is written into this list. The attributes are identified
using the methods of the validation object m_validator. The method RUNTIME_IS_VALID
does not return any return value. If one of the checked attribute values is invalid, a
corresponding exception is triggered at runtime.
method IF_BSP_ELEMENT~RUNTIME_IS_VALID .
m_visible

= m_validator->to_boolean( name = 'visible'


value = me->visible ).

m_axisMinVal = m_validator->to_float( name = 'axisMinVal'


value = me->axisMinVal ).
m_axisMaxVal = m_validator->to_float( name = 'axisMaxVal'
value = me->axisMaxVal ).
endmethod.

Web Application Server

620 SP 9

302

SAP Online Help

25.10.2002

Iteration Through Element Content


Use
Activate this option in the Attributes display for the BSP element if this element is to run
through its own content repeatedly, that is, it should implement a loop.

Activities
In addition to activating this option, you must also redefine the interface method
DO_AT_ITERATION of the element handler class.
This method is called each time at the end of an iteration. Using the return parameter , you
control whether the loop is ended (RC=CO_ELEMENT_DONE) or run through once again
(RC=CO_ELEMENT_CONTINUE).

Example
Let us assume that you wish to have a repeated text call with a simple <do>-Element. The
number of iterations is set through the corresponding attribute howOften.
Example:
<loops:do howOften = "10">
Hello World !
</loops:do>
The value of the attribute howOften is used at the beginning of the element call in the
method DO_AT_BEGINNING in order to initialize the loop counter count:
method IF_BSP_ELEMENT~DO_AT_BEGINNING .
if howOften > 0.
count = howOften - 1.
rc = CO_ELEMENT_CONTINUE.
else.
rc = CO_ELEMENT_DONE.
endmethod.

The method DO_AT_BEGINNING should have already checked whether the


element content is to be evaluated at all. If this not the case, DO_AT_ITERATION
is skipped and afterwards the method DO_AT_END is called.
The implementation of DO_AT_ITERATION could look like this:
method IF_BSP_ELEMENT~DO_AT_ITERATION .
if count <> 0.

Web Application Server

620 SP 9

303

SAP Online Help

25.10.2002

count = count - 1.
rc = CO_ELEMENT_CONTINUE.
else.
rc = CO_ELEMENT_DONE.
endif.
endmethod.

Note that the method DO_AT_ITERATION is only called if the operation Iteration
Through Element Content has been explicitly assigned as element attribute. See
also Defining BSP Elements [page 297].
DO_AT_ITERATION is called as soon as the element content has been
processed. The method DO_AT_END, on the other hand, is called whatever the
case, but only once; in this case, the call takes place after the iteration has closed

Manipulation of the Element Content


Use
Activate this option in the Attributes display for the BSP element if it is necessary that this
element can manipulate its own content.

Activities
After activation of this option, a so-called BodyWriter becomes available in the interface
attribute M_OUT for the element handler class. This manages the content of the BSP element.
Using the BodyWriter methods, you can manipulate the content accordingly.
To change the element content, you must also redefine the interface method DO_AT_END for
the element handler class as well as activate the option Manipulation of the Element Content.
This method is accessed in any case at the end of the element call. You can use them
especially for manipulating the content in order to explicitly pass the BodyWriter content to the
BodyWriter of a surrounding BSP element. If no pass takes place in this case, the element
content is discarded.

Example
In the following example, a BSP element is to convert its entire text content into upper-case
letters. The method DO_AT_END is overwritten as follows:
First, the element content from the current BodyWriter m_out is written to the local variable
content. A new content is then assigned to this variable. Afterwards, the method call me>get_previous_out() returns the BodyWriter of the surrounding element
previous_out. The new content, however, is not automatically copied to this BodyWriter.
The assignment of the new content finally takes place with the method print_string().
method IF_BSP_ELEMENT~DO_AT_END.
data: content type string.

Web Application Server

620 SP 9

304

SAP Online Help

25.10.2002

content = m_out->get_content( ).
translate content to upper case.
data: previous_out type ref to IF_BSP_WRITER.
previous_out = me->get_previous_out().
previous_out-> print_string( content ).
rc = CO_PAGE_CONTINUE.
endmethod.

Pass by Reference for Attributes


Passing by reference is always appropriate if the BSP element is to have access to larger
data quantities in the BSP page and passing by value would be too costly. This is the case if
you have access to internal tables.
In addition, the pass by reference is used whenever the BSP element is to change the content
of a variable defined in the BSP page.

Note that in this case you must also select the typing kind TYPE REF TO for the
corresponding attribute.

Example
The BSP element is to increase the content of a passed variable by 1. The attribute value is
required for passing the value. Calling this increment element into the BSP page could then
take place as follows:
<xyz:increment value = "<%=my_var%>"/>
The variable my_var is declared in the BSP application as a page attribute of the type I.
For the value attribute, the indicator Dynamic Value Allowed was activated and TYPE REF
TO was selected as Typing Kind in the attribute display.
To execute this pass by reference at the beginning of the element call, you need to overwrite
the method DO_AT_BEGINNING:
method IF_BSP_ELEMENT~DO_AT_BEGINNING .
...
add 1 to value->*.
rc = CO_ELEMENT_DONE.
endmethod.

Web Application Server

620 SP 9

305

SAP Online Help

25.10.2002

Note that there is a reference to data in this example within a BSP element. To access data,
the reference operator ->* must be used in ABAP in this case.

Activating the BSP Extension


Use
You use this standard function of the Workbench in order to put the entire BSP extension,
including its elements, into the active version. If necessary, the system will generate the basis
class (CLG_* or ZCLG_*) again upon activation. This renewed generation always tales place
during activation in the following cases:
If generation-relevant element data has been changed because, for example, element
attributes have been created, deleted, or changed.
If a basis class for a particular element does not exist at all because, for example, it was
deleted manually, or was not transported by mistake.

Prerequisites
You have either created a BSP extension or processed one that already exists.

Activation does not take place for the individual BSP elements alone, but is
always done for the entire extension.

Procedure
1. Choose the required BSP extension from the object list.
2. Select the Activate function from the context menu or through the respective
icon in
the application toolbar.
The system displays a list of all inactive objects. The selected BSP extension is
marked.
3. Confirm the selection by clicking

Continue.

Result
When you activate, you create a runtime version of the BSP extension. If necessary, the
system will also regenerate the element handler classes and your basis classes. Newlycreated classes are automatically written to the same transport request as the BSP extension.
Now the active version of the BSP extension appears in the Tag Browser [page 421] under
the entry BSP Extensions. There it is assigned to the selection Transportable or Local,
depending on the object catalog entry.

Note that activating the extension can invalidate all the BSP pages that use this
extension. Calling the respective BSP pages again means they will be
regenerated if changes have been made.

Web Application Server

620 SP 9

306

SAP Online Help

25.10.2002

Implementing Element Handler Classes


Use
The element handler class is the central class of a BSP element. It implements the specific
functions of an element and thus influences the flow logic of the BSP page that uses this
element. Through the type of implementation of certain methods belonging to this class, you
can control whether data is updated in the HTML data stream and whether the content of a
BSP element is processed or discarded.
Element handler classes are instantiated during the processing of a BSP page and called at
defined points in time using certain class methods.

Prerequisites
A valid element handler class must implement the interface IF_BSP_ELEMENT. We therefore
recommend that you derive this class from the generated superclass [page 307]
(Z)CLG_<EXTENSION>_<ELEMENT> because it already contains the standard
implementations for the interface methods.

Process Flow
The flow during implementation of the specific functions of a BSP element is divided up into
the following three steps:
1. Creating the attributes for the BSP element See also Defining BSP Elements.
In this way, you make sure that the new attributes are added as attributes of the
element handler classes after activation of the BSP extension.
2. Overwriting certain interface methods [page 309] of the element handler class
3. Creating further methods or attributes that enhance the element functions

Generated Classes and Class Hierarchy


The following figure shows the position of the element handler class within the inheritance
hierarchy of the classes involved:

Web Application Server

620 SP 9

307

SAP Online Help

25.10.2002

<<interface>>

Basis Interface

IF_BSP_ELEMENT

Extension
Framework
Basis Class

CL_BSP_ELEMENT

Generated Basis
Class

(Z)CLG_<Extension>_<Element> *

Element-Specific
Classes
Generated
Element Handler
Class

CL_<Extension>_<Element>

**

* Class name in customer namespace: ZCLG_<Extension>_<Element>


** Name of element handler class can be selected by the user

Extension Framework
IF_BSP_ELEMENT

Basic interface that each valid element handler


class must implement. The methods and
attributes of this interface already define the
actual extension framework for BSP
applications.

CL_BSP_ELEMENT

Basis class with a standard implementation of


the IF_BSP_ELEMENT methods for all BSP
elements.
See also:
Basis Class CL_BSP_ELEMENT [page 309]

Element-specific classes
(Z)CLG_<EXTENSION>_<ELEMENT>

This class is automatically generated by the


development environment for each new BSP
element and is provided as a basis class for
the element handler class.
It has a 1:1 relationship to a BSP element and

Web Application Server

620 SP 9

308

SAP Online Help

25.10.2002
already contains a standard implementation for
the corresponding element.
In contrast to its superclass
CL_BSP_ELEMENT, it contains public
attributes that correspond to element attributes
and, additionally, the standard implementation
for the constructor (and, if necessary, for the
class constructor as well).

CL_<EXTENSION>_<ELEMENT>

The element class, too, has a 1:1 relationship


to a BSP element and implements its specific
functions. As a rule, it is derived from the CLG
class. This is recommended, but not
compulsory.
Compared to its basis class, the element
handler class can be enhanced to include
specific methods. In addition, special interface
methods can be redefined, depending on the
element attributes.

Basis Class CL_BSP_ELEMENT


Definition
The CL_BSP_ELEMENT class supplies a standard implementation of the interface
IF_BSP_ELEMENT. This basis interface basically provides a series of methods and attributes
that are used as a framework for the implementation of individual elements in BSP
extensions.

Use
The standard implementation of the class CL_BSP_ELEMENT provides the common basic
functions for all element handler classes. To implement specific functions of a BSP element,
you must overwrite certain interface methods in the element handler class and possibly also
create new ones there.
Refer also to the section: Implementing Element Handler Classes [page 307].
Methods
Interface Methods for Validation
COMPILE_TIME_IS_VALID

RUNTIME_IS_VALID

Determines at compile time whether correct values have


been assigned to element attributes. The validation result is
written to the return parameter valid.
The possible values for valid are: X' or ' ' (blank).
For information on how you can overwrite this method in
the element handler class, refer to the example given for
user-defined validation [page 301].
Determines at runtime whether correct values have been
assigned to the element attributes. For more information,
refer also to the example for user-defined validation [page
301].
By calling the runtime method <Elementname>>RUNTIME_IS_VALID with the special argument /*/, you
can prevent termination from happening at activation if the
string with runtime attributes (arg_1/arg_2/...) becomes too

Web Application Server

620 SP 9

309

SAP Online Help

25.10.2002

long (maximum length is 200 characters) and thus


overflows.
Interface Methods to Influence Element Flow and Element Content
DO_AT_BEGINNING
This method is always accessed at the beginning of the
element call when the BSP page is processed.
Using the return parameter RC you can control whether the
content of the current BSP element is to be evaluated or
not. The possible values of the return parameter RC are
therefore:
CO_ELEMENT_CONTINUE and CO_ELEMENT_DONE.
For an example of a special implementation of this method,
refer to the section Pass by Reference for Attributes [page
305].
DO_AT_ITERATION
This method is accessed after evaluation of the element
content when the BSP page is processed. The prerequisite
for calling this method at all is that the corresponding option
Iteration Through Element Content has been explicitly set
for the element.
This method returns the return parameter RC.
The possible values of the return parameter RC here, too,
include the following:
CO_ELEMENT_CONTINUE and CO_ELEMENT_DONE.
For an example of the implementation, refer to the section
Iteration Through Element Content [page 303].
DO_AT_END
This method is accessed, whatever the case, at the end of
the element call. Since the entire element content is
available at this point, this method can be used for
Manipulation of the Element Content [page 304].
Using the return parameter RC, you can control whether
the entire BSP page is to be evaluated further or not. The
possible values are therefore:
CO_PAGE_CONTINUE and CO_PAGE_DONE.
Interface Methods for Accessing Parent Nodes
GET_CLASS_NAMED_PARENT
Returns an arbitrary parent element that is identified by the
element handler class.
GET_ELEMENT_NAMED_PARENT Returns an arbitrary parent element that is identified by the
name of the extension and the name of the element.
GET_DIRECT_PARENT
Returns the direct parent element.
Interface Method For Error Handling
RAISE_ERROR
Triggers an exception of the class
CX_BSP_ELEMENT_EXCEPTION.
Interface Method for Accessing the Content of the BodyWriter
GET_PREVIOUS_OUT
Returns the reference to the BodyWriter of the surrounding
element.
Attributes
General Interface Attributes
ID
M_NAME
M_EXTENSION
M_CLASS_NAME
M_PARENT
M_PAGE_CONTEXT
Predefined Interface Constants
CO_PAGE_DONE
CO_PAGE_CONTINUE
CO_ELEMENT_DONE
Web Application Server

BSP element ID
BSP element name
BSP extension name
Name of element handler class
Reference to a parent element
Reference to the page context (IF_BSP_PAGE_CONTEXT)
This constant defines that the BSP page is not to be
evaluated further.
This constant defines that the BSP page is to be evaluated
further.
This constant defines that the BSP element is not to be
620 SP 9

310

SAP Online Help

CO_ELEMENT_CONTINUE

25.10.2002
evaluated further.
This constant defines that the BSP element is to be
evaluated (once more).

Interface Attribute for the BodyWriter


M_OUT
Reference to the BodyWriter that manages the element
content.
Interface Attribute for Validation
M_VALIDATOR
Static validator (for all class instances) that is used for
runtime validation. Instances of this object are created only
if the option Iteration Through Element Content has been
explicitly set for the element.

Entering Documentation
Use
You can create a long text documentation both for a BSP extension as well as for each BSP
element in the system that is contained in this extension. This document is of particular
importance for the productive usage of the extension in BSP pages because you can include
special aspects of the individual BSP elements here.
If you store the documentation in the system, it is then available to users through the context
menu in the Tag Browser and also through insertion of the tag into a BSP page also by
pressing F1 in the layout editor.

Prerequisites

The BSP extension and the elements to be documented have already been created.

There are two different templates available for the BSP extension and the BSP elements.
The procedure for creating the documentation is the same, however.

Procedure
To create documentation for a BSP element in SE80:
1. Select the BSP extension in the Repository Browser.
2. Double-click the required BSP element in the object list.
The system displays the element editor.
3. Go to Change mode.
4. Click the Documentation pushbutton in the toolbar.
The SAPScript Editor is called up and displays an empty template with predefined
paragraphs.
5. Write your text into the predefined paragraphs.
6. Save the SAPScript document as a raw version first.
7. Test the documentation and make whatever corrections are necessary.
8. Save the document as active version.

Result
You have created a SAPScript document for the long text documentation of a BSP element
and have assigned a transport request to it.

Web Application Server

620 SP 9

311

SAP Online Help

25.10.2002

If you have saved the document as an active version as well, this will be transported to the
translation worklist.

Example
The documentation for all BSP elements is available for the BSP extension HTMLB.

Using BSP Elements


Use
All delivered or newly created BSP extensions are available in the Tag Browser [page 421] of
the Object Navigator. You can use these in BSP application pages in order to create flexible
Web user interfaces.
You enter the individual BSP elements and their attributes as tags or tag attributes from the
Tag Browser into the layout source text of the BSP pages.

Prerequisites

The switch button Tab Browser is available in the navigation area of the Object Navigator.
If this is not the case, change the corresponding user settings.

So that the BSP extension is displayed with the required elements in the Tab Browser,
the extension must already be activated.

Procedure
To insert BSP elements or their attributes into a BSP page, proceed as follows:
1. Choose the Layout view for the required BSP page.
2. Switch to Change mode.
3. Click the switch button Tag Browser in the navigation area of the Object Navigator.
4. Under BSP Extensions, choose the appropriate extension.
5. Expand the tree display and click the required BSP element.
6. Double-click the selected entry in order to display the documentation for the BSP
element.
7. Using Drag and Drop, drag the selected element or element attribute to the appropriate
position in the layout editor.

Multiple selection within the tree display is currently not supported.

Result
When you select an element in the tree display, the corresponding start tag and end tag,
including all the obligatory element attributes, are inserted at the selected cursor position in
the BSP page. If you enter an element attribute, the system takes the predefined standard
value.
With the first element of a BSP extension, the extension directive for the page is automatically
created. The system adopts as prefix the default prefix that was specified when you created
the BSP extension [page 296]. By typing over the prefix value in the extension directive,
however, you can rename the prefix. This means that all tags entered subsequently from the
Tag Browser already contain the new prefix.

Web Application Server

620 SP 9

312

SAP Online Help

25.10.2002

If documentation was created [page 311] for a BSP element, you can call this by
pressing F1 in the layout editor of the BSP page.

Example
The following example [page 313] demonstrates the usage of the BSP extension HTMLB in a
BSP application.

Example: Using Extensions in BSP Pages


The following example shows the realization of a simple Web user interface for a BSP
application using the HTMLB library HTMLB. This library is available in each SAP Web
Application Server System and can be imported within the workbench from the Tag Browser
[page 421] into any BSP page.
This example contains a label, input, and pushbutton element in addition to the content,
page, and form elements - for simple selection of flight data. The flight data is displayed using
a TableView element.
<%@page language="abap"%>
<%@ extension name="htmlb" prefix="ui" %>
<ui:content>
<ui:page>
<ui:form>
<ui:label

id

= "myLabel"

for

= "carrier"

text

= "Airline"

design
width
<ui:inputField

id

= "LABEL"
= "65" />
= "carrier"

type

= "String"

value

= "<%=carrier%>"

size
design
<ui:button

id
text

= "3"
= "standard />
= "myButton"
= "Find Flights"

onClick = "FIND"
design

= "STANDARD />

<br><br>
<ui:tableView id
table

= "myTable"
= "<%=flights%>"

headerVisible = "true"

Web Application Server

620 SP 9

313

SAP Online Help

25.10.2002

footerVisible = "true"
fillUpEmptyRows= "true"
selectionMode = "MULTISELECT"
design

= "ALTERNATING" />

</ui:form>
</ui:page>
</ui:content>

Note on the prefix:


The BSP extension HTMLB is imported into the BSP page through the extension directive (2nd
line). A prefix serves as a unique identification of this extension within the page. This directive
is automatically crated after you have inserted the first BSP element for the page. In the
standard version, the default prefix is taken. However, you can rename the prefix by
overwriting the corresponding value in the extension directive (in our example: ui).

Composite Elements
Use
When you create BSP applications with BSP extensions, it may not be easy to use elements
that are essentially simple BSP elements. To generate the layout you require, you often need
a number of special elements. In such cases, you can create composite BSP elements to
facilitate handling several special elements, and to minimize the amount of work required to
develop BSP applications and their layouts.
The following uses a complex, typical task to display possible solutions. A simple BSP
extension is presented and implemented.

Although the example is restricted to three simple input fields, the composite
element solution is intended for cases where a number of variable input fields
should be displayed, including labels and table-format displays.
Task
Three input fields with labels should be displayed on a screen. Users should enter their name,
password and e-mail address in these input fields. The three fields should be arranged under
each other.
You should use BSP extension HTMLB to solve this task, with the following predefined layout
elements:

<htmlb:gridLayout>

<htmlb:label>

<htmlb:inputField>

Process
1. Create a test BSP application.
2. First use the already existing BSP extension HTMLB on page before.htm.

Web Application Server

620 SP 9

314

SAP Online Help

25.10.2002

3. Then create the composite element and use it on page after.htm.

Integration
Composite BSP elements use other, already existing BSP elements to generate the output
within the layout framework by including and wrapping the BSP elements that already exist.

Prerequisites
You already understand the concept of BSP extensions [page 284] and their implementation.

Activities
Create page before.htm [page 315]
Design solution [page 317]
Create a new BSP extension with elements [page 318]
Create page after.htm [page 319]
Dynamically process BSP elements [page 320]
Create a new BSP extension with composite elements [page 324]
Step 1 a) Implement <sf:SimpleFormItem> [page 324]
Step 1 b) Use <htmlb:SimpleFormItem> [page 326]
Step 2: Create <sf:SimpleForm> [page 328]
Step 3: Changes to the Look and Feel [page 331]

Creating Page before.htm


Use
On this page, implement the output using HTMBL.

Prerequisites
You have created a BSP application (see also Creating BSP Applications [External
documentation]). In our example, this has the name BSP_TUT_COMPLEX.

Procedure
1. In your BSP application, create page before.htm as a page with flow logic
(see also Creating Pages [External documentation]).
2. Define three page attributes for the three input fields:
Attribute

Auto

Typing Type

Reference Type

name

TYPE

STRING

password

TYPE

STRING

email

TYPE

STRING

3. Create the page layout with HTMBL elements:


<%@page language="abap"%>
<%@extension name = "HTMLB" prefix = "htmlb" %>

Web Application Server

620 SP 9

315

SAP Online Help

25.10.2002

<htmlb:content>
<htmlb:page>
<htmlb:form>
<htmlb:gridLayout cellSpacing = "2"
cellPadding = "0"
width
= "100%"
rowSize
= "3"
columnSize = "2">
<%-- name --%>
<htmlb:gridLayoutCell columnIndex
= "1"
rowIndex
= "1" >
<htmlb:label
id
= "name_label"
text
= "Name:"
for
= "name" />
</htmlb:gridLayoutCell>
<htmlb:gridLayoutCell columnIndex
= "2"
rowIndex
= "1">
<htmlb:inputField
id
= "name"
value
= "<%=name%>"/>
</htmlb:gridLayoutCell>
<%-- password --%>
<htmlb:gridLayoutCell columnIndex
= "1"
rowIndex
= "2" >
<htmlb:label
id
= "password_label"
text
= "Password:"
for
= "password" />
</htmlb:gridLayoutCell>
<htmlb:gridLayoutCell columnIndex
= "2"
rowIndex
= "2">
<htmlb:inputField
id
= "password"
value
= "<%=password%>"
password
= "TRUE" />
</htmlb:gridLayoutCell>
<%-- email --%>
<htmlb:gridLayoutCell columnIndex
= "1"
rowIndex
= "3" >
<htmlb:label
id
= "email_label"
text
= "Email:"
for
= "email" />
</htmlb:gridLayoutCell>
<htmlb:gridLayoutCell columnIndex
= "2"
rowIndex
= "3">
<htmlb:inputField
id
= "email"
value
= "<%=email%>" />
</htmlb:gridLayoutCell>
</htmlb:gridLayout>
</htmlb:form>
</htmlb:page>
</htmlb:content>
4. Save and activate your page and the BSP application.

Result
The generated output is as follows:

Web Application Server

620 SP 9

316

SAP Online Help

25.10.2002

Analysis
You need more than 40 lines coding to code the simple three input fields. Also, because of
the <htmlb:gridLayout> element, you cannot always immediately recognize at a glance
the coding structure. This element is not absolutely necessary for our example, although it
makes sense to use it with more complex layouts.
For these flow-type layouts, most attributes can now be calculated automatically, especially
counters for rows and columns. It is exactly the same when you connect <htmlb:label> to
<htmlb:inputField>. Many of the attributes can also be hard-coded in a set of wrapper
elements.
It is therefore recommended that you design a BSP extension library that also contains
inherent information (that is, hard-coded elements) for the layout of a specific BSP application
or a group of BSP applications. Ideally, the individual BSP extensions in this library will be
slim and easy to create. These can be used to create toolboxes that encapsulate the
appearance and the whole layout centrally. As a result, you can also make changes to the
whole application very quickly.
You can do all this using the Design Solution [page 317].

Design Solution
After analyzing the page before.htm [page 315], you need a set of elements that are easy to
use and which can be used for the outlined task area. As a result, this is not a universal
solution, but a solution for a clearly delimited application area.
Starting with the example, the initial situation is as follows:

All row and index counters are calculated automatically

All values for the layout (such as width, style, and so on) are hard-coded

Elements <htmlb:label> and <htmlb:inputField> are linked to each other.

The flexibility of the <htmlb:inputField> is still available, so that you can carry out
functions such as password handling without any problems

The format of the layout can be specified with BSP elements as follows:
<sf:SimpleForm

id

= "sf" >

<sf:SimpleFormItem
label
value

id

= "name"
= "Name:"
= "<%=name%>" />

<sf:SimpleFormItem
label
value
password

id

= "password"
= "Password:"
= "<%=password%>"
= "TRUE" />

<sf:SimpleFormItem
label

id

Web Application Server

= "email"
= "Email:"

620 SP 9

317

SAP Online Help

25.10.2002
value

= "<%=email%>" />

</sf:SimpleForm>
Here you require a new BSP extension, which contains all of the necessary elements. You
also need a test page, of course. Finally, you also need to implement the elements.

Procedure
The following describes the procedure for implementing this solution:
1. Create the new BSP extension [page 318]
2. Create the elements for the new BSP extension
a. Element <SimpleForm>
b. Element <SimpleFormItem>
3. Generate your new BSP extension
4. Create the page after.htm [page 319]
5. Specify that the BSP elements are processed dynamically [page 320]

Creating a New BSP Extension with Elements


Procedure
To create the new BSP extension for the solution [page 317] that is described, first define the
extension itself and then the elements that it contains. At the end, activate the extension.
1. Create a new BSP extension in the ABAP Workbench (see also Creating BSP Extensions
[page 296]).
In our example, this has the name BSP_TUTORIAL_COMPLEX.
2. Enter a Default prefix.
The default prefix is used for this BSP extension if you use drag & drop to add
elements of this extension in the page with flow logic, or if you want to insert them in
the view without having used this extension previously.
If you use the BSP extension, you can change the default prefix at any time by
renaming the prefix attribute of the extension directive.
In our example, this is TutCmplx.
3. In your new extension, create element <SimpleForm> (see also Defining BSP Elements
[page 297]).

We recommend that you integrate the default BSP extension prefix with the name of
the element handler class.
In our example, the name of the element handler class is
CL_BSP_TUTCMPLX_SIMPLE_FORM.
4. Define and configure the BSP element as usual.
In our example, the element content consists exclusively of inner BSP elements and
therefore does not have any freely-defined text.
In our example, the element has an (obligatory) attribute called id of type string.

Web Application Server

620 SP 9

318

SAP Online Help

25.10.2002

5. Create new BSP element <SimpleFormItem>.


This element displays an element that wraps both <htmlb:label> and
<htmlb:inputField>. Since the <htmlb:inputField> element contains most
of the attributes that you require for the new <TutCmplx:SimpleFormItem>
element, you can simply copy the <htmlb:inputField> element.
a. To do this, branch to the BSP extension HTMLB for element <inputField> and on the
selected element in the context menu choose Copy....
b. Then enter as the destination the BSP extension BSP_TUTORIAL_COMPLEX and
SimpleFormItem as the destination BSP element.
Since the copy function only copies the logical definition of the element, you must
make a few additional changes. The new definition in particular is still linked to
the original implementation class (element handler class).
c.

Use the tabstrip Properties to change the connection to the element handler class
and enter CL_BSP_TUTCMPLX_SIMPLE_FORM_IT.

d. Add the additional attributes that you require for processing <htmlb:label>. In this
simple example, you only need one new attribute, which is the label name.
On the tabstrip Attributes, enter the additional attribute label of type string.
6. Save the BSP extension and generate it.

Result
At this point, the empty implementations for the elements were already generated.
You can now create a simple test page [page 319] (although this does not create any output).

Creating Page after.htm


Use
Once you have created your new BSP extension [page 318] with the two new elements, you
can use this new extension already in a new page in your BSP application.
All elements are defined, and empty standard implementations were generated by the system
for each element. As a result, the elements can be used already, even if they do not create
any tasks.

Procedure
1. In the Web Application Builder, use the context menu to copy the existing page
before.htm [page 315] to the name after.htm.
2. Change the layout coding:
<%@page language="abap"%>
<%@extension name = "HTMLB"
<%@extension name = "BSP_TUTORIAL_COMPLEX"
<htmlb:content>
<htmlb:page>
<htmlb:form>
<sf:SimpleForm
<sf:SimpleFormItem

Web Application Server

620 SP 9

id
id
label
value

prefix = "htmlb" %>


prefix = "sf" %>

= "sf" >
= "name"
= "Name:"
= "<%=name%>" />

319

SAP Online Help

25.10.2002
<sf:SimpleFormItem

<sf:SimpleFormItem
</sf:SimpleForm>
</htmlb:form>
</htmlb:page>
</htmlb:content>

id
label
value
password
id
label
value

=
=
=
=
=
=
=

"password"
"Password:"
"<%=password%>"
"TRUE" />
"email"
"Email:"
"<%=email%>" />

3. Save, activate and test your BSP application.

Result
Everything runs as usual, although there is no output.
In the next step, implement dynamic BSP element processing [page 320]

Dynamically Processing BSP Elements


If a BSP element is located in the layout of a BSP, a compiler translates the XML syntax that
represents the interface for the element in source code, which is then executed at runtime.
In a simple example, (in simple pseudocode notation) this could be as follows:
Element:
Source:

<lib:element a1 = v1 />
DATA: e123 TYPE REF TO CL_LIB_ELEMENT.
CREATE OBJECT e123.
e123->a1 = v1.
e123->parent = page->current_element.
page->current_element = e123.
e123->context = page->context.
e123->DO_AT_BEGINNING( ).
e123->DO_AT_END( ).
page->current_element = e123->parent.

An element can, however, also require its own writer, and possibly also validation. The
element can either contain body text only, or it can include inner, embedded elements that
must be processed.
Element:

<lib:element2 a1 = v1 />
...
</lib:element2>

Source:

DATA: e124 TYPE REF TO CL_LIB_ELEMENT2.


CREATE OBJECT e124.
e124->a1 = v1.
e124->parent = page->current_element.
page->current_element = e124.
e124->context = page->context.
e124->m_out
= context->PUSH_WRITER( ).
e124->RUNTIME_VALIDATION( ).
IF e124->DO_AT_BEGINNING( ) = CO_ELEMENT_CONTINUE.
context->current_writer->PRINT_STRING( `....` ).

Web Application Server

620 SP 9

320

SAP Online Help

25.10.2002

ENDIF.
e124->DO_AT_END( ).
context->POP_WRITER( ).
page->current_element = e124->parent.
Furthermore, an element can specify that its body requires iteration. This suggests that the
body of the element is processed more than once.
Element:

<lib:element3 a1 = v1 />
...
</lib:element3>

Source:

DATA: e125 TYPE REF TO CL_LIB_ELEMENT3.


CREATE OBJECT e125.
e125->a1 = v1.
e125->parent = page->current_element.
page->current_element = e125.
e125->context = page->context.
e125->m_out
= context->PUSH_WRITER( ).
e125->RUNTIME_VALIDATION( ).
rc125 = e125-> DO_AT_BEGINNING( ).
WHILE e125 = CO_ELEMENT_CONTINUE.
context->current_writer->PRINT_STRING( `....` ).
rc125 = e125->DO_AT_ITERATION( ).
ENDWHILE.
e125->DO_AT_END( ).
context->POP_WRITER( ).
page->current_element = e124->parent.

Obviously, the compiler uses the additional information about the BSP elements definition to
generate the optimum code for processing the element.
The same flexibility is now required for processing BSP elements externally of the actual
BSP, that is, externally of the page.
From the examples above, you can see that to set an elements attributes you need a
reference to the actual class, and not to interface IF_BSP_ELEMENT. Also, elements do not
have methods to actually set attributes. The attributes are set directly as public attributes of
the element classes.
It is not effective to encapsulate the actual element class reference, or the phase in which
attributes are set. If an element is processed dynamically, you must know the element class
(you can find it in the BSP extension workbench). You can, however, pack the remaining code
in one or more methods.
You cannot encapsulate body processing, since it is not known if the body is a string, or if it
consists of several embedded elements that have to be processed.
Due to these design constraints, the following pseudocode can be written:
DATA: eX TYPE REF TO CL_LIB_ELEMENTX.
CREATE OBJECT eX.
eX->a1 = v1.
processing_before_body( eX ).
...body processing...
processing_after_body( eX ).

Web Application Server

620 SP 9

321

SAP Online Help

25.10.2002

This code is still not sufficiently flexible to handle element iteration. After the body has been
processed, you must decide whether iteration is carried out, or if it should be stopped. The
pseudocode can therefore be written as follows:
DATA: eX TYPE REF TO CL_LIB_ELEMENTX.
CREATE OBJECT eX.
eX->a1 = v1.
WHILE process_element( eX ).
...body processing...
ENDWHILE.
This enables users to set the element attributes first of all. Furthermore, users can be flexible
when determining how inner elements are to be used.
This type of element processing method with the name ELEMENT_PROCESS is available in
interface IF_BSP_PAGE_CONTEXT [page 266], which is available in every element.
If a body is not required, or only a simple string body is required, processing continues as far
as possible (until it is complete, if this is possible), provided that the optional body string is
available.
Now to processing an empty element. In this case, empty means that the element is
flagged in the Workbench as empty; it does not mean that there is only an optional body.
Element:
Source:

<lib:eX a1 = v1 />
DATA: eX TYPE REF TO CL_LIB_ELEMENTX.
CREATE OBJECT eX.
eX->a1 = v1.
m_page_context->ELEMENT_PROCESS ( element = eX ).

If the simple element requires a body as well, this can be done when the body string is
provided.
Element:

<lib:eX a1 = v1 />
body string
</lib.eX>

Source:

DATA: eX TYPE REF TO CL_LIB_ELEMENTX.


CREATE OBJECT eX.
eX->a1 = v1.
m_page_context->ELEMENT_PROCESS ( element = eX body = body
string).
The body can also be written dynamically during the processing step.

Note however, that the active writer is used for writing the body. Each time a
new element is (partly) processed, new writers may be pushed on the stack. The
writer that is used must be the last writer that was added.
Element:

Source:

<lib:eX a1 = v1 />
body string
</lib.eX>
DATA: eX TYPE REF TO CL_LIB_ELEMENTX.
CREATE OBJECT eX.
eX->a1 = v1.
m_page_context->ELEMENT_PROCESS ( element = eX ).
DATA: out TYPE REF TO IF_BSP_WRITER.
out = m_page_context->GET_OUT( ).
out->PRINT_STRING( `body string` ).

Web Application Server

620 SP 9

322

SAP Online Help

25.10.2002

m_page_context->ELEMENT_PROCESS( element = eX ).
You can process inner elements by starting your processing when the external element is
processed.

Ensure that you do not transfer a body to the processing code. If the body is
transferred as a parameter, the system assumes that this body represents the
whole body, and therefore then ends processing for that element.
Element:

<lib:eX a1 = v1>
body before
<lib:eY a1 = v1>
body inside
</lib:eY>
body after
</lib:eX>

Source:

DATA: eX TYPE REF TO CL_LIB_ELEMENTX.


CREATE OBJECT eX.
eX->a1 = v1.
m_page_context->ELEMENT_PROCESS( element = eX ).
DATA: out TYPE REF TO IF_BSP_WRITER.
out = m_page_context->GET_OUT( ).
out->PRINT_STRING( `body before` ).

DATA: eY TYPE REF TO CL_LIB_ELEMENTY.


CREATE OBJECT eY.
eY->a1 = v1.
m_page_context->ELEMENT_PROCESS( element = eY body =
`body inside` ).
out = m_page_context->GET_OUT( ).
out->PRINT_STRING( `body after` ).
m_page_context->ELEMENT_PROCESS( element = eX ).
Iteration implies that the same body is processed until the element has enough.
Element:

Source:

<lib:iterator repeat = 3 />


body string
</lib:iterator>
DATA: iterator TYPE REF TO CL_LIB_ITERATIR.
CREATE OBJECT iterator.
iterator->repeat = 3.
WHILE m_page_context->ELEMENT_PROCESS (
element = iterator
body = body string ) = CO_ELEMENT_CONTINUE.
ENDWHILE.

In principle, it is always correct to write a WHILE loop around the


ELEMENT_PROCESS()- call. This is the recommended technique for using this
method.

Web Application Server

620 SP 9

323

SAP Online Help

25.10.2002

As soon as an element has been processed, the element instance can not be reused, since
you cannot rest all element default values like the BSP compiler does. The create object call
must therefore always be executed when the same element is to be processed again.
Element:
Source:

<lib:eX a1 = v1 />
<lib:eX a1 = v1 />
DATA: eX TYPE REF TO CL_LIB_ELEMENTX.
CREATE OBJECT eX.
eX->a1 = v1.
m_page_context->ELEMENT_PROCESS ( element = eX ).
CREATE OBJECT eX.
eX->a1 = v1.
m_page_context->ELEMENT_PROCESS ( element = eX ).

Now create the new BSP extension [page 324] with the composite elements.

Creating a New BSP Extension with Composite


Elements
Use
Instead of creating a complete solution using the <htmlb:gridLayout> as in the first
implementation, the following selects a two-level implementation.

In the first section, a simple HTML code sequence is written using the <table> HTML
element. The elements <htmlb:label> and <htmlb:inputField> are used for the
actual table content.

In the second step, the <htmlb:gridLayout> is added.

Finally, you will see how you can change the layout of all pages simply by changing the new
elements.

Procedure
Step 1 a) Implement <sf:SimpleFormItem> [page 324]
Step 1 b) Use <htmlb:SimpleFormItem> [page 326]
Step 2: Create <sf:SimpleForm> [page 328]
Step 3: Changes to the Look & Feel [page 331]

Step 1 a) Implementing <sf:SimpleFormItem>


Since the <sf:SimpleFormItem> requires an HTML <table> wrapper, first create the
<sf:SimpleForm> element to render the correct HTML in the output stream.
Within class CL_BSP_TUTCMPLX_SIMPLE_FORM, overwrite and implement the following two
methods:
method IF_BSP_ELEMENT~DO_AT_BEGINNING .
DATA: out TYPE REF TO IF_BSP_WRITER.
Web Application Server

620 SP 9

324

SAP Online Help

25.10.2002

out = me->GET_PREVIOUS_OUT( ).
out->PRINT_STRING( '<table>' ).
RC = CO_ELEMENT_CONTINUE.
endmethod.
method IF_BSP_ELEMENT~DO_AT_END .
DATA: out TYPE REF TO IF_BSP_WRITER.
out = me->GET_PREVIOUS_OUT( ).
out->PRINT_STRING( '</table>' ).
RC = CO_PAGE_CONTINUE.
endmethod.
For the actual element <sf:SimpleFormItem>, the rendering code is as follows:
<tr><td> <htmlb:Label/> </td><td> <htmlb:inputField/> </td></tr>
For the implementation, the HTML coding is fetched in the usual way using the current output
writer, and written to the data stream.
Processing the <htmlb:*> element is slightly more difficult. Since both elements are empty
(that is, they dont have a body), they can be processed in one step. The processing steps are
as follows for each element:
1. Create the element class
2. Set the attributes
3. Use method ELEMENT_PROCESS for the final processing.
The complete coding is then as follows:
method IF_BSP_ELEMENT~DO_AT_BEGINNING .
DATA: out TYPE REF TO IF_BSP_WRITER.
out = me->GET_PREVIOUS_OUT( ).
* <tr><td>
out->PRINT_STRING( '<tr><td>' ).
* <htmlb:Label/>
DATA: label TYPE REF TO CL_HTMLB_LABEL.
CREATE OBJECT label.
CONCATENATE me->id '_label' INTO label->id.
label->encode
= 'FALSE'.
label->for
= me->id.
label->wrapping
= 'FALSE'.
label->text
= me->label.
m_page_context->ELEMENT_PROCESS( element = label ).
* </td><td>
out->PRINT_STRING( '</td><td>' ).
* <htmlb:inputField/>
DATA: inputField TYPE REF TO CL_HTMLB_INPUTFIELD.
CREATE OBJECT inputField.
inputField->id
inputField->description
inputField->disabled
inputField->firstDayOfWeek
inputField->invalid

Web Application Server

=
=
=
=
=

me->id.
me->description.
me->disabled.
me->firstDayOfWeek.
me->invalid.

620 SP 9

325

SAP Online Help


inputField->maxlength
inputField->password
inputField->required
inputField->showHelp
inputField->size
inputField->type
inputField->value
inputField->visible
inputField->width

25.10.2002
=
=
=
=
=
=
=
=
=

me->maxlength.
me->password.
me->required.
me->showHelp.
me->size.
me->type.
me->value.
me->visible.
me->width.

m_page_context->ELEMENT_PROCESS( element = inputField ).


* </td></tr>
out->PRINT_STRING( '</td></tr>' ).
rc = CO_ELEMENT_DONE.
endmethod.

Note that you cannot make any changed to the actual output writer structures.
The coding, exactly like the inner elements that are processed, is executed on
the current writer. This is automatically controlled by the development
environment (indirectly using the PROCESS_ELEMENT call).
You can now test page after.htm.
The following task appears:

Continue with Step1 b) Using <htmlb:SimpleFormItem> [page 326]

Step 1 b) Using <htmlb:SimpleFormItem>


Element <sf:SimpleFormItem> [page 324] has been implemented and can therefore be used.
You must now ensure that each entry is rendered directly in the current output stream. If the
<htmlb:gridLayout> is used later, a counter is required to count exactly the number of
fields that are required so that the gridLayout and, of course, each individual cell can be
configured correctly. This means that entries are first counted and then later rendered.
The best way to do this is if elements <htmlb:label> and <htmlb:inputField> are
rendered immediately, although not in the output stream. Instead, these elements are
rendered in separate writers, in which the content is stored and the entries are counted, and
with which they are finally rendered.

Web Application Server

620 SP 9

326

SAP Online Help

25.10.2002

To realize this, the entry must be changed so that it renders a string, and that this string is
forwarded for rendering the <sf:SimpleForm> later.
A new method ADD_ITEM is added to element <sf:SimpleForm> with the two parameters
label_html and inputField_html, which are both of type string.

You can add additional methods to the BSP event handlers, which implement
additional functionality, and which can in turn be used by lesser elements. The
element handler classes are normal ABAP classes that can be processed in the
Workbench.
The simple coding will be as follows:
method ADD_ITEM .
DATA: out TYPE REF TO IF_BSP_WRITER.
out = me->GET_PREVIOUS_OUT( ).
out->PRINT_STRING(
out->PRINT_STRING(
out->PRINT_STRING(
out->PRINT_STRING(
out->PRINT_STRING(

'<tr><td>' ).
"
label_html ).
"
'</td><td>' ).
"
inputField_html ). "
'</td></tr>' ).
"

<tr><td>
<htmlb:Label/>
</td><td>
<htmlb:inputField/>
</td></tr>

endmethod.
The only task for ADD_ITEM at the moment to render the string immediately.
In the next step, the coding is changed within <sf:SimpleFormItem>. For each internal
element that is used, the element output must not be written to the current writer under any
circumstance. As a result, this ensures that a new writer is pushed on the stack. Furthermore,
all new elements will write to this new writer, and the context can be extracted from this new
writer at any time.
The changed coding is then as follows:
method IF_BSP_ELEMENT~DO_AT_BEGINNING .
DATA: my_out
TYPE REF TO IF_BSP_WRITER,
label_html
TYPE STRING,
inputField_html TYPE STRING.
* Add own temporary writer on stack
my_out = m_page_context->PUSH_WRITER( ).
* <htmlb:Label/>
....
label_html = my_out->GET_CONTENT( ).
my_out->CLEAR( ).
* <htmlb:inputField/>
....
inputField_html = my_out->GET_CONTENT( ).
my_out->CLEAR( ).
* Remove my writer from stack
m_page_context->POP_WRITER( ).
* Copy Text to <sf:SimpleForm>
DATA: sf
TYPE REF TO CL_BSP_TUTCMPLX_SIMPLE_FORM.
sf ?= me->GET_CLASS_NAMED_PARENT( 'CL_BSP_TUTCMPLX_SIMPLE_FORM' ).
sf->ADD_ITEM( label_html = label_html inputField_html =
inputField_html ).
rc = CO_ELEMENT_DONE.

Web Application Server

620 SP 9

327

SAP Online Help

25.10.2002

endmethod.
Note the following points:

The use of PUSH_WRITER() at the beginning to add an additional writer to the stack.
All new elements that are now processed write to the top writer on the stack. At the
end of this method, the additional writer must be removed from the stack using
method POP_WRITER().

The use of methods GET_CONTENT() to extract the current string to the output, and
CLEAR() to ensure that the two elements are in separate strings.

The use of method GET_CLASS_NAMED_PARENT() to receive a reference to an element


that is located further up in the element stack.

The call of method ADD_ITEM(), which represents a local method that is defined by the
element.

You can now execute page after.htm again to ensure that it still runs correctly.
The element <sf:SimpleFormItem> is then complete.
This section has described how BSP elements are processed on the stack. We have also
described how the output of this type of element can be written to a string, so that it can be
rendered later.
For more information, see Step 2: Creating <sf:SimpleForm> [page 328]

Step 2: Creating <sf:SimpleForm>


The next step after Step 1: Using <htmlb:SimpleFormItem> [page 326] is similar. You must
first enhance the simple form handler class so that the entries are not written as soon as they
are added. The entries must be collected and rendered at the end.
Add two string tables as class attributes to class CL_BSP_TUTCMPLX_SIMPLE_FORM:
Name

Type

Visibility

Typing Type

Reference
Type

Description

LABELS

Instance
attribute

private

TYPE

STRING_TAB
LE

Table of
strings

INPUTFIELD
S

Instance
attribute

private

TYPE

STRING_TAB
LE

Table of
strings

Change the ADD_ITEM method to collect the entries:


method ADD_ITEM .
APPEND label_html
TO labels.
APPEND inputField_html TO inputFields.
endmethod.

Ensure that an element handler class can be reused several times. This is
triggered by the code generator for the BSP. This is why the whole local data
structure must be reset each time that a new element is restarted.
The coding that is executed at the beginning must be changed as follows:

Web Application Server

620 SP 9

328

SAP Online Help

25.10.2002

method IF_BSP_ELEMENT~DO_AT_BEGINNING .
CLEAR labels.
CLEAR inputFields.
RC = CO_ELEMENT_CONTINUE.
endmethod.
In the last step, the whole rendering should be executed at the end tag of the element.
The coding for the output would therefore be as follows:
<htmlb:GridLayout >
LOOP AT labels/fields
<htmlb:GridLayoutCell >
output label string
</htmlb:GridLayoutCell>
<htmlb:GridLayoutCell >
output inputfield string
</htmlb:GridLayoutCell>
ENDLOOP.
</htmlb:GridLayout>
Here, the most interesting point is that tags must be processed with bodies. An element would
usually be processed by a WHILE loop, while PROCESS_ELEMENT is called at the end. As a
result, both the start and the end tag are processed. After the first processing call, the
element was pushed on the processing stack and is therefore available as if the compiler had
generated the code. After the inner tag has been processed, the second call of
PROCESS_ELEMENT is required for processing the end tag.
The <htmlb:gridLayout> is processed in the first part of the coding. There then follows a
LOOP, in which all of the calls are executed, and finally the end tag </htmlb:gridLayout>
must be processed. Ensure that the whole output is written to the currently active writer.
The coding is as follows:
method IF_BSP_ELEMENT~DO_AT_END .
*

<htmlb:gridLayout>
DATA: gridLayout TYPE REF TO CL_HTMLB_GRIDLAYOUT.
CREATE OBJECT gridLayout.
gridLayout->id
= me->id.
gridLayout->cellSpacing = '0'.
gridLayout->cellPadding = '2'.
gridLayout->rowSize
= lines( labels ).
gridLayout->columnSize = 2.
gridLayout->width
= '100%'.
m_page_context->ELEMENT_PROCESS( element = gridLayout ).

* Output all cells.


DATA: label
inputField

TYPE STRING,
TYPE STRING.

LOOP AT labels INTO label.


READ TABLE inputFields INTO inputField INDEX sy-tabix.
....code to process gridLayoutCell for label and for inputField
ENDLOOP.
* </htmlb:gridLayout>
m_page_context->ELEMENT_PROCESS( element = gridLayout ).
rc = CO_PAGE_CONTINUE.
endmethod.

Web Application Server

620 SP 9

329

SAP Online Help

25.10.2002

Processing the <htmlb:gridLayoutCell> element is slightly more complex. The reason


for this is that for each cell, the current body (the HTML string that was previously collected)
must be written to the output stream.
The coding is therefore split into three steps. First the start tag is processed, then the body is
written to the current output writer, and finally the end tag is processed. For the
<htmlb:label> string, the coding is as follows:
*

<htmlb:gridLayoutCell> for label


DATA: gridLayoutCell TYPE REF TO CL_HTMLB_GRIDLAYOUTCELL.
CREATE OBJECT gridLayoutCell.
gridLayoutCell->rowIndex
= sy-tabix.
gridLayoutCell->columnIndex
= 1.
gridLayoutCell->horizontalAlignment = 'LEFT'.
gridLayoutCell->verticalAlignment
= 'MIDDLE'.
m_page_context->ELEMENT_PROCESS( element = gridLayoutCell ).

print content
DATA: out TYPE REF TO IF_BSP_WRITER.
out = me->m_page_context->GET_OUT( ).
out->PRINT_STRING( label ).

</htmlb:gridLayoutCell>
m_page_context->ELEMENT_PROCESS( element = gridLayoutCell ).

Ensure that the output writer that is currently active is not received until just
before it is used. It is important that GET_OUT() is called each time an element is
processed. Every element can push additional writers on the stack, even the
BSP framework can add its own writer to the stack from time to time. If only one
single writer is received at the start of the method, this is therefore probably the
parent writer of the gridLayout, that is, all of the new output is written to the
parent writer of the gridLayout. It is therefore important that the new active writer
is always received after a PROCESS_ELEMENT call and before the new output.
The method PROCESS_ELEMENT is aligned with element processing, even if they require
iteration. In theory, after every write/processing cycle the system should check explicitly
whether the element has finished. In this case, the element does not include iteration.
PROCESS_ELEMENT can therefore be called again without any problems.
In cases where only one body must be written, particularly if the body is already present as a
string, the body can be transferred as a parameter of the PROCESS_ELEMENT method. A
writer is not required, and the processing code automatically writes the body correctly and
finished processing the method.
The more simple coding is as follows (here string inputField is used as an example):
*

<htmlb:gridLayoutCell/> for inputField


CREATE OBJECT gridLayoutCell.
gridLayoutCell->rowIndex
= sy-tabix.
gridLayoutCell->columnIndex
= 2.
gridLayoutCell->horizontalAlignment = 'LEFT'.
gridLayoutCell->verticalAlignment
= 'MIDDLE'.

m_page_context->ELEMENT_PROCESS( element = gridLayoutCell body =


inputField ).

Ensure that the gridLayoutCell object is not reused. This is expressly


forbidden. It must be newly created each time a new element is required.
In the last step, you make changes to the look and feel [page 331].

Web Application Server

620 SP 9

330

SAP Online Help

25.10.2002

Step 3: Changes to the Look and Feel


After <sf:SimpleForm> is implemented, there may be requirements for visualization, such
as in our example that all field names should be formatted in bold.
This is the advantage of composite elements. Instead of having to individually change all of
the BSP elements that were already created, you only need to make one small change to a
single BSP element.
Within the coding for <sf:SimpleFormItem>, the change
from:

label->text

= me->label.

to:

CONCATENATE '<b>' me->label '</b>' INTO label->text.

causes the following task:

Model View Controller (MVC)


Use
SAP Web Application Server 6.20 has implemented the Model View Controller [page 335]
(MVC) design pattern, which is widely used in the user interface programming field and which
has proved its worth, as an extension of the previous BSP implementation model. Its
controller-based use ensures an even clearer distinction between application logic and
presentation logic in BSP applications. You can structure graphical user interfaces clearly and
organize them in logical units, even with complex applications.
Using the MVC design pattern has the following advantages:

Structuring BSP applications is simplified, since the view is cleanly separated from the
controller and the model. This not only facilitates changing BSP applications, but also
considerably improves their maintenance.

You have the option of generating program-driven layout. The HTML/XML output is
therefore created by program code instead of a page with scripting.

Navigation using the <bsp:goto> element and call using the <bsp:call> element. The
advantage of using <bsp:goto> navigation over redirect is that there is no additional
network traffic. Furthermore, you remain in the same work process, which can have
advantages for creating objects and memory space. The call using <bsp:call> element

Web Application Server

620 SP 9

331

SAP Online Help

25.10.2002

is more variable than adding them using INCLUDE directives, since it is triggered at
runtime.
With the call option using <bsp:call>, you can also distribute the user interface into
components [page 349].

Optimized performance due to fewer redirects.

Intuitive and east-to-use interface for application development.

Previous BSP applications, that is, BSP applications without MVC, can still be
executed without requiring any changes. MVC does, however, have various
advantages with more complex applications. See Using MVC for BSP [page 336].

Integration
The MVC design pattern is integrated in the BSP programming model and the Web
Application Builder of the ABAP development environment (Transaction SE80) from SAP
Web Application Server 6.20.

Functions
A BSP application can consist of one or more controllers and Business Server Pages, as well
as known elements such application classes, MIME objects and themes. A BSP can have
different characteristics; it is either a page with flow logic (as before), or a view or a page
fragment:

BSP Application

Seite mit Ablauflogik


Seite mit Ablauflogik
Page with Flow Logic
Layout
Layout
Layout
Eventhandler
Eventhandler
Event Handler
Auto-/Seitenattribute
Auto-/Seitenattribute
Auto/Page Attribute

Application Class

Controller
Controller Class
URL

View
View
View

Layout
Layout
Layout
Seitenattribute
Seitenattribute
Page Attribute

Business Server Page


(BSP)

Seitenfragment
Seitenfragment
Page Fragment

Within a BSP application, there can be several controllers, several views and several pages
with flow logic.
Controllers
A controller is the instance of a central controller class. In the BSP-MVC environment, each
controller is directly or indirectly derived from the same base class CL_BSP_CONTROLLER2
[page 361], where the central method is DO_REQUEST.

Web Application Server

620 SP 9

332

SAP Online Help

25.10.2002

There is a URL for every controller that can be addressed externally, such as using a
browser. A controller can therefore be used as the initial point of entry to a BSP application.
The mapping of the URL to the controller class is determined in the BSP application.
A controller is the controlling instance in the MVC design pattern, where it also acts as the
controlling mechanism. It carries out the following tasks:
It provides the data
It is responsible for selecting the correct layout
It triggers data initialization
It executes input processing
It creates and calls a view instance
Layout selection
A controller will usually call a view instance for creating the HTML / XML output. The
controller can call a view that is created using a factory method. The theme or the browser
variant, for example, can be used here as the selection criteria. If a controller passes the
control to a view, it can and should set attributes to the view. These attributes may just be
data, or a reference to one (or, in extreme cases, several) model(s). A reference to the
controller is automatically transferred.

A controller has access only to views in its own application.


A controller can, however, delegate processing to another controller, and this
controller can be located in a different application.
A controller should not work with too many views, since all of these requests are processed
centrally. On the other hand, the controller should jump to all views that have the same or
very similar input processing.
Data provision
Although a controller does not have any pre-defined attributes, they can be set and read
using generic methods. However, a controller should provide a method init_attributes,
which is responsible for filling the attributes. There is a service method that facilitates filling
the attributes.
Event handling
The controller also takes care of event handling. It takes on all of the tasks that were
executed in the previous BSP programming model by the event handlers [page 213]: It carries
out initialization and request processing, manages data transfer and is responsible for
managing views and controlling a views lifetime.

Redirects from the controller or page to the controller or page can be easily
implemented. See also Navigation [page 344]

If it cannot be decided until input processing which page should follow, we


recommend that you let the controller branch to different views (for example, if it
is checked internally whether the user has registered as a customer, and the
corresponding data is then queried).
A controller can also be used to delegate control over screens to the sub-controller. A
controller can delegate the control for a whole screen or a screen section to one or more
different sub-controllers. This can result in a complex tree structure of controllers and
components [page 349] can be formed (that consist of both cascading controllers as well as
their corresponding views).

Web Application Server

620 SP 9

333

SAP Online Help

25.10.2002

You can find information about the life cycle of controllers in Lifetime [page 345].
View
Views are only responsible for the layout; they visualize the application data. Views are very
much like pages, although they do not have event handlers nor auto-page attributes, nor their
own URL. Unlike auto-page attributes, normal page attributes can be used, which are then
filled by the controller. Controllers should control calling views and communicate with a
model.
If the type of controller class is known for a view (see the Properties tab for the view), the view
can also access the attributes of the controller class.

You can use the navigation modeler to call the view.


You can find information about the life cycle of views in Lifetime [page 345].
Models
The model is used to obtain all necessary application data from the database. It represents
the internal data structures and corresponds to the application class [page 207] used in the
remaining BSP programming model. The model is responsible for carrying out the central
actions of reading, modifying, blocking and saving data.
When used with controllers, this controller can create a reference to a class that is used as a
model. Class CL_BSP_MODEL is available for this (see also Data Connection [page 346]).

MVC in BSP Applications


Eventhandling
handling
Event
Updateapplication
applicationdata
data
Update
Determine
the
control
flow
Determine the control flow
Request

Controller
Set

Model
Get
Response

Definethe
theapplication
applicationdata
data
Define
Usualconnection
connectionto
to
Usual
businessfunctionality
functionality
business

View
Visualizedata
data
Visualize

Control flow
Data flow

For more information, refer to:


Using MVC for BSP [page 336]
Class CL_BSP_CONTROLLER2 [page 361]
Navigation [page 344]
Lifetime [page 345]
BSP Component Call Options [page 343]

Web Application Server

620 SP 9

334

SAP Online Help

25.10.2002

Components [page 349]

Activities
Creating a Controller [page 337]
Creating a View [page 338]
Calling a Controller [page 339]
Calling a View [page 340]
Creating Error Pages [page 341]

A simple Tutorial [page 369] is available for your first steps with the MVC design
pattern.
The general bookshop tutorial for BSP contains a more extensive MCV tutorial:
Our Online Bookshop Using MVC and HTMLB [External documentation].

Example
You can find an example of MVC in the system in BSP application ITMVC2 or in package
SBSP_MVC.
Furthermore, the following Architecture Examples [page 365] are outlined:

BSP Application with Controllers and Views [page 365]

BSP Application with Several Views per Controller [page 366]

Combination of the Previous Examples [page 367]

Calling Controllers of Other Applications [page 367]

Calling Several Controllers from a View [page 368]

MVC Design Pattern


The Model View Controller (MVC) design pattern contains a clear distinction between
processing control, data model and displaying the data in the interface. These three areas
are formally distinguished from each other by three objects: model, view and controller. As
a result, you can easily split Web applications into logical units.
The model is used as an application object of the application data administration. It responds
to information requests about its status, which usually come from the view, as well as to
statements for status changes, which are usually sent by the controller. In this way, only the
model is used to process data internally, without making reference to the application and its
user interface.
There can be different views for a model, which can be implemented using different view
pages.
The view handles the graphical and textual output at the interface and therefore represents
the input and output data in each interface element, such as pushbuttons, menus, dialog
boxes and so on. The view takes of visualization. To visualize the status, the view queries the
model, or the model informs the view about possible status changes.
The controller interprets and monitors the data that is input by the user using the mouse and
the keyboard, causing the model or the view later to change if necessary. Input data is
forwarded and changes to the model data are initiated. The controller uses the model

Web Application Server

620 SP 9

335

SAP Online Help

25.10.2002

methods to change the internal status and then informs the view about this. This is how the
controller determines reactions to the user input and controls processing.
The view and the controller together form the user interface.
Since the model does not recognize either views or the controller, internal data processing is
detached from the user interface. As a result, changes to the user interface have no effect on
internal data processing and the data structure. You also have the option, however, of
displaying the data in different formats; you can display election results as a table, a bar chart
or as a pie chart.
You can find additional information about the MVC design pattern on the Internet and in
current specialist literature.

Using MVC for BSP


Uses
All BSP applications that you created with SAP Web AS 6.10 can also be executed without
MVC. In general, you do not need to change anything.
The previous BSP implementation model gives you the option of controlling event handling
and navigation using redirects.
The MVC design pattern provides you with various advantages, so that you can consider
converting to MVC in the following cases:

If your pages are dynamically composed of several parts (components)


A controller can assemble a page from several views. As a result, the layout is
componentized [page 349].

If input processing is so complex that it should be subdivided into different methods


A controller offers great flexibility, especially during input processing, since you can
create and call new methods.
If the system cannot decide which page comes next until input processing, we
recommend that you let the controller branch to different views.

If redirects using navigation can lead to performance problems (such as slow diversion)

If visualization logic is fairly important, since you can use MVC to separate the logic from
the layout

If the layout from a different person is being processed as the visualization logic

If parts of the layout should be created by the program, such as by a generating program
or an XSLT processor

Combination of MVC with BSP


You can combine the technology of the previous implementation model for BSPs with the new
MVC design pattern.

In an application, there may be pages with flow logic as well as controllers and views

The views can only be called by the controllers.

Redirects from pages to controllers and back can take place with the help of redirect
using the navigation methods.

In the page layouts you can use the <bsp:call> element or the <bsp:goto> element
to call a controller. You cannot use these elements to call pages.

Web Application Server

620 SP 9

336

SAP Online Help

25.10.2002

Process

Use the top controller as a point of entry to your BSP application and its process flow.
First create a controller (see Creating Controllers [page 337]).

Then a call a view from this top controller. Next create a corresponding view (see
Creating Views [page 338]).

Now test [page 338] your controller.

Then call the controller or the sub-controller (see Calling Controllers [page 339]), and
then the view (see Calling Views [page 340]).

If necessary, you can also create error pages [page 341].

Creating a Controller
Use
You create a controller to use a Model View Controller [page 331] design pattern in your BSP
application. You can use a controller for the initial access (see also Testing Controllers [page
338]).

Prerequisites
You are in a system from SAP Web AS 6.20.

Procedure
1. Use the Web Application Builder in the ABAP Workbench (Transaction SE80) to create a
controller object as a sub-object of your BSP application.
In doing so, you determine the controller name and the class name of the controller.
The URL is automatically inserted from the name of the BSP application and the
controller name.
2. In the Class Builder (Transaction SE24), create the class that is derived from
CL_BSP_CONTROLLER2 [page 361].

If you create your class directly from the Web Application Builder by double-clicking
on the class names, then the inheritance of CL_BSP_CONTROLLER2 has already
been configured.
3. Overwrite some of the methods of your class, especially DO_REQUEST.
You can find additional information about these methods in
CL_BSP_CONTROLLER2 [page 361] and Process Flow [page 351].
4. Save and activate your class and your controller.

Example
You can find examples of controllers in BSP application ITMVC2.

Web Application Server

620 SP 9

337

SAP Online Help

25.10.2002

Creating a View
Use
You create views to use the view of the Model View Controller [page 331] design pattern in
your BSP application.

Prerequisites
You are in a system from SAP Web AS 6.20.

Procedure
4. Use the Web Application Builder in the ABAP Workbench (Transaction SE80) to create a
page with the page type View as a sub-object of your BSP application.
5. Specify the layout and any attributes that may be required.
6. Save and activate your view.

Example
You can find examples of views in BSP application ITMVC2.

Testing Controllers
Use
You can use a controller as an initial point of entry to your BSP application. In the BSP
programming model without MVC, you have always used a central page as the initial page
that you called start.htm, for example. Use the main controller instead in connection with
the MVC design pattern.

Prerequisites

You are in a system from SAP Web AS 6.20.

You have successfully activated your BSP application and the controllers and views to be
tested.

Procedure
1. Place your cursor on the top controller in your BSP application.
2. Click on

(Test/Execute) in the application toolbar.

The browser starts and a logon screen may be displayed.


3. Log on to the system if this is necessary.

Result
The selected controller is started in the browser.

Web Application Server

620 SP 9

338

SAP Online Help

25.10.2002

Calling (Sub) Controllers


Use
Sub-controllers can be instantiated and called by a subordinate controller (main controller) or
by a view or a page.

We recommend that a subordinate controller in method DO_INIT creates a subcontroller, sets the parameters accordingly and then calls the sub-controller from
the appropriate view.

Prerequisites

You are in a system from SAP Web AS 6.20.

You have crated at least one controller [page 337] for your BSP application, or at least a
main and a sub-controller.

Calling a Controller
1. Create the controller instance. You have the following options:

data: l_ctrl type ref to cl_bsp_controller.


l_ctrl = create_controller( key = navigation_key ).
or

l_ctrl = create_controller( application_namespace = 'fred'


application_name = 'hugo' controller_name = 'do_something.do'
).
application_namespace and application_name are optional. Unless you
specify otherwise, the system uses the current values.

You can also specify each of the controller IDs.


2. If necessary, set the request parameters:
l_ctrl->do_initattributes( ).
3. Set additional attributes:
l_ctrl->set_attribute( name = name value = value ).
4. Call the request:
call_controller( l_ctrl ).

Calling (Sub) Controllers


1. Instantiate your sub-controller.
Create your sub-controller in method DO_INIT:
subcontroller = create_controller (controller_name = name.do
controller_id = 'id' ).
Example:
flightdetails ?= create_controller( controller_name =
'flightdetails.do'
controller_id = 'fld' ).
Ensure that the controller_id is specified.

Web Application Server

620 SP 9

339

SAP Online Help

25.10.2002

2. Call your sub-controller.


a. You can execute the call from the controller.
This makes sense in particular if the calling controller does not control a layout. There
are two call options here:

data: l_ctrl type ref to cl_bsp_controller.


l_ctrl = create_controller( key = navigation_key ).
or

l_ctrl = create_controller( application_namespace = 'fred'


application_name = 'hugo' controller_name =
'do_something.do' ).
application_namespace and application_name are optional. Unless you
specify otherwise, the system uses the current values.

b. You can execute the call from the view. There are three call options here, which are
all implemented using the <bsp:call> BSP element. The comp_id used here
corresponds to the controller_id from create_controller.

<bsp:call comp_id = />


Note that the instantiation using the controller_id must have already taken
place.

<bsp:call url = comp_id = />


A controller instance is generated if no controller is created under the comp_id.

<bsp:call key = comp_id = />


A controller instance is generated if no controller is created under the comp_id.
The key is taken from the navigation table.

3. Determine the parameter transfer.


a. You can execute the parameter transfer from the controller.

sub_controller -> set_attribute (name value)

To do this, use any public method of the sub-controller if you know its class. Of
course, you can also set the sub-controllers public attributes directly.

b. You can execute the parameter transfer from the view.


<bsp:call>
<bsp:parameter name = value = />
</bsp:call>

Calling a View
Prerequisites

You are in a system from SAP Web AS 6.20.

You have created at least one view [page 338] for your BSP application.

Procedure
1. Create the view instance.
data: l_view type ref to if_bsp_page.
l_view = create_view( key = navigation_key ).
or

Web Application Server

620 SP 9

340

SAP Online Help

25.10.2002

l_view = create_view( view_name = 'next.htm' ).

Note that you can call views only from your own application.
2. Set the attributes of the view:
l_view->set_attribute( name = 'model' value = my_model_instance
).
or
l_view->set_attribute( name = 'hugo' value = 'Hugo-Text' ).
3. Call the view layout:
call_view( l_view ).

Creating Error Pages


Use
If on a page that contains flow logic, a view, or a controller, a runtime error occurs, you can
assign an error page to it. When a runtime error occurs during execution of this (other) page
or this controller, the system automatically processes the assigned error page and sends it to
the browser. If no error page is assigned to a page/a controller, in case of a runtime error the
system displays a standard page. If runtime errors occur in a called controller or view and
there is no error page, this section remains empty.

Prerequisites

You created the page (the controller) you want to use as error page. See also: Creating
Pages [External documentation] or Creating Controllers [page 337].

You cannot assign an error page to a page or a controller that itself is marked as error
page.

With views you must not assign a controller class, because an error page is always called
implicitly by the BSP runtime.

Procedure
To identify a page / a controller as an error page:
1. Select the page or the controller for your BSP application.
2. Go to the properties display and switch to Change mode if necessary.
3. In section Error Handling, mark the checkbox Is Error Page.
4. Save your entries and activate the page or controller.

Result
You can now assign this page or controller as Assigned Error Page to another page or
another controller.

Example
The BSP application ITMVC contains an example of how to implement and use an error page.

Web Application Server

620 SP 9

341

SAP Online Help

25.10.2002

From Pages to Controllers


With a normal page, the presentation is determined by the layout, whilst in the MVC design
pattern, views specify the presentation. With normal BSPs, predefined event handlers are
available to process events. With MVC on the other hand, events are handled by controllers.
Normal pages are different from controllers especially with regard to event handling and
programming. The events of the pages can be matched with the controller methods:

Page events and main controller methods

Page events and sub-controller methods

Page events and main controller methods

Page
OnCreate
OnInitialization

Main Controller
DO_INIT
DO_INITATTRIBUTES

OnRequest
DO_HANDLE_DATA

OnInputProcessing
DO_REQUEST
OnLayout

DO_HANDLE_EVENT
DO_FINISH_INPUT

OnManipulation

View )

A main controller handles both input and output processing, where it uses the central method
DO_REQUEST to call the methods specializing in input processing: DO_HANDLE_DATA,
DO_HANDLE_EVENT and DO_FINISH_INPUT. In method DO_REQUEST, input processing
must be triggered using DISPATCH_INPUT. This corresponds to the processing steps in the
purely page-based BSP programming model that are executed using events OnRequest
[page 214], OnInputProcessing [page 216], OnManipulation [page 217] and Layout [page
212].
Page events and sub-controller methods
From method DO_REQUEST, the three following methods required for input processing are
called:

DO_HANDLE_DATA

DO_HANDLE_EVENT

DO_FINISH_INPUT

Web Application Server

620 SP 9

342

SAP Online Help

25.10.2002

Page
OnCreate
OnInitialization
OnRequest

Sub-Controller
DO_INIT
DO_INITATTRIBUTES
DO_HANDLE_DATA

OnInputProcessing

DO_HANDLE_EVENT
DO_FINISH_INPUT

OnLayout
DO_REQUEST (

View )

OnManipulation

Call Options of BSP Components


In general, views can only be called from controllers. The only exceptions are error pages.
Controllers can be called from controllers, or from the layout methods of pages and views.
The calls can be considered as forwarding a request or as adding a page fragment.
Calls that are made from a controller are identical. Only the environment is different,
particularly depending on whether or not data was already written in the HTTP response, and
whether additional data is subsequently added in the HTTP response.
The calls are different from views or pages. You can use the following elements of BSP
extension bsp to branch from a view or a page to a controller:

<bsp:goto>
Forward

<bsp:call>
Insert

These two elements are based on the same technology as when a controller is called by a
controller. As inner elements, both can only have elements of type <bsp:parameter>. You
hereby determine the parameters that are passed to the controller.

Web Application Server

620 SP 9

343

SAP Online Help

25.10.2002

Navigation
There are two options for navigating to a different URL:
navigation->goto_page for a page or a controller
<bsp:goto> element for a controller.

navigation->goto_page
With goto_page, there is a redirect to the specified page (or to the controller), that is, the
browser is informed that it may request a different page. There is then a new browser request
to the destination page.
This has the following effect:
The browser recognizes the URL for the destination page, since it requested it itself. In
the page does not run in a frame, its URL is displayed in the address line of the browser.
An additional browser request is required, which leads to increased network load. Even if
the amount of data is extremely small, this may slow down performance with very slow
networks (such as via satellite).
In a stateless case, all temporary data from previous processing is lost.

<bsp:goto> Element
With the <bsp:goto> element, the new controller or view is called to provide the content for
the current request.
This means that:
The browser does not recognize the URL for the destination page, but tries to
communicate with the existing page.
No additional browser request is required.
If no target has been entered in the form of the target page, the request that results
from sending the form (or also from a refresh) is sent to the requesting page. As a
result, the target page only has the task of creating the HTML (view) and does not usually
have to worry about input. The calling page is responsible for this and thereby takes over
the controller functionality.
The work process does not change, that is, the context remains the same even in a
stateless application and you can therefore access the data and objects that have already
been created.
The controller must be able to use the input to decide on its current status if it should
display several views after each other. It should not store this status on the server,
otherwise the Back processing would not function correctly. With different URLs, this is
easier using redirects.
When you use different views, the URL does not change. As a result, you cannot use
bookmarks on these pages.
What does page_name point to?
runtime->page_name always points to the externally addressed page or the controller.
You get the name and URL using page->get_page_name() or page->get_page_url().
Lifetime of the View that is Called
The lifetime of the view that is called is limited to the call only. For more information, see
Lifetime [page 345] and Note 545847.

Web Application Server

620 SP 9

344

SAP Online Help

25.10.2002

Lifetime
Controllers
You determine the lifetime of components or their controllers in the usual way using the
Properties tab page of the controller. You can specify the lifetime as one of the following three
options in Status:

To page change

For the duration of the request

For the duration of the session

The setting is usually To page change.


By default, the lifetime of controller instances is limited to the one call. If the controller
instance is passed with id, then its lifetime is the same as that specified in the controllers
properties (Properties tab). The id can be specified as follows:

From a page or a view:

From a controller or a page event: create_controller(controller_id=id)

<bsp:call/goto comp_id = id>

The controller_id or the comp_id of the <bsp:call> element must not


contain an underscore (_ ).
The underscore is reserved as a separator between controllers.
The lifetime of the top-level controller ranges from the first CREATE_CONTROLLER for a subcontroller to DELETE_CONTROLLER for the sub-controller.
If sub-controllers should occasionally be hidden, so that they are not involved in event
handling for a while, then use method CONTROLLER_SET_ACTIVE. A controller that is set to
inactive in this way will not be called for input processing.

The controller is only hidden; the controller instance is not deleted.

Views
This section concerning the lifetime of views concerns the use of MVC in SAP
Web AS 6.20 up to and including Support Package 9.
Unlike controllers or pages, views have only a very short lifetime. Their life cycle looks as
follows:
1. They are created.
2. They are supplied with parameters.
3. They are called.
4. They are now no longer required and therefore expire, since views cannot be reused.
Views therefore only exist for the duration of the call, that is, they are destroyed after
they have been called.
As a developer of BSP applications with MVC, you must explicitly recreate the view, since you
cannot reuse it in a controller. The following provides an example of correct and incorrect
coding:
Use:

Web Application Server

Do not use:

620 SP 9

345

SAP Online Help

25.10.2002

DATA: view TYPE REF TO if_bsp_page.

DATA: view TYPE REF TO if_bsp_page.

view = create_view( view_name =


'main.htm' ).

IF view IS NOT BOUND. " or IS NOT


INITIAL.
view = create_view( view_name =
'main.htm' ).
ENDIF.

In any case, the view must be explicitly recreated before it is used.


DATA: view TYPE REF TO if_bsp_page.
view = create_view( view_name = 'main.htm' ).
" ... set attributes ....
call_view( page ).
CLEAR view.

Data Binding
To make programming easier for you with the MVC design, the framework for the model of an
application provides you with basic class CL_BSP_MODEL, which you can use in your own
model class as a class that passes on its properties. The model class represents the data
context of your application and, as a result, receives a copy of the data (or references to the
data) that are relevant for the view from the database model.
The model class provides:

The data that are used for the views, with the corresponding type and data Dictionary
information.

Input conversions

Information about input errors that occurred for which data

A controller can instantiate a model class or even several model classes (see also Calling the
Model Class Using the Controller [page 349]). The controller has a list of all model instances,
analogous to the list of sub-controllers.
The controller assigns unique IDs to each model instance.

If you are using the MVC Design Pattern, you do not need to use the Application
Class [page 207]. Instead of the usual application class with purely page-based
BSP applications, you should use controllers and model classes in the MVC
environment.
Data binding is particularly important with HTMLB extension elements inputField and
label (see also the documentation for these elements in the system). It is also implemented
for HTMLB elements dropdownListBox, radioButtonGroup, checkbox, textEdit and
tableView.
A model class can either be designed quite simply or it can be used with more complex
application cases.

Web Application Server

620 SP 9

346

SAP Online Help

25.10.2002

Simple Model Class


Data binding is important for transmitting values for output data. Add the data that is required
by the view to your model class as attributes. These attributes are all from the visibility range
public and can be as follows:

Simple variables

Structures

Tables

In the most simple case, the model class has these attributes only and so can easily be used
for data binding as part of a BSP application.
This type of simple model class provides the following functionality:

The controller can create a model instance and initialize the attributes, since they are
public attributes.

The controller transmits a reference to the model instance to the view.

The data binding to the model is specified in the view for each view element using a path
expression (//...).

Example:
A BSP application contains an input field that is implemented using HTMLB, in
which users can write data.
model is defined as a page attribute. For the input field you can then write:
<htmlb inputField value=//model/<Attribut>
This ensures that the content of value is bound to the corresponding attribute of
the model class.
The process flow is now as follows:
i.

The content of the attribute is assigned to the input field value using the above
statement.

ii.

This generates the ID from the model.

iii. Additional properties are also generated, such as whether F4 help is available or
whether fixed values exist.
iv. User input is transferred to the model class at the next request.
v.

Data conversions including connection to the Dictionary (conversion exists, for


example) are automatically executed by the base model class.
In the default case, if a conversion exit for a field exists in the ABAP Dictionary,
this conversion exit is called. All data contained in the ABAP Dictionary structure
for the field are available. If, however, separate setter/getter methods (see the
following section) are written, the conversion exit can be switched off.

If necessary you can also add your own methods to your model class for further processing
attributes.

Complex Model Class


It is possible that simple model classes are not sufficient for your requirements. This may be
the case, for example, if you are working with generic data or if you need special methods for
setting (SET) and getting (GET) attributes. You can therefore use these methods to determine
your own implementations that are important for your specific application.
In these types of applications, the base class contains copy templates for the setter and getter
methods: _SET_<attribute> and _GET_<attribute> . All of these templates begin with
_. The naming conventions for the actual methods are as follows:

Web Application Server

620 SP 9

347

SAP Online Help

25.10.2002

Naming convention for setter methods:


SET_<attribute> for a field
SET_S_<attribute> for a structure
SET_T_<attribute> for a table

Naming convention for getter methods:


GET_<attribute> for a field
GET_S_<attribute> for a structure
GET_T_<attribute> for a table

An example of implementing a getter method for structure fields/structure


attributes:
method GET_S_FLIGHT .
field-symbols: <l_comp> type any.
assign component component of structure flight to
<l_comp>.
value = <l_comp>.
if component eq 'CARRID'.
translate value to lower case.
endif.
if component eq 'CONNID'.
shift value left deleting leading '0'.
endif.
endmethod.
The ABAP keyword assign component assigns the structure component
component for the structured field flight (with reference type sflight) to the
field symbol <l_comp>. The value of <l_comp> is output as follows: If the
structure component component points to an airline (CARRID), the name of the
airline is translated in lowercase. If the structure component component points to
a single flight connection (CONNID), then some of the introductory zeros may be
deleted.

Note that in an SAP Web AS System 6.30 and below, that when you use setter
and getter methods, the metadata must be explicitly procured by the getter
methods. The syntax for this is:
GET_M <attribute> for a field
GET_M_S_<attribute> for a structure
GET_M_T_<attribute> for a table
This is done automatically from SAP Web AS 6.30.
As soon as a setter or a getter method is set, it is used automatically.
Data binding is automatically available because the name is the same. In method
DO_HANDLE_DATA (see also Process Flow [page 351]) of class CL_BSP_CONTROLLER2
[page 361], all controllers automatically fill the form fields with data.
The path specifications for the model data have the following syntax:

Web Application Server

620 SP 9

348

SAP Online Help

25.10.2002

Simple field attribute


value=//<field name>

Structure attribute
value=//<structure name>.<field name>

Table attribute
value=//<table name>[<row index>].<field name>

Calling the Model Class by the Controller


Uses
A model class is called or managed by a controller, that is, a controller can hold one or
several model classes (or instances). The controller class provides methods for creating,
getting, setting and deleting this type of model class. There are also methods for passing
incoming data on to the correct model instance, which is identified by the model_id.

Components
Use
Complex BSP applications that are based on the MVC Design Pattern [page 331] have many
extensive components. Each individual part, consisting of a complex BSP application,
contains precise application logic and well thought out presentation logic. It makes sense to
create the individual BSP components as reusable modules. These reusable modules are:

Controllers

One or more views

A Model

Together they form a component.

Components are only available for stateful BSP applications.

Integration
The use of components is integrated in the MVC design pattern.

Prerequisites
You are in SAP Web AS 6.20.

Functions
A component consists of a controller, whose class is derived from CL_BSP_CONTROLLER2
[page 361], as well as one or more views, which can result in regular nesting. This is outlines
in the following graphic:

Web Application Server

620 SP 9

349

SAP Online Help

25.10.2002

Response

Request

BSP Controller
METHOD
DO_REQUEST
CALL_VIEW
CALL_CONTR

BSP View

METHOD
DO_REQUEST
...
CALL_VIEW

<form ...>
<input
...>
</form>

Komponente

BSP Controller

BSP View
<form ...>
<input
...>
</form>

Komponente

METHOD
DO_REQUEST
...
CALL_VIEW

BSP View
<form ...>
<input
...>
</form>

Komponente

BSP Controller
METHOD
DO_REQUEST
...
CALL_VIEW

BSP View
<form ...>
<input
...>BSP View
</form>
<form ...>
<input
...>
</form>

BSP Controller

Central features of components are:

With components, there are complex call sequences during an HTTP request.

The individual parts, of which a page in the browser consists, are dynamically assembled
during runtime.

One component can call a different component. It should therefore be placed in a view.
This is done using the <bsp:call> element.

Initialization can be called by the controller using method create_controller. This


method is available for all controller classes. It creates a controller or finds an existing
one.

The parent controller contains a list of the individual sub-controllers and forwards all input
to the relevant controller. This is done by prefixing all IDs with the path of the controller
IDs.

The controller has a hierarchical tree. Every controller controls its view or views, its model
as well as the list of sub-controllers.

Basis class CL_BSP_CONTROLLER2 controls the sub-controllters. The controller


developer is responsible for controlling the view and the model.

If you want to use data binding functionality, you can add a model class to your
component. For more information see Data Binding [page 346].

Activities
1. Create the top-level controller [page 357]
2. Create a component [page 358]
3. Call the component [page 358]
4. Determine the input processing [page 361]

Web Application Server

620 SP 9

350

SAP Online Help

25.10.2002

Process Flow
Uses
The methods of class Class CL_BSP_CONTROLLER2 [page 361] are used to create
components as part of the Model View Controller design pattern.

The whole hierarchy level is processed with every request.


The hierarchy itself is defined at output.

Process
1. First call DO_INIT.
2. Then call DO_INITATTRIBUTES.
3. Then call DO_REQUEST.
With a main controller, DO_REQUEST takes care of both input and output processing.
a. Input processing
The browser request is sent directly to the top-level controller. This dispatches
the input to the sub-controllers. Service function DISPATCH_INPUT is available
for this.
DISPATCH_INPUT reads the form fields from the request and dispatches them to
the sub-controller. Prefixes are added to the form fields.

The prefixes are written automatically for BSP elements, for example, by BSP
extension HTMLB.
If, however, you have pure HTML or HTML tags, then you must add the name of
the controller as a prefix to your input data. In this case, service function GET_ID
is available for adding prefixes.
All data that do not belong to one of the sub-components must be processed
using method DISPATCH_INPUT in the main controller. The following methods
are called:

DO_HANDLE_DATA

DO_HANDLE_EVENT

DO_FINISH_INPUT

These three methods are called by the parent controller only with the form fields
for the current controller.
b. Output processing
Determining output processes contains the output for the next page. A view is
created and displayed. Depending on the status of the top-level controller, you
can also set a sub-controller to inactive or create new controllers.
The process flow of the output is displayed in the following graphic:
Page Output

Web Application Server

620 SP 9

351

SAP Online Help

25.10.2002

Main Controller

Runtime

Controller0

View0

DO_REQUEST

Sub-Controller
Controller1
DO_REQUEST

View1

Sub-Controller
Controller1.1
DO_REQUEST

View1.1

Sub-Controller
Controller2
DO_REQUEST

View2

At output, DO_REQUEST carries out the following tasks:


i.

DO_REQUEST determines whether data must be fetched from the model or from
the global attributes.

ii.

DO_REQUEST fetches the table with the object keys from the top-level controller.

iii. DO_REQUEST requests a view.


iv. DO_REQUEST sets the correct attributes for the view.
v.

DO_REQUEST calls the view.

Handling events
If a component contains events, DISPATCH_INPUT calls the HTMLB manager. The HTMBL
manager collects the relevant information, including the ID, that is, the ID of the object that
triggered the event.
DISPATCH_INPUT then calls method DO_HANDLE_DATA. DO_HANDLE_DATA is called by all
controllers (that is, for all active components), that is, by the top-level controller as well as by
all sub-controllers. The model class is filled with DO_HANDLE_DATA (see also Data Binding
[page 346]): The system transfers form fields and messages for the global messages object
(see below).

If your model class is based on CL_BSP_MODEL and you have defined your setter
and getter methods accordingly, the form fields are filled automatically.
The process flow with DO_HANDLE_DATA is displayed in the following graphic:

Web Application Server

620 SP 9

352

SAP Online Help

25.10.2002

Page Input (DO_HANDLE_DATA)


Runtime

Controller1
FILL_VALUES

Controller0
DO_REQUEST
DISPATCH_INPUT
DO_HANDLE_DATA
DO_HANDLE_EVENT

HANDLE_EVENT
FINISH_INPUT_PROCE.

Controller1.1

DO_HANDLE_DATA

FILL_VALUES

DO_HANDLE_EVENT

HANDLE_EVENT

DO_FINISH_INPUT

FINISH_INPUT_PROCE.
DO_HANDLE_DATA

DO_FINISH_INPUT

DO_HANDLE_EVENT

Controller2

DO_FINISH_INPUT

FILL_VALUES
HANDLE_EVENT
FINISH_INPUT_PROCE.
DO_HANDLE_DATA
DO_HANDLE_EVENT
DO_FINISH_INPUT

Once DO_HANDLE_DATA has filled all data, method DO_HANDLE_EVENT is called for the
controller that is responsible for the input event. This also states the event ID and the event is
dispatched to the controller. DO_HANDLE_EVENT also outputs parameter GLOBAL_EVENT (a
string). If the event is an HTMLB event, object HTMLB_EVENT is filled accordingly.

Events are only dispatched to the relevant controller if the element ID was
assigned to the HTMLB element (attribute id).
DO_HANDLE_EVENT also has access to the global messages object and can carry out
additional steps if necessary. For example in the case of an error, this method can have data
displayed again.
The process flow with DO_HANDLE_DATA is displayed in the following graphic:

Web Application Server

620 SP 9

353

SAP Online Help

25.10.2002

Page Input (DO_HANDLE_EVENT)


Runtime

Controller1
FILL_VALUES

Controller0
DO_REQUEST
DISPATCH_INPUT
DO_HANDLE_DATA
DO_HANDLE_EVENT

HANDLE_EVENT
FINISH_INPUT_PROCE.

Controller1.1

DO_HANDLE_DATA

FILL_VALUES

DO_HANDLE_EVENT

HANDLE_EVENT

DO_FINISH_INPUT

FINISH_INPUT_PROCE.
DO_HANDLE_DATA

DO_FINISH_INPUT

DO_HANDLE_EVENT

Controller2

DO_FINISH_INPUT

FILL_VALUES
HANDLE_EVENT
FINISH_INPUT_PROCE.
DO_HANDLE_DATA
DO_HANDLE_EVENT
DO_FINISH_INPUT

Note that only a sub-controller is called here.


Method DO_FINISH_INPUT is always called (for every controller, that is, for all active
components). You can use it to react to events in a component that occur in a different
component. To do this, use parameter GLOBAL_EVENT, which is set in method
DO_HANDLE_EVENT. Using this global event, at the end of input processing each component
should know exactly which events are present and how to react to them.
The process flow with DO_FINISH_INPUT is displayed in the following graphic:

Web Application Server

620 SP 9

354

SAP Online Help

25.10.2002

Page Input (DO_FINISH_INPUT)


Runtime

Controller1
FILL_VALUES

Controller0
DO_REQUEST
DISPATCH_INPUT
DO_HANDLE_DATA
DO_HANDLE_EVENT

HANDLE_EVENT
FINISH_INPUT_PROCE.

Controller1.1

DO_HANDLE_DATA

FILL_VALUES

DO_HANDLE_EVENT

HANDLE_EVENT

DO_FINISH_INPUT

FINISH_INPUT_PROCE.
DO_HANDLE_DATA

DO_FINISH_INPUT

DO_HANDLE_EVENT

Controller2

DO_FINISH_INPUT

FILL_VALUES
HANDLE_EVENT
FINISH_INPUT_PROCE.
DO_HANDLE_DATA
DO_HANDLE_EVENT
DO_FINISH_INPUT

Global Messages
Parameter GLOBAL_MESSAGES is shared by all components. Use this parameter to handle
incorrect user input, for example to display that an error occurred, or that the end date
entered by the user is before the start date, and so on.
The main controller creates the global messages and forwards them to all sub-controllers. On
the other hand, the messages object [page 282] is local. If the local messages object is now
filled in a controller, then you can forward this information to the global messages object and
react to it using any component you like.

Controllers and Their IDs


Usually there is a main controller, a top-level view as well as different sub-controllers and
additional views.
A main controller first calls CREATE_VIEW, then SET_ATTRIBUTE for the view, and then
CALL_VIEW. The top level controller can also create sub-controllers. This is done using the
<bsp:call> element, which has the attributes PAGE and COMP_ID. Furthermore, the
embedded element <bsp:parameter> can also specify parameters for name and value.

Web Application Server

620 SP 9

355

SAP Online Help

25.10.2002

Main Controller
ControllerC0
DO_REQUEST

View0
<html>
<form>

</html>
Sub-Controller
ControllerC1
DO_REQUEST

View1

Sub-Controller
Controller1.1
DO_REQUEST

View1.1

<bsp:call page=subcontroller1.htm
comp_id=C1>
<bsp:parameter name =
value= />
</bsp:call>

The attribute output takes place either in the view or in the top-level controller.

COMPONENT_ID always identifies the controller. The COMPONENT_ID has a


reference to the controllers concerned.
In method CREATE_CONTROLLER this reference is parameter COMPONENT_ID,
and in the <bsp:call> element it is attribute COMP_ID:
When a controller is created, a reference is sent to the parent controller, which
has a list of all the sub-controllers that belong to it. Every sub-controller can query
its parent controller for the COMP_ID of each additional sub-controller.

Creating Your Own Components


Uses
You create components to use them independently as well as together with other components
for BSP applications. You can create a component for a search in an online shop, for
example, and create an additional one for the detail display of the article that was found.
When you develop components, you can also form teams, so that one team is responsible for
developing controllers, a different team is responsible for the views, and a third team is
responsible for developing the models.

Process
5. Create the top-level controller [page 357]
6. Create a component [page 358]
7. Call the component [page 358]
8. Determine the input processing [page 361]
Web Application Server

620 SP 9

356

SAP Online Help

25.10.2002

Creating the Top-Level Controller


Procedure
1. Create a BSP application and declare it as stateful.
You can find the checkbox for stateful on the Properties tab page as the ID Stateful.
2. Save your BSP application.
3. Create a controller within this BSP application.
a. Enter a unique class name for the controller.
b. Set the lifetime in the Status field to Session.
4. Save your controller.
5. Double-click on the controller class name.
6. The following dialog box asks if you want to create the class. Answer it with Yes.
You branch to the Class Builder.
7. Save your class.
8. On the Properties tab page, check that your class inherits properties from
CL_BSP_CONTROLLER2. If this is not the case, for example if your class inherits
properties from CL_BSP_CONTROLLER, then change the data for the class that passes
on the properties.
9. Branch to the Methods tab page.
a. In change mode, overwrite method DO_REQUEST using the icon

(Redefine):

method DO_REQUEST .
data: main_view type ref to if_bsp_page.
* if input is available, dispatch this input to subcomponent.
* this call is only necessary for top-level controllers.
* ( if this is not a top-level controller or no input is present,
*
this call returns without any action)
dispatch_input( ).
* if any of the controllers has requested a navigation,
* do not try to display, but leave current processing
if is_navigation_requested( ) is not initial.
return.
endif.
* output current view
main_view = create_view( view_name = 'main.htm' ).
call_view( main_view ).
endmethod.
b. If necessary, overwrite method DO_INIT.
c.

In order to react to user input, overwrite methods DO_HANDLE_DATA and


DO_HANDLE_EVENT.

10. Activate your class.


11. Create a view within your BSP application.

Web Application Server

620 SP 9

357

SAP Online Help

25.10.2002

a. In the following example, the view is called main.htm.


b. Fill the view layout with HTML coding or HTMLB coding.
c.

Save the view.

12. Activate and test your finished BSP application.


Continue by Creating Components [page 358].

Creating Components
Procedure
1. Create a controller (including classes) in a BSP application.
This controller may belong to an already existing BSP application or it can be located
in its own BSP application.

Note that the basic class of this controller and the top-level controller is class
CL_BSP_CONTROLLER2 (see also Creating Top-Level Controllers and Views [page
357]).
2. If this controller should always be used as the component controller, then change method
DO_REQUEST so that only views can be displayed. If not, DO_REQUEST would look
exactly the same as the DO_REQUEST from the top-level controller.
a. Overwrite methods DO_HANDLE_DATA, DO_HANDLE_EVENT and/or
DO_FINISH_INPUT.
These methods are called by the parent controller only with the form fields for the
current controller. All components share parameter GLOBAL_MESSAGES.
GLOBAL_MESSAGES is used to handle incorrect input.
Parameter GLOBAL_EVENT is set by method DO_HANDLE_EVENT and is used in
DO_FINISH_INPUT. The component developers should device how these values
should be set.
Methods DO_HANDLE_DATA and DO_FINISH_INPUT are called for all active
components. DO_HANDLE_EVENT is only called by the controller that is responsible
for the input event.
b. For every attribute that should be passed to this controller, create a public attribute or
a method.
3. Create one or several views.
4. Activate the views.
Continue by Calling the Components [page 358].

Calling Components
Use
You can call a main controller, sub-controller in two ways:
Web Application Server

620 SP 9

358

SAP Online Help

25.10.2002

A. By creating the sub-controller in a method of the main controller


B. By creating the sub-controller from a view

Option A is more flexible than Option B, especially if the sub-controller should be


initialized once only in method DO_INIT.

Procedure
Option A
1. In method DO_INIT or DO_REQUEST, for example, add the following coding:
...
data: addresscontroller type ref to CL_C_MYPROJ_ADDRESS.
* create the controller
addresscontroller ?= create_controller(
controller_name = 'address.do'
component_id = 'ad'
).
* set some attributes with a self defined method
addresscontroller->Init_data( ... ).
...
or
...
data: subcontroller type ref to CL_BSP_CONTROLLER2.
* create the controller
subcontroller ?= create_controller(
controller_name = 'address.do'
controller_id = 'ad'
).
* set some attributes with standard method
subcontroller->set_attributes( name = 'address'
value = ship_address ).
...
2. Call the controller in the view.
Two components are called in the above example: the address component
(address.do) and the flight component (flights.do).
COMPONENT_ID identifies the controller. In method CREATE_CONTROLLER this is the
parameter COMPONENT_ID, and in <bsp:call>-element this is the attribute
COMP_ID:
<%@page language="abap"%>
<%@extension name="htmlb" prefix="htmlb"%>

Web Application Server

620 SP 9

359

SAP Online Help

25.10.2002

<%@extension name="bsp" prefix="bsp"%>


<htmlb:content id="ComponentTest" >
<htmlb:page title = "Component Test">
<H1>Component Test</H1>
<htmlb:form id="myFormId" method="post">
<htmlb:tray
id
= "tray1"
title
= "Address"
design
= "form"
width
= "350"
isCollapsed = "false" >
<bsp:call url="address.do" comp_id="ad">
</bsp:call>
</htmlb:tray>
<htmlb:tray
id
= "tray2"
title
= "Flights"
design
= "form"
width
= "350"
isCollapsed = "false" >
<bsp:call url="flights.do" comp_id="fl">
</bsp:call>
</htmlb:tray>
<p>
<htmlb:button id="SAVE" text="SAVE DATA" onClick="SAVE" />
<htmlb:button id="CANCEL" text="CANCEL" onClick="CANCEL" />
</htmlb:form>
</htmlb:page>
</htmlb:content>

Option B
In this option, you do not need to create the sub-controller in the coding of the main
controller. Instead you should only add the parameters to the view call, which then creates
and calls the controller. In the following example, ship_address is an attribute of the view
and is set by the controller:
<%@page language="abap"%>
<%@extension name="htmlb" prefix="htmlb"%>
<%@extension name="bsp" prefix="bsp"%>
<htmlb:content id="ComponentTest" >
<htmlb:page title = "Component Test">
<H1>Component Test</H1>
<htmlb:form id="myFormId" method="post">
<htmlb:tray
id
= "tray1"
title
= "Address"
design
= "form"
width
= "350"
isCollapsed = "false" >
<bsp:call url="address.do" comp_id="ad">
<bsp:parameter name="address" value="<%=ship_address%>"/>
</bsp:call>
</htmlb:tray>
<htmlb:tray
title
design
width

Web Application Server

id

= "tray2"
= "Flights"
= "form"
= "350"

620 SP 9

360

SAP Online Help

25.10.2002

isCollapsed = "false" >


<bsp:call url="flights.do" comp_id="fl">
</bsp:call>
</htmlb:tray>
<p>
<htmlb:button id="SAVE" text="SAVE DATA" onClick="SAVE" />
<htmlb:button id="CANCEL" text="CANCEL" onClick="CANCEL" />
</htmlb:form>
</htmlb:page>
</htmlb:content>
Continue by Determining Input Processing [page 361].

Determining Input Processing


Use
The browser sends its request to the top-level controller. This main controller dispatches the
input to the appropriate sub-controller. This is why it is necessary to call method
DISPATCH_INPUT in the top-level controller.

Procedure
Input processing consists of three steps:
1. Filling data
For every controller, method DO_HANDLE_DATA is called with a list of form fields that
should be handled by this method.
If an error occurs during the data conversion, then this method can also pass one or
more messages to the global error object (global_messages).
2. Handle event
Method DO_HANDLE_EVENT is called for exactly one controller. The event is passed
on and object htmlb_event is filled if it is an HTMLB-event. Method
DO_HANDLE_EVENT has access to object global_messages, in order to determine
the additional steps that are necessary, depending on the error. For example, in the
case of an error, you can specify that you want to display the data again. You can
also set a global_event using method DO_HANDLE_EVENT.
3. Finish input processing
For every controller, method DO_FINISH_INPUT is called with a global event, which
is set by the event handler method. The closing input processing is carried out here.

Class CL_BSP_CONTROLLER2
Overview
Class CL_BSP_CONTROLLER2 is used to create controllers and components [page 349].
Every controller class automatically inherits all methods and attributes from this central basic
class.

Web Application Server

620 SP 9

361

SAP Online Help

25.10.2002

If the basic class of your controller class displays CL_BSP_CONTROLLER instead


of CL_BSP_CONTROLLER2, change the inheritance hierarchy accordingly.
Class CL_BSP_CONTROLLER2 enables you to:

Retain a list of sub-controllers

Create unique IDs for the sub-controllers, where the sub-controller is assigned the
controller ID prefix

Use models

Forward data to the correct controller as well as fill model classes (if they exist)

Methods
Below you can find an overview of all methods in a controller class. Processing Process
provides details on the most important methods.
The individual methods can be separated into different categories:

Functions where overwriting is required


DO_REQUEST is the central method in a controller class.

You must overwrite this method.


In DO_REQUEST you specify the request processing, that is, this method is called for every
request. This method does the main work; in particular it should branch to the correct view.
DO_REQUEST can be used in two different areas:

If it is the top-level controller of a component, then this method handles both input and
output processing.

If it is a sub-controller of a component, then this method only handles output processing.

Functions where overwriting is recommended


You should overwrite these methods in order to determine input processing.
Method

Description

DO_HANDLE_DATA

Reacts to user input.


Processes data input for this component.

DO_HANDLE_EVENT

Reacts to user input.


Processes events if the component contains them.
Exactly one view controller is called to handle the
event, which contains an event such as a save
button, for example.

DO_FINISH_INPUT

Ends the input processing.

Functions where overwriting is possible


You can overwrite these methods in order to determine input processing.
Method

Description

DO_INIT

This method is called once at the start and is used


for initialization.

Web Application Server

620 SP 9

362

SAP Online Help

25.10.2002

This method behaves like a constructor method.


DO_INITATTRIBUTES

This method is called with every request and is used


to initialize the attributes. The parameters are read
from the request. In this method, you can also
execute initializations that are required for each
request.
You can also use this method to set additional
attributes. This method is not absolutely necessary,
since you can use DO_REQUEST to solve everything
that you can (theoretically) handle here.

Service functions
You can call these methods:
Method

Description

CREATE_VIEW

Creates or fetches a view instance


Use either the name of the view, or the object
navigation [page 280].

A view must always belong to the same BSP


application as its controller.
CALL_VIEW

Calls the request handler of the view instance.

CREATE_CONTROLLER

Creates or fetches a controller instance

CALL_CONTROLLER

Calls the request handler (method DO-REQUEST) of


the controller instance.

GET_ATTRIBUTE

Returns the specified page attributes.


Generic method for reading an attribute value.

GET_LIFETIME

Returns the lifetime of this page (only for the toplevel controller)

GET_PAGE_URL

Returns the URL of the page or the current controller

SET_ATTRIBUTE

Sets the specified page attributes.


Generic method for setting an attribute value.

SET_LIFETIME

Changes the lifetime of this page (only for the toplevel controller)

TO_STRING

Creates a formatted string

WRITE

Writes a formatted string in the output

GET_OUT

Fetches the current output writer

SET_MIME_TYPE

Changes the MIME type of the page or the content


type of the header field

INSTANTIATE_PARAMETER

Instantiates the parameter from the request using


the request data

SET_CACHING

Changes the caching values


There are two types of caching:

Web Application Server

620 SP 9

Browser cache

Server cache

363

SAP Online Help

25.10.2002

See also Caching BSPs [page 403].

You can only use limited caching here.


Note that the server cache is not user-specific.
If you change the page, you should reset the cache
that may be set.
DISPATCH_INPUT

Dispatches the input processing (only for the toplevel controller).


For each input, DISPATCH_INPUT calls the correct
methods in the correct sequence.
This method fetches data from the request.

This method does not have any attributes.


GET_ID

Calculates the ID from the specified ID and the


component ID

SET_MODEL

Creates and registers a model instance

CREATE_MODEL

Creates and registers a model instance

GET_CONTROLLER

Fetches a sub-controller

CONTROLLER_SET_ACTIVE

Sets a controller to active/inactive.


This is relevant with input processing, since you can
use it to hide a controller.
See also Lifetime [page 345]

DELETE_MODEL

Deletes a model instance

FILL_MODEL_DATA

Fills the model data

DELETE_CONTROLLER

Deletes a sub-controller

GET_MODEL

Fetches a model instance

IS_TOPLEVEL

Is this controller a top (main) controller (0: no, 1:


yes)?

IS_NAVIGATION_REQUESTED

Has a controller requested a navigation (0: no, 1:


yes)?

Framework functions
These methods are provided as part of the framework and are only included here for the sake
of completeness. They are not usually relevant for application development.
Method

Description

IF_BSP_DISPATCHER~REGISTER

Registers a sub-components

IF_BSP_CONTROLLER~FINISH_INPUT_PROCE
SSING

Processes or dispatches: end of input processing.

IF_BSP_CONTROLLER~FILL_VALUES

Processes or dispatches: handling values

IF_BSP_CONTROLLER~HANDLE_EVENT

Processes or dispatches: Handle event

GET_FIELD_COMPONENT

Finds components for a field name

GET_FIELD_MODEL

Finds model for a field name

Web Application Server

620 SP 9

364

SAP Online Help

25.10.2002

Methods DO_DESTROY and SUBSCRIBE are not relevant.

Examples of Architecture
Previous BSP Application
With SAP Web AS 6.10, normal BSP applications usually consisted of an application class
and several BSPs. Navigation between the pages was controlled using redirects.

BSP Application
Application
Class

Page 2

Navigation
using Redirect

Page 1

Page 4

Page 3

This is how it looks with SAP Web AS 6.20: BSP Application with Controllers and Views [page
365]

BSP Application with Controllers and Views


From SAP Web AS 6.20, you can combine controllers and views in a BSP application. You
navigate between the controllers and any pages that exist using redirect. Each controller can
have one (or several) model(s).
You can use redirect to navigate between the controllers. You call the views using a call.

Web Application Server

620 SP 9

365

SAP Online Help

25.10.2002

BSP Application
Application
Class

Direct Call
Controller 2
Model 2

Controller 1

Navigation
using Redirect

View 2

Model 1
Controller 3

View 1

Model 3
View 3
Page 3

With several views for a controller, the whole thing looks as follows: BSP Application with
Several Views per Controller [page 366]

BSP Application with Several Views per Controller


With a BSP application with controllers and views [page 365], an individual controller can also
call several views either sequentially after each other or alternately. With this example, you
always access it using a controller.

BSP Application
Application
Class
View 1

Controller

Direct Call

Model
View 2

View 3

Web Application Server

620 SP 9

366

SAP Online Help

25.10.2002

What does a combination of these two examples look like (this one here and BSP application
with controllers and views [page 365])? Like this [page 367].

Combination of the Previous Examples


You can combine the examples of a BSP application with several views per controller [page
366] with a BSP application with controllers and views [page 365] so that each view is
controlled by exactly one controller. Central distribution is carried out by a superior controller.

BSP Application
Application
Class
Model
Controller

Direct Call

Controller 3
Controller 1
Controller 2

Model 3

Model 1
View 3

Model 2
View 1
View 2

Does this also work with several BSP applications? Of course [page 367]!

Calling Controllers of Other Applications


You can also call controllers of other BSP applications:

Web Application Server

620 SP 9

367

SAP Online Help

25.10.2002

BSP Application 1
BSP Application 2

Application
Class
Model
Controller

Controller 1
Model 1

Controller X

Controller 2

Model X

Model 2

View 1

View X

View 2

Calling Several Controllers from a View


With this example, several controllers are called from a view using a BSP element.

There can also be a page in place of the calling controller and view (in the
graphic on the left-hand side). There cannot be a page, however, at the level of
the called areas (in the graphic on the right-hand side).
With help from the views that are allocated, these controllers provide the contents for a subarea of the main views. A reference to the model can also be specified with the call.

Web Application Server

620 SP 9

368

SAP Online Help

25.10.2002

BSP Application
<bsp:call URL="ControllerI1">
<bsp:parameter Name="Model"
Value="<%=Model1%>"/>
</bsp:call>

Controller I1

View I1
Model 1
Controller 1

Controller I2
Component 1
View 1

View I2

Component 2

Model View Controller Tutorial


Uses
In this tutorial you can use a simple example to run through the first steps with the Model
View Controller [page 331] design pattern for BSP.

The general bookshop tutorial for BSP contains a more extensive MCV tutorial:
Our Online Bookshop Using MVC and HTMLB [External documentation].

Prerequisites

You are in an SAP Web AS 6.20 system

You know how to use MVC for BSPs [page 336]

Functions
Creating a Controller [page 370]
Creating a View [page 372]
Calling a Controller [page 375]

Web Application Server

620 SP 9

369

SAP Online Help

25.10.2002

Creating a Controller
Prerequisites
You have created an empty BSP application for this tutorial.

Procedure
1. Create a controller within your BSP application.
To do this, choose Create Controller.

2. On the following dialog box, give the controller a name and add a short description.

3. Choose

4. On the following screen, assign a class name to the controller.


The class does not have to exist yet.

Web Application Server

620 SP 9

370

SAP Online Help

25.10.2002

5. You navigate to the Class Builder by double-clicking on the controller class.


If the class does not already exist, the system asks you if you want to create it.
Choose Yes so that you create a class with the specified name that is derived from
CL_BSP_CONTROLLER2.

Each controller class must be derived directly or indirectly from


CL_BSP_CONTROLLER2.
6. Choose the

symbol to branch to the change mode in your class.

7. Select method DO_REQUEST and choose symbol

to overwrite the methods.

8. Generate the required output.


In this example, it is simple HTML:
method DO_REQUEST .
write( '<html><body><H1>' ).
write( 'This is my very first controller' ).
write( '</H1></body></html>' ).
endmethod.
9. Activate your class and your BSP application.
10. Before you can test the controller, in Transaction SICF you must also activate the new
entry that was automatically created for your BSP application (see also Activating and
Deactivating an ICF Service [page 147]).
In Transaction SICF, select the entry for your BSP application and choose
Service/Virt.Host Activate.

Web Application Server

620 SP 9

371

SAP Online Help

25.10.2002

Confirm the following confirmation prompts.


11. You can now test the new controller page that you have created.

Result

Continue by creating a view [page 372].

Creating a View
Use
If you do not always want to use the write function to create the HTML page content (as
described in Creating a Controller [page 370]), and you want to create it as pure HTMLO
layout instead, then create a view that you can call from the controller.

Web Application Server

620 SP 9

372

SAP Online Help

25.10.2002

Procedure
1. Begin as if you are creating a normal page with flow logic in your BSP application.
To do this, choose Create Page.

2. In the following dialog box, enter a name and short description of the view and select
View as the page type:

3. Choose

4. Create the attributes for the variable parts of the view.

You cannot define auto-page attributes, since views cannot be called directly from the
browser.
Create the following attribute:

5. Define the layout as usual:


<%@ page language="abap" %>
<html>

Web Application Server

620 SP 9

373

SAP Online Help

25.10.2002

<head>
<link rel="stylesheet"
href="../../sap/public/bc/bsp/styles/sapbsp.css">
<title> Layout for Controller </title>
</head>
<body class="bspBody1">
</head>
<body class="bspBody1">
<H1>View Example</H1>
<H3>Hello, user <%= name%></H3>
</body>
</html>
6. Activate the view.
7. Finally, adjust the DO_REQUEST method to the controller class.
Here, the schema is always the same. First you create the view, then you set the
attributes, and then you call the view. (For the time being you can ignore the warning
concerning exception CX_STATIC_CHECK, or you can set a try-catch block
around the calls):
method DO_REQUEST .
data: myview type ref to if_bsp_page.
myview = create_view( view_name = 'view_test.htm' ).
myview->set_attribute( name = 'name' value = sy-uname ).
call_view( main_view ).
endmethod.
8. Activate your class and test your controller.

Result
You have created your own view for the layout.

Continue by Calling the Controller [page 375].

Web Application Server

620 SP 9

374

SAP Online Help

25.10.2002

Calling a Controller
Use
You can call a controller from a page with flow logic, or from a view.

Procedure
1. Create a page within your BSP application.
Ensure that you select Page with Flow Logic as the page type.
2. In the Tag Browser, select BSP extension bsp and drag it to the second line of your
BSPs layout under the page directive.

3. Now drag the <bsp:goto> directive of BSP extension bsp to the body of the HTML
layout and add the URL parameter.
The source now looks as follows:
<%@page language="abap"%>
<%@ extension name="bsp" prefix="bsp" %>
<html>
<head>
<link rel="stylesheet" href="../../sap/public/bc/bsp/styles/sapbsp.css">
<title> Initial page </title>
</head>
<body class="bspBody1">
<bsp:goto url="example.do"></bsp:goto>
</body>
</html>
4. You can now activate and test the page.
The page looks as follows:

Web Application Server

620 SP 9

375

SAP Online Help

25.10.2002

Ensure that the page you have tested looks exactly the same as when you tested the
controller. The URL is different, however. You can use View Source in the browser to
see that nothing remains of the HTML text from the BSP, but that only the content of
the view is displayed:
<html>
<head>
<link rel="stylesheet"
href="../../sap/public/bc/bsp/styles/sapbsp.css">
<title> Layout for Controller </title>
</head>
<body class="bspBody1">
</head>
<body class="bspBody1">
<H1>View Example</H1>
<H3>Hello, User GREBEL</H3>
</body>
</html>
5. You can now try out the difference between the <bsp:goto> element and the
<bsp:call> element.
If you use the <bsp:call> element instead of the <bsp:goto> element, the calling
page text remains the same. In the view that is inserted, you should therefore delete
the HTML text available on the outline page, otherwise these texts will be transferred
twice.
6. You can add another attribute to the controller. This is a public class attribute.
It is set using the <bsp:parameter> element. You can use it for example to control
which view is called, or this value can be passed to the view.

Web Application Server

620 SP 9

376

SAP Online Help

25.10.2002

Calling Java Beans


Use
In connection with the SAP J2EE Engine [page 101], which represents a Java server, from
SAP Web AS 6.20 you can call Enterprise Java Beans (EJBs) from ABAP.

Integration
An SAP system uses HTTP to connect to the SAP J2EE engine and calls a servlet. The bean
to be called is determined from the parameters specified with the call. Once it has been
converted to type string, the return parameter is sent back to the SAP system via XML.

Prerequisites

You are in an SAP Web AS 6.20 system.

File SAPWASCALLEJB.EAR is deployed on the SAP J2EE engine.

Functions
You can display a list of all beans by executing program BSPJAVABEAN.
List of all Beans

Web Application Server

620 SP 9

377

SAP Online Help

25.10.2002

Column

Explanation

Name of the bean on the server


All beans that are available are listed together with their parameters.

Type of bean
A bean can be stateful, stateless or it can be an entity bean.

Name of the generated class (if available) and parameter name.

See also:
Function group EJB_CATALOG

Activities
To generate a corresponding class, proceed as follows:

Web Application Server

620 SP 9

378

SAP Online Help

25.10.2002

1. Double-click on a bean.
This creates a corresponding proxy in the SAP system.
2. Accept or change the default class names on the following screen:
The class name consists of the prefix CL_EJB and the bean name.
The name is truncated if the name is longer than 30 characters.
You can also ignore the default name and assign another one to it.

Ensure that all classes that are generated in this context start with CL_EJB.
Furthermore, you should ensure that the return parameter of a bean in the ABAP
proxies that are generated is mapped to exporting parameters, due to technical
restrictions.
3. An HTTP client is generated in the class and the individual methods are implemented.
Collections, hashes and so on are mapped to ABAP tables of type string.
For more information, refer to:
The FLUSH Method [page 379]
Possible Return Values [page 380]

Example
This example of a call generated an object, and then calls and sets parameters for methods:
data: mystring type ref to cl_ejb_simplestringbean,
myinteger type ref to cl_ejb_simpleinteger,
myint type i,
myst type string.
call method mystring->returnstring
exporting par0 = a new string
importing return = myst.
call method myinteger->returninteger
importing return = myint.
call method cl_ejb_queue=>flush( ).

The FLUSH Method


Use
You use the FLUSH method to send the importing parameters of generated proxies to the
Java server.

Process

When these methods are called, this collects information about all of the ABAP proxies
that are called in a queue, whereby the call sequence is maintained.

The queue is sent to the Java server.

The corresponding Enterprise JavaBeans are called with the parameters that are
delivered.

Web Application Server

620 SP 9

379

SAP Online Help

25.10.2002

The return values (packaged in XML) are returned to the SAP system.

The advantage of this queuing is that a request is not sent to the Java server
each time a bean is called. This helps improve performance.
For more information see Possible Return Values [page 380].

Possible Return Values


Primitive types such as int, char, byte or float are converted to the corresponding ABAP
types. In ABAP, hashed tables, collections and vectors are converted into tables of type string
(Dictionary structures BSP_STABLE_2C and BSP_STABLE).
For all other Java objects, an object handler is returned instead of the object. The
corresponding methods of this object can be called using class CL_EJB_GENERIC_CALLER.

Example
data jobject type CL_EJB_JAVA_OBJECT,
result type I,
data par type bsp_n_v.
*

Create instance

create object jobject


exporting url = l_url
host = l_host
port = l_port.
*
*

Return object returns any Java object.


Reference to this object is stored in result.

result = jobject->returnobject( ).
*

Create instance of the generic caller

create object caller


exporting url = l_url
host = l_host
port = l_port.
*
*

Call method myMethod,


Parameters are specified in table PAR.

clear par. refresh par.


CALL METHOD CALLER ->GET_RESULT
EXPORTING
NUMBER = result
METHODNAME = myMethod
IM_PARAMS = par
RECEIVING
RETURN = par0.

Web Application Server

620 SP 9

380

SAP Online Help

25.10.2002

Session Handling
BSP applications can be implemented as both stateful and stateless applications. The term
stateless does not mean that request data for a running application is not retained on
principle; it refers to whether in the SAP Web Application Server the application context (also
called Roll Area [External documentation]) is retained for individual requests, or whether it is
released following each request.
If you want to keep large datasets about request limits in the server (in internal tables), this
can be done either by working in stateful mode, that is, retaining data using the Application
Class [page 207] or by Using Server-Side Cookies [page 384] in a stateless application.
Both ways have advantages and disadvantages, which are explained in the following
sections.
A running BSP application regardless of whether it is HTTP stateful or stateless is referred
to as a session from here on. The start and end of a session is determined either by the user
externally (compare System-Specific URL-Parameters [page 204]) or by the application itself
and then only the end is determined.
The following topics are dealt with:

Stateful BSP Applications [page 381]

Stateless BSP Applications [page 383]

Hybrid Forms [page 387]

Setting Stateful or Stateless [page 388]

Stateful or Stateless Programming? [page 388]

Stateful BSP Applications


A stateful BSP application is executed like a normal SAP transaction, independent of all
user interactions - in one single context (roll area). This means that data specified by the user
during the application execution or data determined by the application itself is available
potentially throughout the entire execution duration of the session.
Since the HTTP protocol itself operates in stateless mode and knows no implicit mechanism
to assign independent requests to a common logical session, the BSP runtime uses Session
Cookies [page 382] to group requests into one common session. The name of the cookie is
sap-contextid, the validity area is restricted to the URL of the BSP application. This means
that a BSP application can be executed within a browser only once at any one time. Different
BSP applications can operate in parallel in the same browser. Multiple users/browsers can
execute the same BSP application in parallel as often as required.

Advantage
The main advantage of stateful BSP applications is that they are simple to program. As usual,
you have access to data determined previously and reading or re-calculating data can often
be omitted. For database-intensive applications, this can lead to considerably better system
performance compared to a procedure where identical read operations have to be executed
for every request.

Disadvantage
This significant advantage is at the same time however a disadvantage the improved
runtime is offset by a larger memory requirement. The number of possible parallel sessions in
an SAP Web Application Server is restricted not least by the amount of available memory

Web Application Server

620 SP 9

381

SAP Online Help

25.10.2002

space. When this space is exhausted, no further sessions can be started and users cannot
log on.
A further advantage is the fact that, unlike SAPGUI, Web browsers do not log off servers, that
is, if users navigate in their Web browsers to a different Web site, the SAP Web Application
Server is not be informed. Thus, an open session cannot be terminated and is retained in the
application server until the context is released by the timeout mechanism. Since this can take
some time, scarce resources are unnecessarily blocked in the application server.

Note that with stateful applications, the application status can be easily
distinguished from the status users accept based on their interface. This can be
caused by users navigating in the browser history or using the browser Back
button - information that is not necessarily passed on to the server. So a user
may navigate back to a Web site and the Web site sends the information again
even though the application is expecting other requests. Measures are required
in the application to deal with this.
In the next release, we plan to provide at least one detection mechanism.
See also:
Stateless BSP Applications [page 383]
Hybrid Forms [page 387]
Setting Stateful or Stateless [page 388]
Stateful or Stateless Programming? [page 388]

Session Cookie
Definition
A cookie is an HTTP mechanism that enables an HTTP server to store limited amounts of
data in an HTTP client. This data can then be sent back to the server for requests based on
specific criteria.
There are two types of cookie: persistent cookies, which are usually saved on the hard disk of
the client until an expiry date and session cookies, which are not saved in the file system;
they are kept only in the memory of the client (for example, the Web browser) until this is
closed.
As such, session cookies involve no security risks and are deleted immediately the browser
window is closed. Some browsers now differentiate between these two cookie types and, if
required, only inform the user when persistent cookies are received, which require the users
confirmation.

Integration
The next version of the SAP Web Application Server will also support applications with no
cookies at all.

Web Application Server

620 SP 9

382

SAP Online Help

25.10.2002

Stateless BSP Applications


Stateless BSP applications only block resources on the SAP Web Application Server during
the time one single request is being processed. When the request has been processed, all
resources in particular the application context are returned to the system for use in other
requests.
Stateless applications allow - at least from the viewpoint of the memory resource optimal
scaling regardless of the number of users. On the other hand, releasing the application
context after every request may mean that identical data is read from the database and
formatted multiple times. In this respect, the runtime may offset the memory saving. This
should be evaluated and analyzed on a case by case basis.

Rule of Thumb: Stateful or Stateless?


As a rule of thumb, it is recommended that Internet scenarios used at the same time by a
large number of users operate in stateless mode. Stateful programming is recommended for
more complex applications that are used by a limited number of users in parallel and that
operate with data that is expensive to determine.

Retaining Information in Stateless Mode Through Multiple Requests


The question arises of how to save information in stateless applications, such as user entries,
across multiple requests despite the loss of the application context after each request. For
this purpose, you must program the following functions for the application. Possible technical
solutions include the following options:

Temporary (Invisible) Storage of Data on the Web Site Itself:


This can be done by means of what are called HTML hidden fields, for example:
<input type=hidden name="customerID" value="4711">

You can include hidden fields by implementing a page fragment, which is embedded
in each page of the application. You can easily define the attributes you want to save
in the application class itself. The page fragment is then embedded in each Web site.
The application attributes from the request (we are working in stateless mode) are
restored in the OnRequest [page 214] event handler of the page (or preferably in the
ONREQUEST method of the IF_BSP_APPLICATION [page 240] interfaces. You
should pay particular attention to hyperlinks and to including the parameters you want
to save, for example, in the query string part of the URL from the application.

Storing Data in Client-Side Cookies:


You must ensure that the size and number of cookies that can be saved in a Web
client/browser is strictly limited.

Server-Side Cookies:
The BSP runtime provides a generic mechanism known as server-side cookies
that can be used to efficiently store data types of any kind and number. For more
information see Class CL_BSP_SERVER_SIDE_COOKIE [page 230] as well as Data
Persistency With Server-Side Cookies [page 384].

Application-Specific DB Table for Temporary Data Storage


The application provides a database table specially designed to meet the specific
requirements of the data to be saved. Unlike server-side cookies appropriate typed
tables can be used here. These tables can provide for better performance than the
generic solution. However, this solution involves considerable application
programming (in particular, release of the database entry). The session ID can be
used to identify an entry and can be accessed through the programming interface
IF_BSP_RUNTIME [page 262].

Web Application Server

620 SP 9

383

SAP Online Help

25.10.2002

See also:
Stateful BSP Applications [page 381]
Session Cookie [page 382]
Hybrid Forms [page 387]
Setting Stateful or Stateless [page 388]
Stateful or Stateless Programming? [page 388]

Server-Side Cookies and Data Persistency


Use
You can use server-side cookies to make data persistent, especially page attributes.
To do this you use simple ABAP statements in the event handlers OnManipulation [page 217]
and OnRequest [page 214], combined with methods of the class for server-side cookies:

Using export you can store the data (strings) as a cluster in database tables and you
can transfer them back again using import.

Class CL_BSP_SERVER_SIDE_COOKIE [page 230] provides methods to set, fetch,


delete and manage cookies in the server.

Server-side cookies are persistent data, similar to the usual client-side cookies. Whereas the
size of cookies on the client is restricted to four kilobytes per cookie, 300 cookies in total, and
30 per server or domain, server-side cookies do not have any size or quantity restrictions.

Server-side cookies consist of large datasets that are customized and stored on
the server. They are not transferred between client and server.

Functions
In the specified event handlers you use the following ABAP expressions and class methods:

OnManipulation:

export (required page + controller + page attributes) to buffer


XSTRING.

CL_BSP_SERVER_SIDE_COOKIE->method for buffer(XSTRING).

OnRequest:

CL_BSP_SERVER_SIDE_COOKIE->method for retrieval(XSTRING).

import (required page + controller + page attributes) from


buffer XSTRING.

The steps listed here are explained in more detail in the example below.

Example
In the following example you can see how, in a BSP, simple ABAP statements are used to
group the page parameters (strings) using export in one object. The cookie is then stored
with method SET_SERVER_COOKIE of class CL_BSP_SERVER_SIDE_COOKIE. Similarly the
cookie can be fetched again with GET_SERVER_COOKIE and returned with import.

Web Application Server

620 SP 9

384

SAP Online Help

25.10.2002

Page Attributes
This example contains some important page attributes that are to be defined as persistent.
The list of page attributes looks like:
Page Attributes
Attribute Name

Auto

LAST_STRING_ADDE
D
NEXT_STRING

STRINGS

Typing Type

Reference Type

Description

type

STRING

Last string
added by user

type

STRING

Next string

type

STRING_TABLE

Table of strings

Not all page attributes should be persistent- only the strings added by users. They are
displayed in a table on the interface. Therefore, in this BSP application only the strings
LAST_STRING_ADDED and STRINGS are to be made persistent.

Event Handler
In this BSP application the following event handlers are important:

OnRequest [page 214]


This event handler is always triggered with inbound requests to restore the persistent
data.

OnManipulation [page 217]


This is the last event handler before the response is sent. In this event handler the
new values of the page attributes are stored in the form of server-side cookies.

OnManipulation is described first of all to explain the storage concept.


OnManipulation
In this event handler the values of specific page attributes are saved in the server-side cookie.
Both parameters are saved on the server and then combined in one object. The user details
are written to the page data using the ABAP statement export.

The export syntax is:


export object1 from F ... Objectn from F to data buffer F.
A data cluster is stored in data buffer f, which must be of type XSTRING. All page
attributes that are relevant here are described in a byte sequence of variable
length (XSTRING).
In this BSP we use the following code to receive XSTRING:
data: PAGE_DATA type XSTRING.
data: NAME type STRING.
export LAST_STRING_ADDED from LAST_STRING_ADDED
STRINGS

from STRINGS

to data buffer PAGE_DATA.


Next we have to make the server-side cookie XSTRING persistent:

Web Application Server

620 SP 9

385

SAP Online Help

25.10.2002

NAME = SY-UNAME.
call method CL_BSP_SERVER_SIDE_COOKIE=>SET_SERVER_COOKIE
exporting
NAME

= 'my_page_data'

APPLICATION_NAME

= RUNTIME->APPLICATION_NAME

APPLICATION_NAMESPACE = RUNTIME -> APPLICATION_NAMESPACE


USERNAME

= NAME

SESSION_ID

= 'same_for_all'

DATA_NAME

= 'page_data'

DATA_VALUE

= PAGE_DATA

EXPIRY_TIME_REL

= 3600

.
The export parameters mean:
Parameters

Meaning

NAME

Any name can be chosen for the cookie

APPLICATION_NAME

Parameters which refer to the cookie and


uniquely identify it. These are the name of the
BSP application, the namespace of the BSP
application, the user name and the session ID.

APPLICATION_NAMESPACE
USERNAME
SESSION_ID
DATA_NAME

Name and value of the data; these parameters


must match.

DATA_VALUE
EXPIRY_TIME_REL

Details of relative expiry time.

OnRequest
In this event handler the internal data structures of the requests are restored. The persistent
page attributes are returned by the server-side cookie. So there are many parallels with the
event handler OnManipulation.
The server-side cookie is fetched by calling method GET_SERVER_COOKIE of class
CL_BSP_SERVER_SIDE_COOKIE. The meaning of the parameters is essentially the same as
for the parameters for the event handler OnManipulation (see above); only that here
DATA_VALUE is a changing parameter.
data: PAGE_DATA type XSTRING.
data: NAME type STRING.
* User administration can, for example, use the ABAP system name
NAME = SY-UNAME.
* The server-side cookie is fetched
call method CL_BSP_SERVER_SIDE_COOKIE=>GET_SERVER_COOKIE
exporting

Web Application Server

620 SP 9

386

SAP Online Help

25.10.2002

NAME

= 'my_page_data'

APPLICATION_NAME

= RUNTIME->APPLICATION_NAME

APPLICATION_NAMESPACE = RUNTIME -> APPLICATION_NAMESPACE


USERNAME

= NAME

SESSION_ID

= 'same_for_all'

DATA_NAME

= 'page_data'

CHANGING
DATA_VALUE

= PAGE_DATA

.
Provided that the data values do actually have values and therefore are not empty, the
persistent page attributes are now restored by the server-side cookie. This is implemented by
the ABAP statement import.

The syntax of import is:


import Object1 = F ... Objectn = F from data buffer F.
The data object (or several data objects) are imported from the specified data
buffer F, which must be of type XSTRING. All data that has been stored using
export ... to data buffer (see above) in the data buffer F and listed
here, is imported. The system checks that the structure for export and import
corresponds.
In our example the call to restore the persistent cookies is:
if PAGE_DATA is not initial.
import LAST_STRING_ADDED = LAST_STRING_ADDED
STRINGS

= STRINGS

from data buffer PAGE_DATA.


endif.

See also:
You will find this example in the system in BSP application it00 (package SBSP_TEST) on
page misc_page_persistence.htm.

Hybrid Forms
Realistically, the situation often arises in applications where neither one or the other model is
the most suitable at all times. A typical example of this would be the online store, where
browsing and navigating through the product catalog can very well be done in stateless mode,
but where the actual ordering operation including first-time registration is, for technical
reasons, very often realized in stateful mode.
These scenarios are handled by switching the mode can be switched between stateful and
stateless at runtime.
See also:
Stateful BSP Applications [page 381]

Web Application Server

620 SP 9

387

SAP Online Help

25.10.2002

Stateless BSP Applications [page 383]


Stateful or Stateless Programming? [page 388]

Setting Stateful or Stateless


You can classify a BSP application in two types stateful or stateless:
1. During development in the development environment (transaction SE80):

You can define a BSP application as stateful by selecting the BSP application
characteristic Stateful. If the checkbox is deactivated, the BSP application is working
in stateless mode.
2. At runtime using the programming interface IF_BSP_RUNTIME [page 262] (compare
Object Runtime [page 281]):
At any given time, a BSP application can be switched from stateless to stateful (and
vice versa). This would make sense, for example, if you wanted to retain the roll area
for a few consecutive pages but not for the whole application. You can set this by
setting or deleting the attribute KEEP_CONTEXT of the IF_BSP_RUNTIME [page 262]
interface at runtime. The runtime definition overrides any definitions made in the
development environment.
See also: Stateful or Stateless Programming? [page 388]

Stateful or Stateless Programming?


As described in Stateless and Stateful Model [page 112], the underlying framework supports
both stateful (user context in SAP System is maintained) and stateless (user context is
terminated and regenerated for every request) modes.
This process is represented in the following graphic:

Web Application Server

620 SP 9

388

SAP Online Help

25.10.2002

Activity
Server responds,
contains context and
objects

Browser

Time
2

3
Browser

SAP Web
AS

Internet

5
Session 3

Browser

Session 2

Session 1

HTTP

A role area is assigned


to each user
RUNTIME->KEEP_CONTEXT = 1.

1. The first user enters the shop.


2. The second user enters the shop.
3. User 1 puts a book in his or her shopping basket.
4. The third user enters the shop.
5. User 3 puts a book in his or her shopping basket.
6. User 1 places his or her order.
7. User 2 performs an action.
In stateless mode, the process looks like this:

Web Application Server

620 SP 9

389

SAP Online Help

25.10.2002

Activity
Browser

Server answers,
SAP session is
closed

1
2

Browser

SAP Web
AppServer

Internet

Time

HTTP

Browser

Roll area is only


maintained as long as
the user is active.

runtime->keep_context = 0.
2

The numbers indicate which user performs each action. The time progression clarifies the
sequence of events.

When Should Stateful Mode Be Used?


When developing a BSP application, you should weigh up the advantages and disadvantages
of stateful and stateless modes.
If a status needs to be maintained over a number of pages (for example, items in a shopping
basket), stateful mode or the use of client-side cookies is advisable. If the application is
working with stateful mode, the user context must not be kept over the entire flow logic of the
BSP application. Alternatively, stateful mode could just be implemented for the length of time
the status needs to be retained. It can be switched at any time to stateless by using the
command RUNTIME->KEEP_CONTEXT = 0.
Stateless mode is more suitable for applications that do not require any status information, as
this mode avoids unnecessary use of SAP System resources.

How to Set the Mode


When a BSP application is created, this mode can be set by accessing the runtime [page 281]
object dynamically or in the development environment for the whole BSP application.
This is described in the section Setting Stateful or Stateless Mode [page 388].
Stateful means that the Object Application [page 279], specified by the application class is
retained (see also Application Class of BSP Application [page 207]). In stateless mode, the
object is reset.
This is demonstrated in the example below:
A Sample BSP Application [page 391]

Web Application Server

620 SP 9

390

SAP Online Help

25.10.2002

A Sample BSP Application


There is a sample BSP application called stateful_stateless_sample in your system
(package SBSP_SAMPLES). It contains the application class thtest, which consists of only
one attribute of type STRING, as well as 3 BSPs.
On the first page, default.htm, you choose whether you want to work in stateful or
stateless mode. Depending on what you choose, the value RUNTIME->KEEP_CONTEXT is set
to 0 or 1.
Whichever you choose, the application navigates to the page page1.htm. On this page, you
can set the initial string of the application class by entering it in a HTML field. Choose to
second page to navigate to the next page, page2.htm. On this page, the string in stateful
mode has the value just set; in stateless mode the string is empty (initial) again.
This is because in stateful mode the instance of the Application Object [page 279] always
retains its current value in the user context. In stateless mode, the object is re-generated on
page1.htm when the application object is accessed.
The graphic below illustrates the process.
Choose:
stateful or stateless?

default.htm

page1.htm

page2.htm

String: initial
New value: test

String: initial
New value: test

to page2

to page2

String: test

String: initial

to page1

to page1

Control Flow of BSPs


Overview
The control flow of a page is displayed in the following graphic:

Web Application Server

620 SP 9

391

SAP Online Help

25.10.2002

Page Instance Does Not Exist

Create Page Object


OnCreate
Page Instance
Exists

Page Instance Exists

Set Auto Attributes


OnRequest
No User
Events

UserDialog

Navigation

PageInput
User
Events

OnInputProcessing

Navigation

Browser
Redirect

No Navigation
PageOutput

OnInitialization

Navigation

(On)Layout

Evaluate Navigation

OnManipulation
Keep Page
Instance

Keep Page Instance

Destroy Page Object

Destroy Page Object

You do not have to use all event handlers, for example a BSP can consist of just
the layout, or it only contains the layout, OnInitialization and OnInputProcessing.
Since event handler OnDestroy is used infrequently, it is irrelevant here.
The following cases should be distinguished:

stateless BSPs

stateful BSPs

See also:
Interface IF_BSP_PAGE [page 254]

Stateless
In the stateless case, the context is created each time that a request is received. The context
is always destroyed when the response is sent.
For the BSP runtime stateless means: runtime->keep_context = 0
When creating the output of a page, processing is the same as described in the following
graphic.
Output of a BSP (Stateless)

Web Application Server

620 SP 9

392

SAP Online Help

25.10.2002
1
Page Instance Does not Exist

Create Page Object

2
OnCreate
Page Instance
Exists

Page Instance Exists

Set Auto Attributes

3
OnRequest

User
Dialog

Navigation

Page Input

No User
Events

User
Events

Browser
Redirect

No Navigation

4
6

Navigation

OnInputProcessing

Page Output
Navigation

OnInitialization

...
<input type="submit"
name="OnInputProcessing(OK)"
value="Send" />

(On)Layout
OnManipulation

Evaluate
Navigation
Keep Page
Instance

Keep Page Instance

Destroy Page Object

Destroy Page Object

When creating the input for a page, processing is the same as described in the following
graphic.
Input for a BSP (Stateless)
1

Page instance Does not Exist


Form-Fields
...
OnInputProcessing
...

Create Page Object

2
OnCreate
Page Instance
Exists

Page Instance Exists

Set Auto Attributes

3
OnRequest

User
Dialog

...
OK
...

No User
Events

...
Navigation->next_page('OK');

Navigation

Page Input

4 User Events

OnInputProcessing

Navigation

Browser
Redirect

No Navigation
Page Output

OnInitialization

To
Next
Page

Navigation

(On)Layout

Evaluate Navigation

OnManipulation

Keep Page
Instance

Keep Page Instance

Destroy Page Object


Destroy Page Object

With stateless BSPs (the default is stateless), the navigation can be executed either on the
same page or on other pages.

Navigation Within the BSP


When the page is called, the system first checks if there is already a page object for this BSP.
If this is not the case, the event handler OnCreate runs, which creates the page object or an

Web Application Server

620 SP 9

393

SAP Online Help

25.10.2002

instance of it. The event handler OnRequest then follows. If a page object already exists (in
general, this does not happen with the first call, just as little as in stateless BSPs), the system
branches directly to the event handler OnRequest. There then follows either OnInitialization, if
there is no user interaction, and OnInputProcessing if there is user interaction. From
OnInputProcessing, there is no further navigation to OnInitialization. Processing continues
with the layout and then possibly with OnManipulation, although this event handler is used
infrequently. The requested page is then displayed in the browser. User action can now take
place, and then processing begins again.

Navigating to Other BSPs


The processing process is very similar to when you navigate within a BSP. If you now
navigate from the OnRequest to a different page, event handler OnInputProcessing is called
and evaluated. The follows OnInitialization, and then the layout and so on.

Stateful
In the stateful case, the context is held by gone request to the next.
For the BSP runtime stateful means: runtime->keep_context = 1
When creating the output of a page, processing is the same as described in the following
graphic.
Output of a BSP (Stateful)
1
Page Instance Does Not Exist

Create Page Object

2
OnCreate
Page Instance
Exists

Page Instance Exists

Set Auto Attributes

3
OnRequest

User
Dialog

Navigation

Page Input

No User
Events

User Events

Navigation

Browser
Redirect

No Navigation

4
6

OnInputProcessing

Page Output

OnInitialization
(On)Layout
OnManipulation
Keep Page Instance

Navigation
...
<input type="submit"
name="OnInputProcessing(OK)"
value="Send" />

Evaluate
Navigation
Keep Page
Instance

Destroy Page Object

Destroy Page Object

When creating the input for a page, processing is the same as described in the following
graphic.
Input for a BSP (Stateful)

Web Application Server

620 SP 9

394

SAP Online Help

25.10.2002

Page Instance Does Not Exist


Form-Fields
...
OnInputProcessing
...

Create Page Object


OnCreate

1
Page
Instance
Exists

Page Instance Exists

Set Auto-Attributes
OnRequest
No User
Events

User
Dialog

...
OK
...

...
Navigation->next_page('OK');

Navigation

Page Input

3 Benutzer-

OnInputProcessing

Events

Navigation

Browser
Redirect

No Navigation
Page Output

OnInitialization

to
next
page

Navigation

(On)Layout

Evaluate Navigation

OnManipulation

5 Keep
Page Instance

Keep Page Instance

Destroy Page Object


Destroy Page Object

With stateful BSPs, there can be three different variants of lifetime:

Up to the page change (lifetime_page)


The page is destroyed if a different page is used.

For the duration of the request (lifetime_request)


The page is destroyed after each individual request, that is, is only available for the
duration of each request.

For the duration of the session (lifetime_session)


The page is destroyed at the end of the session.

Examples

BSP only with Layout [page 395]

BSP with Layout and Initialization [page 396]

BSPs with Layout, Initialization and Navigation [page 398]

BSPs with Layout, Initialization and Input Processing [page 400]

BSP Only with Layout


Overview
This simple BSP merely consists of the layout. This layout:

has the scripting language ABAP

contains static HTML

contains server-side scripting

Web Application Server

620 SP 9

395

SAP Online Help

25.10.2002

In the Web Application Builder, the layout of this BSP looks as follows:
<%@page language="abap"%>
<html>
<body>
<center>
<% do 5 times. %>
<font size=<%=sy-index%>>
Hello World! <br>
</font>
<% enddo. %>
</center>
</body>
</html>
See also:
tutorial_1 in packet SBOOKSHOP or First Steps with the Business Server Pages
[External documentation]

Processing Process
The individual steps that are followed when processing this BSP are as follows:

The user calls a BSP application in the browser or enters an appropriate URL.

An HTTP-GET request is sent to the BSP runtime.

The BSP runtime determines the suitable BSP application and the BSP that is called.

Since the BSP only consists of the layout, the page layout that is established there is
determined and the scripting code is processed.

The BSP runtime then generates a suitable response.

and sends it to the browser that displays the BSP.

BSP With Layout and Initialization


Overview
This simple BSP contains the layout, a page attribute and event handler OnInitialization. This
outputs the title, publisher and ISBN of all books in the database table BSBOOK that were
published in the year 2000.
This BSP is as follows in the Web Application Builder:
Layout
<%@page language="abap"%>
<html>
<body>
<h2> Book list </h2>

Web Application Server

620 SP 9

396

SAP Online Help

25.10.2002

<table border=1>
<tr>
<th>Title</th>
<th>Publisher</th>
<th>ISBN</th>
</tr>
<% data: wbook like line of books.
loop at books into wbook. %>
<tr>
<td><%= wbook-title %></td>
<td><%= wbook-publisher %></td>
<td><%= wbook-ISBN %></td>
</tr>
<% endloop. %>
</table>
</body>
</html>
OnInitialization
select * from bsbook into table books where publyear = '2000'.
Page Attributes
Attribute Name

automatic

books

Typing Type

Reference Type

Description

TYPE

BOOK_TAB

Booklist

The internal table books of type BOOK_TAB is filled in OnInitialization.

Processing Process
The individual steps that are followed when processing this BSP are as follows:

The user calls a BSP application in the browser or enters an appropriate URL.

An HTTP-GET request is sent to the BSP runtime.

The BSP runtime determines the suitable BSP application and the BSP that is called.

In the BSP, data is retrieved using OnInitialization. Table BSBOOK is read for those book
entries that were made in the year 2000.

The scripting code is processed in the layout and the page is rendered: An HTML table is
output and filled with content.

The BSP runtime then generates a suitable response

and sends it to the browser that displays the BSP.

Web Application Server

620 SP 9

397

SAP Online Help

25.10.2002

This example can be enhanced by adding a second BSP with navigation: BSP
Application with Layout and Initialization [page 398]

BSPs with Layout, Initialization and Navigation


Overview
This simple BSP applications contains two BSPs with layout, page attributes and the event
handler OnInitialization.
Depending on the user input for the year of publication, the next page displays various lists of
books in table form.
These BSPs are as follows in the Web Application Builder:
Layout of startpage.htm
<%@page language="abap"%>
<html>
<head>
<link rel="stylesheet"
href="../../sap/public/bc/bsp/styles/sapbsp.css">
<title> Selection Page </title>
</head>
<body class="bspBody1">
Year of Publication:
<form method="post" action="page2.htm" >
<select name="sel_publyear">
<option value="2000"> Year 2000
<option value="2001"> Year 2001
</select>
<input type="submit" value="Select">
</form>
</body>
</html>
Layout of page2.htm
<%@page language="abap"%>
<html>
<body>
<h2> Book list </h2>
<table border=1>
<tr>
<th>Title</th>

Web Application Server

620 SP 9

398

SAP Online Help

25.10.2002

<th>Publisher</th>
<th>ISBN</th>
</tr>
<% data: wbook like line of books.
loop at books into wbook. %>
<tr>
<td><%= wbook-title %></td>
<td><%= wbook-publisher %></td>
<td><%= wbook-ISBN %></td>
</tr>
<% endloop. %>
</table>
</body>
</html>
OnInitialization of page2.htm
data: year type int.
year = request->get_form_field( 'sel_publyear' ).
select * from bsbook into table books where publyear = year.
Page Attribute of page2.htm
Attribute Name

automatic

books

Typing Type

Reference Type

Description

TYPE

BOOK_TAB

Booklist

The internal table books of type BOOK_TAB is filled in OnInitialization.

Processing Process
The individual steps that are followed when processing this BSP are as follows:

The user calls a BSP application in the browser or enters an appropriate URL.

An HTTP-GET request is sent to the BSP runtime.

The BSP runtime determines the suitable BSP application and the BSP that is called:
startpage.htm.

The layout is assessed, since this page only has layout.

The BSP runtime generates the page and sends it to be displayed at the browser.

In the pulldown menu, the user selects the required year of publication and selects the
pushbutton.

An HTTP-POST request is now sent to the BSP runtime.

This POST request requests a different page, page2.htm.

Web Application Server

620 SP 9

399

SAP Online Help

25.10.2002

Event handler OnInitialization is assessed by this second page. Table BSBOOK is read for
those book entries that were published in the year specified by the user.

The scripting code is processed in the layout and the page is rendered: An HTML table is
output and filled with content.

The BSP runtime then generates a suitable response

and sends it to the browser that displays the BSP.

BSPs with Layout, Initialization and Input


Processing
In this example, there is a CD page as well as a book page. The CD page should be aligned
with the distribution of CDs. Furthermore there is also user input, which outputs the book
page or the CD page depending on the category that was selected on the selection page.

Overview
These BSPs are as follows in the Web Application Builder:
Layout of select.htm
<%@ page language="abap" %>
<html>
<body>
<h2> Select CDs or Books! </h2>
<form method="post" >
<select name="sel_category">
<option value="0001"> Books
<option value="0002"> CDs
</select>
<input type="submit" name="OnInputProcessing(select)"
value="Select">
</form>
</body>
</html>

OnInputProcessing of select.htm
* event handler for checking and processing user input and
* for defining navigation
data: cat type string.
case event_id.

Web Application Server

620 SP 9

400

SAP Online Help

25.10.2002

when 'select'.
cat = request->get_form_field( 'sel_category' ).
if cat = '0001'.
navigation->goto_page( 'books.htm' ).
elseif cat = '0002'.
navigation->goto_page( 'cds.htm' ).
endif.
endcase.
Layout of books.htm
<%@ page language="abap" %>
<html>
<body>
<h2> All books </h2>
<table border=1>
<tr>
<th></th>
<th>Title</th>
<th>Author</th>
<th>Publisher</th>
<th>ISBN</th>
</tr>
<% data: wbook like line of books.
loop at books into wbook. %>
<tr>
<td><img src="../../bookstore2/<%=wbook-category%><%=wbookid%>_s.jpg"></td>
<td><%= wbook-title %></td>
<td><%= wbook-author %></td>
<td><%= wbook-publisher %></td>
<td><%= wbook-id %></td>
</tr>
<% endloop. %>
</table>

Web Application Server

620 SP 9

401

SAP Online Help

25.10.2002

</body>
</html>
OnInitialization of books.htm
select * from bsparticle into table books where category = '0001'.cds
Page Attribute of books.htm
Attribute Name

automatic

books

Typing Type

Reference Type

Description

TYPE

TARTICLE

list of
books

Layout of cds.htm
<%@ page language="abap" %>
<html>
<body>
<h2> All CDs </h2>
<table border=1>
<tr>
<th></th>
<th>Title</th>
<th>by</th>
<th>Label</th>
<th>number</th>
</tr>
<% data: wcd like line of cds.
loop at cds into wcd. %>
<tr>
<td><img src="../../bookstore2/<%=wcd-category%><%=wcdid%>_s.jpg" border=1></td>
<td><%= wcd-title %></td>
<td><%= wcd-author %></td>
<td><%= wcd-publisher %></td>
<td><%= wcd-author %></td>
</tr>
<% endloop. %>
</table>

Web Application Server

620 SP 9

402

SAP Online Help

25.10.2002

</body>
</html>
OnInitialization of cds.htm
select * from bsparticle into table cds where category = '0002'.
Page Attribute of cds.htm
Attribute Name

automatic

cds

Typing Type

Reference Type

Description

TYPE

TARTICLE

list of cds

Caching BSPs
Use
With the Internet Server Cache (see also ICM Server-Cache [page 34]) you can considerably
increase the performance and scalability of your BSP application. The ICM server cache
provides a dynamic and active content caching technology, resulting in the following
advantages for developing BSPs:

The resources required for creating BSPs are reduced

You do not have to repeatedly execute BSPs that are frequently requested

The possible performance improvements can be up to factor 20.

Performance and Scalability


Benchmarking tests for cache hits in the main memory have resulted in latent response times
of less than one millisecond per request, and a total run of under 3,000 requests per second
on a 4 CPU hardware.
These results are based on a strong parallel and multithreaded architecture that supports
simultaneous read and write accesses with versioning. Furthermore, a patented indexing
algorithm is used to access the cache directory quickly. This algorithm is particularly suitable
for long Web URLs as cache keys.

Functions
The features and the architecture of the ICM server cache are described in Internet Server
Cache [page 34].
You have the following options to control BSP caching:

In the Web Application Builder (Transaction SE80), you can set the following properties
for caching on the Properties tab page:

Expiry date for caching in the Internet server cache

Expiry date for caching in the browser (client-side)

Flag whether page caching should be browser-dependent

Web Application Server

620 SP 9

403

SAP Online Help

25.10.2002

In your BSP application you can control the behavior of the ICM server cache using
response object method calls.

The following section describes how you should proceed.

Activities
Setting Caching Properties in the Web Application Builder

You can set the caching properties for the page on the Properties tab page of a BSP:
For both the browser cache and the ICM server cache you can determine how long the page
should be held in the cache. If you do not enter any data, this means that the cache is not
used for the page. Set flag Browser Dependent if you want the ICM server cache to fetch the
page from the cache only if the request comes from the same browser type. If you do not set
the flag, note that all of the elements used by the page must not be browser-dependent.

Note that when you use the browser cache, the client cannot tell when a page
has changed. If the URL is the same, it always returns the same page from the
cache until the expiry date has passed. If you use the ICM server cache, by
using the invalidation methods you can ensure that the page stored in the cache
is up-to-date.

Setting Caching Properties Using Method Calls in the BSP


You have several options here. In addition to the relative expiry date and browserdependency, you can specify a final expiry date and invalidate cache entries. You can also
activate caching not just for the page in general, but also according to user input.
Set the expiry time for an HTTP response with the methods of class CL_HTTP_RESPONSE
(see also IF_HTTP_RESPONSE and IF_HTTP_REQUEST [page 119]):

SERVER_CACHE_EXPIRE_ABS

SERVER_CACHE_EXPIRE_REL

Use appropriate automatic expiry times. For example, a banner displaying stock
market tickers is updated every n minutes, whilst a product catalog should be
updated only every n days or weeks.
You refresh (invalidate) objects asynchronously using the methods of class
CL_HTTP_SERVER (see also IF_HTTP_SERVER [page 117]):

You can use method SERVER_CACHE_INVALIDATE() to invalidate an individual object


that can be identified by the following data:

Complete name, that is, URI path, form fields and BSP application context

Prefix of the name (hierarchical wildcards)

E-tag, that is, the entity tag and the unique ID that was assigned at the time of
creation

Web Application Server

620 SP 9

404

SAP Online Help

25.10.2002

You can use method SERVER_CACHE_INVALIDATE_LIST() to invalidate a list of


objects (internal tables).

The system automatically forwards this data to other application servers, thus ensuring cache
integrity.

You should avoid too frequent invalidations, so that system-wide transfers to


other application servers are avoided.
See also:
Manipulating Cache Properties [page 39]

Example
You can find a simple example in the system in BSP application TUTORIAL_4, BSP
results.htm in the event handler OnInitialization:
* cache result page in case Plattner's books are searched
if

'PLATTNER' cp author.

response->server_cache_expire_abs( expires_abs_time

= '180000'

browser_dependent = 'X' ).
endif.
The result list for querying the books from Hasso Plattner is only stored in the cache because
you know that these are requested especially often. The cache entry is invalidated every night
at 18.00. This function may be useful for things that must be recalculated every day (such as
current prices).
See also:
Further Developing the Online Bookshop [External documentation]

Page Layout
Prerequisites
Before you can choose from the various options available for the layout of your BSP
application, you need some knowledge of following:

Page-based programming model

HTML

Work method of graphical Web design tools

Do you have to choose one or the other option?


The SAP Web Application Server provides a number of design options for the BSP layout.
The easiest option is to design a page with pure HTML. You either use the text editor in the
BSP development environment (see also the documentation on the Web Application Builder
[External documentation]) and design the page textually. This presupposes a good knowledge
of HTML and it is usually a lengthy process. The advantage of it is: script can be added
immediately to the correct parts of the page. Moreover, the Web Application Builder in the

Web Application Server

620 SP 9

405

SAP Online Help

25.10.2002

development environment has a preview function so that you can check the static layout of a
page at any time.

From SAP Web AS 6.20 you can use BSP extensions [page 284] as an ideal
mechanism for easily integrating interface elements such as tableviews, buttons,
input fields or charts into your BSPs. In particular, you can use the BSP
extension HTML Business (HTMLB) for BSP applications.
A more elegant solution is to design a page with a design tool such as AdobeGoLive5.0,
Dreamweaver 4.0, Frontpage and so on. The SAP Web Application Server lets you check in
Web pages created with such tools and directly edit such pages managed on the server. This
is done by means of the WebDAV access of the SAP Web Application Server (see also Using
External Tools [page 420]). WebDAV is supported by the above-mentioned tools (Frontpage
together with the WebFolders). After check-in, you can add script to the pages. If the pages
checked in to the server are edited again using the tool, you should flag the server-side script
parts so that a designer can recognize them as such.
Thus, developers of Web applications using the SAP Web Application Server are subject to
no design restrictions whatever.

Accessibility
Use
The Accessibility Guidelines (Section 508) established in the United States are intended to
enable partially sighted users to use software interfaces. In general, all texts on an interface
are read out using an external tool, provided that all screen elements, such as symbols,
pushbuttons and so on have been assigned quick infos.
In the context of BSP applications, you can use BSP extension HTMLB to structure interfaces
with the Tag Browser.

In particular, you should think about the accessibility of BSP applications that
contain tables, tabstrips and tree controls. These three types of interface
elements are not always easy for Screen Reader to read out.

Integration
When developing BSP applications, you can specify whether or not you want to follow the
accessibility rules.
The accessibility specification is integrated in the BSP runtime [page 262]:
1. Specify the accessibility in the following URL:
...?sap-accessibility=X
2. Query the accessibility in the BSP runtime:
runtime->with_accessibility( ) = 'X'
Accessibility is activated.
runtime->with_accessibility( ) = 'X'
Accessibility is not activated.

Web Application Server

620 SP 9

406

SAP Online Help

25.10.2002

Programming Environment
The following documentation describes the BSP programming environment:
Recommended Browser Settings [page 407]
Debugging [page 408]
Internationalization and Translation [page 412]
BSP Development Tools [page 416]
Task Formatting [page 426]
Style Sheets [page 426]
File Upload in BSP Applications [page 429]
Handling Incorrect Entries [page 434]
Sending E-Mails from BSP Applications [page 441]
MIME Types of a Page [page 448]
Mobile Enhancements of the SAP Web Application Server [External documentation]
DDIC Services for BSP Applications [page 497]

Recommended Browser Settings


When developing BSP applications, it is useful if you make the following settings in the
browser:

Set the development language

Display new sessions in the same browser window

Display error messages from the SAP Web AS

The description of these settings is intended for Microsoft Internet Explorer 5.5.

Set the development language


Your main development and display languages should match the default language that is
specified in the browser.
1. Choose Tools Internet Options...
2. On the General tab page, choose Languages...
3. In the Language Preference window, enter your preferred language and then choose OK.
4. In the Internet Options window, choose OK.

Display new sessions in the same browser window


If you open new sessions, you can have these processed in the previous browser window to
avoid having a large number of browser instances open on your desktop.
1. Choose Tools Internet Options...
2. Choose the Advanced tab page.
3. In Browsing, activate the option Reuse windows for launching shortcuts and then choose
OK.
Web Application Server

620 SP 9

407

SAP Online Help

25.10.2002

Displaying error messages from the SAP Web AS


Instead of the usual error messages from the browser, you can also display more detailed
HTTP error messages, which originate from the SAP Web AS.
1. Choose Tools Internet Options...
2. Choose the Advanced tab page.
3. In Browsing, deactivate the two options Show friendly HTTP error messages and Show
friendly URLs, and then choose OK.

Debugging
Use
Problems that occur when you display or execute BSP applications can be caused by all sorts
of different reasons. If a problem occurs, you can debug to find the solution.
A special HTTP debugger is available for the coding in your BSP application. You can use
HTTP debugging in exactly the same way as usual debugging.

HTTP debugging is user-specific, that is, breakpoints are set user-specific.


Debugging is not possible for a public or Internet user.
If it is set for the HTTP request, authentication must be carried out.
See also:
You can find additional information about debugging in the Debugger [External
documentation] documentation.
You can also set breakpoints for BSP page fragments [page 409].
If the debugger does not help you, you can use a trace [page 409] for your BSP application.

Prerequisites
Before you debug, ensure that:

The Internet Communication Manager [page 22] (ICM) is active.


To do this, go to Transaction SMICM: The ICM status should be running and you
should see a green stoplight
.
The ICM is running with the correct parameters (see also Parameterizing the ICM and
the ICM Server Cache [page 45]).

The correct domain or DNS configuration is specified for your BSP application.
See also DNS Configuration for BSP Applications Under Windows 2000 [page 525]

Activities