Loads a local or remote Data Service Catalog into the current Session object.
The appropriate Catalog must be loaded before creating a JSDO for any resource defined in the Catalog.
If a Catalog is on a web server (remote), this method throws an exception if it is not possible to send a request to the specified web application.
This method can be called synchronously or asynchronously, depending on parameters that you pass.
Note: You can call this method either before or after the Session object has successfully established a JSDO login session using its login( ) method. However, if the Data Service Catalog is stored remotely in the web application that hosts the Data Object Service, Progress recommends that you log into the web application before calling this method.
Note: If you call addCatalog( ) passing catalog-uri, the method executes synchronously. If you call it passing parameter-object, the method executes synchronously or asynchronously, depending on the setting of parameter-object.
catalog-uri
A string expression that specifies the URI of a Data Service Catalog file. This URI can specify either a location (remote) in a web application running on a web server or a location (local) that is relative to the device where the app is currently running. If the URI specifies a remote location, it is typically the location of the web application that hosts the Data Object Service and where the Session object has a JSDO login session. If the URI is a relative path (e.g., catalogs/OrderEntrySvc.json), the catalog-uri is assumed to be relative to the location from which the app was loaded.
If the mobile app from which you are logging in is a hybrid app that will be installed to run directly in a native device container, or if it is a web app deployed to a different web server from the web application to which the Session object has already logged in, you must specify an absolute URI for the Catalog that includes the Tomcat server domain or host and port, for example, http://www.progress.com:8980/SportsMobileApp/static/OrderEntrySvc.json, or perhaps for testing, http://localhost:8980/SportsMobileApp/static/OrderEntrySvc.json.
If the Session object has already logged in and the mobile app is a web app deployed to the same Apache Tomcat server as the web application that hosts the Data Object Service, you can specify catalog-uri as a relative URI, for example: /SportsMobileApp/static/OrderEntrySvc.json, which is relative to the deployment end point (Tomcat server domain or host and port).
Note: The default Catalog URI for a Catalog created for an OpenEdge Data Object Service, relative to the Apache Tomcat server domain or host and port where the session is logged in, is the following: /WebApplicationName/static/ServiceName.json, where WebApplicationName is the name of the web application and ServiceName is the name of the Data Object Service for which the Data Service Catalog is created.
cat-user-name
A string expression containing a user ID to authenticate access to a protected Catalog. If you do not specify cat-user-name, Catalog access is authorized using existing user credentials (if any).
cat-password
A string expression containing a password (if required) to authenticate the user specified by cat-user-name.
parameter-object
An object that has one or more of the following properties:
catalogURI — (Required) Same value as the catalog-uri parameter.
userName — (Optional) Same value as the cat-user-name parameter.
password — (Optional) Same value as the cat-password parameter.
async — (Optional) A boolean that, if true, tells addCatalog( ) to execute asynchronously. If false or absent, addCatalog( ) executes synchronously.
iOSBasicAuthTimeout — A (Optional) number that specifies the time, in milliseconds, that the addCatalog( ) method waits for a response before returning an error. This error might mean that the user entered invalid credentials. If you set this value to zero (0), no timeout is set, and addCatalog( ) can wait indefinitely before returning an error. If you do not set the iOSBasicAuthTimeout property, addCatalog( ) uses 4000 (4 seconds) as the default value.
Any non-zero timeout value (default or otherwise) for this parameter-object property operates only under certain conditions, including when addCatalog( ) is executed asynchronously. Otherwise, any setting of this property has no effect. For more information, see the notes of the progress.data.Session class description.
Note: If the Session object is already logged in, you typically do not need to specify cat-user-name and cat-password (or the equivalent userName and password properties). These optional parameters are available primarily if the object is not yet logged in, or if you store the Catalog somewhere other than in the web application that hosts the Data Object Service (where the Session object has a JSDO login session).
Caution: Although you can use a single Session object to load a Catalog that is stored somewhere on the web other than the web application that hosts the Data Object Service, this typically works only if the Catalog is protected with Anonymous or HTTP Basic authentication.
Caution: To help ensure that HTTP Forms access to web applications works in certain web browsers, such as Firefox, when the web application is configured for Cross-Origin Resource Sharing (CORS), always call the addCatalog( ) method asynchronously.
You can read the catalogURIs property to return the URIs for all catalogs previously loaded for the login session.
When the method completes, it returns one of the following numeric constants to indicate the result:
progress.data.Session.ASYNC_PENDING — The method is called asynchronously, or if there is an error preparing to send the request to the server, it throws an Error object. All asynchronous execution results (including any server errors) are returned in the afterAddCatalog event that is fired on the Session object after the method completes. Before calling the method, you can subscribe one or more handlers to this event using the subscribe( ) method on the Session object.
progress.data.Session.SUCCESS — The specified Data Service Catalog loaded successfully.
progress.data.Session.CATALOG_ALREADY_LOADED — The specified Data Service Catalog did not load because it is already loaded.
progress.data.Session.AUTHENTICATION_FAILURE — The Catalog failed to load because of a user authentication error.
progress.data.Session.GENERAL_FAILURE — The specified Catalog failed to load because of an error other than an authentication failure.
It is also possible for this method to throw an Error object, in which case it does not return a value at all. For more detailed information about any response (successful or unsuccessful) returned from the web server, you can also check the XMLHttpRequest object (XHR) returned by the lastSessionXHR property.
Note: When called asynchronously, any handler for the afterAddCatalog event is passed the same information that is available for the addCatalog( ) method when it is called synchronously, including the Session object that executed addCatalog( ) (with the same property settings) and any Error object that was thrown processing the server response.
Caution: To help ensure that HTTP Forms access to web applications works in certain web browsers, such as Firefox, when the web application is configured for Cross-Origin Resource Sharing (CORS), always call the addCatalog( ) method asynchronously.
Example
The following code fragment calls the addCatalog( ) method synchronously on the session, empSession by omitting the async property from its object parameter. For a similar example with the method called asynchronously, see the reference entry for the afterAddCatalog event. This synchronous example uses try and catch blocks to check for either expected success and failure return values, or a thrown Error object with an unknown error, and assembles an appropriate message to display in an alert box for each case:
catalogURI — (Required) Same value as the catalog-uri parameter.