Skip to content

Troubleshooting with ILOData

Interactive Local OData (ILOData) is a command line utility that lets you execute OData requests, upload and download against a local offline store.

ILOData functions in the same way as an offline OData client, without the need for an application or device, enabling you to test data from the back-end service.

If an offline store exists, ILOData uses it. If not, ILOData performs a download to create the offline store. To perform a download, you must set defining_query and service_root. If no defining queries are specified on the command line and no offline store exists, you are prompted to enter defining queries before ILOData opens the offline store.

To use ILOData against an existing offline store, you must first retrieve the underlying offline store files from the device they were created on. Offline store files include two database files, prefixed with the store name (or the default name if no store name was specified when the offline store was created). One has a .rq.udb suffix and the other has a .udb suffix. These files are located in the directory provided in the store_path option, or in the application data directory by default if no store_path has been provided.

Syntax

1
ilodata.exe -[option=<value> [option=<value> ...]]

Options

  • host The host name of the mobile services server.

  • port The port of the mobile services server.

  • appcid The application client ID.

Note

This is required by SAP Mobile Platform server and you DO NOT need to specify it for SAP Cloud Platform server.

  • custom_cookie A dictionary of custom cookies to add to all HTTP communications. Custom cookies are added to HTTP requests between the offline store and mobile services and to HTTP requests between mobile services and the back-end OData service. For example, custom_cookie=name1:value1;.

  • custom_header A dictionary of custom headers to add to all HTTP communications. Custom headers are added to HTTP requests between the offline store and SAP Cloud Platform Mobile Services and to HTTP requests between mobile services and the back-end OData service. For example, custom_header=name1:value1;.

  • defining_query An OData read request that targets the OData endpoint that is associated with the offline store and retrieves a subset of the data, either during initialization of the offline store or during a download. Multiple defining queries can be defined for each OData endpoint by specifying multiple defining_query options on the command line. Defining queries become fixed for an offline store after the first time the store is opened.

    If no defining queries are provided on the command line, and no database files exist, ILOData prompts you to specify them. You can specify a name for the defining query (the name that would be used for a selective download and/or in an application configuration .ini file on the mobile services), as well as specify whether to download media streams. When the defining queries are specified using command line options, media streams are not downloaded by default, and the defining queries' names are the index at which they are specified. For example, in the following ILOData command, the first defining query would be named “1” and the second defining request would be named “2”.

1
ilodata defining_query=Events defining_query=Sessions
  • enable_https Whether to use HTTP or HTTPS to communicate with the mobile services. The default is no.

  • enable_repeatable_reqs Whether the back-end OData service supports repeatable requests. Repeatable requests (or idempotent requests) are a feature of some OData services that ensure OData requests are applied only once, even if they are received multiple times. This is useful in cases where OData responses may be lost due to intermittent network connectivity and is required by the offline store to guarantee that requests are applied exactly once to the back-end OData service.

  • extra_stream_parms Additional advanced stream parameters.

  • identity_file A file containing a client authentication certificate.

  • identity_password The password to use with the client authentication certificate.

  • log_file A file in which to log output.

  • prompt Override the default ILOData prompt.

  • retry_download The number of times to retry a download or store open when a failure occurs. The default is 0 (no retry).

  • retry_wait The amount of time, in milliseconds, to wait before retrying a download. The default is 100.

  • service_root The service root of the OData service. When the server is an instance of mobile services, this value depends on the Rewrite Mode configuration in the server-side application. If Rewrite Mode is set to Rewrite URL, then this is the name of the application back-end connector. If Rewrite Mode is set to Rewrite URL on Back End, then this is the path of the back-end OData endpoint. For example, if the application is configured with a connector named myconn to an OData endpoint of http://myhost:80/odata/endpoint, then the service_root should be myconn for Rewrite URL and odata/endpoint for Rewrite URL on Back End.

Note

The mobile service does not provide the functionality to use No Rewriting mode to support external back ends for offline usage.

  • store_key The key that encrypts the local database. By default the database is not encrypted.

  • store_name An arbitrary name that identifies the offline store. If omitted, the default name lodata is used.

  • store_path The file system path to store the offline store files. The default is the current directory.

  • trusted_certificate A file containing a trusted root certificate.

  • url_suffix The URL suffix path to the server. Specify the suffix to add to the URL of each HTTP request sent to the server.

  • username The user name to authenticate with the OData service.

  • password The password to authenticate with the OData service.

Formats of Data Used with ILOData

  • null | NULL (case sensitive)

  • binary: 0xhhhhhh (hh is a pair of hexidecimal digits)

  • boolean: true | false

  • byte, sbyte, int16, int32, int64: [0-9]*

  • datetime: yyyy-mm-dd[T]hh:mm:ss.ssssss (time portion is optional)

  • datetime_offset: like datetime plus timezone

  • decimal, double, single: normal numeric representation for type

  • guid: hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh (h is hex digit)

  • time: PnYnMnWnDTnHnMn[.m]S each component is optional

Commands

You can run commands in ILOData, or you can specify them on the command line, to run immediately on startup.

For example, command=get ~/T1 causes ILOData to exit immediately after executing the command.

Command Option Description
delete <id_url> Execute the given DELETE request.
exit Quit ILOData.
upload Upload queued requests.
get [request] Execute the given GET request.
help Print usage information.
patch <id_url> [prop=value] Execute the given PATCH request.

id_url is an URL identifying an entity.1
patch <link_url> [id_url] Execute the given request to modify a link.

link_url is an URL identifying a navigation property.1

id_url is an URL identifying an entity.1
post <set_url> [prop=value] Execute the given POST request.

set_url is an URL identifying an entity set.1

POST requests support:
  • Deep inserts and complex types. The syntax for both is the same. ILOData allows wrapping groups of properties for deep inserted entities or complex type properties in curly braces ({}).
  • Bind operations. To perform a bind, rather than setting the navigation property to an object ({}), you set the value to a URL.
put <id_url> [prop=value] Execute the given PUT request.

id_url is an URL identifying an entity.1
put <link_url> [id_url] Execute the given request to modify a link.

link_url is an URL identifying a navigation property.1

id_url is an URL identifying an entity.1
download Perform a delta download.
register <name> <id_url> Register a media stream request.

id_url is an URL identifying an entity.1
requestQueueIsEmpty Returns whether or not the request queue is empty.
set name=value Set an ILOData variable.
pagesize variable The page size for server driven paging. pagesize must be a 32-bit integer greater than 0. A special value for this variable is NO_PAGING, which means do not use server driven paging. NO_PAGING is the default.
unregister <name> Unregister a media stream request.
Batch operations The important commands for executing batch operations are:
  • start batch start a batch request.
  • start change set start a change set when within a batch.
  • add change set add the current change set to the batch
  • execute batch execute the requests in the current batch.
  • cancel batch cancel the current batch when building a batch.
  • cancel change set cancel the current change set when building a change set.
Each request within a change set is given an request number. The request number can be used as a Content-ID reference in later requests in the same change set.

1 All URLs must be properly encoded, particularly spaces and slashes. All values that contain spaces or tabs must be quoted with double quotes ("). All other values can be, but aren't required to be quoted with double quotes. Quoted values may contain \, \xhh and "" escape sequences. Except when noted, values are case insensitive.

Examples

Example 1: Create a new offline store using the SAP Mobile Platform server

1
2
ilodata host=smpHost.sap.corp port=8080 service_root=com.test.mySampleApp
defining_query=MySampleCollection appcid=9ae89115-b7e2-41d8-a20e-524729b9278a username=jdoe password=pw123

Example 2: Create a new entity

1
ILOData> post MySampleCollection strProp="myvalue1" dateProp="2015-01-01 T12:00:00"

Example 3: Query the error archive

1
ILOData> get ErrorArchive

Example 4: Batch operations

  • Batch operation #1:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    ILOData > start batch
    -------------------------------------------------------------------------------------------------------
    Batch Operation #1 > start change set
    -------------------------------------------------------------------------------------------------------
    Change Set #1 Operation #1 > post Customers ID=3 GivenName="John" Surname="Doe"
    The operation was successfully added to the change set.
    ------------------------------------------------------------------------------------------------------
    Change Set #1 Operation #2 > post $1/Orders ID=3 FinancialCode="r1" Region="Eastern"    SalesRepresentative=299 OrderDate="2017-07-04T00:00:00.000"
    The operation was successfully added to the change set.
    -------------------------------------------------------------------------------------------------------
    Change Set #1 Operation #3 > add change set
    The change set was successfully added to the batch.
    
  • Batch operation #2:

    1
    2
    Batch Operation #2 > get Customers?$expand=Orders&$orderby=ID
    The query was successfully added to the batch.
    
  • Batch operation #3:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    Batch Operation #3 > start change set
    -------------------------------------------------------------------------------------------------------
    Change Set #2 Operation #1 > post Customers ID=4 GivenName="John" Surname="Doe"
    The operation was successfully added to the change set.
    -----------------------------------------------------------------------------------------------------
    Change Set #2 Operation #2 > post $1/Orders ID=4 FinancialCode="r1" Region="Canada" SalesRepresentative=299 OrderDate="2017-07-04T12:00:00.000"
    The operation was successfully added to the change set.
    ----------------------------------------------------------------------------------------------------
    Change Set #2 Operation #3 > post $2/OrderItems LineID=1 ProductID=1 Quantity=1 ShipDate="2017-07-04T13:00:00.000"
    The operation was successfully added to the change set.
    --------------------------------------------------------------------    ---------------------------
    Change Set #2 Operation #4 > add change set
    The change set was successfully added to the batch.
    
  • Batch operation #4:

    1
    2
    Batch Operation #4 > get Customers?$expand=Orders/OrderItems&$orderby=ID
    The query was successfully added to the batch.
    
  • Batch operation #5:

    1
    Batch Operation #5 > execute batch
    

Example 5: Deep insert and complex type

  • This example performs a deep insert of a customer within a new order, then retrieves the new customer:
1
2
3
4
5
6
7
ILOData > post Orders Customer={ID=2 GivenName="John" Surname="Doe"} ID=2 FinancialCode="r1" Region="Eastern" SalesRepresentative=299 OrderDate="2017-07-04T00:00:00.000"

HTTP 201: Created
-------------------------------------------------------------------------------------------------------------------
ILOData > get Customers?$expand=Orders&$orderby=ID,Orders/ID

HTTP 200: OK
  • This example illustrates how to work with complex types:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
ILOData > post Customers ID=3 GivenName="John" Surname="Doe" Address={Street=445 Wes Graham Way City=Waterloo Country=Canada}     

HTTP 201: Created
------------------------------------------------------------------------------------------------------------------

ILOData > upload

Upload complete
--------------------------------------------------------------------------------
ILOData > download

Download complete

Example 6: Bind operations

  • The following example creates a new customer and binds it to two existing orders:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
ILOData > post Customers ID=3 GivenName="John" Surname="Doe" Orders="Orders(3)" Orders="Orders(4)"

HTTP 201: Created
------------------------------------------------------------------------------------------------------------------

ILOData > upload

Upload complete
--------------------------------------------------------------------------------
ILOData > download

Download complete
--------------------------------------------------------------------------------
ILOData > get Customers?$expand=Orders&$orderby=ID,Orders/ID


HTTP 200: OK

Tip

  • If you set the value of a navigation property to an object (for example, Orders= {….}) it is treated as a deep insert.
  • If you set the value of a navigation property to a URL (for example, Orders=Customers(101)), it is treated as a bind.

Example 7: Event log with data changed flag

  1. From the ilodata command line open a store with the parameter:

    1
    extra_stream_parms=_data_changed_by_download_flag;
    
  2. Retrieve the EventLog with the get EventLog command.

  3. If there have been any changes, or for the initial download, the log shows "DataChanged": true:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    {
        "_metadata": {
            "uri": "EventLog(1L)",
        "type": "offlineOData.Event"
        },
        "ID": "1",
        "Type": "download",
        "Time": "\/Date (1500988667440-240) \/",
        "Details": null,
        "DataChanged": true
    }
    

Note

Performing a download operation when no data has changed in the back end results in "DataChanged": false in the the EventLog. DataChanged is null for other types of events, such as upload.