Skip to main content

Migration Utility Explorer editor express feature

Copyright Statement

© Copyright Transiom Software, Inc. 2015, 2020. All rights reserved. Unauthorized use or disclosure of any part of the system is prohibited. Transiom Software, Inc. has granted IBM a non-exclusive license to market PEngiGUI as IBM Migration Utility Explorer.

© Copyright IBM® Corporation 2015, 2020. All rights reserved. For legal information, see http://www.ibm.com/legal/copytrade.shtml

Contents

Description

A program may be written to produce output based on selection criteria that frequently change such as date, amount values, account number, etc. Normally, such values/variables must be manually changed in the program source (in the open code or macro statement arguments), introducing potential errors and unintentional change to the program source. For example, if a program is taking a date as an argument, then the date must be in a correct format, otherwise the attempt to run the program would fail.

Traditionally, users developed special ISPF Panels so that pretested Easytrieve Plus programs can be submitted without manual changes.

The editor express was designed to replace the use of ISPF panels. Parameters/variables are collected and validated on the client work station using the key-value data concept.

To use editor express feature, two things are needed:

  1. Program(s) must be written and tested in Easytrieve Plus Macro format where variables are supplied via the macro arguments. Only the keyword arguments are accepted.
  2. The editor express shell must be written on the client work station to validate the required macro arguments. The developed shell then can be used as an interface to supply and validate the required macro arguments.
Back to Contents

Example of a functional macro

DEMOSHL1 is assumed to be in a PDS on z/OS.

 
   MACRO 0 COMPANY(02) LIMIT(20) TITLE1(‘TEST REPORT1‘) BRANCH(010) +
   OFFICER(‘AAAA‘)

   * EASYTRAN: PROCESS NOLIST,NOXREF,NOMAP
   * EASYTRAN: DEBUG (COBOL LKED SQLTRAN BIND LKED)
   * END-EASYTRAN

   FILE REPORT1 PRINTER

   FILE FILEIN DISK F (80)
   COMPANY 1 2 A HEADING (‘COMPANY‘)
   BRANCH 3 3 A HEADING (‘BRANCH‘)
   OFFICER 6 4 A HEADING (‘OFFICER‘)
   WAGE 10 08 N 2 HEADING (‘WAGE‘)
   RATE 18 05 N 3 HEADING (‘RATE‘) MASK ‘ZZ.999‘
   WBONUS W 5 P 2

   JOB INPUT FILEIN

   IF (COMPANY = ‘&COMPANY‘ +
      AND BRANCH = ‘&BRANCH‘ +
      AND OFFICER = ‘&OFFICER‘)
      WBONUS = (WAGE * RATE / 100)
      PRINT RPT1
   END-IF

   REPORT RPT1 PRINTER REPORT1 LIMIT &LIMIT LINESIZE 80 SUMCTL TAG
   SEQUENCE COMPANY BRANCH OFFICER
   CONTROL FINAL NOPRINT COMPANY BRANCH NOPRINT
   TITLE 1 ‘&TITLE1‘
   LINE 1 COMPANY BRANCH OFFICER WAGE RATE WBONUS
   

Back to Contents

Example of editor express shell

DEMOSHL1.ezx on the client system.

 
   SSTART DEMOSHL1
   MACRO 0 COMPANY(10) BRANCH(010) OFFICER (‘AAAA‘) +
   LIMIT(200) TITLE1(‘DEMO EXPLORER EXPRESS-1‘)
   *
   * Validation functions for each macro argument
   <PROPERTIES>
       TITLE1 NR text ValQuotedString:1,64
       COMPANY NR text ValABSNumber:1,99,2
       BRANCH NR text ValABSNumber:1,999,3
       OFFICER NR text ValQuotedString:4,4
       LIMIT NR text ValABSNumber:1,9999,0
   </PROPERTIES>

   **
   * Default selection values. The default panel allows users
   * to select values from the list.

   <KEYVALUES>
      TITLE1 ‘DEMO EXPLORER EXPRESS-2‘ ‘DEMO EXPLORER EXPRESS-3‘
      COMPANY 10 20 30 40 50 60
      LIMIT 100 150 200 300
      BRANCH 010 020 030 040 050 060
      OFFICER ‘AAAA‘ ‘BBBC‘ ‘CCCC‘ ‘DDDD‘
   </KEYVALUES>

   SEND
   

Back to Contents

Creating editor express shell

To create an editor express shell:

  1. Right click on directory node in the main shell tree.
  2. Select ‘New File’. The New File dialog is presented.
  3. Click on the arrow on the right side of the text box and select .ezx for file type.
  4. Complete the name and click on ‘Create’ button. When the selection screen with generic shells is opened:
    • Right click on the .ezx shell of interest
    • Click on ‘Select’ to select the shell
    • Modify the shell to conform to your own requirements
Back to Contents

Editor express shell structure

The editor shell is composed of five (5) parts:

  1. Te shell name at the top.
            Syntax:
    
               SSTART &name
                      Where: &name   - the shell name
    
                      Example:
                         SSTART DEMOSHL1
          
  2. The macro prototype statement following the shell name. The macro prototype declares the macro keyword arguments.
            Syntax:
    
               MACRO &key (&value) . . . . &key-n(&value-n)
                     Where: &key    - the keyword name
                            &value  - the default value
    
                     Example:
                         MACRO 0 COMPANY(10) BRANCH(010) OFFICER (‘AAAA‘) +
                         LIMIT(200) TITLE1(‘DEMO EXPLORER EXPRESS-1‘)
          
  3. The properties declaration following the prototype statement. The properties declaration defines properties for each keyword value.
            Syntax:
               <PROPERTIES>
                  &key NR TEXT &function
                    .
                    .
                  &key-n NR TEXT &function-n
               </PROPERTIES>
    
                      Where: &key       - the name of the key
                             &function  - one or more validation functions
    
                      The following functions are available:
    
                      ValABSNumber:&lowvalue,&highvalue,&length
                          Where:
                                &lowvalue  - the lowest number allowed
                                &highvalue - the highest number allowd
                                &length    - the maximum digits allowed
    
                          Example:
                             COMPANY NR text ValABSNumber:1,99,2
    
                      ValNumericValue:S,&length,&decimals
                          Where:
                                &length    - the maximum length allowed
                                &decimals  - the number of decimal places
    
                          Example:
                             AMOUNT NR text ValNumericValue:S,9,2
    
                      ValDateValue:option,&mask
                          Where:
                                &option    - ‘long’ for long date format ( date with ccyy)
                                           - ‘short’ for short date format (date with yy only)
                          Example:
                             BIRTHDATE NR text ValDateValue:SHORT,MMDDCCYY
    
    
                      ValQuotedString:&minlength,&maxlength
                          Where:
                                &minlength  - the minimum string length (exclude quotes)
                                &maxlength  - the maximum string length (exclude quotes)
    
                          Example:
                             STREET NR text ValQuotedString:1,32
          
  4. The key values declaration following the properties declaration. The key values declaration lists the default values for each key.
            Syntax:
    
               <KEYVALUES>
                  &key &value1.... &value-n
                     .
                     .
                  &key &value1.... &value-n
               </KEYVALUES>
                      Where: &key   - the name of the key
                             &value - one or more default values
          

    Coding hints:

    • Use the ‘+’ sign for continuation.
    • Alpanumeric values must be enclosed in quotes.
    • Numeric values are coded without quotes.
    • Values must pass the properties function tests.
    • Note: When the editor express shell is opened for edit, the default values can be selected as shown on the right side of the screen, or the allowed values can be typed in.
      The default values listed are those defined in the <KEYVALUES>. . . </KEYVALUES> declarations.

  5. The macro END statement at the bottom of the shell.
            Syntax:
    
               SEND
             
Back to Contents

Running editor express program on z/OS

To run an editor express programs on z/OS, you must edit the shell and use ‘Submit’ button on the editor screen toolbar to send it to z/OS JES2/JES3 reader. Submit presents a JCL dialog to choose the JCL to run. Clicking ‘Submit’ button on the JCL dialog combines the Key-Value parameters with the JCL. It generates Easytrieve Plus %COPY statement with its arguments and submits the JOB.

Example of editor express shell and JCL are provided in the eztPrograms directory supplied with the product follows:

Editor express shell:

          DEMOSHL1.ezx

JCL to run the shell:

          DEMOSHL1.jcl

Keep in mind:

a. The macro represented by editor express shell must be located in a PDS and pointed to via //PANDD statement.
b. The JCL file must be in a directory on your PC (presumably in the same directory where editor express shell resides).
c. The JCL must be a valid IBM Migration Utility Link and Go job. The SYSIN must be the last statement followed by ‘/*’ and ‘//’ statements.

Example:

      //TESTJOB JOB . . .
       .
       .
      //FSYTPA00.SYSIN DD *
      /*
      //
   

d. Submit inserts editor express macro statement following the SYSIN and sends it to z/OS JES2/JES3 reader. This is equivalent to submitting an IMU Link and Go job from PDS. Example of inserted macro statement (red lines are the inserted lines):

      //TESTJOB JOB . . .
        .
        .
      //FSYTPA00.SYSIN DD *
      %DEMOSHL1 +
      COMPANY (10) +
      BRANCH (010) +
      OFFICER (‘AAAA‘) +
      LIMIT (200) +
      TITLE1 (‘DEMO EXPRESS PROGRAM‘)
      * end of express build **
      /*
      //
  
** End of document **

Back to Contents