Retrieving MainView data using the Common REST API (deprecated)

You can use the Common REST API (CRA) to retrieve MainView view definitions and MainView data:

Before you begin

You must have CRA installed and running. For more information, see Setting-up-the-Common-REST-API.

You have two endpoints for retrieving data from a MainView view:

Retrieving a view definition using the GetView endpoint

The GetView endpoint uses the POST method to retrieve a MainView view definition. To retrieve the view definition for a MainView view, use a URL based on the following structure:

https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<serviceName>/getView?product=<productName>&view=<viewName>

The variables represent the following values:

  • <hostName> is the name of the mainframe host where the CRA server is running.
  • <portNumber> is the port number of the CRA server.
  • <serviceName> is the name of the service as it appears on the list. For more information, see To retrieve a list of services.

Set the following parameters:

Note

If accepting the default value for a parameter, you can omit that parameter from the URL. However, parameters that do not have default values are required.

Parameter

Description

context

Context of the server from which you want to retrieve data

Default: *

product

(required) Product from which you want to retrieve data

Example: MVMVS

server

Server from which you want to retrieve data

Default: *

system

System from which you want to retrieve data

Default: *

scope

Scope for which you want to retrieve data

Default: *

view

(required) View for which you want to retrieve data

Example: JCPU

  1. In the Header, set the Content-Type to application/x-www-form-urlencoded. 
  2. In the Body, set the following key:
          userToken=<userToken>
    <userToken> is the token issued to you when you logged on. For more information, see Logging-in-to-a-service-using-the-Common-REST-API. 

In curl, the command would look something like the following example:

Example
curl -d "userToken=38651614-99ca-4ec8-90ce-334475abc0f4" https://mymainframe:161616/cra/ServiceGateway/Services/MVA/getView?product=MVMVS&view=JCPU

Error Codes

If you send a GetView request with incorrect inputs, you may see one of the following error codes:

Error Code

Message

Explanation

404

Invalid product name

You entered an empty product name.

Invalid view

You entered an empty MainView view name.

Invalid context

You entered an empty context name.

Invalid server

You entered an empty server name.

Invalid system

You entered an empty system name.

Retrieving view data using the GetData endpoint

The GetData endpoint uses the POST method to retrieve data from a MainView view. To retrieve data from a MainView view, use a URL based on the following structure:

  https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<servicename>/getData?product=<productname>&select=<select_statement>

The variables represent the following values:

  • <hostName> is the name of the Mainframe host where the Tomcat server is running.
  • <portNumber> is the port number of the Tomcat server.

Header parameter

This endpoint accepts the following header parameter:

Parameter

Description

session

(optional) Session token for retrieving more data for the same view as a previous GetData request

For more information, see Managing-Common-REST-API-session-tokens-and-user-tokens.

Parameters

Set the following parameters:

Note

If accepting the default value for a parameter, you can omit that parameter from the URL. However, parameters that do not have default values are required.

Parameter

Description

context

Context of the server from which you want to retrieve data

Default: *

product

(required) Product from which you want to retrieve data

server

Server from which you want to retrieve data

Default: *

system

System from which you want to retrieve data

Default: *

scope

Scope for which you want to retrieve data

Default: *

select

(required) Selection criteria for for your data request

Examples of select strings:

  • View name
  • WHERE clause
  • QWHERE clause

Notes

  • Replace any ampersand ( &) characters in your command strings with AND.
  • Replace any equals (=) characters in your command strings with EQUALS.
  • All text in the select parameter must be in uppercase.

For more information, see the MainView documentation on Forms and queries.

period

Timestamp of the data to be retrieved

Possible values are:

  • * is the current time.
  • = is the same time period as the previous request.
  • yyyy/mm/dd hh:mm:ss n h is n hours from timestamp.
  • yyyy/mm/dd hh:mm:ss nm is n minutes from timestamp.
  • yyyy/mm/dd hh:mm:ss ni is n intervals from timestamp.                  

Default: =

startrow

Row from which to start the data retrieval

Default: 1

rows

Number of rows to retrieve

Default: 200

Maximum: 999999

refresh

Whether to refresh the data for the request

Possible values are:

Y – Refresh the view data.  BMC recommends using this option for the initial GetData request.  

N – For subsequent requests, to get the same set view data as the previous request. For example, use N to get more rows of data from the same view.

Default: Y

close

(optional) Parameter for indicating if a session will stay open or not.

For more information, see Managing-Common-REST-API-session-tokens-and-user-tokens.

  1. In the Header, set the Content-Type to application/x-www-form-urlencoded. 
  2. In the Body, set the following key: 
          userToken=<userToken> 
    <userToken> is the token issued to you when you logged on. For more information, see Logging-in-to-a-service-using-the-Common-REST-API. 

In curl, the command would look something like the following example:

curl -d "userToken=38651614-99ca-4ec8-90ce-334475abc0f4" https://mymainframe:161616/cra/ServiceGateway/Services/MVA/getData?product=MVMVS&select=JCPU

Error Codes

If you send a Getdata request with incorrect inputs, you may see one of the following error codes:

Error Code

Message

Explanation

400

Invalid select command

You entered invalid inputs in the select command. For example, XWHERE is an invalid select command or an empty select command is also invalid.

Invalid period specification

You entered an invalid input in the period parameter. The period parameter must be *, =, or a time range.

Invalid rows

You entered an invalid input in the rows parameter. For example, a non-numeric character.

Invalid start row

You entered an invalid input in the startrow parameter. For example, a non-numeric character.

Invalid refresh

You entered something other than Y or N in the refresh parameter.

404

Invalid product name

You entered an empty product name.

Invalid view

You entered an empty MainView view name.

Invalid context

You entered an empty context name.

Invalid server

You entered an empty server name.

Invalid system

You entered an empty system name.

Related Topic

Administering-the-Common-REST-API

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*