add docs

Signed-off-by: Anatoli Kalbasin <[email protected]>

README.md

@@ -129,6 +129,47 @@ deleteDataset dsn:"EXAMPLE.DATASET"
     ISRZ002 Data set in use - Data set 'EXAMPLE.DS.ISUSED.BY.USER' in use by another user, try later or enter HELP for a list of jobs and users allocated to 'EXAMPLE.DS.ISUSED.BY.USER'.
     ```
 
+### `performMvsCommand` - Execute an MVS System Command
+The output of a command can be returned to a variable and subsequently processed. The step must be accompanied by `script` tag. It gives wide range of options such displaying system activities, device statuses, managing configuration, starting system tasks, etc.
+
+#### Usage:
+
+The step can be specified in two ways:
+```groovy
+performMvsCommand "DISPLAY TIME"
+```
+or using the named parameter:
+```groovy
+performMvsCommand command: "DISPLAY TIME"
+```
+**Mandatory Parameters:** there is only one parameter - `command`.
+
+#### Example - Displaying Active Units of Work:
+To display detailed information about all active units of work, use the following command:
+```groovy
+def active_units = performMvsCommand "D A,L"
+```
+
+#### Expected behavior under various scenarios:
+
+* Insufficient Authorization: you are not authorized to issue the command:
+    ```
+    [Perform MVS command] - Issuing command : D T
+    [Perform MVS command] - MVS command execution failed
+    
+    Also:   org.jenkinsci.plugins.workflow.actions.ErrorAction$ErrorId: f3f36e14-75f5-48ec-a47e-32727371972b
+    java.lang.Exception: {"reason":"Unexpected IEE136I: IEE345I DISPLAY  AUTHORITY INVALID, FAILED BY SECURITY PRODUCT","return-code":5,"reason-code":4}
+    ```
+* Successful Execution:
+    ```
+    [Perform MVS command] - Issuing command : D A,L
+    CNZ4105I 12.45.44 DISPLAY ACTIVITY 535
+    ...
+    [Perform MVS command] - The command has been successfully executed
+    ```
+
+
+
 ## Use case example
 Here you can find an example of a minimal declarative Jenkins pipeline for execution, testing and further modification for your personal needs.
 Pipeline can be used either directly inside the ```Pipeline``` code block in the Jenkins server, or in a ```Jenkinsfile``` stored in Git

src/test/resources/mock/displayActiveASCommandOutput.json

@@ -2,5 +2,5 @@
   "cmd-response-key": "C1977656",
   "cmd-response-url": "https://192.168.1.1:10443/zosmf/restconsoles/consoles/defcn/solmsgs/C1977656",
   "cmd-response-uri": "/zosmf/restconsoles/consoles/defcn/solmsgs/C1977656",
-  "cmd-response": " CNZ4105I 12.56.27 DISPLAY ACTIVITY 546\r  JOBS     M/S    TS USERS    SYSAS    INITS   ACTIVE/MAX VTAM     OAS\r 00020    00040    00004      00034    00025    00002/00040       00041\r  LLA      LLA      LLA      NSW  S  JES2     JES2     IEFPROC  NSW  S\r  VLF      VLF      VLF      NSW  S  VTAM     VTAM     VTAM     NSW  S\r  DLF      DLF      DLF      NSW  S  RACF     RACF     RACF     NSW  S\r  RRS      RRS      RRS      NSW  S  TSO      TSO      STEP1    OWT  S\r  SDSF     SDSF     SDSF     NSW  S  TCPIP    TCPIP    TCPIP    NSW  SO\r  TN3270   TN3270   TN3270   NSW  SO DBCGMSTR DBCGMSTR IEFPROC  NSW  S\r  SDSFAUX  SDSFAUX  SDSFAUX  NSW  S  HTTPD1   HTTPD1   *OMVSEX  OWT  SO\r  NFSS     NFSS     GFSAMAIN NSW  SO CSF      CSF      CSF      NSW  S\r  HZSPROC  HZSPROC  HZSSTEP  NSW  SO DBCGIRLM DBCGIRLM          NSW  S\r  DBCGDBM1 DBCGDBM1 IEFPROC  NSW  S  CICSTS55 CICSTS55 CICS     NSW  SO\r  IMS15RL1 IMS15RL1 DXRJPROC NSW  S  DBCGDIST DBCGDIST IEFPROC  NSW  SO\r  IMS15CR1 IMS15CR1 IEFPROC  NSW  S  DBCGADMT DBCGADMT STARTADM IN   SO\r  CSQ9MSTR CSQ9MSTR PROCSTEP NSW  S  CSQ9CHIN CSQ9CHIN PROCSTEP IN   SO\r  IMS15DL1 IMS15DL1 IEFPROC  NSW  S  IMS15RC1 IMS15RC1 IEFPROC  NSW  S\r  ASCH     ASCH     ASCH     NSW  S  JMON     JMON     JMON     OWT  SO\r  RSED     RSED     RSED     OWT  SO FTPD1    STEP1    FTPD     OWT  AO\r  CFZCIM   CFZCIM   *OMVSEX  OWT  SO PAGENT   PAGENT   PAGENT   OWT  SO\r  PORTMAP  PORTMAP  PMAP     OWT  SO SSHD3    STEP1    START1   OWT  AO\r  HTTPD13  STEP1    WEBSRV   OWT  AO BUZAGNT  BUZAGNT  BUZAGNT  OWT  SO\r  ZOSCSRV  ZOSCSRV  ZCONNECT IN   SO HTTPD19  STEP1    WEBSRV   IN   AO\r  BUZAGNT1 *OMVSEX  START1   IN   AO BLZBFA3  STEP1    STCBFA   OWT  AO\r  HTTPD11  STEP1    WEBSRV   IN   AO HTTPD12  STEP1    WEBSRV   OWT  AO\r  BUZAGNT3 *OMVSEX  START1   IN   AO IMS15M11 IMS15M11 REGION   NSW  J\r  IMS15F11 IMS15F11 IFP      NSW  J  IMS15F12 IMS15F12 IFP      NSW  J\r  IMS15F13 IMS15F13 IFP      NSW  J  IMS15J11 IMS15J11 JMPRGN   NSW  JO\r  RSED9    STEP1    STCRSE   OWT  AO RSED1    STEP1    STCRSE   OWT  AO\r  RSED1    STEP1    STCRSE   OWT  AO RSED2    STEP1    STCRSE   OWT  AO\r  RSED3    STEP1    STCRSE   OWT  AO RSED4    STEP1    STCRSE   OWT  AO\r  APPC     APPC     APPC     NSW  S  RMF      RMF      IEFPROC  NSW  S\r  RMFGAT   RMFGAT   IEFPROC  NSW  SO AUTOMAN  AUTOMAN  AUTOMAN  NSW  S\r CICADM   OWT      KIRJU    OWT      KBA      OWT  O   KBA      IN   O"
+  "cmd-response": " CNZ4105I 12.56.27 DISPLAY ACTIVITY 546\r  JOBS     M/S    TS USERS    SYSAS    INITS   ACTIVE/MAX VTAM     OAS\r 00020    00040    00004      00034    00025    00002/00040       00041\r  ..."
 }