SAP Treasury
SAP
SAP AG Treasury
SAP
Neither this document nor any part of it may be copied or reproduced in any form or by any means, or translated into another language, without the prior consent of SAP AG.
SAP AG makes no warranties or representations with respect to the content hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. SAP AG assumes no responsibility for any errors that may appear in this document. The information contained in this document is subject to change without notice. SAP AG reserves the right to make any such changes without obligation to notify any person of such revision or changes. SAP AG makes no commitment to keep the information contained herein up to date.
July 1997
SAP Treasury
SAP
Contents
1. General Information ........................................................................................................... 4 1.1 General Requirements ..................................................................................................... 4 1.2 Functions.......................................................................................................................... 4 1.3 Technology....................................................................................................................... 4 1.4 Partner Concept ............................................................................................................... 5 1.5 Certification Requirements .............................................................................................. 5 2. Overall System Architecture .............................................................................................. 6 2.1 Overview ........................................................................................................................... 6 2.2 Application Scenario 1..................................................................................................... 6 2.3 Application Scenario 2..................................................................................................... 8 2.4 Application Scenario 3..................................................................................................... 9 3. Additional Functions of the Datafeed Interface................................................................ 9 3.1 Overview ........................................................................................................................... 9 3.2 Market Data/Error Buffer .................................................................................................. 9 3.3 Translation Table Settings............................................................................................. 10 3.4 User Log ......................................................................................................................... 11 3.4.1 Display ..................................................................................................................... 11 3.4.2 User Log Archive ...................................................................................................... 11 3.5 File Interface ................................................................................................................... 12 4. Technical Description of Transfer Structures ................................................................ 12 4.1 Structure of the Table for Requesting Market Data...................................................... 12 4.2 Structure of the Table for Delivering Market Data ........................................................ 13 4.3 Calling up External Functions from the SAP R/3 System ............................................ 14 4.4 Calling up SAP R/3 Functions from External Systems (Transactional RFC) .............. 15 5. Error Processing .............................................................................................................. 16
July 1997
SAP AG Treasury
SAP
1. General Information
1.1 General Requirements
As part of its R/3 client/server software solution, SAP has developed an application for the treasury area (SAP R/3 TR). The applications main task is to manage treasury transactions. Besides position management, this includes monitoring and valuing positions on an ongoing basis. To help the user work more efficiently, SAP R/3 TR supports an interface that allows the user to transfer the market data required for valuation into the SAP System automatically. This interface is called a datafeed interface. SAP aims to make it an open, universal interface, via which every provider of datafeed platform systems can export market data into the SAP R/3 TR System. This document describes how external datafeed programs must be configured to allow them to transfer market data to the SAP R/3 TR System. The datafeed interface was first made available to all customers with SAP R/3 TR Release 3.0D.
1.2 Functions
In SAP R/3 TR Release 4.0A, the datafeed interface supports the following transfer functions: Transfer of exchange rates Transfer of security price information (stocks, bonds) Transfer of reference interest rates (e.g. LIBOR, FIBOR) Transfer of index values Transfer of volatilities ( for currencies, securities, interest rates and indexes) Transfer of forwards Transfer of commodities The data can be transferred real-time using Remote Function Call (RFC) (see Section 2), or by means of a file interface in datafeed notation (see Section 3.5).
Note: SAP plans to support the transfer of additional market data types in later releases.
1.3 Technology
From Release 3.0D, data can be transferred between the external interface program and the SAP R/3 TR datafeed module either synchronously, with direct program-to-program communication, or asynchronously (transactional link). The SAP R/3 TR datafeed module sets up the communication link when it requests the price/rate information. The advantage of this processing method is that the SAP R/3 TR datafeed module can call up the required market data independently, and vary the volume of data it requests according to its own processing capacity and processing times. To obtain market data, the SAP R/3 TR datafeed module calls up an external interface
4 July 1997
SAP Treasury
SAP
program that requests the market data from the datafeed server and returns it to the SAP R/3 TR System. This program is provided by the partner, and is executed outside the SAP R/3 System. The link is based on SAPs synchronous Remote Function Call (sRFC) technology. The technical details and the requirements the interface software must meet to be compatible with the RFC are described in the handbook entitled SAP Remote Function Call (RFC) Interface. Releases 3.0D and above allow asynchronous buffered data transmission between the SAP R/3 TR datafeed module and external partner programs using transactional RFC (tRFC). When this transmission method is used, the partner is responsible for updating the requested market data on a continual basis according to SAP specifications (times, frequencies).
July 1997
SAP AG Treasury
SAP
Datafeed Architecture
SAP R/3 Applications
TR-TM TR-MRM ...
Treasury Market Risk Management Management
Datafeed Provider
R e p l y Reply
Information providers
Selective Refresh
SAP AG
XXYYY / 22 - 1
Request
SAP Treasury
SAP
The function module first converts the the market data request in R/3 notation into datafeed notation by means of a translation table (Table VTB_DFCU in the SAP Data Dictionary). The datafeed notation contains the instruments, the data source (producer) and the instrument properties for which current values are being requested. A property describes which item of information about an instrument is being requested from the external interface program. Examples of properties are: BID, ASK, FIRST, LAST, HIGH, LOW, YR_LOW, YR_HIGH. The property names are defined by the SAP R/3 TR user as part of TR-MRM Customizing. Part of the function module TB_DATAFEED_RATE_REQUEST uses the RFC method. This means that the function module calls up the external interface program of the partner (data provider) using the CALL FUNCTION <ext. function name> DESTINATION <partner destination>. The table of requested instruments, data sources (producers) and corresponding instrument properties defined in the R/3 System is transferred to the partners interface program. This part of the internal SAP R/3 System function module TB_DATAFEED_RATE_REQUEST is an RFC client, and thus forms an interface to the external interface program(s) outside the SAP R/3 System. The external interface program acts as an RFC server and market data supplier. The function module TB_DATAFEED_RATE_REQUEST can also be called up to read the values exclusively from the market data buffer. In this case, the market data is retrieved by a separate report program (RFTBDF07). Note: RFC method: The SAP function module is responsible for setting up the link to the external datafeed program.
To call up the partner functions, the internal SAP R/3 function module uses two parameters that identify the program to be called up: the name of the function within the partner program (<ext. function name>) and the RFC destination defined in the R/3 System (<partner destination>). The RFC destination is used to define the technical details of the partner program to be called up, and is defined in the R/3-System via transaction SM59 (Display and Maintain RFC Destinations). The line structure of the table of requirements REQUEST is described in structure VTB_DFREQ in the SAP Data Dictionary (see Section 4.1 of this document). A further table, ANSWER, is used to return the market values from the external datafeed program to the SAP R/3 System. The structure of the table is defined in the SAP Data Dictionary under VTB_DFANS, and corresponds to the structure of the table of requirements. However, it also includes additional fields for transferring the market values identified by the external datafeed program (see Section 4.2). When the external interface program is called up, this table is initially empty. The external program processes the market data requirements that have been transferred to it in the table of requirements REQUEST. It determines the values for the requested instrument properties and puts them into the return table ANSWER. During this time, it must make sure that the communication link to the R/3 function module that called it up remains open, since the function module waits for either the market values or an error message (sRFC). The communication link is deactivated when the data are returned from the external partner program to the function module in the R/3 System that called it up. Note: When the requested data has been transmitted, the R/3 System deactivates the link. The content of the keys in the table ANSWER for the instrument, the data source (producer) and the property must match those in the table of requirements REQUEST. If errors occur, the customer needs to follow the procedure for error processing (see Section 5). The market data supplied in datafeed notation is translated back into R/3 notation by means of a translation table, and made available to the TR-MRM application in the form of an internal table. In addition, the market data buffer can be used to analyze the market data obtained or the error situation. The market data/error buffer always stores the last external request on a particular date. The function module TB_DATAFEED_RATE_REQUEST does not update the SAP R/3 market data tables. This is the responsibility of the application module (here: TRMRM).
July 1997 7
SAP AG Treasury
SAP
Within the R/3 System, the report program RFTBDF07 calls up the function module TB_DATAFEED_RATE_UPDATE. The selection criteria in the report program are translated into a table of requirements in R/3 notation. The function module TB_DATAFEED_RATE_UPDATE works in the same way as the function module TB_DATAFEED_RATE_REQUEST, so that the process described for application scenario 1 also applies here. In addition, TB_DATAFEED_RATE_UPDATE triggers a selective automatic update of the R/3 market data tables. In application scenario 2, the R/3 security price table is filled with the closing prices if the corresponding update indicators have been flagged in the translation table. When program RFTBDF07 has finished running, the closing security prices that have been transferred can be used directly by the TR-SE application module. To list the market data transferred or any error messages, the user can refer to the spool list of report program RFTBDF07, or to the market data and error buffer.
July 1997
SAP Treasury
SAP
Note: At present, this function is only available if special versions of report RFTBDF07 are scheduled.
SAP AG Treasury
SAP
tables (for example, for exchange rates or security prices) are only updated by this report program if the update indicator has been flagged on the selection screen. An error and/or market data list can be generated, if required. Note: If an error occurs, the partner must return an error code. For more details, refer to Section 5 (Error Processing).
Manual customizing by the customer/partner When the R/3 master data have been copied to the translation table, the customer can enter the datafeed notation manually, with the partners support (Table VTB_DFCU). In the securities area, automatic customizing is supported. Note for our partners: From Release 3.0D, partners must provide detailed documentation of their software. For each certified transfer function, the partner must provide the following (in paper form or as an online query facility in the partner system): Description of the instrument keys that can be called up via the datafeed interface. (If necessary, this must be done separately for each datafeed that can be called up.) Description of all the available data sources (producers) and their semantic meaning for the R/3 customer. Description of all the instrument properties that can be called up and their semantic meaning. The documentation should include a reference indicating where the R/3 customer can get additional information from the partner (stating the appropriate partner support team/hotline). The partner is the first to be contacted if the customer experiences problems setting up the datafeed notation (instrument, data source/producer, instrument properties).
Automatic Customizing support In the securities area, the translation table can be customized automatically, using the securities ID held in the securities master record as a key. To support this function, the partner must make a file available, in which the securities ID number and the corresponding instrument (including stock exchange prefix/suffix) are listed line by line. This file is read by the TR report program RFTBDF05, and the instrument keys are transferred to the translation table automatically. Note for our R/3 customers: From Release 3.0D, the customer must have defined the class data and allocated the security to the relevant stock exchange and quoted currency. If this has
10 July 1997
SAP Treasury
SAP
not been done, report program RFTBDF05 cannot customize the translation table automatically. File format for report program RFTBDF05: Description Instrument key Data source /producer Security ID number Type CHAR CHAR CHAR Length 20 15 13 Example =FSAG QFRecord 716460
Notes for our partners: Each line in the file must be structured in this way. No other lines are permitted! Each field must be filled, and any unutilized characters must be filled up with spaces to make up the field length. Tabulators are not permitted! The partner is responsible for ensuring that the structure of this file is correct, and is the first to be contacted by the customer when problems occur with this report program. To be certified for the function Transfer of security price information, the partner is required to support report program RFTBDF05. Note: SAP plans to provide an intelligent Customizing interface for a later release.
Report program RFTBDF08 is used to check the translation table. The program determines whether all the datafeed parameters have been entered or whether individual fields are still empty. If there are any empty fields, no market data can be obtained, and the report program outputs a corresponding error message.
3.4.1 Display
Report program RFTBDF02 allows the SAP R/3 TR user to display or print the user log. If the partner requires an overview of all the market data obtained by the R/3 customer, the partner must request the information from the customer. The R/3 customer can print the user log for a past period and send it to the partner.
SAP AG Treasury
SAP
system file in DATAFDLOG archive format. Delete an archive (report program RFTBDF11): The archived data are deleted from the R/3 database. Import archive (report program RFTBDF12): The R/3 System reads an external file in DATAFDLOG archive format; the user log is imported back to the R/3 database. During the archiving production run, the transaction SARA first archives the user logs and then runs the deletion program. For this reason, the R/3 user should always call up the transaction SARA to perform the archive function. There is separate, detailed documentation that describes the SARA transaction and the prerequisites for using the archiving function. (e.g. configuration of the archive file names).
Note for our partners: Each line in the file must be structured in this way. Any other lines are not permitted! Each of the fields must be filled, and any unutilized characters must be filled up with spaces to make up the field length. Tabulators are not permitted! The partner is responsible for ensuring that the structure of this file is correct, and is the first to be contacted by the customer when problems occur with this report program. Note for our partners: In later releases there may be minor changes to this format.
12
July 1997
SAP Treasury
SAP
RINID2 SPRPTY
15 15 8 6 8 6 12
R R O O O O R
Producer = Source Instrument property for historical data (YYYYMMDD) for historical data (HHMMSS) for historical data (YYYYMMDD) for historical data (HHMMSS) Name of the SAP R/3 user requesting market data
The table for requesting market data is filled by the SAP R/3 System using the translation table.
Error text Provider ID Contributor ID Contributor country Contribution date Contribution time Value
CHAR CHAR CHAR CHAR DATS TIMS CHAR CHAR CHAR CHAR CHAR
80 10 10 5 8 6 20 5 5 7 7
R R O O R R R R*/O R R
Error message, if status <> ok. Name of data provider (e.g. 'telerate', 'VWD', Reuters...) Name of contributor Country of contributor Format: YYYYMMDD Format: HHMMSS Alphanumeric or numeric values, left justification *Currency key, only required for security price information Price notation (for securities) Only required for currencies Only required for currencies
13
SAP AG Treasury
SAP
UNAME
SAP User-ID
CHAR
12
Name of the SAP R/3 user requesting market data (copy from table of requirements) Required for volatilities. Here: term in days
RZUSATZ
Additional field
CHAR
10
Notes for our partners: Numeric values: Decimal places must be separated from the whole number with a period. Decimal places must be in decimal form (for example 0.375). Fractions (for example 3/8) are not permitted. If fields overflow, decimal places can be omitted. If the SSTATS (status) entry is <> OK, 'N/A' must be entered in the VALUE field. If required, the table structures described above will be adapted and enhanced in a later release.
2. Asynchronous (transactional) RFC: CALL FUNCTION <name of external program> IN BACKGROUND TASK
14 July 1997
SAP Treasury
SAP
DESTINATION EXPORTING
TABLES
The external program name and the RFC destination can both be customized in the SAP R/3 System, which means that the partner can define these variable names freely. feedname: history: update: CHAR 10: CHAR 1: CHAR 1: Name for the datafeed in the R/3 System Flag which indicates whether historical data are to be called up (X) or not( ) Flag which indicates whether the system is to request the data as a snapshot (update = ) or trigger a real-time datafeed request(X). If a snapshot is requested, the partner only needs to supply the market data once. If a real-time datafeed request is initialized, the partner is responsible for supplying up-to-date rates and prices on continual basis.
4.4 Calling up SAP R/3 Functions from External Systems (Transactional RFC)
1. Delivery of market data. Definition in the SAP R/3 System: FUNCTION TB_DATAFED_RATE_RECEIVE_ASYNC IMPORTING feedname history update TABLES answer EXCEPTIONS no_authority update_error empty_table invalid_feedname.
feedname: history:
Name for the datafeed in the R/3 System Flag which indicates whether historical data are to be called up (X) or not( ) Flag which indicates whether the operational SAP tables are to be updated (X) or not ( ).
update:
CHAR 1:
The structure type of the table ANSWER is VTB_DFANS. The partner can call up the EXCEPTIONS to allow him to react to errors. 2. Initialization of real-time data transmission. Definition in the SAP R/3 System: FUNCTION IMPORTING TABLES TB_DATAFED_RATE_REQUEST_REALTIM feedname request error error_doku EXCEPTIONS
no_authority
15
July 1997
SAP AG Treasury
SAP
empty_table invalid_feedname internal_error. The partner can call up the real-time data requirements defined in the R/3 System. These are returned in table REQUEST. Error messages are returned in the table ERROR and detailed error documentation is returned in the table ERROR_DOKU (optional, advisable for external TRACE).
5. Error Processing
As from Release 3.0D, the following error messages are defined in the R/3 System for error processing. The error messages must be returned in the SSTATS field for each record in the answer structure: ok. C SAP R/3 Datafeed Customizing: Entry of datafeed parameters incomplete. Customizing of the SAP R/3 System must be changed. Remedy: Maintain the translation table in Customizing. Note: Error code can only be used by SAP. E SAP R/3 Datafeed-Customizing: Incorrect entries in the translation tables, see the long error text! Note: Error code can only be used by SAP. W SAP R/3 Datafeed market data monitoring: Rate/price differs too greatly from the last rate/price delivered. Remedy: If required, adjust the rate/price manually. Note: If necessary, the market data monitoring function can be adapted by increasing the difference tolerated. Note: Error code can only be used by SAP.
The error name range 50..99 is reserved for the partners. The partners can use this range freely. The partner must return an appropriate error message along with the error code.
Note for our partners: If the external interface program delivers error codes that lie outside the name range 50..99, certification cannot be granted. If such an error arises for the first time with a productive R/3 customer, SAP reserves the right to revoke an existing certificate.
16
July 1997
SAP Treasury
SAP
July 1997
17