Merge pull request #4190 from zowe/v3/feature/jobHeaders

Replay #3951 onto correct base branch

bin/commands/init/generate/.help

@@ -2,6 +2,8 @@ Generate ready to execute JCL samples from zowe.yaml configuration values.
 
 This command executes the job ZWEGENER which copies the JCL templates from Zowe's SZWESAMP dataset, except those not valid for your system ESM, and creates resolved, ready to execute JCL content within the dataset defined by the zowe.yaml property `zowe.setup.dataset.jcllib` (such as `zowe.setup.dataset.prefix` + "CUST.JCLLIB")
 
+If you need to customize the JOB statements, set the zowe.yaml property `zowe.environments.jclHeader`. See examples at the end of this help.
+
 These JCL files can be run by any means desired afterward.
 The actions of `zwe init` will run them automatically if desired.
 Each `zwe init` action has a `--dry-run` command which will print the value of the particular JCL file used, but not submit it.
@@ -64,3 +66,31 @@ If you want to use a premade keyring with Zowe, do not run these. These are for
 
 The above datasets can be run to set up a Zowe instance.
 You can also use `zwe init` or `zwe init` subcommands to have them run automatically.
+
+JCL JOB statement customization:
+- Each JOB statement is defined as `//ZWEnnnnn JOB {zowe.environments.jclHeader}`, where `nnnnn` identifies each job
+- Default setting is empty string causing no additional JOB fields will be used - if your site or External Security Manager does not require additional fields, you can skip this
+- Otherwise you can use `zwe init generate` to set additional JOB fields
+- Note: JCL syntax is not checked by `zwe init generate` command
+
+Accounting information only:
+```yaml
+zowe:
+  environments:
+    jclHeader: 123456
+```
+Additional fields as one string:
+```yaml
+zowe:
+  environments:
+    jclHeader: "123456,\n//       'Zowe User',\n//       NOTIFY=&SYSUID"
+```
+Additional fields as an array:
+```yaml
+zowe:
+  environments:
+    jclHeader:
+    - "123456,"
+    - "//       'Zowe User',"
+    - "//       NOTIFY=&SYSUID"
+```

bin/commands/init/generate/index.ts

@@ -15,7 +15,7 @@ import * as xplatform from "xplatform";
 import * as fs from '../../../libs/fs';
 import * as config from '../../../libs/config';
 import * as common from '../../../libs/common';
-import * as stringlib from '../../../libs/string';
+import * as zosDataset from '../../../libs/zos-dataset';
 import * as zosFs from '../../../libs/zos-fs';
 import * as zosJes from '../../../libs/zos-jes';
 
@@ -33,6 +33,19 @@ export function execute(dryRun?: boolean) {
     common.printErrorAndExit(`Error ZWEL0157E: Zowe runtime directory (zowe.runtimeDirectory) is not defined in Zowe YAML configuration file.`, undefined, 157);
   }
 
+  let jclPostProcessing = false;
+  let jclHeaderJoined = '';
+  const jclHeader = ZOWE_CONFIG.zowe.environments.jclHeader == null ? '' : ZOWE_CONFIG.zowe.environments.jclHeader;
+  if (Array.isArray(jclHeader)) {
+    jclPostProcessing = true;
+    jclHeaderJoined = jclHeader.join("\n");
+  } else {
+    jclHeaderJoined = jclHeader.toString();
+    if (jclHeaderJoined && (jclHeaderJoined.match(/\n/g) || []).length) {
+      jclPostProcessing = true;
+    }
+  }
+
   const tempFile = fs.createTmpFile();
   if (zosFs.copyMvsToUss(ZOWE_CONFIG.zowe.setup.dataset.prefix + '.SZWESAMP(ZWEGENER)', tempFile) !== 0) {
     common.printErrorAndExit(`ZWEL0143E Cannot find data set member '${ZOWE_CONFIG.zowe.setup.dataset.prefix + '.SZWESAMP(ZWEGENER)'}'. You may need to re-run zwe install.`, undefined, 143);
@@ -44,6 +57,7 @@ export function execute(dryRun?: boolean) {
   // $$ inserts a '$', replace(/[$]/g, '$$$$') => double each '$' occurence
   jclContents = jclContents.replace(/\{zowe\.setup\.dataset\.prefix\}/gi, prefix.replace(/[$]/g, '$$$$'));
   jclContents = jclContents.replace(/\{zowe\.runtimeDirectory\}/gi, runtimeDirectory.replace(/[$]/g, '$$$$'));
+  jclContents = jclContents.replace(/\{zowe\.environments\.jclHeader\}/i,jclHeaderJoined.replace(/[$]/g, '$$$$'));
   if (std.getenv('ZWE_PRIVATE_LOG_LEVEL_ZWELS') !== 'INFO') {
     jclContents = jclContents.replace('noverbose -', 'verbose -');
   }
@@ -91,11 +105,29 @@ export function execute(dryRun?: boolean) {
     common.printMessage('Submitting Job ZWEGENER');
     const jobid = zosJes.submitJob(tempFile);
     const result = zosJes.waitForJob(jobid);
-    os.remove(tempFile);
-
+    if (!jclPostProcessing) {
+      os.remove(tempFile);
+    }
     common.printMessage(`Job completed with RC=${result.rc}`);
     if (result.rc == 0) {
-      common.printMessage("Zowe JCL generated successfully");
+      let jobHeaderResult = 0;
+      if (jclHeaderJoined != '') {
+        let replaceRC = zosDataset.replaceInMember(`${ZOWE_CONFIG.zowe.setup.dataset.jcllib}(ZWESECUR)`, tempFile, /^\/\/ZWESECUR JOB/i, '//ZWESECUR JOB ' + jclHeaderJoined);
+        jobHeaderResult += replaceRC;
+      }
+      if (jclPostProcessing) {
+        const memList = zosDataset.listDatasetMembers(ZOWE_CONFIG.zowe.setup.dataset.jcllib);
+        for (let m = 0; m < memList.length; m++) {
+          let replaceRC = zosDataset.replaceInMember(`${ZOWE_CONFIG.zowe.setup.dataset.jcllib}(${memList[m]})`, tempFile, /\{zowe\.environments\.jclHeader\}/i, jclHeaderJoined);
+          jobHeaderResult += replaceRC;
+        }
+      os.remove(tempFile);
+      }
+      if (jobHeaderResult) {
+        common.printMessage("Zowe JCL JOB statement update failed. Review the JOBs before submitting.");
+      } else {
+        common.printMessage("Zowe JCL generated successfully");
+      }
     } else {
       common.printMessage(`Zowe JCL generated with errors, check job log. Job completion code=${result.jobcccode}, Job completion text=${result.jobcctext}`);
     }

bin/commands/init/index.ts

@@ -42,7 +42,7 @@ export function execute(allowOverwrite?: boolean, dryRun?: boolean, ignoreSecuri
 
   common.printLevel1Message(`Check if need to update runtime directory, Java and/or node.js settings in Zowe YAML configuration`);
   // node.home
-  let newNodeHome;
+  let newNodeHome: string;
   const configNodeHome=zoweConfig.node?.home;
   // only try to update if it's not defined, but needed
   if (!configNodeHome && enabledComponents.includes('app-server')) {
@@ -51,7 +51,7 @@ export function execute(allowOverwrite?: boolean, dryRun?: boolean, ignoreSecuri
   }
 
   // java.home
-  let newJavaHome;
+  let newJavaHome: string;
   const configJavaHome=zoweConfig.java?.home;
   const coreJavaComponents = std.getenv('ZWE_PRIVATE_CORE_COMPONENTS_REQUIRE_JAVA').split(',');
   // only try to update if it's not defined, but needed
@@ -66,7 +66,7 @@ export function execute(allowOverwrite?: boolean, dryRun?: boolean, ignoreSecuri
   }
 
   // zowe.runtimeDirectory
-  let newZoweRuntimeDir;
+  let newZoweRuntimeDir: string;
   // do we have zowe.runtimeDirectory defined in zowe.yaml?
   const configRuntimeDir = zoweConfig.zowe?.runtimeDirectory;
   if (configRuntimeDir) {

bin/libs/zos-dataset.ts

@@ -4,13 +4,14 @@
   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.
 */
 
 import * as std from 'cm_std';
+import * as xplatform from 'xplatform';
 
 import * as common from './common';
 import * as stringlib from './string';
@@ -115,7 +116,7 @@ export function isDatasetSmsManaged(dataset: string): { rc: number, smsManaged?:
   // listds 'IBMUSER.LOADLIB' label
   // IBMUSER.LOADLIB
   // --RECFM-LRECL-BLKSIZE-DSORG
-  //   U     **    6144    PO                                                                                          
+  //   U     **    6144    PO
   // --VOLUMES--
   //   VPMVSH
   // --FORMAT 1 DSCB--
@@ -181,3 +182,62 @@ export function isDatasetSmsManaged(dataset: string): { rc: number, smsManaged?:
     return { rc: 1 };
   }
 }
+
+export function listDatasetMembers(dsName: string): string[] {
+  // LISTDS 'ZOWE.JCLLIB' MEMBERS
+  // ZOWE.JCLLIB
+  // --RECFM-LRECL-BLKSIZE-DSORG
+  //   FB    80    27920   PO
+  // --VOLUMES--
+  //   VOL123
+  // --MEMBERS--
+  //   ZWECSRVS
+  //   ZWECSVSM
+  //   ZWEIAPF
+  //   ZWEIAPF2
+  const listDSCommand = `LISTDS '${stringlib.escapeDollar(dsName)}' MEMBERS`;
+  common.printTrace(`  * listDatasetMembers in: "${listDSCommand}"`);
+  const result = zoslib.tsoCommand(listDSCommand);
+  let listOfMembers: string[] = [];
+  if (result.rc == 0 && result.out) {
+      let validMemberName = false;
+      let output = result.out.split("\n");
+      for (let m = 0; m < output.length; m++) {
+          let member = output[m].trim();
+          if (member && validMemberName) {
+              listOfMembers.push(member);
+          }
+          if (member == '--MEMBERS--') {
+              validMemberName = true;
+          }
+      }
+  }
+  common.printTrace(`  * listDatasetMembers out: "${listOfMembers}"`);
+  return listOfMembers;
+}
+
+export function replaceInMember(member: string, tempFile: string, regexFind: RegExp, replaceTo: string): number {
+  common.printTrace(`  * replaceInMember: ${member}, ${tempFile}, ${regexFind} -> ${replaceTo}`);
+  const catCommand = `cat "//'${stringlib.escapeDollar(member)}'"`;
+  const catResult = shell.execOutSync('sh', '-c', catCommand);
+  if (catResult.rc == 0 && catResult.out != undefined) {
+    if (catResult.out.match(regexFind)) {
+      const memberContents = catResult.out.replace(regexFind, replaceTo.replace(/[$]/g, '$$$$'));
+      let storeResult = xplatform.storeFileUTF8(tempFile, xplatform.AUTO_DETECT, memberContents);
+      if (storeResult) {
+        common.printTrace(`  * replaceInMember: xplatform.storeFileUTF8 failed with: ${storeResult}`);
+        return 2;
+      }
+      const cpCommand = `cp "${stringlib.escapeDollar(tempFile)}" "//'${stringlib.escapeDollar(member)}'"`
+      let cpResult = shell.execSync('sh', '-c', cpCommand);
+      if (cpResult.rc) {
+        common.printTrace(`  * replaceInMember: shell.execSync(${cpCommand}) failed with: ${cpResult.rc}`);
+        return 3;
+      }
+    }
+    return 0;
+  } else {
+    common.printTrace(`  * replaceInMember: shell.execOutSync(${catCommand}) failed with: ${catResult.rc}`);
+    return 1;
+  }
+}

files/SZWEEXEC/ZWEGEN00

@@ -326,6 +326,7 @@ say 'All of the substitutions were found.'
 /*
 ================================================================================
     Invoke the edit macro on the substitutions for each member.
+    Skip zowe.environments.jclHeader if contains \n (x'15') or not initialized
     ZWECHG: change all word1 word2
       word1 is expected to be {zowe.something}
       word2 is anything, including spaces, single or double apostrophes
@@ -341,6 +342,12 @@ do i = 1 to members.0
       call Print 'Edit 'd'.'
       old = '{'members.i.substitutions.j'}'
       new = value('CFG.'members.i.substitutions.j)
+      if old = '{zowe.environments.jclHeader}' then do
+        if pos(x2c('15'), new) > 0 then
+          iterate j
+        if symbol('CFG.'members.i.substitutions.j) = 'LIT' then
+          iterate j
+      end
       apostrophes1 = "'"
       apostrophes2 = "'"
       if pos("'", new) > 0 & pos('"', new) = 0 then do

files/SZWESAMP/ZWECSRVS

@@ -1,4 +1,4 @@
-//ZWECSRVS JOB
+//ZWECSRVS JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWECSVSM

@@ -1,4 +1,4 @@
-//ZWECSVSM JOB
+//ZWECSVSM JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEGENER

@@ -1,4 +1,4 @@
-//ZWEGENER JOB
+//ZWEGENER JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIACF

@@ -1,4 +1,4 @@
-//ZWEIACF JOB
+//ZWEIACF JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIACFZ

@@ -1,4 +1,4 @@
-//ZWEIACFZ JOB
+//ZWEIACFZ JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIAPF

@@ -1,4 +1,4 @@
-//ZWEIAPF JOB
+//ZWEIAPF JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIAPF2

@@ -1,4 +1,4 @@
-//ZWEIAPF2 JOB
+//ZWEIAPF2 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRA1

@@ -1,4 +1,4 @@
-//ZWEIKRA1 JOB
+//ZWEIKRA1 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRA2

@@ -1,4 +1,4 @@
-//ZWEIKRA2 JOB
+//ZWEIKRA2 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRA3

@@ -1,4 +1,4 @@
-//ZWEIKRA3 JOB
+//ZWEIKRA3 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRR1

@@ -1,4 +1,4 @@
-//ZWEIKRR1 JOB
+//ZWEIKRR1 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRR2

@@ -1,4 +1,4 @@
-//ZWEIKRR2 JOB
+//ZWEIKRR2 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRR3

@@ -1,4 +1,4 @@
-//ZWEIKRR3 JOB
+//ZWEIKRR3 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRT1

@@ -1,4 +1,4 @@
-//ZWEIKRT1 JOB
+//ZWEIKRT1 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRT2

@@ -1,4 +1,4 @@
-//ZWEIKRT2 JOB
+//ZWEIKRT2 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIKRT3

@@ -1,4 +1,4 @@
-//ZWEIKRT3 JOB
+//ZWEIKRT3 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIMVS

@@ -1,4 +1,4 @@
-//ZWEIMVS JOB
+//ZWEIMVS JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIMVS2

@@ -1,4 +1,4 @@
-//ZWEIMVS2 JOB
+//ZWEIMVS2 JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEINSTL

@@ -1,4 +1,4 @@
-//ZWEINSTL JOB
+//ZWEINSTL JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIRAC

@@ -1,4 +1,4 @@
-//ZWEIRAC JOB
+//ZWEIRAC JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEIRACZ

@@ -1,4 +1,4 @@
-//ZWEIRACZ JOB
+//ZWEIRACZ JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEISTC

@@ -1,4 +1,4 @@
-//ZWEISTC JOB
+//ZWEISTC JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEITSS

@@ -1,4 +1,4 @@
-//ZWEITSS JOB
+//ZWEITSS JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWEITSSZ

@@ -1,4 +1,4 @@
-//ZWEITSSZ JOB
+//ZWEITSSZ JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which

files/SZWESAMP/ZWENOKRA

@@ -1,4 +1,4 @@
-//ZWENOKRA JOB
+//ZWENOKRA JOB {zowe.environments.jclHeader}
 //*
 //* This program and the accompanying materials are made available
 //* under the terms of the Eclipse Public License v2.0 which