IBM z/TPF Development Extension

This extension provides several commands that facilitate performing development tasks for z/TPF system and application code.

The supported build environment for z/TPF is Linux on IBM Z.

Overview / Usage

After a developer has committed and pushed code changes to a branch in a remote Git repository, the z/TPF: Run Pipeline command will perform the following tasks by default:

• Pull the committed changes from the remote repository into the matching clones on the Linux on IBM Z system.
• Generate a project build script named build.sh depending on project configuration.
• Clean up the remote working directory contents
• Copy the project configuration files from the Visual Studio Code workspace to the Linux on IBM Z system using SFTP
• Run the configured build commands on the Linux on IBM Z system.
• Run the configured loadtpf commands on the Linux on IBM Z system.
• Submit requests to the OLDR REST services on the z/TPF host to load and activate the configured loadset.
• Submit requests to the Automated Test Framework REST services on the z/TPF host to run automated tests.

These tasks can be performed individually by selecting the corresponding commands in the Visual Studio Code command palette.

The pipeline tasks can be changed using the Commands: Pipeline setting. See the Adding commands to the pipeline section for more details.

See the sub-headings below for additional details on a selection of the default tasks.

Requirements for the default pipeline

• The z/TPF application / system code is stored in one or more remote Git repositories.
• SSH authentication between your workstation and the Linux on IBM Z system uses a public and private key pair.
• SSH authentication between the Linux on IBM Z system and the Git repositories uses a public and private key pair.
• The Git repositories in your Visual Studio Code workspace are also cloned to your working area on the Linux on IBM Z system with the same names.
• The name of the working directory in your Visual Studio Code workspace and your user workspace on the Linux on IBM Z system is the same.
• Project configuration files are named maketpf.cfg, maketpf.cntl, maketpf.loadfile and maketpf.loaddeck.
• The following extension settings must be provided by the user for the pipeline to run:
  • IBM z/TPF Development > Linux > Base (ztpf-development.linux.base)
  • IBM z/TPF Development > Linux > Host (ztpf-development.linux.host)
  • IBM z/TPF Development > Linux > Private Key (ztpf-development.linux.privateKey)
  • IBM z/TPF Development > Linux > Userid (ztpf-development.linux.userid)

Generating the build script

• The build script is generated using the PROJECT_BUILD_COMPILE and PROJECT_BUILD_LINK variables in the project configuration file (maketpf.cfg).
• If the variables above are not defined, this task deletes build.sh if it exists or otherwise does nothing.

Cleaning the remote working directory

• The default behavior removes all content from the configured folder.
• The Commands: Clean Patterns extension setting changes the behavior of this task.
• This task is included as part of the z/TPF: Build Changes command.
• The z/TPF: Clean Up Project Output command runs the clean target using bldtpf, maketpf or the generated build script rather than deleting contents from the remote working directory. By default, this task is not included in the pipeline to reuse any cached build output from previous pipeline runs.

Build command discovery

• If a control file named maketpf.cntl exists in the working directory, then bldtpf is run with the force option using the control file.
• If a project build script named build.sh is present in the working directory, then it is run.
• Otherwise, maketpf is run using the value provided by the user in the provided prompt as parameters.

Loadtpf command discovery

• If a file named maketpf.loaddeck exists in the working directory, then loadtpf is run using that file.
• If a file named maketpf.cntl exists in the working directory, then loadtpf is run using that file.
  • If a file named maketpf.loadfile exists in the working directory, it will be appended to the above loadtpf command
• If a file named build.sh exists in the working directory, then loadtpf is run using a control file that is generated via maketpf_cntl using the PROJECT_BUILD_LINK values in the project configuration file (maketpf.cfg).
  • If a file named maketpf.loadfile exists in the working directory, it will be appended to the above loadtpf command
• Otherwise, loadtpf is run using the value provided by the user in the provided prompt as parameters.

OLDR REST Service

• LOADTPF_HTTP_PORT is a new required value in the project configuration file (maketpf.cfg) to submit these requests. The value should match the port of the HTTP server on the z/TPF system that has the OLDR REST services deployed.

Automated Test Framework

• Automated tests are run on the z/TPF host based on the PROJECT_TEST_NAMESPACE and PROJECT_TEST_PROGRAM variables in the project configuration file (maketpf.cfg).
• At least one test namespace or program should be specified.
• The LOADTPF_HTTP_PORT value in the project configuration file (maketpf.cfg) is also required for this task

Retrieving Build Output

The "z/TPF: Retrieve Build Output" command retrieves build output files from the Linux on IBM Z system to your local workspace. This command:

• Searches for files in both TPF_ROOT and APPL_ROOT directories based on project configuration file (maketpf.cfg) search patterns.
• Transfers matching files to the local directory specified in extension settings.
• Automatically creates necessary local directories to preserve the remote directory structure.
• Can be run as a standalone command or included as part of the pipeline by updating the Commands: Pipeline setting.

Viewing and running z/TPF Automated Tests

• Use the Test: Refresh Tests command or the refresh icon in the Test Explorer to load z/TPF automated tests in the Testing view.
  • Automated tests are retrieved from the z/TPF host and displayed in the Testing view.
  • PROJECT_TEST_NAMESPACE and PROJECT_TEST_PROGRAM variables in the project configuration file (maketpf.cfg) are used to determine what tests should be retrieved.
• Use Test: Run All Tests command to run all tests in the Testing view or click the Play icon to run a specific namespace or test.

Configuring secure connections to a z/TPF host

• The TLS: Secure Connections extension setting is enabled by default to use secure connections to the z/TPF system. Optionally, you can set the absolute local path to the server certificate file (e.g., .pem, .crt). This certificate will be concatenated to the list of the trusted certificates retrieved by the runtime.

Adding commands to the pipeline

Behavior of the pipeline

• The value of the Commands: Pipeline setting is used to determine the tasks that should be run.
• For each value in the task list the vscode.commands.executeCommand() method is called.
• If an error is caught while waiting for the task to complete, the task is considered failed, the pipeline is stopped, the end user is notified, and the error message is printed to the common vscode.LogOutputChannel instance.
• If the command returns a value, the value is ignored.

Creating your own commands for the pipeline

For more information on how to create a command, see the Visual Studio Code Extension API guide.

Each command is passed two parameters when called by the pipeline:

• The first parameter is a common vscode.LogOutputChannel instance that is used to route information to the end user.
• The second parameter is a connected SSH2Wrapper object to interact with the Linux on IBM Z system, if required. See Accessing the IBM z/TPF Development extension's API section below for details.

Commands may choose to ignore these parameters if they are not required to perform a task (e.g. a utility that runs in the local workspace). If a command requires additional or different parameters, then it is not a candidate for inclusion in the pipeline.

Additional information that the command requires must be retrieved by the command itself.

Pipeline commands that are also registered with the Command Palette

Some commands that are included in the pipeline may also provide value as stand-alone commands. When called from the command palette, the command is not passed any parameters from the pipeline.

Extra coding will be required for commands to be run stand-alone. The parameters passed by the pipeline must be initialized and managed by the command code. The ztpf-development extension provides an API to access the common LogOutputChannel object and initialize an SSH2Wrapper object. See Accessing the ztpf-development Extension's API section below for details.

Stand-alone commands that make use of the SSH2Wrapper object can test the existence of the SSH2Wrapper parameter to determine whether the command is being run from the pipeline or stand-alone. If the SSH2Wrapper object is undefined, then the command is being run stand-alone. The command logic will need to initialize, configure, and connect the SSH2Wrapper object. Before the command completes or returns with an error, the SSH2Wrapper object must be disconnected. Using a try-catch-finally pattern is recommended to ensure the SSH2Wrapper object is disconnected even if an error occurs. Credentials for configuring the SSH2Wrapper object can be retrieved from the extension settings.

Stand-alone commands may also require additional logic to notify the user of the command's progress (e.g. send a notification when the command completes).

Accessing the IBM z/TPF Development Extension's API

The typing file (api.d.ts) for the parameter objects that are passed to vscode.commands.executeCommand() as part of the pipeline are bundled within this extension in the extension/src/api folder. The VSIX file can be opened like any other archive file to retrieve the files and bundle them with your extension. The typing file describes the APIs available to use as part of a command.

To access the API, use the vscode.extensions namespace to access the getExtension method to retrieve the extension and then store the exports property.

const extension = vscode.extensions.getExtension('ztpf-development');
const api = extension.exports;

License Information

See the LICENSE file included in this extension for license information. See the NOTICES file included in this extension for open-source license information See the sbom.json file included in this extension for software bill of materials information.