Description of Functions

Use

The SAP Data Provider works according to the Push Model, that is, before a control can receive a reference to a data object, the data is always transferred by the server to the client as an internal table (using RFC).

Every data object has a unique name that normally references the

sapr3://<GUID>

syntax and is shown as a URL. To get a reference to a data object you must specify its URL.

The data is often shown as an internal table at the client-side but there are also standard interfaces for mass data. These display forms are called media. Enter the medium you require when accessing the data. The data is then displayed in accordance with this and converted as required.

Every data object at the client side is described by the Type and SubType attributes that are closely connected with MIME types used on the internet and which are displayed as Format. Conversions between different media are controlled uing the format of the data object since different conversions are possible for different formats. You can also convert data objects of one format into data objects of another format. Such conversions are controlled using the source and target format.

The same principle applies for backtransports from the client to the server. You can put data in the DataProvider object using any medium. If no URL is available, you must assign a URL to the data object using the SAP Data Provider. Then, by specifying this URL you can transfer the data object to the application server as an internal table.

The SAP Data Provider can also process URLs in the namespaces http:, ftp:, and file: to make it possible to access non-SAP data sources. The procedure for these namesapces is the same as is described above with the exception that the data is not transferred from the application server to the client using a Push Model but that a Pull Model is loaded by the corresponding server.

Using MIME Types

MIME types are used to describe BLOB data (Binary Large Objects). You can use MIME types to control the conversion of different types of BLOB data and also to get access to the data objects yourself.

By specifying a MIME type or a part of a MIME type before accessing a server you can ensure that a data transfer is only triggered later when data of the relevant type is available.

If there is data in multiple formats, you can specify the MIME type to determine which format is to be used. In this context, the following rules apply:

Specifying the MIME type	Processing
Type and subtype are specified.	Only data of this MIME type is processed.
Type or subtype is specified.	Only data that matches the part that is specified is processed. The other part is ignored or interpreted as wildcard characters.
Neither type nor subtype is specified.	All the data is processed. This can lead to unnecessary server accesses and poor performance.

You must always specify a MIME type for BLOB data. Otherwise the data is not accepted and an error occurs.

If no suitable standard MIME type is available for a data object, you can use any name of your choice:
- The main type should always be called 'application'.
- The subtype should always start with 'x-' (for example, 'application/x-myspecialtype').
If the MIME type is not relevant, use 'application/x-unknown'.
If you want to tansport data of a MIME type of your own (not a standard) from/to an http: server, choose one of the following options:
- Use the standard MIME type 'application/octet-stream'.
- Register you own MIME type on the http: server.

Typed Tables

You need to know the structure of a table at the client-side if you want to transport typed tables.

Always used application/x-r3table as the MIME type.

A table of type RFC_FIELDS (which describes the actual data table) is also transferred. There is a conversion object for this data object type which corresponds to the requirements of typed tables.

The function modules in the function group CNDP are provided for transporting typed tables.

Caution

When tranporting typed tables from the client to an ABAP program, first transport an empty table of the same type to client. Then the program/control can fill this table at the client-side and you can then transport the table back to the server at another time.
It is not possible to transport typed internal tables to or from http:, ftp:, or file: servers since this would require a known and secure protocol to serialize the internal tables. It makes more sense to avoid OLE DB and Active Data Object (ADO). The format conversion object required for this is registered under the MIME type application/x-rowset.
There is no delta management in RFC between the SAP GUI and the application server. For this reason you should no send any tables to the client, modify them, and then request them again from the application server. You can try to save the modification in a table of your own. This does not make sense for BLOB data since it is very awkward to modify BLOB data in ABAP programs.

Transferring Data from ABAP Program to Client

To create a control for maintaining BLOB data, the ABAP program calls CONTROL_CREATE or another similar module.
The ABAP program reads the BLOB data to an internal table.
The ABAP program calls a function module, for example, DP_SEND_STREAM. This function module contains parameters for the internal table with the data, the size of the BLOB data in bytes, and the MIME type of the BLOB data.
- The function module that is called provdes system information and calls DP_CREATE_URL.
- DP_CREATE_URL creates a unqiue name (sapr3://<GUID>) for the current data object.
- DP_PUT_CLIENT_TABLE is called in SAP GUI (SAPAWRFC.DLL). The internal table, size, MIME type of the data, URL, and system information are transmitted to this function.
  - DP_PUT_CLIENT_TABLE couples the internal table with an ISAPrfcITab interface.
  - A reference to the ISAPrfcITab interface, the MIME type, size of the BLOB data, and other system information is stored in the LocalTables global object together with the URL. An identifier for the current context is also saved.
  - As a result, DP_CREATE_URL gets the name (URL) where a reference has been saved to the internal table in LocalTables.
The control created in point 1 recognizes and generates a DataProvider object. If not, see point 5.
- The URL of the data object is transferred to the control using CONTROL_SET_PROPERTY or CONTROL_CALL_METHOD.
  - The control creates a DataProvider object.
  - In the DataProviderobject, the control calls (for example) the SetDataFromUrl method with the URL as the parameter.
    
    The DataProvider object creates a reference to the global LocalTables object.
    
    The URL is sent to the LocalTables object. In this way the DataProvider object gets a reference to the ISAPrfcITab interface.
- The control reads the data using a property of the DataProvider object.
  - The DataProvider object gets the data according to the access medium that was requested by the control. The access to the data does not necessarily take place using the ISAPrfcITab interface. It can also happen using all standard COM interfaces (IStream, ILockBytes, IUnknown, VARIANT, and so on).
- See point 8.
The ABAP program calls the DP_CREATE function module that creates a DataProvider object at the client side.
The ABAP program calls the SetDataFromUrl method of the DataProvider object and sends the URL as actual parameter.
- The DataProvider object creates a reference to the global LocalTables object.
- The URL is sent to the LocalTables object. In this way the DataProvider object gets a reference to the ISAPrfcITab interface and all additional information.
The control created under point 1 does not recognize the SAP Data Provider.
- The ABAP program calls CONTROL_ASSIGN_PROPERTY2. This assigns a property of the DataProvider object to a property of the control.
  
  The data is sent to the control depending on the data type, MIME type, and property used (medium).
The transaction is ended.
A new transaction is started.
- The SAP GUI recognizes that the last transaction is ended.
- SAP GUI creates a reference to the global LocalTables object and informs this object about the last transaction being ended by sending the context identifier of the ended transaction.
  - The LocalTables object deletes all references to tables with the specified context identifier and releases these references (Garbage Collection).

Other File Sources

If the data object does not comes from the ABAP program but from an external source, you can implement the same procedure with the following exceptions:

Leave out points 2 and 3 for transferring to the client.
Create the reference to the data object using the URL.

Namespaces ftp:, http:, and file: are supported.

Transferring Data from Client to ABAP Program

The ABAP program creates a control by calling CONTROL_CREATE or another similar module.
The control created in point 1 recognizes the DataProvider object. If not, see point 3.
- The control creates a DataProvider object.
- The control assigns a reference to its data in an appropriate medium to the DataProvider object.
- The control calls the method SaveDataToUrl in the DataProvider object. Either the control specifies the URL, or the DataProvider object generates a URL with the syntax "sapr3://<GUID>".
  - The DataProvider object creates a reference to the global LocalTables object.
  - Both the URL and a reference to the data object are transmitted to this global object.
  - See point 4.
The control created in point 1 does not recognize the DataProvider object.
- The ABAP program creates a DataProvider object using DP_CREATE.
- The ABAP program creates a relelvant format object.
- The ABAP program calls CONTROL_ASSIGN_PROPERTY2. This assigns a property of the control to the format object of the control. This control property either contains the data or a reference to the data.
- The ABAP program calls the method SaveDataToUrl in the DataProvider object.
- See no. 2.
The data is sent to the ABAP program.
- The ABAP program calls the DP_GET_STREAM function module. This function module contains an internal table (where the data is to be saved) as a parameter, as well as the URL of the data object from no. 2.
- DP_GET_STREAM calls the DP_GET_CLIENT_TABLE function in the SAP GUI (SAPAWRFC.DLL) and sends the URL and table.
  - DP_GET_CLIENT_TABLE creates a reference to the global LocalTables object.
  - The URL is sent to the LocalTables object and gets a reference to the data object as response.
  - The data object is copied to the internal table that was sent to DP_GET_CLIENT_TABLE.
  - The reference to the data object is deleted from the LocalTables object and released.
- As a result, DP_GET_STREAM gets the data, MIME type, and size of the BLOB data in bytes.

Other Data Storage

You can also save data on ftp:, http:, or file: servers. For this, just assign the data and call the SaveDataToUrl method in the DataProvider object.

Since this or other procedure can be required again and again for sending and receiving data, the most important steps are encapsultated in ABAP function modules.