Retrieving view data using the Common REST API

You can use the Common REST API (CRA) to retrieve data using the data endpoint. This endpoint retrieves the data for a specific view and returns the details as a JSON.

To retrieve data from a service, you must log in to the service and acquire a token. Until you log out or the token expires, you must pass this token to retrieve data requests from the selected service. For more information, see Logging-in-to-a-service-using-the-Common-REST-API.

Refer to the following sections to learn about retrieving data:

Retrieving data using the data endpoint

The data endpoint uses the GET method to retrieve data for a specific view. Use the following URL structure:

https://<hostName>:<portNumber>/cra/serviceGateway/services/products/<productName>/views/<viewName>/data

In SPE2410, we have deprecated the serviceName parameter from the URL. However, you can still use the existing URL.

https://<hostName>:<portNumber>/cra/serviceGateway/services/<serviceName>/products/<productName>/views/<viewName>/data

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.
(Optional) <serviceName> is the service name you use to log in to a service. For more information, see To retrieve a list of services.
Warning
Important
By default, the service name is the one you have logged in to work with the API.
<productName> is the name of the product as it appears on the list. For more information, see Retrieving-a-list-of-installed-products-using-the-Common-REST-API.
<viewName> is the name of the view within the product.

To retrieve sorted data from a GET data request

If you already have the field details, such as the field visibility, letter representing that field, and the field display name, only perform step 2.

(Optional) Make a REST request to the GET definition by using the following format:
https://<hostName>:<portNnumber>/cra/serviceGateway/services/products/<productName>/views/<viewName>/definition?close=Y
In the response, you get the data definition for the view and an array of columns. Each column displays the field headers, for example, the field visibility, the letter representing that field, and the field display name.
- productName and viewName are mandatory parameters
- Context, server, system, scope, and close are optional parameters
Make a GET data REST request to get the sorted data by using the following URL:
https://<hostName>:<portNnumber>/cra/serviceGateway/services/products/<productName>/views/<viewName>/data?context=%2A&
server=%2A&system=%2A&scope=%2A&period=%3D&startRow=1&rows=200&refresh=Y&close=Y&filter=null&sort=<fieldLetter.A or
fieldLetter.D>&prefix=null&formatMode=N
The GET data contains productName and viewName that are mandatory parameters. The GET data also contains optional parameters such as context, server, system, scope, period, startRow, rows, refresh, close, filter, sort, prefix, formatMode, and session.
- To sort the data by using one field, enter the query by using the following syntax:
  sort=<fieldname.A or fieldname.D>
  For example, sort=A.A or sort= B.D
- To sort the data by using multiple fields, enter the query by using the following syntax:
  sort=<fieldname.A&fieldname.D>
  For example, sort=A.A&B.D
  Warning
  Important
  A and B represent the field letters as defined in the response of the GET definition. .A and .D represent the ascending and descending order in which the data is sorted.

Authorization

Name	Located in	Description
Authorization	header	Authorization token formatted as 'Bearer [token]'

Query parameters

This endpoint accepts the following query parameters:

Parameter	Description
context	Context of the server from which you want to retrieve data Default: *
server	Server from which you want to retrieve data, usually the SSID Default: *
system	System from which you want to retrieve data, usually the LPAR Default: *
scope	Scope for which you want to retrieve data Default: *
period	Timestamp of the data to be retrieved Possible values are: * is the current time. * * PREV is the last complete interval. The size of the interval is based on the defined collection 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: = Warning Important * * PREV and = work as described only for an open session. For a single request, they return data for the current timestamp.
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 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
sort	To sort the data by using one field, enter the query by using the following syntax: sort=<fieldname.A or fieldname.D> For example, sort=A.A or sort= B.D To sort the data by using multiple fields, enter the query by using the following syntax: sort=<fieldname.A&fieldname.D> For example, sort=A.A&B.D Warning Important A and B represent the field letters as defined in the response of the GET definition. .A and .D represent the ascending and descending order in which the data is sorted.
filter	Generates a WHERE clause Example: filter APPLID=CMF&SYSNAME=S*
startrow	Row from which to start the data retrieval Default: 1
rows	Maximum number of rows to return Default: 200
session	(optional) Session token for retrieving more data for the same view as a previous data request For more information, see Managing-Common-REST-API-session-tokens-and-user-tokens.
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.

Response body

The returned data is a JSON object containing the following properties:

Property name	Type	Description
productName	String	Product name
viewName	String	View name
context	String
system	String	Only if sent as a header parameter
server	String	Only if sent as a header parameter
Time	String	Time of the data
Startrow	Integer	1-based index of the first row of data
Rows	Integer	Total number of rows returned for this request
Totalrowcount	Integer	Total number of rows available
rc	Integer	Return code from the API 2 = rows 4 = data and messages 8 and greater = messages but no rows
rows	Array of row data	Each object in the rowdata array contains key-value pairs for the data. The key refers to the dataname property of the column in the view definition. There may or may not be data in the rows array.
messages	Array of string	Messages from the host server There may or may not be data in the messages array.

HTTP status and reason codes

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

Error Code	Explanation
200	Successful completion
403	Unauthorized. The authorization token is missing, invalid, or expired
404	The path is not valid. Most likely because the service in the URL does not exist.

Example to view data

Request

The request example uses the following values:

<hostName> = myCRAhost
<portNumber> = 443
<serviceName> = Mva
<productName> = MVMVS
<viewName> = JCPU

GET https://myCRAhost:443/cra/serviceGateway/services/Mva/products/MVMVS/views/JCPU/data
Accept: application/json
Authorization: Bearer 08bc7580-2a7c-4e12-890f-c2b80f4891e8

Response

200 OK
Content-type: application/json

{
   "productName": "MVMVS",
   "viewName": "ARD",
   "context": "SJSC",
   "startrow": 120,
   "rowcount": 3,
   "totalrowcount": 399,
   "rc" : 0 ,
   "rows": [
       {
           "ASIXCPR": "1.719668",
           "ASGNAME": "DC$CAS",
           "JACT$IHR": "20",
           "ASLDPNV": "0",
           "ASSSWPR": "0",
           "ASIFXBAV": "0",
           "ASGCNMC": "STCGEN",
           "ASGDMNC": "N/A",
           "ASSWMART": "196.278366",
           "ASGNPG": "40",
           "ASIHVPRT": "0",
           "ASSHVPRT": "0",
           "ASSFXBAV": "0",
           "ASIFIXAV": "546.000000",
           "ASSCPSC": "406.570068",
           "ASSCSART": "0",
           "ASSFIXAV": "538.231689",
           "ASGLOCC": "I",
           "ASGFIX": "546",
           "ASREYFLC": "STC",
           "ASSXCPR": "0",
           "ASGFIXB": "0",
           "ASICSART": "0",
           "ASGFLXC": "Active",
           "ASGASCT": "00000077",
           "ASIWMART": "226.755768",
           "ASGDMN": "00",
           "ASGFL1C": "Active",
           "ASITCBSC": "4.360000",
           "ASGXMFC": "X",
           "ASICPSC": "4.589999",
           "ASSTCBSC": "388.159912",
           "ASRETOKN": "D7522ECF4403007C",
           "ASIDCTTM": "0",
           "ASSLPART": "0",
           "ASIIPNV": "0",
           "ASGJELT": "8282775",
           "ASSDCTTM": "0.016128",
           "ASGASID": "124",
           "ASISWPR": "0",
           "ASILPART": "0"
       },
       {
           "ASIXCPR": "0",
           "ASGNAME": "ESSXDC",
           "JACT$IHR": "20",
           "ASLDPNV": "0",
           "ASSSWPR": "0",
           "ASIFXBAV": "0",
           "ASGCNMC": "STCGEN",
           "ASGDMNC": "N/A",
           "ASSWMART": "1.033173",
           "ASGNPG": "40",
           "ASIHVPRT": "0",
           "ASSHVPRT": "0",
           "ASSFXBAV": "0",
           "ASIFIXAV": "146.000000",
           "ASSCPSC": "2.080000",
           "ASSCSART": "0",
           "ASSFIXAV": "145.876556",
           "ASGLOCC": "I",
           "ASGFIX": "146",
           "ASREYFLC": "STC",
           "ASSXCPR": "0",
           "ASGFIXB": "0",
           "ASICSART": "0",
           "ASGFLXC": "Active",
           "ASGASCT": "00000071",
           "ASIWMART": "0.545183",
           "ASGDMN": "00",
           "ASGFL1C": "Active",
           "ASITCBSC": "0",
           "ASGXMFC": "X",
           "ASICPSC": "0",
           "ASSTCBSC": "1.750000",
           "ASRETOKN": "D7522ED9F2B2007D",
           "ASIDCTTM": "0",
           "ASSLPART": "0.000024",
           "ASIIPNV": "0",
           "ASGJELT": "8281655",
           "ASSDCTTM": "0.109696",
           "ASGASID": "125",
           "ASISWPR": "0",
           "ASILPART": "0"
       },
       {
           "ASIXCPR": "0",
           "ASGNAME": "BP01",
           "JACT$IHR": "20",
           "ASLDPNV": "0",
           "ASSSWPR": "0",
           "ASIFXBAV": "0",
           "ASGCNMC": "STCGEN",
           "ASGDMNC": "N/A",
           "ASSWMART": "1.693616",
           "ASGNPG": "40",
           "ASIHVPRT": "0",
           "ASSHVPRT": "0",
           "ASSFXBAV": "0",
           "ASIFIXAV": "129.000000",
           "ASSCPSC": "3.520000",
           "ASSCSART": "0",
           "ASSFIXAV": "129.000000",
           "ASGLOCC": "I",
           "ASGFIX": "129",
           "ASREYFLC": "STC",
           "ASSXCPR": "0",
           "ASGFIXB": "0",
           "ASICSART": "0",
           "ASGFLXC": "Active",
           "ASGASCT": "00000072",
           "ASIWMART": "1.768367",
           "ASGDMN": "00",
           "ASGFL1C": "Active",
           "ASITCBSC": "0.020000",
           "ASGXMFC": "X",
           "ASICPSC": "0.040000",
           "ASSTCBSC": "1.470000",
           "ASRETOKN": "D7522ECF4539007E",
           "ASIDCTTM": "0",
           "ASSLPART": "0",
           "ASIIPNV": "0",
           "ASGJELT": "8282774",
           "ASSDCTTM": "0",
           "ASGASID": "126",
           "ASISWPR": "0",
           "ASILPART": "0"
       }
    ]
}

Example to view data with a specific context

Request

The request example uses the following values:

<hostName> = myCRAhost
<portNumber> = 443
<serviceName> = Mva
<productName> = MVMVS
<viewName> = JCPU
<context> = cont

GET https://myCRAhost:443/cra/serviceGateway/services/Mva/products/MVMVS/views/JCPU/data?context=CONT&startRow=1&rows=15&close=Y
Accept: application/json
Authorization: Bearer 08bc7580-2a7c-4e12-890f-c2b80f4891e8

Response

200 OK
Content-type: application/json
{
{
  "rc": 0,
  "system": "ABCD",
  "viewName": "JCPU",
  "startRow": 1,
  "numRows": 1,
  "context": "ABCD",
  "Columns": {
    "ASGRNMC": "C(8)",
    "ASRESCPN": "N(4.0)",
    "JACT$INT": "D(10),T(5)",
    "SYSNAME": "C(8)",
    "M390IND": "C(1)",
    "ASGJSFLY": "C(4)",
    "ASICPPCU": "N(5.2),G(17.0)",
    "ASGCNMC": "C(8)",
    "ASGJBID": "C(8)",
    "ASIENCV": "T(11),T(8)",
    "ASIENCP": "T(11),T(8)",
    "ASREYFLC": "C(1)",
    "ASIDPAV": "N(3.0)",
    "ASGZIITC": "T(12)",
    "ASIUCPP": "N(5.1)",
    "ASGFLXC": "C(7)",
    "ASRERGRP": "C(8)",
    "ASGCPET": "T(8)",
    "ASREZDECP": "T(14)",
    "ASRETOKN": "H(16)",
    "ASRIZIPT": "N(6.2)",
    "ASISWC": "N(5.0)",
    "ASICPPAU": "N(5.2),G(17.0)",
    "ASRECPUTCP": "N(5.1)",
    "ASITCPC": "N(5.1)",
    "ASIEPPUU": "N(7.2)",
    "ASGASID": "N(4.0)",
    "ASGCPUT": "T(12)",
    "ASRIZIPTS": "N(8.2)",
    "ASRIZDENC": "T(16)",
    "ASGNAME": "C(8)",
    "ASICPPEU": "N(5.2),G(17.0)",
    "ASICPSCP": "N(7.2),G(20.2)",
    "JACT$IHR": "N(2.0)",
    "ASREAPPLCP": "T(12)",
    "ASGFLSC": "C(7)",
    "ASREZIIN": "N(4.0)",
    "ASGNPG": "N(4.0)",
    "ASICPSCA": "N(7.2),G(20.2)",
    "ASIECPUU": "N(7.2)",
    "ASICPSCC": "N(7.2),G(20.2)",
    "ASREFLG1": "H(2)",
    "ASGPGP": "N(1.0)",
    "@STATUS": "C(*)",
    "ASGPHTM": "T(8)",
    "ASISRBPC": "N(5.1)",
    "ASIWCPP": "N(5.1)",
    "ASICPPPU": "N(5.2),G(17.0)",
    "ASGFL1C": "C(7)",
    "ASRERGTY": "C(8)",
    "ASICPSC": "N(7.2),G(20.2)",
    "ASGASST": "T(8)",
    "ASGJCLS": "C(8)",
    "ASREZDENC": "T(14)",
    "ASRIZDECP": "T(16)",
    "ASGJELT": "T(8)"
  },
  "totalRows": 206,
  "version": "2.1.00",
  "productName": "MVMVS",
  "Rows": [
    {
      "ASGRNMC": "",
      "ASRESCPN": "2",
      "JACT$INT": [
        {
          "0": "2023/07/05 06:32:28.78"
        },
        {
          "1": "2023/07/05 06:32:28.78"
        }
      ],
      "SYSNAME": "PQRD",
      "M390IND": "Y",
      "ASGJSFLY": " NO",
      "ASICPPCU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASGCNMC": "SYSTEM",
      "ASGJBID": "XCFAS",
      "ASIENCV": [
        {
          "0": "0"
        },
        {
          "1": "0"
        }
      ],
      "ASIENCP": [
        {
          "0": "0"
        },
        {
          "1": "0"
        }
      ],
      "ASREYFLC": "STC",
      "ASIDPAV": "255",
      "ASGZIITC": "0",
      "ASIUCPP": "0",
      "ASGFLXC": "Active",
      "ASRERGRP": "",
      "ASGCPET": "37119",
      "ASREZDECP": "0",
      "ASRETOKN": "DD8C86EEBDA40006",
      "ASRIZIPT": "0",
      "ASISWC": "18838",
      "ASICPPAU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASRECPUTCP": "2.907393",
      "ASITCPC": "67.654312",
      "ASIEPPUU": "0",
      "ASGASID": "6",
      "ASGCPUT": "37119",
      "ASRIZIPTS": "0",
      "ASRIZDENC": "0",
      "ASGNAME": "XCFAS",
      "ASICPPEU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASICPSCP": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "JACT$IHR": "6",
      "ASREAPPLCP": "405.000000",
      "ASGFLSC": "Active",
      "ASREZIIN": "4",
      "ASGNPG": "57",
      "ASICPSCA": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "ASIECPUU": "0",
      "ASICPSCC": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "ASREFLG1": "80",
      "ASGPGP": "1",
      "@STATUS": {
        "server": "XTS32PAS",
        "product": "MVMVS",
        "cwaction": "",
        "spanmins": "0",
        "numRows": "1",
        "editTitle": "",
        "about": "Y",
        "totalRows": "206",
        "history": "",
        "dblvl": "11",
        "rc": "0",
        "system": "SJSF",
        "viewName": "JCPU",
        "scope": "*",
        "context": "SJSF",
        "hybridSymbols": "",
        "queryName": "JCPU",
        "time": "2023/07/05 06:32:28.78",
        "ViewType": "D",
        "direction": ""
      },
      "ASGPHTM": "0",
      "ASISRBPC": "32.345673",
      "ASIWCPP": "0",
      "ASICPPPU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASGFL1C": "Active",
      "ASRERGTY": "N/A",
      "ASICPSC": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "ASGASST": "0",
      "ASGJCLS": "*",
      "ASREZDENC": "0",
      "ASRIZDECP": "0",
      "ASGJELT": "2267159"
    }
  ]
}

Retrieving view data using the Common REST API

Retrieving data using the data endpoint

To retrieve sorted data from a GET data request

Authorization

Query parameters

Response body

HTTP status and reason codes

Example to view data

Request

Response

Example to view data with a specific context

Request

Response

Common mainframe infrastructure 2022 release

On this page