Select Connection Type

Customize OPS/REXX LS settings in VS Code for the type of secure connection to OPS/MVS that you use.

1. From the File menu, select Preferences > Settings to display the Settings editor, then use the search bar to search for OPS/REXX.

2. Select the User or Workspace tab, depending on the level of settings you want to update.

3. For the Connection Mode setting, select one of the following options to determine which secure connection type OPS/REXX LS uses when it issues commands to OPS/MVS.

   • ADAPTIVE (default): OPS/REXX LS automatically uses the type of connection that is supported by each command. If the command supports both types of connection, the extension uses the Preferred Connection Order setting to determine which secure connection type to use.

   • ONLY_REST-API: OPS/REXX LS uses only the REST API connection to interact with OPS/MVS. Commands requiring SSH will fail.

   • ONLY_SSH: OPS/REXX LS uses only SSH to interact with OPS/MVS. Commands requiring a REST API connection will fail.

4. If you selected ADAPTIVE as the Connection Mode, specify the Preferred Connection Order.

   • REST-API then SSH
     The extension tries to connect to OPS/MVS using a REST API connection first, then uses SSH if a REST API connection is not available.

   • SSH then REST-API
     The extension tries to connect to OPS/MVS using an SSH connection first, then uses the REST API if SSH is not available.

Create File Associations for Zowe Explorer

To ensure that all OPS/REXX programs and rules are recognized by OPS/REXX LS as .opsrexx files, create a file association in your VS Code settings to associate data sets that contain OPS/REXX rules with the .opsrexx file extension.

To create a file association for a data set:

1. From the File menu, select Preferences > Settings to display the Settings editor.

2. Select the User or Workspace tab, depending on which settings you want to update.

3. Scroll down to or search for the Files: Associations setting and select Add Item.

4. Add **/*QUALIFIER*{,/*} to the Key field and opsrexx to the Value field where QUALIFIER is the portion of the fully qualified data set path you want to be automatically set as an OPS/REXX file type.

   Example: if you have a fully qualified data set named OPSS.CCLXSAMP.SAMPLE.RULES, you could put **/*RULES*{,/*} or **/*CCLXSAMP*{,/*} in the Key field to automatically associate all files in any data set with the matching qualifier.

5. To verify the file association: In the Zowe Explorer pane of the VS Code window, on the Data Sets tab, browse to the location of an existing rule or program and confirm that it has the .opsrexx extension and opens in the VS Code editor.

You can now use Zowe Explorer to access OPS/REXX files in data set members.

Connecting to OPS/MVS through the OPS/MVS REST API gives you access to all of the OPS/MVS features offered by OPS/REXX LS.

To set up a connection through the REST API:

1. Ensure that your OPS/MVS instance is configured with the OPS/MVS REST API (OPSREST) component.

• If you are using OPS/REXX LS with multiple OPS/MVS instances running on different systems, the OPS/MVS REST API must be installed and configured on each system in your OPSplex. One instance of the REST API is required for each system.
• When you have multiple instances of OPS/MVS running on a single system, only one instance of the REST API is required.

2. Create a team configuration file that contains the connection information for the OPS/MVS instance. Use one of the following methods:

   • Use Zowe Explorer to create a team configuration file using the following information:

     • The host name of the LPAR on which the REST API is running.
     • The port number for the REST API.
     • A username that has authority to access the REST API.
     • The password to the account that is associated with the username.

   • Manually create a team configuration file as described in the OPS/MVS documentation. This method also requires a host name, port number, username, and password (see previous bullet for details).

3. To verify the connection: in the Zowe Explorer pane of the VS Code window, on the Data Sets tab, browse to the location of an existing rule and issue the Show Rule Statuscommand as described in "Issue OPS/MVS Commands."
   If the rule status displays in the VS Code window, the connection is complete.

Integrating OPS/REXX LS with Zowe API Mediation Layer (API ML) allows you to authenticate your connection to the OPS/MVS REST API using SSO. To integrate OPS/REXX LS with Zowe API ML, follow the instructions in the section "Configure OPS/REXX LS to Access OPS/MVS Using the REST API," but with the following differences:

1. Edit the team configuration file to use the following information in the base profile:

   • The host name for the Zowe API ML instance that you want to access.
   • The port number for the Zowe API ML instance that you want to access.

2. To enable access to OPS/MVS commands from OPS/REXX LS using SSO, edit the ops profile in the Zowe team configuration file to include:

   • the base path to the OPS/MVS REST API that is registered to the API ML instance specified in your base profile.
   • a rest-api parameter with a value of true

The following example shows an ops profile that has been configured for Zowe API ML:

    "OPSREST": {
            "type": "ops",
            "properties": {
                "basePath": "opsrest/api/v1",
                "rest-api": true,
            }
        },

3. To enable login to API ML using Zowe Explorer and access to z/OS data sets using SSO, edit the zosmf profile in the Zowe team configuration file to include only the base path to the z/OSMF API registered to the API ML instance specified in your base profile.

The following example shows a zosmf profile that has been configured for Zowe API ML:

      "zosmf": {
         "type": "zosmf",
         "properties": {
              "basePath": "ibmzosmf/api/v1"
          }
      },

Note
The zosmf and ops profiles use the host and port for Zowe API ML from the base profile. Ensure that you do not provide a username, password, host, or port directly on the ops or zosmf profiles. Supplying those options causes Zowe to ignore the API ML token in your base profile and access the service directly. For information on how profiles work together in a Zowe team configuration file, see Using Base Profiles and Tokens with Existing Profiles.

4. In the Zowe Explorer tree view pane, right click on zosmf to display a context menu.

5. Select Manage Profile.
   VS Code displays a Quick Pick menu of profile actions.

6. Select Log in to Authentication Service to log in to Zowe API ML using the API ML information in your team configuration file.

   After the initial login:

   • Your team configuration profile is updated:

     • The base profile is updated to include tokenType and tokenValue parameters for the API ML as in the following example:

     "base": {
        "type": "base",
        "properties": {
            "host": "example.com",
            "port": 12345,
            "tokenType": "apimlAuthenticationToken"
        },
        "secure": [
            "tokenValue",
        ]
     },
     

     • The zosmf profile is updated to include an authOrder parameter with the value token, bearer.

   • Future commands using the OPS/MVS REST API server or z/OSMF will be made through Zowe API ML, using the tokenValue stored in the base profile until the token's expiration.

   • Once the token is expired, follow steps 4-6 to re-authenticate to API ML.

   • A token can be invalidated at any time by following steps 4 and 5, then choosing Log out from Authentication Service from the Quick Pick menu.

As an alternative to connecting to OPS/MVS using the OPS/MVS REST API, you may access a subset of OPS/REXX LS features by connecting to OPS/MVS subsystems using Secure Shell Protocol (SSH). This type of connection is recommended for individual testing of the extension, since it enables quick setup.

To establish a connection to OPS/MVS using SSH:

1. Specify the location of the OX load module.

   If the OPS/MVS OX load module (see "Address Security Requirements") is not deployed to a LNKLST or LPALIB library, update the .ops_profile for each user of OPS/REXX LS to specify the library that contains the load module as a STEPLIB export, as shown in the following example:

   #!/_bin_/_sh_ _load module_
# this shell script allows the shell to invoke
# OX which resides in the OPS/MVS loadlib.
export STEPLIB="SYS1.OPS.CCLXLOAD"

Note
Ensure that .ops_profile contains no echo statements.

2. Create an OPSVSCE SSH connection profile.

   Note
   If you do not create an SSH profile during setup, and you attempt to issue a command using an SSH connection, you will be prompted to create a profile.

   1. From Zowe Explorer or the VS Code Command Palette, select OPS/MVS: Manage OPS/REXX LS SSH Connection Profiles.
      The command displays a list of settings to allow you to create a profile.

   2. Specify values for the following settings using the VS Code UI:

      Profile Name (Required)
      Enter a name for the OPSVSCE SSH profile. The name must match an existing Zowe SSH profile, which allows your OPSVSCE SSH profile to use the host name, username and password included in the Zowe profile to make the connection to OPS/MVS. If the name you enter does not match a Zowe SSH profile, you will be prompted to change it.

      Backend Data Set (Required)
      Enter a name for a data set in which to store the REXX program OPSVSCE, which enables OPS/REXX LS to carry out OPS/MVS commands over SSH.

      Default Subsystem (Optional)
      Specify the default OPS/MVS subsystem to be used for requests made with this profile. Defaults to OPSS.

      Install z/OS Unix path (Optional)
      Specify the z/OS Unix path where the SSH manager creates the directory .opsrexx-vsce.

      If a path is not specified, your home directory is used. This directory is used to run the commands that are needed to prepare OPSVSCE and deploy it to the specified Backend Data Set. The directory is only used to transfer files to the backend data set, after which it is automatically emptied.

   3. Select Add this OPS/REXX LS SSH Profile to your settings.
      The OPSVSCE SSH profile is saved to your OPS/REXX LS settings.

3. Use the VS Code Command Palette to issue the command OPS/MVS: Deploy Backend.
   A menu appears.

4. From the menu, select the system where you will deploy the OPSVSCE program. (Refer to the description of Backend Data Set in the previous step.)
   When you select a system, OPS/REXX LS checks for an appropriate OPSVSCE SSH profile and deploys OPSVSCE to the data set you specified.

The SSH connection to OPS/MVS is established.

Note
We recommend that you use the OPS/MVS: Manage OPS/REXX LS SSH Connection Profiles command and the VS Code UI to create or edit OPSVSCE SSH profiles. However, you may create a profile or edit it directly in settings.json. To do this, in your OPS/REXX LS settings under SSH Connection Profiles, click the link Edit in settings.json.

The SSH profile settings as they appear in the JSON file are listed here:

name (Required)
The name of the profile, which must match a Zowe SSH profile name.

deployDataset (Required)
The name of the data set in which to store OPSVSCE.

defaultSubsystem (Optional)
The default OPS/MVS subsystem to be used for requests made with this profile. Defaults to OPSS.

installUssPath (Optional)
The z/OS Unix path where the SSH manager will create a directory called .opsrexx-vsce.

Hover insights are available for OPS/REXX built-in functions, host environments, and AOF event variable names. Place and hold your cursor over the name of one of these elements to view more information about it, as shown in the following video:

Autocompletion works for the following OPS/REXX language elements:

• AOF variables
• Built-in functions
• Host environment names

To trigger autocompletion of AOF variables, enter . after an AOF rule type stem, for example: msg. AOF variable completions are supported for all rule types.

Autocompletion is also triggered when you type the name of an OPS/REXX built-in function or host environment, as shown in the following video: