sap business connector built-in services

SAP BC Bulit-In Services Guide 4.8 1

SAP Business Connector Built-In Services Guide

Release 4 .8

SAP® AG Dietmar-Hopp-Allee 16 D-69190 Walldorf

SAP SYSTEM

C H A P T E R 0 I n t r o d u c t i o n

2 SAP BC Bulit-In Services Guide 4.8

Copyright ©Copyright 2008 SAP AG. All rights reserved.

No part of this description of functions 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® and EXCEL®, NT® and SQL-Server® are registered trademarks of Microsoft Corporation.

IBM®, OS/2®, DB2/6000®, AIX®, OS/400® and AS/400® are registered trademarks of IBM Corporation.

OSF/Motif® is a registered trademark of Open Software Foundation.

ORACLE® is a registered trademark of ORACLE Corporation, California, USA.

webMethods® is a registered trademark of webMethods Incorporated, Virginia, USA.

INFORMIX®-OnLine for SAP is a registered trademark of Informix Software Incorporated.

Adobe, Acrobat, and PostScript are trademarks of Adobe Systems Incorporated. UNIX® and X/Open® are registered trademarks of SCO Santa Cruz Operation.

SAP®, R/2®, R/3®, RIVA®, ABAP/4®, SAPaccess®, SAPmail®, SAPoffice®, SAP-EDI®, SAP Business Workflow®, SAP EarlyWatch®, SAP ArchiveLink®, R/3 Retail®, ALE/WEB®, SAPTRONIC® are registered trademarks of SAP AG.

All rights reserved.

Welcome!


Typographical Conventions

Type Style Description

Interface Text Words or characters that appear on the screen. This includes field names, screen titles, pushbuttons, menu names, and menu options.

Document Title Cross-references to other documentation.

User Entry Words and characters that you enter exactly as they appear in the documentation.

<Variable User Entry>

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

NAME Names of elements in the SAP System. These include program names, transaction codes, table names, ABAP key words, file names, and directories.

Name File names, path names, program names, user names, parameters, file contents and operating system output.

KEY Keys on the keyboard. These include the function keys, e.g. F2, or the ENTER key.

Icon Description

A note. Notes contain important information, e.g. exceptions or special cases.

An example. Examples illustrate complex procedures or the syntax for user entries.

A caution. Cautions help users avoid errors which can, for example, lead to loss of data.

Hints and tips.



CONTENTS

Chapter 1 Introduction.................................................................................... 15 Welcome! ............................................................................................................................... 16 Typographical Conventions .................................................................................................... 17

Program Code Conventions .............................................................................. 18 Related Documentation .......................................................................................................... 18 Viewing this Document ........................................................................................................... 19 Printing this Guide .................................................................................................................. 20

Chapter 2 Client Services ............................................................................... 21 pub.client:ftp ...................................................................................................... 24 pub.client:http .................................................................................................... 25 pub.client:smtp................................................................................................... 29 pub.client.ftp:append ......................................................................................... 31 pub.client.ftp:cd.................................................................................................. 31 pub.client.ftp:cdls ............................................................................................... 32 pub.client.ftp:delete............................................................................................ 32 pub.client.ftp:get ................................................................................................ 33 pub.client.ftp:login.............................................................................................. 33 pub.client.ftp:logout............................................................................................ 34 pub.client.ftp:ls................................................................................................... 34 pub.client.ftp:mdelete......................................................................................... 35 pub.client.ftp:mget ............................................................................................. 35 pub.client.ftp:mput ............................................................................................. 36 pub.client.ftp:put ................................................................................................ 36 pub.client.ftp:quote ............................................................................................ 37 pub.client.ftp:rename ......................................................................................... 37 pub.client.ftp:sessioninfo ................................................................................... 37 pub.client:soapHTTP ......................................................................................... 38 pub.client:soapRPC........................................................................................... 40

Chapter 3 Clustering ....................................................................................... 43 pub.cluster:disableServiceRedir ........................................................................ 45 pub.cluster:disableSessionRedir ....................................................................... 45 pub.cluster.getClusterHosts............................................................................... 45

Welcome!


Chapter 4 Zip and GZip algorithms ................................................................46 pub.compress.gzip:addInputData ......................................................................48 pub.compress.gzip:closeGZIPCompressor .......................................................48 pub.compress.gzip.createGZIPCompressor......................................................48 pub.compress.gzip:getOutputData ....................................................................48 pub.compress.gzip:gunzip .................................................................................49 pub.compress.gzip:gzip .....................................................................................49 pub.compress.gzip:openGZIPData....................................................................49 pub.compress.gzip:readNextBlock ....................................................................50 pub.compress.zip:addEntryData........................................................................50 pub.compress.zip:closeZIPArchive....................................................................51 pub.compress.zip.createZIPArchive ..................................................................51 pub.compress.zip:getOutputData ......................................................................52 pub.compress.zip:openZIPArchive ....................................................................52 pub.compress.zip:readNextEntry.......................................................................52 pub.compress.zip:unzip .....................................................................................53 pub.compress.zip:zip .........................................................................................53

Chapter 5 Database Services..........................................................................55 pub.db:call..........................................................................................................57 pub.db:clearTransaction ....................................................................................58 pub.db:close.......................................................................................................59 pub.db:closeAll...................................................................................................60 pub.db:commit ...................................................................................................60 pub.db:connect ..................................................................................................60 pub.db:delete .....................................................................................................62 pub.db:execSQL ................................................................................................63 pub.db:getProcInfo.............................................................................................65 pub.db:getProcs.................................................................................................66 pub.db:getTableInfo ...........................................................................................67 pub.db:getTables ...............................................................................................69 pub.db:insert ......................................................................................................70 pub.db:query ......................................................................................................71 pub.db:rollback...................................................................................................72 pub.db:startTransaction .....................................................................................73 pub.db:update ....................................................................................................74

Chapter 6 Date Services..................................................................................77



Pattern String Symbols ...................................................................................... 78 Time Zones........................................................................................................ 79 Notes on Invalid Dates....................................................................................... 80 pub.date:currentDate ......................................................................................... 81 pub.date:dateBuild............................................................................................. 81 pub.date:dateTimeBuild..................................................................................... 82 pub.date:dateTimeFormat ................................................................................. 82

Chapter 7 Event Services ............................................................................... 85 pub.event:addSubscriber................................................................................... 88 pub.event:alarm ................................................................................................. 90 pub.event:alarmInfo ........................................................................................... 90 pub.event:audit .................................................................................................. 91 pub.event:auditInfo ............................................................................................ 91 pub.event.audit:logToFile .................................................................................. 91 pub.event:callStackItem..................................................................................... 92 pub.event:deleteSubscriber ............................................................................... 92 pub.event:exception........................................................................................... 93 pub.event:exceptionInfo..................................................................................... 93 pub.event.exception:logToFile........................................................................... 94 pub.event:gdEnd................................................................................................ 94 pub.event:gdEndInfo.......................................................................................... 95 pub.event:gdStart .............................................................................................. 95 pub.event:gdStartInfo ........................................................................................ 95 pub.event:getEventTypes.................................................................................. 96 pub.event:getSubscribers .................................................................................. 96 pub.event:modifySubscriber .............................................................................. 97 pub.event:portStatus........................................................................................ 100 pub.event:portStatusInfo.................................................................................. 100 pub.event:reloadEventManagerSettings ......................................................... 101 pub.event:replication........................................................................................ 102 pub.event:replicationInfo.................................................................................. 102 pub.event:saveEventManagerSettings............................................................ 102 pub.event:sessionEnd ..................................................................................... 102 pub.event.sessionEnd:logToFile ..................................................................... 103 pub.event:sessionEndInfo ............................................................................... 103 pub.event:sessionExpire.................................................................................. 103 pub.event.sessionExpire:logToFile.................................................................. 103

Welcome!


pub.event:sessionExpireInfo............................................................................104 pub.event:sessionStart ....................................................................................104 pub.event.sessionStart:logToFile ....................................................................104 pub.event:sessionStartInfo ..............................................................................105 pub.event:stat ..................................................................................................105 pub.event:statInfo ............................................................................................106 pub.event.stats:logToFile.................................................................................107 pub.event:txEnd ...............................................................................................107 pub.event:txEndInfo .........................................................................................107 pub.event:txStart..............................................................................................107 pub.event:txStartInfo........................................................................................108

Chapter 8 File Services..................................................................................109 pub.file:getFile..................................................................................................111 pub.file:head ....................................................................................................112 pub.file:tail ........................................................................................................113

Chapter 9 Flow Services ...............................................................................115 pub.flow:clearPipeline ......................................................................................117 pub.flow:debugLog...........................................................................................117 pub.flow:getLastError.......................................................................................117 pub.flow:getSession.........................................................................................118 pub.flow:getTransportInfo ................................................................................118 pub.flow:restorePipeline...................................................................................118 pub.flow:restorePipelineFromFile ....................................................................119 pub.flow:savePipeline ......................................................................................119 pub.flow:savePipelineToFile ............................................................................120 pub.flow:setResponse......................................................................................120 pub.flow:sleep ..................................................................................................121 pub.flow:tracePipeline......................................................................................121 pub.flow:transportInfo ......................................................................................121

Chapter 10 Stream/Byte conversion ..............................................................124 pub.io:bytesToStream......................................................................................126 pub.io:streamToBytes ......................................................................................126

Chapter 11 LDAP Services..............................................................................127 pub.ldap:bind ...................................................................................................129 pub.ldap:connect..............................................................................................129



pub.ldap:delete ................................................................................................ 130 pub.ldap:disconnect......................................................................................... 130 pub.ldap:getAttributeDef .................................................................................. 131 pub.ldap:getClassDef ...................................................................................... 131 pub.ldap:init ..................................................................................................... 132 pub.ldap:list...................................................................................................... 132 pub.ldap:lookup ............................................................................................... 134 pub.ldap:search ............................................................................................... 134 pub.ldap:shutdown........................................................................................... 136 pub.ldap:update ............................................................................................... 136

Chapter 12 List Services................................................................................. 137 pub.list:appendToRecordList ........................................................................... 139 pub.list:appendToStringList ............................................................................. 139 pub.list:copyListItem ........................................................................................ 139 pub.list:getListItem........................................................................................... 140 pub.list:getRecordListItem ............................................................................... 140 pub.list:getStringListItem ................................................................................. 141 pub.list:setListItem ........................................................................................... 141 pub.list:setRecordListItem ............................................................................... 141 pub.list:setStringListItem.................................................................................. 141 pub.list:sizeOfList............................................................................................. 142 pub.list:stringListToRecordList......................................................................... 142

Chapter 13 Math Services............................................................................... 143 pub.math:addFloatList ..................................................................................... 145 pub.math:addFloats ......................................................................................... 145 pub.math:addIntList ......................................................................................... 145 pub.math:addInts ............................................................................................. 145 pub.math:divideFloats...................................................................................... 146 pub.math:divideInts.......................................................................................... 146 pub.math:multiplyFloatList ............................................................................... 146 pub.math:multiplyFloats................................................................................... 146 pub.math:multiplyIntList ................................................................................... 147 pub.math:multiplyInts....................................................................................... 147 pub.math:randomDouble ................................................................................. 147 pub.math:randomLong..................................................................................... 147 pub.math:subtractFloats .................................................................................. 148

Welcome!


pub.math:subtractInts ......................................................................................148

Chapter 14 Mime Services...............................................................................149 pub.mime:addBodyPart ...................................................................................151 pub.mime:addMimeHeader..............................................................................154 pub.mime:createMimeData..............................................................................155 pub.mime:getBodyPartContent........................................................................157 pub.mime:getBodyPartHeader ........................................................................158 pub.mime:getContentType...............................................................................158 pub.mime:getEnvelopeStream ........................................................................159 pub.mime:getMimeHeader...............................................................................160 pub.mime:getNumParts ...................................................................................161 pub.mime:getPrimaryContentType ..................................................................161 pub.mime:getSubContentType ........................................................................162 pub.mime:mergeHeaderAndBody ...................................................................162

Chapter 15 Package Services .........................................................................165 pub.packages:activatePackage .......................................................................167 pub.packages:disablePackage ........................................................................167 pub.packages:enablePackage.........................................................................168 pub.packages:installPackage ..........................................................................168 pub.packages:recoverPackage .......................................................................169 pub.packages:reloadPackage .........................................................................170

Chapter 16 Record Services ...........................................................................171 pub.record:length .............................................................................................173 pub.record:recordListToRecord .......................................................................173 pub.record:recordToRecordList .......................................................................174 pub.record:recordToXMLValues......................................................................174 pub.record:XMLValuesToRecord ....................................................................175

Chapter 17 Remote Services ..........................................................................177 pub.remote:invoke ...........................................................................................179 pub.remote.gd:end...........................................................................................180 pub.remote.gd:getStatus..................................................................................180 pub.remote.gd:invoke ......................................................................................181 pub.remote.gd:restart.......................................................................................181 pub.remote.gd:retrieve.....................................................................................181 pub.remote.gd:start..........................................................................................182



pub.remote.gd:send......................................................................................... 183 pub.remote.gd:submit ...................................................................................... 183

Chapter 18 Replicator Services ..................................................................... 185 pub.replicator:addReleaseRegistryEntry ......................................................... 187 pub.replicator:deleteReleaseRegistryEntry ..................................................... 188 pub.replicator:distributeViaFTP ....................................................................... 188 pub.replicator:distributeViaSvcPull .................................................................. 189 pub.replicator:distributeViaSvcPush................................................................ 189 pub.replicator:generateReplicationEvent......................................................... 189 pub.replicator:getLocalReleasedList ............................................................... 190 pub.replicator:getRemoteReleasedList ........................................................... 190 pub.replicator:notifyPackageRelease .............................................................. 191 pub.replicator:packageCreation....................................................................... 191

Chapter 19 Report Services ........................................................................... 193 pub.report:runFileTemplate ............................................................................. 195 pub.report:runFileTemplateOnPipe ................................................................. 195 pub.report:runStringTemplate.......................................................................... 195 pub.report:runStringTemplateOnPipe.............................................................. 196 pub.report:runTemplate ................................................................................... 196 pub.report:runTemplateOnPipe ....................................................................... 196

Chapter 20 Scheduler Services...................................................................... 199 pub.scheduler:addComplexTask ..................................................................... 201 pub.scheduler:addOnetimeTask...................................................................... 202 pub.scheduler:addRepeatingTask................................................................... 203 pub.scheduler:cancelTask............................................................................... 204 pub.scheduler:getTaskIDs............................................................................... 204 pub.scheduler:getTaskInfo .............................................................................. 204 pub.scheduler:resumeTask ............................................................................. 206 pub.scheduler:suspendTask............................................................................ 206 pub.scheduler:updateComplexTask ................................................................ 207 pub.scheduler:updateOneTimeTask ............................................................... 209 pub.scheduler:updateRepeatingTask.............................................................. 209

Chapter 21 Schema Services ......................................................................... 211 pub.schema:createXSD................................................................................... 213 pub.schema:validate........................................................................................ 213

Welcome!


pub.schema:validatePipeline ...........................................................................215 pub.schema.w3c:datatypes .............................................................................216 pub.schema.w3c:xml .......................................................................................216

Chapter 22 Security Services .........................................................................217 pub.security:clearKeyAndChain.......................................................................219 pub.security:setKeyAndChain..........................................................................219 pub.security.pkcs7:sign....................................................................................219 pub.security.pkcs7:verify..................................................................................221 pub.security.util:createMessageDigest ............................................................222 pub.security.util:getCertificateInfo....................................................................222 pub.security.util:loadPKCS7CertChain ............................................................223 pub.security.ssf:decrypt ...................................................................................224 pub.security.ssf:encrypt ...................................................................................225 pub.security.ssf:getCertificateInfo....................................................................226 pub.security.ssf:getLoadedProfiles..................................................................226 pub.security.ssf:getLoadedReciepients ...........................................................227 pub.security.ssf:importOwnProfile ...................................................................228 pub.security.ssf:importRecipientKey................................................................229 pub.security.ssf:removeProfile.........................................................................229 pub.security.ssf:removeReciepient..................................................................229 pub.security.ssf:setDefaultProfile ....................................................................230 pub.security.ssf:setDefaultRecipient................................................................230

Chapter 23 SMIME Services............................................................................233 pub.smime:createCertsOnlyData.....................................................................235 pub.smime:createEncryptedData ....................................................................235 pub.smime:createSignedAndEncryptedData...................................................236 pub.smime:createSignedData .........................................................................237 pub.smime:getContentType.............................................................................238 pub.smime:processCertsOnlyData ..................................................................239 pub.smime:processEncryptedData..................................................................239 pub.smime:processSignedData.......................................................................240

Chapter 24 SOAP Services..............................................................................243 pub.soap.processor:list ....................................................................................246 pub.soap.processor:processMessage .............................................................246 pub.soap.processor:processRPCMessage .....................................................246 pub.soap.processor:registerProcessor ............................................................247



pub.soap.processor:unregisterProcessor........................................................ 247 pub.soap.schema:encoding............................................................................. 248 pub.soap.schema:envelope............................................................................. 248 pub.soap.utils:addBodyEntry ........................................................................... 248 pub.soap.utils:addHeaderEntry ....................................................................... 248 pub.soap.utils:addTrailer ................................................................................. 250 pub.soap.utils:createSoapData ....................................................................... 250 pub.soap.utils:exitUnableToUnderstand.......................................................... 251 pub.soap.utils:getActor .................................................................................... 251 pub.soap.utils:getBody .................................................................................... 252 pub.soap.utils:getBodyEntries ......................................................................... 252 pub.soap.utils:getDocument ............................................................................ 253 pub.soap.utils:getHeader................................................................................. 253 pub.soap.utils:getHeaderEntries ..................................................................... 254 pub.soap.utils:getMustUnderstand .................................................................. 254 pub.soap.utils:getQName ................................................................................ 256 pub.soap.utils:getTrailers................................................................................. 256 pub.soap.utils:removeBodyEntry..................................................................... 256 pub.soap.utils:removeHeaderEntry ................................................................. 257 pub.soap.utils:removeTrailer ........................................................................... 258 pub.soap.utils:requestResponseSpec ............................................................. 258 pub.soap.utils:soapDataToString .................................................................... 259 pub.soap.utils:streamToSoapData .................................................................. 259 pub.soap.utils:stringToSoapData .................................................................... 260 pub.soap.utils:validateSoapData ..................................................................... 260 pub.soap.utils:QName ..................................................................................... 261

Chapter 25 Storage Services.......................................................................... 262 pub.storage:add............................................................................................... 264 pub.storage:closeStore.................................................................................... 264 pub.storage:deleteStore .................................................................................. 264 pub.storage:get................................................................................................ 265 pub.storage:keys ............................................................................................. 265 pub.storage:listStores ...................................................................................... 265 pub.storage:lock .............................................................................................. 266 pub.storage:put................................................................................................ 266 pub.storage:registerStore ................................................................................ 267 pub.storage:remove......................................................................................... 267

Welcome!


pub.storage:unlock...........................................................................................267

Chapter 26 String Services .............................................................................271 pub.string:HTMLDecode..................................................................................274 pub.string:HTMLEncode ..................................................................................274 pub.string:URLDecode.....................................................................................274 pub.string:URLEncode.....................................................................................275 pub.string:base64Decode................................................................................275 pub.string:base64Encode ................................................................................275 pub.string:bytesToString..................................................................................276 pub.string:concat..............................................................................................276 pub.string:indexOf............................................................................................276 pub.string:length ..............................................................................................276 pub.string:lookupDictionary .............................................................................277 pub.string:lookupTable.....................................................................................277 pub.string:makeString ......................................................................................277 pub.string:messageFormat ..............................................................................278 pub.string:numericFormat................................................................................278 pub.string:numericParse..................................................................................279 pub.string:padLeft ............................................................................................280 pub.string:padRight..........................................................................................281 pub.string:replace ............................................................................................281 pub.string:stringToBytes ..................................................................................282 pub.string:substring..........................................................................................282 pub.string:toLower ...........................................................................................283 pub.string:toUpper ...........................................................................................283 pub.string:tokenize...........................................................................................283 pub.string:trim ..................................................................................................284 pub.string:gzip..................................................................................................284 pub.string:ungzip..............................................................................................284

Chapter 27 Sync Services ...............................................................................285 pub.sync:notify .................................................................................................287 pub.sync:wait ...................................................................................................287

Chapter 28 Table Services ..............................................................................289 pub.table:recordListToTable ............................................................................291 pub.table:stringTableToTable ..........................................................................291 pub.table:tableToRecordList ............................................................................291



pub.table:tableToStringTable .......................................................................... 292

Chapter 29 Universal Name Services............................................................ 293 pub.universalName:find ................................................................................... 295 pub.universalName:list .................................................................................... 295

Chapter 30 Web Services ............................................................................... 297 pub.web:createRegions ................................................................................... 299 pub.web:documentToRecord........................................................................... 300 pub.web:freeDocument.................................................................................... 306 pub.web:getDocumentType............................................................................. 306 pub.web:getNextNode ..................................................................................... 307 pub.web:getNodeIterator ................................................................................. 308 pub.web:loadDocument ................................................................................... 310 pub.web:makeArrays ....................................................................................... 315 pub.web:queryDocument................................................................................. 315 pub.web:recordToDocument ........................................................................... 317 pub.web:stringToDocument............................................................................. 321

Chapter 31 WebTap Services ......................................................................... 325 pub.webtap:getPage........................................................................................ 327 pub.webtap:triggerSpec................................................................................... 327

INDEX………....................................................................................................... 331

Welcome!

1


Chapter 1 Introduction

Welcome!................................................................................... 16

Typographical Conventions ....................................................... 17

Related Documentation ............................................................. 18

Viewing this Document .............................................................. 19

Printing this Guide ..................................................................... 20



Welcome! The Built-In Services Reference Guide describes the built-in services provided with a standard installation of the SAP BC server. All of the services contained in this guide are located in the WmPublic or WmDB packages.

Services are separated into folders based on function. The following table describes the folders in the WmPublic and WmDB packages.

Folder Page Contains Services You Use To…

client 21 Formulate and submit requests to HTTP, FTP, and SMTP servers.

cluster 43 Handle some tasks for clusteried BC installations

compress 46 Services for Zip and GZip algorithms

db 55 Access JDBC-enabled databases.

date 77 Generate and format date values.

event 85 Build audit-handlers and event-handlers.

file 109 Perform operations on the local file system

flow 115 Perform debugging and utility-type tasks in a flow service.

io 124 Convert between streams and byte arrays

ldap 127 Access and update information on an LDAP directory server.

list 137 Retrieve, replace, or add elements in an object list, record list, or string list; convert string lists to record lists.

math 143 Add, subtract, multiply, or divide string-based numeric values.

mime 149 Create MIME messages. Extract information from MIME messages.

packages 165 Install, load, and/or alter the status of a package on the SAP BC.

record 171 Perform operations on Records in the pipeline.

remote 177 Invoke services on remote SAP BC servers.

replicator 185 Replicate packages across SAP BC servers.

Typographical Conventions


Folder Page Contains Services You Use To…

report 193 Apply an output template to the values in the pipeline.

scheduler 199 Schedule services to execute at the times you specify.

schema 211 Validate objects or values in the pipeline.

security 217 Control which client certificates are sent to other services and to digitally sign data and process digital signatures.

smime 233 Create digitally signed and/or encrypted MIME messages. Process signed and encrypted MIME messages.

soap 243 Send and receive SOAP messages.

storage 262 Create, close, delete, and register data stores. Insert and retrieve information from data stores.

string 271 Perform string manipulation and substitution operations.

sync 285 Coordinate the execution of services.

table 289 Convert instances of com.wm.util.Table to other data types.

universalName 293 Get information from the Universal Name Registry.

web 297 Perform operations on XML and HTML documents.

webtap 325 Build services that monitor HTTP requests and conditionally executes a prescribed set of actions based on the URL requested by a client.

Typographical Conventions This document uses the following typographical conventions:

Convention Example

Terms that identify elements, options, selections, and commands on the screen are shown in bold.

The Service field on the Properties tab specifies the name of the requested service.

Characters that you must type exactly are shown in a typewriter font.

Type: setup and then press ENTER.

Variable information that you must type based on your specific situation or

Type: <sapbc>\setup and then press ENTER.



Convention Example environment is shown in italics.

Keyboard keys are shown in uppercase. Press ENTER; then press TAB.

Keys that you must press simultaneously are joined with the “+” symbol.

Press CTRL+ALT+M.

Directory paths are shown with the “\” directory delimiter unless the subject is UNIX-specific. In these cases, the “/” is used. If you are working in a UNIX environment, substitute a “/” for the “\” shown in the procedures in this book.

<sapbc>\server\packages\Default

Convention Example

Information that you must read that alerts you to negative consequences of certain actions is denoted in this manner.

Important! If the folder is not already open in the Service Browser, open it before you start the following procedure.

Notes that provide related, but non-critical, information are denoted in this manner.

Note: When you start SAP BC Developer, you are prompted to log on to a SAP BC server.

Program Code Conventions For programming code and command syntax, this document uses the following typographical conventions:

Convention Example

Keywords and values that you must type exactly as printed are shown in typewriter font.

%CoSymbol%

Variable values or parameters that you must supply are shown in italics.

%VarName%

Keywords or values that are optional are enclosed in [ ]. Do not type the [ ] symbols in your own code.

%loop LoopVar [null=NullValue]%

Related Documentation The following documents are companions to this guide.

Refer to this book… For…

SAP BC Developer Guide

Information about how to use the Developer to build services. It also contains information about creating client applications, working with

Viewing this Document


Refer to this book… For… output templates, and accessing databases through the SAP BC server. This book is for integrators.

You will find this book at: <sapbc>\Developer\doc\ISDeveloperGuide.pdf

Building Output Templates and DSPs

Information about creating output templates and Dynamic Server Pages (DSPs). This reference is for solution developers. You will find this book at: <sapbc>\Developer\doc\ISTemplatesAndDSPs.pdf

SAP BC Administration Guide

Information about using the Server Administrator to configure, monitor, and control the SAP BC server™. This book is aimed at server administrators.

You will find this book at: <sapbc>\Server\doc\ISAdministratorsGuide.pdf

SAP BC Java API Reference

Descriptions of the Java classes and built-in services you use to create services. This reference is aimed at integrators who build services.

You will find this book at: <sapbc>\Developer\doc\api\Java\index.html

Developer Online Help Information about the controls in SAP BC Developer application windows and step-by-step procedures describing how to perform tasks with Developer.

To open online help, press F1 or select the Contents command from the Help menu.

Viewing this Document To view this document, which is in PDF format, you must have Acrobat® Reader 4.0 or later installed on your computer. If you have an earlier version of Acrobat Reader, you will receive the following error message when you open this document and Acrobat Reader will not display the images in this document:

Could not find the ColorSpace named ‘Cs8.’

If you do not have Acrobat Reader, or you do not have the correct version, you can download a copy from http://www.adobe.com/products/acrobat/readstep2.html?ogn=EN_US-gntray_dl_get_reader

http://www.adobe.com/products/acrobat/readstep2.html?ogn=EN_US-gntray_dl_get_reader

http://www.adobe.com/products/acrobat/readstep2.html?ogn=EN_US-gntray_dl_get_reader



Printing this Guide You can print this guide from Adobe® Acrobat Reader. The document’s title page and table of contents are at the end of the printed copy. To create a traditional, paper-based manual, simply move these pages to the front of the document after it is printed.


Chapter 2 Client Services

You use client services to formulate and submit requests to HTTP, FTP, and SMTP servers.

2

C H A P T E R 2 C l i e n t S e r v i c e s


Summary o f Serv ices in th is Fo lder

The following services are available in this folder:

Service Function pub.client:ftp Logs on to an FTP server. Changes to a specified working directory. Performs one of the

following FTP commands: ls, put or get. Logs off the FTP server.

pub.client.ftp:append Appends data to a remote file. If the remote file does not exist, the service creates the file.

pub.client.ftp:cd Changes the current working directory during an FTP session (corresponds to the FTP user command cd dirpath).

pub.client.ftp:cdls Changes the current working directory and retrieves the file list during an FTP session (corresponds to the FTP user commands cd dirpath and ls namepattern).

pub.client.ftp:delete Deletes a file in the current working directory on an FTP server (corresponds to the FTP user command delete somefile).

pub.client.ftp:get Retrieves a file from a remote FTP server (corresponds to the FTP user command get).

pub.client.ftp:login Connects to a remote FTP server and logs in with a specified user name and password. You must use this service to initiate an FTP session before you can use other services within pub.client.ftp.

pub.client.ftp:logout Logs out of the current FTP session.

pub.client.ftp:ls Retrieves the file list during an FTP session (corresponds to the FTP user command ls namepattern).

pub.client.ftp:mdelete Deletes multiple files in the current working directory on an FTP server (corresponds to the FTP user command mdelete pattern).

pub.client.ftp:mget Transfers multiple files from the remote FTP server (corresponds to the FTP user command mget).

pub.client.ftp:mput Transfers multiple files to a remote ftp server from the local SAP BC server (corresponds to the FTP user command mput).

pub.client.ftp:put Transfers a file to a remote ftp server from the local SAP BC server (corresponds to the FTP user command put).

pub.client.ftp:quote Send a subcommand to a remote ftp server

Printing this Guide


pub.client.fp:quote

Description Send a subcommand to a remote ftp server. You can find information about of possible commands in the documentation of the ftp server software.

Package WmPublic

Input Variable Name Type Description

sessionkey String Unique key that identifies current session information. The sessionkey is output from the pub.client.ftp:login service.

String String The command to be handled by the remote ftp server

Output Variable Name Type Description

returncode String Standard FTP protocol return code.

returnmsg String Standard FTP protocol return message.

logmsg String FTP log messages for the entire user session.

pub.client.ftp:rename

Renames a file on a remote server.

pub.client.ftp:sessioninfo Returns session information for all of the FTP servers that users are currently logged into.

pub.client:http Issues an HTTP request that you specify and returns the HTTP response (headers and data).

pub.client:smtp Sends a MIME-type e-mail message. You may attach one or more content objects or files to the message.

pub.client:soapHTTP Submits a SOAP message to a server via HTTP or HTTPS.

pub.client:soapRPC Submits a SOAP remote procedure call via HTTP or HTTPS.



pub.client:ftp

Description Executes the following sequence of FTP actions: Logs on to an FTP server. Changes to a specified working directory. Performs one of the following FTP commands: ls, put or get. Logs off the FTP server.

Package WmPublic


serverhost String Name or IP address of the FTP server. Example ftp.netscape.com

serverport String Port number of the FTP server. Example 4566

username String Valid FTP user of the remote FTP server. Example anonymous

password String Valid password of the FTP user.

command String One of the following FTP commands: ls, put, or get.

dirpath String Working directory of the FTP server. Example pub

transfermode String One of the following FTP file transfer modes: ascii or binary

transfertype String One of the following FTP data transfer modes: passive or active

localfile String When command is set to put, this value specifies the name of the local file you want to transfer. (When content is not null, this field is ignored.) When command is set to get, this variable specifies the name of the local file in which you want the retrieved content saved.

remotefile String When command is set to put, this value specifies the name of the remote file in which you want the save the data you are sending. When command is set to get, this variable specifies the name of the remote file that you want to retrieve.

content Object Data to be transferred when command is set to put.

encoding String Optional. Character set in which the document is encoded. This information is required to correctly convert the String object to bytes when performing a get. Specify an IANA-registered character set. If variable is null, the default JVM encoding is used. Example ISO-8859-1

Printing this Guide



Variable Name Type Description

timeout String Optional. Time (measured in seconds ) to wait for a response from the ftp server before timing out and aborting the request. Default is to wait forever.

newSession String Optional. ‘yes’ if a new session shall be created for this request. If this parameter is not set to ‘yes’ and some session is already open, the command is send using the existing session.

clientTimeout String Optional. Time (measured in seconds) a session held idle before it is closed.


command String The FTP command that was executed (ls, get, or put).

dirlist String [ ] A String array containing the list of file names returned by the ls command.

localfile String The name of the local file used for a get or put operation.

remotefile String The name of remote file name used for a get or put operation.

content byte [ ] If localfile was not specified, this variable will contain the Content object sent to the remote server (if a put command was executed) or received from the remote server (if a get command was executed).



logmsg String FTP log messages.

pub.client:http

Description Issues an HTTP request that you specify and returns the HTTP response.

Package WmPublic

Input Variable Type Description

url String A String specifying the URL of the resource that you want to access. This string must begin with http: or https:

Example http://www.rubicon.com/orders/orders.html

method String A String specifying the HTTP method you want to use. Valid values are:

delete

get

head

options

post

put

trace loadAs String Optional. A String specifying the form in which you want the http

service to store the returned document.

Set loadAs to… To…



bytes Default. Return the body of the response as a byte[ ]. Use this option if the body will be used as input to a service that operates on whole HTML or XML documents (for example, queryDocument).

stream Return the body of the response as an InputStream. Use this option if the document will be used as input to a service that can process documents incrementally (for example, getNodeIterator).

Variable Type Description

data Record A Record (an IData object) specifying the data that you want the http service to submit with the HTTP request. Specify your data in one or more of the following keys.

Important! When you use more than one element to specify data, args is appended first, table is appended second, and string is appended last.

Key Description

args A Record (IData) specifying the name=value pairs that you want this service to submit to the resource in url.

You can use args to submit data via either the POST, GET, or HEAD method. To specify data using args, create one String element for each name=value pair that you want to submit, where:

The element’s name represents the name portion of the pair, and…

The element’s value represents the value portion of the pair.

Note that when you use args, the http service will:

automatically url-encode name=value pair, so you do not need to url-encode the values you specify in args.

automatically insert the “&” character between pairs, so you do not need to include it in args.

automatically prefix the entire query string with the “?” character if it submits the data in args via a GET or HEAD. You do not need to include this character in args.

When you submit data using the args variable, the SAP BC server automatically sets the value of the Content-Type header to application/x-www-form-urlencoded. If you want to explicitly specify a different Content-Type, you must submit your data using the string or bytes variable.

table A String Table (a String [ ][ ]) specifying the data that

Printing this Guide


the http service will use to construct a query string to submit to the resource specified in url. table is similar to args, but it allows you to submit unnamed values in a query string, not just name=value pairs. To specify data using table, create one row for each value that you want to submit, where:

The contents of column 0 represents the name portion of the pair (leave this column null to submit an unnamed value, and…

The contents of column 1 represents the value portion of the pair.

Note that when you use table, the http service will:

automatically url-encode name=value pair, so you do not need to url-encode the values you specify in table.

automatically insert the “&” character between the pairs (or unnamed values) that it constructs, so you do not need to include it in table.

automatically prefix the entire query string with the “?” character if it submits the data in table via the GET method. You do not need to include this character in table.

When you submit data using the table variable, the SAP BC server automatically sets the value of the Content-Type header to application/x-www-form-urlencoded. If you want to explicitly specify a different Content-Type, you must submit your data using the string or bytes variable.

string A String containing the text that you want the http service to submit to the resource in url.

You can use string to submit data via the POST, GET, or HEAD method.

If you use string to submit data, make sure that you specify the string exactly as you want it presented in the HTTP request. (If you are using the GET or HEAD method, make sure you url-encode the contents of string) Note that when you use string, the http service will automatically prefix the entire query string with the “?” if it submits the data in string via a GET or HEAD. You do not need to include this character in string. When performing a POST, string will be submitted to the resource defined by url as the body of the document.



bytes Optional. A byte[ ] containing the data that you want this service to submit to the resource in url.

You can only use bytes to submit data via the POST method.

Important! When you use bytes and another element (args, table, or string) to specify data, the service appends the data from the args, table, or string element to url. The service appends args to url first, table second, and string last. The service encodes the data from the bytes element in the body of the post. If the stream variable is not null, bytes is ignored.

mimeStream Optional. An InputStream containing a MIME or SMIME message that you want this service to submit to the resource in url. A mimeStream is created by the pub.mime:getEnvStream, pub.smime:createEncryptedData, or pub.smime:createSignedData services. It contains both headers and content. The headers in the mimeStream are appended to the http headers. You can only use mimeStream to submit data via the POST method.

stream Optional. An InputStream containing the data that you want the http service to submit to the resource in url You can only use stream to submit data via the POST method.

Important! When you use stream and another element (args, table, string or bytes) to specify data, the service appends the data from the args, table, or string element to url. The service appends args to url first, table second, and string last. The service encodes the data from the stream element in the body of the post. If the stream input is not null, the bytes input is ignored.

encoding Optional. A String specifying the character set in which the URL data parameters are encoded (args or table and/or string). Encoding is required to correctly convert the String object to bytes when generating the URL for a post. Specify an IANA-registered character set. If this variable is null, the default JVM encoding is used. Because string is used in the body of the post and not used for building the URL, you do not need to specify encoding for the data parameter string. Example ISO-8859-1

auth Record Optional. A Record (an IData object) that specifies authorization information that the http service will submit if the resource specified in url is protected.

Key Description

Printing this Guide


type A String specifying the type of authentication that you want the http service to use when it submits this request. If you are accessing a protected resource, set auth to Basic.

user A String specifying the user name that this service will submit when requesting a protected resource.

pass A String specifying the password associated with user.

headers Record Optional. A Record (an IData object) that specifies the fields that you want to explicitly override in the HTTP request header issued by the http service. Specify one element in the headers Values object for each header field that you want to set, where: The element’s name represents the name of the header field, and…

The element’s value represents the value of that header field.

If you do not set headers, the http service uses its default header values.

Output Variable Type Description

encodedURL String A String containing the URL that was submitted by pub.clinet:http. This will contain any argument set in args, table, or string.

header Record A Record (an IData object) containing the HTTP response headers.

Key Description

lines A Record (an IData object) containing the fields in the response header, where key names represent field names and values represent field values.

status A String string containing the HTTP status code of the response.

statusMessage A String containing the HTTP status message of the response.

body Record A Record (an IData object) containing the body of the HTTP response.

Key Description

bytes A byte[ ] containing the body of the HTTP response. bytes is returned only when the loasAs input parameter is set to bytes.

stream An InputStream containing the body of the HTTP response. stream is returned only when the loasAs input parameter is set to stream.

Usage Notes If pub.client:http does not receive a response within the timeout period specified in the server’s watt.net.timeout parameter, it will throw an exception. For information about the watt.net.timeout parameter, see the SAP BC Administraion Guide.

pub.client:smtp

Description Sends a MIME-type e-mail message. You may attach one or more content objects or files to the message.



Package WmPublic


to String Receiver’s e-mail address. If you specify multiple addresses, separate them with commas.

cc String Optional. Additional receiver’s e-mail addresses. If you specify multiple addresses, separate them with commas.

bcc String Optional. Additional receiver’s e-mail addresses. If you specify multiple addresses, separate them with commas.

subject String Subject of the message.

subjectCharset String A "charset" used to encode the MIME message subject text. (The message is encoded according to RFC 2047, MIME Part 3.) If no subjectCharset is specified and any characters in the subject text are not US-ASCII, the "charset" will be set to the default file encoding of the JRE where the server is running.

charset String A "charset" used to encode the MIME message. If no charset is specified and any characters are not US-ASCII, the "charset" will be set to the default file encoding of the JRE where the server is running.

From String Sender’s email address.

Mailhost String The SMTP host name for outbound messages (e.g., smtp.webMethods.com).

auth Record Optional. A Record (an IData object) that specifies authorization information that the http service will submit if the resource specified in url is protected.

Key Description

user A String specifying the user name that this service will submit when requesting a protected resource.

pass A String specifying the password associated with user.

body String Comments (text string) about the content.

mimeStream InputStream Optional. A MIME or S/MIME message that you want to send in the email. A mimeStream is created by the pub.mime:getEnvStream, pub.smime:createEncryptedData, or pub.smime:createSignedData services. It contains both headers and content. If the mimeStream already contains the from, to, and subject headers, you do not need to pass them as individual inputs to this service.

attachments Values [ ] Optional. Attachments of the message. Each attachment is defined as a message part in a multi-part message.

Variable Name Type Description contenttype String MIME type of the message, e.g.

application/x-edi-message

Printing this Guide



content Object Content of the message of type byte[ ], String, or java.io.InputStream.

filename String Name of a local file to be attached to the message. Used only when content is null.

encoding String Encoding of the message, e.g., base64 or 7bit. If encoding is not specified, the default 7bit is used.


status String Final status of service.

Usage Note If you are using filename to attach a file to the message and the file is not a plain text file, you need to set the contenttype and encoding. Example To attach <sapbc>\Server\mydir\myfile.doc to a pub.client:smtp service, invoke the service with the following attachment values for the variables: contenttype: application/msword filename: mydir/myfile.doc encoding: base64

pub.client.ftp:append

Description Appends data to a remote file. If the remote file does not exist, the service will create the file.

Package WmPublic



transfermode String The FTP file transfer mode. Specify ascii or binary.

content Object Data to be appended to the remote file

localfile String Optional. The name of a local file to be appended to the remote file. Used if content is null.

remotefile String Name of remote file to which data or local file will be appended.





pub.client.ftp:cd

Description Changes the current working directory during an FTP session (corresponding to the standard FTP user command cd dirpath).

Package WmPublic





dirpath String The working directory of the FTP server, e.g., pub.





pub.client.ftp:cdls

Description Changes the current working directory and retrieves the file list during an FTP session (corresponding to the standard FTP user commands cd dirpath and ls namepattern).

Package WmPublic



dirpath String The working directory of the FTP server, e.g., public.

filenamepattern String Optional. A pattern that specifies the file names of the files to retrieve, e.g., *.txt.


dirlist String [ ] The list of file names in the format of a String array.



logmsg String FTP log messages.

pub.client.ftp:delete

Description Deletes a file in the current working directory on an FTP server (corresponding to the standard FTP user command delete somefile).

Package WmPublic



remotefile String The names of the files to be deleted from the current working directory, e.g., text.txt. If you use pattern-matching characters in filename, multiple files will be deleted.





Printing this Guide


pub.client.ftp:get

Description Retrieves a file from a remote FTP server (corresponding to the standard FTP user command get).

Package WmPublic



transfermode String The FTP file transfer mode; specify either ascii or binary.

localfile String Optional. The name of a local file where the content is saved.

remotefile String The name of the remote file.

encoding String Optional. Character set in which the document is encoded. This variable is required to convert the String object to bytes correctly. Specify an IANA-registered character set. If this variable is null, then the encoding currently set for the FTP session is used. If encoding was never set for this FTP Session, the default JVM encoding is used. Example ISO-8859-1


content byte[ ] The data content that was retrieved by the get command.




pub.client.ftp:login

Description Connects to a remote FTP server and logs in with a specified user name and password. You must use this service to initiate an FTP session before you can use other services within pub.client.ftp.

Package WmPublic


serverhost String The name or IP address of the FTP server, e.g., ftp.netscape.com.

serverport String The port number on which the FTP server listens for requests, e.g., 4566. The default is 21.

dataport String Optional. The listener port number of the data transfer channel, e.g., 3345. If you do not specify dataport, the SAP BC server will choose the listener port number. This value is only used when transfertype is active.

username String A valid FTP user on the remote FTP server, e.g., anonymous.

password String A valid password for the FTP user specified in username, e.g., someone@somewhere.

transfertype String The type of the FTP data transfer mode. Specify either passive or active.




encoding String Character set in which the document is encoded. This variable is required to convert the String object to bytes correctly. Specify an IANA-registered character set. If this variable is null, the default JVM encoding is used. Example ISO-8859-1

timeout String Optional. Time (measured in seconds) to wait for a response from the ftp server before timing out and aborting the request. The default is to wait forever.

newSession String Optional. ‘yes’ if a new session shall be created for this request. If this parameter is not set to ‘yes’ and some session is already open, the command is send using the existing session.

clientTimeout String Optional. Time (measured in seconds) a session held idle before it is closed.






pub.client.ftp:logout

Description Logs out of the current FTP session.

Package WmPublic







pub.client.ftp:ls

Description Retrieves the file list during an FTP session (corresponding to the standard FTP user command ls namepattern).

Package WmPublic



filenamepattern String Optional. A pattern that specifies the file names of the files to retrieve, e.g., *.txt.

Printing this Guide



dirlist String [ ] The list of file names in String array format.




pub.client.ftp:mdelete

Description Deletes multiple files in the current working directory on an FTP server (corresponding to the standard FTP user command mdelete pattern).

Package WmPublic



filenamepattern String A pattern that specifies the file names of the files to be deleted from the current working directory, e.g., *.txt. If you do not specify a value for filenamepattern, all files in the current working directory are deleted.





pub.client.ftp:mget

Description Transfers multiple files from the remote FTP server (corresponding to the standard FTP user command mget).

Package WmPublic




localdir String The directory in the local file system where you want the remote files to be saved, e.g., c:\temp\ftpfiles.

filenamepattern String A pattern that specifies the file names of the files to be transferred, e.g., *.txt.

encoding String Optional. Character set in which the document is encoded. This variable is required to convert the String object to bytes correctly. Specify an IANA-registered character set. If this variable is null, then the encoding currently set for the FTP session is used. If encoding was never set for this FTP Session, the default JVM encoding is used. Example ISO-8859-1




filenames String [ ] The list of files being transferred from the remote FTP server.




pub.client.ftp:mput

Description Transfers multiple files to a remote ftp server from the local SAP BC server (corresponding to the standard FTP user command mput).

Package WmPublic




transfermode String The FTP file transfer mode, either “ascii” or “binary”.

localdir String The directory in the local file system that contains the files you want to transfer to the remote FTP server, e.g., c:\temp\ftpfiles.

filenamepattern String A pattern that specifies the file names of the files to be transferred, e.g., *.txt.


filenames String [ ] The list of files being transferred to or from remote FTP server.




pub.client.ftp:put

Description Transfers a file to a remote ftp server from the local SAP BC server (corresponding to the standard FTP user command put).

Package WmPublic




content Object The data content to be transferred with the put command.

localfile String Optional. The name of a local file that you want transferred with the put command when you do not specify a value for content; that is, if content is null. If you specify a value for content, this field is ignored.

remotefile String The name of the remote file.

Printing this Guide






pub.client.ftp:quote

Description Send a subcommand to a remote ftp server. You can find information about of possible commands in the documentation of the ftp server software.

Package WmPublic



String String The command to be handled by the remote ftp server





pub.client.ftp:rename

Description Renames a file on a remote server.

Package WmPublic



oldname String Current pathname of the file you want to rename. Example temp/oldname.txt

newname String New pathname for the file you want to rename. Example temp/newname.txt





pub.client.ftp:sessioninfo

Description Returns session information for all of the FTP servers that users are currently logged into.

Package WmPublic


name String Not used. Reserved for future use.




sessioninfo IData [ ] IData object containing information about the session.

Key Type Description

serverhost String The name or IP address of the FTP server, e.g., ftp.netscape.com.

serverport String The port number on which the FTP server listens for requests, e.g., 4566.

dataport String The listener port number of the data transfer channel, e.g., 3345. If you do not specify dataport, the SAP BC server will choose the listener port number. The dataport is only used when transfertype is set to active.

username String A valid FTP user on the remote FTP server, e.g., anonymous.

password String A valid password for the FTP user specified in username, e.g., anything.

transfertype String The type of the FTP data transfer mode. Specify either passive or active.

encoding String Optional character set used to correctly convert the String object to bytes on pub.client.ftp:get and pub.client.ftp:mget services. If no value is returned, then the encoding was not explicitly set and the default JVM encoding is used.

pub.client:soapHTTP

Description Submits a SOAP message to a server via HTTP or HTTPS.

Package WmPublic


soapRequestData Object The SOAP object that contains the SOAP message that is to be sent.

address String The URL to which you want the SOAP message sent. Examples http://rubicon:5555/soap/default

https://rubicon:5555/soap/default

auth Record Optional. A Record (an IData object) specifying the credentials that are to be submitted to the server specified in address:

Key Value

type A String specifying the type of authentication that the service will perform. Set type to basic or leave unspecified.

Printing this Guide


Key Value

user A String specifying the user name that this service will use if one is requested.

pass A String specifying the password that this service will submit if one is requested.

validateSOAP String Optional. A String that indicates whether or not the response message is to be validated against the SOAP schema.

Set to… To…

true Validate the response message and throw an exception if the response does not conform to the SOAP schema.

false Default. Bypass the validation process. SOAPAction String Optional. A String specifying the value to which you want to set

the SOAPAction HTTP header. Note: The SOAPAction header was required by the initial SOAP specification, but has since been deprecated. The SAP BC does not use the SOAPAction header and accepts SOAP messages that omit it. If you are designing a completely new solution, we recommend that you avoid using the SOAPAction header. However, if you exchange SOAP messages with systems that require a SOAPAction header, this parameter allows you to set it.


soapResponseData Object A SOAP object containing the SOAP response message returned by the server specified in address.

header Record A Record (an IData object) containing the HTTP headers. It contains the following keys:

Key Value

lines A Record (an IData object) in which each entry represents a field (line) of the response header. Key names represent the names of header fields and the key’s values are Strings containing the values of the fields.

status A String that contains the status code from the HTTP response.

statusMessage A String that contains the status message from the HTTP response.

soapStatus String A String indicating whether the SOAP request message was processed successfully, where:

A value of... Indicates that...

0 The remote server successfully processed the SOAP request and returned a SOAP response message.

1 The remote server returned a SOAP fault,




indicating that the SOAP request was received, but was not processed successfully.

2 The server returned an error that was not a SOAP fault. This indicates that some type of HTTP error occurred (often, an HTTP 404). You can check the status element in header to determine the type of HTTP error that occurred.

Usage Notes To send a SOAP message with this service, you must first generate an empty SOAP object with the createSoapData service and then populate it using services such as addHeader, addBody, and addTrailer. For information about creating and sending SOAP messages, see the SAP BC SOAP Programming Guide.

See Also pub.client:soapRPC

Examples sample.soap:buildMsg_sendHTTP

pub.client:soapRPC

Description Submits a SOAP remote procedure call via HTTP or HTTPS.

Package WmPublic


address String A String specifying the numeric address or domain name of the server on which the remote procedure resides. (If you are submitting the request to a SAP BC server, remember to direct it to the RPC processor as shown in the following example.) Example: http://rubicon:5555/soap/rpc

reqParms Record A Record (an IData object) whose elements represent the input parameters that are to be passed to the remote procedure. Example: If you wanted to pass three String parameters, acct, amt, and org, containing the values, Cash, 150.00 and Sales, reqParms would contain the following:

Key Value

acct Cash

amt 150.00

org Sales method Record A Record (an IData object) specifying the QName of the

requested procedure where:

Key Value

namespaceName A String specifying the namespace portion of the procedure’s QName.

localName A String specifying the local portion of the procedure’s QName.

auth IData Optional. A Record (an IData object) specifying the user name and password that are to be submitted to the server specified in address, where:

Printing this Guide


Key Value

type A String specifying the type of authentication that the service will perform. Set type to basic or leave unspecified.

user A String specifying the user name that this service will use if one is requested.

pass A String specifying the password that this service will submit if one is requested.

targetInputSignature String Optional. A String specifying the fully qualified name of the stored Record or Specification that is to be used to validate and encode the contents of reqParms.

targetOutputSignature String Optional. A String specifying the fully qualified name of the stored Record or Specification that will be used to validate and decode the output value returned by the remote procedure.

SOAPAction String Optional. A String specifying the value to which you want to set the SOAPAction HTTP header. Note: The SOAPAction header was required by the initial SOAP specification, but has since been deprecated. The SAP BC does not use the SOAPAction header and accepts SOAP messages that omit it. If you are designing a completely new solution, we recommend that you avoid using the SOAPAction header. However, if you exchange SOAP messages with systems that require a SOAPAction header, this parameter allows you to set it.

loadAs String Optional. A String containing the type of the result Stream. The result as can be loaded as “stream” or “byteArrayStream”. Default is “stream”.


soapResponseData Object A SOAP object containing the SOAP response message returned by the server specified in address.

respParms Record A Record (an IData object) containing the output parameters returned by the remote procedure. Example: If the remote procedure returned two String parameters, status and balance, containing the values, closed and –4.95, respParms would contain the following: Key Value

status closed

balance -4.95

header Record A Record (an IData object) containing the HTTP headers.

Key Value

lines A Record (an IData object) in which each entry represents a field (line) of the response header. Key names represent the names of header fields and key values are Strings containing the values of the fields.



Key Value

status A String that contains the status code from the HTTP response.

statusMessage A String that contains the status message from the HTTP response.

soapStatus String A String indicating whether the SOAP request was processed successfully, where:


0 The remote server successfully processed the SOAP request and returned a SOAP response message.

1 The remote server returned a SOAP fault, indicating that the SOAP request was received, but was not processed successfully.

2 The server returned an error that was not a SOAP fault. This indicates that some type of HTTP error occurred (often, an HTTP 404). You can check the status element in header to determine the type of HTTP error that occurred.

See Also pub.client:soapHTTP

Examples sample.soap:buildRPC_SendHTTPSimple

Printing this Guide


Chapter 3 Clustering

Youu use these Services to get information about and set settings for a SAP Business Connector cluster

3

C H A P T E R 3 C l u s t e r i n g




Service Function pub.cluster:disableServiceRedir Disable or enable redirection for a service.

pub.cluster:disableSessionRedir Disable or enable redirection for the current session.

pub.cluster.getClusterHosts Get a list of hosts in the cluster.

Printing this Guide


pub.cluster:disableServiceRedir

Description Disable or enable redirection for a Service

Package WmPublic


redir String Optional. String containing a Boolean

“true”: enable redirection for the service

“false”: disable redirection for the service (default)

service String A String containing the service to disable/enable the redirection for.

pub.cluster:disableSessionRedir

Description Dis- or enable redirection for the current Session

Package WmPublic


redir String Optional. String containing a Boolean

“true”: enable redirection for the service

“false”: disable redirection for the service (default)

pub.cluster.getClusterHosts

Description Get a list of the hosts in the cluster

Package WmPublic

Input None


hosts Values[] List of hosts located in the cluster

C H A P T E R 4 Z i p a n d G Z i p a l g o r i t h m s

46 SAP BC Bulit-In

Chapter 4 Zip and GZip algorithms

These services provide access to zip and gzip algorithms.

4

Services Guide 4.8

Printing this Guide




Service Function pub.compress.gzip:addInputData Add data to a gzip Archive.

pub.compress.gzip:closeGZIPCompressor Close a gzip compressor.

pub.compress.gzip.createGZIPCompressor Create a new gzip compressor (a new archive to add data to)

pub.compress.gzip:getOutputData Get the result of gzip processing.

pub.compress.gzip:gunzip GUnzip data located in a byte array.

pub.compress.gzip:gzip GZip a byte array.

pub.compress.gzip:openGZIPData Open a gzipped byte array for uncompressing.

pub.compress.gzip:readNextBlock Read the next block of data from a GZIPDecompressor opened using pub.compress.gzip:openGZIPData .

pub.compress.zip:addEntryData Add an entry to a zip archive.

pub.compress.zip:closeZIPArchive Close a zip archive and return the zipped data as byte array.

pub.compress.zip.createZIPArchive Create a new zip archive to write to.

pub.compress.zip:getOutputData Get the zipped data from a zip archive.

pub.compress.zip:openZIPArchive Open a zip archive to read from.

pub.compress.zip:readNextEntry Read the next entry from a zip archive.

pub.compress.zip:unzip Unzip zipped data located in a byte array.

pub.compress.zip:zip Zip data in a byte array.



pub.compress.gzip:addInputData

Description Takes a "GZIPCompressor" object and writes the data given in the input parameter "bytes" to it.

Package WmPublic


GZIPCompressor Object The compressor the data will be added to. Get a GZIPCompressor handle by calling the service pub.compress.gzip.createGZIPCompressor

bytes Object The data to be zipped and added to the compressor.

pub.compress.gzip:closeGZIPCompressor

Description This Service processes any still unprocessed input data, closes the GZIP stream and any other resources and returns the remaining gzipped output data in a byte array named "zippedBytes". Call this when done compressing data, no matter if you have collected intermediate results with getOutputData or not.

Package WmPublic


GZIPCompressor Object The compressor to be closed.


zippedBytes Object A byte array containing the result of the gzip processing.

pub.compress.gzip.createGZIPCompressor

Description This Service creates an empty GZIP stream, that can be used for writing binary data to it, and returns it as a "GZIPCompressor" object. This object is then used by the following three Services.

Package WmPublic

Input None


GZIPCompressor Object The compressor object which can be passed to the other GZIP Services.

pub.compress.gzip:getOutputData

Description Takes a "GZIPCompressor" object as input and returns the current contents of its output buffer. The input data that has already been processed (gzipped) and the current output buffer are freed for garbage collection. Note that this Service might return an empty byte array, if no zipped data is yet available. (Normally it takes about 200K, before the GZIP algorithm can start doing any useful work.) In this case just keep adding input data, and you will get the output with the next call of "getOutputData". Also if you don't want (need) to collect intermediate results, you can just keep adding input data and call "closeGZIPCompressor" in the end. But keep in mind, that in this case the output data remains in memory untill the end.

Package WmPublic

Printing this Guide



GZIPCompressor Object The compressor containing the gzipped data.


zippedBytes Object A byte array containing the result of the gzip processing.

pub.compress.gzip:gunzip

Description Unzip a zipped byte array

Package WmPublic


zippedBytes Object The byte array containing the zipped data


bytes Object A byte array containing the unzipped data.

pub.compress.gzip:gzip

Description gzip data in a byte array

Package WmPublic


bytes Object A byte array containing the data to be gzippes


zippedBytes Object A byte array containing the gzipped data.

pub.compress.gzip:openGZIPData

Description This Service takes a file in GZIP format as input ("zippedBytes"; needs to be a byte array) and converts it to a GZIPDecompressor object, which can be used by the following Service to gunzip the data incrementally block by block.

Package WmPublic


zippedBytes Object A byte array containing data to be ungzipped.


GZIPDecompressor Object The decompressor containing the data in zippedBytes.



pub.compress.gzip:readNextBlock

Description "readNextBlock" takes the GZIPDecompressor from the previous Service and tries to read "maxLength" uncompressed bytes from it. If "maxLength"is not specified, a block length of 65536 is used. The Service returns the number of bytes, it was actually able to decompress, in the output parameter "length", and the bytes themselves in "bytes". If the GZIPDecompressor object is empty (meaning the previous call to "readNextBlock" had decompressed the last remaining contents of it), the Service closes the GZIPDecompressor, removes it from the pipeline and returns "length = -1" and a null object for "bytes". So the two Services "openGZIPData" and "readNextBlock" can be used in a similar manner as illustrated for the "openZIPArchive" & "readNextEntry" pair in the demo Service pub.compress.demo:readZipArchive.

Package WmPublic


GZIPDecompressor Object The decompressor containing data to be gunzipped.

maxLength String A String contaiing the maximum number of bytes to be gunzipped from the GZIPDecompressor.


bytes Object A byte array containing the gunzipped data.

length String A String containing the number of ungzipped bytes.

pub.compress.zip:addEntryData

Description This Service takes a "ZIPArchive_writeMode" object as input and adds another entry (file) to it.

Package WmPublic


ZIPArchive_writeMode Object The Archive to add data to. It can be opened using the service pub.compress.zip.createZIPArchive.

Bytes Object The data of the entry. Needs to be a byte array

name String The filename (including any path information) of the entry

method String Optional. A String containing the method to be used. Possible values are

DEFLATED

STORED

level String Optional. A String setting the level the entry is added to (int value 0<=level<=9)

timestamp String Optional. Astring containing the timestamp for the entry, specified in milliseconds since 1970-01-01, 00:00:00. If omitted, the current time is used.

Printing this Guide


pub.compress.zip:closeZIPArchive

Description Finishes a "ZIPArchive_writeMode" object (which zips any still unprocessed input data), deletes it from the pipeline and returns the last remaining piece of output data as a byte array.

Package WmPublic


ZIPArchive_writeMode Object The Archive containing the zipped data.


zippedBytes Object A byte array containing the result of the zip processing.

pub.compress.zip.createZIPArchive

Description This Service creates an empty ZIP archive in write mode, that can be used for adding entries (files) to it. The input parameters "defaultCompressionLevel" and "defaultMethod" can be used to specify a default for all entries, that don't specify these parameters themselves. If you leave these parameters empty, the highest compression level "9" and the method "DEFLATED" will be used as defaults. The compression level can be in the range 0 - 9, and the method can be "DEFLATED" for compressing the entries or "STORED" for just adding them to the archive as they are. These defaults can later be overridden for a particular entry by setting the corresponding inputs of the Service "addEntryData". The output "ZIPArchive_writeMode" of this Service is in the correct format to be used by the "addEntryData", "getOutputData" and "closeZIPArchive" Services.

Package WmPublic


defaultCompressionLevel String Optional. A String containing the default compression level (an int value) to be used.

defaultMethod String Optional. A String containing the default method to be used. Possible values are

DEFLATED

STORED


ZIPArchive_writeMode Object The Archive to be used in other services.



pub.compress.zip:getOutputData

Description This Service can optionally be used to read the current contents of the output buffer of the ZIPArchive. It takes a "ZIPArchive_writeMode" as input and returns a byte array with whatever is currently available of already finished zipped data. The current output buffer of the ZIPArchive as well as the already processed input data are freed for garbage collection. Note that this Service may return an empty byte array, if no finished data is yet available from the ZIPArchive's output buffer! Depending on the size of the entries and the type of data, it may require adding several entries (normally around 200K), before the first zipped output becomes available. This Service should be used to get intermediate results when processing a big data volume that may take you to the limits of available memory. If memory is not an issue, you don't need to use it. Just keep adding entries, and when you are finished with the archive, call "closeZIPArchive" to retrieve the complete data of the finished archive.

Package WmPublic


ZIPArchive_writeMode Object The Archive containing the zipped data.


zippedBytes Object A byte array containing the result of the zip processing.

pub.compress.zip:openZIPArchive

Description Open a ZIPArchive for a byte array containing zipped data.

Package WmPublic


zippedBytes Object A byte array containing data to be ungzipped.


ZIPArchive_readMode Object The archive containing the data from the input parameter zippedBytes.

pub.compress.zip:readNextEntry

Description Takes a "ZIPArchive_readMode" object as input and returns the next entry from the archive.

The Service also automatically computes the CRC32 checksum of the uncompressed data and compares it with the CRC32 checksum given in the archive. If these two numbers don't match, an Exception is thrown. If the ZIP archive doesn't contain any more entries, this Service automatically closes it, removes it from the pipeline and returns a null Record as result.

As readNextEntry might be a bit difficult to use, there is alsoa demo Service, which shows an example of how to use it: pub.compress.demo:readZipArchive in the Package "Support", which can be downloaded from the BC download site, section "Software Updates". Another demo Service (writeZipArchive) demonstrates how to use the above Services to create a ZIP archive.

Package WmPublic


ZIPArchive_readMode Object The archive to read an entry from.

Printing this Guide



ZIPEntry Record A Record containing the data for the read zip entry.

Key Description

name A String containing the full name of the entry, including path information.

timestamp A String containing : the timestamp of the entry in milliseconds since 1970-01-01 00:00:00

compressedSize A String containing: the compressed size of the entry.

uncompressedSize A String containing the : real size of the entry, which will be equal to the size of the byte array "data".

ratio A String containing the compressed/uncompressed ratio for this entry as % value (0-100).

CRC32 A String containing the CRC32 checksum of the uncompressed data as given in the archive.

data A byte array containing the uncompressed data.

pub.compress.zip:unzip

Description Unzip a zipped byte array

Package WmPublic


zippedBytes Object The byte array containing the zipped data

checkSum String Optional. A String containing the checksum of the zipped data.


bytes Object A byte array containing the unzipped data.

pub.compress.zip:zip

Description zip data in a byte array

Package WmPublic


bytes Object A byte array containing the data to be zipped




check String Optional. Value Description

true Create and return a checksum for the zipped data.

false Default. A checksum is not created and returned.


zippedBytes Object A byte array containing the zipped data.

checksum String Optional. The checksum created for the zipped data when the parameter check is set to true.

zippedLength String A String containing the length of the returned byte array.

unzippedLength String A String containing the length of the unzipped byte array (the input parameter bytes).

Printing this Guide

SAP BC Bulit-In Services Guide 4.8

Chapter 5 Database Services

You use database services to access JDBC-enabled databases. Since 4.8, some methods are deprecated beare no longer needed with new internal connection management. Furthermore, when giving connection inyou should generally switch to the alias parameter and not use URL, user, password and driver anymore services here. Instead, maintain a DB alias in the Administrator UI, so that you only have one place for athis information.

5

55

cause they formation,

in the ccessing

C H A P T E R 5 D a t a b a s e S e r v i c e s




Service Function pub.db:call Invokes a stored procedure on a target database.

pub.db:clearTransaction Clears the transactional state within a database connection.

pub.db:close Deprecated. Closes a specified database connection.

pub.db:closeAll Deprecated. Closes all database connections that the session has opened.

pub.db:commit Commits changes to a database.

pub.db:connect Deprecated. Creates a connection to the database using the supplied JDBC URL, user name, and password. You can also specify a JDBC driver specific to the database.

pub.db:delete Removes all rows in the specified table that meet the given criteria.

pub.db:execSQL Executes the specified SQL statement. The service does not perform any parsing.

pub.db:getProcInfo Retrieves information about one or more stored procedures.

pub.db:getProcs Retrieves the names of stored procedures for the specified database.

pub.db:getTableInfo Retrieves information about columns in the specified table.

pub.db:getTables Retrieves the names of tables in the specified database and schema.

pub.db:insert Inserts one or more rows into the specified table.

pub.db:query Retrieves all rows from the specified table that meet the given criteria.

pub.db:rollback Discards changes to a database.

pub.db:startTransaction Begins a transaction on a database connection.

pub.db:update Updates all rows in the specified table that meet the given criteria. The rows are updated with the supplied new data.

Printing this Guide


pub.db:call

Description Invokes a stored procedure on a target database.

Package WmDB

Input You may specify the connection parameters in one of the following ways:

$dbAlias

–OR–

$dbURL, $dbUser, $dbPass, $dbDriver

–OR–

$dbConnection


$dbAlias String The alias of the database on which you want to execute the stored procedure.

$dbURL String Deprecated. JDBC URL that identifies the database resource.

$dbUser String Deprecated. User name to use to log into the database.

$dbPass String Deprecated. Password for the user.

$dbDriver String Deprecated. Name of the JDBC driver to use.

$dbConnection Object Deprecated. The connection object.

$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to invoke a stored procedure from a database other than the one to which you are connected. If you are not using a distributed database system, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the character location.

$dbSchemaPattern String Optional. Name of the schema to which the stored procedure belongs. If your database supports pattern-matching on schemas, you may specify the schema name with a pattern-matching string, where _ represents a single character and % represents any string of characters. For example, the value of HR% would represent any schema beginning with characters HR. If you are running against DB2, you use this parameter to specify the stored procedures AuthID.

$dbProc String The name of the stored procedure you want to invoke.

$dbProcSig Values [ ] Optional. Record list containing information about the stored procedure you want to invoke.





name String Parameter name defined in the stored procedure.

sqlType String Type of procedure parameter for name as defined in the database. Set to one of the following: BIT TINYINT

SMALLINT INTEGER

BIGINT FLOAT

REAL DOUBLE

NUMBERIC DECIMAL

CHAR VARCHAR

LONGVARCHAR DATE

TIME TIMESTAMP

BINARY VARBINARY

LONGVARBINARY NULL direction String The way the parameter is used by

the stored procedure. Set to one of the following:

in

out

inout

return value

$dbParamsByOrder String Optional. Indicates whether the contents of $data should be sent to the database in order.

Set $dbParamsByOrder to… To…

true Send the contents of $data to the database in the order they are listed in $data.

false Default. Send the contents of $data to the database in no particular order.

$data Values Optional. The parameter values for the stored procedure.


$dbMessage String A message indicating the success or failure of the operation.

Usage Notes The output will also contain output parameters and procedure return values and keyed name (the return value is called RETURN_VALUE).

pub.db:clearTransaction

Description Clears the transactional state within a database connection.

Package WmDB


$dbAlias

Printing this Guide


–OR–

$dbURL, $dbUser, $dbPass, $dbDriver –OR–

$dbConnection


$dbAlias String The alias of the database connection on which you want to clear the transactional state. The alias is passed automatically if the database is connected.








Usage Notes On some databases, exceptional conditions within transactions will automatically abort the entire transaction. When this happens, the standard commit/rollback operations are meaningless because there is no current transaction. If this occurs, use the clearTransaction service to clear the transactional state and prepare for a new transaction. You should only use this service if you have begun a transaction and cannot end it with a standard commit or rollback. The clearTransaction service does not involve a database operation; it is entirely internal to the SAP BC server.

pub.db:close

Description Deprecated. Closes a specified database connection.

Package WmDB


$dbAlias –OR–


$dbConnection


$dbAlias String A database alias.










pub.db:closeAll

Description Deprecated. Closes all database connections that the session has opened.

Package WmDB

Input None.



pub.db:commit

Description Commits changes to a database.

Package WmDB


$dbAlias

–OR–


–OR–

$dbConnection


$dbAlias String The alias of the database on which you want to commit changes. The alias is passed automatically if the database is connected.








Usage Notes This service returns an exception if an error occurs when committing changes to the database. The most common reason for this error is that no transaction has been started (see pub.db.startTransaction).

pub.db:connect

Description Deprecated. Creates a connection to the database using the supplied JDBC URL, user name, and password. You can also specify a JDBC driver specific to the database.

Package WmDB

Printing this Guide


Input You may specify the connection parameters in one of the following ways: $dbAlias –OR– $dbURL, $dbUser, $dbPass, $dbDriver –OR– $dbURL, $dbDriver, $dbProperties


$dbAlias String Optional. A database alias.

$dbURL String Deprecated. Optional. JDBC URL that identifies the database resource.

$dbUser String Deprecated. Optional. User name to use to log into the database.

$dbPass String Deprecated. Optional. Password for the user.

$dbDriver String Deprecated. Optional. Name of the JDBC driver to use.

$dbProperties IData Deprecated. Optional. An IData object that specifies the set of connection parameters that are to be used to make the database connection. Within $dbProperties, key names represent the names of the connection parameters that are to be used to establish the connection, and the value of a key specifies the value of that particular parameter. In most cases, you will include the keys user and password in $dbProperties to specify the user name and password parameters that are to be used to connect to the database. You may include additional parameters as needed. The following example shows how $dbProperties would look if you wanted to set the weblogic.codeset parameter to GBK in order to extract Unicode data out of the database:

Key Value

User dbu

Password dbu

weblogic.codeset GBK


$dbConnection Object The connection object.


Usage Notes Database connections opened by pub.db:connect are associated with the current session. Multiple attempts to connect to the same database by the same client will result in the same connection being reused. This means that if client A and client B request connections to the same database, they each get their own new connection. If client A makes another call to pub.db:connect, the previous connection is reused. Associating the database connection with the client session prevents remote clients from having to repeatedly reconnect to a target database. Connections are not pooled or shared across connections. Unless explicitly closed (by calling pub.db:close or pub.db:closeAll), connections associated with a session are closed when the session is flushed from memory. This happens at a regular interval which can be configured using the Server Administrator. For more information about setting the session timeout limit, see the SAP BC Administration Guide.



pub.db:delete

Description Removes all rows in the specified table that meet the given criteria.

Package WmDB


$dbAlias

–OR–


–OR–

$dbConnection








$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to delete rows from a table that is not in the database to which you are connected. If you are not using a distributed database system or if you want to delete rows from the database to which you are connected, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.

$dbSchemaPattern String Optional. Name of the schema to which the table belongs. If your database supports pattern-matching on schemas, you may specify the schema name with a pattern-matching string, where _ represents a single character and % represents any string of characters. For example, the value HR% would represent any schema beginning with the characters HR. If you are running against DB2, you use this parameter to specify the table’s AuthID.

$dbTable String Name of the table to remove rows from.

$data Values Optional. Values object containing the criteria that the rows to delete must meet.

Important! If no criteria are provided, all rows are deleted from the table.


$updateCount String Number of rows deleted.


Printing this Guide


pub.db:execSQL

Description Executes the specified SQL statement. The service does not perform any parsing on the SQL statement.

Package WmDB


$dbAlias –OR–


$dbConnection



$dbURL String Deprecated. JDBC URL that identifies the database Deprecated. resource.





$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to retrieve information from a database to which you are not currently connected. If you are not using a distributed database system, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.


$dbSQL String SQL statement to execute. $dbProcessEsc String Optional. A String that specifies whether JDBC SQL

escapes will be processed. These escapes allow database-independent access to database-dependent functionality. For example, different dialects of SQL have different syntax for date literals. Using a JDBC escape, you can encode a date literal in a SQL string that should work on any database. Documentation on JDBC SQL escapes is widely available

Set to.. To …



true Process JDBC SQL escapes false Skip processing JDBC SQL escapes

Default is true.

$dbProcessReporterTokens String Optional. A String that specifies whether reporter tokens (e.g., %value xxx%) will be processed in the SQL. Including these tokens in your SQL allows dynamic construction of complex SQL statements, at the possible expense of some execution speed.

Set to.. To… true Process tokens. false Ignore tokens.

Default is false.

$dbParamValues Object[] Optional. If the ‘?’ parameters in the SQL statement are not supplied indirectly (with the $dbParamNames parameter), they can be supplied directly via this parameter. See Usage Notes, below.

$dbParamNames String [ ] Optional. A String [ ] that specifies the names of any ‘?’ parameters in the SQL (they must also be supplied). See Usage Notes, below.

$dbParamTypes String [ ] Optional. A String [ ] that specifies the SQL type names for each parameter. Use the type names from the JDBC 1.2 specification ( “INTEGER”, “VARCHAR”, etc.).


$dbMessage String Optional. A message indicating the success or failure of the operation.

sql String Optional. The SQL as it was actually passed to the target database. This can be helpful in debugging calls to this service when dynamic SQL is used (i.e., you are using either JDBC SQL escapes or webMethods Reporter tokens in your SQL).

paramsAsStrings String [ ] Optional. This is a String [ ] containing the values used for each of the parameters in the SQL statement. This can be helpful in debugging calls to this service when ‘?’ parameters are being used.

$rowCount String Optional. Number of rows in results.

results com.wm.util.Table

Optional. An instance of com.wm.util.Table that contains the results of the SQL statement.

$updateCount String Optional. Number of rows updated.

Printing this Guide


Usage Notes This service does not support updates from a Web browser or HTML form.

SQL supports host variables ('?') in statements to be executed. Because the pipeline is based on named values and individual host variables are not named, $dbParamNames and $dbParamTypes are used to supply an index-to-name mapping for each SQL statement executed. Example Consider the following SQL query: SELECT * FROM royalties WHERE pub_id = ? and roy_amt > ?

To execute this SQL query, you could supply the following values to the pub.dbase:execSQL service:

Variable Name Value Comment

$dbSQL SELECT * FROM royalties

WHERE pub_id = ? and

roy_amt > ?

SQL query to execute.

$dbParamNames pub_id, roy_amt Pipeline items to use for the host variables.

$dbParamTypes VARCHAR, INTEGER SQL types for the host variables.

pub_id

roy_amt

P1053

10

Values for the host variables

Note: Even if there is only one host variable in the SQL statement, both $dbParamNames and $dbParamTypes are String arrays.

Example Consider the following SQL query, which contains an INSERT with three host variables: INSERT INTO books VALUES (?, ?, ?)

Variable Name Value

$dbSQL INSERT INTO books VALUES (?, ?, ?)

$dbParamNames book_id, pub_id, book_title

$dbParamTypes varchar, varchar, varchar

book_id

pub_id

book_title

B234

P1053

The Importance of Being Earnest

Note: The SQL type names used in the examples are defined in the java.sql.Types and SQL92. Even if you used an Oracle database, which calls long string types “VARCHAR2,” you would call them VARCHAR. The standard names from SQL92 will be mapped into database-specific type names.

pub.db:getProcInfo

Description Retrieves information about one or more stored procedures.

Package WmDB


$dbAlias –OR–


$dbConnection










$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to retrieve information about a stored procedure that is not in the database to which you are currently connected. If you are not using a distributed database system, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.


$dbProc String The name of the procedure about which you want information.

Output An IData object (Values object) containing a set of variables whose keys represent items in the stored procedure’s signature. Each element is an IData object containing additional information about that signature item. For specific information about what this service will return for your database, see java.sql.DatabaseMetaData.getProcedureColumns in your JDBC documentation.

pub.db:getProcs

Description Retrieves the names of stored procedures for the specified database.

Package WmDB


$dbAlias

–OR–


–OR–

$dbConnection

Printing this Guide









$dbCatalog String Optional. The name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to retrieve a list of stored procedures from a database other than the one to which you are connected. If you are not using a distributed database system, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.

$dbSchemaPattern String Optional. The name of the schema to which the stored procedures belong. If your database supports pattern-matching on schemas, you may specify the schema name with a pattern-matching string, where _ represents a single character and % represents any string of characters. For example, the value HR% would represent any schema beginning with the characters HR. If you are running against DB2, you use this parameter to specify the stored procedure’s AuthID.

$dbProcNamePattern String Optional. A pattern-matching string that specifies the procedures that you want included in the returned list, where _ represents a single character and % represents any string of characters. For example, the value DATE% would represent any procedure beginning with the characters DATE.

Output An IData object containing a set of variables whose keys represent the names of stored procedures matching the input criteria. Each element in the IData object is itself a IData object that contains information about the stored procedure. For specific information about what information is supplied by your database, see java.sql.DatabaseMetaData.getProcedures in your JDBC documentation.

pub.db:getTableInfo

Description Retrieves information about columns in the specified table.

Package WmDB


$dbAlias

–OR–




–OR–

$dbConnection








$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want information about a table that is not in the database to which you are connected. If you are not using a distributed database system or you want information about a table in the database to which you are connected, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.

$dbSchemaPattern String Optional. Name of the schema to which the table belongs. If your database supports pattern-matching on schemas, you may specify a pattern-matching string for the schema name, where _ represents a single character and % represents any string of characters. For example, the value HR% would represent any schema beginning with the characters HR. If you are running against DB2, you use this parameter to specify the table’s AuthID.

$dbTable String Name of table to query.

$dbColumnNamePattern String Optional. Pattern-matching string that specifies the column names about which you want information, where _ represents a single character and % represents any string of characters. For example, the value ADDR% would represent any column name beginning with the characters ADDR.

Output An IData object with variable names that are the column names of the table. Each element in the output is an IData object that contains information for each column.

$dbTableInfoFound « true » if table was found in database, else « false »

Usage Notes This service will accept input from a Web browser or HTML form.

Printing this Guide


pub.db:getTables

Description Retrieves the names of tables in the specified database and schema.

Package WmDB


$dbAlias –OR–


$dbConnection








$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want information from a database that is not the one to which you are connected. If you are not using a distributed database system or you want information about the database to which you are connected, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.

$dbSchemaPattern String Optional. Name of the schema for which you want the names of tables. If your database supports pattern-matching on schemas, you may specify a pattern-matching string for the schema name, where _ represents a single character and % represents any string of characters. For example, the value HR% would represent any schema beginning with the characters HR. If you want the table names from all schemas, set $dbSchemaPattern to null. If you are running against DB2, you use this parameter to specify the table’s AuthID.

$dbTableNamePattern String Optional. Pattern string describing the tables whose names you want to retrieve. If your database supports pattern-matching on schemas, you may specify a pattern-matching string, where _ represents a single character and % represents any string of characters. For example, the value HR% would



Variable Name Type Description represent any table name beginning with the characters HR. If you want all table names, set $dbTableNamePattern to null.

$dbTableTypeList String [ ] Optional. A String [ ] specifying the types of tables whose names you want to retrieve. Common JDBC table types include: TABLE, VIEW, SYSTEM TABLE, ALIAS, and SYNONYM. Check your driver documentation for others.

Output An IData object with variable names that are the table names in the database. Each element in the output is an IData object that contains information for each table.


pub.db:insert

Description Inserts one or more rows into the specified table.

Package WmDB


$dbAlias

–OR–


–OR–

$dbConnection








$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to insert rows into a table that is not in the database to which you are connected. If you are not using a distributed database system or if you want to insert rows into the database to which you are connected, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.

$dbSchemaPattern String Optional. Name of the schema to which the table belongs. If your database supports pattern-matching on schemas, you may specify the schema name with a pattern-

Printing this Guide


Variable Name Type Description matching string, where _ represents a single character and % represents any string of characters. For example, the value HR% would represent any schema beginning with the characters HR. If you are running against DB2, you use this parameter to specify the table’s AuthID.

$dbTable String Name of table into which you want to insert rows. $dbRollbackOnFail String Optional. A String that determine whether changes are

committed if a failure occurs while processing multiple inserts.

Set to.. To…

true Undo changes on failure.

false Commit changes on failure. $data Values [ ] Optional. Values object containing the data to insert. This

object can be of the type Values or Values [ ].


$updateCount String String specifying the number of rows the service inserted.

$failCount String String specifying the number of rows the service failed to insert.

$errors IData [ ] An IData array object containing any error messages.



pub.db:query

Description Retrieves all rows from the specified table that meet the given criteria.

Package WmDB


$dbAlias

–OR–


–OR–

$dbConnection











$dbCatalog String Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to query a table that is not in the database to which you are connected. If you are not using a distributed database system or if you want to query a table in the database to which you are connected, you do not need to specify this parameter. If you are running against DB2, use this parameter to specify the database location.


$dbTable String Name of table to query.

$data Values Optional. Values object with criteria that the rows to retrieve must meet.


results com.wm.util.Table

An instance of com.wm.util.Table that contains the results of the query.

$dbMessage String A message indicating the success or failure of an operation.

$rowCount String Number of rows for the table that meet the criteria specified in $data.


pub.db:rollback

Description Discards changes to a database.

Package WmDB


$dbAlias

–OR–


–OR–

$dbConnection


Printing this Guide



$dbAlias String Alias of the database for which you want to discard changes. This information is passed automatically.








Usage Notes This service returns an exception if there an error occurs when discarding changes to the database. The most common reason for this error is that no transaction has been started (see startTransaction).

pub.db:startTransaction

Description Begins a transaction on a database connection.

Package WmDB


$dbAlias

–OR–


–OR–

$dbConnection


$dbAlias String Alias of the database for which you want to start the transaction. This information is passed automatically.








Usage Notes By default, all database connections are opened in “auto commit” mode, meaning the results of a operation are automatically committed to the database when that operation succeeds. To use a connection in a transactional context, you must first call pub.db:startTransaction to take that connection out of “auto commit” mode. This service returns an exception if an error occurs when starting the new transaction. Common reasons for an error when starting a new transaction are:



A transaction is already in progress (see pub.db:commit, pub.db:rollback or pub.db:clearTransaction) The target database does not support transactions After a transaction has been started, it must be terminated with a call to either pub.db:commit (to save all changes to the database) or pub.db:rollback (to discard changes).

pub.db:update

Description Updates all rows in a table that meet the given criteria. Rows are updated with the supplied new data.

Package WmDB

Input You may specify the connection parameters in one of the following ways: $dbAlias

–OR–


–OR–

$dbConnection








$dbCatalog String Optional. Name of the database’s system catalog. Include this parameter if your DBMS supports distributed databases and you want to update rows in a table that is not in the database to which you are connected. If you are not using a distributed database system or if you want to update rows in the database to which you are connected, you do not need to specify this parameter. If you are running against DB2, you use this parameter to specify the database location.


$dbTable String Name of table to update.

$criteria Values [ ] Values object with criteria that the rows to update must meet.

Important! If no criteria are provided, all rows are updated.

$set Values [ ] Values object containing the new data to update rows with.

Printing this Guide



$updateCount String Number of rows updated.


Printing this Guide


Chapter 6 Date Services

You use date services to generate and format date values.

6

C H A P T E R 6 D a t e S e r v i c e s




Service Function pub.date:currentDate Returns the current date in a specified format.

pub.date:dateBuild Builds a date/time string using the specified pattern and the specified date elements.

pub.date:dateTimeBuild Builds a date/time string using the specified pattern and the specified date elements.

pub.date:dateTimeFormat Converts a date/time string from one format to another.

Pattern String Symbols Many of the date services require you to specify pattern strings describing the data’s current format and/or the format to which you want it converted. For services that require a pattern string, use the symbols in the following table to describe the format of your data. For example, to describe the format of a date in January 15, 1999 format, you would use the pattern string MMMMM dd, yyyy. To describe the format of a date in 01/15/99 format, you would use the pattern string MM/dd/yy.

Symbol Meaning Presentation Example G era designator Text AD

y year Number 1996

M month in year Text & Number July & 07

d day in month Number 10

h hour in am/pm (1-12) Number 12

H hour in day (0-23) Number 0

m minute in hour Number 30

s second in minute Number 55

S millisecond Number 978

E day in week Text Tuesday

D day in year Number 189

F day of week in month Number 2 (2nd Wed in July)

w week in year Number 27

W week in month Number 2

a am/pm marker Text PM

k hour in day (1-24) Number 24

K hour in am/pm (0-11) Number 0

z time zone Text Pacific Standard Time or PST

' escape for text Delimiter

' ' single quote Literal '

Printing this Guide


Time Zones When working with date services, you can specify time zones. The Earth is divided into 24 standard time zones—one for every 15° of longitude. Using the time zone including Greenwich, England as the starting point, the time is increased by an hour for each time zone east of Greenwich and decreases by an hour for each time zone west of Greenwich. The time difference between a time zone and the time zone including Greenwich, England (GMT) is referred to as the raw offset.

The following table identifies the different time zones for the Earth and the raw offset for each zone from Greenwich, England.

The effects of daily savings time are ignored in the following table.

ID Raw Offset Name

MIT -11 Midway Islands Time

HST -10 Hawaii Standard Time

AST -9 Alaska Standard Time

PST -8 Pacific Standard Time

PNT -7 Phoenix Standard Time

MST -7 Mountain Standard Time

CST -6 Central Standard Time

EST -5 Eastern Standard Time

IET -5 Indiana Eastern Standard Time

PRT -4 Puerto Rico and U.S. Virgin Islands Time

CNT -3.5 Canada Newfoundland Time

AGT -3 Argentina Standard Time

BET -3 Brazil Eastern Time

CAT +2 Central Africa Time

GMT 0 Greenwich Mean Time

ECT +1 European Central Time

EET +2 Eastern European Time

ART +2 (Arabic) Egypt Standard Time

EAT +3 Eastern African Time

MET +3.5 Middle East Time

NET +4 Near East Time



ID Raw Offset Name

PLT +5 Pakistan Lahore Time

IST +5.5 India Standard Time

BST +6 Bangladesh Standard Time

VST +7 Vietnam Standard Time

CTT +8 China Taiwan Time

JST +9 Japan Standard Time

ACT +9.5 Australian Central Time

AET +10 Australian Eastern Time

SST +11 Solomon Standard Time

NST +12 New Zealand Standard Time

Notes on Invalid Dates If you use an invalid date with a date service, the date service automatically translates the date to a legal date. For example, if you specify “1999/02/30” as input, the date service interprets the date as “1999/03/02” (two days after 2/28/1999).

If you use “00” for the month or day, the date service interprets “00” as the last month or day in the Gregorian calendar. For example, if you specify “00” for the month, the date service interprets it as 12.

If the pattern YY is used for the year, the date service uses a 50 year moving window to interpret the value of YY. The date service establishes the window by subtracting 49 years from the current year and adding 50 years to the current year. For example, if you are running the SAP BC server in the year 2000, the moving window would be from 1951 to 2050. The date service interprets 2-digit years as falling into this window (e.g., 12 would be 2012, 95 would be 1995).

Printing this Guide


pub.date:currentDate

Description Returns the current date in a specified format.

Package WmPublic


pattern String A pattern string representing the format in which you want the date returned. See “Pattern String Symbols” on page 78.

timeZone String Optional. String representation of a time zone

locale String Optional. String containing the locale to use for formatting.


value String The current date in the format of pattern.

pub.date:dateBuild

Description Builds a date/time string using the specified pattern and the specified date elements.

Package WmPublic


pattern String A pattern string representing the format in which you want the date returned. See “Pattern String Symbols” on page 78.

year String String representation of an integer year, yyyy or yy.

month String String representation of an integer month. month value is 1-based, e.g., “1” for January.

dayofmonth String String representation of an integer day of month. dayofmonth value is 1-based.




value String A string that represents the date specified by year, month, and dayofmonth, in the format of pattern.

Note: The value of year is not modified; year is only displayed in the format defined in pattern.

Usage Notes If pattern is null, dateBuild returns null. If pattern contains a time zone, the time zone of the SAP BC server is used. If a date element is null or invalid, dateBuild uses the element value at the time the service is invoked.



pub.date:dateTimeBuild

Description Builds a date/time string using the specified pattern and the specified date elements.

Package WmPublic


pattern String A pattern string representing the format in which you want the time returned. See “Pattern String Symbols” on page 78.

year String Optional. String representation of an integer year, yyyy or yy.

month String Optional. String representation of an integer month. The month value is 1-based, e.g., “1” for January.

dayofmonth String Optional. String representation of an integer day of month. dayofmonth value is 1-based.

hour String Optional. String representation of the hour, based on a 24-hour clock.

minute String Optional. String representation of the minute.

second String Optional. String representation of the second.

millis String Optional. String representation of the milliseconds.




value String A string that represents the date specified by the date and time elements in the format of pattern.

Note: The value of year is not modified; year is only displayed in the format defined in pattern.

Usage Notes If pattern is null, dateTimeBuild returns null. If pattern contains a time zone, the time zone of the SAP BC server is used. If a date element is null or invalid, dateTimeBuild uses the element value at the time the service is invoked. If a time element is null or invalid, dateTimeBuild uses “0”.

pub.date:dateTimeFormat

Description Converts a date/time string from one format to another.

Package WmPublic


inString String String containing a date or time.

Important! If inString contains a character in the last position, that character is interpreted as 0. This can result in an inaccurate date. For information about invalid dates, see page 79.

currentPattern String Current format of inString, using time formatting syntax. See “Pattern String Symbols” on page 78.

Printing this Guide



newPattern String Desired format for inString, using time formatting syntax. See “Pattern String Symbols” on page 78.



value String A string representing the date/time given by inString, in the format of newPattern.

Usage Notes If currentPattern does not contain a time zone, the value is assumed to be in the time zone of the SAP BC server. If newPattern contains a time zone, the time zone of the SAP BC server is used.


Chapter 7 Event Services

Use the event services and specifications to write your own event handler services. SAP BC provides the pub.event:audit:logToFile and pub.event.excepton:logToFile services as samples of audit and exception events and for backward compatibility with earlier versions of the SAP BC server.

7

C H A P T E R 7 E v e n t S e r v i c e s




Service Function pub.event:addSubscriber Creates a subscription for a specified event.

pub.event:alarm Specification for alarm event handlers.

pub.event:alarmInfo Record for alarm event information.

pub.event:audit Specification for audit event handlers.

pub.event:auditInfo Record for audit-event information.

pub.event.audit:logToFile Logs Audit Events to the wmServer\logs\audit.log file.

pub.event:callStackItem Record for the name of the service in the invocation path when an exception occurred.

pub.event:deleteSubscriber Removes an event handler from the subscription list for a specified event.

pub.event:exception Specification for exception event handlers.

pub.event:exceptionInfo Record for exception information.

pub.event.exception:logToFile Logs exception events to the wmServer\error.log..

pub.event:getEventTypes Returns the list of supported event types.

pub.event:getSubscribers Returns the list of subscribers for a specified event type.

pub.event:gdEnd Specification for gdEnd event handlers.

pub.event:gdEndInfo Record for gdEnd event information.

pub.event:gdStart Specification for gdStart event handlers.

pub.event:gdStartInfo Record for gdStart event information.

pub.event:modifySubscriber Modifies the information about a subscription.

pub.event:portStatus pub.event:portStatus

pub.event:portStatusInfo Record for port event information.

pub.event:reloadEventManagerSettings Reloads the settings from the event manager’s configuration file (eventcfg.bin) on the server.

pub.event:replication Specification for replication event handlers.

pub.event:replicationInfo Record for replication event information.

pub.event:saveEventManagerSettings Saves the current subscriber information to the event manager’s configuration file (eventcfg.bin) on the server.

pub.event:sessionEnd Specification for sessionEnd event handlers.

pub.event:sessionEndInfo Record for sessionEnd event information

pub.event.sessionExpire:logToFile For internal use only.

pub.event:sessionExpire Specification for sessionExpire event handlers.

pub.event:sessionExpireInfo Record for sessionExpire event information.

pub.event.sessionExpire:logToFile For internal use only.

Printing this Guide


pub.event:sessionStart Specification for sessionStart event handlers.

pub.event:sessionStartInfo Record for sessionStart event information.

pub.event.sessionStart:logToFile For internal use only.

pub.event:stat Specification for stat event handlers.

pub.event:statInfo Record for stat event information.

pub.event.stats:logToFile For internal use only.

pub.event:txEnd Specification for txEnd event handlers.

pub.event:txEndInfo Record for txEnd event information.

pub.event:txStart Specification for txStart event handlers.

pub.event:txStartInfo Record for txStart event information.



pub.event:addSubscriber

Description Creates a subscription for a specified event. Important! Subscriptions that you add using this service take effect immediately, however they are not made permanent unless you also persist them to disk with the pub.event:saveEventManagerSettings service. If you do not run saveEventManagerSettings after adding subscribers, your changes will be lost when the server is restarted.

Package WmPublic


EventType String A String specifying the type of event to which the event handler is subscribing. Must be one of the following:

Alarm Event

Audit Event

Exception Event

GD End Event

GD Start Event

Port Status Event

Replication Event

Session End Event

Session Expire Event

Session Start Event

Stat Event

Tx End Event

Tx Start Event

Tip! To view the current list of event types, you can execute the pub.event:getEventTypes service in Developer.

Filter String A String that selects (filters) the set of events within EventType to which the event handler is subscribing. addSubscriber uses Filter as a pattern string to filter a particular attribute of an event. The pattern string can be composed of literal characters, which match a character exactly, and/or the * character, which matches any sequence of characters. For example:

This Pattern String... Would Match...

* Any string M* Any string that starts with an upper-case

“M.” M*X Any string that starts with an upper-case

“M” and ends with an upper-case ‘X.”

The following table shows the attribute that is filtered for each event type. Note that some event types cannot be filtered.

EventType Filtered attribute Alarm Event The message generated by the alarm event.

Printing this Guide


EventType Filtered attribute Audit Event The fully qualified name of the service that

generates the audit event. Exception Event The fully qualified name of the service that

generates the exception event. GD End Event This event type cannot be filtered. Filter is

ignored for this event type. GD Start Event The fully qualified name of the service that

generates the GD Start Event. Port Status Event This event type cannot be filtered. Filter is

ignored for this event type. Replication Event The name of the package being replicated. Session End Event This event type cannot be filtered. Filter is

ignored for this event type. Session Expire

Event

This event type cannot be filtered. Filter is ignored for this event type.

Session Start

Event

The user ID of the user starting the session or the groups to which the user belongs. (The filter is applied to a space delimited list of groups, composed of groups names suffixed with the user’s user ID.) Examples The following examples show how you might filter session start events for various groups and/or user IDs: To select session starts for any user in the Administrators group, the filter would be:

*Administrators*

To select session starts for the user ID “LRMalley” in the Administrators group, the filter would be:

*Administrators*LRMalley

To select session starts for the user ID “LRMalley” in any group, the filter would be:

*LRMalley Stat Event This event type cannot be filtered. Filter is

ignored for this event type. Tx End Event This event type cannot be filtered. Filter is

ignored for this event type. Tx Start Event This event type cannot be filtered. Filter is

ignored for this event type.

Service String The fully qualified name of the event-handler service. (The service that will execute when the event specified by EventType and Filter occurs.)



Comment String Optional. A String specifying a descriptive comment for this subscription. This comment will be displayed when subscriptions are viewed in Developer.

Enabled String Optional. A String specifying the status of the subscription. Must be one of the following values:

Set to… To…

true Make the subscription active. false Default. Make the subscription inactive.

Note: Although the default value is false, you will generally want to set Enabled to true to activate the subscription immediately when it is added.

Output None.

See Also pub.event:deleteSubscriber pub.event:modifySubscriber pub.event:getSubscribers pub.event:saveEventManagerSettings

pub.event:alarm

Description Specification for alarm event handlers.

Package WmPublic


time String The date and time that the event occurred. Given in the format yyyy/MM/dd HH:mm:ss.SS.

service String Fully qualified name of the service that generated the event.

sessionID String Session ID of the service firing the alarm.

msg String Text describing the alarm.

Output None.

Usage Notes Remember to register your handler with the Event Manager.

pub.event:alarmInfo

Description Record for alarm event information.

Package WmPublic




service String Fully-qualified name of the service that generated the event.

msg String Text describing the alarm.

Printing this Guide


pub.event:audit

Description Specification for audit event handlers.

Package WmPublic



TID String The transaction ID of the service that generated the event.


sessionID String Session ID of the service that generated the event.

result String The description of the audit point (‘begin’, ‘ok’, ‘error’, …)

pipeline Record Optional. An IData object that contains the state of the pipeline at the audit point.

userName String The name of the user that invoked the service that generated the event.

Usage Notes Not all audit handlers that you code will log information.

pub.event:auditInfo

Description Record for audit-event information.

Package WmPublic






result String The description of the audit point (‘begin’, ‘ok’, ‘error’, …)

pipeline IData Optional. The state of the pipeline at the audit point.

userName String The name of the user that invoked the service that generated the event.

pub.event.audit:logToFile

Description Logs Audit Events to the wmServer\logs\audit.log file.

Package WmPublic



TID String The Transaction ID of the service that generated the event.






result String The description of the audit point (‘begin’, ‘ok’, ‘error’, …).

pipeline IData Optional. The state of the pipeline at the audit point.

userName String The user ID that invoked the service that generated the event.

Output None.

Usage Notes When writing your own audit handler, be careful to not modify the pipeline variable within your handler.

pub.event:callStackItem

Description Record for the name of the service in the invocation path when an exception occurred.

Package WmPublic


service String The fully qualified name of the last service (i.e., most recently called) on the call stack.

pub.event:deleteSubscriber

Description Removes an event handler from the subscription list for a specified event. Important! Deletions made using this service take effect immediately, however they are not made permanent unless you persist them to disk with the pub.event:saveEventManagerSettings service. If you do not run saveEventManagerSettings after deleting subscribers, your changes will be lost when the server is restarted.

Package WmPublic


EventType String A String specifying the type of event from which the event handler is unsubscribing. Must be one of the following values:

Alarm Event

Audit Event

Exception Event

GD End Event

GD Start Event

Port Status Event

Replication Event

Session End Event


Session Start Event

Stat Event

Tx End Event

Tx Start Event


gID String A String specifying the ID of the subscriber that you want to delete. To get a list of subscriber IDs, execute the pub.event:getSubscribers service.

Printing this Guide



Result String A String indicating whether the subscriber was successfully deleted.

Result will be… If…

true Subscriber was deleted successfully. false Subscriber was not deleted (typically because an

invalid subscriber ID was provided in gID).

See Also pub.event:addSubscriber pub.event:modifySubscriber pub.event:getSubscribers pub.event:saveEventManagerSettings

pub.event:exception

Description Specification for exception event handlers.

Package WmPublic



error String Error message of the exception.

localilzedError String Localized error message.

errorType String Exception type that was thrown.

errorDump String More detailed information about the exception.

Service String The fully qualified name of the service that generated the event.

User String The user that requested the service that generated the event.

callStack Record List A reference to a list of Idata objects (callstackItem) containing information about the service, pipeline, and current path of the flow operation when the exception occurred. This Record list has the same structure and variables as the pub.event:callStackItem Record.

Pipeline Record An Idata object containing the state of the pipeline at the time the exception occurred.

threadID String The thread ID identifying the thread that invoked the service.

Ssnid String The session ID during which the exception occurred.

Usage Notes Not all exception handlers that you code will log information.

pub.event:exceptionInfo

Description Record for exception information.

Package WmPublic







localizedError String Localized error message.



Service String The fully qualified name of the service that generated the event.

User String The user that requested the service that generated the event.

callStack Record List A reference to a Record List (callstackItem) containing information about the service, pipeline, and current path of the flow operation when the exception occurred. This Record List has the same structure and variables as the pub.event:callStackItem record.

Pipeline Idata The state of the pipeline at the time the exception occurred.


Ssnid String The session ID during which the exception occurred.

pub.event.exception:logToFile

Description Logs exception events to the wmServer\error.log.. This service will also send an e-mail notice if your SMTP settings are configured properly.

Package WmPublic




errorType String Localized error message.



service String The fully qualified name of the service that generated the event.

user String The user that requested the service that generated the event.

callStack IData [ ] A reference to a record list (callstackItem) containing a stack of the called services that were interrupted by the exception.

Variable Name Type Description service String The name of the service.

pipeline IData The state of the pipeline at the time the exception occurred.


ssnid String The session ID during which the exception occurred.

Output None.

pub.event:gdEnd

Description Specification for gdEnd event handlers.

Package WmPublic

Printing this Guide




TID String The Transaction ID of the service that generated the event.

result String Status of the transaction.

Output None.


pub.event:gdEndInfo

Description Record for gdEnd event information.

Package WmPublic





pub.event:gdStart

Description Specification for gdStart event handlers.

Package WmPublic




svcname String Fully qualified name of the service that generated the event.


Output None.


pub.event:gdStartInfo

Description Record for gdStart event information.

Package WmPublic




svcname String Fully qualified name of the service that generated the event.




pub.event:getEventTypes

Description Returns the list of supported event types.

Package WmPublic

Input None.


EventType IData An IData object whose keys represent the names of the event types that the server supports. The value of each key is a description of the event type.

See Also pub.event:getSubscribers

pub.event:getSubscribers

Description Returns the list of subscribers for a specified event type.

Package WmPublic


EventType String A String specifying the type of event for which you want the list of subscribers. Must be one of the following values:

Alarm Event

Audit Event

Exception Event

GD End Event

GD Start Event

Port Status Event

Replication Event

Session End Event


Session Start Event

Stat Event

Tx End Event

Tx Start Event



Subscribers Record A Record (an IData object) that contains one Record (IData object) for each subscriber. The key for each Record is the subscriber ID. Each Record contains the following information about the subscriber:

Key Description

Service A String indicating the fully qualified name of the event-handler service (i.e., the service that subscribes to the event in EventType.)

Filter A String representing the filter associated with the subscription. This is a pattern string that selects (filters) an event based on a particular

Printing this Guide


Output Variable Name Type Description attribute. Filter is composed of literal characters and/or the * character, which matches any sequence of characters. For example:

This string.. Matches...

* Any string M* Any string that starts with an

upper-case “M.” M*X Any string that starts with an

upper-case “M” and ends with an upper-case “X.”

For a list of attributes to which the filter is applied, see “pub.event:addSubscriber” on page 88.

Comment A String containing the descriptive comment associated with the description.

gID A String containing the subscriber ID

Enabled A String indicating the status of the subscription. Will be one of the following values:

Value Description

true Subscription is active. false Subscription is inactive.

See Also pub.event:addSubscriber pub.event:modifySubscriber pub.event:deleteSubscriber

pub.event:modifySubscriber

Description Modifies the information about a subscription. Important! The changes you make with this service take effect immediately, however they are not made permanent unless you also persist them to disk with the pub.event:saveEventManagerSettings service. If you do not run saveEventManagerSettings after modifying subscribers, your changes will be lost when the server is restarted.

Package WmPublic


EventType String A String specifying the event type that you want the subscription to have:

Alarm Event

Audit Event

Exception Event

GD End Event

GD Start Event

Port Status Event

Replication Event

Session End Event



Input Variable Name Type Description Session Expire Event

Session Start Event

Stat Event

Tx End Event

Tx Start Event


gID String A String specifying the ID of the subscriber that you want to modify. To get the current list of subscriber IDs, execute the pub.event:getSubscribers service.

Filter String A String specifying the filter you want the subscription to have. Filter is a pattern-matching string that can include literal characters and/or the ‘*’ character to match any string of characters.

This Pattern String... Would Match...

* Any string M* Any string that starts with an upper-case

“M.” M*X Any string that starts with an upper-case “M”

and ends with an upper-case “X.”

The following table shows the attribute that is filtered for each event type. Note that some event types cannot be filtered.

EventType Filtered attribute Alarm Event The message generated by the alarm event. Audit Event The fully qualified name of the service that

generates the audit event. Exception Event The fully qualified name of the service that

generates the exception event. GD End Event This event type cannot be filtered. Filter is

ignored for this event type. GD Start Event The fully qualified name of the service that

generates the GD Start Event. Port Status Event This event type cannot be filtered. Filter is

ignored for this event type. Replication Event The name of the package being replicated. Session End Event This event type cannot be filtered. Filter is

ignored for this event type. Session Expire

Event

This event type cannot be filtered. Filter is ignored for this event type.

Printing this Guide


EventType Filtered attribute

Session Start

Event

The user ID of the user starting the session or the groups to which the user belongs. (The filter is applied to a space delimited list of groups, composed of groups names suffixed with the user’s user ID.) Examples The following examples show how you might filter session-start events for vaious groups and/or user IDs: To select session starts for any user in the Administrators group, the filter would be:

*Administrators*

To select session starts for the user ID “LRMalley” in the Administrators group, the filter would be:

*Administrators*LRMalley

To select session starts for the user ID “LRMalley” in any group, the filter would be:

*LRMalley Stat Event This event type cannot be filtered. Filter is

ignored for this event type. Tx End Event This event type cannot be filtered. Filter is

ignored for this event type. Tx Start Event This event type cannot be filtered. Filter is

ignored for this event type.

Service String The fully qualified name of the event-handler service that you want the subscription to specify.

Comment String Optional. A String specifying a descriptive comment that you want to assign to the subscription.

Enabled String Optional. A String specifying the status of the subscription. Must be one of the following values:

St to… To…

true Make the subscription active. false Default. Make the subscription inactive.

Note: Although the default value is false, you will generally want to set Enabled to true to activate the subscription immediately after it is modified.


Result String A String indicating whether the subscriber was successfully deleted.

Result will be… If…

true Subscriber was updated successfully. false Subscriber was not updated (typically because an

invalid subscriber ID was provided in gID).



See Also pub.event:addSubscriber pub.event:deleteSubscriber pub.event:getSubscribers pub.event:saveEventManagerSettings

pub.event:portStatus

Description Specification for a port status event.

Package WmPublic


portStatusInfo Record List A Record List (an IData [ ]) containing the following information.


time String The date and time that the event occurred, in the format yyyy/MM/dd HH:mm:ss.SS.

port String The number for the port.

status String The status of the port.

protocol String The type of port (e.g., http, https, ftp, or e-mail)..

primary String The primary port. By default, the SAP BC server designates an HTTP port at port 5555 as the primary port.

enabled String A String indicating whether or not the port is enabled. The value will be one of the following:

Value Description true The port is enabled. false The port is disabled.

Output None.


pub.event:portStatusInfo

Description Record for port event information.

Package WmPublic


time String The date and time that the event occurred, in the format yyyy/MM/dd HH:mm:ss.SS.

port String The number for the port.

status String The status of the port.

protocol String The type of port (e.g., http, https, ftp, or e-mail).

primary String The primary port. By default, the SAP BC server designates an HTTP port at port 5555 as the primary port.

Printing this Guide



enabled String A String indicating whether or not the port is enabled. The value will be one of the following:

Value Description

true The port is enabled. false The port is disabled.

Output None.


pub.event:reloadEventManagerSettings

Description Reloads the settings from the event manager’s configuration file (eventcfg.bin) on the server.

Package WmPublic

Input None.

Output None.

See Also pub.event:saveEventManagerSettings



pub.event:replication

Description Specification for replication event handlers.

Package WmPublic



action String Description of the event.

package String Name of package being replicated.


Output None.


pub.event:replicationInfo

Description Record for replication event information.

Package WmPublic



action String Description of the event.

package String Name of package being replicated.


pub.event:saveEventManagerSettings

Description Saves the current subscriber information to the event manager’s configuration file (eventcfg.bin) on the server. Important! Always run this service after making any permanent changes to subscriber information (e.g., add subscribers, modify subscribers, or delete subscribers), otherwise your changes will be lost the next time the server is restarted.

Package WmPublic

Input None.

Output None.

See Also pub.event:addSubscriber pub.event:deleteSubscriber pub.event:modifySubscriber pub.event:reloadEventManagerSettings

pub.event:sessionEnd

Description Specification for sessionEnd event handlers.

Printing this Guide


Package WmPublic




rpcs String Number of service calls the session has performed.

age String Number of milliseconds the session has existed.

Output None.


pub.event.sessionEnd:logToFile

For internal use only.

pub.event:sessionEndInfo

Description Record for sessionEnd event information.

Package WmPublic






pub.event:sessionExpire

Description Specification for sessionExpire event handlers.

Package WmPublic






Output None.


pub.event.sessionExpire:logToFile




pub.event:sessionExpireInfo

Description Record for sessionExpire event information.

Package WmPublic






pub.event:sessionStart

Description Specification for sessionStart event handlers.

Package WmPublic



sessionID String ID of the new session.

userid String The user ID that the SAP BC client or developer used to log on to the SAP BC server.

sessionName String The name of the new session.

Output None.


pub.event.sessionStart:logToFile For internal use only.

Printing this Guide


pub.event:sessionStartInfo

Description Record for sessionStart event information.

Package WmPublic



sessionID String ID of the new session.

userid String The user ID that the SAP BC client or developer used to log on to the SAP BC server.

sessionName String Name of the new session.

pub.event:stat

Description Specification for stat event handlers.

Package WmPublic


startTime String The date and time that the event occurred. Given in the format yyyy/MM/dd HH:mm:ss.SS.

uptime String The amount of time the server has been up. Given in the format yyyy/MM/dd HH:mm:ss.SS.

totalMem String The total amount of used and unused storage available to the JVM (X 1000) ex: 65535 equals about 64 megabytes of storage.

freeMem String The amount of unused storage available to the SAP BC (X 1000) ex: 65535 equals about 64 megabytes of storage.

usedMem String The amount of storage used by the SAP BC (X 1000) ex: 65535 equals about 64 megabytes of storage.

freeMemPer String Percent of total memory unused.

usedMemPer String Percent of total memory used.

svrT String Number of services currently running.

svrTMax String Peak number of servers ever running concurrently.

sysT String Number of JVM threads running.

sysTMax String Peak number of threads ever running.

conn String Number of current sessions.

connMax String Peak number of sessions concurrently.

reqTotal String Cumulative total number of services processed.

reqAvg String Average duration of service.

newReqPM String New requests per minute.

endReqPM String End requests per minute.

errSvc String Number of services completed in error state.




svcRate String Number of end/start(s) per second.

ssnUsed String Number of licensed sessions currently active

ssnPeak String Number of licensed sessions that have ever run concurrently on the server

ssnMax String Maximum number of sessions for which the server is licensed.

errSys String Number of unknown errors.

Output None.


pub.event:statInfo

Description Record for stat event information.

Package WmPublic


startTime String The date and time that the event occurred. Given in the format yyyy/MM/dd HH:mm:ss.SS.

uptime String The amount of time the server has been up. Given in the format yyyy/MM/dd HH:mm:ss.SS.

totalMem String The total amount of used and unused storage available to the JVM (X 1000) ex: 65535 equals about 64 megabytes of storage.

freeMem String The amount of unused storage available to the SAP BC (X 1000) ex: 65535 equals about 64 megabytes of storage.

usedMem String The amount of storage used by the SAP BC (X 1000) ex: 65535 equals about 64 megabytes of storage.

freeMemPer String Percent of total memory unused.

usedMemPer String Percent of total memory used.

svrT String Number of services currently running.

svrTMax String Peak number of servers ever running concurrently.

sysT String Number of JVM threads running.

sysTMax String Peak number of threads ever running.

conn String Number of current sessions.

connMax String Peak number of sessions concurrently.

reqTotal String Cumulative total number of services processed.

reqAvg String Average duration of service.

newReqPM String New requests per minute.

endReqPM String End requests per minute.

errSvc String Number of services completed in error state.

svcRate String Number of end/start(s) per second.

ssnUsed String Number of licensed sessions currently active

Printing this Guide



ssnPeak String Number of licensed sessions that have ever run concurrently on the server

ssnMax String Maximum number of sessions for which the server is licensed.

errSys String Number of unknown errors.

pub.event.stats:logToFile For internal use only.

pub.event:txEnd

Description Specification for txEnd event handlers.

Package WmPublic





Output None.


pub.event:txEndInfo

Description Record for txEnd event information.

Package WmPublic





pub.event:txStart

Description Specification for txStart event handlers.

Package WmPublic





Output None.




pub.event:txStartInfo

Description Record for txStart event information.

Package WmPublic


Time String The date and time that the event occurred. Given in the format yyyy/MM/dd HH:mm:ss.SS.




Chapter 8 File Services

You use file services to perform operations on the local file system.

8

C H A P T E R 8 F i l e S e r v i c e s




Service Function pub.file:getFile Retrieves a specified file from the local file system. After retrieving the document, you

can use other built-in services (for example, pub.web services) to convert the document information to a node if necessary. The getFile service does not parse a document.

pub.file:head Shows start of the given file.

pub.file:tail Shows end of the given file.

Printing this Guide


pub.file:getFile

Description Retrieves a specified file from the local file system. After retrieving the document, you can use other built-in services (for example, pub.web services) to convert the document information to a node if necessary. The getFile service does not parse a document.

Package WmPublic


filename String The location of the document on the local file system. Example c:\rubicon\document.xml

loadAs String Optional. The form in which you want getFile to make the document available to subsequent services.


bytes Default. Pass the document as a byte array. This is the default option. Use this option if the document will be used as input to a service that operates on whole documents (for example, queryDocument).

stream Pass the document as an input stream. Use this option if the document will be used as input to a service that can process a document incrementally (for example, getNodeIterator).

bufferSize String Optional. The buffer size (in bytes) to use if you are loading an input stream (i.e., loadAs=stream). The default is 4096 bytes. Example 1024


body IData The Document object containing the local document in a byte array or an input stream, which can be used as input to a service. If you want to convert it to a node, you can use the pub.web:stringToDocument service.


bytes byte[ ] The Document object in a byte array if you specified bytes for loadAs.

stream InputStream The Document object in an input stream if you specified stream for loadAs.

Usage Notes The getFile service does not parse the document. To parse the retrieved file, use the pub.web:stringToDocument service.

C H A P T E R 8 F i l e S e r v i c e s


pub.file:head

Description Shows start of the given file.

Package WmPublic


filename String File to be read.

showLines String

Optional. Number of lines to be displayed (Default:10).

skipLines String

Optional. Number of lines to be skipped (Default: 0).

encoding String Optional. Encoding that is used to read the bytes of the file.

Output Variable Name Description

lines String[] Lines from the file.

Printing this Guide


pub.file:tail

Description Shows end of the given file.

Package WmPublic


filename String File to be read.

showLines String

Optional. Number of lines to be displayed (Default:10).

skipLines String

Optional. Number of lines to be skipped (Default: 0).

encoding String Optional. Encoding that is used to read the bytes of the file.


lines String[] Lines from the file.


Chapter 9 Flow Services

You use these services to perform debugging and utility-type tasks in a flow service.

9

C H A P T E R 9 F l o w S e r v i c e s




Service Function pub.flow:clearPipeline Removes all fields from the pipeline

pub.flow:debugLog Writes a message to the server log (server\logs\server.log). Each log message contains a line number, function name, and message field.

pub.flow:getLastError Obtains detailed information about the last exception that was trapped within a flow.

pub.flow:getSession Inserts the Session object into the pipeline as a Record named $session.

pub.flow:getTransportInfo Retrieves information about the protocol from which the current flow was invoked.

pub.flow:restorePipeline Restores a pipeline previously saved by pub.flow:savePipeline.

pub.flow:restorePipelineFromFile Retrieves a file of previously saved keys and values and merge or replace the existing pipeline with them.

pub.flow:savePipeline Saves a pipeline into memory, for later retrieval by a call to pub.flow:restorePipeline.

pub.flow:savePipelineToFile Saves the current pipeline contents to a file on the machine running SAP BC server.

pub.flow:setResponse Forces a specific response string to be returned by the SAP BC server to a calling process (such as a browser or application server).

pub.flow:sleep Sends the current service to sleep the given amount of seconds.

pub.flow:sleep

Description Sends the current service to sleep the given amount of seconds.

Package WmPublic


seconds String Optional. Sleep time in seconds (Default: 10)

pub.flow:tracePipeline

Writes the names and values of all fields in the pipeline to the server log (server\logs\server.log).

pub.flow:transportInfo A Record containing the information about the protocol used to invoke a service.

pub.flow:clearPipeline


pub.flow:clearPipeline

Description Removes all fields from the pipeline.

Package WmPublic


preserve String [ ] Optional. String list containing field names that should not be cleared from the pipeline.

Output None.

pub.flow:debugLog

Description Writes a message to the server log (server\logs\server.log). Each log message contains a line number, function name, and message field. Example 000002 WMTXMG9999V message

Package WmPublic


message String Optional. Text of the message to write to the log.

function String Optional. Function name, typically an abbreviation used to identify the source of the message.

level String Optional. Debug level at which to display this message. Defaults to 1. If the debug level on the Server is set to a value less than this parameter, the message will not be written.

Output None.

pub.flow:getLastError

Description Obtains detailed information about the last exception that was trapped within a flow. An exception is trapped in a flow when a service failure occurs inside a SEQUENCE step that executes until DONE, or when a service failure occurs inside a REPEAT step that repeats on FAILURE.

Package WmPublic


lastError IData Contains information about the last error. The error information returned is specified by the pub.event:exceptionInfo Record.

Usage Notes If this service is not invoked from within a flow service, an exception is thrown. Each execution of a service (whether the service succeeds or fails) updates the value returned by getLastError. Consequently, getLastError itself resets the value of lastError. Therefore, if the results of getLastError will be used as input to subsequent services, map the value of lastError to a variable in the pipeline.



pub.flow:getSession

Description Inserts the Session object into the pipeline as a Record named $session. Session is useful for associating values with particular clients or users. Once $session is added to the pipeline, it can be used like any other Record in a flow. This permits more powerful flows that perform work spanning several user requests.

Package WmPublic

Input None.


$session IData An IData object containing fields associated with the current user session. Setting, copying, or dropping fields within $session is effectively manipulating the Session object on the Server.

pub.flow:getTransportInfo

Description Retrieves information about the protocol from which the current flow was invoked. The Record pub.flow:transportInfo defines what is output by this service.

Package WmPublic

Input None.


transport (transportInfo)

IData An IData object containing protocol specific information.

Usage Notes This service may be used by a flow service that needs protocol specific information. The protocol value should first be retrieved from the pub.flow:transportInfo Record. (protocol indicates the protocol used to invoke the service.) The Record for the protocol type can then be retrieved from the pub.flow:transportInfo Record. Currently, only the email client listener supports the getTransportInfo service. In the case of email protocol, protocol is set to email.

pub.flow:restorePipeline

Description Restores a pipeline previously saved by pub.flow:savePipeline. Pipelines are identified by $name, and an exception will be raised if the name is not known. After a successful invocation of pub.flow:restorePipeline, all fields present immediately before the respective invocation to pub.flow:savePipeline will be contained in the pipeline. Existing pipeline values are cleared during this invocation unless the optional $merge field is specified.

Package WmPublic


$name String Name of the saved pipeline. Since the multiple pipelines can be saved, this is necessary to identify the pipeline in memory. An exception will be raised if this value is left null or the name is unknown.

$merge String Optional. Indicates whether or not to merge the values in the existing pipeline with the values in the saved pipeline.

Set $merge to… To…

pub.flow:restorePipelineFromFile


Input Variable Name Type Description false Default. Clear the existing pipeline before

restoring the saved pipeline. true Merge the existing pipeline with the saved

pipeline. If a field exists in the saved pipeline and the existing pipeline, the saved field takes precedence.

$remove String Optional. Indicates whether or not the saved pipeline will remain in memory after this service is executed.

Set $remove to… To… false Default. Retain the saved pipeline in

memory so that future calls to restorePipeline with the same $name will still return the pipeline.

true Remove the saved pipeline from memory after the service executes.

Output The output is dynamic, based on the fields within the saved and existing pipelines.

pub.flow:restorePipelineFromFile

Description Retrieves a file of previously saved keys and values and merges or replaces the existing pipeline with them. Often the values are initially saved using pub.flow:savePipelineToFile.

Package WmPublic


fileName String Relative path and file name of a file containing a saved pipeline on the SAP BC.

merge String Optional. Whether or not to merge the saved values into the existing pipeline.

Set merge to… To… false Default. Replace the existing pipeline with

the saved values. true Merge the saved values into the existing

pipeline.

Usage Notes There is no specific output from this service. The pipeline contents depend on the values in the specified file. If the file is not found, an exception is thrown. This service is useful for debugging part of an application. Values that appear in the saved pipeline, but are not part of the regular running of the flow will not appear in the Pipeline Editor and, therefore, will not be available for explicit mapping.

pub.flow:savePipeline

Description Saves a pipeline into memory, for later retrieval by a call to pub.flow:restorePipeline. Pipelines are identified by $name, and an exception will be raised if the name is not provided. After a successful invocation of pub.flow:savePipeline, a snapshot of all pipeline fields will be saved in memory under the key provided by $name. Note that since pipelines are saved to memory, they will not be available after a server restart.



The main purpose of the save and restore services is to allow interactive development or debugging of flows. For example, if a client process posts data asynchronously to your flow, there is no way to visually step through the flow with Developer. But if your client calls pub.flow:savePipeline, you can develop a flow by calling pub.flow:restorePipeline as the first service in your flow. From there, you have access to the snapshot of the data sent by the client and can interactively develop and debug. When the flow is ready for production, remove the call to pub.flow:restorePipeline and ask the client to call your flow directly.

Package WmPublic


$name String Name to identify the pipeline in memory. An exception will be raised if this value is left null.

Output None.

pub.flow:savePipelineToFile

Description Saves the current pipeline contents to a file on the machine running SAP BC server. Often the values are restored using pub.flow:restorePipelineToFile.

Package WmPublic


fileName String Relative path to a file on SAP BC server in which to save the contents of the pipeline. If the file does not exist, the service creates it. If the file already exists, the service overwrites the contents of the old file with the new pipeline.

Usage Notes There is no specific output from this service. If the file is not found then an exception is thrown. This service is useful for debugging part of an application.

pub.flow:setResponse

Description Forces a specific response string to be returned by the SAP BC server to a calling process (such as a browser or application server). Formatting of the response is normally handled by templates, which format values from the pipeline. If templates are not appropriate for a particular integration scenario, a response message can be created within the flow and returned to the caller using this service. Typical usage of this service is to create an XML response to an XML request. A flow that creates an XML document by calling pub.web:recordToDocument can add pub.flow:setResponse and map the xmldata field (output of recordToDocument) to response (input to setResponse). Instead of processing the entire pipeline through a template to return a response, the template is ignored and the xmldata (response) is returned.

Package WmPublic


response String String body of the response to be returned to the caller.

contentType String Optional. String specifying the MIME type of the response data. By default the server’s response will match the MIME type of the request. This field allows this behavior to be overridden.

Preset values are text/XML and text/HTML, but user-defined values are also permitted.

pub.flow:sleep



encoding String Optional. The character set in which the response is encoded.

Output None.

Usage Notes The value you specify for contentType overrides the Content-Type the SAP BC server normally uses to return output to Developer. As a result, Developer is unable to decode or display output from flows that include this service. Consequently, if you use Run to test a flow including the pub.flow:setResponse service, Developer will not display any results. Instead, you will receive an error message. Therefore, if you include this service in a flow and you want to test the flow from Developer, use Run in Browser.

pub.flow:sleep

Description Sends the current service to sleep the given amount of seconds.

Package WmPublic


seconds String Optional. Sleep time in seconds (Default: 10)

pub.flow:tracePipeline

Description Writes the names and values of all fields in the pipeline to the server log (server\logs\server.log). This can be useful for debugging flows invoked by clients other than the Developer and thus cannot be debugged interactively.

Package WmPublic


level String Optional. Debug level at which to display the pipeline. Defaults to 1. If the debug level on the SAP BC server is set to a value less than this parameter, the pipeline will not be written.

Output None.

pub.flow:transportInfo

Description A Record containing the information about the protocol used to invoke a service.

Package WmPublic


protocol String Name of protocol used. Currently can only be set to email.

email IData IData object (Record) containing information about the email transport.


to String [ ] Email addresses for the recipients of the email.

from String [ ] Email addresses for the senders of the email.




cc String [ ] Email addresses receiving a copy of the email.

bcc String [ ] Email addresses receiving a blind copy of the email.

replyto String [ ] Email address to which replies of this email should be sent,

subject String [ ] Subject of the email.

filename String Name of the attached file.

contenttype String Content-Type of the attached file.

content Object A java.io:InputStream containing the contents of the attached file.

sentdate String Date the email was sent in String format. sentdate may be passed as parameter for the java.util.Date constructor.

recvdate String Date the email was received in String format. recvdate may be passed as parameter for the java.util.Date constructor.

http IData IData object (Record) containing information about the http transport.


requestUrl String String containing the URL of the request called.

query String String containing the HTTP query value.

requestHdrs Record The Http headers send with the request.

ipInfo Record Contains ip connection information Variable Name Description

localIp Local IP address used for the connection

localPort Local Port used for the connection

remoteIp Remote ip address for the connection

remotePort Remote Port for the connection



ftp IData IData object (Record) containing information about the ftp transport.


filename String String containing the name of the file send

mimetype String Mimetype used to send the file

Usage Notes This Record is output by the pub.flow:getTransportInfo service and can be used by a service to retrieve information about a transport.

C H A P T E R 1 0 S t r e a m / B y t e c o n v e r s i o n

124 SAP

Chapter 10 Stream/Byte conversion

You use this services to convert between Stream and byte data types.

10

BC Bulit-In Services Guide 4.8





Service Function pub.io:bytesToStream Convert a byte array to a stream.

pub.io:streamToBytes Convert a stream to a byte array.

C H A P T E R 1 0 S t r e a m / B y t e c o n v e r s i o n


pub.io:bytesToStream

Description Convert a byte array to a stream.

Package WmPublic


bytes Object Byte array to be converted to a stream.


stream Object The stream pointing to the byte array.

pub.io:streamToBytes

Description Convert a stream to a byte array.

Package WmPublic


stream Object The stream to get the bytes from.


bytes Object The bytes read from the stream.


Chapter 11 LDAP Services

You use LDAP services to access and update information on an LDAP directory server.

11

C H A P T E R 1 1 L D A P S e r v i c e s




Service Function pub.ldap:bind Adds an entry into the LDAP server.

pub.ldap:connect Connect to an LDAP server.

pub.ldap:delete Delete an entry from the LDAP server.

pub.ldap:disconnect Closes a connection to an LDAP server.

pub.ldap:getAttributeDef Get the definition of an attribute in the server’s schema.

pub.ldap:getClassDef Get the definition of an objectclass in the server’s schema.

pub.ldap:init Do not use. It is not meant to be invoked by a user.

pub.ldap:list List the bindings within a particular directory context.

pub.ldap:lookup Lookup a single entry in the directory server.

pub.ldap:search Search the directory for entries matching a set of criteria.

pub.ldap:shutdown Do not use. It is not meant to be invoked by a user.

pub.ldap:update Modifies attributes of an entry in the LDAP directory.

pub.ldap:bind


pub.ldap:bind

Description Adds an entry into the LDAP server.

Package WmPublic


ldapTargetName String The name of the entry that you want to add. For example, to add a user entry for Joe Krebbs in the ou=People context, specify cn=Joe Krebbs, ou=People for ldapTargetName.

ldapTargetObject Object Optional. An object that you want to store into this entry. Some LDAP servers restrict the kinds of objects you can store (some do not even support storage of Java objects). Typically, the objects must implement the java.io.Serializable interface. The default value for ldapTargetObject is null.

ldapTargetAttributes Values Optional. A Record containing the attributes to assign to the new entry. The following shows an example of inputs you might use to add the user Joe Krebbs: Example

Variable Value

objectclass organizationalPerson

cn Joe

sn Krebbs

uid jkrebbs

mail [email protected]

ldapConnectionKey String The key for the connection on the SAP BC; this is the key returned from the execution of pub.ldap:connect.

Output None.

Usage Notes You must have the appropriate permissions to add entries into an LDAP directory. For most simple insertions, you should not need to supply a Java object value for the ldapTargetObject input parameter. Refer to the schema of the target server to determine the attributes that are required. For example, typically an “objectclass” attribute is required.

pub.ldap:connect

Description Connect to an LDAP server.

Package WmPublic


ldapUrl String The URL of the LDAP server to connect with (e.g., ldap://bigfoot.com).

ldapUser String Optional. The user name to use on the LDAP server.

ldapPass String Optional. The password to use on the LDAP server.

ldapConnectionKey String Key for this connection on the SAP BC.



Output None.

Usage Notes Use this service to connect to an LDAP server and get a valid connection key. Use the returned connection key to invoke the rest of the pub.ldap services (including pub.ldap:disconnect). Your connection to the LDAP server remains open until the server shuts down or until the connection is disconnected. To connect to a subdirectory, specify the URL of the subtree for ldapUrl. For example, if your directory starts at ldap://mydir.com and you only want to operate on the subtree rooted at ou=People, specify, ldap://mydir.com/ou=People for ldapUrl.

pub.ldap:delete

Description Delete an entry from the LDAP server.

Package WmPublic


ldapLookupName String The name of the entry that you want to delete. For example, to delete Joe Krebbs from the ou=People context, specify cn=Joe Krebbs, ou=People for ldapLookupName.


Output None.

Usage Notes You must have the appropriate permissions to delete entries in an LDAP directory.

pub.ldap:disconnect

Description Closes a connection to an LDAP server.

Package WmPublic



Output None.

Usage Notes Use this service to disconnect from an LDAP server when you are done using the connection.

pub.ldap:getAttributeDef


pub.ldap:getAttributeDef

Description Get the definition of an attribute in the server’s schema.

Package WmPublic


ldapAttributeName String The name of the attribute for which you want to get the definition. For example, to get the definition of the “mail” class, specify mail for ldapAttributeName.



ldapAttributeDef IData A Record describing the named objectclass. It has the following structure:

Variable Value

NAME The name of the objectclass.

NUMERICOID The numeric OID of the objectclass.

SYNTAX The numeric OID of the syntax for the attribute.

DESC A description of this objectclass.

The following shows an example of the returned output from looking up the “mail” attribute: Example

NAME mail

NUMERICOID 2.16.840.1.113730.3.2.2

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15

DESC Standard Attribute

Usage Notes This service has been tested for the Netscape Directory servers. If you use a different LDAP server, test this service to ensure it works for your server.

pub.ldap:getClassDef

Description Get the definition of an objectclass in the server’s schema.

Package WmPublic


ldapObjectClass String The name of the objectclass for which you want to retrieve the definition. For example, to get the definition of the “organizationalPerson” class, specify organizationalPerson for ldapObjectClass.





ldapObjectClassDef IData A Record describing the named objectclass. It has the following structure:

Variable Type Value

NAME String The name of the objectclass. NUMERICOID String The numeric OID of the

objectclass. MAY String [ ] An array of names of optional

attributes. MUST String [ ] An array of names of required

attributes. DESC String A description of this

objectclass SUP String The superclass of this

objectclass.

Example The following shows an example of the returned output from looking up the “inetOrgPerson” class

Variable Value

NAME inetOrgPerson

NUMERICOID 2.16.840.1.113730.3.2.2

MAY aci

description

ssealso

etc.

MUST objectclass

sn

cn

DESC Standard ObjectClass

SUP organizationalPerson

Usage Notes This service has been tested for the Netscape Directory servers. If you use a different LDAP server, test this service to ensure it works for your server.

pub.ldap:init

Description Do not use. This service performs initialization routines that are used by the SAP BC server. It is not meant to be invoked by a user.

Package WmPublic

pub.ldap:list

Description List the bindings within a particular directory context.

Package WmPublic


ldapConnectionKey String The key for the connection on the SAP BC server; this is the

pub.ldap:list


Input Variable Name Type Description key returned from the execution of pub.ldap:connect.

ldapListRoot String Optional. The relative name of the context to list. If you do not specify a value for ldapListRoot, the default is "", which indicates the root context for the directory server.

ldapReturnObjects String Optional. Specifies whether you want the directory to return objects from the bindings or just the attributes. Specify the string true to have the objects returned; specify the string false to have just the attributes returned. For example, if your directory contains persisted Java objects, set this attribute to true to have the objects returned. If you do not specify a value for ldapReturnObjects, false is used and just attributes are returned.

ldapReturnAttributes String Optional. A comma-separated list of attribute names to return for each of the listed bindings. For example, to return only the “mail” and “uid” attributes, set this parameter to mail,uid. If you do not specify a value for ldapReturnAttributes, all attributes are returned.


ldapListing IData [ ] A Record array describing the objects bound within the specified directory context; one Record for each object. Each Record contains the following keys:

Key Type Description $name String The fully-qualified name of the

binding. $class String Java class of the returned object $object Object The object bound to this name in the

directory. (If you specified true for ldapReturnObjects).

There is one key for each returned attribute.

Usage Notes The directory server running on myCompany.com contains an ou=Users context, which contains an entry (binding) for each user in the directory server. To list the userid and e-mail address of each user, specify the following input parameters for the pub.ldap:list service:

Variable Value

ldapListRoot ou=Users

ldapReturnObjects false

ldapReturnAttributes uid,mail

The resulting Record list might look like this (perhaps with more entries): Key Description $name cn=Arthur Milberg, ou=People

uid amilberg


$name n=Dorothy Hadden, ou=People

uid dhadden




$name cn=Scott Treezak, ou=People

uid streezak


pub.ldap:lookup

Description Lookup a single entry in the directory server.

Package WmPublic


ldapConnectionKey String The key for the connection on the SAP BC.

ldapLookupName String The relative name of the context to look up, e.g., ou=People, cn=Arthur Milberg.

ldapReturnObject String Optional. Specifies whether you want the directory to return objects from the bindings or just the attributes. Specify the string true to have the objects returned; specify false to have just the attributes returned. For example, if your directory contains persisted Java objects, set this attribute to true to have the objects returned. If you do not specify a value for ldapReturnObjects, false is used and just attributes are returned.

ldapReturnAttributes String Optional. A comma-separated list of attribute names to return for each of the listed bindings. For example, to return only the “mail” and “uid” attributes, set this parameter to mail,uid. If you do not specify a value for ldapReturnAttributes, all attributes are returned.


ldapObject Object The object bound to the given name in the directory. (Returned only if ldapReturnObject is true.)

ldapAttributes IData The attributes associated with the given name in the directory. This will consist of a Record with one entry for each attribute.

Usage Notes It is recommended that you set the ldapReturnAttributes parameter to return a limited set of attributes. This reduces network traffic.

pub.ldap:search

Description Search the directory for entries matching a set of criteria.

Package WmPublic


ldapConnectionKey String Key for the connection on the SAP BC.

pub.ldap:search



ldapSearchFilter String A filter describing which entries to return. For instance, to retrieve all entries with the objectClass groupOfNames and cn of Engineers, you might use: (&(objectclass=groupOfNames)(cn=Engineers))

For more information about LDAP search filters, consult your server documentation or look for RFC 1558.

ldapSearchRoot String Optional. The name of the context in which to start the search (defaults to the root entry). The search will be recursive unless you specify the ldapSearchOneLevel parameter (see below). For example, to search only the “ou=Engineers” subcontext, set this parameter to “ou=Engineers”.

ldapSearchOneLevel String Optional. Specifies whether the search is performed only on the current node or on the current node and everything below it.

Set to… To… true Search only the current node. false Default. Search the current node and

everything below it.

ldapReturnObjects String Optional. Specifies whether the directory returns an object from the matching entries (as opposed to just attributes). This should be either the string “true” or the string “false” (default is “false”). For example, if your directory contains persisted Java objects, set this attribute to “true” to receive the objects themselves.

ldapReturnAttributes String Optional. A comma-separated list of attribute names to return for each of the returned entries (default is all attributes). For example, to return only the “mail” and “uid” attributes, set this parameter to “mail, uid”.


ldapSearchResults IData [ ] A Record array describing objects matching the search filter; one Record for each object. Each Record contains the following keys:

Key Type Value

$name String The fully-qualified name of the binding.

$object Object The object bound to this name in the directory. (Only if ldapReturnObjects is true.)

There is one key for each returned attribute.



Usage Notes Use searches that are as specific as possible, to avoid returning additional unnecessary data. This reduces network traffic and speeds up searches. Also, note that different servers respond to search filters in different ways based on their schema. For instance, the (uid=a*) filter might be rejected on a server that does not allow substring searches on the uid attribute.

pub.ldap:shutdown

Description Do not use. This service performs shutdown routines that are used by the SAP BC server. It is not meant to be invoked by a user.

Package WmPublic

pub.ldap:update

Description Modifies attributes of an entry in the LDAP directory.

Package WmPublic


ldapLookupName String The name of the entry that you want to modify. For example, to modify the entry for Joe Krebbs in the ou=People context, specify cn=Joe Krebbs, ou=People for ldapLookupName.


ldapAttributeMods Values [ ] An array of Records that describe the changes you want to make to this entry. Each of these Records has the following structure:

Variable Type Value

$name String The name of the attribute to modify.

$modtype String Optional. The action to take. Specify remove, replace, or add. The default is add.

$value String Optional. The new value to assign, if applicable.

The following shows an example of the inputs you might specify to change Joe Krebbs’ e-mail address:

Example

Variable Value

$name mail

$modtype replace

$value [email protected]

Output None.

Usage Notes You must have the appropriate permissions to modify entries in an LDAP directory. You cannot use this service to change the value of an entry itself (i.e., if you have bound Java objects in your directory, you must delete them and rebind the name to a different Java object).

pub.ldap:update


Chapter 12 List Services

You can use list services to retrieve, replace, or add elements in an Object list, Record list, or String list. You can also use list services to convert a String list to a Record list.

12

C H A P T E R 1 2 L i s t S e r v i c e s




Service Function pub.list:appendToRecordList Adds Records to a Record list.

pub.list:appendToStringList Adds strings to a string list.

pub.list:copyListItem Copies an element from one index in an object list to another index in a different object list or the same object list. The copied element replaces the existing element in the destination index.

pub.list:getListItem Retrieves an element from an object list.

pub.list:getRecordListItem Retrieves an individual Record from a Record list.

pub.list:getStringListItem Retrieves a string from a string list.

pub.list:setListItem Replaces an element in an object list with a new element.

pub.list:setRecordListItem Replaces a Record in a Record list with a new Record.

pub.list:setStringListItem Replaces a string in a string list with a new string.

pub.list:sizeOfList Returns the number of elements in a list.

pub.list:stringListToRecordList Converts a string list to a Record list.

pub.list:appendToRecordList


pub.list:appendToRecordList

Description Adds Records to a Record list.

Package WmPublic


toList IData [ ] Optional. Record list to append Records to. If you do not specify toList, the service creates a new list.

fromList IData [ ] Optional. Record list containing the Records you want to append to the end of toList. Records are added after the entries of toList.

fromItem IData Optional. Record you want to append to the end of toList. The Record is added after the entries of toList and fromList,.


toList IData [ ] The toList Record list with the Records in fromList and fromItem appended to it.

Usage Notes The Records contained in fromList and fromItem are not actually appended as entries to toList. Instead, the object references to the values in fromList and fromItem are appended as entries to toList. As a result, any changes made to the Records in fromList and fromItem affect the resulting toList as well.

pub.list:appendToStringList

Description Adds strings to a string list.

Package WmPublic


toList String [ ] Optional. String list to append strings to. If the value of toList is null, a null pointer exception error is given. If you do not specify toList, the service creates a new list.

fromList String[ ] Optional. String list you want to append to toList. Strings are added after the entries of toList.

fromItem String Optional. String you want to append to the end of toList. The string is added after the entries of toList and fromList,.


toList String[ ] The toList string list with the strings in fromList and fromItem appended to it.

Usage Notes The strings contained in fromList and fromItem are not actually appended as entries to toList. Instead, the object references to the strings in fromList and fromItem are appended as entries to toList. Consequently, any changes made to the strings in fromList and fromItem affect the resulting toList as well.

pub.list:copyListItem

Description Copies an element from one index in an object list to another index in a different object list or the same object list. The copied element replaces the existing element in the destination index.



Package WmPublic


fromList Object[ ] Object list containing the element you want to copy.

toList Object[ ] Object list in which you want to place the copied element

fromIndex String Index of the element you want to copy.

toIndex String Index in which you want to place the copied element.

Output None.

Usage Notes String lists and Record lists can also be used with this list service because they are acceptable object lists. Note: To copy an element from one index in an object list to another index in the same object list, you can delete the toList on the Input/Output tab. Then, on the Flow tab, map the fromList to the toList.

pub.list:getListItem

Description Retrieves an element from an object list.

Package WmPublic


list Object[ ] Object list containing the element you want to retrieve.

index String Index of the element you want to retrieve.


item Object Object at the specified index.

pub.list:getRecordListItem

Description Retrieves an individual Record from a Record list.

Package WmPublic


list Values [ ] Record list containing the Record you want to retrieve.

index String Index of the Record you want to retrieve.


item IData Record at the specified index.

pub.list:getStringListItem


pub.list:getStringListItem

Description Retrieves a string from a string list.

Package WmPublic


list String [ ] String list containing the string you want to retrieve.

index String Index of the string you want to retrieve.


item String String at the specified index.

pub.list:setListItem

Description Replaces an element in an object list with a new element.

Package WmPublic


list Object[ ] Object list containing the element you want to replace.

index String Index of the element you want to replace.

item Object New element you want to use as a replacement for the existing element at the specified index.

Output None.

pub.list:setRecordListItem

Description Replaces a Record in a Record list with a new Record.

Package WmPublic


list Values [ ] Record list containing the Record you want to replace.

index String Index of the Record you want to replace.

item Values New Record you want to use as a replacement for the Record that currently exists at the specified index.

Output None.

pub.list:setStringListItem

Description Replaces a string in a string list with a new string.

Package WmPublic


list String [ ] String list containing the string you want to replace.

index String Index of the string you want to replace.

item String New string you want to use as a replacement for the existing string at the specified index.



Output None.

pub.list:sizeOfList

Description Returns the number of elements in a list.

Package WmPublic


fromList Object[ ] Object list you want the size of.


size String Length of the list.

Usage Notes Example: if fromList consists of: fromList[0] = "a" fromList[1] = "b" fromList[2] = "c"

Result: size="3"

pub.list:stringListToRecordList

Description Converts a string list to a Record list.

Package WmPublic


fromList String[ ] String list you want to convert to a Record list.

key String The key to use in the generated Record list.


toList IData [] The generated Record list.

Usage Notes Creates a Record list with a Record named toList for each element in the fromList. Each Record contains a string named key. Example

fromList[0] = "a" fromList[1] = "b" fromList[2] = "c" key = "myKey"

Result

pub.list:stringListToRecordList


Chapter 13 Math Services

You use math services to add, subtract, multiply, or divide string-based numeric values.

Note: Services that operate on integer values use Java’s long data type (64-bit two’s complement). Services that operate on float values use Java’s double data type (64-bit IEEE 754). If extremely precise calculations are critical to your application, you should write your own Java services to perform math functions.

13

C H A P T E R 1 3 M a t h S e r v i c e s




Service Function pub.math:addFloatList Adds the numeric values in numList and returns the sum as value.

pub.math:addFloats Adds the numeric values of num1 and num2 and returns the sum as value.

pub.math:addIntList Adds the numeric values in numList and returns the sum as value.

pub.math:addInts Adds the numeric values of num1 and num2 and returns the sum as value.

pub.math:divideFloats Divides the numeric value of num1 by the numeric value of num2 (num1 / num2) and returns the quotient as value.

pub.math:divideInts Divides the numeric value of num1 by the numeric value of num2 (num1 / num2) and returns the quotient as value.

pub.math:multiplyFloatList Multiplies the numeric values in numList and returns the product as value.

pub.math:multiplyFloats Multiplies the numeric value of num1 by the numeric value of num2 and returns the product as value.

pub.math:multiplyIntList Multiplies the numeric values in numList and returns the product as value.

pub.math:multiplyInts Multiplies the numeric value of num1 by the numeric value of num2 and returns the product as value.

pub.math:randomDouble Returns the next pseudorandom, uniformly distributed double between 0.0 and 1.0. Random number generators are often referred to as pseudorandom number generators because the numbers produced tend to repeat themselves after a period of time.

pub.math:randomLong Generates a pseudo random number and returns its string representation in a pipeline variable. This number may be used as a universal identifier with reasonable security if it is used in non-distributed scenarios and for a small number of items.

pub.math:randmLong

Description Generates a pseudo random number and returns its string representation in a pipeline variable. This number may be used as a universal identifier with reasonable security if it is used in non-distributed scenarios and for a small number of items.

Package WmPublic


None.


number String Pseudo random number.

pub.math:subtractFloats

Subtracts the numeric value of num2 from the numeric value of num1 (num1 – num2) and returns the difference as value.

pub.math:subtractInts Subtracts the numeric value of num2 from the numeric value of num1 (num1 – num2) and returns the difference as value.

pub.math:addFloatList


pub.math:addFloatList

Description Adds the numeric values in numList and returns the sum as value.

Package WmPublic


numList String [ ] A String array containing a list of string-based float values.


value String A String representation of the sum of the numeric values contained in numList.

pub.math:addFloats

Description Adds the numeric values of num1 and num2 and returns the sum as value.

Package WmPublic


num1 String String representation of a float.



value String A String representation of the sum of the numeric values of num1 and num2.

pub.math:addIntList

Description Adds the numeric values in numList and returns the sum as value.

Package WmPublic


numList String [ ] String array containing a list of string-based integer values.


value String A String representation of the sum of the numeric values contained in numList.

pub.math:addInts

Description Adds the numeric values of num1 and num2 and returns the sum as value.

Package WmPublic


num1 String String representation of an integer.



value String A String representation of the sum of the numeric values of num1 and num2.



Usage Notes Make sure the result of your calculation is less than 64-bits in width (the maximum width for the long data type). If the result exceeds this limit, it will generate a data overflow.

pub.math:divideFloats

Description Divides the numeric value of num1 by the numeric value of num2 (num1 / num2) and returns the quotient as value.

Package WmPublic





value String A String representation of the quotient of sum of num1 / num2.

pub.math:divideInts

Description Divides the numeric value of num1 by the numeric value of num2 (num1 / num2) and returns the quotient as value.

Package WmPublic





value String A String representation of the quotient of sum of num1 / num2.

pub.math:multiplyFloatList

Description Multiplies the numeric values in numList and returns the product as value.

Package WmPublic


numList String [ ] String array containing a list of string-based float values.


value String A String representation of the product of the values in numlist.

pub.math:multiplyFloats

Description Multiplies the numeric value of num1 by the numeric value of num2 and returns the product as value.

Package WmPublic




pub.math:multiplyIntList



value String A String representation of the product of of num1 and num2.

pub.math:multiplyIntList

Description Multiplies the numeric values in numList and returns the product as value.

Package WmPublic


numList String [ ] String array containing a list of string-based integer values.


value String A String representation of the product of the values in numlist.


pub.math:multiplyInts

Description Multiplies the numeric value of num1 by the numeric value of num2 and returns the product as value.

Package WmPublic





value String A String representation of the product of of num1 and num2.


pub.math:randomDouble

Description Returns the next pseudorandom, uniformly distributed double between 0.0 and 1.0. Random number generators are often referred to as pseudorandom number generators because the numbers produced tend to repeat themselves after a period of time.

Package WmPublic

Input None.


number String The generated random number.

pub.math:randomLong

Description Generates a pseudo random number and returns its string representation in a pipeline variable. This number may be used as a universal identifier with reasonable security if it is used in non-distributed scenarios and for a small number of items.

Package WmPublic




None.


number String Pseudo random number.

pub.math:subtractFloats

Description Subtracts the numeric value of num2 from the numeric value of num1 (num1 – num2) and returns the difference as value.

Package WmPublic





value String A String representation of the result of num1 – num2.

pub.math:subtractInts

Description Subtracts the numeric value of num2 from the numeric value of num1 (num1 – num2) and returns the difference as value.

Package WmPublic





value String A String representation of the result of num1 – num2.



Chapter 14 Mime Services

You use the mime services to work with MIME messages. This folder contains services for constructing MIME messages and for extracting data from MIME messages that are placed in the pipeline.

14

C H A P T E R 1 4 M i m e S e r v i c e s




Service Function

pub.mime:addBodyPart Adds a body part (header fields and content) to a specified MIME object.

pub.mime:addMimeHeader Adds one or more header fields to a specified MIME object.

pub.mime:createMimeData Creates an empty MIME object if no input value is passed to it. Otherwise, creates a MIME object containing the elements (header fields and content) from the MIME message in input.

pub.mime:getBodyPartContent Retrieves the content (payload) from the specified MIME object. You use this service for both single-part and multi-part messages.

pub.mime:getBodyPartHeader Returns the list of header fields for the specified body part.

pub.mime:getContentType Returns the value of the content-type message header from the specified MIME object.

pub.mime:getEnvelopeStream Generates an InputStream representation of a MIME message from a specified MIME object.

pub.mime:getMimeHeader Returns the list of message headers from a specified MIME object.

pub.mime:getNumParts Returns the number of body parts in the specified MIME object.

pub.mime:getPrimaryContentType Returns the top-level portion of a MIME object’s content-type value.

pub.mime:getSubContentType Returns the sub-type portion of a MIME object’s content-type value.

pub.mime:mergeHeaderAndBody Concatenates the contents of the header and body and returned by pub.client:http service.

pub.mime:addBodyPart



Description Adds a body part (header fields and content) to a specified MIME object.

Package WmPublic


mimeData Object The MIME object to which you want to add a body part.

content InputStream —OR— MIME Object

An InputStream containing the content that you want to add to the MIME object. content can be an InputStream or another MIME object. Use an InputStream to add an ordinary payload. Use a MIME object to add a payload that is itself a MIME message

mimeHeader IData Optional. Specifies the part headers that you want to add with this body part. Key names represent the names of the header fields. The values of the keys represent the values of the header fields. For example, if you wanted to add the following header fields:

X-Doctype: RFQ

X-Severity: 10

You would set mimeHeader as follows:

Key Value

X-Doctype RFQ X-Severity 10

Be aware that the following MIME headers are automatically inserted by getEnvelopeStream when it generates the MIME message: Message-ID

MIME-Version

Additionally, you use the content, encoding, and description parameters to set the following fields: Content-Type

Content-Transfer-Encoding

Content-Description

Be aware that if you set these header fields in mimeHeader, they will be overwritten if contenttype, encoding, and/or description are also set.

contenttype String Optional. Specifies the value of the Content-Type header for this body part.

encoding String Optional. Specifies how the body part is to be encoded for transport and sets the value of the Content-Transfer-Encoding header. Note: This parameters determines how the payload is to be encoded for transport. When you add a payload to mimeData, it should be in its original format. The getEnvolopeStream service will perform the encoding (as specified by encoding) when it generates the final MIME message.



Must be one of the following:

Value Description

7bit Default. Specifies that content is 7-bit, line-oriented text that needs no encoding.

8bit Specifies that content is 8-bit, line-oriented text that needs no encoding.

Note: This encoding value is not recommended for messages that will be transported via SMTP over the Internet, because mail servers that the data can be altered by intervening mail servers that can’t accommodate 8-bit text. To safely transport 8-bit text, use quoted-printable encoding instead.

binary Specifies that content contains binary information that needs no encoding.

Note: This encoding value is not recommended for messages that will be transported via SMTP over the Internet, because the data can be altered by intervening mail servers that can’t accommodate binary data. To safely transport binary data, use base64 encoding instead.

quoted-printable Specifies that content contains 7 or 8-bit, line-oriented text that you want to encode using the quoted-printable encoding scheme.

base64 Specifies that content contains an arbitrary sequence of octets that you want to encode using the base64 encoding scheme.

uuencode Specifies that content contains an arbitrary sequence of octets that you want to encode using the uuencode encoding scheme.

isEnvStream String A String that specifies whether content is to be treated as a MIME entity. This parameter is only used if content is an InputStream. You must set this parameter to one of the following values:

Value Description

yes Treat content as a MIME entity. addBodyPart will strip out the header fields from the top of content and add them to mimeData as part headers. The remaining data will be treated as the payload. Note: addBodyPart assumes that all data up to the first blank line represents the entity’s header



fields. no Treat content as an ordinary payload. multipart String Optional. A String whose value determines how addBodyPart

behaves if mimeData already contains one or more body parts. By default, addBodyPart simply appends a new body part to mimeData if it already contains a payload. (This allows you to construct multi-part messages.) However, you can override this behavior if you want to either replace the existing payload with the new body part or throw an exception under these circumstances (see replace parameter, below)

Value Description

yes Default. addBodyPart appends a new body part to mimeData.

no addBodyPart replaces the existing payload with the new body part or throws an exception, depending on the value of replace.

replace String Optional. A String whose value specifies whether addBodyPart replaces the existing payload or throws an exception when it receives a mimeData that already contains a payload. This parameter is only used when multipart is “false.”

Value Description

yes Default. addBodyPart replaces the existing payload with the new body part.

no addBodyPart throws an exception.

description String Optional. Specifies the value of the Content-Description header for this body part.

Output mimeData Object The MIME object to which the body part was added.

Usage Notes This service operates on the MIME object (mimeData) produced by createMimeData. For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME messages” in the SAP BC Developer Guide.

See Also createMimeData getBodyPartContent addMimeHeader

Examples For examples of how to use this service, see the following services, which reside in the WmSamples package on your SAP BC server. samples.mime:build_SimpleMIME samples.mime:build_MultipartMIME



pub.mime:addMimeHeader

Description Adds one or more header fields to a specified MIME object.

Package WmPublic


mimeHeader IData Specifies header fields that you want to add to the MIME object. Key names represent the names of the header fields. The values of the keys represent the values of the header fields. For example, to add the following header fields:

X-Doctype: RFQ

X-Severity: 10

You would set mimeHeader as follows:

Key Value

X-Doctype RFQ X-Severity 10 Be aware that the following MIME headers are automatically

inserted by getEnvelopeStream when it generates the MIME message: Message-ID

MIME-Version

If you set these values in mimeHeader, they will be overwritten by getEnvelopeStream at run-time. Do not set the Content-Type header with this service. This particular header field is derived at run time, and any value you set here will be ignored. For single-part messages, Content-Type is derived from the contenttype setting specified for the body part. For multipart messages, Content-Type is automatically set to “multipart/mixed.”

mimeData Object The MIME object to which you want the header fields added.

Output mimeData Object The MIME object to which the header fields were added.

Usage Notes This service operates on the MIME object (mimeData) produced by createMimeData. If you add MIME headers before you add multiple body parts, the header fields will be added to each of the body parts. If you do not want this behavior, either drop mimeHeader from the pipeline immediately after you execute addMimeHeader, or invoke addMimeHeader after you’ve added all body parts to the MIME object. For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME Messages” in the SAP BC Developer Guide.

See Also createMimeData getMimeHeader addMimeBodyPart

Examples For examples of how to use this service, see the following services, which reside in the WmSamples package on your SAP BC server. samples.mime:build_SimpleMIME

pub.mime:createMimeData


pub.mime:createMimeData

Description Creates an empty MIME object if no input value is passed to it. Otherwise, creates a MIME object containing the elements (header fields and content) from the MIME message in input.

If you are building a MIME message, you use this service to create an empty MIME object. You populate the empty MIME object with header fields and content, and then pass it to getEnvelopeStream, which produces the finished MIME message.

If you are extracting data from a MIME message, you use this service to parse the original MIME message into a MIME object so that you can extract its header fields and content using other SAP BC services.

Package WmPublic


input InputStream Optional. The MIME entity you want to parse. If input is not provided, createMimeData creates an empty MIME object.

mimeHeader IData Optional. Specifies header fields that you want to add to the MIME object Key names represent the names of the header fields. The values of the keys represent the values of the header fields. Note: This parameter is ignored when input is passed to this service. For example, if you wanted to add the following header fields:

X-Doctype: RFQ

X-Severity: 10

You would set mimeHeader as follows: Key Value..

X-Doctype RFQ X-Severity 10 Be aware that the following MIME headers are automatically

inserted by getEnvelopeStream when it generates the MIME message: Message-ID

MIME-Version

Content-Type

Content-Transfer-Encoding

If you set these values in mimeHeader, they might be overwritten by getEnvelopeStream at run-time.

subType String Optional. A String that specifies the subtype portion of the Content Type header, when the message is a multipart message and you want something other than the default value of mixed. For example, if you want the Content Type header to be multipart/related in the resulting message, set subType to related. subType is ignored if the resulting message is not a multipart message.




mimeData Object A MIME object. If input was passed to createMimeData, mimeData will contain the parsed MIME message. If input was not passed to createMimeData, mimeData will be empty.

signed String A String whose value indicates whether input was a signed message.

If Value is… Then..

true The message is signed message (the original message stream is in stream).

false The message is not signed. encrypted String A String whose value indicates whether input was an

encrypted message.


true The message is encrypted message (the original message stream is in stream).

false The message is not encrypted.

certsOnly String A String whose value indicates whether input contained only digital certificates. (This type of message can be produced by the pub.smime:createCertsOnlyObject service, and allows digital certificates to be transported via the network as a MIME message.)


true The message contains only certificates. false The message contains a regular payload.

stream InputStream An InputStream that contains the original MIME message from input. It is only returned when input is an S/MIME message.

Usage Notes All of the other MIME services operate on the mimeData object produced by this service. They do not operate directly on MIME message streams. For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME Messages” in the SAP BC Developer Guide.

See Also addMimeHeader addMimeBodyPart getMimeHeader getMimeBodyPartContent getEnvelopeStream

Examples For examples of how to use this service, see the following services, which reside in the WmSamples package on your SAP BC server. samples.mime:build_SimpleMIME samples.mime:build_MultipartMIME samples.mime:extract_SimpleMIME samples.mime:extract_MultipartMIME

pub.mime:getBodyPartContent


pub.mime:getBodyPartContent

Description Retrieves the content (payload) from the specified MIME object. You use this service for both single-part and multi-part messages. To retrieve content from a multi-part message, you set the index (to select the part by index number) or contentID (to select the part by content-ID value) parameter to specify the body part whose content you want to retrieve. To get the content from a single-part message, you omit the index and contentID parameters or set index to 0.

Package WmPublic


mimeData Object The MIME object whose content you want to retrieve.

index String Optional. The index number of the body part whose content you want to retrieve. (If you want to retrieve the content from a specific body part.) The first body part is index number zero.

contentID String Optional. The value of the Content-ID header field of the body part whose content you want to retrieve. (If you want to retrieve the payload from a specific body part.) Note: In cases where both contentID and index are specified, index is ignored.


content InputStream An InputStream containing the payload of the specified body part.

signed String A String whose value indicates whether output is a signed MIME message.


true output is a signed MIME message. false output is not a signed MIME message.

encrypted String A String whose value indicates whether output is an encrypted MIME message.


true output is an encrypted message. false output is not an encrypted message.

certsOnly String A String whose value indicates whether output is a certs-only MIME message.


true output is a certs-only message. false output is not a certs-only message.

Usage Notes This service operates on the MIME object (mimeData) produced by createMimeData. If you omit index or contentID when retrieving content from a multi-part message, getBodyPartContent returns the payload from the first body part. For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME Messages” in the SAP BC Developer Guide.

See Also createMimeData addBodyPart getBodyPartHeader



Examples For examples of how to use this service, see the following services, which reside in the WmSamples package on your SAP BC server. samples.mime:extract_SimpleMIME samples.mime:extract_MultipartMIME

pub.mime:getBodyPartHeader

Description Returns the list of header fields for the specified body part.

Package WmPublic


mimeData Object The MIME object whose message headers you want to retrieve.

index String Optional. The index number of the body part whose header fields you want to retrieve. The first body part is index zero.

contentID String Optional. The value of the Content-ID header field of the body part whose header fields you want to retrieve. Note: In cases where both contentID and index are specified, index is ignored.


mimeHeader IData An IData object (a Record) containing the message headers. Key names represent the names of the header fields. The value of a key represents the value of that header field. For example, if the original message contained the following message header fields:

Content-Type: text/xml

X-Doctype: RFQ

X-Severity: 0

getBodyPartHeader would return the following IData object: Key Value

Content-Type text/xml

X-Doctype RFQ

X-Severity 0

Usage Notes This service operates on the MIME object (mimeData) produced by createMimeData. If you omit index or contentID, getBodyPartHeader returns the message headers from the first body part. For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME Messages” in the SAP BC Developer Guide.

See Also createMimeData addBodyPart getMimeHeader

pub.mime:getContentType

Description Returns the value of the content-type message header from the specified MIME object.

Package WmPublic

pub.mime:getEnvelopeStream



mimeData Object The MIME object whose Content-Type you want to discover.


contentType String A String containing the value of the MIME object’s Content-Type header field. Note that this service returns only the media type and subtype portion of this header field’s value. It does not return any parameters the value may include. For example, if the message’s Content-Type header were:

content-type: text/plain;charset=UTF8

contentType would contain: text/plain

Usage Notes This service operates on the MIME object (mimeData) produced by createMimeData. For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME Messages” in the SAP BC Developer Guide.

See Also createMimeData getMultipartSubType getMimeHeader getBodyPartHeader

pub.mime:getEnvelopeStream

Description Generates an InputStream representation of a MIME message from a specified MIME object.

Package WmPublic


mimeData Object The MIME object from which you want to generate the MIME message.

index String Optional. The index number of the body part for which you want to generate the MIME message. (If you want to generate the message from a specific body part.) The first body part is index number zero.

contentID String Optional. The value of the Content-ID header field of the body part from which you want to generate the MIME message. (If you want to generate the message from a specific body part.) Note: In cases where both contentID and index are specified, contentID is ignored.

suppressHeaders String[ ] Optional. A String list specifying the names of header fields that are to be omitted from message. You can use this option to exclude header fields that getEnvelopeStream generates by default, such as content-type and content-encoding.

createMultipart String Optional. A String specifying whether a multipart message is to be created, even if mimeData contains only one body part.

Value Description

yes getEnvelopeStream will create a multipart message. (Content-Type message header is set to “multipart/mixed”)




no Default. getEnvelopeStream will create a message based on the number of body parts in mimeData. If the message contains only one body part,

Content-Type is set according to the contenttype setting specified when that body part was added to mimeData.

If the message contains multiple body parts, Content-Type is automatically set to “multipart/mixed.”


envStream InputStream An InputStream containing the finished MIME message.

Usage Notes This service operates on the MIME object (mimeData) produced by createMimeData. If you omit index or contentID, getEnvelopeStream generates the MIME message from the entire contents of the mimeData. getEnvelopeStream automatically inserts the MIME-Version and Message-ID message headers into the MIME message it puts into envStream. For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME Messages” in the SAP BC Developer Guide.

See Also createMimeData addBodyPart addMimeHeader

Examples For examples of how to use this service, see the following services, which reside in the WmSamples package on your SAP BC server. samples.mime:build_SimpleMIME samples.mime:build_MultipartMIME

pub.mime:getMimeHeader

Description Returns the list of message headers from a specified MIME object.

Package WmPublic


mimeData Object The MIME object whose message headers you want to retrieve.


mimeHeader IData An IData object (a Record) containing the message headers. Key names represent the names of the header fields. The value of a key represent the value of the header fields. For example, if the original message contained the following message header fields: Message-ID: <[email protected]>

From: "[email protected]" <[email protected]>

To: <[email protected]>

MIME-Version: 1.0

Content-Type: text/xml

X-Doctype: RFQ

X-Severity: 0

pub.mime:getNumParts


getMimeHeader would return the following:

Key Value

Message-ID <[email protected]>

From "[email protected]" <[email protected]>

To <[email protected]>

MIME-Version 1.0

Content-Type text/xml

X-Doctype RFQ

X-Severity 0


See Also createMimeData addMimeHeader getBodyPartHeader

pub.mime:getNumParts

Description Returns the number of body parts in the specified MIME object.

Package WmPublic


mimeData Object The MIME object whose parts you want to count.


numParts String An String representing the number of body parts in the MIME object.


See Also createMimeData getBodyPartContent addBodyPart

Examples For examples of how to use this service, see the following services, which reside in the WmSamples package on your SAP BC server. samples.mime:extract_MultipartMIME

pub.mime:getPrimaryContentType

Description Returns the top-level portion of a MIME object’s content-type value.

Package WmPublic


mimeData Object The MIME object whose Content-Type you want to discover.




primContentType String A String containing the message’s top-level Content-Type. For example, if the message’s Content-Type header were:

Content-Type: multipart/mixed

primContentType would contain: multipart


See Also createMimeData getContentType getMimeHeader getBodyPartHeader

pub.mime:getSubContentType

Description Returns the sub-type portion of a MIME object’s content-type value.

Package WmPublic


mimeData Object The MIME object whose sub-type you want to discover.


subContentType String A String containing the message’s sub-type. For example, if the message’s content-type header were:

content-type: multipart/mixed

subContentType would contain: mixed


See Also createMimeData getContentType getMimeHeader getBodyPartHeader

pub.mime:mergeHeaderAndBody

Description Concatenates the contents of the header and body and returned by pub.client:http service. You can use this service to reassemble the message into its original form so that it can be used as input to the createMimeData service (or any other service that requires the entire HTTP response as an InputStream).

Package WmPublic


headerLines Record The Record (IData object) containing the message headers returned by pub.client:http. (The message headers are returned in the lines Record inside the header output parameter that is produced by pub.client:http.)

pub.mime:mergeHeaderAndBody


body Record The Record (IData object) containing the body of the message returned by pub.client:http. This Record must contain the body of the message in one of the following keys:

Key Description

bytes A byte[ ] containing the body of the message (if pub.client:http returned the body as a byte[ ]).

stream An InputStream containing the body of the message (if pub.client:http returned the body as an InputStream).


stream Object An InputStream containing the reassembled http message.

Usage Notes Use this service to merge the results produced by pub.client:http to get the original MIME message.

See Also pub.client:http pub.mime:createMimeData


Chapter 15 Package Services

You use these services to install, load, and/or alter the status of a package on the SAP BC.

15

C H A P T E R 1 5 P a c k a g e S e r v i c e s




Service Function pub.packages:activatePackage Activates (makes available to clients) an inactive package.

pub.packages:disablePackage Disables a package, which prohibits access to the services in the package.

pub.packages:enablePackage Enables a package that has been disabled.

pub.packages:installPackage Installs a package that has been published to this server.

pub.packages:recoverPackage Recovers a package that exists in the server’s salvage directory..

pub.packages:reloadPackage Loads a new copy of the package into memory from disk.

pub.packages:activatePackage


pub.packages:activatePackage

Description Activates (makes available to clients) an inactive package. You use this service to activate a package that was not activated when it was initially installed or recovered. Note: This service is to be used to activate packages from an inactive state (i.e., packages that are installed on the server, but are not registered in the active-package list). To enable a package that is in a disabled state, you use pub.packages:enablePackage.

Package WmPublic


package String The name of the package that you want to activate. (Package names are case-sensitive.)


message String A String containing a descriptive text message. (This is the same message that you receive when you activate a package with the SAP BC Administrator.)

Usage Notes This service will throw an exception if the package specified in package does not exist or cannot otherwise be activated. When a package is activated, it is loaded into memory in an enabled state (i.e. activatePackage automatically activates and enables the package.) You do not need to explicitly enable it with pub.packages:enablePackage.

See Also pub.packages:enablePackage pub.packages:installPackage pub.packages:recoverPackage

pub.packages:disablePackage

Description Disables a package, which prohibits access to the services in the package.

Package WmPublic


package String A String specifying the name of the package that you want to disable. (Package names are case-sensitive.)


message String A String containing a descriptive text message. (This is the same message that you receive when you disable a package with the SAP BC Administrator.)

Usage Notes When a package is disabled, the services in the package are no longer available to the clients. To re-enable a package that has been disabled, use pub.packages:enablePackage. Important! Never disable the WmRoot package. Doing so would disable the server. Be aware that if you disable a package while services in the package are being executed, those services will most likely fail—pub.packages:disablePackage does not wait for in-progress services to finish before disabling a package. This service will throw an exception if the package specified in package does not exist or cannot otherwise be disabled.



See Also pub.packages:enablePackage

pub.packages:enablePackage

Description Enables a package that has been disabled. Note: You use this service to enable a package that is in a disabled state (i.e., a package that has been disabled through the SAP BC Administrator or the pub.packages:disablePackage service. If you want to activate a package that is in an inactive state, you use pub.packages:activatePackage.

Package WmPublic


package String A String specifying the name of the package that you want to enable. (Package names are case-sensitive.)


message String A String containing a descriptive text message. (This is the same message that you receive when you enable a package with the SAP BC Administrator.)

Usage Notes When you enable a package, the package is reloaded into memory from disk. This service will throw an exception if the package specified in package does not exist, has not been activated, or cannot otherwise be enabled.

See Also pub.packages:disablePackage pub.packages:activatePackage pub.packages:reloadPackage

pub.packages:installPackage

Description Installs a package that has been published to this server.

Package WmPublic


packageFile String A String specifying the name of the distribution file that contains the package that you want to install. This file must reside in the server’s inbound directory (<sapbc>\server\replicate\inbound). When specifying packageFile,

Do include the .zip extension in the file name. Do not include the directory path.

Example: myPackageFileAug2001.zip

activateOnInstall String A String that specifies whether you want the package to become active or inactive after installation.

Set to… To…

yes Install the package and make it immediately available to clients.

no Install the package without making it available to clients. If you install a package in this mode, it will not be accessible until it is explicitly activated through the SAP BC Administrator or the pub.packages:activatePackage

pub.packages:recoverPackage


service.


message String A String containing a descriptive text message. (This is the same message that is displayed when you install a package with the SAP BC Administrator.)

Usage Notes If the installed package replaces an existing package on the server, installPackage will automatically put a back-up copy of the existing package in <sapbc>\server\replicate\salvage before it installs the new package. This service will throw an exception if the file named in packageFile does not exist or cannot otherwise be installed correctly.

See Also pub.packages:activatePackage pub.packages:recoverPackage

pub.packages:recoverPackage

Description Recovers a package that exists in the server’s salvage directory.. The salvage directory (<sapbc>\server\replicate\salvage) is where the server keeps packages that are deleted with the “safe delete” option or replaced with newer installed versions.

Package WmPublic


package String The name of the package that you want to recover. (Package names are case-sensitive.)

String A String that specifies whether you want the package to become active or inactive after it is recovered.

activateOnRecover Set to… To…

yes Recover the package and make it immediately available to clients.

no Recover the package without making it available to clients. If you recover a package in this mode, it does not become accessible to clients until you explicitly activate it through the SAP BC Administrator or the pub.packages:activatePackage service.


message String A String containing a descriptive text message. (This is the same message that is displayed when you recover a package with the SAP BC Administrator.)

Usage Notes You can only recover packages that exist in the server’s salvage directory. If you recover a package that is currently installed on the server, the package from the salvage directory replaces the version that is currently installed. (Be aware that the server does not retain a copy of the version that it replaces.) This service will throw an exception if the file named in package does not exist in the server’s salvage directory or cannot otherwise be recovered.

See Also pub.packages:activatePackage



pub.packages:reloadPackage

Description Loads a new copy of the package into memory from disk. If you make changes to the service in a package while the server is running, you must use reloadPackage to put those changes into effect.

Package WmPublic


package String The name of the package that you want to reload. (Package names are case-sensitive.)


message String A String containing a descriptive text message. (This is the same message that is displayed when you reload a package with the SAP BC Administrator.)

Usage Notes Be aware that if you reload a package while services in the package are being executed, those services will most likely fail—pub.packages:reloadPackage does not wait for in-progress services to finish before reloading a package. This service will throw an exception if the file named in package does not exist or cannot otherwise be reloaded.


Chapter 16 Record Services

You use these services to perform operations on Records in the pipeline.

16

C H A P T E R 1 6 R e c o r d S e r v i c e s




Service Function pub.record:length Returns the number of Records in a Record list.

pub.record:recordListToRecord Construct a Record from a list of Records. Two constant fields (name, value) are retrieved from every Record in the input Record list. The name field is then placed into the output Record, with its value equal to the value field.

pub.record:recordToRecordList Expand the contents of a Record into a list of Records. Each name/value pair in the target Record will become a new Record in a Record list with constant keys for name and value.

pub.record:recordToXMLValues Convert a Record in the pipeline to a String by encoding it as SAP BC XMLValues format. To decode the String back into a Record, use pub.record:XMLValuesToRecord.

pub.record:XMLValuesToRecord Convert a String containing XMLValues to a Record by decoding the SAP BC XMLValues format.

pub.record:length


pub.record:length

Description Returns the number of Records in a Record list.

Package WmPublic


recordList Values [ ] Record list for which a length calculation is needed.


length String Number of Records in the input Record list. If the input Record list is null, this key is not added to the pipeline.

pub.record:recordListToRecord

Description Constructs a Record (an IData object) from a Record List (an array of IData objects) by generating key/value pairs from the values of two elements that you specify in the Record List. The following illustrates how recordListToRecord would convert a Record List that contains three records to a single Record containing three, key/value pairs. When you use recordListToRecord, you specify which two elements from the source list are to be transformed into the keys and values in the output Record. In this example, the values from the pName elements in the source list are transformed into key names, and the values from the pValue elements are transformed into the values for these keys.

A Record List containing these 3 records... Would be converted to a Record containing these 3 keys...

Key Value Key Value

pName cx_timeout cx_timeout 1000

pValue 1000 cx_max 2500

cx_min 10

pName cx_max

pValue 2500

pName cx_min

pValue 10

Package WmPublic


recordList IData [ ] The array of IData objects (i.e., a Record list) whose contents you want to transform into a single IData object (i.e., a single Record). Note: If recordList contains an IData instead of an IData[ ], recordListToRecord will do nothing.

name String The name of the element in recordList whose value will provide the name of each key in the resulting IData. Important! The data type of the element that you specify in name must be String.

value String The name of the element in recordList whose values will be



Input Variable Name Type Description assigned to the keys specified in name. This element can be of any data type.


record IData An IData object (i.e., a Record) containing the key/value pairs generated from recordList.

pub.record:recordToRecordList

Description Expand the contents of a Record into a list of Records. Each name/value pair in the target Record will become a new Record in a Record list with constant keys for name and value.

Package WmPublic


record Values Target Record to transform.

name String Constant name to use for the keys of the target Record.

value String Constant name to use for the values of the target Record.


recordList IData [ ] Resulting Record list, length equal to the number of fields in the input Record. Each of its Records will have two fields (name and value).

pub.record:recordToXMLValues

Description Convert a Record in the pipeline to a String by encoding it as SAP BC XMLValues format. To decode the String back into a Record, use pub.record:XMLValuesToRecord.

Package WmPublic


record Values Target Record to convert. This Record can contain any number of other fields, lists, and other Records.


xmlvalues String XML document containing encoded representation of input Record. The XML format is SAP BC XMLValues. No other formats can be generated.

pub.record:XMLValuesToRecord


pub.record:XMLValuesToRecord

Description Convert a String containing XMLValues to a Record by decoding the SAP BC XMLValues format.

Package WmPublic


xmlvalues String XML document containing encoded representation of a Record. The XML format is SAP BC XMLValues. No other formats will be accepted.


record IData [ ] Record resulting from the decoding of xmlvalues.


Chapter 17 Remote Services

You use remote services to invoke services on remote SAP BC servers.

You can also use remote services for guaranteed delivery transactions. For more information about guaranteed delivery transactions, see the SAP BC Developer Guide and the SAP BC Administration Guide.

17

C H A P T E R 1 7 R e m o t e S e r v i c e s




Service Function pub.remote:invoke Invokes a service on a remote SAP BC server.

pub.remote.gd:end Ends a guaranteed delivery transaction.

pub.remote.gd:getStatus Returns the status of the guaranteed delivery transaction.

pub.remote.gd:invoke Invokes the service for a guaranteed delivery transaction by making a synchronous call to a remote SAP BC server.

pub.remote.gd:restart Restart an expired guaranteed delivery transaction

pub.remote.gd:retrieve Retrieves the results of a guaranteed delivery transaction submitted asynchronously or synchronously to a remote SAP BC server.

pub.remote.gd:start Starts a guaranteed delivery transaction.

pub.remote.gd:send Makes a guaranteed one-way call (fire-and-forget) to the SAP BC server to invoke a service for which no output is needed or expected. The service than automatically ends the transaction when it successfully completes.

pub.remote.gd:submit Invokes a service for a guaranteed delivery transaction by making an asynchronous call to a remote SAP BC server.

pub.remote:invoke


pub.remote:invoke

Description Invokes a service on a remote SAP BC server. The remote server is identified by an alias, which is configured on the Remote Servers tab in the SAP BC Administrator. Connection and authentication to the remote server is managed transparently to the caller of this service. All current pipeline inputs are passed to the remote service. To improve performance and minimize the amount of data sent over the wire, scope the pipeline to a separate Record or drop unneeded fields before invoking this service. The same advice applies to the output values of the remote service, because all values returned from the service are sent over the wire in response to the caller.

Package WmPublic


$alias String Name of the target server on which to invoke the specified service. This name and its associated connection attributes are defined on the Create Remote Server Alias screen in the SAP BC Administrator. Note: The alias could be protected by an Access Control List. If so, the user invoking pub.remote:invoke must be a member of this list or the invocation will fail.

$service String Fully-qualified name of the service to invoke on the remote server. The fully qualified service name includes the folder name and uses the format folderName.folderName:serviceName. Example wm.server:ping

$scope String Specifies how the session to the remote server should be managed.

Set to… To…

SESSION Default. Store the remote session in the current user session. Further calls by the same user to pub.remote:invoke for the same server alias re-use the existing remote session with the server. Stateful interactions with the remote server are maintained and protected inside the current user’s session. When the current user disconnects or expires, the remote session expires, or the local server is shutdown, the remote session is automatically disconnected.

GLOBAL Store the remote session in a shared pool of sessions. If another user invokes a service on the same remote server with GLOBAL scope, the session will be re-used. Stateful interactions with the remote server could be destroyed by other users’ invocations. When the remote session expires due to inactivity or the local server is shut down, the remote session is automatically disconnected.



Output The fields returned by the remote server’s invocation of the specified service.

Usage Notes If pub.remote:invoke does not receive a response within the timeout period specified in the server’s watt.net.timeout parameter, it will throw an exception. For information about the watt.net.timeout parameter, see the SAP BC Administration Guide.

pub.remote.gd:end

Description Ends a guaranteed delivery transaction.

Package WmPublic


tid String Transaction ID of the transaction you want to end.

Output None.

Usage Notes This service is used to eliminate a guaranteed delivery transaction from the jobstore.

pub.remote.gd:getStatus

Description Returns the status of the guaranteed delivery transaction.

Package WmPublic


tid String Transaction identification number.


status String Current status of the transaction. status can have one of the following values :

This status… Indicates…

NEW The transaction is new. PENDING The transaction is pending. DONE The transaction completed. FAILED The transaction expired because the time-

to-live or the retry limit has been exceeded. UNKNOWN The transaction identification number in tid

is not recognized.

Usage Notes Use the pub.remote.gd:restart service to restart a FAILED (expired) guaranteed delivery transaction.

pub.remote.gd:invoke


pub.remote.gd:invoke

Description Invokes the service for a guaranteed delivery transaction by making a synchronous call to a remote SAP BC server.

Package WmPublic


service String Service to be run on the remote SAP BC server

tid String Transaction identification number for the service.

inputs IData Optional. An IData object containing the inputs for the service.


results IData IData object containing the results of the service

Usage Notes To use an asynchronous call to the server to invoke a service for a guaranteed delivery transaction, use the pub.remote.gd:submit service.

pub.remote.gd:restart

Description Restart an expired guaranteed delivery transaction

Package WmPublic


tid String Transaction identification number for the guaranteed delivery transaction you want to restart.

Output None.

Usage Notes If a guaranteed delivery transaction failed because of server or network failure, use this service to restart the traction without resubmitting the transaction.

pub.remote.gd:retrieve

Description Retrieves the results of a guaranteed delivery transaction submitted asynchronously or synchronously to a remote SAP BC server.

Package WmPublic



block String Optional. Specify whether to block or poll for the results of the transaction. This service may be used in blocking or polling modes.

Set block to… To… true Default. Wait until the invoked service completes

before retrieving results. This is also known as blocking mode.

false Retrieve the results immediately, whether or not the invoked service is completed. This is also known as polling mode.




results IData IData object containing the results of the service in the guaranteed delivery transaction.

Usage Notes If block is false, and the results of the transaction are still pending when this service executes, the results are returned as null.

pub.remote.gd:start

Description Starts a guaranteed delivery transaction.

Package WmPublic


alias String Name of the SAP BC server on which you want to invoke a Guaranteed Delivery transaction. This name and its associated connection attributes are defined on the Remote Servers tab of the SAP BC Administrator.

retries String Optional. Maximum number of times to retry the transaction. Specify 0 to indicate no retry limit. Default value is 0

ttl String Optional. The transaction time-to-live measured in minutes. The transaction expires when ttl is exceeded. Default equals the value set in the watt.tx.defaultTTLMins property or, if the property is not set, 30 minutes.

followtid String Optional. Identification number of the transaction you want this Guaranteed Delivery transaction to follow. The current transaction executes only after the transaction indicated by followtid completes.



pub.remote.gd:send


pub.remote.gd:send

Description Makes a guaranteed one-way call (fire-and-forget) to the SAP BC server to invoke a service for which no output is needed or expected. The service than automatically ends the transaction when it successfully completes.

Package WmPublic


service String Service to be run on the remote SAP BC server.



Output None.

Usage Notes The results of service cannot be retrieved unless the invoked service returns an exception. Use the pub.remote.gd:send service to invoke a service remotely only if you want to run a guaranteed delivery transaction and are not concerned about the results of the invoked service. You do not need to use the pub.remote.gd:end service to end the transaction performed by this service..

pub.remote.gd:submit

Description Invokes a service for a guaranteed delivery transaction by making an asynchronous call to a remote SAP BC server.

Package WmPublic


service String Service to be run on the remote SAP BC server



Usage Notes To remove the transaction from the remote SAP BC server, use the pub.remote.gd:end service. To use a synchronous call to invoke the service, use the pub.remote.gd:invoke service.


Chapter 18 Replicator Services

Use the replicator services to create services that replicate packages across SAP BC servers. This folder contains services that you can use to push packages from your SAP BC servers to a subscriber's server. It also contains services that you can use to pull packages from a publisher's server to your SAP BC server.

18

C H A P T E R 1 8 R e p l i c a t o r S e r v i c e s




Service Function pub.replicator:addReleaseRegistryEntry Adds an entry to the SAP BC server's Package Release Registry.

pub.replicator:deleteReleaseRegistryEntry Deletes an entry from the SAP BC server’s package-release registry.

pub.replicator:distributeViaFTP Allows a publisher to send a package to a subscriber via FTP. —OR—

Allows a subscriber to retrieve a package from a publisher via FTP.

pub.replicator:distributeViaSvcPull Pulls a specified package release from a publisher's server.

pub.replicator:distributeViaSvcPush Pushes a package from your server to a list of subscriber's (other SAP BC servers).

pub.replicator:generateReplicationEvent Generates a replication event.

pub.replicator:getLocalReleasedList Return all entries in your SAP BC server’s Package Release Registry.

pub.replicator:getRemoteReleasedList Queries the publisher for released packages.

pub.replicator:notifyPackageRelease Sends an e-mail message to subscribers who have said that they want to be notified when a new release becomes available.

pub.replicator:packageCreation Creates a distribution file (a zip file) for the package.

pub.replicator:addReleaseRegistryEntry


pub.replicator:addReleaseRegistryEntry

Description Adds an entry to the SAP BC server's Package Release Registry.

Package WmPublic


package String The name of the package.

name String The name of the release. This name could be different from the name of the package.

version String The version number of the release. Format is #.# or #.#.# (e.g. 1.2, 1.2.1).

build String Optional. The build number of the release (e.g., 12, 530).

patchNums String Optional. One or more comma-separated patch numbers included in this release.

JVMVersion String The minimum JVM version number that this release requires

description String Optional. Brief description of this release. You may want to use this parameter to summarize the nature and purpose of the release.


packages IData[ ] All entries in the Server’s Package Release Registry.


name String The name of the release.


build String The build number of the release. (e.g. 12, 530).

patch_nums String A comma-separated list of patch numbers included in this release.

time String The time when the package was released.

jvm_version String The minimum JVM version number that the release requires.

description String Brief description of this release.

source_server_version String The version number of SAP BC that released the package.



pub.replicator:deleteReleaseRegistryEntry

Description Deletes an entry from the SAP BC server’s package-release registry.

Package WmPublic


packageName String The name of the release that you want to delete.


packages IData[ ] All entries in the Server’s package-release registry.



version String The version number of the release. Format is #.# or #.#.# (e.g., 1.2, 1.2.1).

build String The build number of the release (e.g., 12, 530).

patch_nums String A comma-separated list of patch numbers included in this release.

time String Time when the package was released.


description String Brief description of the release.

source_server_version String The version number of SAP BC that released the package.

pub.replicator:distributeViaFTP

Description Allows a publisher to send a package to a subscriber via FTP. —OR— Allows a subscriber to retrieve a package from a publisher via FTP.

Package WmPublic


packageName String The name of the released package.

action String Specifies whether you want to send (put) a package to another SAP BC server, or whether you want to retrieve (get) a package from another SAP BC.

Set variableName to… To… get Default. Retrieve a package from the

publisher's server. put Send a package to a subscriber's server.

serverhost String Host name or IP address of the remote SAP BC.

serverport String Number of the FTP port on the remote SAP BC.

pub.replicator:distributeViaSvcPull



username String User name that your server will use to log on to the remote SAP BC.

password String Password that your server will use to logo on to the remote SAP BC.

pub.replicator:distributeViaSvcPull

Description Pulls a specified package release from a publisher's server.

Package WmPublic


packageName String The name of the release.

publisher String The alias of the publisher's server.

pub.replicator:distributeViaSvcPush

Description Pushes a package from your server to a list of subscriber's (other SAP BC servers).

Package WmPublic



subscriber String[ ] A list of the subscriber's host names or IP addresses.

pub.replicator:generateReplicationEvent

Description Generates a replication event. You might invoke this service in conjunction with other services to make the package replication process generate an event. The replication event handler would listen for this event and perform some prescribed action that you have specified.

Package WmPublic


packageName String The name of the package.

action String Optional. User-defined string that describes the replication event, such as “pulled” or “pushed.”



pub.replicator:getLocalReleasedList

Description Return all entries in your SAP BC server’s Package Release Registry.

Package WmPublic


packages IData[ ] All entries in the Server’s Package Release Registry.




build String The build number of the release. (e.g. 12, 530).

patch_nums String A comma-separated list of the patch numbers included in this release.

time String The time when the package is released.



source_server_version String The version number of SAP BC server that released the package.

pub.replicator:getRemoteReleasedList

Description Queries the publisher for released packages. This service gets a list of released packages that your server subscribes to. You can use the list to find out if any new packages have been released or a newer version of a package has been released.

Package WmPublic


publisher String The alias of the publisher's server.


packages IData[ ] A list of released packages on the publishing server that you subscribe to.



version String The version number of the release. Format is #.# or #.#.# (e.g., 1.2, 1.2.1).

build String The build number of the release. (e.g., 12, 530).

patch_nums String A comma-separated list of the patch numbers included in this release.

pub.replicator:notifyPackageRelease



time String The time when the package was released.



source_server_version String The version number of SAP BC server that released the package.

pub.replicator:notifyPackageRelease

Description Sends an e-mail message to subscribers who have said that they want to be notified when a new release becomes available.

Package WmPublic



pub.replicator:packageCreation

Description Creates a distribution file (a zip file) for the package.

Package WmPublic


package String The name of the package.



build String Optional. The build number of the release (e.g. 12, 530).

patchNums String Optional. A comma-separated list of patch numbers included in the release.

targetPkgVersion String The version number of the target package. This field will be checked when the subscriber installs this package over an existing package, and will prevent it from overwriting an existing higher version of package.

targetServerVersion String The version of number of the SAP BC server that this release requires.

JVMVersion String The minimum JVM version number that this release requires.

description String Brief description of this release. You might use this parameter to summarize the nature and purpose of the release.

type String The type of the release.

Set variableName to… If release contains a…

full Default. Full package. partial Patch or an update for the package.




filter String Flag that specifies whether all files are included in the release or, if not all files are included, whether the fileList specifies the list of files to be included or excluded from the distribution file.

Set variableName to… To…

includeall Default. Include all the files in the distribution file.

include Include selected files in the distribution file. exclude Include all except selected files in the

distribution file.

fileList String[ ] A list of file names that will be included or excluded from the distribution file, depending on the value of filter.

fileNamePattern String A pattern string that specifies the names of files to be included in the distribution file. The asterisk (*) is the only wildcard character allowed in a pattern string. All other characters are treated literally (e.g., *.java, *.dsp).

filesToDeleteList String[] A list of files to be deleted before package creation.


Chapter 19 Report Services

Report services allow you to apply an output template to a Values object. Each service requires an output template and a Values object. They can be used in order to generate any type of dynamic XML, EDI, or HTML document.

19

C H A P T E R 1 9 R e p o r t S e r v i c e s




Service Function pub.report:runFileTemplate This service applies a template that is available in a File object on a specified Values

object.

pub.report:runFileTemplateOnPipe This service is a replica of the pub.report:runFileTemplate, only the Values object to bind against is the input Values object to the service (the Pipeline).

pub.report:runStringTemplate This service provides added flexibility by allowing you to use a template from a String object. The template does not have to be known and saved to file before hand.

pub.report:runStringTemplateOnPipe This service applies an output template that is available as a String object to a specified Values object.

pub.report:runTemplate Generates dynamic text by binding an output template to a Values object. The output template is located by its file name and the package where is resides on the server. The Values object is passed as input to the service.

pub.report:runTemplateOnPipe This service is a replica of pub.report:runTemplate, only the Values object to bind against is the input Values object to the service (the Pipeline).

pub.report:runFileTemplate


pub.report:runFileTemplate

Description This service applies an output template available in a File object to a specified Values object.

Package WmPublic


$template File A File object (java.io.File) which points to a physical template file.

$values Values Values object to bind against the template.

resultEncoding String Encoding to use for the resulting string.


$txt String The resulting string from applying the template.

Usage Notes If a template is not available in a templates directory of any of the packages on the server, you can use this service by passing in a File object representing the template.

pub.report:runFileTemplateOnPipe

Description This service is a replica of the pub.report:runFileTemplate, only the Values object to bind against is the input Values object to the service (the Pipeline).

Package WmPublic


$template File A File object (java.io.File) which points to a physical template file.




Usage Notes If a template is not available in a templates directory of any of the packages on the server you can use this service by passing in a File object representing the template.

pub.report:runStringTemplate

Description This service applies an output template that is available as a String object to a specified Values object.

Package WmPublic


$template String String object containing the template to be used.

$values Values Values object to bind against the template.




Usage Notes This service is typically invoked from other services that already have a template in a String object and a Values object that will be used to bind against the template.

C H A P T E R 1 9 R e p o r t S e r v i c e s


pub.report:runStringTemplateOnPipe

Description This service is a replica of pub.report:runStringTemplate, only the Values object to bind against is the input Values object to the service (the Pipeline).

Package WmPublic


$template String The String object containing the template to be used.




Usage Notes This service is typically invoked from other services that already have a template in a String object and need the template to bind against the Pipeline.

pub.report:runTemplate

Description This service applies an output template that is saved in the SAP BC namespace to a specified Values object. The output template is located by its file name and the package where is resides on the server.

Package WmPublic


$template String The filename for a template, e.g., mytemp.html or mytemp.xml.

$package String The package where the template is, e.g., “Default”.

$values Values The values object to bind against the template.




Usage Notes To apply a template that resides in <sapbc>\server\packages\Default\templates\mytemp.xml, invoke the service with the following values.

$template: mytemp.xml $package: Default $values: Make sure that the Values object you want to bind against is pointed to by this key.

pub.report:runTemplateOnPipe

Description This service is a replica of pub.report:runTemplate, only the Values object to bind against is the input Values object to the service (the Pipeline).

Package WmPublic


$template String The filename for a template, e.g., mytemp.html or mytemp.xml.

$package String The package where the template is, e.g., “Default”.


pub.report:runTemplateOnPipe




Usage Notes To apply a template that resides in <sapbc>\server\packages\Default\templates\mytemp.xml, invoke the service with the following values. $template: mytemp.xml $package: Default


Chapter 20 Scheduler Services

You use the scheduler services to schedule services to execute at the times you specify. Services that you schedule are referred to as user tasks or just tasks. The Scheduler feature on the SAP BC server handles executions of the tasks.

20

C H A P T E R 2 0 S c h e d u l e r S e r v i c e s




Service Function pub.scheduler:addComplexTask Adds a complex task to the Scheduler. The SAP BC server runs the service for a

complex task on the day(s) and time(s) that you specify either during a specified date range or indefinitely.

pub.scheduler:addOnetimeTask Adds a task that runs only once, to the Scheduler. The SAP BC server executes the service a single time on the date and time you specify.

pub.scheduler:addRepeatingTask Adds a recurring task to the Scheduler. The SAP BC server continually executes a repeating task at the interval you specify.

pub.scheduler:cancelTask Removes a task from the Scheduler.

pub.scheduler:getTaskIDs Retrieves a list of identification numbers for of all tasks currently in the Scheduler.

pub.scheduler:getTaskInfo Retrieves information about a task on the Scheduler.

pub.scheduler:resumeTask Resumes a suspended task.

pub.scheduler:suspendTask Suspends a task on the Scheduler.

pub.scheduler:updateComplexTask Updates a complex task on the Scheduler. The SAP BC server runs the service for a complex task on the day(s) and time(s) that you specify either during a specified date range or indefinitely.

pub.scheduler:updateOneTimeTask Updates a one-time task on the Scheduler.

pub.scheduler:updateRepeatingTask Updates a repeating task to the Scheduler.

pub.scheduler:addComplexTask


pub.scheduler:addComplexTask

Description Adds a complex task to the Scheduler. The SAP BC server runs the service for a complex task on the day(s) and time(s) that you specify either during a specified date range or indefinitely.

Package WmPublic


service String Name of the service you want to schedule for execution on the server.

persistJob String Optional. Indicates whether you want to the task to persist after the server is restarted. Set this variable to true if you want the task to persist after restart of the server. Default is false

runInCluster String Optional. Indicates whether you want the task to run in a clustered environment. Set this variable to true if you want the task to run in a clustered environment. Default is false

runAsUser String Optional. Invoke the service using the access rights of the specified user. If you do not specify a user name, the access rights of the Default user.

inputs IData Optional. An IData object that can be sent as input to the scheduled service.

startTime String Optional. Time at which the task is scheduled to start. The time should be in HH:MM:SS format. If you do not specify a startTime, the current time is used.

startDate String Optional. Date on which the task is scheduled to start. The date should be in the YYYY/MM/DD format. If you do not specify a startDate, the current date is used.

endTime String Optional. Time at which the task expires. The time should be in HH:MM:SS format. If you do not specify an endTime, the server uses 00:00:00 (midnight).

endDate String Optional. Date on which the task expires. Thee date should be in the YYYY/MM/DD format. If you do not specify an endDate, the server executes this service for an indefinite period of time.

months String [ ] Optional. Months during which the task is scheduled to run. Months are represented by integers between 1 and 12., where ‘1’ indicates January and ‘12’ indicates December. If you do not specify months, the task will run every month.

hours String [ ] Optional. Hours at which the task is scheduled to run. Hours are represented by integers between 0 and 23. If you do not specify hours the task runs every hour.

minutes String [ ] Optional. Minutes at which the task is scheduled to run. Minutes are represented by integers between 0 and 59. If you do not specify minutes, the task runs every minute.




daysOfMonth String [ ] Optional. Days of the month on which the task is scheduled to run. Days are represented by integers between 1 and 31. If you do not specify daysOfMonth, the task runs every day of the month.

daysOfWeek String [ ] Optional. Days of the week on which the task is scheduled to run. Days are represented by integers between 1 and 7, where ‘1’ indicates Sunday and ‘7’ indicates Saturday. If you do not specify daysOfWeek, the task runs every day of the week.


taskID String Identification number of the task added to the scheduler

type String Indicates the type of task added. The value of type is complex.

taskAdded String Indicates if the task was successfully added to the Scheduler. If the value of taskAdded is true, the task was successfully added to the Scheduler. If the value of taskAdded is false, the task was not added to the Scheduler.

pub.scheduler:addOnetimeTask

Description Adds a task that runs only once, to the Scheduler. The SAP BC server executes the service a single time on the date and time you specify.

Package WmPublic



persistJob String Optional. Indicates whether you want to the server to maintain the scheduled task in the event that the server is restarted before the task completely executes. Set this variable to true if you want the task to persist after restart of the server. Default is false




date String Date on which to run the task, in YYYY/MM/DD format. If you do not specify date, the current date is used.

time String Time at which to run the service, in HH:MM:SS format. If you do not specify time, the current time is used.

pub.scheduler:addRepeatingTask



taskID String Identification number of the task added to the scheduler

type String Indicates the type of task added. The value of type is once.


pub.scheduler:addRepeatingTask

Description Adds a recurring task to the Scheduler. The SAP BC server continually executes a repeating task at the interval you specify.

Package WmPublic



persistJob String Optional. Indicates whether you want to the task to persist after the server is restarted. Set this variable to true if you want the task to persist after restart of the server. Default is false.

runInCluster String Optional. Indicates whether you want the task to run in a clustered environment. Set this variable to true if you want the task to run in a clustered environment. Default is false.



interval String Time interval (measured in seconds) between executions of the task.

doNotOverlap String Optional. Indicates whether or not you want executions of this task to overlap.

Set doNotOverlap to… To… true Prevent executions of the scheduled task

from overlapping. After a scheduled task finishes executing, the Scheduler waits the number of seconds specified in interval before running the task again.

false Default. Allow executions of the scheduled task to overlap. The Scheduler runs the task every time the value of interval elapses.




taskID String Identification number of the task added to the Scheduler

type String Indicates the type of task added. The value of type is repeat.


pub.scheduler:cancelTask

Description Removes a task from the Scheduler.

Package WmPublic


taskID String Identification number of the task to remove from the Scheduler.


taskCancelled String Indicates whether the task was removed from the scheduler. If the value is true, if the task was successfully removed. If the value is false, the task has not been removed.

Usage Notes For information about the tasks on the Scheduler, run the pub.scheduler:getTaskIDs and pub.scheduler:getTaskInfo services.

pub.scheduler:getTaskIDs

Description Retrieves a list of identification numbers for of all tasks currently in the Scheduler.

Package WmPublic

Input None.


taskIDs String [ ] List containing the taskID for each task on the Scheduler.

pub.scheduler:getTaskInfo

Description Retrieves information about a task on the Scheduler.

Package WmPublic


taskID String Task identification number.


type String Indicates the type of task. Can be one of the following: complex once repeat

service String Name of the service run by the task.

runAsUser String Indicates the user name whose access rights are used to invoke the service.

pub.scheduler:getTaskInfo



runInCluster String Indicates whether or not the task runs in a clustered environment. If runInCluster is… Then… true The task runs in a clustered environment. false The task does not run in a clustered

environment.

persistJob String Indicates whether the task persists after the server on which the task is running is restarted.

If persistJob is… Then…

true The task persists after the server is restarted.

false The task does not persist after the server is restarted.

complexTaskInfo IData A Record containing information about the task represented by taskID. This variable only appears in output if type is complex.


startTime String Time at which the task is scheduled to start, in HH:MM:SS format.

startDate String Date on which the task is scheduled to start, in YYYY/MM/DD format.

endTime String Time at which the task expires, in HH:MM:SS format.

endDate String Date on which the task expires, in YYYY/MM/DD format.

months String [ ] Months during which the task is scheduled to run. Months are represented by integers between 1 and 12., where ‘1’ indicates January and ‘12’ indicates December.

hours String [ ] Hours when the task is scheduled to run. Hours are represented by integers between 0 and 23. If you do not specify hours the task runs every hour.

minutes String [ ] Minutes at which the task is scheduled to run. Minutes are represented by integers between 0 and 59. If you do not specify minutes, the task runs every minute.

daysOfMonth String [ ] Days of the month on which the task is scheduled to run. Days are represented by integers between 1 and 31. If you do not specify daysOfMonth, the task runs every day of the month.

daysOfWeek String [ ] Days of the week on which the task is scheduled to run. Days are represented



Key Type Description by integers between 1 and 7, where ‘1’ indicates Sunday and ‘7’ indicates Saturday. If you do not specify daysOfWeek, the task runs every day of the week.

oneTimeTaskInfo IData A Record containing information about the complex task represented by taskID. This variable only appears in output if type is once.

Variable Name Type Description date String Date on which to run the task, in

YYYY/MM/DD format. time String Time at which to run the service, in

HH:MM:SS format.

repeatingTaskInfo IData A Record containing information about the task represented by taskID. This variable only appears in output if type is repeat.

Variable Name Type Description interval String Time interval (measured in seconds)

between repetitions of the task. doNotOverlap String Optional. Indicates whether or not you

want recurrences of this task to overlap.

nextRun String Specifies the next date and time the task is scheduled to run. The value represents the number of milliseconds since January 1, 1970, 00:00:00 GMT to the next execution of the task.

inputs IData An IData object containing the inputs to the scheduled service.

execState String Current state of the task. Tasks can be in one of two states:

If execState is… Then…

running The task is currently active. suspended The task has been suspended.

pub.scheduler:resumeTask

Description Resumes a suspended task.

Package WmPublic


taskID String Identification number of the task to resume.


taskResumed String Indicates if the task was successfully resumed. If the value is true, the task was successfully resumed. If the value is false, the task was not successfully resumed.

pub.scheduler:suspendTask

Description Suspends a task on the Scheduler.

Package WmPublic

pub.scheduler:updateComplexTask



taskID String Identification number of the task to suspend.


taskSuspended String Indicates if the task was successfully suspended. If the value is true, the task was successfully suspended. If the value is false, the task was not successfully suspended.

Usage Notes If you want to cancel a task or remove a task from the scheduler, use the pub.scheduler:cancelTask service.

pub.scheduler:updateComplexTask

Description Updates a complex task on the Scheduler. The SAP BC server runs the service for a complex task on the day(s) and time(s) that you specify either during a specified date range or indefinitely.

Package WmPublic


taskID String Identification number of the task to be updated.






startTime String Optional. Time at which the task is scheduled to start, in HH:MM:SS format. If you do not specify a startTime, the current time is used.

startDate String Optional. Date on which the task is scheduled to start, in YYYY/MM/DD format. If you do not specify date, the current date is used.

endTime String Optional. Time at which the task expires, in HH:MM:SS format. If you do not specify an endTime, the server uses 00:00:00 (midnight).

endDate String Optional. Date on which the task expires, in YYYY/MM/DD format. If you do not specify an endDate, the server executes this service for an indefinite period of time.




months String [ ] Optional. Months during which the task is scheduled to run. Months are represented by integers between 1 and 12., where ‘1’ indicates January and ‘12’ indicates December. If you do not specify months, the task will run every month.

hours String [ ] Optional. Hours at which the task is scheduled to run. Hours are represented by integers between 0 and 23. If you do not specify hours the task runs every hour.

minutes String [ ] Optional. Minutes at which the task is scheduled to run. Minutes are represented by integers between 0 and 59. If you do not specify minutes, the task runs every minute.

daysOfMonth String [ ] Optional. Days of the month on which the task is scheduled to run. Days are represented by integers between 1 and 31. If you do not specify daysOfMonth, the task runs every day of the month.

daysOfWeek String [ ] Optional. Days of the week on which the task is scheduled to run. Days are represented by integers between 1 and 7, where ‘1’ indicates Sunday and ‘7’ indicates Saturday. If you do not specify daysOfWeek, the task runs every day of the week.


taskUpdated String Indicates whether or not the task was successfully updated. A value of true indicates the task was successfully updated. A value of false indicates the task was not successfully updated.

type String Indicates the type of task updated. The value of type is complex.

Usage Notes You can use pub.scheduler:getTaskIDs and pub.scheduler:getTaskInfo services to get information about the task you want to update. Unlike the services pub.scheduler:updateOneTimeTask and pub.scheduler:updateRepeatingTask, this service updates all the fields in the task by default—all the parameter values you specified when you created or last updated the task are overwritten (except values for taskID and type). Using this service to update a task is similar to creating a new complex task with the original taskID and type.

pub.scheduler:updateOneTimeTask


pub.scheduler:updateOneTimeTask

Description Updates a one-time task on the Scheduler.

Package WmPublic



service String Optional. Name of the service to be scheduled.





date String Date on which to run the task, in YYYY/MM/DD format. If you do not specify date, the current date is used.

time String Time at which to run the service, in HH:MM:SS format. If you do not specify time, the current time is used.



type String Indicates the type of task updated. The value of type is once.

Usage Notes Unlike the pub.scheduler.updateComplexTask service, this service does not overwrite all the original parameter values. This service only updates the parameters for which you specify new values.

pub.scheduler:updateRepeatingTask

Description Updates a repeating task to the Scheduler.

Package WmPublic



service String Optional. Name of the service run by the task.








interval String Time interval (measured in seconds) between repetitions of the task.

doNotOverlap String Optional. Indicates whether or not you want recurrences of this task to overlap.

Set doNotOverlap to… To… true Prevent executions of the scheduled task

from overlapping. After a scheduled task finishes executing, the Scheduler waits the number of seconds specified in interval before running the task again.

false Default. Allow executions of the scheduled task to overlap. The Scheduler runs the task every time the value of interval elapses.



type String Indicates the type of task updated. The value of type is repeat.

Usage Notes Unlike the pub.scheduler.updateComplexTask service, this service does not overwrite all the original parameter values. This service only updates the parameters for which you specify new values.


Chapter 21 Schema Services

You can use schema services to validate objects and to validate the pipeline.

21

C H A P T E R 2 1 S c h e m a S e r v i c e s




Service Function pub.schema:createXSD Creates an XML Schema definition from a Record, a service or a specification.

pub.schema:validate Values or Node object to be validated.

pub.schema:validatePipeline Validates the pipeline against a saved record definition.

pub.schema.w3c:datatypes A schema containing all of the built-in datatypes for XML Schemas as defined in the W3C specification XML Schema Part 2: Datatypes.

pub.schema.w3c:xml A schema containing the XML Namespace components, such as xml:lang, xml:space, as defined in the W3C specifications Namespaces in XML and Extensible Markup Language (XML) 1.0.

pub.schema:createXSD


pub.schema:createXSD

Description Creates an XML Schema definition from a Record, a service or a specification.

Package WmPublic


name String A String specifying the fully qualified name of a Record, service or specification.


isSuccessful String A String indicating whether the schema definition was created successfully.

Value Description

true The schema definition was created successfully. false The schema definition was not created successfully. See

errors for detailed information.

xsd Record A Record (an IData object) containing the schema definition. xsd has the following keys:

Key Description

url A String specifying the absolute url of the generated schema.

source A String containing the schema definition.

import-xsd Conditional. A Record containing an independent schema definition.

include-xsd Conditional. A Record containing an independent schema definition.

redefine-xsd Conditional. A Record containing an independent XML Schema definition.

import-dtd Conditional. A Record containing a Document Type Description (DTD) with xml namespace information.

Key Description

url A String specifying the absolute url of the DTD.

source A String containing the DTD. errors IData[] A List of errors which occurred during xsd creation. warnings IData[] A List of warnings which occurred during xsd creation.

pub.schema:validate

Description Validates an object using a Record or a schema.

Package WmPublic


object Object Values or Node object to be validated.




conformsTo String The fully-qualified name of the Record (if the object is of type Values) or schema (if the object is of type Node) that you want to validate against. Example rosettaNet.schema:record_PurchaseOrder

Note: The nominated (specified) schema is used only for validating element nodes with ‘Names’ that are not from XML Namespaces (i.e., nodes with XML Namespace URI = null).

maxErrors String Optional. Number of errors to be collected. Default value is 1. When the number of errors found is equal to maxErrors, the validation processor stops validation and returns the result. If maxErrors = -1, the validation processor returns all errors.

ignoreContent String Optional. String that specifies whether the validation processor will validate content (key values) of the type String, String List, or String Table.

Set to.. To.. true Ignore content. false Default. Validate content.

failIfInvalid String Optional. String that indicates whether the service will fail if the object is invalid. If any errors are encountered, the service throws an exception.

Set to.. To.. true Indicate service fails. false Default. Indicate service success and return errors to the

pipeline.


isValid String String indicating the validation result. Value Description true Validation is successful. false Validation is unsuccessful. errors IData [ ] IData [ ] specifying any errors found during validation.

Key Description pathName A String containing the location of the error in

XQL. errorCode A String containing the error code (e.g., VV-001).

errorMessage A String containing the error message (e.g., “Missing Object”).

pub.schema:validatePipeline


pub.schema:validatePipeline

Description Validates the pipeline using a Record.

Package WmPublic


conformsTo String The fully-qualified name of the saved Record that you want to validate against. Example rosettaNet.schema:record_PurchaseOrder

maxErrors String Optional. Number of errors to be collected. Default value is 1. When the number of errors found is equal to maxErrors, the validation processor stops validation and returns the result. If maxErrors = -1, the validation processor returns all errors.

ignoreContent String Optional. String that specifies whether the validation processor will validate content (key values) of the type String, String List, or String Table.

Set to.. To.. true Ignore content. false Default. Validate content.

failIfInvalid String Optional. String that indicates whether the service will fail if the object is invalid. If any errors are encountered, the service throws an exception.

Set to.. To.. true Indicate service fails. false Default. Indicate service success and return

errors to the pipeline.


isValid String String indicating the validation result. Value Description true Validation is successful. false Validation is unsuccessful.

errors IData [ ] IData [ ] specifying any errors found during validation.

Key Description pathName A String containing the location of the error

in XQL. errorCode A String containing the error code (e.g.,

VV-001).

errorMessage A String containing the error message (e.g., “Missing Object”).



pub.schema.w3c:datatypes

Description A schema containing all of the built-in datatypes for XML Schemas as defined in the W3C specification XML Schema Part 2: Datatypes. For more information about schemas and datatypes, see the SAP BC Developer Guide.

Package WmPublic

pub.schema.w3c:xml

Description A schema containing the XML Namespace components, such as xml:lang, xml:space, as defined in the W3C specifications Namespaces in XML and Extensible Markup Language (XML) 1.0.

Package WmPublic


Chapter 22 Security Services

You can use security services to control which client certificates are sent to other services and to digitally sign data and process digital signatures.

The pub.security:setKeyAndChain and pub.security:clearKeyAndChain services are used to control which client certificate the SAP BC server presents to remote servers. You need to use these services to switch between certificates and certificate chains if you are not using aliases for remote servers. For more information about aliases for remote servers, see the SAP BC Administration Guide.

22

C H A P T E R 2 2 S e c u r i t y S e r v i c e s




Service Function pub.security:clearKeyAndChain Associates the default key and certificate chain with the subsequent set of

invoked services.

pub.security:setKeyAndChain Processes a digital signature to make sure that the provided data has not been modified. The signature input is the DER encoding of the PKCS#7 SignedData object.

pub.security.pkcs7:sign Creates a PKCS7 SignedData object.

pub.security.pkcs7:verify Processes a digital signature to make sure that the provided data has not been modified.

pub.security.util:createMessageDigest Generates a message digest for a given message.

pub.security.util:getCertificateInfo Retrieves information (e.g., serial number, issuer, expiration date) from a digital certificate.

pub.security.util:loadPKCS7CertChain Converts a certificate chain that is in PKCS7 format to a list (a one-dimensional array) of byte arrays.

pub.security.ssf:decrypt Decrypt data using a installed profile (certificate and private key)

pub.security.ssf:encrypt Encrypt data using a recipients certificate.

pub.security.ssf:getCertificateInfo Obtain information about a certificate/profile

pub.security.ssf:getLoadedProfiles Obtain a list of all imported profiles.

pub.security.ssf:getLoadedReciepients Obtain a list of all imported reciepients.

pub.security.ssf:importOwnProfile Import a profile into BC.

pub.security.ssf:importRecipientKey Import a recipients certificate

pub.security.ssf:removeProfile Remove an imported profile

pub.security.ssf:removeReciepient Remove an imported recipient.

pub.security.ssf:setDefaultProfile Set the default profile.

pub.security.ssf:setDefaultRecipient Set the default recipient.

pub.security:clearKeyAndChain


pub.security:clearKeyAndChain

Description Associates the default key and certificate chain with the subsequent set of invoked services.

Package WmPublic

Input None.

Output None.

Usage Notes The following scenario describes a situation in which you would use the pub.security:setKeyAndChain and pub.security:clearKeyAndChain services. Company A has a SAP BC server with one certificate chain. Company A wants to start trading with two new companies: Company B and Company C. Due to explicit business decisions both Company B and Company C require that secure requests to their servers use certificates issued by their company’s certificate authority. Company A now has three certificate sets that it must manage: one for connections to B, one for connections to C, and one for all other requests. Below is a high level process flow of what Company A would do if documents needed to be forwarded to companies B, C, and D (some arbitrary partner without the stringent security). Assume all network communication is done using HTTPS. Documents are sent to the companies in the following order: Company D, Company B, Company C, Company D. All data transfers make use of the pub.client:http service. Invoke pub.client:http to send data to Company D. Invoke pub.security:setKeyAndChain using the key and certificate chain for Company B. Invoke pub.client:http to send data to Company B. Invoke pub.security:setKeyAndChain using the key and certificate chain for Company C. Invoke pub.client:http to send data to Company C. Invoke pub.security:clearKeyAndChain to revert back to the default key and certificate chain for Company

A’s server. Invoke pub.client:http to send data to Company D.

pub.security:setKeyAndChain

Description Associates a key and certificate chain with the subsequent set of invoked services.

Package WmPublic


privKeyFile String Absolute or relative path of file containing private key.

certFiles String [ ] List of files containing the certificates that comprise the certificate chain. The list should start with the user’s certificate followed by (in order) intermediate certificates and finally the root CA certificate. Absolute or relative paths of the files can be specified.

Output None.

Usage Notes Use this service to associate a key and certificate chain that is different from the default settings. See the Usage Notes for pub.security:clearKeyAndChain for more information about using this service.

pub.security.pkcs7:sign

Description Creates a PKCS7 SignedData object. This service provides the capability for multiple entities to sign the



specified data. The data to digitally sign must be provided as a Java byte [ ]; otherwise an error will be generated. Each signerInfo block contained in the resulting signature contains two authenticated attributes: the content type, and a timestamp. For each signerInfo Record provided one of the following is required: a key alias that references a certificate chain and private key in the key store, or a certificate chain and private key. The signature operation will use MD5 for the message digest computation if no algorithm name is provided. The resulting signature is a Java byte[ ]. This is a DER-encoded representation of the SignedData object as specified in PKCS7.

Package WmPublic


signerInfo IData [ ] Information about a single signer of the signed data object.

Key Description

certChain A X509Certificate[ ] or an array of byte[ ]. The certificate chain of the signer. The subject that is performing the signature should be the first certificate in this chain, while the root Certifying Authority should be the last. It is expected that the key provided corresponds to the public key contained in the first certificate of the chain.

key An instance of Java.security.PrivateKey or byte[ ]. The private key that will be used to digitally sign the data. The private key can be any asymmetric encryption key that is supported by the SAP BC server; for example, DSA or RSA.

keyAlias A String specifying the alias of the certificate chain and private key in the key store. This key is not currently used.

hashAlgorithm A String specifying the algorithm to use when computing the digest of the provided data. This can currently be one of two values: SHA or MD5.

data byte[ ] The data to digitally sign. This is expected to be a byte[ ].

detachedSignature String Specifies whether the created PKCS#7 object should contain the data that is digitally signed. A detached signature does not include the data. If “true” a detached signature is created; otherwise the data to sign is included in the resulting signature object.


signature byte[ ] The resulting signature of the supplied data.

pub.security.pkcs7:verify


pub.security.pkcs7:verify

Description Processes a digital signature to make sure that the provided data has not been modified. The signature input is the DER encoding of the PKCS#7 SignedData object.

Package WmPublic


signature byte [ ] A byte array containing the signature that is to be used to determine whether the signed message is intact. If you are processing a detatched signature, pass the signature in signature. If you are processing an implicit signature, pass the entire signed message in signature.

data byte [ ] Optional. A byte array containing the message that was signed. If you are processing a detached signature, you must supply data. If you are processing an implicitly signed message, you do not need to supply data, because both the message and the signature reside in signature.

detachedSignature String Optional. A String specifying whether the message has a detached signature.

Value Description

true The message has a detached signature.

false Default. The message has an implicit signature.


signerInfo IData [ ] An array of IData objects, where each IData provides the following information about a single signer.


certChain Object[ ] A list (a one-dimensional array) of X.509 certificates representing the signer’s certificate chain. The chain will appear in hierarchical order, starting with the signer’s X.509 certificate in element 0.

timeStamp Object An instance of java.util.Date, indicating the time at which the signer signed the message.

trusted String A String indicating whether the certificate chain presented by the signer is trusted. Value of trusted will be one of the following: true – The chain is trusted. false – The chain is not trusted.




status String A String indicating whether the signatures were successfully verified. If successful, the value of status will be verified. If the signatures were not successfully verified, status will contain an error message.

content byte [ ] A byte array containing the message extracted from an implicit signature. (If you are verifying a detached signature, content is not returned.) Note: The extracted message is returned in content even if signature verification fails.

pub.security.util:createMessageDigest

Description Generates a message digest for a given message.

Package WmPublic


algorithm String A String that identifies the name of the algorithm that you want to use to compute the message digest. Must be either MD5 or SHA-1.

input byte[ ] A byte array containing the message for which you want the digest generated.


output byte[ ] A byte array containing the computed digest.

pub.security.util:getCertificateInfo

Description Retrieves information (e.g., serial number, issuer, expiration date) from a digital certificate.

Package WmPublic


certificate byte [ ] A byte array containing the certificate whose information you want to retrieve.


info IData A Record that contains the information from the certificate. Will contain the following fields:

Variable Name Description

version A String containing the X509 certificate version number.

serialNumber A String containing the serial number of the certificate.

signature A String containing the signature algorithm used by the issuer to sign this certificate.

pub.security.util:loadPKCS7CertChain


issuer A Record (an IData) containing detailed information (e.g., name, location, e-mail address) about the CA that signed the certificate.

validity A Record (an IData) containing the following fields, which describe the time period over which the certificate is valid: notBefore – A String that specifies the first

date on which this certificate is valid (e.g., 3/15/00 3:36PM).

notAfter – A String that specifies the last date on which this certificate is valid (e.g., 3/15/00 3:36PM).

subject A Record (an IData) containing detailed information (e.g., name, location, e-mail address) about the owner of the certificate.

subjectPublicKeyAlgorithm A String indicating the encryption algorithm that the certificate’s key is designed to be used with (e.g., RSA or DSA).

pub.security.util:loadPKCS7CertChain

Description Converts a certificate chain that is in PKCS7 format to a list (a one-dimensional array) of byte arrays.

Package WmPublic


certificateChain byte[ ] A byte array containing the certificate chain in PKCS7 format.




certificates byte [ ] [ ] A list (a one-dimensional array) of byte arrays, where each byte[ ] contains a certificate from certificateChain.

pub.security.ssf:decrypt

Description This Service decrypts data that has been encrypted with the public certificate of your profile. Note: only the owner of the private key contained in this profile is able to decrypt data that has been encrypted with the public key. So if you want to receive encrypted data from someone, you would send him the public certificate of your profile, and then the "decrypt" Service will be able to decrypt it using the private key of your profile. The inputs need to be set as follows:

o Exactly one of "inputStream" or "inputBytes" needs to be filled. If you have the encrypted data in form of a java.io.InputStream, assign this stream to "inputStream", if you have it in form of a byte array, assign the array to "inputBytes".

o "writeToOutputStream" can be set to "true" or "false". If set to "true", you must also fill the parameter "outputStream" with a java.io.OutputStream object. The decrypted data will then be written to that OutputStream and no output parameter "outputBytes" will be returned. If set to "false" (which is the default, if this parameter is left empty), the decrypted data will be returned in a byte array of name "outputBytes". Note: this behavior is independent of whether the input data is provided as a stream or as bytes.

o In the parameter "profileSubjectDN" you can specify the subject DN of the profile, whose private key ought to be used for the decryption process. This profile must have been imported prior to this with the Service "importOwnProfile". If this parameter is left empty, the private key of the default profile is used for decrypting. If no default profile has been set, an exception is thrown.

Package WmPublic


inputStream Object A stream containing the data to be decrypted. Either inputStream or inputBytges must be set.

inputBytes Object A byte array containing the data to be decrypted. Either inputStream or inputBytges must be set.

outputStream Object Optional. Stream to write the decrypted data to

writeToOutputStream String Optional. Flag indicating whether the result should be written to the output stream

profileSubjectDN String Designated name of the profile

pub.security.ssf:encrypt



outputBytes Object A byte array containing the decrypted string.

pub.security.ssf:encrypt

Description This Service encrypts any kind of binary data using the public certificate of the intended receiver. The encrypted data can only be decrypted again by the owner of the private key that matches the public key. The input parameters need to be set as follows:

o Exactly one of "inputStream" or "inputBytes" needs to be filled. If you have the input data in form of a java.io.InputStream, assign this stream to "inputStream", if you have it in form of a byte array, assign the array to "inputBytes".

o "writeToOutputStream" can be set to "true" or "false". If set to "true", you must also fill the parameter "outputStream" with a java.io.OutputStream object. The encrypted data will then be written to that OutputStream and no output parameter "outputBytes" will be returned. If set to "false" (which is the default, if this parameter is left empty), the encrypted data will be returned in a byte array of name "outputBytes". Note: this behavior is independent of whether the input data is provided as a stream or as bytes.

o In the parameter "algorithm" you may specify one of the standard encryption algorithms: AES128_CBS, DES_EDE3_CBS, MD5, RC2_40_CBS, RC2_CBS, SHA. If left empty, AES128_CBS is taken as default.

o The public certificate of the intended recipient can be specified in three ways: 1. Fill the parameter "recipientCertificateFile" with the filename of the certificate. 2. If "recipientCertificateFile" is left empty, the Service looks for the parameter "recipientSubjectDN". Here you can specify the subject DN of any of the certificates, that have been loaded with the Service "importRecipientKey". Note: This (or point 3.) is of course the preferred way, as reading the file once at Server startup is much better for the performance than reading it from the file system over and over again in each single invocation of "encrypt". 3. If "recipientSubjectDN" is left empty as well, then the default recipient is being used. If no default has been set either, an exception is thrown.

Package WmPublic


inputStream Object A stream containing the data to be decrypted. Either inputStream or inputBytges must be set.

inputBytes Object A byte array containing the data to be decrypted. Either inputStream or inputBytges must be set.

outputStream Object Optional. Stream to write the decrypted data to

writeToOutputStream String Optional. Flag indicating whether the result should be written to the output stream

algorithm String Algorithm to be used for encryption.

recipientCertificateFile String Filename of the certificate to use.

recipientCertificateDN String Designated Name of the certificate if it is imported to BC.


outputBytes Object A byte array containing the decrypted string.



pub.security.ssf:getCertificateInfo

Description This Service can be used to display detail information for a certain certificate, either the public certificate of one of your own profiles or the public certificate of one of your recipients. The ouput parameters contain the following fields:

o subjectDN : Subject Distinguished Name

o issuerDN : Distinguished Name of the authority that signed this certificate

o notBefore : Validity starts at

o notAfter : Validity ends at

o sigAlgName : Algorithm of signature (e.g. md5WithRSAEncryption)

o serialNumber: Serial number

o certType : Type of certificate (e.g. X.509)

o keyAlgorithm: Algorithm of key (e.g. RSA (2048 Bits))

o fileName : Name of the file, from which this certificate was loaded

The input parameter "recipientSubjectDN" has to be filled with the subjectDN of one of the imported recipient certificates. If left empty, the information for the current default recipient (if any) will be displayed. The information will be returned in the output record "recipientInfo". The input parameter "profileSubjectDN" has to be filled with the subject DN of the public certificate of one of the imported profiles. If left empty, the information for the current default profile (if any) will be displayed. The information will be returned in the output record "profileInfo". Both inputs can be used simultaneously. If one of the subject DNs does not exist, the corresponding "Info" record will simply not be returned (instead of throwing an error message).

Package WmPublic


profileSubjectDN String Designated name of the profile to get information for. Set this if you want to get information about any profile the server uses. These profiles have a private key installed.

recipientCertificateDN String Designated name of a certificate. Set this value if you want to get information about certificates of reciepients (customers for example) not having a private key installed.


reciepientInfo Record A record containing information about the certificate

profileInfo Record A record containing information about the profile

pub.security.ssf:getLoadedProfiles

Description This Service returns the subject DNs and the filenames of all currently loaded profiles in the output parameter "profileList". If a default profile has been set, the subject DN and filename of that will also be given in "defaultProfile". Note: if the profile has been imported from a PKCS#12 file, the name of that file is given. If it has been imported as a list of separate files, only the name of the public certificate is given.

Package WmPublic

pub.security.ssf:getLoadedReciepients


Input None


profileList Record[] List of profiles


subjectDN Designated name of the installed profile

filename Name of the file containing the profile

defaultProfile Record The default profile used.




pub.security.ssf:getLoadedReciepients

Description This Service returns the subject DNs and filenames of all currently loaded recipient certificates in the output parameter "recipientList". If a default recipient has been set, the subject DN and filename of that will also be given in "defaultRecipient".

Package WmPublic

Input None




reciepientList Record[] List of reciepients. Variable Name Description



defaultReciepient Record The default reciepient used.




pub.security.ssf:importOwnProfile

Description Before you do any encryption/decryption, you need to import one (or more) "profiles". A profile consists of your private key, an SSL certificate containing your public key and (optionally) the chain of intermediate certificates and CA root certificate, which signed your certificate. A profile can be imported in two different ways:

o If you have the certificates and the private key in a file that conforms to the PKCS#12 standard, simply fill the inputs "pkcs12File" and "pin" with the filename of the PKCS#12 file and the pin that protects the file, and then execute importOwnProfile. Note: You may use the tool sapgenpse (version 1.555.16 or higher) to generate a public/private key pair in PKCS#12 format. Note 662340 explains how to download sapgenpse (besides lots of other things that are not needed here). If you type sapgenpse -h, the syntax of the necessary commands will be explained. First use "gen_pse" to generate a key pair, and then use "export_p12" to convert it to PKCS#12. Note: Microsofts .pfx files are PKCS#12 compatible, too.

o If you have the certificates and the private key in separate files, fill the input "certificateChain" with the filenames of public certificate, intermediate certificate 1, ... , intermediate certificate n, CA root certificate (in that order) and the input "privateKeyFile" with the filename of the private key. The files should be in DER format. Again execute the Service.

Note: for security reasons all files should be kept in a directory, to which only the operating system user, that runs the Business Connector, has read access.

The Service returns the "Subject Distinguished Name" of the public certificate in the output parameter "subjectDN". This is the key, under which the other Services can access this profile from now on. You can import any number of profiles, but the usual situation is, that you have one and then send your public certificate to all communication partners, who want to transmit encrypted data to you.

The import of certificates needs to be done only once, so it is probably a good idea, to create a Flow Service that uses "importOwnProfile" and loads all profiles, and to define this Flow as a "Startup Service" for your Package. Then the profiles will be loaded once at BC startup, and the other Services can use them from then on. You will probably want to include calls to "importRecipientKey" and to the "setDefault..." Services as well.

Package WmPublic

pub.security.ssf:importRecipientKey



pkcs12File String File containing the certificate

pin String Pin to use for the private key

certificateChain String[] Chain of certificates used for signing this profile

privateKeyFile String Name of the file containing the private key.


subjectDN String Designated name of the profile.

pub.security.ssf:importRecipientKey

Description People, to whom you want to send encrypted data, will provide you with their public certificate. Save it to a secure directory, to which the Business Connector has read access, and then execute this Service with the filename of the public certificate as input. The Service returns the "Subject Distinguished Name" of the certificate. This is the key, under which the other Services can then use the certificate. You can import any number of certificates. The files should be in DER format.

Package WmPublic


reciepientCertificateFile String Name of the file containing the certificate to import.


subjectDN String Designated name of the certificate.

pub.security.ssf:removeProfile

Description One of the loaded profiles can be removed by calling this Service with the subject DN of the profile's public certificate. If this profile had been set as default, the default will be cleared, too.

Package WmPublic


subjectDN String Designated name of the profile to remove

Output None

pub.security.ssf:removeReciepient

Description One of the loaded recipient certificates can be removed by calling this Service with the corresponding subject DN. If this recipient had been set as default, the default will be cleared, too.

Package WmPublic


subjectDN String Designated name of the reciepient to remove



Output None

pub.security.ssf:setDefaultProfile

Description If you execute this Service with the subject DN of one of the imported profiles as input, the "decrypt" Service will from then on use this profile for decryption, whenever it is invoked with no explicit profile specified.

Package WmPublic


subjectDN String Designated name of the profile to use as default.

Output None

pub.security.ssf:setDefaultRecipient

Description If you execute this Service with the subject DN of one of the imported recipients as input, the "encrypt" Service will from then on use this recipient certificate for encryption, whenever it is invoked with no explicit recipient specified.

Package WmPublic


subjectDN String Designated name of the recipient to use as default.

Output None

pub.security.ssf:setDefaultRecipient



Chapter 23 SMIME Services

You use S/MIME services to create digitally signed and/or encrypt MIME messages. You also use the services in this folder to process signed and encrypted MIME messages that are passed into the pipeline.

23

C H A P T E R 2 3 S M I M E S e r v i c e s




Service Function pub.smime:createCertsOnlyData Generates a PKCS #7 certs-only S/MIME entity from an array of

certificates.

pub.smime:createEncryptedData Encrypts a MIME message.

pub.smime:createSignedData Digitally signs a MIME message.

pub.smime:createSignedAndEncryptedData Digitally signs a MIME message and then encrypts it.

pub.smime:getContentType For internal use only.

pub.smime:processCertsOnlyData Extracts the certificates from a PKCS #7 certs-only S/MIME entity.

pub.smime:processEncryptedData Decrypts an encrypted S/MIME message.

pub.smime:processSignedData Verifies the signature from a signed S/MIME entity and extracts the message from it.

pub.smime:createCertsOnlyData


pub.smime:createCertsOnlyData

Description Generates a PKCS #7 certs-only S/MIME entity from an array of certificates. This service can be used to develop mechanisms for transmitting certificates and certificate chains to other parties.

Package WmPublic

Variable Name Type Description Input certificates Object[ ] A list (a one-dimensional array) of byte arrays containing the

certificates that are to be encapsulated within the S/MIME entity.

Variable Name Type Description Output SMimeEnvStream InputStream An InputStream containing the S/MIME entity.

Usage Notes For general information about MIME messages and using the MIME services, service, see “Working with MIME and S/MIME Messages” in the SAP BC Developer Guide.

See Also ProcessCertsOnlyData

pub.smime:createEncryptedData

Description Encrypts a MIME message.

Package WmPublic


envStream InputStream InputStream containing the MIME message that you want to encrypt (e.g., the output produced by pub.mime:getEnvelopeStream).

recipientCerts Object[ ] A list (a one-dimensional array) of X.509 certificates of the recipients for whom this message will be encrypted, where each element in the list contains the certificate for a single recipient, in the form of a byte array. Note: When you have multiple recipients, createEncryptedData creates a single message that is encrypted for all recipients. It does not create a separate message for each recipient.

encryptionAlg String A String whose value specifies which encryption algorithm is to be used. Must be one of the following values:

TripleDES

DES

RC2

Default is TripleDES

keyLength String A String whose value specifies the length of the encryption key for RC2 encryption. Must be one of the following values

40

64

128

Default is 128. This parameter is ignored if encryptionAlg is not RC2.




SMimeEnvStream InputStream An InputStream containing the encrypted MIME message.


See Also CreateSignedData processEncryptedData pub.mime:getEnvelopeStream

Examples See the following in the WmSamples package. sample.smime:build_EncryptedSMime

pub.smime:createSignedAndEncryptedData

Description Digitally signs a MIME message and then encrypts it. Important! You must use this service when you want to create a message that is both signed and encrypted. You cannot produce this type of message using the createSignedData and createEncryptedData services.

Package WmPublic


envStream InputStream InputStream containing the MIME message that you want to sign and encrypt (e.g., the output produced by pub.mime:getEnvelopeStream).

privKey byte[ ] A byte array containing the private key of the party signing the message.

signerCert byte[ ] A byte array containing the digital certificate of the party signing the message

certificates Object[ ] Optional. A list (a one-dimensional array) of byte arrays containing the certificate chain of the party signing the message. The chain must appear in hierarchical order, starting with the signer’s certificate in element 0. The following list shows how the elements of a complete chain would appear for a certificate that was issued through two intermediate CAs:

Element Contents 0 Signer’s certificate 1 Intermediary CA Certificate 2 Intermediary CA Certificate 3 Root CA Certificate

Although this parameter is optional, it should only be omitted if the party receiving the message is able to process this signature without an accompanying certificate chain.

explicit String Optional. A String whose value specifies whether an implicit or explicit signature is to be generated.

Value Description

true Default. createSignedData generates an explicit signature.

pub.smime:createSignedData


false createSignedData generates an implicit signature.

recipientCerts Object[ ] A list (a one-dimensional array) of X.509 certificates of the recipients for whom this message will be encrypted, where each element in the list contains the certificate for a single recipient, in the form of a byte array.

encryptionAlg String A String whose value specifies which encryption algorithm is to be used. Must be one of the following values:

TripleDES

DES

RC2

Default is TripleDES

keyLength String A String whose value specifies the length of the encryption key for RC2 encryption. Must be one of the following values

40

64

128

Default is 128. This parameter is ignored if encryptionAlg is not RC2.

Variable Name Type Description Output SMimeEnvStream InputStream An InputStream containing the signed and encrypted MIME

message.


See Also CreateEncryptedData processEncryptedData CreateSignedData processSignedData pub.mime:getEnvelopeStream

Examples See the following in the WmSamples package. sample.smime:build_SignedAndEncryptedSMime

pub.smime:createSignedData

Description Digitally signs a MIME message.

Package WmPublic


envStream InputStream InputStream containing the MIME message that you want to sign (e.g., the output produced by pub.mime:getEnvelopeStream).

privKey byte[ ] A byte array containing the private key of the party signing the message.

signerCert byte[ ] A byte array containing the digital certificate of the party signing the message




certificates Object[ ] Optional. A list (a one-dimensional array) of byte arrays containing the certificate chain of the party signing the message. The chain must appear in hierarchical order, starting with the signer’s certificate in element 0. The following list shows how the elements of a complete chain would appear for a certificate that was issued through two intermediate CAs:


Although this parameter is optional, it should only be omitted if the party receiving the message is able to process this signature without an accompanying certificate chain.

explicit String Optional. A String whose value specifies whether an implicit or explicit signature is generated.

Value Description

true Default. createSignedData generates an explicit signature.

false createSignedData generates an implicit signature.


SMimeEnvStream InputStream An InputStream containing the signed MIME message.


See Also CreateEncryptedData processSignedData pub.mime:getEnvelopeStream

Examples See the following in the WmSamples package. sample.smime:build_SignedSMime

pub.smime:getContentType


pub.smime:processCertsOnlyData


pub.smime:processCertsOnlyData

Description Extracts the certificates from a PKCS #7 certs-only S/MIME entity.

Package WmPublic


SMimeEnvStream InputStream InputStream containing certs-only S/MIME entity.


certificates Object[ ] A list (a one-dimensional array) of byte arrays, in which each element contains one of the extracted certificates.

pub.smime:processEncryptedData

Description Decrypts an encrypted S/MIME message.

Package WmPublic


SMimeEnvStream InputStream An Input Stream containing an encrypted S/MIME entity (e.g., the output produced by createEncryptedData).

privKey byte[ ] A byte array containing the private key of the party receiving the message (i.e., the party whose public key was used to encrypt the message)..

recipientCert byte[ ] A byte array containing the digital certificate of the party receiving the message.


mimeData Object A MIME object containing the parsed contents of the decrypted MIME message.

encrypted String A String whose value indicates whether the decrypted MIME entity is encrypted.


true The MIME entity is encrypted. false The MIME entity is not encrypted. signed String A String whose value indicates whether the decrypted MIME

entity is signed.


true The MIME entity is signed. false The MIME entity is not signed.

certsOnly String A String whose value indicates whether the decrypted MIME entity is a certs-only entity.


true The MIME entity is a certs-only entity. false The MIME entity is not a certs-only entity. stream InputStream An InputStream containing the decrypted MIME entity.




contentDigest String A String containing a message digest of the encrypted content, base64-encoded. (Some sites return this digest to the sender to acknowledge their receipt of the message.)

Usage Notes If the decrypted message is signed or encrypted, mimeData will be empty, and the decrypted message will reside in stream. You can check the state of the signed and encrypted output variables to determine whether the decrypted message requires additional processing, and pass stream to the processSignedData or processEncryptedData service as necessary.

See Also processSignedData createEncryptedData

Examples See the following in the WmSamples package. sample.smime:extract_EncryptedSMime sample.smime:extract_SignedAndEncryptedSMime

pub.smime:processSignedData

Description Verifies the signature from a signed S/MIME entity and extracts the message from it.

Package WmPublic


SMimeEnvStream InputStream An Input Stream containing a signed MIME entity (e.g., the output produced by createSignedData).

signerCertChain Object[ ] Optional. A list (a one-dimensional array) of byte arrays containing the certificate chain of the party that signed the message. The chain must appear in hierarchical order, starting with the signer’s certificate in element 0. The following list shows how the elements of a complete chain would appear for a certificate that was issued through two intermediate CAs.


Note: If the signer included the certificate chain with the digital signature, you do not need to supply signerCertChain.


mimeData Object A MIME object containing the parsed contents of the extracted MIME entity.

contentDigest String A String that contains the message digest (base64-encoded) that was recalculated by processSignedData.

signerCert Object An Object containing the signer’s X.509 certificate.

encrypted String A String whose value indicates whether the extracted MIME entity is encrypted.

If Value is… Then...

true The MIME entity is encrypted.

pub.smime:processSignedData


Output Variable Name Type Description false The MIME entity is not encrypted.

signed String A String whose value indicates whether the extracted MIME entity is signed.


true The MIME entity is signed. false The MIME entity is not signed.

certsOnly String A String whose value indicates whether the extracted MIME entity is a certs-only entity.


true The MIME entity is a certs-only entity. false The MIME entity is not a certs-only entity. stream Object An InputStream containing the extracted MIME entity.

verify String A String whose value indicates whether the signature was successfully processed. Success indicates that the signature was successfully verified with the supplied public key.


true Signature processing was successful. false Signature processing failed. The signature

could not be verified, because an errorCode 1, 2, 3, or 4 occurred.

errorCode String A String that contains a number that indicates what kind of error occurred while processing the signature. See errorMessage for possible values. If no error occurred, errorCode will not be returned.

errorMessage String A String that contains a textual error message indicating what kind of error occurred while processing the signature. The table below shows the possible values returned in errorCode and errorMessage.

errorCode errorMessage

1 Invalid signer certificate file information. 2 Certificate at index ‘i’ is not in recognizable

format. 3 Invalid certificate input at index ‘i’. 4 Signature cannot be verified. 5 Expired certificate chain. 6 Error in certificate chain. 7 Untrusted certificate.

Usage Notes If verify is false, the errorCode and errorMessage values will indicate the error that caused the failure. Note that errorCode values 5 through 7 do not represent signature-validation failures, and therefore do not cause the verify flag to be set to false. If the extracted entity is signed or encrypted, mimeData will be empty, and the extracted entity will reside in stream. You can check the state of the signed and encrypted output variables to determine whether the extracted entity requires additional processing, and pass stream to the processSignedData or



processEncryptedData service as necessary.

See Also ProcessEncryptedData createSignedData

Examples See the following in the WmSamples package. sample.smime:extract_SignedSMime sample.smime:extract_SignedAndEncryptedSMime


Chapter 24 SOAP Services

You use the services in this folder to compose and send SOAP messages and to receive and retrieve data from within them. You also use the services in this folder to register custom SOAP processors.

24

C H A P T E R 2 4 S O A P S e r v i c e s


Summary o f Serv ices in the SOAP Folder

The following services are available for working with SOAP messages:

Service Function pub.soap.processor:list Returns a list of the SOAP processors that are currently registered on

the SAP BC.

pub.soap.processor:processMessage Default soap processor.

pub.soap.processor:processRPCMessage Default soap rpc processor.

pub.soap.processor:processMessage Description Process a soap message. This service calls the default soap processor (see SAP BC Soap Programming

Guide) Package WmPublic


soapRequestData Object The soap request to process

soapResponseData String A String specifying the fully qualified name of the service that you are registering as a SOAP processor.



pub.soap.processor:procssRPCMessage

Description Process a soap rpc message. This service calls the default RPC soap processor (see SAP BC Soap Programming Guide)

Package WmPublic






pub.soap.processor:registerProcessor

Registers a service as a SOAP processor on the SAP BC.

pub.soap.processor:unregisterProcessor Unregisters (removes from the registry) a SOAP processor.

pub.soap.schema:encoding The schema that defines the data types SOAP supports.

pub.soap.schema:envelope The schema that defines the structure of a SOAP message.

pub.soap.utils:addBodyEntry Inserts an entry into the body element of a SOAP message.

pub.soap.utils:addHeaderEntry Inserts an entry into the header element of a SOAP message.

pub.soap.processor:processRPCMessage


pub.soap.utils:addTrailer Inserts a trailer in a SOAP message.

pub.soap.utils:exitUnableToUnderstand Terminates processing and returns a MustUnderstand fault to the client.

pub.soap.utils:getActor Retrieves the value of the actor attribute from a given header entry.

pub.soap.utils:getBody Retrieves the body from a SOAP message as a single node object.

pub.soap.utils:getBodyEntries Retrieves the body entries from a SOAP message as an array of node objects.

pub.soap.utils:getDocument Retrieves an entire SOAP message as a node object.

pub.soap.utils:getHeader Retrieves the header from a SOAP message as a single node object.

pub.soap.utils:getHeaderEntries Retrieves the header entries from a SOAP message as an array of node objects.

pub.soap.utils:getMustUnderstand Returns the mustUnderstand status for a given header entry.

pub.soap.utils:getQName Returns the qualified name for a given node.

pub.soap.utils:getTrailers Retrieves the trailers from a SOAP message.

pub.soap.utils:removeBodyEntry Deletes a body entry from a SOAP message.

pub.soap.utils:removeHeaderEntry Deletes a body entry from a SOAP message.

pub.soap.utils:removeTrailer Deletes a trailer from a SOAP message.

pub.soap.utils:requestResponseSpec Defines the input/output signature for a custom processor and a target service for the default processor.

pub.soap.utils:soapDataToString Converts a SOAP object to a String.

pub.soap.utils:streamToSoapData Converts an InputStream containing a SOAP message to a SOAP object.

pub.soap.utils:stringToSoapData Converts a String containing a SOAP message to a SOAP object.

pub.soap.utils:validateSoapData Verifies that a SOAP object represents a valid SOAP message.



pub.soap.processor:list

Description Returns a list of the SOAP processors that are currently registered on the SAP BC.

Package WmPublic

Input None.


list Record List A Record list (an IData[ ]) containing a Record for each processor registered on the server. Each Record in the list contains the following keys:

Key… Contains…

directive A String containing the process directive that is assigned to the SOAP processor.

svcName A String containing the fully qualified name of the service that functions as the SOAP processor.

descriptiveName A String containing the descriptive comment that was given to the SOAP processor when it was registered. This element will be empty if the processor was not registered with a descriptive comment.

See Also pub.soap.processor:registerProcessor pub.soap.processor:unregisterProcessor

pub.soap.processor:processMessage

Description Process a soap message. This service calls the default soap processor (see SAP BC Soap Programming Guide)

Package WmPublic






pub.soap.processor:processRPCMessage

Description Process a soap rpc message. This service calls the default RPC soap processor (see SAP BC Soap Programming Guide)

Package WmPublic



soapResponseData String A String specifying the fully qualified name of the service that you are



registering as a SOAP processor.




Description Registers a service as a SOAP processor on the SAP BC.

Package WmPublic


directive String A String specifying the process directive that you want to assign to the SOAP processor. Note: Use only letters, digits, or the characters -_.!~*'( ) in the name you specify in directive.

svcName String A String specifying the fully qualified name of the service that you are registering as a SOAP processor.

descriptiveName String Optional. A String that contains a descriptive comment for this SOAP processor. This comment is shown when you run the utility service pub.soap.processor:list to get a list of the registered SOAP processors.

Output None.

Usage Notes For information about creating and registering SOAP processors, see the SAP BC SOAP Programming Guide.

See Also pub.soap.processor:rlist pub.soap.processor:unregisterProcessor

Examples See the following in the WmSamples package. sample.soap:registerProcessor

pub.soap.processor:unregisterProcessor

Description Unregisters (removes from the registry) a SOAP processor.

Package WmPublic


directive String A String specifying the process directive that you want to assign to the SOAP processor. Tip! To obtain a list of the current SOAP processor directives registered on the server, run the pub.soap.processor:list service.

Output None.

Usage Notes If the directive specified in directive is not registered on the SAP BC, unregisterProcessor throws an exception [B2BSERV.0088.9107].

See Also pub.soap.processor:rlist pub.soap.processor:registerProcessor



pub.soap.schema:encoding

Description The schema that defines the data types SOAP supports.

Package WmPublic

pub.soap.schema:envelope

Description The schema that defines the structure of a SOAP message.

Package WmPublic

pub.soap.utils:addBodyEntry

Description Inserts an entry into the body element of a SOAP message.

Package WmPublic


soapData Object The SOAP object to which you want the body entry added.

bodyEntry Object A node object containing the body entry that you want to add to soapData. Note: A node object is a parsed representation of a XML node. You generate a node object using services such as pub.web:stringToDocument. Important! This service adds a single body entry to a SOAP object. If you need to add more than one entry, execute addBodyEntry once for each entry.

Output None.

Usage Notes A SOAP object is an object that represents a SOAP message. If you are composing a new SOAP message, you must first create an empty SOAP object (called

soapData) with the createSoapData service, and then add body entries to with addBodyEntry. If you are composing a SOAP response, you use addBodyEntry to populate the soapResponseData object

that the SOAP message handler generates and puts in the pipeline. For information about composing SOAP messages, see the SOAP Programming Guide.

See Also pub.soap.utils:createSoapData pub.soap.utils:addBodyEntry pub.soap.utils:addHeaderEntry pub.soap.utils:addTrailer pub.soap.utils:getBody pub.soap.utils:getBodyEntries

Examples See the following in the WmSamples package. sample.soap:buildMsg_sendHTTP sample.soap:customProc_msgQuwue sample.soap:targetSvc_defaultProc

pub.soap.utils:addHeaderEntry

Description Inserts an entry into the header element of a SOAP message.

Package WmPublic

pub.soap.utils:addHeaderEntry



soapData Object The SOAP object to which you want the header entry added.

headerEntry Object A node object containing the entry that you want to add to soapData. Note: A node object is a parsed representation of a XML node. You generate a node object using services such as pub.web:stringToDocument. Important! This service adds a single header entry to a SOAP object. If you need to add more than one entry, execute addHeaderEntry once for each entry.

mustUnderstand String Optional. A String specifying the value to which you want the mustUnderstand attribute set. The mustUnderstand attribute specifies whether recipients are required to process a header entry—i.e., whether processing of the entry is mandatory or options. Recipients that cannot process a mandatory header entry must reject the message and return a SOAP fault.

Value Description 0 The header is optional. 1 The header is mandatory.

Note: If you do not set mustUnderstand, the mustUnderstand attribute is omitted from the header entry, which is equivalent to setting mustUnderstand to 0. For additional information about the mustUnderstand attribute, see the Simple Object Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/.

actor String Optional. A String specifying the value to which you want the actor attribute set. The actor attribute specifies a URI that identifies the recipient to which a header entry is targeted. For additional information about the mustUnderstand attribute, see the Simple Object Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/.

Output None


soapData) with the createSoapData service, and then add your header entries to with addHeaderEntry. If you are composing a SOAP response, you use addHeaderEntry to populate the soapResponseData object


See Also pub.soap.utils:createSoapData pub.soap.utils:addBodyEntry pub.soap.utils:addTrailer pub.soap.utils:getHeader pub.soap.utils:getHeaderEntries

Examples See the following in the WmSamples package. sample.soap:buildMsg_sendHTTP



sample.soap:targetSvc_defaultProc

pub.soap.utils:addTrailer

Description Inserts a trailer in a SOAP message. (A trailer is an arbitrary element that follows the Body element in the SOAP envelope.) Important!: It appears likely that trailers will not be permitted in future versions of SOAP (versions 1.2 and later). If you are designing a completely new solution, we recommend that you avoid using trailers. However, if you exchange SOAP messages with older systems that already make use of trailers, this service allows you to insert them into a SOAP message.

Package WmPublic


soapData Object The SOAP object to which you want the trailer added.

trailer Object A node object containing the trailer that you want to add to soapData. Note: A node object is a parsed representation of a XML node. You generate a node object using services such as pub.web:stringToDocument. Important! This service adds a single trailer to a SOAP object. If you need to insert more than one trailer in the message, execute addTrailer once for each trailer that needs to be added.

Output None.


soapData) with the createSoapData service, and then add your header entries to with addHeaderEntry. If you are composing a SOAP response, you use addHeaderEntry to populate the soapResponseData object


See Also pub.soap.utils:createSoapData pub.soap.utils:addHeaderEntry pub.soap.utils:addBodyEntry pub.soap.utils:getTrailers

pub.soap.utils:createSoapData

Description Creates an empty SOAP object. To compose a new SOAP message, you first use this service to create an empty SOAP object, and then you add content to the SOAP object using services such as addHeaderEntry and addBodyEntry.

Package WmPublic


schemaVersion String Optional. Version of the soap schema to use.

Value Description

1999 Use soap schema of the year 1999

2001 Use soap schema of the year 2001

pub.soap.utils:exitUnableToUnderstand



soapData Object An empty SOAP object.

Usage Notes For information about composing SOAP messages, see the SOAP Programming Guide.

See Also pub.soap.utils:addHeaderEntry pub.soap.utils:addBodyEntry pub.soap.utils:addTrailer

Examples See the following in the WmSamples package. sample.soap:buildMsg_sendHTTP

pub.soap.utils:exitUnableToUnderstand

Description Terminates processing and returns a MustUnderstand fault to the client. You execute this service when your SOAP processor detects a mandatory header entry that it cannot process.

Package WmPublic


soapData Object The SOAP object that contains the header entry that cannot be understood.

headerEntry Object The node containing the header entry that cannot be understood.

Output None.

Usage Notes This service throws an exception, which is meant to be caught by the message handler so that the appropriate SOAP fault will be returned to the client. Your processor should not catch this exception.

pub.soap.utils:getActor

Description Retrieves the value of the actor attribute from a given header entry.

Package WmPublic


headerEntry Object A node containing the header entry whose actor value you want to retrieve. If you use getHeaderEntries to retrieve header entries, you can loop

over the list of header nodes to retrieve the actor value from each entry.

If you use getHeader to retrieve header entries, you will need to query the node returned by that service (using the pub.web:queryDocument service) to extract a node for an individual header entry. Then you can run getActor on the resulting node.


actor String A String containing the value of the header entry’s actor attribute. If the header entry does not have an actor attribute, actor will be null.

Usage Notes For general information about the SOAP header entries and attributes, see the SAP BC SOAP Programming Guide.

See Also pub.soap.utils:addHeaderEntry



pub.soap.utils:getMustUnderstand pub.soap.utils:getHeader pub.soap.utils:getHeaderEntries

pub.soap.utils:getBody

Description Retrieves the body from a SOAP message as a single node object.

Package WmPublic


soapData Object The SOAP object containing the message whose Body node you want to retrieve.


body Object A node object containing the Body node from the SOAP message (i.e., <SOAP-ENV:Body> to </SOAP-ENV:Body>).

Usage Notes This service returns the entire Body element in body. You can query body with the pub.web:queryDocument service to extract the data within it. If you want to extract the body of the message as an array of nodes, use the getBodyEntries service. For additional information about extracting information from SOAP messages, see the SOAP Programming Guide.

See Also pub.soap.utils:getBodyEntries pub.soap.utils:addBodyEntry

Examples See the following in the WmSamples package. sample.soap:buildMsg_sendHTTP sample.soap:customProc_msgQueue sample.soap:targetSvc_defaultProc

pub.soap.utils:getBodyEntries

Description Retrieves the body entries from a SOAP message as an array of node objects.

Package WmPublic


soapData Object The SOAP object containing the message whose body entries you want to retrieve.


bodyEntries Object[ ] An array of nodes wherein each node represents a body entry from the message.

Usage Notes This service returns each body entry as a separate node. You can loop over bodyEntries and extract data from each node using the pub.web:queryDocument service. If you want to extract the body of the message as a single node, use the getBody service. For additional information about extracting information from SOAP messages, see the SOAP Programming Guide.

See Also pub.soap.utils:getBody pub.soap.utils:addBodyEntry

pub.soap.utils:getDocument


pub.soap.utils:getDocument

Description Retrieves an entire SOAP message as a node object. This service useful when you want to use queryDocument to query an entire SOAP message. Since queryDocument requires a node as input, you cannot use it to query a SOAP object directly. Instead, you must convert the SOAP object to a node, and then query the resulting node.

Package WmPublic


soapData Object The SOAP object for which you want a node representation.


node Object A node representation of the entire SOAP message in soapData (i.e., <SOAP-ENV:Envelope> to </SOAP-ENV:Envelope>.

Usage Notes For additional information about extracting information from SOAP messages, see the SOAP Programming Guide.

See Also pub.soap.utils:getBody pub.soap.utils:getBodyEntries pub.soap.utils:getHeader pub.soap.utils:getHeaderEntries pub.soap.utils:getTrailers

pub.soap.utils:getHeader

Description Retrieves the header from a SOAP message as a single node object.

Package WmPublic


soapData Object The SOAP object containing the message whose Header node you want to retrieve.


header Object A node object containing the Header node from the SOAP message (i.e., <SOAP-ENV:Header> to </SOAP-ENV:Header>).

Usage Notes This service returns the entire Header element in header. You can query header with the pub.web:queryDocument service to extract the data within it. If you want to extract the contents of the header as an array of nodes, use the getHeaderEntries service. For additional information about extracting information from SOAP messages, see the SOAP Programming Guide.

See Also pub.soap.utils:getHeaderEntries pub.soap.utils:getBody pub.soap.utils:getBodyEntries pub.soap.utils:getTrailers pub.soap.utils:addHeaderEntry

Examples See the following in the WmSamples package. sample.soap:customProc_msgQueue



pub.soap.utils:getHeaderEntries

Description Retrieves the header entries from a SOAP message as an array of node objects. This service is useful when you want to build a process that loops through all the header entries in a message and identify entries with specific QNames (using the getQName service) or actor attributes (using the getActor service).

Package WmPublic


soapData Object The SOAP object containing the message whose header entries you want to retrieve.


headerEntries Object[ ] An array of nodes wherein each node represents a header entry from the message.

Usage Notes This service returns each header entry as a separate node. You can loop over headerEntries and extract data from each node with the queryDocument service or get the entry’s QName and/or actor value using the getQName and getActor services. If you want to extract the message header as a single node, use the getHeader service. For additional information about extracting information from SOAP messages, see the SOAP Programming Guide.

See Also pub.soap.utils:getHeader pub.soap.utils:getBody pub.soap.utils:getBodyEntries pub.soap.utils:getDocument pub.soap.utils:addHeaderEntry pub.soap.utils:getActor pub.soap.utils:getQName

pub.soap.utils:getMustUnderstand

Description Returns the mustUnderstand status for a given header entry. The mustUnderstand status specifies whether recipients are required to process a header entry—i.e., whether processing of the entry is mandatory or optional. Recipients that cannot process a mandatory header entry must reject the message and return a SOAP fault. (See the pub.soap.utils:exitUnableToUnderstand service.)

Package WmPublic


headerEntry Object A node containing the header entry whose mustUnderstand status you want to retrieve. If you use getHeaderEntries to retrieve header entries, you can loop

over the list of header nodes to check the status of each entry. If you use getHeader to retrieve header entries, you will need to query

the node returned by that service (using the queryDocument service) to extract a node for an individual header entry. Then you can run getMustUnderstand on the resulting node.


mustUnderstand String A String indicating the header entry’s mustUnderstand status. If the header entry has a mustUnderstand attribute, mustUnderstand

pub.soap.utils:getMustUnderstand


will return one of the following values: Value Description 0 The header is optional. 1 The header is mandatory.

Usage Notes For additional information about the mustUnderstand attribute, see the Simple Object Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/ and the SAP BC SOAP Programming Guide.

See Also pub.soap.utils:addHeaderEntry pub.soap.utils:getActor pub.soap.utils:getHeader pub.soap.utils:getHeaderEntries pub.soap.utils:exitUnableToUnderstand



pub.soap.utils:getQName

Description Returns the qualified name for a given node.

Package WmPublic


node Object A node.


QName Record A Record (an IData object) that contains the node’s qualified element name. QName will contain the following keys:

Key Value namespaceName A String containing the namespace portion of the

node’s qualified name. localName A String containing the local portion of the

node’s qualified name.

Usage Notes Generally, you use this service in conjunction with the getHeaderEntries or getBodyEntries service to loop over the message’s header or body entries and identify entries with a particular qualified name.

See Also pub.soap.utils:getBodyEntries pub.soap.utils:getHeaderEntries

pub.soap.utils:getTrailers

Description Retrieves the trailers from a SOAP message. (A trailer is an arbitrary element that follows the Body element in the SOAP envelope.) Important!: It appears likely that trailers will not be permitted in future versions of SOAP (versions 1.2 and later). If you are designing a completely new solution, we recommend that you avoid using trailers. However, if you exchange SOAP messages with older systems that already make use of trailers, this service allows you to retrieve them from a SOAP message.

Package WmPublic


soapData Object The SOAP object containing the message whose trailers you want to retrieve.


trailers Object [ ] An array of nodes wherein each node represents a trailer from the message. If the message does not contain trailers, trailers will be null.

See Also pub.soap.utils:addTrailer pub.soap.utils:getHeader pub.soap.utils:getHeaderEntries pub.soap.utils:getBody pub.soap.utils:getBodyEntries pub.soap.utils:getDocument

pub.soap.utils:removeBodyEntry

Description Deletes a body entry from a SOAP message.

pub.soap.utils:removeHeaderEntry


Package WmPublic


soapData Object The SOAP object containing the body entry that you want to delete.

bodyEntry Object Optional. The node object representing the entry that you want to remove from soapData. (You would obtain the node with the getBodyEntries service.) Note: You can use bodyEntry or index to specify the entry that you want removeBodyEntry to delete.

index String Optional. A String specifying the index of the entry that you want to remove (where index 0 represents the first body entry). index is ignored if bodyEntry is specified.

Output None.

Usage Notes When you use the bodyEntry parameter, be sure that it specifies the correct node. This service deletes whatever node is specified in bodyEntry, even if the node is not a body entry (for example, if bodyEntry contains the whole Body element, removeBodyEntry will delete the body of the message). Also, be aware that if you use the index parameter to delete an entry, you will change the index numbers (positions) of all entries following the one you deleted. For example, if your message contains four body entries (0, 1, 2, 3) and you delete entry 1, then the entries originally at positions 2 and 3 will subsequently occupy positions 1 and 2.

See Also pub.soap.utils:removeHeaderEntry pub.soap.utils:removeTrailer pub.soap.utils:addBodyEntry pub.soap.utils:getBody pub.soap.utils:getBodyEntries

pub.soap.utils:removeHeaderEntry

Description Deletes a body entry from a SOAP message.

Package WmPublic


soapData Object The SOAP object containing the header entry that you want to delete.

headerEntry Object Optional. The node object representing the entry that you want to remove from soapData. (You would obtain the node with the getHeaderEntries service.) Note: You can use headerEntry or index to specify the entry that you want removeHeaderEntry to delete.

index String Optional. A String specifying the index of the entry that you want to remove (where index 0 represents the first header entry). index is ignored if headerEntry is specified.

Output None.

Usage Notes When you use the headerEntry parameter, be sure that it specifies the correct node. This service deletes whatever node is specified in headerEntry, even if the node is not a header entry (for example, if headerEntry contains the whole Header element, removeHeaderEntry will delete the entire header from the message).



Also, be aware that if you use the index parameter to delete an entry, you will change the index numbers (positions) of all entries following the one you deleted. For example, if your header contains four entries (0, 1, 2, 3) and you delete entry 1, then the entries originally at positions 2 and 3 will subsequently occupy positions 1 and 2.

See Also pub.soap.utils:removeBodyEntry pub.soap.utils:removeTrailer pub.soap.utils:addHeaderEntry pub.soap.utils:getHeader pub.soap.utils:getHeaderEntries

pub.soap.utils:removeTrailer

Description Deletes a trailer from a SOAP message.

Package WmPublic


soapData Object The SOAP object containing the trailer that you want to delete.

trailer Object Optional. The node object representing the trailer that you want to remove from soapData. (You would obtain the node with the getTrailers service.) Note: You can use trailer or index to specify the trailer that you want removeHeaderEntry to delete.

index String Optional. A String specifying the index of the trailer that you want to remove (where index 0 represents the first trailer). index is ignored if trailer is specified.

Output None.

Usage Notes When you use the trailer parameter, be sure that it specifies the correct node. This service deletes whatever node is specified in trailer, even if the node is not a trailer (for example, if trailer contains the Body element, removeTrailer will delete the entire body of the message). Also, be aware that if you use the index parameter to delete a trailer, you will change the index numbers (positions) of all trailers following the one you deleted. For example, if your message contains four trailers (0, 1, 2, 3) and you delete trailer 1, then the trailers originally at positions 2 and 3 will subsequently occupy positions 1 and 2.

See Also pub.soap.utils:removeHeaderEntry pub.soap.utils:removeBodyEntry pub.soap.utils:addTrailer pub.soap.utils:getTrailers

pub.soap.utils:requestResponseSpec

Description Defines the input/output signature for a custom processor and a target service for the default processor.

Package WmPublic


soapRequestData Object A SOAP object containing the SOAP request submitted to the SAP BC by the client.

pub.soap.utils:soapDataToString


soapResponseData Object An empty SOAP object that the custom processor or target service uses to compose the SOAP response message.


soapResponseData Object A SOAP object containing the message that is to be returned to the client.

Examples See the following in the WmSamples package. sample.soap:customProc_msgQueue sample.soap:targetSvc_defaultProc

pub.soap.utils:soapDataToString

Description Converts a SOAP object to a String. This is useful when you want to use the message with a process that requires the message to be in the form of a String.

Package WmPublic


soapData Object The SOAP object that you want to convert to a String.


string String A String containing the entire SOAP message.

See Also pub.soap.utils:streamToSoapData pub.soap.utils:stringToSoapData

pub.soap.utils:streamToSoapData

Description Converts an InputStream containing a SOAP message to a SOAP object. (A SOAP message must be represented as a SOAP object to be used with the data-retrieval services such as getBody and getHeader). Note: This service is a convenient way to produce a SOAP object during development and testing. It is not meant to be used for production purposes, because it does not ensure that a valid SOAP message is produced. For production purposes, we recommend that you create SOAP objects with the createSoapData service, and populate them with the message-composition services (e.g., addBodyEntry and addHeaderEntry).

Package WmPublic


stream Object An InputStream containing the SOAP message that is to be converted to a SOAP object.


soapData Object A SOAP object that contains a representation of the SOAP message in stream.

Usage Notes Be aware that if stream does not contain a valid SOAP message, this service does not throw an exception. Instead, it produces a soapData that contains a representation of whatever it received in stream (which might not even be an XML document). This will cause problems later when you attempt to use the soapData with other SOAP utilities or pass it to the message handler. To determine whether soapData represents a valid SOAP message, we recommend that you always execute the validateSoapData service immediately after using streamToSoapData.



See Also pub.soap.utils:stringToSoapData pub.soap.utils:validateSoapData

pub.soap.utils:stringToSoapData

Description Converts a String containing a SOAP message to a SOAP object. (A SOAP message must be represented as a SOAP object to be used with the data-retrieval services such as getBody and getHeader). Note: This service is a convenient way to produce a SOAP object during development and testing. It is not meant to be used for production purposes, because it does not ensure that a valid SOAP message is produced. Additionally, producing a SOAP object from a String is a very time-consuming process. For production purposes, we recommend that you create SOAP objects with the createSoapData service, and populate them with the message-composition services (e.g., addBodyEntry and addHeaderEntry).

Package WmPublic


string String A String containing the SOAP message that is to be converted to a SOAP object.


soapData Object A SOAP object that contains a representation of the SOAP message in string.

Usage Notes Be aware that if string does not contain a valid SOAP message, this service does not throw an exception. Instead, it produces a soapData that contains a representation of whatever it received in string (which might not even be an XML document). This will cause problems later when you attempt to use the soapData with other SOAP utilities or pass it to the message handler. To determine whether soapData represents a valid SOAP message, we recommend that you always execute the validateSoapData service immediately after using stringToSoapData.

See Also pub.soap.utils:streamToSoapData pub.soap.utils:validateSoapData

pub.soap.utils:validateSoapData

Description Verifies that a SOAP object represents a valid SOAP message. You can use this service to validate a SOAP object that was generated directly from an InputStream or String with pub.soap.utils:stringToSoapData or pub.soap.utils:streamToSoapData. Note: This service validates the SOAP object against the schema in pub.soap.schema:envelope.

Package WmPublic


soapData Object The SOAP object that you want to validate. If soapData does not contain a valid SOAP message, validateSoapData will throw an exception.

Output None.

Usage Notes If you create SOAP objects using the standard message-composition services (e.g., createSoapData, addBodyEntry, addHeaderEntry) there is no need to use this service. This service is only necessary when you generate a SOAP object directly from an InputStream or a String.

See Also pub.soap.utils:stringToSoapData pub.soap.utils:streamToSoapData

pub.soap.utils:QName



Description A record representing a qualified name.

Package WmPublic

Values Variable Name Type Description

namespaceName String Name of the namespace this QName resides in.

localName String Local name.

C H A P T E R 2 5 S t o r a g e S e r v i c e s


Chapter 25 Storage Services

Use storage services to create, close, delete, and register repository data stores and insert and retrieve information from repository data stores. Each entry in a data store consists of a key (which identifies the entry) and a value.

When a flow service retrieves an entry from a data store, the entry is locked to prevent modification by other users. The entry, which needs to be unlocked before the flow completes, remains locked until released via a put (pub.storage:put) or an explicit unlock (pub.storage:unlock).

Note: If you include storage services in a flow and you want to test the flow from Developer, use Run or Run in Browser. Trace and Step cannot be used to test storage services.

25





Service Function pub.storage:add Inserts a new entry into a repository data store. If the key already exists in the store,

then nothing is done.

pub.storage:closeStore Closes a repository data store, and unregisters the data store with the server.

pub.storage:deleteStore Deletes a repository data store, and unregisters the data store with the server.

pub.storage:get Retrieves a value from a repository data store and locks the entry on behalf of the flow that invoked the service.

pub.storage:keys Obtains a list of all the keys in a repository data store.

pub.storage:listStores Obtains a list of the names of all registered stores.

pub.storage:listStores Description Get a List of all registered stores.

Package WmPublic

Input None.


storeNames String[] A String list including the names of all registered stores.

pub.storage:lock

Locks an entry on behalf of the flow invoking this service.

pub.storage:put Inserts or updates an entry in a repository data store.

pub.storage:registerStore Opens or creates a repository data store, and registers the store with the server.

pub.storage:remove Removes an entry from a repository data store.

pub.storage:unlock Unlocks an entry in the repository data store.



pub.storage:add

Description Inserts a new entry into a repository data store. If the key already exists in the store, then the add service does nothing.

Package WmPublic


storeName String A String specifying the name of the data store in which to insert the entry.

key String A String specifying the key under which the entry is to be inserted.

value Record A Values object containing the value to be inserted.


result String A String indicating whether the entry was successfully added. If result is… Then..

true The new entry was inserted successfully. false The entry was not inserted. (Usually because an

entry for key already exists.)

pub.storage:closeStore

Description Closes a repository data store, and unregisters the data store with the server. If the data store is not registered with the server, an exception will be thrown. A store cannot be accessed after it has been unregistered. If you want to access the data in the store, you need to register the store again using pub.storage:registerStore.

Package WmPublic


storeName String A String specifying the name of the data store to unregister.

Output None.

Usage Notes This service does not delete the contents of the data store. If you want to delete the contents of a data store in addition to closing and unregistering the data store, use the pub.storage:deleteStore service.

pub.storage:deleteStore

Description Deletes a repository data store, and unregisters the data store with the server. Any data in the store is deleted. If the data store is not registered with the server, an exception will be thrown.

Package WmPublic


storeName String A String specifying the name of the data store to delete.

Output None.

Usage Notes If you want to close and unregister a data store without deleting the contents of the data store, use the pub.storage:closeStore service.

pub.storage:get


pub.storage:get

Description Retrieves a value from a repository data store and locks the entry on behalf of the flow that invoked the service. Locking the entry prevents other services from modifying the entry before the initial flow completes. Important! The lock needs to be released, via a put (pub.storage:put) or an explicit unlock (pub.storage:unlock) before the flow completes.

Package WmPublic


storeName String A String specifying the name of the data store from which you want to retrieve the entry.

key String A String specifying the key of the entry whose value you want to retrieve.

waitLength String A String specifying the length of time, in milliseconds, that you want to wait for this entry to become available if it’s already locked by another thread.

lockMode String A String specifying the type of lock you want to place on the entry. Must be one of the following values:

Set to… To…

Exclusive Prevent other threads from reading or updating the entry while you are using it. This type allows you to modify the entry

Share Prevent other threads from updating the entry while you are using it. This type allows you to modify the entry.

Read Allow other threads to read and update the entry while you are using it. This type of lock allows you to read, but not modify an entry.


value Record The retrieved Record (a Values object), or null if the requested entry does not exist.

pub.storage:keys

Description Obtains a list of all the keys in a repository data store.

Package WmPublic


storeName String A String specifying the name of the data store from which you want to obtain a list of keys.


keys String A list of keys.

pub.storage:listStores

Description Get a List of all registered stores.



Package WmPublic

Input None.


storeNames String[] A String list including the names of all registered stores.

pub.storage:lock

Description Locks an entry on behalf of the flow invoking this service. Locking an entry prevents other services from modifying it before your flow completes. Important! When you lock an entry using this service, the lock must be released, using a put (pub.storage:put) or an explicit unlock (pub.storage:unlock) before the flow completes.

Package WmPublic


storeName String A String specifying the name of the data store from which you want to retrieve the entry.

key String A String specifying the key of the entry that you want to lock.

waitLength String A String specifying the length of time, in milliseconds, that you want to wait for this entry to become available if it’s already locked by another thread.

lockMode String A String specifying the type of lock you want to place on the entry. Must be one of the following values:

Set to… To…

Exclusive Prevent other threads from reading or updating the entry while you are using it. This type allows you to modify the entry

Share Prevent other threads from updating the entry while you are using it. This type allows you to modify the entry.

Read Allow other threads to read and update the entry while you are using it. This type of lock allows you to read, but not modify an entry.

pub.storage:put

Description Inserts or updates an entry in a repository data store. If the key does not exist in the data store, then the entry is inserted. If the key already exists in the store, then its value is updated and the associated entry is unlocked. If the requested entry is not currently locked by the flow that invoked this service, the put service will automatically attempt to lock the entry.

Package WmPublic


storeName String A String specifying the name of the data store into which you want to insert or update the entry.

pub.storage:registerStore



key String A String specifying the key where you want to insert or update the entry.

value Record A Record (a Values object) representing the value that is to be inserted or updated.

waitLength String A String specifying the length of time, in milliseconds, that you want to wait for this entry to become available if it’s already locked by another thread. This parameter is used only when your service did not explicitly lock the entry beforehand.

Output None.

pub.storage:registerStore

Description Opens or creates a repository data store, and registers the store with the server. If the store is already registered with the server, nothing is done. A data store must be registered before it can be accessed.

Package WmPublic


storeName String A String specifying the name of the data store to register.

Output None.

Usage Notes To unregister and close a store, use the service pub.storage:closeStore.

pub.storage:remove

Description Removes an entry from a repository data store.

Package WmPublic


storeName String A String specifying the name of the data store from which to remove an entry.

key String A String specifying the key of the entry that you want to remove.


result String A String indicating whether the entry was successfully added. If result is… Then..

true The entry was removed successfully. false The entry was not removed. (Usually because

an entry for key does not exist.)

pub.storage:unlock

Description Unlocks an entry in the repository data store. When a flow retrieves an entry using the pub.storage:get service, the entry is locked to prevent modification by other users before the flow completes. The entry remains locked until the lock owner invokes a pub.storage:put service. To unlock a service without using the pub.storage:put service, use the pub.storage:unlock service.



Package WmPublic


storeName String A String specifying the name of the data store in which to unlock an entry.

key String A String specifying the key of the entry that you want to unlock.

Output None.

pub.storage:unlock



Chapter 26 String Services

You use string services to perform string manipulation and substitution operations.

26

C H A P T E R 2 6 S t r i n g S e r v i c e s




Service Function pub.string:HTMLDecode Replaces HTML character entities in inString with native characters.

pub.string:HTMLEncode Replaces HTML-sensitive characters in inString with equivalent HTML character entities.

pub.string:URLDecode Decodes a URL-encoded string.

pub.string:URLEncode URL-encodes a string. Encodes characters the same way that posted data from a WWW form is encoded, that is, the application/x-www-form-urlencoded MIME type.

pub.string:base64Decode Decodes a Base64 encoded string into a sequence of bytes.

pub.string:base64Encode Converts a sequence of bytes into a Base64 encoded string.

pub.string:bytesToString Converts a byte array to a String.

pub.string:concat Concatenates two strings.

pub.string:indexOf Returns the index of the first occurrence of subString in inString, starting at fromIndex.

pub.string:length Returns the length of a string.

pub.string:lookupDictionary Looks up a key string in a hash table and returns the corresponding string to which the specified key is mapped (case-sensitive).

pub.string:lookupTable Looks up a key string in a String table (String[][]) and returns the corresponding string to which the specified key is mapped.

pub.string:makeString Builds a single string by concatenating an array of strings while concatenating an optional separator between each string.

pub.string:messageFormat Formats an array of strings into a given message pattern.

pub.string:numericFormat Formats a number into a given numeric pattern.

pub.string:numericParse Parses a number according to a given numeric pattern.

pub.string:padLeft Pads a string to a certain length. Padded characters are added to the beginning of the string.

pub.string:padRight Pads a string to a certain length. Padded characters are added to the end of the string.

pub.string:replace Replaces all occurrences of a specified substring with a substitute string.

pub.string:stringToBytes Converts a String to a byte array.

pub.string:substring Returns a substring of a given string.

pub.string:toLower Converts all characters in a string to lowercase. Language, country, and variant are optional arguments.

pub.string:toUpper Converts all characters in a string to uppercase. Language, country, and variant are optional arguments.

pub.string:tokenize Tokenizes a string into an array of strings (String[]) using specified delimiter characters. Does not return delimiters as tokens.

pub.string:trim Trims white space from a string.

pub.string:gzip Compresses the given input string and optionally generates a check sum. For measurement or statistical purposes, the lengths of the zipped and unzipped string are given as output.

pub.storage:unlock


Service Function pub.string:ungzip Decompresses a given input string that was compressed by pub.string:gzip and checks the

optionally supplied check sum.



pub.string:HTMLDecode

Description Replaces HTML character entities in inString with native characters. Specifically:

This HTML character entity… Is replaced with… > > < < & & " "

Package WmPublic


inString String A String.


value String A String containing the characters in inString with the HTML character entities replaced by equivalent native characters.

pub.string:HTMLEncode

Description Replaces HTML-sensitive characters in inString with equivalent HTML character entities. Specifically:

This native language character… Is replaced with… > > < < & & " "

These translations are useful when displaying text in an HTML context.

Package WmPublic




value String A String containing the characters in inString with occurrences of the characters above replaced by their equivalent HTML character entities.

pub.string:URLDecode

Description Decodes a URL-encoded string.

Package WmPublic


inString String A URL-encoded String.


value String A String containing the decoded form of inString. Converts plus (+) signs to spaces, and converts any %xx encoding to the character equivalent of the hex value.

pub.string:URLEncode


pub.string:URLEncode

Description URL-encodes a string. Encodes characters the same way that posted data from a WWW form is encoded, that is, the application/x-www-form-urlencoded MIME type.

Package WmPublic




value String A String in which all non-alphanumeric characters except [-_.*@] have been replaced with a percent (%) sign followed by two hex digits and spaces encoded as plus (+) signs.

pub.string:base64Decode

Description Decodes a Base64 encoded string into a sequence of bytes.

Package WmPublic


string String Bas64 encoded String.


value Object A byte [ ] containing the decoded from of string.

pub.string:base64Encode

Description Converts a sequence of bytes into a Base64 encoded string.

Package WmPublic


bytes Object A byte[ ] containing the sequence of bytes to be encoded.

addLineFeed String Optional. A Boolean value.

Value Description

true Default behaviour. Add a linefeed (“\r\n”) after 76 characters (used to encode certificates for example).

false Do not add linefeeds.


value String A String containing the Base64 encoded form of bytes.



pub.string:bytesToString

Description Converts a byte array to a String.

Package WmPublic


bytes Object A byte array (byte[ ]).

encoding String Optional. The name of a registered, IANA character set. Example ISO-8859-1. To use the default encoding, set the to autoDetect will use the default encoding. If you specify an unsupported encoding, an exception will be thrown.


string String A String representation of the contents of bytes.

pub.string:concat

Description Concatenates two strings.

Package WmPublic


inString1 String A String.

inString2 String A String.


value String A string that represents inString1 concatenated with inString2 (inString1 + inString2).

pub.string:indexOf

Description Returns the index of the first occurrence of subString in inString, starting at fromIndex.

Package WmPublic



subString String The String containing the sequence of characters to look for.

fromIndex String Optional. A String representing the index of inString to start the search from. If null or empty, uses “0.”


value String A String representing the index of the first occurrence of subString in inString, or “-1” if no occurrence is found.

pub.string:length

Description Returns the length of a string.

Package WmPublic

pub.string:lookupDictionary





value String A String representing the length of inString.

pub.string:lookupDictionary

Description Looks up a key string in a hash table and returns the corresponding string to which the specified key is mapped (case-sensitive).

Package WmPublic


hashtable Hashtable A Hashtable that uses String objects for keys and values.

key String The String to look up.


value String The String to which key is mapped; if key is null or if key is not mapped to any value in hashtable, returns null.

pub.string:lookupTable

Description Looks up a key string in a String table (String[][]) and returns the corresponding string to which the specified key is mapped.

Package WmPublic


lookupTable String [ ] [ ] A multi-row, multi-column table of Strings.

keyColumnIndex String String representation of the index of the key column. If not specified, the default is 0.

valueColumnIndex String String representation of the index of the value column. If not specified, the default is 1.

key String The String to look up.

ignoreCase String Optional. Set this string to “true” to perform a case-insensitive lookup.

useRegex String Optional. Set this string to “true” to have the key column values interpreted as regular expressions. The regular expressions in the table should not include slashes. For example, use hello.*, not /hello.*/.


value String The String in the value column of the first row whose key column matches key. If no match is found, returns null.

pub.string:makeString

Description Builds a single string by concatenating an array of strings while concatenating an optional separator between each string.



Package WmPublic


elementList String [ ] An array of Strings to concatenate.

separator String The String to insert between each non-null element in elementList.


value String A String that contains all the Strings in elementList concatenated with separator between each String.

pub.string:messageFormat

Description Formats an array of strings into a given message pattern.

Package WmPublic


pattern String Optional. A String that contains the desired message pattern. Use {n} as a placeholder for the nth string in argumentList. Example “Test results: {0} items passed, {1} items failed.” Do not use any characters other than digits for n.

argumentList String [ ] An array of Strings to format into a single String.


value String A String that contains the elements in argumentList substituted into pattern. If pattern is an empty string or null, null is returned.

pub.string:numericFormat

Description Formats a number into a given numeric pattern.

Package WmPublic


locale Record Optional. Locale used for formatting.

+ language String Lowercase two-letter ISO-639 language code

Note: ISO 639 is not a stable standard; some of the language codes it defines (specifically iw, ji, and in) have changed. This variable accepts both the old codes (iw, ji, and in) and the new codes (he, yi, and id).

+ country String Optional. Uppercase two-letter ISO-3166 country code.

+ variant String Optional. Vendor specific codes.

num String A String representation of a number.

pattern String A String that contains the desired number pattern, using the following syntax:

Symbol Description

0 A digit.

pub.string:numericParse


# A digit. Zero shows as absent (leading zeroes will not be shown).

. Placeholder for a decimal separator.

, Placeholder for a grouping separator.

; Separates formats.

- Default negative prefix.

% Multiply by 100 and show as a percentage.

X Any character you want to use as a prefix or suffix, e.g., A, $.

' Use to enclose special characters that you want to use in prefix or suffix.

Examples The following are examples of pattern strings:

Pattern Description

#,### Use commas to separate into groups of three digits.

#,#### Use commas to separate into groups of four digits.

$#.00 Show digits before the decimal point as needed and exactly two digits after the decimal point. Prefix with the $ character.

'#'#.0 Show digits before the decimal point as needed and exactly one digit after the decimal point. Prefix with the # character.


value String A string that represents num formatted according to pattern. If pattern is an empty (not null) string, the default pattern of comma separators and three decimal places is used. For example, 1121.888888 would be returned as 1,121.888.

pub.string:numericParse

Description Parses a number according to a given numeric pattern.

Package WmPublic


locale Record Optional. Locale used for formatting.

+ language String Lowercase two-letter ISO-639 language code

Note: ISO 639 is not a stable standard; some of the language codes it defines (specifically iw, ji, and in) have changed. This variable accepts both the old codes (iw, ji, and in) and the new codes (he, yi, and id).

+ country String Optional. Uppercase two-letter ISO-3166 country code.

+ variant String Optional. Vendor specific codes.



num String A String representation of a number.

pattern String A String that contains the desired number pattern, using the following syntax (Default: #,##0.###):

Symbol Description

0 A digit.

# A digit. Zero shows as absent (leading zeroes will not be shown).

. Placeholder for a decimal separator.

, Placeholder for a grouping separator.

; Separates formats.

- Default negative prefix.

% Multiply by 100 and show as a percentage.

X Any character you want to use as a prefix or suffix, e.g., A, $.

' Use to enclose special characters that you want to use in prefix or suffix.

Examples The following are examples of pattern strings:

Pattern Description

#,### Use commas to separate into groups of three digits.

#,#### Use commas to separate into groups of four digits.

$#.00 Show digits before the decimal point as needed and exactly two digits after the decimal point. Prefix with the $ character.

'#'#.0 Show digits before the decimal point as needed and exactly one digit after the decimal point. Prefix with the # character.


value String Standard representation of the number, which could be used in the pub.math:* services.

pub.string:padLeft

Description Pads a string to a certain length. Padded characters are added to the beginning of the string.

Package WmPublic



padString String String to use as padding.

length String Desired length of resulting String.

pub.string:padRight



value String A string of length, containing inString preceded by multiple occurrences of padString. If padString is longer than one character and padString does not fit an exact number of times into the resulting string, the beginning of padString will be aligned with the beginning of the resulting string. If inString is longer than length characters, the right-most length characters will be returned.

pub.string:padRight

Description Pads a string to a certain length. Padded characters are added to the end of the string.

Package WmPublic



padString String String to use as padding.

length String Desired length of resulting String.


value String A string of length, containing inString followed by multiple occurrences of padString. If padString is longer than one character and padString does not fit an exact number of times into the resulting string, the end of padString will be aligned with the end of the resulting string. If inString is longer than length characters, the first length characters will be returned.

pub.string:replace

Description Replaces all occurrences of a specified substring with a substitute string.

Package WmPublic


inString String A string.

searchString String String to search for within inString.

replaceString String String to substitute in place of searchString. If null or empty, occurrences of searchString will simply be removed.

useRegex String Optional. Set this String to “true” to have searchString interpreted as a regular expression. replaceString may also contain interpolation variables (e.g., “$1”) that match parenthetical subexpressions in searchString.


value String A String that represents inString, with all occurrences of substrings matching searchString replaced by replaceString.



pub.string:stringToBytes

Description Converts a String to a byte array.

Package WmPublic


string String A String.

encoding String Optional. The name of a registered, IANA character set Example ISO-8859-1. To use the default encoding, set this value to autoDetect. If you specify an unsupported encoding, an exception will be thrown.


bytes Object A byte array containing the bytes in string.

pub.string:substring

Description Returns a substring of a given String.

Package WmPublic



beginIndex String String representation of the beginning index, inclusive.

endIndex String String representation of the end index, exclusive. If null or empty, the substring will extend to the end of inString.


value String A String that is a substring of inString beginning at the specified beginIndex and extending to the character at endIndex – 1.

pub.string:toLower


pub.string:toLower

Description Converts all characters in a given String to lowercase.

Package WmPublic



language String Optional. Lowercase two-letter ISO-639 code. If null, uses system default.

country String Optional. Uppercase two-letter ISO-3166 code. If null, uses system default.

variant String Optional. Vendor and browser-specific code. If null, ignored.


value String A String that represents inString, with all uppercase characters converted to lowercase.

pub.string:toUpper

Description Converts all characters in a given String to uppercase.

Package WmPublic



language String Optional. Lowercase two-letter ISO-639 code. If null, uses system default.

country String Optional. Uppercase two-letter ISO-3166 code. If null, uses system default.

variant String Optional. Vendor and browser-specific code. If null, ignored.


value String A string that represents inString, with all lowercase characters converted to uppercase.

pub.string:tokenize

Description Tokenizes a String into an array of strings (String[ ]) using specified delimiter characters. Does not return delimiters as tokens.

Package WmPublic



delim String A Sstring containing the delimiter characters. If null or empty, it uses the default delimiter “\t\n\r” (where t, n, and r represent the white space characters tab, new line, and carriage return).




valueList String [ ] An array of Strings containing the tokens in inString.

pub.string:trim

Description Trims leading and trailing white space from a given String.

Package WmPublic


inString String ASstring.


value String A String containing inString with white space trimmed from both ends.

pub.string:gzip

Description Compresses the given input string and optionally generates a check sum. For measurement or statistical purposes, the lengths of the zipped and unzipped string are given as output.

Package WmPublic


check String Optional. Flag that indicates whether to create a check sum of the input string.(Default: false)

string string String to compress


gzipped Object Compressed string as a byte array object.

checkSum String Optional. Checks sum of input string,

zippedLength String Length of compressed string.

unZippedLength String Length of input string.

pub.string:ungzip

Description Decompresses a given input string that was compressed by pub.string:gzip and checks the optionally supplied check sum.

Package WmPublic


gzipped Object Compressed string as a byte array object.

checkSum String Optional. Checks sum of input string,


string string Decompressed String.

pub.string:ungzip


Chapter 27 Sync Services

Use synchronization services to coordinate the execution of services. You can coordinate services so that a waiting service will execute if and only if a notifying service produces the input required by the waiting service within a specified time period. The synchronization services wait for and send notification using a key. A notifying service only delivers input to waiting services with the same key.

27

C H A P T E R 2 7 S y n c S e r v i c e s




Service Function pub.sync:notify Notifies services waiting on the specified key and delivers the input Record to the

services. Receives a count of the number of notified services.

pub.sync:wait Allows one or more services to wait on delivery of data from a notifying service. Notification must occur within a specified time period.

pub.sync:notify


pub.sync:notify

Description Notifies services waiting on the specified key and delivers the input Record to the services. Receives a count of the number of notified services.

Package WmPublic


key String Name of the key. Waiting services with the same key will receive notification and input from this service.

value Values Values object containing the input delivered to the waiting services.


notified String Number indicating how many services were notified.

pub.sync:wait

Description Allows one or more services to wait on delivery of data from a notifying service. Notification must occur within a specified time period.

Package WmPublic


key String Name of the key for which the service is waiting notification. The service receives notification and data from a notifying service with the same key.

time String Length of time, measured in seconds, the service waits for notification. If the request times out, an exception is thrown.

exclusive String Optional. Specifies if other services can wait for notification from a notifying service with the specified key.

Set to… To… yes Allow only one service to wait for

notification. no Default. Allow other services to wait for

notification.


value IData IData object containing the input delivered by the notifying service.

C H A P T E R 2 7 S y n c S e r v i c e s



Chapter 28 Table Services

You use table services to convert instances of com.wm.util.Table to other data types.

28

C H A P T E R 2 8 T a b l e S e r v i c e s




Service Function pub.table:recordListToTable Deprecated. Converts a list of Records into an instance of com.wm.util.Table.

pub.table:stringTableToTable Converts a string table (Java array) into an instance of com.wm.util.Table.

pub.table:tableToRecordList Deprecated. Converts an instance of com.wm.util.Table into a list of Records.

pub.table:tableToStringTable Converts an instance of com.wm.util.Table into a two-dimensional string array.

pub.table:recordListToTable


pub.table:recordListToTable

Description Deprecated. Converts a list of Records into an instance of com.wm.util.Table.

Package WmPublic


recordList Records [ ] A Record list (IData [ ]) containing the sata for the new table. Each Record represents a row for the new table.

columnNames String [ ] An array of Strings representing the column names for the new table. Each Record/row will be queried for a value for each column.

tableName String Optional. A name for the new table.


table Object An instance of com.wm.util.Table. The resulting table with the supplied data.

pub.table:stringTableToTable

Description Converts a string table (Java array) into an instance of com.wm.util.Table.

Package WmPublic


columnNames String [ ] A string array of column names for the table.

stringTable String [ ][ ] A multi-dimensional string array of table data.

tableName String Optional. A name for the new table.


table Object An instance of com.wm.util.Table. The resulting table with the supplied data.

Usage Notes For example, to create a two-column table which maps ID numbers to names, you might use the following parameters: columnNames = { “id”, “name” } stringTable = { { “1099”, “arthur” }, { “3000”, “dorothy” }, { “2068”, “scott” } } tableName = “idTable”

pub.table:tableToRecordList

Description Deprecated. Converts an instance of com.wm.util.Table into a list of Records. Note: In versions 3.5 and later, there is no need to use this service to convert a table to a Record List in order to map it in a flow service. Objects in the pipeline that are of type com.wm.util.Table are automatically recognized and treated as Record Lists at run time.

Package WmPublic


table Object An instance of com.wm.util.Table. The table to convert to a Record list.

C H A P T E R 2 8 T a b l e S e r v i c e s



recordList IData [ ] Data from the table. Each Record represents a row from the table. The keys of the Record are the column names, and their values are the corresponding values in that row.

pub.table:tableToStringTable

Description Converts an instance of com.wm.util.Table into a two-dimensional string array.

Package WmPublic


table Object An instance of com.wm.util.Table. The table to convert to a string table.


columnNames String [ ] An array of column names from the table.

stringTable String [ ][ ] A two-dimensional array of string data from the table.

Usage Notes If you just used pub.db:select to query your database for a table of all transactions with an ID higher than 3000, you could turn the resulting instance of com.wm.util.Table into a multi-dimensional string array with this service.


Chapter 29 Universal Name Services

You use the universal name services to list the contents of the Universal Registery and to look-up services by their universal name.

29

C H A P T E R 2 9 U n i v e r s a l N a m e S e r v i c e s




Service Function pub.universalName:find Returns the fully qualified service name for an explicit universal name.

pub.universalName:list Returns the contents of the current universal-name registry.

pub.universalName:find


pub.universalName:find

Description Returns the fully qualified service name for an explicit universal name.

Package WmPublic


namespaceName String A String that specifies the namespace portion of the universal name.

lacalName String A String that specifies the local portion of the universal name.


svcName String A String containing the fully qualified name of the service. If the specified universal name is not in the registry, svcName will be null.

pub.universalName:list

Description Returns the contents of the current universal-name registry.

Package WmPublic

Input None.


names Record[ ] A Record List (an array of IData objects ) in which each Record represents an entry in the universal-name registry. (The registry contains a Record for every explicit universal name that has been defined on the server). Each Record in the list contains the following:

Key Description

svcName A String representing the fully qualified SAP BC service name associated with the entry. Example: gl.post:postEntry

universalName A Record (an IData object) containing the universal name associated with the entry. This IData contains the following elements:

localName A String containing the local portion of the universal name.

nameSpaceName A String containing the namespace portion of the universal name.

C H A P T E R 2 9 U n i v e r s a l N a m e S e r v i c e s



Chapter 30 Web Services

You use Web services to perform operations on XML and HTML documents.

0
3

C H A P T E R 3 0 W e b S e r v i c e s




Service Function pub.web:createRegions Generates regions output parameters.

pub.web:documentToRecord Converts a parsed HTML or XML document to an IData object..

pub.web:freeDocument Frees the resources allocated to the given document.

pub.web:getDocumentType Returns document type information about a document.

pub.web:getNextNode Gets the next node from a NodeIterator.

pub.web:getNodeIterator Creates and returns a NodeIterator.

pub.web:loadDocument Retrieves a specified XML or HTML document via HTTP or HTTPS and returns a parsed Document object that can be used as input to any service that accepts a node.

pub.web:makeArrays Produces a String[ ] that can be sent to pub.web:documentToRecord based on the values in the document’s DTD.

pub.web:queryDocument Executes queries on a document, region, or node to generate output variables.

pub.web:recordToDocument Converts a Values object to an XML string.

pub.web:stringToDocument Converts a text string representing an XML document into a Document object.

pub.web:createRegions


pub.web:createRegions

Description Generates regions output parameters.

Package WmPublic


node

Node Document Region

The node from which you want to create regions. (A node is produced by loadDocument, stringToDocument, createRegions, or one of the SAP BC server content handlers.)

nsDecls

Record Optional. A Record (an IData object) that declares the namespaces associated with any namespace prefixes that are used in query. Within nsDecls, set the key names to the prefixes that you use. Set the values of each key to the URI represented by that prefix. For example, the following shows how nsDecls would look if it defined the namespaces associated with prefixes called GSX and TxMon:

Element Type Description

prefix String Prefix that represents the URL in queries.

url String URL identifying the XML namespace.

regions IData Optional. A set of parameters defining a region. A region is a portion of a document between two delimiting nodes, possibly including either or both delimiting nodes. Each region is defined as follows:

Element Description

name A String specifying the name to assign to resulting region.

structured Optional. Not used. Reserved for future use.

start Optional. A Record (IData object) that identifies the starting node of the region. When start is not specified, the region starts with the first node and includes the first node. Specify start as follows:

Key Description

queryType A String specifying the query language in which the query for the starting node is expressed. Valid values are WQL and XQL.

query A String specifying the query identifying the starting node. If the identified node cannot be found, the region cannot be found.

include A String specifying whether to include the starting node in the region. Valid values are true and false.



Element Description

end Optional. A Record (IData object) that identifies the ending node of the region. When end is not specified, the region ends with the last node and includes the last node. Specify end as follows:

Key Description

queryType A String specifying the query language in which the query for the ending node is expressed. Valid values are WQL and XQL.

query A String specifying a query identifying the ending node. If the identified node cannot be found, the region cannot be found.

include A String specifying whether to include the ending node in the region. Valid values are true and false.

pattern String Pattern is not currently implemented.

nullok String Optional. Specifies whether the service should fail if the resulting region is null. Set to true or false. Default is true.

Output Values retrieved by the regions input specifications. There will be one output parameter for each region, which will go directly into the IData object passed to the service (usually the IData object representing the pipeline).

pub.web:documentToRecord

Description Converts a parsed HTML or XML document to an IData object.. This service transforms each element and attribute in the source document to an element in an IData object. For example:

This service would convert this XML document... To an IData that looks like this...



<?xml version="1.0" ?>

<AcctInfo>

<name>Midwest Extreme Sports</name>

<rep>Laura M. Sanchez</rep>

<acctNum

type=platinum>G97041A</acctNum>

<phoneNum cc=011>216-741-

7566</phoneNum>

<address county=USA>

<street1>10211 Brook

Road</street1>

<city>Cleveland</city>

<state>OH</state>

<postalCode>22130</postalCode>

</address>

<serialNum>19970523A</serialNum>

<serialNum>20001106G</serialNum>

<serialNum>20010404K</serialNum>

</AcctInfo>

Note that: The XML version attribute is converted to an element named @version. The entire document is contained in an IData that is named after the document’s root element (AcctInfo

in the example above) and is a child of the boundNode IData returned by this service. Simple elements (such as <name> and <rep> in the example above) are converted to String elements

within the parent IData. Complex elements (i.e., elements with children, such as <address> in the example above) and simple

elements that have attributes (such as <acctNum> and <phoneNum>) are converted to IData objects within the parent IData. Note that the names of keys that have been derived from attributes are prefixed with a ‘@’ character to distinguish them from keys derived from elements. Also note that when a simple element has an attribute, it’s value is placed in an element named *body.

Repeated elements (such as <serialNum>) can be collected into arrays using the makeArrays and/or arrays, parameters. See makeArrays and arrays below for additional information about producing arrays from the source data.

Package WmPublic


node Object An instance of com.wm.lang.xml.Node (i.e., the node variable returned by a service such as loadDocument or stringToDocument).

useLocalNames

Optional. If set to true, xml namespace prefixes are cut from names in an XML document with namespaces, e.g. <sap:RFC_SYSTEM_INFO> will be decoded as RFC_SYSTEM_INFO. The default "false" is the original behaviour to decode the name as sap:RFC_SYSTEM_INFO.



attrPrefix String Optional. A String specifying the prefix that is to be used to designate keys containing attribute values. The default is “@”. For example, if you set attrPrefix to ATT_ and the source document contained the following element:

<tx currency=dollars> <acct>cash</acct> <amt>120.00</amt> </tx>

documentToRecord would convert the currency attribute as follows:

arrays String[ ] Optional. An array of Strings specifying the names of elements that are

to be generated as arrays, regardless of whether they appear multiple times in the source document. For example, if arrays contains the following values for the XML document shown in Description above: rep address

documentToRecord would generate element rep as an array of Strings and element address as an array of IData. You may optionally include namespace prefixes in the element names that you specify in arrays; however, if you do, you must define the namespaces associated with those prefixes in nsDecls.

makeArrays String Optional. A String specifying whether you want documentToRecord to automatically create an array for every element that appears in the source document more than once.

Set to… To…

true Default. Automatically create arrays for every element that appears more than once in the source document.

false Create arrays for only those elements specified in arrays or defined as arrays in the record specified by recordName. Important! You must set makeArrays to false when using recordName to define the structure of an element. Otherwise, an exception will be thrown at run time.

collect Record Optional. A Record (an IData object) that specifies the elements that you want placed into a new, named array (i.e., a “collection”). Within collect, set the key names to specify the names of those elements that are to be included in the collection. Set the value of each key to the name of the collection in which you want that element placed. For example, if you wanted to place <name> and <rep> in an array called originator, you would set collect as follows:

Key Value

name originator

rep originator

If the set of elements placed in a collection are all simple elements, a String array will be produced. If the set is made up of complex elements, or a combination of simple and complex elements, an array of IData

The currency attribute is prefixed with the characters “ATT_”



objects will be produced. In this case, each member of the array will include a child element called *name that contains the name of the element from which that member was derived. You may optionally include namespace prefixes in the element names that you specify in collect; however, if you do, you must define the namespaces associated with those prefixes in nsDecls. Important! You cannot include an element into more than one collection.

nsDecls Record Optional. A Record (an IData object) that declares the namespaces associated with any namespace prefixes that are used in arrays, record and collect. Within nsDecls, set the key names to the prefixes that you use. Set the values of each key to the URI represented by that prefix. For example, the following shows how nsDecls would look if it defined the namespaces associated with prefixes called GSX and TxMon:

records String[ ] Optional. An array of Strings that specifies the names of any simple

elements that are to be generated as IData objects instead of Strings. The IData produced for each element specified in records will have the same name as the source element from which it was derived and will contain a String element named *body that will hold the element’s value. For example, if records contained the Strings name and rep and the source document contained the following:

. . . <name>Midwest Extreme Sports</name> <rep>Laura M. Sanchez</rep> . . .

documentToRecord would produce the following IData objects:

recordName String Optional. The fully qualified name of a saved Record, which specifies

the structure that you want imposed on the elements in the resulting IData. You can use this parameter to explicitly specify the order and dimensionality of elements. It is an alternative to using makeArrays and arrays to specify which elements are to be generated as arrays. For example, if you had the XML document shown in Description above, and you wanted the <name> and <rep> elements to be generated as String arrays, you would define them as such in a saved Record and then specify the name of that Record in recordName. Note: recordName does not need to specify every element that will appear in the resulting IData. It only needs to specify those elements whose structure you want to explicitly set. Important! When you use recordName , you must set makeArrays to false and set arrays and records to null. Otherwise, documentToRecord will



throw an exception at run time.

mixedModel String Optional. A String specifying how mixed-content elements (elements containing both text values and child elements) are to be converted. The following is an example of a mixed-content element:

<comment> This job is <status>pending</status>. Estimated completion date is <edc>Feb 14, 2000</edc>. </comment>

Set mixedModel to… To…

True Place text in an element named *body. This setting would produce the following IData for the <comment> element shown above:

Important! When you set mixedModel to true, you

must also use recordName to specify a stored Record definition that describes the structure of the IData that you want documentToRecord to produce. Within the Record definition, mixed-content elements must be defined as IData objects that include a String child named *body.

False Omit top-level text and include only the child elements from mixed-content elements. This setting would produce the following IData for the <comment> element shown above:


boundNode IData An IData object that includes all the nodes and attributes of the source document.

processingInstructions IData An IData object that includes all processing instructions in the document Example: <?soxtype urn:x-commerceone:document:com:commerceone:XCBL30:XCBL30.sox$1.0?> Will be added to the IData as: key = "soxtype" value = "urn:x-commerceone:document:com:commerceone:XCBL30:XCBL30.sox$1.0"

Usage Notes Following are examples of XML documents and the IData objects that result when you use the documentToRecord service.



XML Document Output <myDoc> <e1>e1Value</e1> </myDoc>

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <myDoc> <e1>e1Value</e1> </myDoc>

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <myDoc> <e1 e1Attr="attrValue">e1Value</e1> </myDoc>

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <myDoc> <e1>e1Value</e1> <e2>e2Value</e2> </myDoc>

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <myDoc> <e1>e1Value1</e1> <e2>e2Value</e2> <e1>e1Value2</e1> </myDoc>

<?xml version="1.0" encoding="UTF-8"?> <myDoc> <e1 e1Attr="attrValue1">e1Value1</e1> <e2>e2Value</e2> <e1 e1Attr="attrValue2">e1Value2</e1> </myDoc>

Note: This example assumes that makeArrays is set to true. Note that an array e1 was created, which holds both <e1> elements that were in the source document.



XML Document Output

<?xml version="1.0" encoding="UTF-8"?> <myDoc> <e1 e1Attr="attrValue1">e1Value1</e1> <e2>e2Value</e2> <e1 e1Attr="attrValue2">e1Value2</e1> </myDoc>

Note: This example assumes that makeArrays is set to false. Note that only the last <e1> element in the source document was retained in the resulting IData.

<?xml version="1.0" encoding="UTF-8"?> <myDoc> <e1 e1Attr="attrValue1">e1Value1</e1> <e2> <e3>e3Value</e3> <e4 e4Attr="attrValue4" e4Attrb="attrValue4b"> e4Value </e4> </e2> </myDoc>

pub.web:freeDocument

Description Frees the resources allocated to the given document. When using a NodeIterator to iterate over a document, the client may decide to stop reading the document before the entire document is read. The client can call web.pub:freeDocument to explicitly free the resources held by the document instead of waiting for Java garbage collection to occur. It is not necessary to call this method, but doing so can boost server performance. The document is left in an unfinished state and should not be used subsequently.

Package WmPublic


document Document An instance of com.wm.lang.xml.Document. Document whose resources you want to release.

Output None.

pub.web:getDocumentType

Description Returns document type information about a document.

Package WmPublic


document Object An instance of com.wm.lang.xml.Document. Document for which you want information.

pub.web:getNextNode



systemID String System identifier, as provided by the DTD contained in the document. If the document does not provide a system identifier, this value is null.

publicID String Public identifier, as provided by the DTD contained in the document. If the document does not provide a public identifier, this value is null.

rootNamespaceURI String URI of the XML namespace to which the document's root element belongs, if any.

rootNSPrefix String The namespace prefix of the rootLocalName, if any.

rootLocalName String Local element name (excluding the namespace prefix) of the root element of the document.

pub.web:getNextNode

Description Gets the next node from a NodeIterator. NodeIterator is acquired via the service getNodeIterator. Output is a IData object containing the element type name of the node and the node itself. The instance of this IData object is only valid until the next getNextNode call on the same NodeIterator, because getNextNode uses the same IData object for each call.

Package WmPublic


iterator Object An instance of com.wm.app.b2b.util.NodeIterator. The NodeIterator from which to retrieve the next node.


next IData Optional. A IData object containing the next node. Assumes a value of null when the NodeIterator has no more nodes to return.


name String Element type name of the node. If the element belongs to a namespace and the namespace was declared at the time the NodeIterator was constructed, name will have the prefix declared for that namespace. If the namespace is not declared, name will use prefix that occurs in the XML.

node Node Node identified by the input criteria array of the call to getNodeIterator that originally generated the NodeIterator.

It is possible that all calls to getNextNode on a given NodeIterator will yield the same IData object instance, where the values of the instance’s entries vary. For this reason applications should assume that each call to getNextNode invalidates the IData object returned by the previous call. The approach maximizes the speed of the server and minimizes the use of resources.



pub.web:getNodeIterator

Description Creates and returns a NodeIterator. A NodeIterator iterates over the element node descendants of a given node and returns the element nodes that satisfy the indicated criteria. The client application or flow service uses the service getNextNode( ) to get each node in turn. NodeIterators can only be created for XML nodes (not for HTML nodes). getNodeIterator is useful for loading and parsing documents on-demand. Large or slow documents need only be loaded as far as needed to get the desired data. NodeIterators are also useful for providing service as the pertinent information in the document arrives rather than first having to wait for the entire document to load. This service is primarily intended to deal with large documents or documents that arrive slowly. NodeIterator provides a moving window mode, in which the only node that is resident in memory is the last node returned by getNextNode( ). In this mode, when getNextNode( ) is called, all nodes preceding the newly returned node become invalid, including all nodes previously returned by getNextNode( ). The client must fully complete processing preceding nodes before advancing the window by calling getNextNode () again. In moving window mode, the document consumes at least enough memory to hold the most recently returned node. Moving window mode allows the server to process multi-megabyte XML documents using very little memory. Moving window mode may only be used on a node that represents an entire XML document and not on any descendant node.

Package WmPublic


node Object An instance of com.wm.lang.xml.Node. Node over which to iterate. The node must represent either an XML document or an element of an XML document. The parameter is constrained to be of type Document when used in moving window mode. This is because moving window mode is only meaningful for managing the loading process of a document, and to operate on a node, is to have already loaded the node.

criteria String [ ] Optional. This input parameter is a String[] of patterns identifying the nodes that the iterator is to return. A pattern may take either the form "<localName>" or the form "<prefix>:<localName>". When a pattern takes the first form, it identifies an element whose local name is <localName> and that belongs to the default XML namespace. When a pattern takes the second form, it identifies an element whose local name is <localName> and whose XML namespace is given by the prefix <prefix>. If the input parameter nsDecls declares this prefix, the namespace URI of the element must match the URI declared for the prefix. If the prefix is not declared in nsDecls, the prefix is matched against prefixes found in the XML. <prefix> and <localName> can each optionally take the value '*' (asterisk) to match any namespace or local name. A '*' prefix also matches elements residing in the default namespace. If the criterion is not specified, all element node children of the root element are returned.

pub.web:getNodeIterator



nsDecls Record Optional. A Record (an IData object) that declares the namespaces associated with any namespace prefixes that are used in criteria. In nsDecls, set key names to the prefixes that are used in criteria. Then, set the value of each key to the namespace that each prefix represents. For example, the following shows how nsDecls would look if it defined the namespaces associated with prefixes called GSX and TxMon:

movingWindow String Optional. Specifies whether the NodeIterator is to iterate using a

moving window, as described above. In moving window mode, the entire document preceding the node most recently returned by getNextNode is discarded. Subsequent attempts to return preceding portions of the document will return either the repeating text “*PURGED*” or the proper data, depending on whether the data falls within an area that the server was able to discard. When iterating with a moving window, the current node should be queried and completely examined prior to requesting the next node. Valid values are true and false. When absent, a value of false is assumed.


iterator NodeIterator An instance of com.wm.app.b2b.util.NodeIterator. A NodeIterator for use with the service getNextNode.



pub.web:loadDocument

Description Retrieves a specified XML or HTML document via HTTP or HTTPS and returns a parsed Document object that can be used as input to any service that accepts a node.

Package WmPublic


url String Specifies the URL of the document you want to load. This string must begin with http: or https:

Examples http://www.rubicon.com/orders/orders.html

https://localhost:5555/WmPublic/index.html

method String Specifies the HTTP method you want loadDocument to use. You must set method to either get or post.

auth IData Optional. Specifies authorization information that loadDocument will submit if the resource specified in url is protected.


type String Type of authentication you want loadDocument to use to submit this request. Currently, only basic authentication is supported. If you are accessing a protected resource, set auth to Basic.

user String The user name that loadDocument will submit when it requests a protected resource.

pass String The password associated with user.

data IData Optional. Specifies data that you want loadDocument to submit with the HTTP request. Specify your data in one or more of the following elements. Note: When you use more than one element to submit data with loadDocument, args is appended first, table is appended second, and string is appended last.


args IData Specifies name=value pairs that you want loadDocument to submit to the resource in url.

You can use args to submit data via either the POST or GET method. To specify data using args, create one element for each name=value pair that you want to submit, where:



The element’s name represents the name portion of the pair, and…

The element’s value represents the value portion of the pair.

Note that when you use args, loadDocument will:

automatically URL-encode name=value pair, so you do not need to url-encode the values you specify in args.

automatically insert the “&” character between pairs, so you do not need to include it in args.

automatically prefix the entire query string with the “?” character if it submits the data in args via a GET. You do not need to include this character in args.

When you submit data using the args variable, the SAP BC automatically sets the value of the Content-Type header to application/x-www-form-urlencoded. If you want to explicitly specify a different Content-Type, you must submit your data using the string or bytes variable.

table String[ ][ ] Specifies data that loadDocument will use to construct a query string to submit to the resource specified in url. table is similar to args, but it allows you to submit unnamed values in a query string, not just name=value pairs. To specify data using table, create one row for each value that you want to submit, where:

The contents of column 0 represents the name portion of the pair (leave this column null to submit an unnamed value, and…

The contents of column 1 represents the value portion of the pair.

When you submit data using the table variable, the SAP BC automatically sets the value of the Content-Type header to application/x-www-form-urlencoded. If you want to explicitly specify a different Content-Type, you must submit your data using the string or bytes variable.



Note that when you use table, loadDocument will:

Automatically URL-encode name=value pair, so you do not need to URL-encode the values you specify in table.

Automatically insert the “&” character between the pairs (or unnamed values) that it constructs, so you do not need to include it in table.

Automatically prefix the entire query string with the “?” character if it submits the data in table via the GET method. You do not need to include this character in table.

string String Specifies a string of text that you want loadDocument to submit to the resource in url.

You can use string to submit data via either the POST or GET method.

If you use string to specify data you want loadDocument to submit, make sure that you specify the string exactly as you want it presented in the HTTP request. (If you are using the GET method, make sure you URL-encode the contents of string). When performing a POST the string will be submitted to the resource defined by url as the body of the document.

bytes byte[ ] Specifies an array of bytes that you want loadDocument to submit to the resource in url.

You can only use bytes to submit data via the POST method.

Note: When you use bytes and another element (args, table, or string) to submit data with loadDocument, the service appends the data from the args, table, or string element to url. The service appends args to url first, table second, and string last. The service encodes the data from the bytes element in the body of the post.

encoding String The name of a registered, IANA character set.



headers IData Optional. Specifies fields that you want to explicitly override in the HTTP request header issued by loadDocument. Specify one element in the headers IData object for each header field that you want to set, where: The element’s name represents the name of the header field, and…

The element’s value represents the value of that header field. If headers is not set, loadDocument will use its default header values.

encoding String The character set in which the returned document is encoded. The parser requires this value in order to interpret a document correctly.

Set encoding to… To…

autoDetect Determine the document’s character set based on document type, where:

ISO-8859-1 is used for HTML UTF-8 is used for XML

Set encoding to… To…

The name of a registered IANA character set

Decode the document using that character set.

Example ISO-8859-1 If you do not specify an encoding value, loadDocument decodes the

returned document using the following defaults:

If the document is… It is decoded using…

HTML ISO-8859-1 XML UTF-8

expandDTD String Determines whether or not loadDocument processes references to parameter entities in the returned document’s DTD.

Set expandDTD to… To…

true Expand references to parameter entities to their full definition.

false Default. Ignore references to parameter entities in the document’s DTD.

isXML String Specifies whether the returned document is XML or HTML. loadDocument must know this in order to parse a document correctly.

Set isXML to… To…

autoDetect Default. Parse the document based on its type. When you use this option, loadDocument senses the document’s type based on its <!DOCTYPE…> or <?XML…> tag. If it cannot determine a document’s type, it parses it as HTML.

true Parse the document as XML. false Parse the document as HTML.

loadAs String Specifies the form in which you want loadDocument to make the parsed document available to subsequent services.




bytes Pass the parsed document as a byte array. Use this option if the document will be used as input to a service that operates on whole documents (for example, queryDocument).

stream Pass the parsed document as an input stream. Use this option if the document will be used as input to a service that can process a document incrementally (for example, getNodeIterator).

failOnHTTPError

String Determines whether or not loadDocument should fail (throw an exception) if the desired URL it not loaded correctly based on an HTTP status code. This parameter allows for customized error handling of the load failure.

Set exception to… To… true Throw a service exception if the URL is not

loaded as indicated by an HTTP status code between 400 and 599, inclusive.

false Default. Ignore HTTP errors. If there is an error, the HTML page returned by the web server will be sent to the parser.


node Document Document object containing the parsed HTML or XML document. This object can be used as input to any service that accepts a node.

Usage Notes If pub.web:loadDocument does not receive a response within the timeout period specified in the server’s watt.net.timeout parameter, it will throw an exception. For information about the watt.net.timeout parameter, see the SAP BC Administration Guide.

pub.web:makeArrays


pub.web:makeArrays

Description Produces a String[ ] that can be sent to pub.web:documentToRecord based on the values in the document’s DTD.

Package WmPublic


node Object An instance of com.wm.lang.xml.Node. Any node in a parsed Document object (node can be produced by loadDocument, stringToDocument, or XML content handlers).


arrays String[ ] Array of element names for each repeating element in the document. This variable will be null if the document’s DTD is not found or if there are no DTD references in the document specified by node.

pub.web:queryDocument

Description Executes queries on a document, region, or node to generate output variables. Each field specifies how data is extracted from the document to yield an output variable. This output variable may be called a binding, because the field parameter binds a certain part of the document to an output variable. An invocation must include at least one field entry. The fields parameter can contain nested definitions of fields, which will produce a nested binding as the

result. If a fields parameter is to create an instance of each of the children for each result, it should have

resultType Record[]. If a fields parameter is to create only a set of children for the first result value, it should be defined with

resultType Record. If a fields parameter has any children, its query must return a node object and be defined as resultType

Record or return a node array and be defined as resultType Record[ ]. If a parent has no query, the children query the same node that the parent would have, allowing you to

group child results into a Record or Record []. If the parent returns a node, each child queries that node (and only that node) once and fills the IData

object. In this case, the parent must be defined as returning a Record (not an Object). If the parent returns a node array, each child queries each node once and fills the IData[ ] object. In this case, the parent must be defined as returning Record[] (not an Object[]).The result of each root field (top-level parent) is put into the pipeline in a variable named for the field name. Child fields cannot reference a region unless the parent node has no query and the input node is set to a region.

Package WmPublic


node

Node Document Region

The node that you want to query. (A node is produced by loadDocument, stringToDocument, createRegions, or one that the SAP BC content handlers.)




nsDecls Record Optional. A Record (an IData object) that declares the namespaces associated with any namespace prefixes that are used when an element is specified in fields.query. Within nsDecls, set the key names to the prefixes that you used in fields.query. Then set the value of each key to the namespace that the prefix represents. For example, the following shows how nsDecls would look if it defined the namespaces associated with prefixes called GSX and TxMon:

fields Record [ ] Optional. Each field defines how a value is extracted from a document.

This parameter defines fields for the values that are to be extracted. Each field is defined as follows:


name String Name to assign to resulting value.

resultType String Primitive type of the value or values that the query is to yield. Valid values are Object, Object[], Object[][], String, String[], and String[][].

query String Query identifying the value to return.

queryType String Query language in which the query for the value is expressed. Valid values are WQL and XQL.

onnull String Specifies what you want queryDocument to do when the result is null: continue—All result values are legal. fail—If the result of the query is null, the service fails. If the result of the query is not null, the service continues. succeed—If the result of the query is null, the service continues. If the result of the query is not null, the service fails.

fields IData[ ] A nested set of fields parameters that support recursive execution of bindings. Each array of fields Records define bindings for one level of the output with the top level being the pipeline and the first level down being contents of a IData or IData[ ] object that is in the pipeline.

Output IData object defined by the fields input specifications. There will be one output variable for each field specified with nested IData objects for the results of the child fields.

pub.web:recordToDocument



Description Converts a IData object to a String of XML. This service recurses through a given IData object, building and XML document from the elements within it. Key names are turned into XML elements and the key values are turned into the contents of those elements.

This service would convert this IData... To an XML document that looke like this...

<?xml version="1.0" ?>

<AcctInfo>

<name>Midwest Extreme Sports</name>

<rep>Laura M. Sanchez</rep>

<acctNum

type=platinum>G97041A</acctNum>

<phoneNum cc=011>216-741-

7566</phoneNum>

<address county=USA>

<street1>10211 Brook

Road</street1>

<city>Cleveland</city>

<state>OH</state>

<postalCode>22130</postalCode>

</address>

<serialNum>19970523A</serialNum>

<serialNum>20001106G</serialNum>

<serialNum>20010404K</serialNum>

</AcctInfo>

Note that key names that start with the attribute prefix (which, in this example, is the ‘@’ character) are turned into attributes of the elements in which they occur. For example, the @type key in the acctNum element is converted to the type=platinum attribute of the <acctNum> element in the output document. Also note that the *body key is used to represent the value of a simple element that contains both a text value and an attribute. See the acctNum and phoneNum keys for an example of this kind of element.

Package WmPublic


attrPrefix String Optional. A String specifying the prefix that designates keys containing attributes. The default prefix is “@”.

For example, if you set attrPrefix to ATT_ and boundNode contained the following element:

recordToDocument would convert the ATT_currency key to the attribute, currency=dollars, in the <tx> element as shown below:

<tx currency=dollars> <acct>cash</acct> <amt>120.00</amt> </tx>

addNSPrefix Optional. If set to true and recordName is set to a valid value as well, the records information about XML namespaces is used to automatically generate a namespace definition within the XML



document, and use the defined prefix for fields and records if necessary according to the record definition. If nsdecls is given, those prefixes are preferred to generated ones. (Default:"false")

boundNode IData The IData object that is to be converted to XML. Note that if you want to produce a valid XML document (one with a single root node), boundNode must contain only one, top-level IData object (i.e., a single Record). The name of that IData object will serve as the name of the root element. For example, boundNode shown in Description above contains one, top-level IData named AcctInfo, which would result in one root element named <AcctInfo> in the output document. If you needed to produce an XML fragment—e.g., a loose collection of elements that are not encompassed within a single root element—then boundNode can contain multiple, top-level elements. To produce this type of output, you must also set the addHeader and enforceLegalXML parameters to false.

nsDecls Record Optional. A Record (an IData object) that declares the namespaces associated with any namespace prefixes that you used in the key names in boundNode. In nsDecls, set the key names to the prefixes that you are used in boundNode. Then set the value of each key to the namespace that the prefix represents. For example, the following shows how nsDecls would look if it defined the namespaces associated with prefixes called GSX and TxMon:

For each prefix specified in nsDecls, recordToDocument

generates an xmlns attribute and inserts it into the top-most element in the output document. For example, if nsDecls had the two keys shown above, recordToDocument would insert the following attributes into the root element in the output document:

xmlns:gsx="http://www.gsx.com"

xmlns:TxMon="http:www.acrtrak/txMonitor"

Note: You can also include a namespace declaration in your output document via an @xmlns key in the boundNode (you would, of course use the correct attribute prefix in your code if you weren't using the @ character to designate keys representing attributes.) The advantage of use this approach over nsDecls is that it lets you specify the point where you want the xmlns attribute inserted.

addHeader String Optional. Specifies whether the header element: <?xml version=”1.0”?> is to be included in the output document.

Set to… To..

true Default. Include the header.



false Omit the header. (You would omit the header when generating an XML fragment or when you need to insert a custom header.)

encode String Optional. Specifies whether the data should be HTML-encoded or not.

Set to… To..

true HTML encode the data. false Default. Do not HTML-encode the data.

recordName String Optional. The fully qualified name of a saved Record, which describes the format of the output document, including elements that may not be present in the document represented by boundNode. It also specifies the order in which elements are to appear in the output document. Example examples.rtd:exampleRecord1

generateRequiredTags String Optional. If recordName is specified, determines whether or not empty tags are to be included in the output document when a mandatory element appears in the specified Record definition, but does not appear within the IData in boundNode.

Set to… To… true Include mandatory elements if they aren’t

present in boundNode. false Default. Omit mandatory elements if they are not

present in boundNode.

enforceLegalXML String Optional. Specifies whether the service throws an exception when boundNode contains multiple root elements or illegal XML tag names.

Set to… To… true Throw an exception if boundNode would

produce a XML document containing multiple root elements and/or illegal XML tag names.

false Default. Allow the output document to contain multiple root elements and/or illegal XML tag names. You would use this setting to create an XML fragment composed of multiple elements that were not all enclosed within a root element.

dtdHeaderInfo IData Optional. An IData object that defines the contents of the DOCTYPE header that is to be inserted into the output document. (You can retrieve this information from an incoming document using pub.web:getDocumentType.) Set the following elements in dtdHeaderInfo.

Element Description

systemID Optional. A String specifying the system identifier for the DTD, if any.

publicID Optional. A String specifying the public identifier for the DTD, if any.



Element Description

rootNSPrefix Optional. A String that specifies the namespace prefix of the rootLocalName, if any.

rootLocalName Optional. A String that specifies the local element name (excluding the namespace prefix) of the root element of the document.

bufferSize String Optional. A String that specifies the initial size of the String buffer (in bytes) that recordToDocument uses to assemble the output document. If the String buffer fills up before recordToDocument is finished generating the output document, it reallocates the buffer, expanding it by this amount each time the buffer becomes full. If you do not set bufferSize, recordToDocument looks to see whether a default buffer size is specified in the following parameter on the server: watt.server.recordToDocument.bufferSize

If so, it uses this value to allocate the String buffer. If this parameter is not set, recordToDocument uses a default buffer size of 4096 bytes. For best performance, you should always set bufferSize to a value that closely matches the size of the XML document that you expect recordToDocument to produce. This practice will spare the server from having to repeatedly enlarge the buffer if the output document is many times larger than the default buffer or if you arbitrarily set bufferSize to a value that is too small. Setting bufferSize to an appropriately-sized value will also prevent your service from unnecessarily consuming more memory than it needs if the document is much smaller than the default buffer size or you set bufferSize to an arbitrarily large value.

processingInstructions IData Optional. An IData object that includes processing instructions to be written the document Example: key = "soxtype" value = "urn:x-commerceone:document:com:commerceone:XCBL30:XCBL30.sox$1.0" will be added to the document as: <?soxtype urn:x-commerceone:document:com:commerceone:XCBL30:XCBL30.sox$1.0?>


pub.web:stringToDocument


xmldata String The XML document produced from boundNode.

Usage Notes If you are building an IData that will be converted to an XML document, keep the following points in mind:

If you want to generate a simple element that contains only a character value, represent it with a String element in boundNode as shown in the following:

If you want to generate an element that contains children, represent with an IData in boundNode, as shown in the following.

If your document includes attributes, you must put their values in keys whose name starts with the character(s) specified in attrPrefix. For example, if you use the default attrPrefix, the names of all keys containing attributes (and only those keys containing attributes) must start with the @ character (e.g., @type, @xmlns). When you include attributes, make sure that keys representing attributes are direct children of the elements in which they are to be applied. For example, if you wanted to include an xmlns attribute to the <AcctInfo> element in the example shown in Description above, you must create a String element named @xmlns in the AcctInfo element within boundNode.

If you want to generate a simple element that contains a character value and one or more attributes, you must represent it as an IData that has one key for each attribute and a key named *body that contains element’s value. For example, if you wanted to produce the following element:

<phoneNum cc=011>216-741-7566</phoneNum>

You would include the following IData in boundNode:

If your document includes namespaces, make sure you do the following: Include the appropriate namespace prefix in the key names in boundNode. For example, if your

document has an element called “acctNum,” and it is supposed to be associated with the namespace represented by the “GSX” prefix, the key name for that element must appear as GSX:acctNum in boundNode.

Define the URIs for the prefixes that appear in boundNode. You can do this through nsDecls or by including an @xmlns key in the element where you want the xmlns attribute to be inserted. See the nsDecls above for more information about declaring namespaces.


Description Converts a text string representing an XML document into a Document object.

Package WmPublic




xmldata String Optional. Java String to convert to a document.

$filedata byte[ ] Optional. Input as a byte array to convert to a document.

$filestream Object Optional. Input as a Java InputStream to convert to a document.

encoding String Optional. Character encoding in which text is represented to use when parsing the document. Specify UTF-8 for XML files and ISO-8859-1 for HTML files. To have the parser attempt to detect the type of encoding, specify autoDetect.

expandDTD String Optional. Determines whether or not loadDocument processes references to parameter entities in the returned document’s DTD.

Set expandDTD to… To… true Expand references to parameter entities to their

full definition. false Default. Ignore references to parameter entities

in the document’s DTD.

isXML String Optional. Specifies whether the returned document is XML or HTML. loadDocument must know this in order to parse a document correctly.

Set isXML to… To…

autoDetect Default. Parse the document based on its type.

When you use this option, loadDocument detects the document’s type based on its <!DOCTYPE…> or <?XML…> tag. If it cannot determine a document’s type, it parses it as HTML.

true Parse the document as XML.

false Parse the document as HTML.


node Document Document object representing the parsed document. The output can by input into any service that accepts a node.


Chapter 31 WebTap Services

You use this service to build services that monitor HTTP requests and conditionaactions based on a URL requested by a client that combine manual and automatedHTTP requests—letting some requests “pass through” to the target server and intehandling.

Notice! The components in this folder have been deprecated and are earmarked forSAP BC.

1
3
lly executes a prescribed set of interactions, by letting you filter rcepting others for special

removal in a future version of the

C H A P T E R 3 1 W e b T a p S e r v i c e s




Service Function pub.webtap:getPage Deprecated. Maps all URLs of the supplied page so that subsequent requests go back

through this service.

pub.webtap:triggerSpec Deprecated. Specifies the signature for “trigger” services invoked by the WebTap rules engine. Use this specification when you create such services in Developer.

pub.webtap:getPage


pub.webtap:getPage

Description Deprecated. Maps all URLs of the supplied page so that subsequent requests go back through this service. This service can be used to test WebTap’s URL-mapping abilities on a particular site. It may also be sufficient for some applications that only need WebTap in order to utilize HTTP authentication information in order to access links from protected Web pages. This service is only for use by Browser clients. Also, customized WebTap capabilities, such as rules engine or custom triggers, are only available via user-generated WebTap services.

Package WmPublic

Input Variable Name Description

reqUrl Web page URL that will be retrieved and mapped before being returned to the caller’s browser.

mapJS Optional. Specify “true” to have JavaScript-manipulated URLs mapped. Note that this feature handles many common cases; however, it does not handle URLs defined in document.write() or eval() blocks.

Output None.

Usage Notes If you invoke this service from the Browser’s command line⎯rather than SAP BC Developer⎯make sure to URL encode any prohibited characters within the reqUrl argument. Example

http://localhost:5555/invoke/wm.pub/getPage?reqUrl=http%3A%2F%2Fquote.yahoo.c

om%2F

pub.webtap:triggerSpec

Description Deprecated. Specifies the signature for “trigger” services invoked by the WebTap rules engine. Use this specification when you create such services in Developer. The signature provides identical inputs and outputs so that the data and the control options are available for one service or a sequence of services.

Package WmPublic


WebtapData Values Values object (Record) containing all inputs to WebTap service (e.g., reqUrl and other variables in the query string or cgi post data. The elements of this Record are unspecified, as they vary for each WebTap request.

WebtapControl Values Values object (Record) containing control variables that identify the current request and can be used to redirect the flow of the WebTap request. The variables are specified below.

reqUrl String Corresponds to the requested Web page, i.e., as specified in pub.webtap:getPage. Modify to redirect request.

reqVals Values Null. Set to provide substitute inputs when redirecting to a different URL.

C H A P T E R 3 1 W e b T a p S e r v i c e s



rspUrl String Null. Set on response (read-only) if the request was redirected to indicate the URL of returned page.

rspVals Values Null. Set to Values object (Record) to interrupt normal WebTap sequence and force return of alternate data either on request or response.

rspTemplate String Null. Set to name of template to use in formatting alternate response data set via rspVals.

rspTxt String Null. Set to HTML text to interrupt normal WebTap sequence and return this data instead either on request or response. Alternative to using rspVals and rspTemplate.

authUser String Null. Set HTTP authentication info (username) on request for protected pages.

authPwd String Null. Set HTTP authentication info (password) on request for protected pages.

authUrl String Null. Set HTTP authentication info (url) on request for protected pages.

mapImages String Default is true. Set to “false” on request to leave image URLs unmapped (use only if images are not password-protected).

mapPage String Default is true. Set to “false” on request to exit WebTap by not mapping the returned pages’ URLs.

mapJavaScript String Default is false. Set to “true” to map JavaScript found in the page. Note that this mapping handles many common cases of dynamic JavaScript URL creation; however, it does not handle document.write() and eval() blocks that involve URL definition.

showEmbed String Contains the string true or false, specifying whether WebTap will transform the URLs associated with <EMBED> elements.

Set showEmbed to… If you want WebTap to…

true Remap the URLs associated with <EMBED> elements to fully-qualified Web addresses. This setting enables the requestor’s browser to retrieve the embedded resource from the page returned by your WebTap service

false Default. Strip attributes from <EMBED> elements, which will prevent embedded resources from appearing in the page returned to the requestor.

showApplet String Contains the string true or false, specifying whether WebTap will transform URLs associated with <APPLET> elements.

pub.webtap:triggerSpec


Set showApplet to… If you want WebTap to… true Remap the URLs associated with

<APPLET> to fully-qualified Web addresses. This setting enables the requestor’s browser to retrieve the applet from the page returned by your WebTap service

false Default. Strip attributes from <APPLET> elements, which will prevent applets from appearing in the page returned to the requestor.

showObject String Contains the string true or false, specifying whether WebTap will transform URLs associated with <OBJECT> elements.

Set showObject to… If you want WebTap to… true Remap the URLs associated with

<OBJECT> elements to fully-qualified Web addresses. This setting enables the requestor’s browser to retrieve the object from the page returned by your WebTap service.

false Default. Strip attributes from <OBJECT> elements, which will prevent objects from appearing in the page returned to the requestor.

matchSSL String Contains the string true or false, specifying whether WebTap should map https-based URLs to https-based aliases.

Set matchSSL to… To… true Use an SSL connection between the

client and the SAP BC server when linking to a site whose URL specifies the https protocol.

false Default. Not use an SSL connection between the client and the SAP BC server when linking to a site whose URL specifies the https protocol.

Important! Before using this option, verify with your server administrator that an https listener is configured on your SAP BC server.

node Object An instance of com.wm.lang.xml.Document. Contains a parsed representation of the HTML document retrieved by WebTap (before URL mapping occurs). You can use this document as input to any service that accepts a node as input (e.g., queryDocument).

INDEX


INDEX

A

activatePackage 163 add 256 addBodyEntry 240 addBodyPart 147 addComplexTask 197 addFloatList 141 addFloats 141 addHeaderEntry 240 adding body parts to MIME messages 147 adding LDAP server entries 122, 125 adding MIME message headers 150 adding numeric values 141 adding Records to list 135 adding strings to list 135 addIntList 141 addInts 141 addMimeHeader 150 addOnetimeTask 198 addReleaseRegistryEntry 183 addRepeatingTask 199 addTrailer 242 Administration Guide 19 alarm specification 86 alarmInfo Record 86 API-related documentation 19 append 30 appendToRecord 135 appendToStringList 135 arithmetic services 139 attributes

definition 108, 109, 127 modifying in LDAP entries 132

audit events, logging 87 audit log, event logging 87 audit specification 87 auditInfo Record 87

B

base64Decode 267 base64Encode 267 bind 122, 125 binding output template to Values object 192 bindings, listing 128 byte array from string 274

bytesToString 268

C

call 44, 54 callStackItem Record 88 cancelTask 200 cd 30 cdls 31 certs-only S/MIME Message

creating 227 extracting certificates from 231

clearing transactional state 55 clearKeyAndChain 215 clearPipeline 113 clearTransaction 55 client services 21 close 56 closeAll 57 closeStore 256 commit 57 complex tasks

adding to scheduler 197 updating to scheduler 203

concat 268 concatenating an array of strings 269 concatenating strings 268 connect

LDAP 122, 125 pub.db 57

connections, closing 126 content type, getting from MIME message 154,

230 conventions used in this document 17, 18 converting

date formats 73 string list to Record list 138 time formats 73

Converting parsed documents to IData objects 292

copyListItem 135 createCertsOnlyObject 227 createEncryptedData 227 createMessageDigest 218 createMimeData 151 createSignedAndEncryptedData 228 createSignedData 229 createSoapData 242

INDEX


createXSD 209 creating MIME messages 151 currentDate 77

D

data stores adding entries 256 closing 256 deleting 256 inserting entries 258 registering 259 removing entries 257, 259 retrieving values 257 unlocking entries 258, 259 unregistering 256 updating entries 258

database connection, closing 56, 57 database services 42, 45, 52 databases

clearing transactional state 55 closing connections 56, 57 committing changes 57 creating connections 57 discarding changes 69 invoking stored procedures 44, 54 retrieving names of stored procedures 63 retrieving tables 65 starting a transaction 70

datatypes 212 date/time transformation services 73 dateBuild 77 dates

converting formats 78 invalid dates 76 returning current 77 symbols used for 74 time zones 75

dateTimeBuild 78 dateTimeFormat 78 debug log 113 decoding URL-encoded strings 266 decrypting MIME messages 231 delete

client.ftp 31 db 59 LDAP 126

deleteReleaseRegistryEntry 184 deleteStore 256 deleteSubscriber 88 deleting data stores 256 deleting subscribers from subscription list 88 digital signatures

attaching to MIME messages 229 verifying 232

directory server looking up entries 130

directory, searching for entries 130 disablePackage 163 disconnect 126 distributeViaFTP 184 distributeViaSvcPull 185 distributeViaSvcPush 185 divideFloats 142 divideInts 142 do not use

pub.Idap:init 128 shutdown 132

Document objects as output from loadDocument 302 creating from XML documents 313

documentation conventions used 17 printing 20 related manuals 18 viewing 19

documents executing queries on 307 retrieving from a local file system 105 returning document type info 298

documentToRecord 292 dynamic text generation 192

E

elements number of in a list 138 replacing in an object list 137

enablePackage 164 encoding schema. SOAP 240 encoding URL strings 267 encrypting MIME messages 227, 228 end 176 ending guaranteed delivery transactions 176 entries

adding to LDAP server 122, 125 inserting into repository 256 looking up single 130 searching for all matching 130

envelope schema, SOAP 240 error log, exception events 90 event handlers 81

alarm specification 86 alarmInfo Record 86 audit specification 87 audit:logToFile service 87

INDEX


auditInfo Record 87 callStackItem Record 88 exception specification 89 exception:logToFile service 90 exceptionInfo Record 89 gdEnd specification 90 gdEndInfo Record 91 gdStart specification 91 gdStartInfo Record 91 get list of event types 92 get list of subscribers 92 listenerStatus specification 98 modify subscriber info 93 portStatus specification 96 portStatusInfo Record 96 reload event manager settings 97 replicationInfo Record 98 save event manager settings 98 sessionEnd specification 98 sessionEnd:logToFile service 99 sessionEndInfo Record 99 sessionExpire

logToFile service 99 sessionExpire specification 99 sessionExpireInfo Record 100 sessionStart

logToFile service 100 sessionStart specification 100 sessionStartInfo Record 101 stat specification 101 statInfo Record 102 stats:logToFile service 103 txEnd specification 103 txEndInfo Record 103 txStart specification 103 txStartInfo Record 104 unsubscribing from an event 88

exception events, logging 90 exception specification 89 exceptionInfo Record 89 exceptions

last trapped in a flow 113 execSQL 60 exitUnableToUnderstand 243 extracting MIME content 153 extracting MIME message headers 154, 156

F

fields, removing from pipeline 113 file object, templates 191 file services 105 files

appending data to 30 deleting 31 listing 31 multiple delete 34 multiple get 34 multiple transfer 35 rename 36 retrieving 32, 107 saving pipeline contents 116 transfer 35, 36

find, universal names 287 flow services 111 forcing a response string 116 formatting

array of strings 270 number to numeric pattern 270, 271

freeDocument 298 FTP

changing directory and listing files 31 changing working directory 30 client actions 23 delete file 31 file transfer 35, 36 listing files 33 login 32 logout 33 multiple file delete 34 multiple file get 34 multiple file transfer 35 rename file 36 retrieving files 32 session info for all logged into servers 36

FTP servers, submitting requests to 21

G

gdEnd specification 90 gdEndInfo Record 91 gdstart specification 91 gdStartInfo Record 91 generateReplicationEvent 185 get 32 getActor 243 getAttributeDef 108, 109, 127 getBody 244 getBodyEntries 244 getBodyPartContent 153 getBodyPartHeader 154 getBodyPartSubType 157, 158 getCertificateInfo 218 getClassDef 127 getContentType 154, 230 getDocument 245

INDEX


getDocumentType 298 getEnvelopeStream 155 getEventTypes 92 getFile 107 getHeader 245 getHeaderEntries 246 getLastError 113 getListItem 136 getLocalReleasedList 186 getMimeHeader 156 getMustUnderstand 246 getNextNode 299 getNodeIterator 300 getNumParts 157 getPage 319 getProcInfo 62 getProcs 63 getQName 248 getRecordListItem 136 getRemoteReleasedList 186 getSession 114 getStatus 176 getStringListItem 137 getSubscribers 92 getTableInfo 64 getTables 65 getTaskIDs 200 getTaskInfo 200 getTrailer service 248 getTransportInfo 114 guaranteed delivery services 173 guaranteed delivery transactions

ending 176 getting status of 176 invoking service 177 restarting 177 retrieving results of 177 starting 178

guaranteed one-way call 179

H

headers, changing HTTP 24 HTML documents

converting to IData objects 292 HTML documents, loading 302 HTMLDecode 266 HTMLEncode 266 HTTP

changing header variables 24 submitting requests to servers 21

I IData objects

converting to XML documents 309 IDs, retrieving list of 200 indexOf 268 init (do not use) 128 insert 67 installPackage 164 invalid dates 76 invoke, guaranteed delivery service 177 invoke, remote service 175 invoking 177

client services 21 emote services 173 report services 189 stored procedures 44, 54 string services 263

invoking a service guaranteed delivery 179 protocols used 117 remote SAP BC server 175

iterating through XML nodes 300

J

JDBC-related services 42, 45, 52

K

key string lookup 269 keys 257

L

LDAP server adding entries 122, 125 closing connections 126 connecting to 122, 125 deleting entries 126

LDAP services 120, 123 length 169, 268 list

LDAP 128 number of elements 138

list services 133 list, registered processors 238 list, universal names 287 loadDocument 302 loadPKCS7CertChain 219 locking a repository entry 258 logging

audit events 87 exception events 90

INDEX


session-end events 99 status events 103

login 32 logout 33 logToFile, audit events 87 logToFile, exception events 90 logToFile, server statistics 103 logToFile, session-end events 99 logToFile, session-expire events 99 logToFile, session-start events 100 lookup 130 lookupDictionary 269 lookupTable 269 lowercase, converting to 275 ls 33

M

makeArrays 307 makeString 269 math services 139 mdelete 34 mergeHeaderAndBody 158 messageFormat 270 mget 34 MIME 28 MIME messages

adding body parts to 147 adding headers to 150 creating 151 creating encrypted messages 227 creating signed and encrypted messages 228 creating signed messages 229 decrypting 231 discovering content type 154, 230 discovering number of parts 157 discovering subtype 157, 158 generating message stream 155 getting content from 153 getting headers from 156 getting part headers from 154 merging HTTP response into InputStream 158 verifying signed messages 232

MIME services 145 minput 35 modifySubscriber 93 multiplyFloatList 142 multiplyFloats 142 multiplyIntList 143 multiplyInts 143

N

namespace components 212

node iterator creating 300 freeDocument 298 getNextNode 299 getNodeIterator 300

nodes, executing queries on 307 notify 279 notifyPackageRelease 187 numeric values

adding 141, 142 dividing 142 multiplying 142, 143 subtracting 143, 144

numericFormat 270, 271

O

object lists copying elements 135 replacing elements in 137 retrieving elements from 136

objectclass definitions 127 one-time tasks

adding to scheduler 198 updating to scheduler 205

one-way call, guaranteed 179 output templates

applying to Values object 189 using with non-browser clients 189

P

package services 161 packageCreation 187 packages

activating 163 disabling 163 enabling 164 installing 164 recovering 165 reloading 166

padLeft 272 padRight 273 pattern strings

date patterns 74 pipeline

inserting Session object 114 removing fields 113 restoring previously saved 114 saving contents to a file 116 saving into memory 115 tracing 117 using previously saved keys and values 115 validating 207

INDEX


validating using a Record 211 pipeline services 111 portStatus specification 96 portStatusInfo Record 96 printing this guide 20 processCertsOnlyData 231 processEncryptedData 231 processSignedData 232 program code conventions 18 protocols

information about for invoke flow 114 invoking a service, info about 117

pseudorandom number generator 143 pub.cient

soapHTTP 37 soapRPC 39

pub.client ftp 23 http 24 smtp 28

pub.client.ftp append 30 cd 30 cdls 31 delete 31 get 32 login 32 logout 33 ls 33 mdelete 34 mget 34 mput 35 put 35, 36 rename 36 sessioninfo 36

pub.date currentDate 77 dateBuild 77 dateTimeBuild 78 dateTimeFormat 78

pub.db call 44, 54 clearTransaction 55 close 56 closeAll 57 commit 57 connect 57 delete 59 execSQL 60 getProcInfo 62 getProcs 63 getTableInfo 64 getTables 65

insert 67 query 68 rollback 69 startTransaction 70 update 70

pub.event alarm 86 alarmInfo 86 audit 87 auditInfo 87 callStackItem 88 deleteSubscriber 88 exception 89 exceptionInfo 89 gdEnd 90 gdEndInfo 91 gdstart 91 gdStartInfo 91 getEventTypes 92 getSubscribers 92 modifySubscriber 93 portStatus 96 portStatusInfo 96 reloadEventManagerSettings 97 replication 98 replicationInfo 98 saveEventManagerSettings 98 sessionEnd 98 sessionEndInfo Record 99 sessionExpire 99

logToFile 99 sessionExpireInfo 100 sessionStart 100

logToFile 100 sessionStartInfo Record 101 stat 101 statInfo 102 txEnd 103 txEndInfo 103 txStart 103 txStartInfo 104

pub.event.audit logToFile 87

pub.event.exception logToFile 90

pub.event.sessionEnd logToFile 99

pub.event.stats logToFile 103

pub.file getFile 107

pub.flow clearPipeline 113

INDEX


debugLog 113 getLastError 113 getSession 114 getTransportInfo 114 restorePipeline 114 restorePipelineFromFile 115 savePipeline 115 savePipelineToFile 116 setResponse 116 tracePipeline 117 transportInfo 117

pub.ldap bind 122, 125 connect 122, 125 delete 126 disconnect 126 getAttributeDef 108, 109, 127 getClassDef 127 init (do not use) 128 list 128 lookup 130 search 130 shutdown (do not use) 132 update 132

pub.list appendToRecordList 135 appendToStringList 135 copyListItem 135 getListItem 136 getRecordListItem 136 getStringListItem 137 setListItem 137 setRecordListItem 137 setStringListItem 137 sizeOfList 138 stringListToRecordList 138

pub.math addFloatList 141 addFloats 141 addIntList 141 addInts 141 divideFloats 142 divideInts 142 multiplyFloatList 142 multiplyFloats 142 multiplyIntList 143 multiplyInts 143 randomDouble 143 subtractFloats 144 subtractInts 143, 144

pub.mime addBodyPart 147 addMimeHeader 150

createMimeData 151 getBodyPartContent 153 getBodyPartHeader 154 getContentType 154, 230 getEnvelopeStream 155 getMimeHeader 156 getMultipartSubType 157, 158 getNumParts 157 mergeHeaderAndBody 158

pub.packages activatePackage 163 disablePackage 163 enablePackage 164 installPackage 164 recoverPackage 165 reloadPackage 166

pub.record length 169 recordListToRecord 169 recordToRecordList 170 recordToXMLValues 170 XMLValuesToRecord 171

pub.remote invoke 175

pub.remote.gd end 176 getStatus 176 invoke 177 restart 177 retrieve 177 send 179 start 178 submit 179

pub.replicator addReleaseRegistryEntry 183 deleteReleaseRegistryEntry 184 distributeViaFTP 184 distributeViaSvcPull 185 distributeViaSvcPush 185 generateReplicationEvent 185 getLocalReleasedList 186 getRemoteReleasedList 186 notifyPackageRelease 187 packageCreation 187

pub.report runFileTemplate 191 runFileTemplateOnPipe 191 runStringTemplate 191 runStringTemplateOnPipe 192 runTemplate 192 runTemplateOnPipe 192

pub.scheduler addComplexTask 197

INDEX


addOnetimeTask 198 addRepeatingTask 199 cancelTask 200 getTaskIDs 200 getTaskInfo 200 resumeTask 202 suspendTask 202 updateComplexTask 203 updateOneTimeTask 205 updateRepeatingTask 205

pub.schema createXSD 209 validate 209 validatePipeline 211

pub.schema.w3c datatypes 212 xml 212

pub.security clearKeyAndChain 215 setKeyAndChain 215

pub.security.pkcs7 sign 215 verify 217

pub.security.util createMessageDigest 218 getCertificateInfo 218 loadPKCS7CertChain 219

pub.smime createCertsOnlyObject 227 createEncryptedData 227 createSignedAndEncryptedData 228 createSignedData 229 processCertsOnlyData 231 processEncryptedData 231 processSignedData 232

pub.soap.processor list 238 registerProcessor 238, 239 unregisterProcessor 239

pub.soap.schema encoding 240 envelope 240

pub.soap.utils addBodyEntry 240 addHeaderEntry 240 addTrailer 242 createSoapData 242 exitUnableToUnderstand 243 getActor 243 getBody 244 getBodyEntries 244 getDocument 245 getHeader 245

getHeaderEntries 246 getMustUnderstand 246 getQName 248 getTrailer 248 removeBodyEntry 248 removeHeaderEntry 249 removeTrailer 250 requestResponseSpec 250 soapDataToString 251 streamTosoapData 251 stringTosoapData 252, 253 validateSoapData 252

pub.storage add 256 closeStore 256 deleteStore 256 get 257 keys 257 lock 258 put 258 registerStore 259 remove 257, 259 unlock 259

pub.string base64Decode 267 base64Encode 267 bytesToString 268 concat 268 HTMLDecode 266 HTMLEncode 266 indexOf 268 length 268 lookupDictionary 269 lookupTable 269 makeString 269 messageFormat 270 numericFormat 270, 271 padLeft 272 padRight 273 replace 273 stringToBytes 274 substring 274 tokenize 275 toLower 275 toUpper 275 trim 276 URLDecode 266 URLEncode 267

pub.sync notify 279 wait 279

pub.table recordListToTable 283

INDEX


stringTableToTable 283 tableToRecordList 283 tableToStringTable 284

pub.universalName find 287 list 287

pub.web createRegions 291 documentToRecord 292 freeDocument 298 getDocumentType 298 getNextNode 299 getNodeIterator 300 loadDocument 302 makeArrays 307 queryDocument 307 recordToDocument 309 stringToDocument 313

pub.webtap getPage 319 triggerSpec 319

publishing packages 181 addReleaseRegistryEntry 183 deleteReleaseRegistryEntry 184 distributeViaFTP 184 distributeViaSvcPull 185 distributeViaSvcPush 185 generateReplicationEvent 185 getLocalReleasedList 186 getRemoteReleasedList 186 notifyPackageRelease 187 packageCreation 187

put 35, 36

Q

query 68 queryDocument 307

definition of 307

R

random number generator 143 randomDouble 143 record services 167 recordListToRecord 169 recordListToTable 283 records

converting to a String 170 Records

adding to list 135 alarmInfo 86 audit event information 87 callStack item 88

constructing from a list of Records 169 converting list from string list 138 converting to XML documents 309 converts list of to table 283 exception information 89 expand contents into a list of Records 170 gdEndInfo 91 gdStartInfo 91 number of in a list 169 portStatusInfo 96 replacing 137 replicationInfo 98 retrieving from list 136 sessionEndInfo 99 sessionExpireInfo 100 sessionStartInfo 101 statInfo 102 txEndInfo 103 txStartInfo 104

recordToDocument 309 recordToRecordList 170 recordToXMLValues 170 recoverPackage 165 recurring tasks, adding to scheduler 199 regions

creating 291 executing queries on 307

registering data stores 259 registerProcessor 238, 239 registerStore 259 related documenation 18 reloadEventManagerSettings 97 reloadPackage 166 remote servers, invoking services on 173, 175 remove 257, 259 removeBodyEntry 248 removeHeaderEntry 249 removeTrailer 250 rename 36 repeating tasks, updating to scheduler 205 replace 273 replication specification 98 replicationInfo Record 98 replicator services 181 report services 189 repository

closing data store 256 creating/opening 259 deleting data store 256 inserting entries 256 inserting/updating entries 258 list of keys in 257 locking entries 258

INDEX


locking entries in 258 registering 259 removing entries 257, 259 retrieving keys from 257 retrieving values from 257 unlocking entries 259

requestResponseSpec 250 response string, forcing 116 restart 177 restorePipeline 114 restorePipelineFromFile 115 resumeTask 202 retrieve 177 retrieving documents from a local file system 105 retrieving MIME content 153 retrieving MIME message headers 154, 156 rollback 69 runFileTemplate 191 runFileTemplateOnPipe 191 runStringTemplate 191 runTemplate 192 runTemplateOnPipe 192

S

S/MIME messages creating certs-only message 227 creating encrypted messages 227 creating signed and encrypted messages 228 creating signed messages 229 decrypting 231 extracting certificates from certs-only message

231 verifying signed messages 232

S/MIME services 225 saveEventManagerSettings 98 savePipeline 115 savePipelineToFile 116 scheduler

adding complex tasks 197 canceling tasks 200 one-time tasks 198 recurring tasks 199 retrieving list of IDs 200 retrieving task info 200 updating complex tasks 203 updating one-time tasks 205 updating repeating tasks 205

scheduler services 195 schema services 207 schemas

attribute definition 108, 109, 127 creating 209

for validating 209 namespace components 212 objectclass definitions 127 retrieving tables 65 SOAP encoding schema 240 SOAP envelope schema 240 XML datatypes 212

search 130 security services 213 send 179 server log

pipeline field names and values 117 writing to 113

session log, session-end events 99 session log, status events 103 Session object, inserting in pipeline 114 session-end events, logging 99 sessionEnd specification 98 sessionEndInfo 99 sessionExpire specification 99 sessionExpireInfo Record 100 sessioninfo 36 sessionStart specification 100 sessionStartInfo 101 setKeyAndChain 215 setListItem 137 setResponse 116 setStringListItem 137 shutdown (do not use) 132 sign 215 signing MIME messages 228, 229, 232 sizeOfList 138 SMTP 28 SMTP servers, submitting requests to 21 SOAP

actor attribute 243 adding body entries 240 adding header entries 240 adding trailers 242 converting SOAP object to String 251 converting stream to SOAP object 251, 252,

253 creating SOAP objects 242 encoding schema 240 envelope schema 240 getting body entries 244, 248 getting header entries 245, 246 getting QNames 248 getting whole message 245 listing processors 238 mustUnderstand attribute 243, 246 registering a processor 238, 239 removing body entries 248

INDEX


removing header entries 249 removing trailers 250 sending a SOAP message 37 specification for custom processor 250 specification for target service 250 submitting an RPC request 39 unregistering processors 239 validating SOAP objects 252

soapDataToString 251 soapHTTP 37 soapRPC 39 specifications

alarm event handler 86 audit event handler 87 exception event handler 89 gdEnd 90 gdstart 91 portStatus event handler 96 replication event handler 98 sessionEnd event handler 98 sessionExpire event handler 99 sessionStart event handler 100 stat event handler 101 txEnd event handler 103 txStart event handler 103 webTap triggerSpec 319

SQL statements, executing 60 start 178 startTransaction 70 stat specification 101 statInfo Record 102 status events, logging 103 status of guaranteed delivery transactions 176 storage services 254 stored procedures

invoking 44, 54 retrieving info about 62 retrieving names of 63

streamTosoapData 251 string array, formatting 270 string services 263 String[ ], based on document's DTD 307 stringListToRecordList 138 strings

adding to list 135 base64 decoding 267 base64 encoding 267 byte array conversion 268 concatenating 268 concatenating an array of strings 269 convert to byte array 274 convert to lowercase 275 convert to uppercase 275

converting list to Record list 138 decoding URL-encoded 266 HTML to native characters 266 length of 268 native characters to HTML 266 padding beginning 272 padding end 273 replace all 273 replacing in a list 137 retrieving from a list 137 returning substring of 274 tokenizing into an array 275 trimming whitespace 276 URL-encoding 267

Strings converted from Records 170 transformation services 263 XML values to a record 171

stringTableToTable 283 stringToBytes 274 stringToDocument 313 stringTosoapData 252, 253 submit 179 subscribing to packages 181 substring 274 subString, index of first occurrence 268 subtractFloats 144 subtractInts 143, 144 subtype, getting from MIME message 157, 158 sum of numeric values 141 suspended tasks, resuming 202 suspendTask 202 sync services 277

T

table convert into two-dimensional array 284 convert string table into 283 convert to list of Records 283 converts list of Records to 283

table services 281 tables

inserting rows 67 removing rows 59 retrieving column info 64 retrieving names of 65 retrieving rows from 68 updating all rows 70

tableToRecordList 283 tableToStringTable 284 tasks

adding complex to scheduler 197

INDEX


adding one-time to scheduler 198 adding recurring to scheduler 199 getting info on 200 removing from scheduler 200 resuming 202 retrieving IDs for 200 updating complex to scheduler 203 updating one-time to scheduler 205 updating repeating to scheduler 205

templates applying 191 from string objects 191

time zones 75 time, converting formats 78 time/date transformation services 73 tokenize 275 toLower 275 toUpper 275 tracePipeline 117 transactional state, clearing 55 transactions, ending guaranteed delivery 176 transforming

date formats 73 time formats 73

transportInfo 117 trigger specification for WebTap 319 triggerSpec 319 trim 276 txEnd specification 103 txEndInfo Record 103 txStart specification 103 txStartInfo Record 104 typographical conventions 17

U

universal name services 285 universal names

finding service names for 287 listing the registry 287

unlock 259 unregisterProcessor 239 unsubscribing from an event 88 update

LDAP 132 pub.db 70

updateComplexTask 203 updateOneTimeTask 205 updateRepeatingTask 205 uppercase, converting to 275 URLDecode 266 URLEncode 267 URLs, mapping 319

V

validate 209 validatePipeline 211 validateSoapData 252 validating objects 207 validating the pipeline 207 verify 217 viewing documentation in PDF format 19

W

wait 279 Web services 289 WebTap

trigger specification 319 WebTap services 317 whitespace, trimming 276

X

XML datatypes 212 pub.schema.w3c 212

XML document, loading 302 XML documents

converting to IData objects 292, 313 creating from Records 309 creating from Values objects 309 creating regions in 291

XML values, converting to a String 171 XMLValuesToRecord 171