@broadcom/file-master-plus-for-zowe-cli/README.md

File Master Plus Plug-in for Zowe CLI

# File Master Plus Plug-in for Zowe CLI

<img src="https://www.openmainframeproject.org/wp-content/uploads/sites/11/2022/05/zowe-conformant-zowev2-cli-color.png" width=25% alt="Zowe Conformance Badge"/>

The File Master Plus Plug-in for Zowe CLI helps you quickly create, edit, and manipulate files in virtual storage access method (VSAM), sequential, and partitioned data sets.

- [How the Plug-in Works](#how-the-plug-in-works)
- [Software Requirements](#software-requirements)
- [Installing](#installing)
- [Create a File Master Plus Profile](#create-a-file-master-plus-profile)
- [Uninstalling](#uninstalling)
- [Example Use Cases](#example-use-cases)

## How the Plug-in Works

- The plug-in defines an FMP profile to manage the connection information, which is required to access the FMP API.
- It implements a local API to interface with the relevant API on the server.
- The plug-in creates a wrapping CLI around the local API to provide the command-line function.

## Software Requirements

Before you install and use the plug-in, complete the following tasks:

<!-- TODO When @latest branch of Zowe docs-site exists, we should give users the option to go and read about/install the @latest or the @lts-incremental versions of this plug-in. We can also explain which branches in the repo correspond to which CLI version. -->

1. Install Zowe CLI on your computer. For more information, see [Installing Zowe CLI](https://docs.zowe.org/stable/user-guide/cli-installcli).
2. Ensure that File Master Plus version 12 or later is installed and running in your mainframe environment.
3. Complete one of the following two tasks:
    - Integrate the FMP REST API with the API Mediation Layer (API ML).
    - Connect the plug-in directly to the File Master Plus REST API.  

For more information, see the [File Master Plus documentation](https://techdocs.broadcom.com/fmp).

## Installing

To install the plug-in, use the online registry. For more information, see [Installing Zowe CLI plug-ins](https://docs.zowe.org/stable/user-guide/cli-installplugins).

After the installation process completes, it validates that the plug-in was installed correctly and that the names of its commands, options, and arguments do not conflict with those of your other Zowe CLI plug-ins.

If the validation process is successful, the following message displays:

```
Validation results for plugin 'file-master-plus-for-zowe-cli':
Successfully validated.
```

If an unsuccessful message displays, troubleshoot the installation by addressing the issues that the message describes. You can also review the information in the log file in the Zowe CLI home directory.

## Create a File Master Plus Profile
	
Create a File Master Plus profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. Use one of the following methods to create a profile:

- Create a profile using a configuration file
- Create a profile using a command

We recommend that you create profiles using the configuration file. We do not recommend using profile commands because we are removing the commands from Brightside in a future major release. 

### Create a File Master Plus Profile using a Configuration File

When you issue various `zowe config` commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. If the File Master Plus plug-in is installed when you issue one of these commands, the command automatically adds a profile for a File Master Plus profile to your `zowe.config.json` configuration file. 

Alternatively, you can create a File Master Plus profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file.

1. Navigate to the following directory: `C:\Users\<username>\.zowe`.
2. Open the `zowe.config.json` configuration file using a text editor or IDE.  
  **Note**: If the file does not exist, issue the following command to create the configuration file: `zowe config init --gc`
3. Add the following JSON to the `"profiles"` section of the configuration file.  
  ```
  "fmp_profile": {  
      "type": "fmp",  
      "properties": {  
          "host": "example.com",  
          "port": 12345,  
          "protocol": "http",  
          "user": "johndoe",  
          "password": "qwerty",  
          "rejectUnauthorized": false  
          },  
      },
   ```
4. Populate the following fields in the above JSON:
    - **host** (string)  
    The host URL of your Testing Tools server instance
    - **port** (integer)  
    The port number of your Testing Tools server instance  
    **Default**: 51914
    - **protocol** (string)  
    Specify "https" or "http".  
    **Default**: https
    - **user** (string)  
    Your mainframe username
    - **password** (string)  
    Your mainframe password
    - **rejectUnauthorized** (boolean)  
    Specify "false" to accept self-signed certificates.  
    **Default**: true
5. Save the file.

You can now use your profile when you issue commands in the File Master Plus command group.

### Create a File Master Plus Profile Using a Command

To create a profile using the `zowe profiles create` command, open a terminal window and issue the following command to view the command syntax:

`zowe profiles create fmp -h`

Submit the `zowe profiles create fmp` command with all parameters specified.

**Example**: `zowe profiles create fmp fmp123 --host fmphost --port 19853 --user mfuser --pass m4pass --protocol http`.

The result of the command displays as a success or failure message.

## Uninstalling

To uninstall the plug-in, issue the following command:

```
zowe plugins uninstall @broadcom/file-master-plus-for-zowe-cli
```
    
## Example Use Cases:

As an application developer, you can use the plug-in to perform the following tasks:

* CREATE  
Allocate a VSAM data set along with its components, copying the parameters of an existing VSAM file.
* POPULATE  
Populate a VSAM file with newly constructed test data stored in a JSON file.
* COPY  
Copy a whole VSAM file using only one CLI command. Selects desired parts of the source of a file and copies only those parts over to a new VSAM file.
* RENAME  
Rename a VSAM file with ARCHIVE as the second qualifier.
* DELETE  
Delete a VSAM file using Zowe CLI.