The options Object

For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

The options Object

The options object contains properties that are common to all methods. It is used in all asynchronous calls to the IBM MobileFirst™ Platform Server

Pass an options object for all asynchronous calls to MobileFirst Server. The options object contains properties that are common to all methods. Sometimes it is augmented by properties that are only applicable to specific methods. These additional properties are detailed as part of the description of the specific methods.
The common properties of the options object are as follows:
options = {
  onSuccess: success-handler-function(response),
  onFailure: failure-handler-function(response),
  invocationContext: invocation-context
};
The meaning of each property is as follows:
Table 1. Options object properties
Property Description
onSuccess
Optional. The function to be invoked on successful completion of the asynchronous call.
The syntax of the onSuccess function is:
success-handler-function(response)
where response is an object that contains at a minimum the following property:
invocationContext

The invocationContext object that was originally passed to the MobileFirst Server in the options object, or undefined if no invocationContext object was passed.

status

The HTTP response status

Note: For methods for which the response object contains additional properties, these properties are detailed as part of the description of the specific method.
onFailure
Optional. The function to be invoked when the asynchronous call fails. Such failures include both server-side errors, and client-side errors that occurred during asynchronous calls, such as server connection failure or timed out calls.
Note: The function is not called for client-side errors that stop the execution by throwing an exception.
The syntax of the onFailure function is:
failure-handler-function(response)
where response is an object that contains the following properties:
invocationContext

The invocationContext object that was originally passed to the MobileFirst Server in the options object, or undefined if no invocationContext object was passed.

errorCode

An error code string. All error codes that can be returned are defined as constants in the WL.ErrorCode object in the worklight.js file.

errorMsg

An error message that is provided by the MobileFirst Server. This message is for the developer's use only, and should not be displayed to the user. It will not be translated to the user's language.

status

The HTTP response status

Note: For methods for which the response object contains additional properties, these properties are detailed as part of the description of the specific method.
invocationContext Optional. An object that is returned to the success and failure handlers.
The invocationContext object is used to preserve the context of the calling asynchronous service upon returning from the service.
For example, the invokeProcedure method might be called successively, using the same success handler. The success handler needs to be able to identify which call to invokeProcedure is being handled. One solution is to implement the invocationContext object as an integer, and increment its value by one for each call of invokeProcedure. When it invokes the success handler, the MobileFirst framework passes to it the invocationContext object of the options object associated with the invokeProcedure method. The value of the invocationContext object can be used to identify the call to invokeProcedure with which the results that are being handled are associated.
Parent topic: JavaScript client-side API


Property	Description
onSuccess	Optional. The function to be invoked on successful completion of the asynchronous call. The syntax of the onSuccess function is: success-handler-function(response) where response is an object that contains at a minimum the following property: invocationContext The invocationContext object that was originally passed to the MobileFirst Server in the options object, or undefined if no invocationContext object was passed. status The HTTP response status Note: For methods for which the response object contains additional properties, these properties are detailed as part of the description of the specific method.
onFailure	Optional. The function to be invoked when the asynchronous call fails. Such failures include both server-side errors, and client-side errors that occurred during asynchronous calls, such as server connection failure or timed out calls. Note: The function is not called for client-side errors that stop the execution by throwing an exception. The syntax of the onFailure function is: failure-handler-function(response) where response is an object that contains the following properties: invocationContext The invocationContext object that was originally passed to the MobileFirst Server in the options object, or undefined if no invocationContext object was passed. errorCode An error code string. All error codes that can be returned are defined as constants in the WL.ErrorCode object in the worklight.js file. errorMsg An error message that is provided by the MobileFirst Server. This message is for the developer's use only, and should not be displayed to the user. It will not be translated to the user's language. status The HTTP response status Note: For methods for which the response object contains additional properties, these properties are detailed as part of the description of the specific method.
invocationContext	Optional. An object that is returned to the success and failure handlers. The invocationContext object is used to preserve the context of the calling asynchronous service upon returning from the service. For example, the invokeProcedure method might be called successively, using the same success handler. The success handler needs to be able to identify which call to invokeProcedure is being handled. One solution is to implement the invocationContext object as an integer, and increment its value by one for each call of invokeProcedure. When it invokes the success handler, the MobileFirst framework passes to it the invocationContext object of the options object associated with the invokeProcedure method. The value of the invocationContext object can be used to identify the call to invokeProcedure with which the results that are being handled are associated.