Skip to main content
Hitachi Vantara Knowledge

Setting journals

This section describes how to specify settings of journals to be used in Universal Replicator by using the REST API.

Getting journal information

The following request gets a list of information about a journal.
Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/storages/storage-device-ID/journals
Request message
  • Object ID

    None.

  • Query parameters

    Parameter

    Type

    Filter Condition

    journalInfo

    string

    (Required) Type of information to be obtained

    The specifiable values are as follows:

    • basic: Basic journal information
    • timer: Journal time information
    • detail: Detailed journal information
  • Body

    None.

Response message
  • Body

    The following is an example of the output when basic journal information is obtained:

    {
      "data": [
        {
          "journalId": 0,
          "muNumber": 1,
          "consistencyGroupId": 5,
          "journalStatus": "PJSF",
          "numOfActivePaths": 1,
          "usageRate": 0,
          "qMarker": "575cc653",
          "qCount": 0,
          "byteFormatCapacity": "1.88 G",
          "blockCapacity": 3956736,
          "numOfLdevs": 1,
          "firstLdevId": 513
        }
      ]
    }

    Attribute

    Type

    Description

    journalId

    int

    Journal ID

    muNumber

    int

    MU (mirror unit) number

    consistencyGroupId

    int

    Consistency group identifier

    journalStatus

    string

    Journal volume status

    For details, see the section explaining the mirror journal statuses.

    numOfActivePaths

    int

    Number of active link paths

    usageRate

    int

    Usage rate of the journal volume

    qMarker

    string

    If the obtained journal is the master journal, the last sequential number (Q-marker) when the journal volume received the write data is output. If the obtained journal is the restore journal, the last sequential number (Q-marker) that is written in the cache is output.

    qCount

    long

    Number of qMarker remaining in the master journal volume

    byteFormatCapacity

    string

    Capacity of the journal volume

    The value is output to the second decimal place.

    blockCapacity

    long

    Number of blocks of the journal volume

    numOfLdevs

    int

    Number of LDEVs configuring the journal volume

    firstLdevId

    int

    LDEV number of the first LDEV assigned to the journal

    The following is an example of the output when journal time information is obtained:

    {
      "data": [
        {
          "journalId": 0,
          "muNumber": 1,
          "consistencyGroupId": 5,
          "journalStatus": "PJSF",
          "numOfActivePaths": 1,
          "usageRate": 0,
          "qMarker": "575cc653",
          "qCount": 0,
          "byteFormatCapacity": "1.88 G",
          "blockCapacity": 3956736,
          "dataOverflowWatchInSeconds": 60,
          "pathBlockadeWatchInMinutes": 5,
          "activePathWatchTimerSettingInSeconds": 40
        }
      ]
    }

    Attribute

    Type

    Description

    journalId

    int

    Journal ID

    muNumber

    int

    MU (mirror unit) number

    consistencyGroupId

    int

    Consistency group identifier

    journalStatus

    string

    Journal volume status

    For details, see the section explaining the mirror journal statuses.

    numOfActivePaths

    int

    Number of active link paths

    usageRate

    int

    Usage rate of the journal volume

    qMarker

    string

    If the obtained journal is the master journal, the last sequential number (Q-marker) when the journal volume received the write data is output. If the obtained journal is the restore journal, the last sequential number (Q-marker) that is written in the cache is output.

    qCount

    long

    Number of qMarker remaining in the master journal volume

    byteFormatCapacity

    string

    Capacity of the journal volume

    The value is output to the second decimal place.

    blockCapacity

    long

    Number of blocks of the journal volume

    dataOverflowWatchInSeconds

    int

    Data Overflow Watch timer setting (in seconds) per the Journal

    pathBlockadeWatchInMinutes

    int

    Path Blockade Watch timer setting (in minutes) per the Journal

    activePathWatchTimerSettingInSeconds

    int

    Active Path Watch timer setting (in seconds) to detect any link failures

    The following is an example of the output when detailed journal information is obtained:

    {
      "data": [
        {
          "journalId": 0,
          "isMainframe": false,
          "isCacheModeEnabled": true,
          "isInflowControlEnabled": true,
          "dataOverflowWatchInSeconds": 60,
          "copySpeed": 256,
          "isDataCopying": true,
          "mpBladeId": 0,
          "mirrorUnits": [
            {
              "muNumber": 0,
              "consistencyGroupId": 0,
              "journalStatus": "SMPL",
              "pathBlockadeWatchInMinutes": 5,
              "copyPace": "L"
              "copySpeed": 256,
              "isDataCopying": true,
            },
              ...
              ...
            {
              "muNumber": 3,
              "consistencyGroupId": 0,
              "journalStatus": "SMPL",
              "pathBlockadeWatchInMinutes": 5,
              "copyPace": "L"
              "copySpeed": 256,
              "isDataCopying": true,
            }
          ]
        }
      ]
    }

    Attribute

    Type

    Description

    journalId

    int

    Journal ID

    isMainframe

    boolean

    Indicates whether the journal is used for mainframe systems or open systems

    • true: The journal is used for mainframe systems
    • false: The journal is used for open systems

    mfTimerType

    string

    Timer type for mainframe systems

    • LOCAL: A local timer is used.
    • SYSTEM: A system timer is used.
    • none: A system timer is used (when the copy direction is the reverse).

    isCacheModeEnabled

    boolean

    Indicates whether the cache mode setting is enabled

    • true: The cache mode setting is enabled.
    • false: The cache mode setting is disabled.

    isInflowControlEnabled

    boolean

    Indicates whether an inflow of update I/O to the journal volume is limited

    • true: Inflow is limited.
    • false: Inflow is unlimited.

    dataOverflowWatchInSeconds

    int

    Data Overflow Watch timer setting (in seconds) per the Journal

    copySpeed

    int

    Transfer speed (in Mbps)

    The value set for the object whose MU (mirror unit) number is 3 is output. For details about the value for each mirror, see the description of the copySpeed attribute of the mirrorUnits object.

    isDataCopying

    boolean

    Copy mode "true" or "false" under failure of the delta resync:

    • true: copying ALL data
    • false: No copying

    The value set for the object whose MU (mirror unit) number is 3 is output. For details about the value for each mirror, see the description of the isDataCopying attribute of the mirrorUnits object.

    mpBladeId

    int

    MP blade ID

    mirrorUnits

    object[]

    The following attributes are output for each mirror:

    • muNumber (int)

      MU (mirror unit) number

    • consistencyGroupId (int)

      Consistency group ID

    • journalStatus (string)

      The journal status

      For details, see the section explaining the mirror journal statuses.

    • pathBlockadeWatchInMinutes (int)

      Path Blockade Watch timer setting (in minutes) per the Journal

    • copyPace (string)

      Copy speed

      • L: Low speed
      • M: Medium speed
      • H: High speed
    • copySpeed (int)

      Transfer speed (in Mbps)

    • isDataCopying (boolean)

      Copy mode "true" or "false" under failure of the delta resync:

      • true: copying ALL data
      • false: No copying
Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

To get basic journal information:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals?journalInfo=basic

To get journal time information:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals?journalInfo=timer

To get detailed journal information:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals?journalInfo=detail

Getting information about a specific journal

The following request gets basic information about the specified journal. To get journal time information or detailed journal information, run the API function for getting a list of journals.
NoteIf the specified journal is used in a 3DC configuration and multiple MUs are set for the journal, information about only one MU can be acquired for the API. In this situation, run the API function for getting a list of journals to get the information about the target journal ID.
Execution permission

Storage Administrator (View Only)

Request line
GET base-URL/v1/objects/storages/storage-device-ID/journals/object-ID
Request message
  • Object ID

    Specify the journalId value obtained by getting information about the journal.

    Attribute

    Type

    Description

    journalId

    int

    (Required) Journal ID

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "journalId": 0,
      "muNumber": 1,
      "consistencyGroupId": 5,
      "journalStatus": "PJSF",
      "numOfActivePaths": 1,
      "usageRate": 0,
      "qMarker": "575cc653",
      "qCount": 0,
      "byteFormatCapacity": "1.88 G",
      "blockCapacity": 3956736,
      "numOfLdevs": 1,
      "firstLdevId": 513
    }

    Attribute

    Type

    Description

    journalId

    int

    Journal ID

    muNumber

    int

    MU (mirror unit) number

    consistencyGroupId

    int

    Consistency group identifier

    journalStatus

    string

    Journal volume status

    For details, see the section explaining the mirror journal statuses.

    numOfActivePaths

    int

    Number of active link paths

    usageRate

    int

    Usage rate of the journal volume

    qMarker

    string

    If the obtained journal is the master journal, the last sequential number (Q-marker) when the journal volume received the write data is output. If the obtained journal is the restore journal, the last sequential number (Q-marker) that is written in the cache is output.

    qCount

    long

    Number of qMarker remaining in the master journal volume

    byteFormatCapacity

    string

    Capacity of the journal volume

    The value is output to the second decimal place.

    blockCapacity

    long

    Number of blocks of the journal volume

    numOfLdevs

    int

    Number of LDEVs configuring the journal volume

    firstLdevId

    int

    LDEV number of the first LDEV assigned to the journal

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/0

Creating a journal

The following request creates a journal and then adds a journal volume. Specify a DP volume for a journal volume to be added.
Note

This API function cannot be used for Virtual Storage Platform or HUS VM.

Execution permission

Storage Administrator (Remote Copy)

Request line

POST base-URL/v1/objects/storages/storage-device-ID/journals
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    The following is a coding example for creating a journal by specifying the LDEV number:

    {
      "journalId": 33,
      "ldevIds": [101,102]
    }

    When creating a journal by specifying the LDEV number

    Attribute

    Type

    Description

    journalId

    int

    (Required) Specify the journal ID.

    Specify a decimal (base 10) number in the range from 0 to 255.

    ldevIds

    int[]

    (Required) Specify the LDEV number with a decimal (base 10) number.

    You can specify up to 2 numbers.

    The following is a coding example for creating a journal by specifying a range of consecutive LDEV numbers:

    {
      "journalId": 33,
      "startLdevId": 101,
      "endLdevId": 102
    }

    When creating a journal by specifying a range of consecutive LDEV numbers

    Attribute

    Type

    Description

    journalId

    int

    (Required) Specify the journal ID with a decimal (base 10) number.

    startLdevId

    int

    (Required) Specify the first LDEV number by using a decimal (base 10) number.

    The value of this attribute must be smaller than that of endLdevId.

    endLdevId

    int

    (Required) Specify the last LDEV number by using a decimal (base 10) number.

    The value of this attribute must be greater than that of startLdevId.

    Specify a number such that the range indicated by the startLdevId and endLdevId attributes consists of no more than 2 LDEVs.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description on job objects.

    Attribute

    Description

    affectedResources

    URL of the created journal

Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description on HTTP status codes.

Status code

Message

Description

409

Conflict

A journal that has the specified journal ID already exists.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X POST --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals

The mirror journal status

The following table describes the mirror journal statuses for Universal Replicator.

Status

Description

SMPL

The mirror is not used.

P(S)JNN

The master journal (restore journal) is normal.

P(S)JSN

The master journal (restore journal) is in normal split status.

P(S)JNF

The master journal (restore journal) is full.

P(S)JSF

The master journal (restore journal) is full and split.

P(S)JSE

The master journal (restore journal) is split due to an error (including link errors).

P(S)JNS

The master journal (restore journal) is in normal split status (for the 3DC multi-target configuration that uses delta resync).

P(S)JES

The master journal (restore journal) is split due to an error (for the 3DC multi-target configuration that uses delta resync).

Changing journal settings

The following request changes the journal settings, such as Data Overflow Watch and the transfer speed.
Note

If a user uses the REST API to lock the resources of a target storage system, any request that includes a change to the transfer speed (the copySpeed attribute) cannot run. In such a case, unlock the resources before performing the operation.

Execution permission

Storage Administrator (Remote Copy)

Request line
PUT base-URL/v1/objects/storages/storage-device-ID/journals/object-ID

You can run this API request in a PATCH method.

Request message
  • Object ID

    Specify the value of journalId that was obtained by the processing to get information about journals.

    Attribute

    Type

    Description

    journalId

    int

    (Required) Journal ID

  • Query parameters

    None.

  • Body

    The following is a coding example for changing the following settings: Data Overflow Watch, cache mode, and transfer speed:

    {
      "dataOverflowWatchInSeconds": 60,
      "isCacheModeEnabled": true,
      "copySpeed": 100
    }

    The following is a coding example for changing the following settings: mirror copy speed and Path Blockade Watch Time for the mirror:

    {
      "mirrorUnit": {
        "muNumber": 0,
        "copyPace": "M",
        "pathBlockadeWatchInMinutes": 10
      }
    }

    The following is a coding example for changing the following settings: Data Overflow Watch, cache mode, transfer speed, copy speed per mirror, and Path Blockade Watch Time for the mirror:

    {
      "dataOverflowWatchInSeconds": 60,
      "isCacheModeEnabled": true,
      "copySpeed": 100,
      "mirrorUnit": {
        "muNumber": 0,
        "copyPace": "M",
        "pathBlockadeWatchInMinutes": 10
      }
    }

    Attribute

    Type

    Description

    dataOverflowWatchInSeconds

    int

    (Optional) Data Overflow Watch (in seconds)

    This value is set to 60 by default when a journal is created.

    If 0 is specified, control on inflow of update I/O to the journal volume will be disabled.

    isCacheModeEnabled

    boolean

    (Optional) Specify whether to enable the cache mode setting.

    • true: The cache mode setting is enabled.
    • false: Disable the cache mode setting.

    This value is set to true by default when a journal is created.

    copySpeed

    int

    (Optional) Transfer speed (in Mbps)

    Specify the transfer speed for data transfer. You can specify one of the following values:

    3, 10, 100, or 256

    This value is set to 256 by default when a journal is created.

    mirrorUnit

    object

    Specify the following attributes for each mirror:

    • (Optional) muNumber (int)

      MU (mirror unit) number

      Specify this attribute together with either the copyPace attribute or the pathBlockadeWatchInMinutes attribute.

    • (Optional) copyPace (string)

      Copy speed

      The type is not case sensitive.

      • L: Low speed
      • M: Medium speed
      • H: High speed

      This value is set to L by default when a journal is created.

    • (Optional) pathBlockadeWatchInMinutes (int)

      Path Blockade Watch Time (in minutes)

      Specify a value in the range from 0 to 60.

      This value is set to 5 by default when a journal is created.

      If 0 is specified, the Path Blockade Watch Time is not changed, and the function that transfers the Path Blockade Watch Time to the secondary site of the mirror (the RCU) is disabled.

      If a value other than 0 is specified, the specified value is set as the value for the Path Blockade Watch Time, and the function that transfers the Path Blockade Watch Time to the secondary site of the mirror (the RCU) is enabled.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description on job objects.

    Attribute

    Description

    affectedResources

    URL of the changed journal

    You can use detailed journal information to check changed setting values. You can obtain detailed information by specifying journalInfo=detail for the query parameter of the API for getting a list of journals.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X PUT --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/100

Adding a journal volume

The following request adds a journal volume to a journal to expand the journal. Specify a DP volume for a journal volume to be added.
NoteThis API function cannot be used for Virtual Storage Platform or HUS VM.
Execution permission

Storage Administrator (Remote Copy)

Request line
PUT base-URL/v1/objects/storages/storage-device-ID/journals/object-ID/actions/expand/invoke

You can run this API request in a POST method.

Request message
  • Object ID

    Specify the value of journalId that was obtained by the processing to get information about journals.

    Attribute

    Type

    Description

    journalId

    int

    (Required) Journal ID

  • Query parameters

    None.

  • Body

    {
      "parameters": {
        "ldevIds": [101]
      }
    }

    Attribute

    Type

    Description

    ldevIds

    int[]

    (Required) Specify the LDEV number with a decimal (base 10) number.

    You can specify only one LDEV.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description on job objects.

    Attribute

    Description

    affectedResources

    URL of the journal to which a volume was added

Action template

GET base-URL/v1/objects/storages/storage-device-ID/journals/object-ID/actions/expand
Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description on HTTP status codes.

Status code

Message

Description

412

Precondition Failed

The number of journal volumes that are registered to the target volume is already at the maximum.

Coding example

To get an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/3/actions/expand

To run the request after getting an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X PUT --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/3/actions/expand/invoke

Deleting a journal volume from a journal

The following request deletes the specified journal volume from a journal to shrink the journal.
NoteThis API function cannot be used for Virtual Storage Platform or HUS VM.
Execution permission

Storage Administrator (Remote Copy)

Request line
PUT base-URL/v1/objects/storages/storage-device-ID/journals/object-ID/actions/shrink/invoke

You can run this API request in a POST method.

Request message
  • Object ID

    Specify the value of journalId that was obtained by the processing to get information about journals.

    Attribute

    Type

    Description

    journalId

    int

    (Required) Journal ID

  • Query parameters

    None.

  • Body

    {
      "parameters": {
        "ldevIds": [101]
      }
    }

    Attribute

    Type

    Description

    ldevIds

    int[]

    (Required) Specify the LDEV number with a decimal (base 10) number.

    You can specify only one LDEV.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description on job objects.

    Attribute

    Description

    affectedResources

    URL of the journal from which a volume was deleted

Action template

GET base-URL/v1/objects/storages/storage-device-ID/journals/object-ID/actions/shrink
Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description on HTTP status codes.

Status code

Message

Description

412

Precondition Failed

Only one journal volume exists in the target journal, or pairs are created and the status of the journal volume is normal.

Coding example

To get an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/3/actions/shrink

To run the request after getting an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X PUT --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/3/actions/shrink/invoke

Changing the MP blade assigned to a journal

The following request changes the MP blade assigned to a journal.
Execution permission

Storage Administrator (System Resource Management)

Request line

PUT base-URL/v1/objects/storages/storage-device-ID/journals/object-ID/actions/assign-mp-blade/invoke

You can run this API request in a POST method.

Request message
  • Object ID

    Specify the journalId value obtained by getting journal information.

    Attribute

    Type

    Description

    journalId

    int

    (Required) Journal ID

  • Query parameters

    None.

  • Body

    {
        "parameters": {
            "mpBladeId": 1
        }
    }

    Attribute

    Type

    Description

    mpBladeId

    int

    (Required) The blade number of the MP blade to be assigned to the journal

Response message
  • Body

    A job object is returned. For details about attributes other than affectedResources, see the description of job objects.

    Attribute

    Description

    affectedResources

    URL of the journal for which the MP blade was changed

    You can use detailed journal information to check changed setting values. You can obtain detailed information by specifying journalInfo=detail for the query parameter of the API for getting a list of journals.

Action template

None.

Status codes

For details about the status codes of the request for this operation, see the description of the HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X PUT --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/3/actions/assign-mp-blade/invoke

Deleting a journal

The following request deletes a journal. A DP volume registered as a journal volume is not deleted. However, the DP volume can no longer be used as a journal.
Note

This API function cannot be used for Virtual Storage Platform or HUS VM.

Execution permission

Storage Administrator (Remote Copy)

Request line

DELETE base-URL/v1/objects/storages/storage-device-ID/journals/object-ID
Request message
  • Object ID

    Specify the value of journalId that was obtained by the processing to get information about journals.

    Attribute

    Type

    Description

    journalId

    int

    (Required) Journal ID

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description on job objects.

    Attribute

    Description

    affectedResources

    URL of the deleted journal

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X DELETE https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/journals/30

 

  • Was this article helpful?