History

Some years ago (1986) a friend of mine, Mr Steve Carr created a system for maintaining ISPF tables using CLISTS and a table-of-tables concept, based in turn on the Telephone Directory example from the ISPF Dialogue Services manual.

I used and extended those CLISTs over time quite considerably, until a period when I worked on a collection of systems at Nat West. At that time, I generalized the concept to make the tables editor both less fragile and also far more capable of handling large volumes of records - by basing the table storage on VSAM datasets rather than ISPF tables.

The GTE product is a result of that long history.

Introduction

GTE provides a mechanism for groups of users to maintain and view user-defined tables suitable for use within ISPF applications. Batch systems can also access and update these data structures.

User applications, written principally using ISPF panels, TSO CLISTs or REXX EXECs, and SKELS, provide flexible extensible mechanisms for a wide range of problems based on tables of related tables of data. Useful systems can be constructed with minimal tailoring of three panels.

Sample applications for source management, work stack management, etc are available for download as starter sets or samples.

This end is achieved by use of the following mechanisms:

Features

  • minimal coding required to create new table structures
  • standard ISPF services used for display, edit and validation
  • ordering, subsetting and generation facilities easily established
  • no CLIST or REXX coding required for basic functions
  • multiple simultaneous users supported
  • regression detection supported
  • allows multiple views of the same datal using alternate panel definitions

    Editor

    Main processing flow

    The following diagram describes the basic program flow. Although detailed it does describe the function accurately. Some portions of the processing are skipped dependent on options set at program invocation.

    The GTE

    The GTE editor is invoked by the following ISPF command:

    SELECT PGM(GTELEDT0) PARM(control.ds(member) options)

    or by equivalent syntax in a selection panel.

    Here,

  • the GTELEDIT program has to reside in the ISPLLIB concatenation in a PDSE dataset;
  • The control.ds(member) holds information about the table or group of tables to be edited.
  • options provides some additional hints as to the type of environment in which the user wants the editor started

    When the system is invoked, it:-

    1. reads and validates the input parameter file, building internal control structures which it will use during program execution.
    2. It then writes information to a TRACE dataset defined in the parameter file. This dataset can be useful when building the table from scratch as the essential parameters (recordsize, key size and location) are written here during initialization.
    3. The program then displays a panel the name of which is defined in the parameter file and which is referred to as the coarse selection panel. This panel allows the user to subset the VSAM file to a smaller range than the whole file: this is good where the whole file is very large and the portion being worked on is much smaller. The use of '*' in the fields which can have any values allows the user to select all, some or none of the existing file.
    4. Next the VSAM file is opened, positioned (if possible) and read until the end of the generic key derived from the fields identified in the parameter file as participating in the coarse select is exhausted (this could be the whole file). Each record read is loaded into an ISPF table held in memory. All work is performed against this in-core table, but each time a row is added or modified the changed data record is written to the VSAM file.
    5. The in-core table is now sorted according to the sort order specified in the parameter file. This order does not need to be the same as the order for the VSAM KSDS.
    6. The table edit process then occurs. The table is displayed with the TBDISPL service, and then for each row that is modified a panel referred to as the Edit Rules panel is driven. Typically this panel is operated in non-display mode. This panel checks fields for validity and consistency, and throws an error if the rules are broken. This panel can also initiate further ISPF functions based on the line command entered, and on completion returns the result of the edit in a field called &ACTION. This field specifies the action the GTELEDT0 program is to perform: this must be one of ADD, PUT, DEL or DLC.
    7. The program will update in accord with the requested action, and then update the VSAM file. During the VSAM update, each record modified is checked that there has been no other updater in the interim. If this has happened, the program displays the message 'REGRESSION' and the data fields for that record are refreshed from the VSAM dataset. The user's edits to that row are lost.
    8. The user may issue a primary command. These are performed AFTER any line commands. See below for details of the possible line commands.
    9. . When the user presses PF3 (END) on the table display panel, the ISPF table is deleted, and control passes back to the coarse selection criteria in order than the user can either press PF3 again, and exit, or start over with a different subset.

      See the above diagram for a visual appreciation of this logic.

    Primary commands

    The primary commands are issued at the COMMAND prompt on the list (ED) panel(s). These commands control various global functions of the editor. They are implemented within GRTLEDIT.

    These commands include

    Primary command Description of command
    BROWSE Browse the last tailored member
    EDIT Edit the last tailored member.

    This is useful for tailored output (for example, JCL) which needs tweaking.

    F string Searches all rows of the table for the specified string. Each row which is found to have a match has the SELECTION field set to Y.
    FLIP VAR(variablename) For every row, if the variable is Y, set it to N, and if the variable is N then set it to Y.
    GEN Display the custom GN panel to initiate a file tailoring operation. The GN panel collects parameters and returns the name of a member to pass through file tailoring. The output from this operation is placed into &SYSUID..A.CNTL(&SYSUID).
    LFT Display next panel leftwards
    RGT Move to next screen rightwards
    SEL Set the SELECTION indicator on all displayed lines in table.
    SET A custom panel is displayed for the user to put new values in. These values are then set in every displayed row to the new value.

    All fields should be shown on this panel. The default value for each variable should be '*'. If the value '*' is left on the panel, the variable will not be altered in any row.

    It isn't valid to put key fields on this panel. There is no facility for altering values stored in key fields.

    SORT This command throws up a custom panel which allows the user to select a sort order.

    The custom panel actually returns to the program the field list to sort on, held in the variable SORTSPEC.

    UNSEL Clear the selection indicator on all displayed lines in incore-table.
    TN Table Next - moves display to next table within this ring
    TP Table Previous - moves display to previous table within this ring
    T tablename Selects the named table. If the table name is omitted, a panel of possible tables is displayed.

    Line Commands

    These are the line action commands placed beside each row of the displayed table. They are implemented by logic within the ER panel, or within the GTELEDT0 program. They usually include
    s
    select selects a row for inspection of all its data values
    i
    insert

    create a new row in the table: all values are defaulted and the user gets to specify all fields made available on the edit rules panel

    d
    delete deletes the current record from the incore table and the VSAM dataset
    r
    replicate replicate - create a duplicate

     

    and may include many other functions.

    To add another function:-

    1. Choose a new action command. This will be a string which is interpreted by the ER panel, and which will cause that panel to start an ISPF process under this panel using variables from the current row to provide parameters for the process.

    For example, the command can drive a CLIST or another program.

    2. Write and debug the function being added (CLIST or program, or panel).

    3. Add the action string to the TRANS(TRUNC statement in the ER panel, and invoke the command to start your new service.

    That's all you have to do! If the subcommand will update fields in this row you also need to set ACTION to UPD in the ER panel, but this is not usual.

    There are some supplied CLISTs which make this coding easy. The CLISTs which I have found useful in the past include

     
    CLIST Purpose
    GTECED Invokes the ISPF editor on the specified dataset and/or member
    GTECBR Invokes ISPF browse on the specified dataset and/or member
    GTECSKEL Will tailor and submit a job or jobs, using an optional panel for additional parameters. See the CLIST itself for the parameter specification. Facilities for submitting the job on another system are also implemented using FTP for the transport.
    GTESUB Submit a job on this or another system Using FTP as transport.

    Application Construction

    Overview

    The following discussion covers the construction of a new ISPF Table-based application, and includes a collection of notes, and memos on what can go wrong.

    1. List the fields you will need in the table.

    You don't need the action string field defined in the table.

    You will need a selection field as well. This is used for search logic and subsetting. It doesn't get put on the VSAM file: so its value is held per table editor session. It is used to handle the result of search logic, and can be used for other functions within your application.

    For each field, you need to determine its size and whether it's a key field. Fields can also be generated.

    2. Determine the key fields for the table

    The editor requires key fields in normal operation. You can have one or more fields making up the key; however any row added must have a unique key. The editing system works best with just one key, although more are possible.

    If the key field is going to appear on the coarse selection panel, which is quite likely, you need to ensure that the name of the field does not begin with a K. This is because when the coarse selection panel is defined, it works in terms of variables which have the same name as table fields except that the first letter is replaced with a K.

    3. Create the parameter file for the table.

    To do this, you copy the standard parameter file and modify it to suit. There are suggestions in the parameter file as to what everything does - however this is expanded below.

    4. Next create the SL (coarse selection), ED (table display) and ER (edit rules) panels. These panels are best created from a skeleton or an existing panel. The names of these panels can be anything, but I usually keep the suffix in line with this documentation.

    On the ED panel go the data items which are most useful when viewing the table as a set of rows. You need the &LCMD action character; but the &NEWNAME field is optional, and can be omitted easily if screen real-estate is at a premium.

    You are NOT limited to a single screen row per table row.

    Updates performed directly onto this screen will still drive the ER panel, and the associated edits will be performed: the ER will only display if there are problems.

    See the section on the ED and ER panels for more details.

    5. Then create any special facilities required. These are driven by the SR (sort specification selection), GN (generate), ST (set) and SC (scan/subset) panels. See the sections relating to each of these constructs for more details.

    6. Next, create a linkage from an existing panel to the new table. This is done within a menu panel by including a line within a SELECT statement similar to

    optn,'PGM(GRTLEDIT) PARM(parameterfile(member))'

    7. Check all panels using option =7.2 for syntax errors.

    8. Start the tables editor. It will crash virtually immediately but before it burns it will print diagnostics saying that the input file doesn't exist. It also (obligingly) informs you how large to make the key and how large the record is. Using this information, construct a KSDS for data storage.

    Main Features - details

    Setting up the parameter file for the editor

    The parameter file is divided into several sections. These are {names}, {fields}, {commands}, {tables}, {generate} and {skels}. In addition you can put in comment lines (start these with '*').

    Each section of the input file is processed in turn. The {names} section defines various names and options required for the program to process. The {fields} section defines the field names and sizes within the application. These sizes are only used when storing data onto the VSAM file or retrieving same ISPF doesn't case about field lengths particularly. {skels} is used to identify the SKELS libraries required to generate any output from the table: the list of libraries is catenated before file tailoring. {commands} provides a way of extending the ISPF application by adding new command words. {tables} allows the root parameter file to point to the various component table parameter files. {generate} provides controls for managing automatic generation of keys.

    {names} section

    The names must start in column 1, and be in upper case.

    The values must start in column 10 and are space terminated. The rest of the line is ignored (you can put comments in it).

    Variable Form of data
    SYSTRACE dataset name with 1st %s imbedded where you want the userid substituted, and second where you want the &ZSCREEN variable inserted (allows two edits in progress at one time).
    WORKFILE Name of the main VSAM cluster
    MAJENQ Major name for the ENQ (max 8 bytes)
    MINENQ Minor name for the ENQ (max 255 bytes)
    TABLE table name and %s. The %s gets replaced by the session number (&ZSCREEN)
    PTABNX This parameter details TWO panel names: one in col 10, and the second in col 20. The first panel name is the main ISPF table display panel (an ED panel), and the second is an ER panel.

    This keyword can be repeated, and for each repetition a new ED/ER pair is built, and connected up in a ring. When the command RGT is issued, the pair used to display and edit move around the ring (eventually coming back to the first pair). The command LFT moves back the other way around the ring.

    This allows various views of the data to be shown. The ER panel is likely to be the same panel in each case, but need not be (this could be a way of implementing more line commands).

    PFINSUB The fine-subsetting display (the SC panel), invoked with the SCAN command. All variables should be set to '*' by default: the user gets to specify those variables which are to drive the subset.
    PSETVAR The value setting panel invoked with the SET command or NONE
    PSRTSEL The name of the panel to drive when the user types SORT on the command line, or NONE. The value returned by this panel (SORTSPEC) is used to TBSORT the table.
    PGENSEL The generate panel for requesting file-tailoring (the GN panel), or NONE.
    ORDER The sort parameters used to specify the initial order of the table for display purposes, or NONE
    FTOUT The name of the PDS/PDSE dataset to be used for file-tailoring output. %s in this name gets replaced by the userid.
    STATS ON or OFF. If ON, a display of memory allocation information is done just before program exit to allow the writer to check all memory has been deallocated.

    {fields} section

    Each row of the [fields] section defines a separate field, and the parameters are positional. Information following the last significant position is ignored, and this area can be used for comments.

    Value Position Description
    'FIELD'

    1

    Identifies the type of the row
    field name

    10

    Name of this field. Must be in uppercase, and 1-8 bytes long with first character a letter.
    field length

    19

    Length of field (decimal, expressed in characters)
    Type of field

    24

    Must be:

    N for a normal field
    D for a date field (must be eight bytes)
    T for a time field (must be eight bytes)
    U for the userid field (must be eight bytes)
    S for a selection field (must be one byte)
    G for a generated field

    key field indicator

    26

    Y/N. Y means this is a portion of the VSAM key.

    Key fields must be specified one after the so that the key field for VSAM is contiguous.

    Coarse selection field

    28

    Y/N. Y means this field is set on the 'ST' panel and is used for coarse selection when the editor starts.

    Coarse selection fields MUST be part of the key, and to be useful for generic locate should start at the beginning of the key. If the first field of the key is not on the coarse selection panel, the whole VSAM dataset has to be passed at startup.

    {skels} section

    Each line in this section has the keyword ISPSLIB in column 1 and the name of the library to catenate next starting in column 10. Don't use ' marks around the library name as this will confuse the system. Libraries are catenated in the order specified.

    {commands} section

    This section is a way of implementing more primary commands. Each line following the {commands} introducer is a command word in column 1 (use uppercase) followed by the body of a SELECT CMD() statement starting in column 10. Don't code anything in the way of comments on this line - the whole line is passed, along with any parameters following the command word on the command line.

    This mechanism allows you to add complex logic to the system to perform 'whole table' operations: basically anything can go.

    {generate} section

    This section defines how the system generates values for keys. There can be multiple key generators - and in this case a portion of the key is used to choose the generator. In addition you need to designate a non-key field in the layout used to hold the next number to use.

    To support this feature, two keywords are used in the {generate} section: NUMBER and GENERATE.

  • NUMBER identifies a field in the layout and outside the key area to hold the next free number. This must be at least four bytes long. The number is stored in binary and starts at 1.
    NUMBER    fffffff F qqqqqqq
    
    NUMBER    fffffff V vvvvvvvvvvvv
     ffffffff - field name
     qqqqqqqq - field name
     vvvvvvvvvvv - value
    
  • GENERATE has two possible forms: use one or the other, not both. The F form identifies a key field to use as an identifier for this generator. The V field provides a value to use as the key of the generator record.
    GENERATE  ffffffff
    
     ffffffff - field name
    

    For example, suppose your key is made up of two fields, a group field and a sequence number: GRP and SEQ. These might be defined as

    GRP       2    N Y Y Y
    
    SEQ       5    N Y Y Y
    
    ...
    
    OTHER     4    N N N N
    

    In this case the generator section would look like:

    {generate}
    *23456789012345678901234...
    NUMBER   GRP      F GRP
    GENERATE OTHER
    


    Each different GRP used would have a separate counter created. These counters contain spaces in the SEQ area, and in the OTHER field for these records there is a four byte binary counter. Even if you delete all records for a specific group the counter would remain, once created.

    The logic in the ER panel also changes. The user can't enter a sequence number - it is generated - but only when the record is added. Any value in the sequence number field is lost. The ER panel doesn't need to validate the SEQ either as the field will be initialized before writing.

    Panels, and panel logic

    ED panels

    This is the first thing the user sees when starting one of these generalized table editor applications. The ED panels are the basic workbench for the application; and provides facilities for data entry, command issuance, and reporting.

    Ensure that the &LCMD field and the &NEWNAME field are set to &Z in the )INIT section.

    Do not include a )PROC section as this will break the whole facility.

    Use the GRTPSKED panel as a starting point. You need to add those fields which you want to see on each line of the screen corresponding to each row of the table. You should also document on this panel those action characters your application will handle on each line. You can put modifiable fields directly onto this panel - the ER panel will be driven for each modified row anyway.

    The first ED panel will always be shown first, and often there will only be one ED/ER pair.

    ER panels

    The ER panel is the most complicated piece of coding, especially as it seems to do everything without any actual flow. Start from one that is going, and be prepared to test your changes carefully. Always check the panel syntax using 7.2, and remember that changing any panel or skeleton requires the cache to be cleared before the new definition will come into play. To do this, option 7.2 is invaluable.

    Even if you use more than one ED panel, you likely will only want one ER panel. This is valid, andif you do have more than one ER panel remember to include consistent defaults for new records and so forth on all of them. More than one ER panel allows you to implement different sets of line commands in different contexts - all very clever but likely to come unstuck.

    Here is a sample edit rules panel GTEPSKER:

    )ATTR DEFAULT(%+_)                                                    
        % TYPE(TEXT) INTENS(HIGH)                                         
        + TYPE(TEXT) INTENS(LOW)                                          
        _ TYPE(INPUT) INTENS(HIGH) CAPS(ON) JUST(LEFT)                    
        \ TYPE(INPUT) INTENS(LOW) CAPS(OFF) JUST(LEFT)                    
    )BODY EXPAND()                                                      
    %---  VALIDATE/DISPLAY ROW OF &TABNAME  ---                       
    %COMMAND ===>_ZCMD                                                    
    +KEY             %===>_KEY1    +                                      
    +FIELD1          %===>_FIELD1                                    +    
    +FIELD2          %===>_Z+                                             
    )INIT                                                                 
      .ZVARS ='(FIELD2)'                                                  
      &LCMD = TRUNC(&LCMD,1)                                              
      IF (&YREPEAT = &Z)                                                  
         &YREPEAT = .TRAIL                                                
      IF (&LCMD=R,r)                                                      
         &KEY1 = &NEWNAME                                                 
      IF (&LCMD=I,i)                                                      
         /* set defaults in this section for new records */               
         &KEY1=&NEWNAME                                                   
         &FIELD1 = &Z                                                     
         &FIELD2 = &Z                                                     
      IF (&LCMD = S,s)                                                   
         .RESP = ENTER                                                    
    )PROC                                                                 
      IF (&YREPEAT = &Z)                                                 
         IF (&YSCANON = Y)/* if filtering in effect! */                   
            IF (&LCMD = D,d)                                              
               &YREPEAT = &Z                                              
      IF (&LCMD = D,d)           /* Do validation if NOT deleting */     
        /* validate fields in row here */                                 
        VER(&KEY1,NB)                                                     
        VER(&FIELD1,NB)                                                   
        VER(&FIELD2,NB,LIST,A,B)                                          
        /* handle action commands here */                                 
      &ZSEL = &Z                                             
      IF (&LCMD=actionchars)                                 
         &ZSEL=TRANS(&LCMD                                   
        act,'select'                                         
         &LCMD=&Z                                            
      /* compute action to pass back to CLIST */             
      /* nothing below here should need editing */           
      &ACTION=TRANS(&LCMD                                    
                 I,'ADD'                                     
                 i,'ADD'                                     
                 R,'ADD'                                     
                 r,'ADD'                                     
                 S,'PUT'                                     
                 s,'PUT'                                     
                 D,'DEL'                                     
                 d,'DEL'                                     
                 *,'PUT')                                    
     VPUT (ACTION &YTABVRS) ASIS                             
     VPUT (ACTION &YTABKEY) ASIS                             
     VPUT (YSCANON YREPEAT &YTABEXT) ASIS                    
     IF (.MSG = &Z)                                          
         IF (&ZSEL=&Z)                                       
            .RESP=END                                        
    )END                                                     

    The above model covers a multitude of problems. Let's dissect these one by one -

    1. The body of the panel should present every field in the table, with (by convention), key fields first. I usually try to get as much help 'on screen' to the right of each field.

    2. .ZVARS is the most tricky item to get right - purely mechanical and the cause of the single largest number of errors.

    3. If the user has chosen the line command I or i, the idea is that a row is being inserted. Each of the table fields needs to be initialized in this circumstances. Note that an ISPF panel IF controls the execution of all statements indented further than the controlling IF.

    4. The fragment of code dealing with LCMD = S or s is the non-display panel bit. All other line commands attempt to run this panel in non-display mode: they will present the panel only if validation errors result. However an S command will display the fields for the row. You may wish to vary the action character which does this, and it would probably work fine. However I have never tested this.

    5. The )PROC section starts with field validation. Validate anything and everything, if you wish.

    6. After field validation, the logic to handle line commands is performed.

     

    OR panel

    The OR panel allows the user to choose an order for the panel. This facility is optional - if you don't want to provide this facility, code NONE in the parameter file for the panel specification.

    The OR panel is a simple menu panel returning the sort order to use in the variable &SORTSPEC. The skeleton panel GRTPSKSR is very suitable as a starting point for creating this panel. Here it is:

    )ATTR DEFAULT(%+_)                                                      
          /*  % TYPE(TEXT) INTENS(HIGH)      defaults displayed for      */ 
          /*  + TYPE(TEXT) INTENS(LOW)       information only            */ 
          /*  _ TYPE(INPUT) INTENS(HIGH) CAPS(ON) JUST(LEFT)             */ 
      $ TYPE(INPUT) INTENS(LOW) PAD(_)    /* input field padded with '_' */ 
      ! TYPE(INPUT) INTENS(LOW) PAD(' ')  /* input field padded with ' ' */ 
    )BODY expand()                                                        
    %---  RE-ORDER TABLE  ---                                           
    %COMMAND ===>_ZCMD                                                      
    %                                                                       
    +   This panel sorts the table into a required order                    
    +                                                                       
    +  %1 XXX       +- Order by...                                          
    +  %2 YYY       +- Order by                                             
    +  %3 ZZZ       +- Order by                                             
    +                                                                       
    +                                                                       
    +   Make selection and press%ENTER+to perform sort. Press%END+to cancel.
    +                                                                       
    )INIT                                                                   
      .HELP = GTEPSORY           /* Insert name of tutorial panel    */     
    )PROC                                                                   
      &OPTION=TRUNC(&ZCMD,'.')                                              
      &SORTSPEC=TRANS(&OPTION                                               
                  1,'fld1,C,A'                                              
                  2,'fld2,C,A,fld1,C,A,fld3,C,A'                            
                  3,'fld4,C,A')                                             
      VPUT (SORTSPEC) SHARED                                                
    )END                                                                          
    

    SC panel

    The SC panel allows the user to specify a set of values in fields to select a subset of the rows of the table for display.

    The following skeleton is useful when showing the format of the panel definition; but in practice it is better to copy the ER panel, and then modify that.

    )ATTR DEFAULT(%+_)                                                      
        % TYPE(TEXT) INTENS(HIGH)                                           
        + TYPE(TEXT) INTENS(LOW)                                            
        _ TYPE(INPUT) INTENS(HIGH) CAPS(ON) JUST(LEFT)                      
        \ TYPE(INPUT) INTENS(LOW) CAPS(OFF) JUST(LEFT)                      
    )BODY EXPAND()                                                        
    %---  SUBSET/FILTER &YTABNAM  ---                                   
    %COMMAND ===>_ZCMD                                                      
    +KEY             %===>_KEY1    +                                        
    +FIELD1          %===>_FIELD1                                    +      
    +FIELD2          %===>_Z+                                               
    )INIT                                                                   
      /* copy the ER member to create the SC but use this to help */        
      .ZVARS ='(FIELD2)'                                                    
      &KEY1= '*'                                                            
      &FIELD1 = '*'                                                         
      &FIELD2 = '*'                                                         
    )PROC                                                                   
     IF (&KEY1 = &Z)                                                        
        &KEY1 = ' *'       /* Field longer than one char, do blank scan */  
     IF (&FIELD1 = &Z)                                                      
        &FIELD1 = ' *'     /* Field longer than one char, do blank scan */  
     IF (&FIELD2 = &Z)                                                      
        &FIELD2 = '*'      /* Field only one char, do blank scan */         
                                                                            
     /* OK, if scan criteria has been specified we need to know in order */ 
     /*  that we can prevent the user falling foul of the feature of     */ 
     /*  ISPF that return a non-displayed row after a TBSKIP.            */ 
                                                                            
     &YSCANON = Y                                                           
                                                                            
     IF (&KEY1 = '*')                                                       
      IF (&FIELD1 = '*')                                                    
       IF (&FIELD2 = '*')                                                   
        &YSCANON = N             /* fields untouched, no scan! */           
                                                                         
     VPUT (YSCANON &YTABVR1 &YTABVR2 &YTABVR3 &YTABKEY &YTABEXT) ASIS    
                                                                         
    )END                                                                                                                                         
    

    GN panel

    The GN panel is used to provide a stream generation, job generation and/or reporting function for the table.

    This facility is optional - code NONE for the related panel name in the parameter file to disable this facility.

    This panel relies heavily on the ISPF File Tailoring services FTOPEN, FTINCL and FTCLOSE: however the user doesn't need to use these services directly. All the user has to create to use the facility is to key up one or more ISPF skeletons.

    An ISPF skeleton is a text member held in an SKELS library (a library on the ISPSLIB concatenation). It contains text, which is just copied, and ISPF variables which get replaced by the corresponding value. Commands can also be imbedded into the stream to further control ISPF File Tailoring processing. See the table below for details of the commands which can be inserted into such a skeleton.

     

  • Feature Syntax (simplified) Description
    Conditional Text selection )SEL Start selection block
      )ENDSEL End selection block
    Iterate over a table )DOT tabname Start iteration

    Note, the table name is specified in the parameter file(s), and can optionally include the logical screen ID. If the logical screen ID is being used, you must code &ZSCREEN. at the point in the name where the %s is present in the table name for GRTLEDIT.

      )ENDDOT End of iterated block
    Set a variable )SET var = value Set variable
    Emit blank line )BL  
    Imbed a file )IM member [NT] [OPT] member is the name of the member to include.

    NT is put in where tailoring is NOT to be done (contents just get copied).

    OPT is put where is is not mandatory that the member exist.

    Tabstops )TB n1 n2 n3 ... Set tabstops at columns
    Change default special characters )DEFAULT ijklmno Sets different default characters for this include member. Using this option can select non-standard values for the <|> construct, allowing the user to produce documentation suitable for HTML browsers.

    The GN panel (skeleton) looks like this:

    )ATTR DEFAULT(%+_)                                                      
          /*  % TYPE(TEXT) INTENS(HIGH)      defaults displayed for      */ 
          /*  + TYPE(TEXT) INTENS(LOW)       information only            */ 
          /*  _ TYPE(INPUT) INTENS(HIGH) CAPS(ON) JUST(LEFT)             */ 
      ! TYPE(INPUT) INTENS(LOW) PAD(' ')  /* input field padded with ' ' */ 
    )BODY EXPAND()                                                        
    %---  GENERATE DATA FROM &YTABNAME  ---                             
    %COMMAND ===>_ZCMD                                                      
    %                                                                       
    +   WHICH TYPE OF OUTPUT DO YOU WANT TO GENERATE?                       
    +                                                                       
    +  %1+-type1  - Build ...                                               
    +  %2+-type2  - Build ...                                               
    +  %3+-type3  - Build ...                                               
    +                                                                       
    + Get any other parms you might need for the generation from panel      
    + If you are building jobs, these lines are often very useful:-         
    %JOB CARD:                                                              
    % %===>_BJC1                                                            
    % %===>_BJC2                                                            
    % %===>_BJC3                                                            
    % %===>_BJC4                                                            
    +                                                                       
    +  Press%ENTER+to begin tailoring, or%END+to abort this function.       
    )INIT                                                                   
      VGET (BJC1 BJC2 BJC3 BJC4) ASIS                                       
    )PROC                                                                   
      VER (&ZCMD,NB,LIST,1,2,3...)                                          
      VPUT (BJC1 BJC2 BJC3 BJC4) PROFILE                                    
      VPUT (BJC1 BJC2 BJC3 BJC4)                                            
      &FTMEMBER = TRANS(&ZCMD,                                              
                       1,xxxSSK01   <- you have to build these in the       
                       2,xxxSSK02      skels library...                     
                       3,xxxSSK03      etc...also remove these comments     
                       *,*)                                                 
      VPUT (FTMEMBER) SHARED                                                
    )END                                                                    
    

    Each option maps to a skeleton name for the editor to file tailor. After file tailoring, the resultant skeleton can be used as a text file, or submitted using theEDIT;SUB command sequence. EDIT and BROWSE commands in the command line will start the appropriate service against the most recently produced file-tailored member.

    Some Basic Services

    The following services are implemented via CLISTs and SKELS and so forth. There is nothing mystical about them but they are convenient ways of invoking certain facilities which tend to be heavily used in ISPF applications.

    The BROWSE service

  • Attribute Notes
    Name GTECBR
    Fixed parms target

    Name of the dataset to browse, with no quotes around it.

    Variable parms DEBUG(YES/NO)

    Helpful when you are trying to get things working

      LIB1(name)... LIB4(name)

    Used to specify a concatenation of datasets to browse

      MEMBER(memname)

    Optional but gives a way of picking up a member from a concatenation.

    The Edit Service

  • Attribute Notes
    Name GTECED
    Fixed parms target

    Name of the dataset to edit, with no quotes around it.

    Variable parms DEBUG(YES/NO)

    Helpful when you are trying to get things working

      LIB1(name)... LIB4(name)

    Used to specify a concatenation of datasets to browse

      MEMBER(memname)

    Optional but gives a way of picking up a member from a concatenation.

    The Tailor a SKEL service

  • Attribute Notes
    Name GTECSKEL
    Fixed parms target

    Member name to start FTINCL service against

    PanelID

    Name of panel to display prior to file-tailoring, to pick up additional parameters for process.

    If the value NOPANEL is coded, the panel display is omitted.

    Description Opens the specified member for file tailoring, and puts the output out to userid.MISC.SKOUT(userid).
    Variable parms DEBUG(YES/NO)

    Helpful when you are trying to get things working

      FAST(Y/N)

    FAST(Y) means that once the job has been tailored, not backend panel to choose browse, edit, submit or enter SDSF will be displayed.

    FAST(N) will cause this back end dialogue to run.

    The SUBMIT service

  • Attribute Notes
    Name GTECSUB
    Description Submit the named entity and then issued a JOB SUBMITTED ISPF message.
    Fixed parms target

    Name of the dataset to edit, with no quotes around it.

    Variable parms

    SITE(siteid)
    This command indicates the JCL is to be submitted on another system. If the sideid is NONE, the job is submitted on this system. If it is ASK, a panel is displayed to fetch the site to use.


    DEBUG(YES/NO)

    Helpful when you are trying to get things working

    Batch interface

    A crucial requirement is being able to unload and reload data into the VSAM dataset based on partial keys; and update portions of rows. This requirement is met by the 'Batch Interface'. The batch interface allows the editor to run under batch, and receive commands from a SYSIN stream to ADD, UPDate, DELete or ADU - Add/Update records with values specified in the input stream. This interface uses the same integrity rules as the online system, and can be set to checkpoint at low or high frequency. Thus trickle updates from some external source can easily intermingle with online interactive use with little apparent degradation.

    <jobcard>
    //*                                                                 
    //STEP100  EXEC PGM=GTELEDT0,PARM='*DD:P B NS NT'                                     
    //STEPLIB  DD   DISP=SHR,DSN=BCC.BASE.LOAD                          
    //P        DD   DISP=SHR,DSN=BCC.BASE.PARM(WRKTPARM)                
    //SYSPRINT DD   SYSOUT=*                                            
    //STDOUT   DD   SYSOUT=*                                            
    //SYSOUT   DD   SYSOUT=*                                            
    //CEEPRINT DD   SYSOUT=*                                            
    //CEEDUMP  DD   SYSOUT=*                                            
    //SYSABEND DD   SYSOUT=*                                            
    //SYSIN    DD   *                                                   
    TAB "table"                                                         
    LST key("value")                                                    
    UPD key1("value1") ...                                              
        field1("fvalue1") field2("fvalue2")...                          
    ...                                                                 
    NEW key1("value") WRRANK("value")                                   
    ...                                                                 
    DEL key1("value1")...                                               
    /*                                                                  
    

    The PARM is exactly the same as in any other context - except the 'B' tells GTELEDT0 that the program is running in Batch mode. The DD:P parameter says the input dataset is under control of the JCL. Verbs implemented include


  • TAB to switch currrent table - only when not in single table mode
  • UPD to update a record. The KEY and a subset of DATA values must be specified
  • ADD to ADD a new record. Any fields omitted are initialised to spaces - this may not be the desired outcome.
  • DEL deletes a record. The fields participating in the key must be fully specified
  • LST to dump a record for inspection in the same format as used for input

    Components and Installation

    The installation is easy. Download the various components, link edit the supplied object modules, and start using the facility. You may also want a starter application to provide a good place to begin from. The standard installation includes a very simple sample system but this requires tailoring before use.