Node Packaged Masterfully

    zowe-utils

    1.0.0 • Public • Published

    Zowe Utils

    A convenience wrapper for Zowe Cli.

    npm NPM npm JavaScript Style Guide


    This module exports two Objects:

    1. ZosJob : Submit a Job and get a promise , that resolves to execution's outlist.

    1. Create a job from a jcl (string/ local file/ pds member) : let job = new ZosJob(jcl) .
    2. Submit the Job with job.sub() and get back a Promise.
    3. Watch job's running status by subscribing to 'status-change' event : job.on('status-change', newStatus => console.log(newStatus)) .
    4. Cancel job's execution at any time , with job.cancel().

    2. ZosFtp : Ftp common operations.

    1. Get/Put/Del a dataset or PDS member from/to mainframe, e.g. : ZosFtp.del('U001.ZOWEUTIL.FILE')
    2. List Directories , e.g. : ZosFtp.list('U001.ZOWEUTIL.PDS')

    Prerequisites

    • Node.js: Any supported Node.js LTS version. For an up-to-date list of supported LTS versions, see Nodejs.org.

    • Zowe installed at Z/OS.

    • Zowe Cli installed globally at local machine. Zowe Cli @next is strongly recommended for better performance.

    • Your z/OS UserId should be a member of group IZUUSER.


    Getting Started

    Install the package to your project:

    npm i zowe-utils --save 
    
    or
    
    yarn add zowe-utils
    

    In your code :

    const zoweUtils = require('zowe-utils')
    const config = {
      user: 'ZOS_USERNAME',      // String: REQUIRED
      password: 'ZOS_PASSWD',    // String: REQUIRED
      host: 'ZOSMF_HOST',          // String: REQUIRED, host's IP address 
      port: ZOSMF_PORT           // Number: OPTIONAL, defaults to 30443.
    }
    const { ZosJob, ZosFtp } = zoweUtils(config)

    Now you have available both ZosJob & ZosFtp Objects.

    For a full list of config properties check the API section.

    Try to submit a jcl that resides at mainframe , e.g. : 'U001.ZOWEUTIL.PDS(TESTJCL)'

    let jcl = {
      name: 'TESTJCL',                      // String: REQUIRED, Assign a name to your job, used for logging and outlist save name
      description: 'Basic Jcl with RC=0',   // String: Optional
      source: 'U001.ZOWEUTIL.PDS(TESTJCL)', // String: REQUIRED
      sourceType: 'hostFile',               // String: REQUIRED
      RC: '0000'                            // String: REQUIRED, Maximum expected return code
    }
    
    let job = new ZosJob(jcl)
    try {
      let outlist = await job.sub()
      console.log('job.RC :',job.RC)
    } catch(error) {
      console.log(error)
    }

    API

    const zoweUtils = require('zowe-utils')
    const { ZosJob, ZosFtp } = zoweUtils(config)

    Initialise ZosJob and ZosFtp by providing the config object:

    • config<object>:
      • user <string>: Required.
      • password <string>: Required.
      • host <string>: Required. IP address of ZOSMF.
      • port <number>: Optional. Default: 30443
      • encoding <string>: Optional. The encoding of the host. Local JCL's and datasets should always be in 'UTF8' before submitting/uploading to host . Default: 'UTF8'
      • watchJobInterval <number>: Optional. Time interval (ms) used internally by ZosJob to watch Job's status during execution. If the host is not powerful enough , increase this number. Default: 1000
      • deleteMainframeOutlist <boolean>: Optional. Set this to false if you want ZosJob to keep outlist at host, after job completion. Default: true Not Yet Implemented
      • loggingFunction<function>: Optional. Handle / store logs the way you want, instead of logging them at the terminal. For example you can use test/debug.js module , to write to a file of your choice. Default: console.log

    ZosJob

    const zoweUtils = require('zowe-utils')
    const { ZosJob } = zoweUtils(config)
    • Constructor :
    let job = new ZosJob(jcl)
    • jcl<object>:

      • name <string>: Required. Provide a name for your job. Used by ZosJob for logging and naming outlists. e.g. 'TESTJCL'
      • description <string>: Optional.A description of what the job is doing so that you can have all the information attached to the job object. e.g. 'Testing ZosJob basic functionality.'
      • source <string>: Required. This can be a path of a local file , a Javascript String or a host PDS member containing valid JCL code. Examples:
        • Local File:

          'C:\\local.jcl'

        • Host PDS member:

          'U001.ZOWEUTIL.PDS(TESTJCL)'

        • Javascript String ( has at least one newline ('\n') character ):

          '//U001T JOB (BATI,U001,U001)\n' +
          '// EXEC PGM=IEFBR14'
          
      • sourceType <string>: Required. Defines the source type and can be one of these values: 'localFile', 'hostFile', 'string'.
      • RC <string>: Required. The maximum RC expected by the execution of the jcl. If the returned RC is greater than the string declared here, the job.sub() promise will be rejected. e.g. '0004'
      • outlistLocalPath<string>: Optional. The local path where to store the outlist execution results. Default: null
    • ZosJob Methods

      • sub(): Submits the job to JES. Returned promise resolves to outlist of the execution.
        try {
          let outlist = await job.sub()
          console.log(outlist)
          console.log('job.RC :',job.RC)
        } catch(error) {
          console.log(error)
        }  
      • cancel() : Cancel job submission. Returned promise resolves to undefined.
        try {
          await job.cancel()
        } catch(error) {
          console.log(error)
        }  
    • ZosJob Events

      • 'status-change': Emitted whenever job's running status changes e.g. from INPUT to ACTIVE.
        job.on('status-change', newStatus => console.log(newStatus)) // 'ACTIVE'
      • 'job-id': Emitted when JES assigns ID to job e.g. 'JOB19788'
        job.on('job-id', jobId => console.log(jobId)) // 'JOB19788'

    ZosFtp

    • ZosFtp Methods
      • put ( source <string>:Required, hostFile <string>:Required, options <object>:Required): Put the local file or the Javascript String defined by source , to hostFile (it will be deleted and recreated if it exists). Returned promise resolves to undefined.

        • options
          • sourceType<string>: Required. Can be either 'localFile' or 'string'.

          • allocationsOptions<_pairs_of_key_values>: Optional. You can specify the allocation attributes listed under options of zowe zos-files create data-set-sequential command. e.g.

            recfm: 'FB',
            lrecl: 300
        try {
          // source can be a path to local file 
          await ZosFtp.put('C:\\local.txt','U001.ZOWEUTIL.FILE',{
            sourceType: 'localFile'
          })
          // or a Javascript String.
          await ZosFtp.put('I am going to host!','U001.ZOWEUTIL.STRING', {
            sourceType: 'string'
          })
          // supply allocation parameters
          await ZosFtp.put('C:\\local.txt','U001.ZOWEUTIL.FILE2',{
            sourceType: 'localFile',
            recfm : 'FB', 
            lrecl:50, 
            size: '125CYL'
          })
        } catch(error) {
          console.log(error)
        }  
      • get ( hostFile <string>:Required, localFile <string>:Optional): Download the hostFile z/OS dataset or PDS member to a localFile path. If localFile is omitted, then the Promise will resolve with the contents of the host file as a Javascript String.

        try {
          // download hostFile to localFile
          await ZosFtp.get('U001.ZOWEUTIL.FILE','C:\\local3.txt')
          // get contents of hostFile as a Javascript String.
          const result = await ZosFtp.get('U001.ZOWEUTIL.STRING')
          console.log(result) // 'I am going to host!'
        } catch(error) {
          console.log(error)
        }  
      • del ( hostFile <string>:Required): Delete the hostFile Dataset, PDS or PDS member.

        try {
          await ZosFtp.del('U001.ZOWEUTIL.FILE')
        } catch(error) {
          console.log(error)
        }  
      • list ( hostPath <string>:Required): List dataset or PDS members defined by the hostpath variable.

          try {
            const result = await ZosFtp.list('U001.ZOWEUTIL.PDS')
            console.log(result) 
          } catch(error) {
            console.log(error)
          }  

    Running the tests

    Create a .env file at the root of the project and assign the following global variables:

    ZOS_FTP_USERNAME='my_user_id'
    ZOS_FTP_PASSWD='my_password'
    ZOS_FTP_HOST='host_ip_address'
    ZOS_FTP_PORT='host_port'
    ZOS_ENCODING='host_encoding'
    ZOS_JOB_STATEMENT='//jobName JOB (SYSS,userId,userId)' # Minimal JOB statement needed by your z/OS installation for JCL to run 

    Then issue the test command:

    npm run test
    
    or 
    
    yarn test
    

    Authors

    • Christopher Chamaletsos

    See also the list of contributors who participated in this project.


    License

    This project is licensed under the MIT License - see the LICENSE.md file for details

    Install

    npm i zowe-utils

    DownloadsWeekly Downloads

    1

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    37.9 kB

    Total Files

    16

    Last publish

    Collaborators

    • chrishham