SAP Business Connector Built-In Services Guide 46

7/26/2019 SAP Business Connector Built-In Services Guide 46

1/321

SAP BC Bulit-In Services Guide 4.6 1

SAP Business ConnectorBuilt-In Services Guide

Release 4 .6

SAPAG Neurottstr. 16 D-69190 Walldorf

SAP SYSTEM


2/321

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.6

Copyright

Copyright 2002 SAP AG. All rights reserved.

No part of this description of functions may be reproduced or transmitted in any form or for anypurpose 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 softwarecomponents of other software vendors.

Microsoft, WINDOWS and EXCEL, NT and SQL-Server are registered trademarks ofMicrosoft Corporation.

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

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.


3/321

Welcome!


Typographical Conventions

Type Style Description

Interface Text Words or characters that appear on the screen. This includes fieldnames, 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 thedocumentation.

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

NAME Names of elements in the SAP System. These include programnames, transaction codes, table names, ABAP key words, filenames, 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, orthe ENTERkey.

Icon Description

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

An example. Examples illustrate complex procedures or the syntaxfor user entries.

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

Hints and tips.


4/321



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.......................................................................................................23

pub.client:http.....................................................................................................24 pub.client:smtp ...................................................................................................28

pub.client.ftp:append..........................................................................................30

pub.client.ftp:cd ..................................................................................................30

pub.client.ftp:cdls ...............................................................................................31

pub.client.ftp:delete ............................................................................................31

pub.client.ftp:get.................................................................................................31

pub.client.ftp:login ..............................................................................................32

pub.client.ftp:logout ............................................................................................33

pub.client.ftp:ls ...................................................................................................33

pub.client.ftp:mdelete .........................................................................................33

pub.client.ftp:mget..............................................................................................34

pub.client.ftp:mput..............................................................................................34

pub.client.ftp:put.................................................................................................35

pub.client.ftp:rename..........................................................................................35

pub.client.ftp:sessioninfo....................................................................................36

pub.client:soapHTTP..........................................................................................37

pub.client:soapRPC ...........................................................................................38

Chapter 3 Cluster Services.............................................................................42pub.cluster:disableServiceRedir ........................................................................44

pub.cluster:disableSessionRedir........................................................................44

pub.cluster:getClusterHosts...............................................................................44

Chapter 4 Database Services .........................................................................47


5/321

Welcome!


pub.db:call ..........................................................................................................49

pub.db:clearTransaction.....................................................................................50

pub.db:close .......................................................................................................51

pub.db:closeAll ...................................................................................................52

pub.db:commit....................................................................................................52 pub.db:connect...................................................................................................52

pub.db:delete......................................................................................................54

pub.db:execSQL.................................................................................................55

pub.db:getProcInfo .............................................................................................57

pub.db:getProcs .................................................................................................58

pub.db:getTableInfo ...........................................................................................59

pub.db:getTables................................................................................................60

pub.db:insert.......................................................................................................62

pub.db:query ......................................................................................................63

pub.db:rollback ...................................................................................................64

pub.db:startTransaction .....................................................................................65

pub.db:update ....................................................................................................65

Chapter 5 Date Services ................................................................................. 69

Pattern String Symbols.......................................................................................70

Time Zones ........................................................................................................71

Notes on Invalid Dates .......................................................................................72

pub.date:currentDate..........................................................................................73

pub.date:dateBuild .............................................................................................73

pub.date:dateTimeBuild .....................................................................................74

pub.date:dateTimeFormat..................................................................................74

Chapter 6 Event Services ............................................................................... 77

pub.event:addSubscriber ...................................................................................80

pub.event:alarm..................................................................................................82

pub.event:alarmInfo............................................................................................82

pub.event:audit...................................................................................................83

pub.event:auditInfo.............................................................................................83

pub.event.audit:logToFile...................................................................................83 pub.event:callStackItem .....................................................................................84

pub.event:deleteSubscriber ...............................................................................84

pub.event:exception ...........................................................................................85

pub.event:exceptionInfo .....................................................................................85


6/321



pub.event.exception:logToFile ...........................................................................86

pub.event:gdEnd ................................................................................................86

pub.event:gdEndInfo..........................................................................................87

pub.event:gdStart...............................................................................................87

pub.event:gdStartInfo.........................................................................................87 pub.event:getEventTypes ..................................................................................88

pub.event:getSubscribers ..................................................................................88

pub.event:modifySubscriber ..............................................................................89

pub.event:portStatus ..........................................................................................92

pub.event:portStatusInfo....................................................................................92

pub.event:reloadEventManagerSettings............................................................93

pub.event:replication ..........................................................................................94

pub.event:replicationInfo....................................................................................94

pub.event:saveEventManagerSettings ..............................................................94

pub.event:sessionEnd........................................................................................94

pub.event.sessionEnd:logToFile........................................................................95

pub.event:sessionEndInfo..................................................................................95

pub.event:sessionExpire....................................................................................95

pub.event.sessionExpire:logToFile ....................................................................95

pub.event:sessionExpireInfo..............................................................................96

pub.event:sessionStart.......................................................................................96

pub.event.sessionStart:logToFile.......................................................................96

pub.event:sessionStartInfo ................................................................................97

pub.event:stat.....................................................................................................97 pub.event:statInfo...............................................................................................98

pub.event.stats:logToFile ...................................................................................99

pub.event:txEnd .................................................................................................99

pub.event:txEndInfo ...........................................................................................99

pub.event:txStart ................................................................................................99

pub.event:txStartInfo........................................................................................100

Chapter 7 File Services.................................................................................101

pub.file:getFile..................................................................................................103

Chapter 8 Flow Services...............................................................................105

pub.flow:clearPipeline ......................................................................................107

pub.flow:debugLog...........................................................................................107

pub.flow:getLastError.......................................................................................107


7/321

Welcome!


pub.flow:getSession .........................................................................................108

pub.flow:getTransportInfo ................................................................................108

pub.flow:restorePipeline ...................................................................................108

pub.flow:restorePipelineFromFile.....................................................................109

pub.flow:savePipeline.......................................................................................109 pub.flow:savePipelineToFile ............................................................................110

pub.flow:setResponse......................................................................................110

pub.flow:tracePipeline ......................................................................................111

pub.flow:transportInfo.......................................................................................111

Chapter 9 LDAP Services ............................................................................. 113

pub.ldap:bind....................................................................................................115

pub.ldap:connect ..............................................................................................115

pub.ldap:delete.................................................................................................116

pub.ldap:disconnect .........................................................................................116pub.ldap:getAttributeDef ..................................................................................117

pub.ldap:getClassDef.......................................................................................117

pub.ldap:init ......................................................................................................118

pub.ldap:list ......................................................................................................118

pub.ldap:lookup ................................................................................................120

pub.ldap:search................................................................................................120

pub.ldap:shutdown ...........................................................................................122

pub.ldap:update................................................................................................122

Chapter 10 List Services................................................................................125pub.list:appendToRecordList ...........................................................................127

pub.list:appendToStringList..............................................................................127

pub.list:copyListItem.........................................................................................127

pub.list:getListItem ...........................................................................................128

pub.list:getRecordListItem................................................................................128

pub.list:getStringListItem..................................................................................129

pub.list:setListItem............................................................................................129

pub.list:setRecordListItem................................................................................129

pub.list:setStringListItem ..................................................................................129pub.list:sizeOfList .............................................................................................130

pub.list:stringListToRecordList .........................................................................130

Chapter 11 Math Services.............................................................................. 133

pub.math:addFloatList......................................................................................135


8/321



pub.math:addFloats .........................................................................................135

pub.math:addIntList..........................................................................................135

pub.math:addInts .............................................................................................135

pub.math:divideFloats ......................................................................................136

pub.math:divideInts ..........................................................................................136pub.math:multiplyFloatList ...............................................................................136

pub.math:multiplyFloats ...................................................................................136

pub.math:multiplyIntList ...................................................................................137

pub.math:multiplyInts ....................................................................................... 137

pub.math:randomDouble..................................................................................137

pub.math:subtractFloats...................................................................................137

pub.math:subtractInts.......................................................................................138

Chapter 12 Mime Services.............................................................................139

pub.mime:addBodyPart....................................................................................141 pub.mime:addMimeHeader..............................................................................144

pub.mime:createMimeData..............................................................................145

pub.mime:getBodyPartContent........................................................................147

pub.mime:getBodyPartHeader.........................................................................148

pub.mime:getContentType...............................................................................148

pub.mime:getEnvelopeStream.........................................................................149

pub.mime:getMimeHeader...............................................................................150

pub.mime:getNumParts ...................................................................................151

pub.mime:getPrimaryContentType ..................................................................151

pub.mime:getSubContentType ........................................................................152

pub.mime:mergeHeaderAndBody....................................................................152

Chapter 13 Package Services........................................................................155

pub.packages:activatePackage ....................................................................... 157

pub.packages:disablePackage ........................................................................157

pub.packages:enablePackage.........................................................................158

pub.packages:installPackage ..........................................................................158

pub.packages:recoverPackage........................................................................159

pub.packages:reloadPackage..........................................................................160 Chapter 14 Record Services..........................................................................161

pub.record:length .............................................................................................163

pub.record:recordListToRecord ....................................................................... 163

pub.record:recordToRecordList ....................................................................... 164


9/321

Welcome!


pub.record:recordToXMLValues ......................................................................164

pub.record:XMLValuesToRecord.....................................................................165

Chapter 15 Remote Services......................................................................... 167

pub.remote:invoke............................................................................................169

pub.remote.gd:end ...........................................................................................170pub.remote.gd:getStatus..................................................................................170

pub.remote.gd:invoke.......................................................................................171

pub.remote.gd:restart.......................................................................................171

pub.remote.gd:retrieve .....................................................................................171

pub.remote.gd:start ..........................................................................................172

pub.remote.gd:send .........................................................................................173

pub.remote.gd:submit.......................................................................................173

Chapter 16 Replicator Services .................................................................... 175

pub.replicator:addReleaseRegistryEntry..........................................................177

pub.replicator:deleteReleaseRegistryEntry......................................................178

pub.replicator:distributeViaFTP........................................................................178

pub.replicator:distributeViaSvcPull...................................................................179

pub.replicator:distributeViaSvcPush ................................................................179

pub.replicator:generateReplicationEvent .........................................................179

pub.replicator:getLocalReleasedList................................................................180

pub.replicator:getRemoteReleasedList ............................................................180

pub.replicator:notifyPackageRelease...............................................................181

pub.replicator:packageCreation .......................................................................181

Chapter 17 Report Services .......................................................................... 183

pub.report:runFileTemplate..............................................................................185

pub.report:runFileTemplateOnPipe..................................................................185

pub.report:runStringTemplate ..........................................................................185

pub.report:runStringTemplateOnPipe ..............................................................186

pub.report:runTemplate....................................................................................186

pub.report:runTemplateOnPipe........................................................................186

Chapter 18 Scheduler Services.....................................................................189

pub.scheduler:addComplexTask......................................................................191

pub.scheduler:addOnetimeTask ......................................................................192

pub.scheduler:addRepeatingTask ...................................................................193

pub.scheduler:cancelTask ...............................................................................194


10/321



pub.scheduler:getTaskIDs ...............................................................................194

pub.scheduler:getTaskInfo...............................................................................194

pub.scheduler:resumeTask..............................................................................196

pub.scheduler:suspendTask ............................................................................196

pub.scheduler:updateComplexTask ................................................................197pub.scheduler:updateOneTimeTask................................................................199

pub.scheduler:updateRepeatingTask ..............................................................199

Chapter 19 Schema Services ........................................................................201

pub.schema:createXSD ...................................................................................203

pub.schema:validate ........................................................................................ 203

pub.schema:validatePipeline ...........................................................................205

pub.schema.w3c:datatypes .............................................................................206

pub.schema.w3c:xml........................................................................................206

Chapter 20 Security Services ........................................................................207pub.security:clearKeyAndChain.......................................................................209

pub.security:setKeyAndChain..........................................................................209

pub.security.pkcs7:sign....................................................................................209

pub.security.pkcs7:verify..................................................................................211

pub.security.util:createMessageDigest ............................................................212

pub.security.util:getCertificateInfo....................................................................212

pub.security.util:loadPKCS7CertChain ............................................................213

Chapter 21 SMIME Services ..........................................................................215

pub.smime:createCertsOnlyData.....................................................................217

pub.smime:createEncryptedData.....................................................................217

p .......................................................................................................................218

pub.smime:createSignedData..........................................................................219

pub.smime:getContentType.............................................................................220

pub.smime:processCertsOnlyData ..................................................................221

pub.smime:processEncryptedData ..................................................................221

pub.smime:processSignedData .......................................................................222

Chapter 22 SOAP Services............................................................................225

pub.soap.processor:list ....................................................................................227

pub.soap.processor:registerProcessor ............................................................227

pub.soap.processor:unregisterProcessor ........................................................228

pub.soap.schema:encoding .............................................................................228


11/321

Welcome!


pub.soap.schema:envelope .............................................................................228

pub.soap.utils:addBodyEntry ...........................................................................228

pub.soap.utils:addHeaderEntry........................................................................229

pub.soap.utils:addTrailer..................................................................................230

pub.soap.utils:createSoapData ........................................................................231pub.soap.utils:exitUnableToUnderstand ..........................................................231

pub.soap.utils:getActor.....................................................................................231

pub.soap.utils:getBody.....................................................................................232

pub.soap.utils:getBodyEntries..........................................................................232

pub.soap.utils:getDocument.............................................................................233

pub.soap.utils:getHeader .................................................................................233

pub.soap.utils:getHeaderEntries ......................................................................234

pub.soap.utils:getMustUnderstand...................................................................234

pub.soap.utils:getQName.................................................................................236

pub.soap.utils:getTrailers .................................................................................236

pub.soap.utils:removeBodyEntry .....................................................................236

pub.soap.utils:removeHeaderEntry..................................................................237

pub.soap.utils:removeTrailer............................................................................238

pub.soap.utils:requestResponseSpec..............................................................238

pub.soap.utils:soapDataToString .....................................................................239

pub.soap.utils:streamToSoapData...................................................................239

pub.soap.utils:stringToSoapData .....................................................................240

pub.soap.utils:validateSoapData......................................................................240

Chapter 23 Storage Services......................................................................... 243

pub.storage:add ...............................................................................................245

pub.storage:closeStore ....................................................................................245

pub.storage:deleteStore...................................................................................245

pub.storage:get ................................................................................................246

pub.storage:keys ..............................................................................................246

pub.storage:lock ...............................................................................................247

pub.storage:put ................................................................................................247

pub.storage:registerStore.................................................................................248

pub.storage:remove .........................................................................................248

pub.storage:unlock ...........................................................................................248

Chapter 24 String Services............................................................................251

pub.string:HTMLDecode ..................................................................................253


12/321



pub.string:HTMLEncode ..................................................................................253

pub.string:URLDecode.....................................................................................253

pub.string:URLEncode .....................................................................................254

pub.string:base64Decode ................................................................................254

pub.string:base64Encode ................................................................................254pub.string:bytesToString ..................................................................................255

pub.string:concat..............................................................................................255

pub.string:indexOf ............................................................................................255

pub.string:length...............................................................................................255

pub.string:lookupDictionary..............................................................................256

pub.string:lookupTable.....................................................................................256

pub.string:makeString ......................................................................................256

pub.string:messageFormat ..............................................................................257

pub.string:numericFormat ................................................................................257

pub.string:padLeft ............................................................................................258

pub.string:padRight ..........................................................................................258

pub.string:replace.............................................................................................259

pub.string:stringToBytes ..................................................................................259

pub.string:substring..........................................................................................260

pub.string:toLower............................................................................................261

pub.string:toUpper............................................................................................261

pub.string:tokenize ...........................................................................................261

pub.string:trim ..................................................................................................262

Chapter 25 Sync Services..............................................................................263

pub.sync:notify .................................................................................................265

pub.sync:wait ...................................................................................................265

Chapter 26 Table Services.............................................................................267

pub.table:recordListToTable ............................................................................269

pub.table:stringTableToTable ..........................................................................269

pub.table:tableToRecordList ............................................................................269

pub.table:tableToStringTable...........................................................................270

Chapter 27 Universal Name Services ...........................................................271pub.universalName:find ...................................................................................273

pub.universalName:list.....................................................................................273

Chapter 28 Web Services...............................................................................275


13/321

Welcome!


pub.web:createRegions ...................................................................................277

pub.web:documentToRecord ...........................................................................278

pub.web:freeDocument ....................................................................................284

pub.web:getDocumentType .............................................................................284

pub.web:getNextNode......................................................................................285 pub.web:getNodeIterator..................................................................................285

pub.web:loadDocument ...................................................................................288

pub.web:makeArrays........................................................................................293

pub.web:queryDocument .................................................................................293

pub.web:recordToDocument............................................................................295

pub.web:stringToDocument .............................................................................299

Chapter 29 WebTap Services........................................................................303

pub.webtap:getPage ........................................................................................305

pub.webtap:triggerSpec ...................................................................................305

Chapter 30 INDEX...........................................................................................309


14/321




15/321

Welcome!


Chapter 1 Introduction

Welcome!...................................................................................16Typographical Conventions........................................................17

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

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

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


16/321



Welcome!

TheBuilt-In Services Reference Guidedescribes 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 42 Enable and/or disable load balancing for specific services and

sessions in a cluster.

database 47 Access JDBC-enabled databases.

date 69 Generate and format date values.

event 77 Build audit-handlers and event-handlers.

file 101 Perform operations on the local file system

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

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

list 125 Retrieve, replace, or add elements in an object list, record list, or

string list; convert string lists to record lists.

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

mime 139 Create MIME messages. Extract information from MIME

messages.

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

record 161 Perform operations on Records in the pipeline.

remote 167 Invoke services on remote SAP BC servers.

replicator 175 Replicate packages across SAP BC servers.

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


17/321



Folder Page Contains Services You Use To

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

schema 201 Validate objects or values in the pipeline.

security 207 Control which client certificates are sent to other services and to

digitally sign data and process digital signatures.

smime 215 Create digitally signed and/or encrypted MIME messages.

Process signed and encrypted MIME messages.

soap 225 Send and receive SOAP messages.

storage 243 Create, close, delete, and register data stores. Insert and retrieve

information from data stores.

string 251 Perform string manipulation and substitution operations.

sync 263 Coordinate the execution of services.

table 267 Convert instances of com.wm.util.Tableto other data types.

universalName 271 Get information from the Universal Name Registry.

web 275 Perform operations on XML and HTML documents.

webtap 303 Build services that monitor HTTP requests and conditionally

executes a prescribed set of actions based on the URL requested

by a client.


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 Servicefield on the Propertiestab specifies the

name of the requested service.

Characters that you must type exactly areshown in a typewriter font. Type:setupand then press ENTER.

Variable information that you must type

based on your specific situation or

environment is shown in italics.

Type: \setup

and then press ENTER.


18/321



Convention Example

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.

\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 intypewriter 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

output templates, and accessing databases through the SAP BC server.

This book is for integrators.


19/321

Viewing this Document


Refer to this book For

You will find this book at:

\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.


\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.


\Server\doc\ISAdministratorsGuide.pdf

SAP BC Clustering

Guide

Information about how to install and configure the SAP BC

Clustering feature. It contains information for administrators whoconfigure and manage a SAP BC system and for application

integrators who want to create services that interact directly with the

repository. This book is aimed at server administrators.


\Server\doc\SAPBCClusteringGuide.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.


\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 Contentscommand from

the Helpmenu.

Viewing this Document

To view this document, which is in PDF format, you must have AcrobatReader4.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 AcrobatReader 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/supportservice/custsupport/download.html.
http://www.adobe.com/supportservice/custsupport/download.htmlhttp://www.adobe.com/supportservice/custsupport/download.html


20/321



Printing this Guide

You can print this guide from AdobeAcrobat Reader 4.0. The documents title page and

table of contents are at the endof the printed copy. To create a traditional, paper-based

manual, simply move these pages to the front of the document after it is printed.


21/321


Chapter 2 Client Services

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


22/321

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 dirpathand 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: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.


23/321

pub.client:ftp


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

Input Variable Name Type Description

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: asciior binary

transfertype String One of the following FTP data transfer modes: passiveor

active

localfile String When commandis set to put, this value specifies the name of the

local file you want to transfer. (When contentis not null, this field

is ignored.)

When commandis set to get, this variable specifies the name of

the local file in which you want the retrieved content saved.

remotefile String When commandis set to put, this value specifies the name of the

remote file in which you want the save the data you are sending.

When commandis 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


24/321




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.

Output Variable Name Type Description

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 localfilewas 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).

returncode String Standard FTP protocol return code.returnmsg String Standard FTP protocol return message.

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 mustbegin with http:or https:

Example http://www.rubicon.com/orders/orders.htmlmethod 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 loadAsto 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).


25/321

pub.client:http


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 Descriptiondata 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, argsis

appended first, tableis appended second, andstringis 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 argsto 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 elements name represents the name portion of the

pair, and

The elements 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 argsvia a GET or

HEAD. You do not need to include this character in

args.

When you submit data using the argsvariable, 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 thestringor

bytesvariable.

table A String Table (a String [ ][ ]) specifying the data thatthe http service will use to construct a query string to

submit to the resource specified in url.

tableis similar to args, but it allows you to submit

unnamed values in a query string, not just name=value

pairs.


26/321



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 portionof 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.


character if it submits the data in tablevia the GET

method. You do not need to include this character in

table.

When you submit data using the tablevariable, 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 thestringor bytesvariable.

string A String containing the text that you want the http

service to submit to the resource in url.

You can usestringto submit data via the POST, GET,

or HEAD method.

If you usestringto submit data, make sure that youspecify the string exactlyas 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


if it submits the data instringvia a GET or HEAD.

You do not need to include this character instring.

When performing a POST,stringwill be submitted to

the resource defined by urlas the body of the

document.

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

You can only use bytes to submit data via the POST

method.


27/321

pub.client:http


Important! When you use bytesand another element

(args, table, orstring) to specify data, the service

appends the data from the args, table, orstringelement

to url. The service appends argsto urlfirst, table

second, andstringlast. The service encodes the data

from the byteselement in the body of the post. If the

streamvariable is not null, bytesis ignored.

mimeStream Optional. An InputStream containing a MIME or

SMIME message that you want this service to submit

to the resource in url. A mimeStreamis 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 usestream to submit data via the POST

method.

Important! When you usestreamand another element

(args, table,stringor bytes) to specify data, the service

appends the data from the args, table, orstringelement

to url. The service appends argsto urlfirst, table

second, andstringlast. The service encodes the data

from thestreamelement in the body of the post. If the

streaminput is not null, the bytesinput is ignored.

encoding Optional. A String specifying the character set in which

the URL dataparameters are encoded (args or table

and/orstring). 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. Becausestringis used in the body of the post and

not used for building the URL, you do not need to

specify encoding for the data parameterstring.

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

urlis protected.

Key Description


28/321



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 authto

Basic.

user A String specifying the user name that this service willsubmit 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 headersValues object for each header field

that you want to set, where:

The elements name represents the name of the header field, and

The elements 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, orstring.

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.

bytesis returned only when the loasAsinput

parameter is set to bytes.

stream An InputStream containing the body of the HTTP

response.streamis returned only when the loasAs

input parameter is set to stream.

Usage Notes If pub.client:httpdoes not receive a response within the timeout period specified in the servers

watt.net.timeoutparameter, it will throw an exception. For information about the watt.net.timeoutparameter, see theSAP 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.


29/321

pub.client:smtp


Package WmPublic


to String Receivers e-mail address. If you specify multiple addresses,

separate them with commas.

cc String Optional. Additional receivers e-mail addresses. If you specify

multiple addresses, separate them with commas.

bcc String Optional. Additional receivers 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

subjectCharsetis 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.

from String Senders email address.

mailhost String The SMTP host name for outbound messages (e.g.,

smtp.webMethods.com ).

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 mimeStreamis 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.


contenttype String MIME type of the message, e.g.

application/x-edi-message

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 contentis

null.

encoding String Encoding of the message, e.g., base64

or 7bit. If encodingis not specified, the

default 7bit is used.


status String Final status of service.


30/321



Usage Note If you are usingfilenameto attach a file to the message and the file is not a plain text file, you need to

set the contenttypeand encoding.

Example

To attach \Server\mydir\myfile.doc to a pub.client:smtpservice, invoke the service with the

following attachment values for the variables:

contenttype: application/mswordfilename: 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


sessionkey String Unique key that identifies current session information. The

sessionkey is output from the pub.client.ftp:loginservice.

transfermode String The FTP file transfer mode. Specify asciior 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 contentis null.

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


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:cdDescription Changes the current working directory during an FTP session (corresponding to the standard FTP user

command cd dirpath).

Package WmPublic



sessionkeyis output from the pub.client.ftp:loginservice.

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






31/321

pub.client.ftp:cdls


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 dirpathand ls namepattern).

Package WmPublic

Input Variable Name Type Descriptionsessionkey String Unique key that identifies current session information. The


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 infilename, multiple files will be deleted.





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 asciior binary.

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


32/321




remotefile String The name of the remote file.


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. Ifencoding 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

transfertypeis 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 passiveor

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.


33/321

pub.client.ftp:logout




sessionkeyis output from thepub.client.ftp:loginservice.




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.


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 standardFTP user command mdelete pattern).

Package WmPublic


34/321






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 forfilenamepattern, all files in the current working directoryare deleted.





pub.client.ftp:mget

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

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.


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


35/321

pub.client.ftp:put




sessionkeyis output from thepub.client.ftp:loginservice.


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 putcommand.

localfile String Optional. The name of a local file that you want transferred with

the putcommand 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.





pub.client.ftp:rename

Description Renames a file on a remote server.

Package WmPublic





36/321




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 BCserver will choose the listener port

number. The dataportis only used

when transfertypeis 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 passiveor

active.

encoding String Optional character set used to correctly

convert the String object to bytes on

pub.client.ftp:getand

pub.client.ftp:mgetservices. If no value

is returned, then the encoding was not

explicitly set and the default JVM

encoding is used.


37/321

pub.client:soapHTTP


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 besent.

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 typeto

basicor 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.

validateSOAP String Optional. A String that indicates whether or not the response

message

Documents

SAP Business Connector Built-In Services Guide 46