@zowe/zos-files-for-zowe-sdk
Version:
Zowe SDK to interact with files and data sets on z/OS
525 lines • 27.8 kB
JavaScript
;
/*
* This program and the accompanying materials are made available under the terms of the
* Eclipse Public License v2.0 which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-v20.html
*
* SPDX-License-Identifier: EPL-2.0
*
* Copyright Contributors to the Zowe Project.
*
*/
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.List = void 0;
const imperative_1 = require("@zowe/imperative");
const path_1 = require("path");
const util = require("util");
const core_for_zowe_sdk_1 = require("@zowe/core-for-zowe-sdk");
const ZosFiles_constants_1 = require("../../constants/ZosFiles.constants");
const ZosFiles_messages_1 = require("../../constants/ZosFiles.messages");
/**
* This class holds helper functions that are used to list data sets and its members through the z/OS MF APIs
*/
class List {
/**
* Retrieve all members from a PDS
*
* @param {AbstractSession} session - z/OS MF connection info
* @param {string} dataSetName - contains the data set name
* @param {IListOptions} [options={}] - contains the options to be sent
* @returns {Promise<IZosFilesResponse>} A response indicating the outcome of the API
*
* @throws {ImperativeError} data set name must be set
* @throws {Error} When the {@link ZosmfRestClient} throws an error
*
* @see https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.izua700/IZUHPINFO_API_GetListDataSetMembers.htm
*/
static allMembers(session_1, dataSetName_1) {
return __awaiter(this, arguments, void 0, function* (session, dataSetName, options = {}) {
// required
imperative_1.ImperativeExpect.toNotBeNullOrUndefined(dataSetName, ZosFiles_messages_1.ZosFilesMessages.missingDatasetName.message);
imperative_1.ImperativeExpect.toNotBeEqual(dataSetName, "", ZosFiles_messages_1.ZosFilesMessages.missingDatasetName.message);
try {
// Format the endpoint to send the request to
const endpoint = path_1.posix.join(ZosFiles_constants_1.ZosFilesConstants.RESOURCE, ZosFiles_constants_1.ZosFilesConstants.RES_DS_FILES, encodeURIComponent(dataSetName), ZosFiles_constants_1.ZosFilesConstants.RES_DS_MEMBERS);
const params = new URLSearchParams();
if (options.pattern) {
params.set("pattern", options.pattern);
}
if (options.start) {
params.set("start", options.start);
}
const reqHeaders = [core_for_zowe_sdk_1.ZosmfHeaders.ACCEPT_ENCODING];
if (options.attributes) {
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_ATTRIBUTES_BASE);
}
if (options.maxLength) {
reqHeaders.push({ "X-IBM-Max-Items": `${options.maxLength}` });
}
else {
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MAX_ITEMS);
}
if (options.responseTimeout != null) {
reqHeaders.push({ [core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_RESPONSE_TIMEOUT]: options.responseTimeout.toString() });
}
this.log.debug(`Endpoint: ${endpoint}`);
const data = yield core_for_zowe_sdk_1.ZosmfRestClient.getExpectString(session, endpoint.concat(params.size > 0 ? `?${params.toString()}` : ""), reqHeaders);
let response;
try {
response = imperative_1.JSONUtils.parse(data);
}
catch (err) {
const match = /in JSON at position (\d+)/.exec(err.message);
if (match != null) {
// Remove invalid member names from end of list and try to parse again
const lineNum = data.slice(0, parseInt(match[1])).split("\n").length - 1;
const lines = data.trim().split("\n");
lines[lineNum - 1] = lines[lineNum - 1].replace(/,$/, "");
lines.splice(lineNum, lines.length - lineNum - 1);
response = imperative_1.JSONUtils.parse(lines.join("\n"));
const invalidMemberCount = response.returnedRows - response.items.length;
this.log.warn(`${invalidMemberCount} members failed to load due to invalid name errors for ${dataSetName}`);
}
else {
throw err;
}
}
return {
success: true,
commandResponse: null,
apiResponse: response
};
}
catch (error) {
this.log.error(error);
throw error;
}
});
}
/**
* List data set members that match a DSLEVEL pattern
* @param {AbstractSession} session z/OSMF connection info
* @param {string[]} patterns Data set patterns to include
* @param {IDsmListOptions} options Contains options for the z/OSMF request
* @returns {Promise<IZosFilesResponse>} List of z/OSMF list responses for each data set
*
* @example
*/
static membersMatchingPattern(session_1, dataSetName_1, patterns_1) {
return __awaiter(this, arguments, void 0, function* (session, dataSetName, patterns, options = {}) {
imperative_1.ImperativeExpect.toNotBeNullOrUndefined(dataSetName, ZosFiles_messages_1.ZosFilesMessages.missingDatasetName.message);
imperative_1.ImperativeExpect.toNotBeEqual(dataSetName, "", ZosFiles_messages_1.ZosFilesMessages.missingDatasetName.message);
imperative_1.ImperativeExpect.toNotBeNullOrUndefined(patterns, ZosFiles_messages_1.ZosFilesMessages.missingPatterns.message);
patterns = patterns.filter(Boolean);
imperative_1.ImperativeExpect.toNotBeEqual(patterns.length, 0, ZosFiles_messages_1.ZosFilesMessages.missingPatterns.message);
const zosmfResponses = [];
for (const pattern of patterns) {
const response = yield List.allMembers(session, dataSetName, { pattern, maxLength: options.maxLength, start: options.start });
zosmfResponses.push(...response.apiResponse.items);
}
// Check if members matching pattern found
if (zosmfResponses.length === 0) {
return {
success: false,
commandResponse: ZosFiles_messages_1.ZosFilesMessages.noMembersMatchingPattern.message,
apiResponse: []
};
}
// Exclude names of members
for (const pattern of options.excludePatterns || []) {
const response = yield List.allMembers(session, dataSetName, { pattern });
response.apiResponse.items.forEach((membersObj) => {
const responseIndex = zosmfResponses.findIndex(response => response.member === membersObj.member);
if (responseIndex !== -1) {
zosmfResponses.splice(responseIndex, 1);
}
});
}
// Check if exclude pattern has left any members in the list
if (zosmfResponses.length === 0) {
return {
success: false,
commandResponse: ZosFiles_messages_1.ZosFilesMessages.noMembersInList.message,
apiResponse: []
};
}
return {
success: true,
commandResponse: util.format(ZosFiles_messages_1.ZosFilesMessages.membersMatchedPattern.message, zosmfResponses.length),
apiResponse: zosmfResponses
};
});
}
/**
* Retrieve all members from a data set name
*
* @param {AbstractSession} session - z/OS MF connection info
* @param {string} dataSetName - contains the data set name
* @param {IListOptions} [options={}] - contains the options to be sent
*
* @returns {Promise<IZosFilesResponse>} A response indicating the outcome of the API
*
* @throws {ImperativeError} data set name must be set
* @throws {Error} When the {@link ZosmfRestClient} throws an error
*/
static dataSet(session_1, dataSetName_1) {
return __awaiter(this, arguments, void 0, function* (session, dataSetName, options = {}) {
imperative_1.ImperativeExpect.toNotBeNullOrUndefined(dataSetName, ZosFiles_messages_1.ZosFilesMessages.missingDatasetName.message);
imperative_1.ImperativeExpect.toNotBeEqual(dataSetName, "", ZosFiles_messages_1.ZosFilesMessages.missingDatasetName.message);
try {
let endpoint = path_1.posix.join(ZosFiles_constants_1.ZosFilesConstants.RESOURCE, `${ZosFiles_constants_1.ZosFilesConstants.RES_DS_FILES}?${ZosFiles_constants_1.ZosFilesConstants.RES_DS_LEVEL}=${encodeURIComponent(dataSetName)}`);
if (options.volume) {
endpoint = `${endpoint}&volser=${encodeURIComponent(options.volume)}`;
}
if (options.start) {
endpoint = `${endpoint}&start=${encodeURIComponent(options.start)}`;
}
const reqHeaders = [core_for_zowe_sdk_1.ZosmfHeaders.ACCEPT_ENCODING];
if (options.attributes) {
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_ATTRIBUTES_BASE);
}
if (options.maxLength) {
reqHeaders.push({ "X-IBM-Max-Items": `${options.maxLength}` });
}
else {
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MAX_ITEMS);
}
if (options.responseTimeout != null) {
reqHeaders.push({ [core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_RESPONSE_TIMEOUT]: options.responseTimeout.toString() });
}
// Migrated recall options
if (options.recall) {
switch (options.recall.toLowerCase()) {
case "wait":
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MIGRATED_RECALL_WAIT);
break;
case "nowait":
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MIGRATED_RECALL_NO_WAIT);
break;
case "error":
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MIGRATED_RECALL_ERROR);
break;
}
}
this.log.debug(`Endpoint: ${endpoint}`);
const response = yield core_for_zowe_sdk_1.ZosmfRestClient.getExpectJSON(session, endpoint, reqHeaders);
return {
success: true,
commandResponse: null,
apiResponse: response
};
}
catch (error) {
this.log.error(error);
throw error;
}
});
}
/**
* Retrieve a list of all files from a path name
*
* @param {AbstractSession} session - z/OS MF connection info
* @param {string} path - contains the uss path name
* @param {IUSSListOptions} [options={}] - contains the options to be sent
*
* @returns {Promise<IZosFilesResponse>} A response indicating the outcome of the API
*
* @throws {ImperativeError} data set name must be set
* @throws {Error} When the {@link ZosmfRestClient} throws an error
*/
static fileList(session_1, path_2) {
return __awaiter(this, arguments, void 0, function* (session, path, options = {}) {
imperative_1.ImperativeExpect.toNotBeNullOrUndefined(path, ZosFiles_messages_1.ZosFilesMessages.missingUSSFileName.message);
imperative_1.ImperativeExpect.toNotBeEqual(path.trim(), "", ZosFiles_messages_1.ZosFilesMessages.missingUSSFileName.message);
// Error out if someone tries to use a second table parameter without specifying a first table parameter
if (options.depth || options.filesys != null || options.symlinks != null) {
if (!(options.group || options.user || options.name || options.size || options.mtime || options.perm || options.type)) {
throw new imperative_1.ImperativeError({ msg: ZosFiles_messages_1.ZosFilesMessages.missingRequiredTableParameters.message });
}
}
// Remove a trailing slash from the path, if one exists
// Do not remove if requesting the root directory
if (path.trim().length > 1 && path.endsWith("/")) {
path = path.slice(0, -1);
}
try {
let endpoint = path_1.posix.join(ZosFiles_constants_1.ZosFilesConstants.RESOURCE, `${ZosFiles_constants_1.ZosFilesConstants.RES_USS_FILES}?${ZosFiles_constants_1.ZosFilesConstants.RES_PATH}=${encodeURIComponent(path)}`);
const reqHeaders = [core_for_zowe_sdk_1.ZosmfHeaders.ACCEPT_ENCODING];
if (options.maxLength) {
reqHeaders.push({ "X-IBM-Max-Items": `${options.maxLength}` });
}
else {
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MAX_ITEMS);
}
if (options.responseTimeout != null) {
reqHeaders.push({ [core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_RESPONSE_TIMEOUT]: options.responseTimeout.toString() });
}
// Start modifying the endpoint with the query parameters that were passed in
if (options.group) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_GROUP}=${encodeURIComponent(options.group)}`;
}
if (options.user) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_USER}=${encodeURIComponent(options.user)}`;
}
if (options.name) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_NAME}=${encodeURIComponent(options.name)}`;
}
if (options.size) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_SIZE}=${encodeURIComponent(options.size)}`;
}
if (options.mtime) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_MTIME}=${encodeURIComponent(options.mtime)}`;
}
if (options.perm) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_PERM}=${encodeURIComponent(options.perm)}`;
}
if (options.type) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_TYPE}=${encodeURIComponent(options.type)}`;
}
if (options.depth) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_DEPTH}=${encodeURIComponent(options.depth)}`;
}
if (options.filesys != null) {
if (options.filesys === true) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_FILESYS}=all`;
}
else {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_FILESYS}=same`;
}
}
if (options.symlinks != null) {
if (options.symlinks === true) {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_SYMLINKS}=report`;
}
else {
endpoint += `&${ZosFiles_constants_1.ZosFilesConstants.RES_SYMLINKS}=follow`;
}
}
this.log.debug(`Endpoint: ${endpoint}`);
const response = yield core_for_zowe_sdk_1.ZosmfRestClient.getExpectJSON(session, endpoint, reqHeaders);
return {
success: true,
commandResponse: null,
apiResponse: response
};
}
catch (error) {
this.log.error(error);
throw error;
}
});
}
/**
* Retrieve zfs files
*
* @param {AbstractSession} session - z/OS MF connection info
* @param {IZfsOptions} [options={}] - contains the options to be sent
*
* @returns {Promise<IZosFilesResponse>} A response indicating the outcome of the API
*
* @throws {ImperativeError} data set name must be set
* @throws {Error} When the {@link ZosmfRestClient} throws an error
*/
static fs(session_1) {
return __awaiter(this, arguments, void 0, function* (session, options = {}) {
try {
let endpoint = path_1.posix.join(ZosFiles_constants_1.ZosFilesConstants.RESOURCE, `${ZosFiles_constants_1.ZosFilesConstants.RES_MFS}`);
if (options.fsname) {
endpoint = path_1.posix.join(endpoint, `?${ZosFiles_constants_1.ZosFilesConstants.RES_FSNAME}=${encodeURIComponent(options.fsname)}`);
}
const reqHeaders = [core_for_zowe_sdk_1.ZosmfHeaders.ACCEPT_ENCODING];
// if (options.path) {
// reqHeaders.push(ZosmfHeaders.X_IBM_ATTRIBUTES_BASE);
// }
if (options.maxLength) {
reqHeaders.push({ "X-IBM-Max-Items": `${options.maxLength}` });
}
else {
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MAX_ITEMS);
}
if (options.responseTimeout != null) {
reqHeaders.push({ [core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_RESPONSE_TIMEOUT]: options.responseTimeout.toString() });
}
this.log.debug(`Endpoint: ${endpoint}`);
const response = yield core_for_zowe_sdk_1.ZosmfRestClient.getExpectJSON(session, endpoint, reqHeaders);
return {
success: true,
commandResponse: null,
apiResponse: response
};
}
catch (error) {
this.log.error(error);
throw error;
}
});
}
/**
* Retrieve zfs files if indicated path
*
* @param {AbstractSession} session - z/OS MF connection info
* @param {IZfsOptions} [options={}] - contains the options to be sent
*
* @returns {Promise<IZosFilesResponse>} A response indicating the outcome of the API
*
* @throws {ImperativeError} data set name must be set
* @throws {Error} When the {@link ZosmfRestClient} throws an error
*/
static fsWithPath(session_1) {
return __awaiter(this, arguments, void 0, function* (session, options = {}) {
try {
let endpoint = path_1.posix.join(ZosFiles_constants_1.ZosFilesConstants.RESOURCE, `${ZosFiles_constants_1.ZosFilesConstants.RES_MFS}`);
if (options.path) {
endpoint = path_1.posix.join(endpoint, `?${ZosFiles_constants_1.ZosFilesConstants.RES_PATH}=${encodeURIComponent(options.path)}`);
}
const reqHeaders = [core_for_zowe_sdk_1.ZosmfHeaders.ACCEPT_ENCODING];
if (options.maxLength) {
reqHeaders.push({ "X-IBM-Max-Items": `${options.maxLength}` });
}
else {
reqHeaders.push(core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_MAX_ITEMS);
}
if (options.responseTimeout != null) {
reqHeaders.push({ [core_for_zowe_sdk_1.ZosmfHeaders.X_IBM_RESPONSE_TIMEOUT]: options.responseTimeout.toString() });
}
this.log.debug(`Endpoint: ${endpoint}`);
const response = yield core_for_zowe_sdk_1.ZosmfRestClient.getExpectJSON(session, endpoint, reqHeaders);
return {
success: true,
commandResponse: null,
apiResponse: response
};
}
catch (error) {
this.log.error(error);
throw error;
}
});
}
/**
* List data sets that match a DSLEVEL pattern
* @param {AbstractSession} session z/OSMF connection info
* @param {string[]} patterns Data set patterns to include
* @param {IDsmListOptions} options Contains options for the z/OSMF request
* @returns {Promise<IZosFilesResponse>} List of z/OSMF list responses for each data set
*
* @example
* ```typescript
*
* // List all "PS" and "PO" datasets that match the pattern "USER.**.DATASET"
* await List.dataSetsMatchingPattern(session, "USER.**.DATASET");
* ```
*/
static dataSetsMatchingPattern(session_1, patterns_1) {
return __awaiter(this, arguments, void 0, function* (session, patterns, options = {}) {
var _a, _b, _c;
// Pattern is required to be non-empty
imperative_1.ImperativeExpect.toNotBeNullOrUndefined(patterns, ZosFiles_messages_1.ZosFilesMessages.missingPatterns.message);
patterns = patterns.filter(Boolean);
imperative_1.ImperativeExpect.toNotBeEqual(patterns.length, 0, ZosFiles_messages_1.ZosFilesMessages.missingPatterns.message);
const zosmfResponses = [];
const maxLength = options.maxLength;
// Keep a count of returned data sets to compare against the `maxLength` option.
let totalCount = 0;
// Get names of all data sets
for (const pattern of patterns) {
// Stop searching for more data sets once we've reached the `maxLength` limit (if provided).
if (maxLength && totalCount >= options.maxLength) {
break;
}
let response;
try {
response = yield List.dataSet(session, pattern, {
attributes: options.attributes,
volume: options.volume,
recall: options.recall,
maxLength: maxLength ? maxLength - totalCount : undefined,
start: options.start
});
}
catch (err) {
if (!(err instanceof imperative_1.ImperativeError && ((_a = err.errorCode) === null || _a === void 0 ? void 0 : _a.toString().startsWith("5")))) {
throw err;
}
// Listing data sets with attributes may fail sometimes, for
// example if a TSO prompt is triggered. If that happens, we
// try first to list them all without attributes, and then fetch
// the attributes for each data set one by one. When an error
// is thrown we record it on the response object. This is a slow
// process but better than throwing an error.
response = yield List.dataSet(session, pattern);
let listsInitiated = 0;
const createListPromise = (dataSetObj) => {
if (options.task != null) {
options.task.percentComplete = Math.floor(imperative_1.TaskProgress.ONE_HUNDRED_PERCENT *
(listsInitiated / response.apiResponse.items.length));
listsInitiated++;
}
return List.dataSet(session, dataSetObj.dsname, { attributes: true, maxLength: 1 }).then((tempResponse) => {
Object.assign(dataSetObj, tempResponse.apiResponse.items[0]);
}, (tempErr) => {
Object.assign(dataSetObj, { error: tempErr });
});
};
const maxConcurrentRequests = options.maxConcurrentRequests == null ? 1 : options.maxConcurrentRequests;
if (maxConcurrentRequests === 0) {
yield Promise.all(response.apiResponse.items.map(createListPromise));
}
else {
yield (0, core_for_zowe_sdk_1.asyncPool)(maxConcurrentRequests, response.apiResponse.items, createListPromise);
}
}
// Track the total number of datasets returned for this pattern.
if (response.success && ((_c = (_b = response.apiResponse) === null || _b === void 0 ? void 0 : _b.items) === null || _c === void 0 ? void 0 : _c.length) > 0) {
totalCount += response.apiResponse.items.length;
}
zosmfResponses.push(...response.apiResponse.items);
}
// Check if data sets matching pattern found
if (zosmfResponses.length === 0) {
return {
success: false,
commandResponse: ZosFiles_messages_1.ZosFilesMessages.noDataSetsMatchingPattern.message,
apiResponse: []
};
}
// Exclude names of data sets
for (const pattern of options.excludePatterns || []) {
const response = yield List.dataSet(session, pattern);
response.apiResponse.items.forEach((dataSetObj) => {
const responseIndex = zosmfResponses.findIndex(response => response.dsname === dataSetObj.dsname);
if (responseIndex !== -1) {
zosmfResponses.splice(responseIndex, 1);
}
});
}
// Check if exclude pattern has left any data sets in the list
if (zosmfResponses.length === 0) {
return {
success: false,
commandResponse: ZosFiles_messages_1.ZosFilesMessages.noDataSetsInList.message,
apiResponse: []
};
}
return {
success: true,
commandResponse: util.format(ZosFiles_messages_1.ZosFilesMessages.dataSetsMatchedPattern.message, zosmfResponses.length),
apiResponse: zosmfResponses
};
});
}
static get log() {
return imperative_1.Logger.getAppLogger();
}
}
exports.List = List;
//# sourceMappingURL=List.js.map