z/OS Node Accessor

A Node module to help Node.JS developers interacting with z/OS easily, taking advantage of z/OS FTP service. If z/OS FTP service is not configured as FTP over SSL, it's recommended to be deployed on z/OS, to avoid transferring user account/password in clear-text over network. Otherwise, the secure connection of FTP over SSL is recommended. IBM SDK for Node.js - z/OS is available at https://developer.ibm.com/mainframe/products/ibm-sdk-for-node-js-z-os/.

For a Zowe CLI plugin based on this functionality, see https://github.com/zowe/zowe-cli-ftp-plugin

Installation & Test

npm install zos-node-accessor   # Put latest version in your package.json

Features

List MVS dataset or USS files
Download/Upload MVS dataset or USS files
Submit JCL and query its status to track its completion
Access SYSOUT dataset

Migration from v1

zos-node-accessor is rewritten in TypeScript, and defines API methods in more consistent way. So some old API methods are renamed. Here are about some details useful when you migrate the code using zos-node-accessor v1 to v2.

listDataset(...) is renamed to listDatasets(...)
getDataset(...) is split and renamed to downloadFile and downloadDataset(...)
queryJob(...) returns the enum member of JobStatusResult
Job methods takes the query option object like JobIdOption, JobLogOption, or JobListOption
rename(...) is split and renamed to renameFile(...) and renameDataset(...)
delete(...) is split and renamed to deleteFile(...) and deleteDataset(...)

Many list methods in v2 like listDatasets(...) and listFiles(...) returns the objects with the type like DataSetEntry, instead of the key/value pairs in v1. To make the migration easier, you can enable migrationMode to have zos-node-accessor return the v1 key/value pairs, so that you can take time to change code to use the types object. This migration mode will be dropped in future. Let us know, if you have problem in removing the code using the key/value pairs.

    const zosAccessor = new ZosAccessor();
    zosAccessor.setMigrationMode(true);
    var connectionInfo = {
        ....
    };
    await zosAccessor.connect(connectionInfo)

Usage

This accessor leverages z/OS FTP server to interact with z/OS. To work with z/OS JES better, it requires JESINTERFACELevel set to 2 on z/OS FTP settings.

Connection
MVS dataset
USS file or directory
JES jobs
Others
- Retrieve Server Status
- Submit SITE commands

Connection

Before connecting to a z/OS server, you need to initialize an instance using the constructor new ZosAccessor(), then call the connect(option: ConnectionOption) method, where:

Parameter

option - ConnectionOption - Configuration passed to the underlying ftp library.

ConnectionOption

user - string - Username for authentication on z/OS. Default: 'anonymous'
password - string - Password for authentication on z/OS. Default: 'anonymous@'
host - string - The hostname or IP address of the z/OS server to connect to. Default: 'localhost'
port - number - The port of the z/OS FTP server. Default: 21
secure - boolean - Set to true for both control and data connection encryption. Default: false
secureOptions - object - Additional options to be passed to tls.connect(). Default: (none)
connTimeout - number - How long (in milliseconds) to wait for the control connection to be established. Default: 30000
pasvTimeout - number - How long (in milliseconds) to wait for a PASV data connection to be established. Default: 30000
keepalive - number - How often (in milliseconds) to send a 'dummy' (NOOP) command to keep the connection alive. Default: 10000

Return

A promise that resolves itself (ZosAccessor object), and rejects on any error.

Example

import { ZosAccessor } from '../zosAccessor';

const accessor = new ZosAccessor();
await accessor.connect({
    user: 'myname',
    password: 'mypassword',
    host: 'localhost',
    port: 21,
    pasvTimeout: 60000,
    secure: true,
    secureOptions: {
        ca: [ caBuffer ]
    }
});

MVS dataset

Allocate Dataset

allocateDataset(datasetName: string, allocateParamsOrString?: string | AllocateParams) - Allocate sequential or partition (with the DCB attribut "PDSTYPE=PDS") dataset.

Parameter

datasetName - string - Dataset name to allocate.
allocateParams - string | AllocateParams - A string of space separated DCB attributes or an object of DCB attribute key-value pairs, eg. "LRECL=80 RECFM=VB" or {"LRECL": 80, "RECFM": "VB"}. These attributes are transferred as FTP site sub commands. The tested attributes includes BLKsize/BLOCKSIze, BLocks, CYlinders, Directory, LRecl, PDSTYPE, PRImary, RECfm, SECondary, and TRacks.

Note: DSORG=PO was defined by zos-node-accessor, not site sub command. It's deprecated by site sub command, PDSTYPE=PDS or PDSTYPE=PDSE.

The site sub commands can be found at https://www.ibm.com/docs/en/zos/2.3.0?topic=subcommands-site-subcommandsend-site-specific-information-host.

Option Key	Description
BLKsize/BLOCKSIze=size	block size
BLocks	space allocations in blocks
CYlinders	space allocations in cylinders
DATAClass=data_class	data class
DCBDSN=data_set_name	the data set to be used as a model for allocation of new data sets
Directory=size	directory blocks
DSNTYPE=SYSTEM or BASIC or LARGE	data set name type
EATTR=SYSTEM or NO or OPT	extended attributes
LRecl=length	logical record length
MGmtclass=mgmtclass	management class
PDSTYPE=PDS or PDSE	PDS type
PRImary=amount	primary space
RECfm=format	record format
RETpd=days	retention period
SECondary=amount	secondary space
STOrclass=storage_class	storage class
TRacks	space allocations in tracks
UCOUN=unit_count or P	how many devices to allocate concurrently for this allocation request
Unit=unit_type	unit type for allocation of new data sets
VCOUNT=volume_count	number of tape data set volumes that an allocated data set can span
VOLume=volume_serial or (volume_serial_list)	volume serial number

Return

A promise that resolves on success, rejects on error.

Example

await connection.allocateDataset('HLQ.ABC.DEF', 'LRECL=80 RECFM=FB BLKSIZE=320');

await connection.allocateDataset('HLQ.ABC.PDS', {'LRECL': 80, 'RECFM': 'FB', 'BLKSIZE': 320, 'PDSTYPE': 'PDS', 'DIRECTORY': 20});

List Datasets

listDatasets(dsn: string) - Lists the datasets whose names match with the given dataset name.

Note: This method is renamed from listDataset(dsnOrDir) in v1.0.x, to be consistent with the other list methods.

Parameter

dsn - string - Full qualified name of dataset, or dataset name with wildcards (* or ?)

Return

A promise that resolves a list of DatasetEntry.

DatasetEntry

blockSize - number - Block size
dsOrg - string - Dataset organization
extends - number - How many extends
name - string - Dataset name
isMigrated - boolean - Is migrated or not. When migrated, many attributes like recordLength is unknown.
recordFormat - string - Record format
recordLength - number - Record length
referred - string - Last referred date
unit - string - Device unit
usedTracks - number - Used tracks
volume - string - Volume

Example

await connection.listDatasets('HQL.*.JCL');
for (const entry of list) {
  console.log('name:', entry.name, 'dsorg', entry.dsOrg);
}

List members of PDS dataset

listMembers(partitionDsn: string) - Lists the members of partition dataset

Parameter

partitionDsn - string - Full qualified name of partition dataset

Return

A promise that resolves a list of DatasetMemberEntry.

DatasetMemberEntry

changed - string - Changed date
created - string - Created date
name - string - Member name
size - number - Size
version - string - Version

Upload MVS dataset

uploadDataset(input: Input, destDataset: string, transferMode: TransferMode = TransferMode.ASCII, allocateParamsOrString?: string | AllocateParams) - Uploads data to the specified dataset on z/OS.

Parameter

input - Input - Input, which can be a ReadableStream, a Buffer, or a path to a local file.
destDataset - string - Name of the dataset to store the uploaded data.
transferMode - TransferMode_ - Data transfer mode, either TransferMode.ASCII or TransferMode.BINARY. When transfering 'ascii' files, the end-of-line sequence of input should always be \r\n. Otherwise the transfered file will get truncated.
allocateParamsOrString - string | AllocateParams - A string of space separated DCB attributes or an object of DCB attribute key-value pairs, eg. "LRECL=80 RECFM=VB" or {"LRECL": 80, "RECFM": "VB"}. The tested attributes: BLKsize/BLOCKSize, LRecl, RECfm, PRImary, SECondary, TRacks.

Return

A promise that resolves on success, rejects on error.

Example

import * as fs from 'fs';

const input = fs.readFileSync('/etc/hosts', 'utf8').replace(/\r?\n/g, '\r\n');
await connection.uploadDataset(input, 'HLQ.HOSTS');
await connection.uploadDataset(input, 'HLQ.HOSTS', "LRECL=80 RECFM=FB");

Download MVS dataset

downloadDataset(dsn: string, transferMode: TransferMode = TransferMode.ASCII, stream = false, siteParams?: string) - Downloads the specified dataset or member of patition dataset.

Parameter

dsn - string - Specify a full qualified dataset name, or USS file name. It CAN NOT contain any wildcard (*).
transferMode - TransferMode - TransferMode.ASCII, TransferMode.BINARY, TransferMode.ASCII_STRIP_EOL, TransferMode.ASCII_RDW, TransferMode.ASCII_NO_TRAILING_BLANKS, or TransferMode.BINARY_RDW. The TransferMode.ASCII, TransferMode.ASCII_STRIP_EOL, TransferMode.ASCII_RDW, or TransferMode.ASCII_NO_TRAILING_BLANKS asks z/OS FTP service to convert EBCDIC characters to ASCII. The TransferMode.ASCII_STRIP_EOL asks z/OS FTP service not to append a CLRF to the end of each record. The TransferMode.ASCII_NO_TRAILING_BLANKS asks z/OS FTP service to remove trailing blanks. The TransferMode.ASCII_RDW or TransferMode.BINARY_RDW supports to download variable length dataset, which add 4-byte Record Description Word (RDW) at the beginning of each record.
stream - boolean - true if you want to obtain a ReadableStream of the data set content, or false to read a full dataset into memory (in Buffer). The buffer accepts up to 4MB data. For large dataset, use stream=true instead.
siteParams - string - Add extra site parameters, for example, 'sbd=(IBM-1047,ISO8859-1)' for encoding setting.

Return

A promise that resolves content of the dataset in either Buffer or ReadableStream.

Example

const jclBuffer = await connection.downloadDataset('HQL.AA.JCL', TransferMode.ASCII);
console.log('JCL is:');
console.log(jclBuffer.toString());

const jclStream = await connection.downloadDataset('HQL.AA.JCL(MEMBER1)', TransferMode.ASCII, true);
const writable = fs.createWriteStream('file.txt');
jclStream.pipe(writable);

Delete dataset

deleteDataset(dsn) - Deletes the dataset or member of parition dataset whose names match with the given dataset name.

Parameter

dsn - string - Specify a full qualified dataset name to delete. It CAN NOT contain a wildcard (*).

Return

A promise that resolves on success, rejects on error.

Example

await connection.deleteDataset('HQL.AA.JCL');

Rename dataset

renameDataset(dsn: string, newDsn string) - Renames dataset, member in partition dataset.

Parameter

dsn - string - Old dataset name.
newDsn - string - New dataset name to rename to.

Return

A promise that resolves on success, rejects on error.

Example

await connection.renameDataset('HQL.AA.JCL', 'HQL.BB.JCL')

USS file or directory

Make directory

makeDirectory(directoryName: string) - Makes USS directory with the given directory name.

Parameter

directoryName - string - Makes USS directory with the given directory name.

Return

A promise that resolves on success, rejects on error.

Example

await connection.makeDirectory('/u/user/my_directory'});

List files

listFiles(dirPath: string) - Lists files whose names match with the given path name.

Parameter

dirPath - string - Directory to list or file name with widecards (* or ?)

Return

A promise that resolves a list of USSEntry.

USSEntry

name - string - File or directory name
group - string - Group
fileType - FileType - File type
linkedTo - string - The target file if this entry is the link
lastModified - Date - Last modified date
owner - string - Owner
permissions - string - Permission string
size - number - File size

Example

const list = await connection.listFiles('/u/user1/');
for (const entry of list) {
    console.log(entry.name, entry.owner, entry.group, entry.size);
}

Upload USS file

uploadFile(input: Input, destFilePath: string, transferMode: TransferMode = TransferMode.ASCII) - Uploads data to the specified USS file on z/OS.

Parameter

input - Input - Input, which can be a ReadableStream, a Buffer, or a path to a local file.
destFilePath - string - Path name of the destination file on z/OS.
transferMode - TransferMode_ - Data transfer mode, either TransferMode.ASCII or TransferMode.BINARY.

Return

A promise that resolves on success, rejects on error.

Example

import * as fs from 'fs';

const input = fs.readFileSync('/etc/hosts', 'utf8');
await connection.uploadFile(input, '/u/username/hosts');

Download USS file

downloadFile(filePath: string, transferMode: TransferMode = TransferMode.ASCII, stream = false) - Downloads the specified USS file.

Parameter

filePath - string - USS file path name.
transferMode - TransferMode - TransferMode.ASCII, TransferMode.BINARY. When downloading a text dataset, transferMode should be either TransferMode.ASCII so that z/OS FTP service converts EBCDIC characters to ASCII.
stream - boolean - true if you want to obtain a ReadableStream of the file content, or false to read a full file into memory (in Buffer). The buffer accepts up to 4MB data. For large file, use stream=true instead.

Return

A promise that resolves content of the file in either Buffer or ReadableStream.

Example

const jclBuffer = await connection.downloadFile('/etc/hosts', TransferMode.ASCII);
console.log('JCL is:');
console.log(jclBuffer.toString());

const jclStream = await connection.downloadFile('/etc/hosts', TransferMode.ASCII, true);
const writable = fs.createWriteStream('file.txt');
jclStream.pipe(writable);

Delete USS file

deleteFile(filePath: string, fileType: FileToOperate = FileToOperate.FILE_OR_DIRECTORY) - Deletes the USS files or directory whose names match with the given file path.

Parameter

filePath - string - The path name of USS file or directory. It CAN NOT contain a wildcard (*).

Return

A promise that resolves on success, rejects on error.

Example

await connection.deleteFile('/u/username/myfile');
await connection.deleteFile('/u/username/mydir');                                // Delete it, if it's empty
await connection.deleteFile('/u/username/mydir', FileToOperate.WHOLE_DIRECTORY); // Delete it, even if it's not empty.

Rename USS file

renameFile(name: string, newName: string) - Renames USS file/directory.

Parameter

name - string - Old file name.
newName - string - New file name to rename to.

Return

A promise that resolves on success, rejects on error.

Example

await connection.renameFile('/u/username/myfile', '/u/username/newfile')

JES jobs

List jobs

listJobs(queryOption?: JobListOption) - Lists the jobs matching the given query option. If the query option is not provided, it will list all jobs of the current user.

Parameter

queryOption - JobListOption - Query option

JobListOption

jobName - string - Job name, which is optional and can contain a wildcard (*). Default: '*'
jobId - string - Job ID, which is optional
owner - string - Job owner, which is optional and can contain a wildcard (*). Default: The current user
status - string - Job status, eg. ALL, OUTPUT, which is optional. Default: 'ALL'

Return

A promise that resolves an array of Job. For JESINTERFACELEVEL=2, Job contains valid jobName, jobId, owner, status, class.

Job

jobName - string - Job name
jobId - string - Job ID
owner - string - Job owner
status - string - Job status
class - string - Job class
extra - string - Extra information

Example

const jobs: Job[] = await connection.listJobs({jobName: 'TSU*', owner: 'MY-NAME'})

Submit JCL

submitJCL(jclText: string) - Submits job with the specified JCL text.

Parameter

jclText - string - JCL text to submit

Return

A promise that resolves the submitted job id.

Example

import * as fs from 'fs';

const jcl = fs.readFileSync('./unpaxz.jcl', 'utf8');
const jobId = await connection.submitJCL(jcl);

Query job

queryJob(queryOption: JobIdOption) - Returns the status the job identified by job id and optional job name.

Parameter

queryOption - JobIdOption - Job query option

JobIdOption

jobId - string - Job ID, which is required
jobName - string - Job name, which is optional and can contain a wildcard (*). Better to have it, if it's known. Default: '*'
owner - string - Job owner, which is optional. Default: The current user

Return

A promise that resolves status of the job, JobStatusResult.

JobStatusResult

SUCCESS - Job succeeds
ACTIVE - Job running
FAIL - Job fails
WAITING - Job waiting
NOT_FOUND - Cannot find job specified by the jobName and jobId

Example

const status = await connection.queryJob(jobName, jobId);
switch(status) {
    case JobStatusResult.SUCCESS:
        console.log('Job succeeded');
        break;
    case JobStatusResult.FAIL:
        console.log('Job failed');
        break;
    case JobStatusResult.ACTIVE:
        console.log('Job is running');
        break;
    case JobStatusResult.WAITING:
        console.log('Job is waiting');
        break;
    case JobStatusResult.NOT_FOUND:
        console.log('Job is not found');
        break;
}

Get job status

getJobStatus(queryOption: JobIdOption) - Returns the status of the job specified by query option.

Parameter

queryOption - JobIdOption - Job ID option

JobIdOption

jobId - string - Job ID, which is required
jobName - string - Job name, which is optional and can contain a wildcard (*). Better to have it, if it's known. Default: '*'
owner - string - Job owner, which is optional. Default: The current user

Return

A promise that resolves job status, JobStatus.

JobStatus

jobName - string - Job name
jobId - string - Job ID
owner - string - Job owner
status - string - Job status
class - string - Job class
extra - string - Extra information
rc - string | number - Job RC value, indicating job finished with numberic value or failed with error string
retcode - string - Job RC value, to support zftp plugin with consistent return code format with z/OSMF.
spoolFiles - SpoolFile[] - Spool files

SpoolFile

id - number - Spool file ID
stepName - string - Job step name
procStep - string - Proc step name
class - string - Class
ddName - string - DD name
byteCount - number - Bytes

Example

const jobStatus = await connection.getJobStatus(jobId);

Get JES spool files

getJobLog(queryOption: JobLogOption) - Returns job spool files identified by jobId.

Parameter

queryOption - JobLogOption - Job log query option

JobLogOption

fileId - number - Spool file index (1, 2, 3...), or -1, which returns all spool files separated by !! END OF JES SPOOL FILE !!. Default: -1
jobId - string - Job ID, which is required
jobName - string - Job name, which is optional and can contain a wildcard (*). Default: '*'
owner - string - Job owner, which is optional. Default: The current user

Return

A promise that resolves spool files' contents.

Example

const spoolFileContents = await connection.getJobLog({ jobName, jobId, fileId: -1 });
spoolFileContents.split(/\s*!! END OF JES SPOOL FILE !!\s*/)
    .forEach(function (spoolFile, i) {
        if (spoolFile.length > 0) {
            console.log(`Spool file ${i}:`);
            console.log(spoolFile);
        }
    });

Delete job

deleteJob(queryOption: JobIdOption) - Deletes the job of the specified job id.

Parameter

queryOption - JobIdOption - Job query option

JobIdOption

jobId - string - Job ID, which is required
owner - string - Job owner, which is optional. Default: The current user.

Return

A promise that resolves on success, rejects on error.

Example

await connection.deleteJob({ jobId: 'JOB25186' });

Others

Retrieve Server Status

stat(option) - Retrieve status information from a remote server. The following parameters are accepted:

Parameter

option - string - Optional option name like UMASK

Return

A promise that resolves status of the specified option on success, rejects on error. If option is not specified, it returns all status information.

Example

const status = await connection.stat('UMASK');
console.log(status);

Submit SITE commands

site(siteCommands) - Send site-specific information to a server. The following parameters are accepted:

Parameter

siteCommands - string - Site commands separated with space

Return

A promise that resolves text from server on success, rejects on error.

Example

await connection.site('UMASK 007');

Module Long Term Support Policy

This module adopts the Module Long Term Support (LTS) policy, with the following End Of Life (EOL) dates:

Module Version	Release Date	Minimum EOL	Node Version	EOL With	Status
2.x.x	May 2020	May 2022	v8, v10, v12		Current
1.x.x	Oct 2018	Dec 2019	v6, v8, v10, v12	Node v6	EOL

License

Eclipse Public License (EPL)

Files

README.md

Latest commit

History

README.md

File metadata and controls

z/OS Node Accessor

Installation & Test

Features

Migration from v1

Usage

Connection

Parameter

Return

Example

MVS dataset

Allocate Dataset

Parameter

Return

Example

List Datasets

Parameter

Return

Example

List members of PDS dataset

Parameter

Return

Upload MVS dataset

Parameter

Return

Example

Download MVS dataset

Parameter

Return

Example

Delete dataset

Parameter

Return

Example

Rename dataset

Parameter

Return

Example

USS file or directory

Make directory

Parameter

Return

Example

List files

Parameter

Return

Example

Upload USS file

Parameter

Return

Example

Download USS file

Parameter

Return

Example

Delete USS file

Parameter

Return

Example

Rename USS file

Parameter

Return

Example

JES jobs

List jobs

Parameter

Return

Example

Submit JCL

Parameter

Return

Example

Query job

Parameter

Return