FileSystemProvider

---

Table of Contents

• File paths vs. URIs
  • Coupling with tree nodes
• Operations for Extenders
  • Get contents of a USS file, Data Set, or spool file
  • Get entries of a USS folder, PDS, or job
  • Get resource statistics

---

In v3 of Zowe Explorer, we have made an architectural shift from using temporary, on-disk files to using the FileSystemProvider interface provided by VS Code. Starting with v3, the three "core" tree views in Zowe Explorer will use implementations of the FileSystemProvider to encapsulate remote operations (reading/writing, renaming, deleting, etc.):

Tree view	FileSystemProvider implementation
Data Sets	DatasetFSProvider
Jobs	JobsFSProvider
Unix System Services (USS)	UssFSProvider

We will no longer write files to the temporary, on-disk directory used in previous versions. All data is now managed in memory.

We have also exposed a BaseProvider class in Zowe Explorer API to help extenders create their own FileSystemProvider implementations if needed.
However, the implementations above are not directly accessible through Zowe Explorer API. Extenders should use the vscode.workspace.fs façade to access information instead.

File paths vs. URIs

The FileSystemProvider interface largely operates on the concept of resource URIs. Because our implementations leverage Zowe-specific resource URIs to build a path structure in memory, each segment is important when building a correct URI for a resource.

All core resource URIs for Zowe Explorer use this general structure:

zowe-*:/<Profile Name (LPAR)>/<Resource Path>

zowe-* refers to a scheme with the zowe- prefix. The core schemes are exposed in Zowe Explorer API as the ZoweScheme enum and are defined as the following:

• Data Sets: zowe-ds
• Jobs: zowe-jobs
• USS: zowe-uss

Data Set URIs

For a sequential data set named FRUIT.CHKLIST on the food.zosmf LPAR, the URI would read as follows:

zowe-ds:/food.zosmf/FRUIT.CHKLIST

Partitioned data sets are interpreted as directories in the FileSystemProvider, and members are entries inside the directory.
For example, to represent the member APPLE in PDS FRUIT.BASKET on the food.zosmf LPAR, the URI would be:

zowe-ds:/food.zosmf/FRUIT.BASKET/APPLE

USS URIs

USS URIs use the format zowe-uss:/<Profile Name (LPAR)>/<USS Path> to represent files or folders.
A file at path /u/users/fruit/apple.txt on the food.zosmf LPAR would look like this:

zowe-uss:/food.zosmf/u/users/fruit/apple.txt

Its parent folder /u/users/fruit/ would look like this:

zowe-uss:/food.zosmf/u/users/fruit/

Job URIs

Job URIs use the format zowe-jobs:/<Profile Name (LPAR)>/<Job ID>/. Spool URIs use the format zowe-jobs:/<Profile Name (LPAR)>/<Job ID>/<Unique Spool ID>.

Extenders can leverage the buildUniqueSpoolName function in Zowe Explorer API to help build spool URIs. The Job ID segment matches the jobid parameter on the IJobFile object.

Fetching a resource on-demand

Zowe Explorer will create entries in the file system as needed to represent mainframe resources. This means that URIs by default will not be fetched unless explicitly specified. In order to fetch a Data Set or USS file on-demand, you can call the vscode.workspace.fs.stat function with a Zowe URI containing the fetch=true query parameter. Zowe Explorer will attempt to lookup the resource URI, and will return a valid entry if it exists on the remote system:

// When this URI is opened, Zowe Explorer will attempt to fetch the MEM member in the EXAMPLE.PART PDS if it does not already exist.
let pdsMemberUri = vscode.Uri.from("zowe-ds:/lpar.zosmf/EXAMPLE.PART/MEM?fetch=true");
try {
    const fsEntry = await vscode.workspace.fs.stat(pdsMemberUri);
    // optional: remove the fetch query after a successful `stat` call as its no longer needed.
    pdsMemberUri = pdsMemberUri.with({ query: "" });
} catch (err) {
    // an error occurred while trying to fetch the resource; return.
    console.log(err);
    return;
}

Alternatively, you can call vscode.workspace.fs.readFile (no fetch query parameter needed) with the URI to try looking up the resource if it does not exist:

// This will attempt to fetch EXAMPLE.PART(MEM) if it doesn't already exist locally.
const contents = await vscode.workspace.fs.readFile(pdsMemberUri);

Coupling with tree nodes

When instantiating a VS Code TreeItem, each item can be paired with a resourceUri to establish a relationship between the URI and the tree node. We recommend that extenders pair their URIs alongside their tree nodes to establish a connection between the node and the resource, and to allow URI changes to propagate to the item in the tree view (such as when a URI is deleted from a provider).

With Zowe Explorer core resources, the URIs are generated and added to the FileSystemProvider as the user interacts with the tree view. However, extenders can create empty files and folders in the provider using writeFile and createDirectory as needed.

Operations for Extenders

Please note: These operations assume that the given resource URI exists in the FileSystemProvider. If the resource does not exist, an exception may be thrown - these should be caught and handled by your extension as needed.

Get contents of a USS file, Data Set, or spool file

To read the contents of a spool file, data set, or USS file, use the vscode.workspace.fs.readFile function.

• Returns a Uint8Array with the contents of the resource

Get entries of a USS folder, PDS, or job

To list the contents of a USS directory, PDS, or job specified by a given URI, use the vscode.workspace.fs.readDirectory function.

• Returns an array of tuples, where each tuple represents a child entry in the directory
• For jobs, use this to return a list of spool files under a given job URI
• For USS files, use this to a list of files and folders at the given path
• For Data Sets, use this to get the members for a given PDS

Get resource statistics

To retrieve statistics for any resource URI, use the vscode.workspace.fs.stat function.

• Returns a FileStat object containing metadata about the URI, such as its type, size, and timestamps
• For USS files and Data Sets, this also contains e-tag and encoding information
• For jobs, this contains the IJob or IJobFile object depending on the resource (job or spool)