z/OS Service Package: X2018269


SMP/E SYSMOD:
Component:
Operating System:
Publish Date:
APAR & Description:

RS34003
SELCOPYi
z/OS
2018/09/27

IQ004549:

New Feature: PDSE Library Member Generation Support

In z/OS 2.1, PDSE version 2 libraries were introduced which include support for member generations (via the MAXGENS library data set allocation attribute).

When changes are made to member data belonging to a PDSE V2 library that supports generations, a new generation is automatically created for the member when the data is saved. The image of the member data before the change occurred is referenced as relative generation number -1 and the relative generation number of each previous image of the member data is decremented by 1.

IBM publication "z/OS DFSMS Using Data Sets" provides information on PDSE version 2 libraries and member generations.


*** Member Generation Reference ***

When processing a PDSE version 2 library which supports mamber generations, SELCOPYi panel fields and primary commands that identify a library mamber name now also support reference to an individual member generation.

To reference an individual member generation, SELCOPYi supports specification of an absolute or relative generation number following the member name with a single separating "." (dot/period) between. A member generation may be identified by its relative or absolute generation number.

e.g.

Using a relative generation number...

    EDIT   NBJ.GEN25.XEC(APESUB.-5)
    BROWSE NBJ.SELCI.SDO(DB2FUNC1.-1)


Using an absolute generation number...

    E    NBJ.GEN25.XEC(APESUB.56)
    VIEW NBJ.SELCI.SDO(DB2FUNC1.7)


Note: blank characters are not permitted within a member generation specification.

The base (or prime) generation may be identified as generation 0. In SELCOPYi, generation 0 is treated as the relative generation value of the base generation. Although not yet assigned to the base member generation within the PDSE structure, SELCOPYi attributes a positive absolute generation value to the base generation. This value corresponds to the next absolute number in the member generation sequence.

SELCOPYi allows reference to the base generation via its relative (0) or absolute (SELCOPYi attributed) generation number. Alternatively, the generation specification may simply be omitted as referencing the member name only will identify the base generation.

e.g.

Where 12 previous generations have been created for member DB2FUNC1, the base generation may be referenced in SELCOPYi as DB2FUNC1.13. The following are equivalent:

    VIEW    NBJ.SELCI.SDO(DB2FUNC1.13)
    VIEW    NBJ.SELCI.SDO(DB2FUNC1.0)
    VIEW    NBJ.SELCI.SDO(DB2FUNC1)



*** Generic Member Generation Reference ***

SELCOPYi panel fields and commands that support specification of a member name mask to identify multiple library members now also support specification of a member generation mask. This mask may identify multiple generations of one or more member names.

A member generation mask is the same as a single member generation but with either:

  1. A null or wildcard character "*" specified in place of the generation number. This indicates that all generations are to be selected.

  2. A relational operator inserted between the "." (dot/period) and the (absolute or relative) generation number. This indicates that only generation numbers that satisfy the numeric comparison will be selected.

    Supported relational operators are:

    Operator Description
    = Equal.
    <=    ¬=    !=    <> Not equal.
    > Greater than.
    <= Less than or equal.
    < Less than.
    >= Greater than or equal.


Member generations that satisfy both the member mask and generation mask will be selected.

e.g.

The following are equivalent and will open a library list of member generations window to dispay all generations of all members:

    LL    NBJ.JCLLIB(*.*)
    LL    NBJ.JCLLIB(*.)
    LL    NBJ.JCLLIB(*.<*)


To list all member generations whose member name begins with CALL and whose absolute generation number is greater than or equal to 12:

    LL    NBJ.JCLLIB(CALL*.>=12)

To erase all generations except the base (i.e. relative generation 0):

    ERASE NBJ.JCLLIB(NBJX.<0)

To list all member generations whose member name begins with SS and whose relative generation number is -1:

    LL    NBJ.JCLLIB(SS*.-1)

List all member generations whose entries match one of the member and generation masks:

    LL    NBJ.JCLLIB(SS*.>=-3  ADA%%%%.>=-5  CBL*.0)


*** Utility Support for Member Generations ***

Support for PDSE version 2 library, member generation and member generation mask specification has been implemented for SELCOPYi as follows:


** PDSE V2 Library Data Set Information **

Data Set Information panel updated to display organisation type PDSE V2 for PDSE version 2 library data sets. (Primary command DSI or INFO, List window prefix command "I").


** PDSE V2 Library Data Set Allocation **

Allocate NonVSAM dialog window updated to support allocation of a new PDSE version 2 library, optionally with member generations.

The dialog now includes field entries "Version>" (PDSE library version 1 or 2) and "Member Generations>" (PDSE 2 MAXGENS value). It may be opened using primary command ALLOC with no parameters or opened automatically by FSU or FCOPY when output is to a new DSN. Note that command ALLOC already supports parameters DSNTYPE(LIBRARY,2) and MAXGENS.


** PDSE V2 Library Member Generation List **

Library Member Generations list window introduced to display an entry for each generation that matches a supplied member and member generation mask. The list has the same columns as a Library Member list but with additional GenA and GenR columns to display absolute and relative generation numbers respectively.

The list may be opened via the following:

  1. Execute the LL (ListLibrary) primary command with a member generation or member generation mask parameter specification.

    i.e. LL <libname>( <mbrmask>.<genmask> ... )

  2. Execute prefix area command "G" against an entry in a VTOC, Library Member or Dataset type list. All generations will be displayed for the PDSE library or member name list entry.



** Member Generation Copy **

Member generation masks may be used to select individual generations of one or more members to be copied from a PDSE V2 library to a target file. This target file may be an HFS/ZFS file, a VSAM, sequential or GDG dataset, a PDS or PDSE library or an individual library member.

Copy of member generations may be performed via the following methods:

  1. Execute FCOPY primary command with a member generation mask source data object specification.

    e.g.

        FCOPY NBJ.JCLLIB(*.*)  NBJ.JCLLIB.COPY

  2. Open the File Copy panel and enter a member generation mask in the Member Mask field.

  3. Execute prefix area command "C" against entries in a Library Member Generations list.


Copy of multiple member generations will be in ascending alphabetical order of selected member name and ascending order of absolute generation number. Thus, the oldest generation of a member is copied first.

The format of the copied data is dependent upon the organisation of the target data object as follows:

  1. If copy is to a single target dataset, library member or HFS/ZFS file then the records in each selected member generation will be appended to the target file with optional member delimiter lines.

  2. If copy is to a library data set which does *not* support member generations, then the target library will contain individual members with names matching those in the member generation mask. Each of these members will contain only data records from the newest member generation to match the member generation mask.

  3. If copy is to a library data set which supports member generations, then the target library will contain an individual member generation for each generation selected by the member generation mask.

    Note that generation numbers in the target library may not match those selected from the source library by the generation mask. The internal management of generation numbers by the target PDSE will determine the assignment of the next generation number used and cannot be controlled by application programs.

    Since the target library supports generations, each copy to an existing member name will create a new generation for that member in the target library. Because each generation is copied in ascending order, the generation hierarchy is preserved in the target library.

    This type of copy is especially useful if a library needs to be redefined with a greater (or fewer) number of generations.


If a member generation mask has been supplied or entries have been selected for copy from a Library Member Generation list, then the SELECT command in the FCOPY or Library Member Copy panel will display a table of library member generations instead of library members.


** Member Generation Delete **

Delete (Erase) may be performed for a single generation or on multiple member generations that match a member generation mask.

Erase of member generations may be performed via the following methods:
  1. Execute ERASE primary command with a member generation or member generation mask specification.

    e.g.

    To erase a relative generation -5 of member SSCALL:

        ERASE  NBJ.JCLLIB(SSCALL.-5)

    To erase all generations of member SSREL other than the base member:

        ERASE  NBJ.JCLLIB(SSREL.<0)

    To erase generations of all members that are older than relative generation -3:

        ERASE  NBJ.JCLLIB(*.<-3)

  2. Execute prefix area command "D" (or "K" if no confirmation prompt is required) against entries in a Library Member Generations list. Like library member delete, by default a prompt for each delete of a member generation will be displayed.

  3. Execute prefix area command "D" (or "K") against entries in a Library Member list (see note below).


Note: When delete is performed without a member generation specification on a member of a PDSE library that supports generations, then a prompt to delete all generations of the member will be displayed.


** Member Generation Recovery **

A specific member generation may be recovered so that it becomes the base member (generation 0). The relative generation number of each generation is decremented by 1 so that the previous base member becomes generation -1, etc.

Recovery of a member generation may be performed via the following methods:

  1. Execute RECOVER primary command with an explicit member generation specification.

    e.g.

        RECOVER  NBJ.JCLLIB(SSCALL.-1)

  2. Enter "RECOVER" in the prefix command area against the non-base generation entry to be recovered in a Library Member Generations list.



** Member Generation Search **

Member generation masks are supported as input to the FSU (File Search and Update) utility. Output to a member generation is not valid.

Data in member generations selected by the mask may be filtered, searched, updated, copied and remapped as supported for library members.

The File Search and Update utility using member generation input may be started via the following methods:

  1. Execute FSU primary command with a member generation mask on the INPUT parameter specification.

    e.g.

    To report records in all generations of all members that contain the string "Lev":

        FSU INPUT("NBJ.JCLLIB(*.*)")  FIND(C'Lev')

  2. Open the FSU (Basic or Extended) File Search panel views and enter a member generation mask in the Member Mask field.



** Member Generation Compare **

Member generations may be used as one or both of the file specifications used as input to the COMPFILE primary command Compare File utility.

e.g.

    COMPFILE" NBJ.JCLLIB(SSREL) NBJ.JCLLIB(SSREL.-1)


** Member Generation Text Edit/View **

The Text Editor may be used to EDIT or VIEW (i.e. edit read-only) a member generation.

The absolute and relative generation numbers of the member generation in the focus text edit window view is displayed in the window title bar.

e.g.     G=10(-1)

Edit and view of a member generation may be started via the following methods:

  1. Execute the EDIT or VIEW primary command with a member generation or member generation mask specification. If a mask is specified, a list of matching generation entries are displayed in which one entry may be selected for use by the edit/view operation.

    e.g.

        EDIT   NBJ.JCLLIB(SSCALL.-5)
        VIEW   NBJ.JCLLIB(SSREP.23)
        E      NBJ.JCLLIB(SSREP)       (Gen=0)

  2. Select (position the cursor and hit Enter) an entry from a Library Member Generations list.

  3. Execute prefix area command "E" or "V" against an entry in a Library Member Generations list.


Edit of a member generation places an exclusive SYSEDIT ENQ on the member name and so it is not possible to open for output more than 1 generation of the same member at the same time.

When saving changes to a member generation, the prevailing value of the GENSAVE option dictates whether a new generation is created (NEWGEN), the current generation is updated (NOGEN) or a popup window is opened to prompt the user for the action to be taken on save (PROMPT). PROMPT is the default.

"SAVE ( NOGEN" or "SAVE ( NEWGEN" may be executed to specifically save the data back to the current generation or to create a new generation respectively.

If a fileid is also specified on the SAVE, then the NOGEN/NEWGEN parameter is ignored. If fileid is a member of a PDSE supporting generations, then NEWGEN is used.


** Member Generation Data Edit/View **

If the library member contains data records that are mapped by a defined language structure (SELCOPYi SDO, COBOL, PL1, HLASM, SYMNAMES), then the Data Editor may be used to EDIT or BROWSE member generation data with or without the structure.

Like the Text Editor, the absolute and relative generation numbers are displayed in the Data Editor window view title bar.

Data Edit and browse of a member generation may be started by executing SD EDIT or BROWSE primary command with a member generation or member generation mask specification. If a mask is specified, a list of matching generation entries are displayed in which one entry may be selected for use by the edit/browse operation.

e.g.

    SD EDIT NBJ.DATA(EMP.-2)     USING NBJ.SDO(EMPMAP)
    BROWSE  NBJ.JCLLIB(SSREP.-1)


Saving changes to member generation data obeys the GENSAVE parameter as for the Text Editor. "SAVE NOGEN" and "SAVE NEWGEN" will override the value set for this option as appropriate.

IQ005044:

New Feature: MVS System Management Facilities (SMF) Utilities

SELCOPYi includes utilities to process records generated by MVS System Management Facilities. SMF collects and records system and job related information which gets written to the allocated SMF dataset (SYS1.MANx) or log stream.

Each SMF record is assigned a distinct record type number and has a well defined (though often complex) structure. The structure of each SMF record type is comprised of a number of sections that can occur many times, only once or not at all within the data of a record of the record type.

SELCOPYi SMF utilities treat each section of data as a record segment and will use Structured Data Edit (SDE) environment segmented record processing to interpret the data. (See Primary/Secondary Segments below.)

SELCOPYi is distributed with a library of members (hlq.SZZSDIST.SMFMAP) that each map an SMF record type (or record sub-type) using SELCOPYi's own Structured Data (SDE) environment CREATE STRUCTURE syntax. These members are used to generate the SELCOPYi structure used to map SMF record data.


SELCOPYi SMF utilities are:

SMF Record BROWSE:

Browse formatted SMF records directly from an on-line SMF data set or from SMF DUMP (IFASMFDL or IFASMFDP) output in a Data Editor window view. All standard Data Editor functionality for browsed data is available (e.g. table and/or single record display, FIND, EXCLUDE, ONLY, etc.)

SMF records may be browsed using either of the following data formatting options:

  1. A basic non-segmented layout that displays columns for fields mapped by the header/self-defining section only. All remaining data is unformatted.
  2. A full segmented layout that displays columns for all fields mapped by all segment (section) structures identified within the record's data.


SMF Record Extract:

Using selection criteria, extract required SMF records directly from an on-line SMF data set or from one or more SMF DUMP archives to another data set.

SMF Record Reporting:

Using field selection and other report definition syntax, generate a text report of SMF record data.


*** Primary/Secondary Segments ***

A feature of many SMF record-types is that they may include a number of different repeating group structures, each representing a map of repeating areas of data within the record.

A single instance of a repeating group structure may occur zero or more times within the record data to which it applies. If more than one occurrence of a particular repeating group structure exists, then each occurrence will occupy an area of the record that immediately follows the previous occurrence. All occurrences of a repeating group are typically addressed by what IBM refer to as "triplet" fields. Each triplet field comprise the following 3 consecutive fields:

  1. A field (xxxOF) containing the offset within the base record to the first occurrence of the repeating group.

  2. A field (xxxLN) containing the length of one instance of the repeating group.

  3. A field (xxxON) containing the number of occurrences of the repeating group within the current record. (May be zero.)


SELCOPYi treats a repeating group as having a different record-type to that of the rest of the SMF record. More accurately, they are treated as separate "Secondary" segments of the SMF record that are subordinate to a single "Base" or "Primary" segment. Secondary segments are also assigned to areas of the SMF record that are not repeating but have a distinct sub-structure based on an SMF record sub-type (e.g. the sub-types for SMF records 14 and 15).

When browsing an SMF dataset in SELCOPYi, the initial "Table" view of the file will display all SMF record segment types at once. The user may choose whether secondary segments are initially displayed with each segment occupying a new line of the display, or as "shadowed" lines (one for each group of segments having the same structure.)


*** Layout Definition Source Text ***

The structure layout for each SMF record type supported by SELCOPYi is supplied in a member of the distributed library, "hlq.SZZSDIST.SMFMAP", where hlq is the product install library high level qualifier. Note that SELCOPYi SDE option SMFMAPLIB may be used to display the DSN of the active SMFMAP library (i.e. "SD QUERY SMFMAPLIB").

Each member of this library corresponds to an individual SMF record layout or SMF record subtype layout as documented in publication: "MVS System Management\n Facilities (SMF)"

The member names are "Tnnn" where nnn is a 3 character number corresponding to the SMF record type number to which the member applies (e.g. "T014" contains the layout for SMF record type 14). For members that apply specifically to an individual SMF record number and subtype, the member name format is "TnnnSTmm" where nnn is as already described and mm is a 2 character number corresponding to the SMF record subtype number (e.g. "T099ST05" contains the layout for SMF record type 99 subtype 5).

Member "TNNN" is a generic form of the SMF record layout and can apply to any SMF record. It is used specifically to map SMF record types for which no layout has been defined. The "BASENAMS" member contains a refernce to every SMF record-type layout name supported by SELCOPYi to date.

The format used to define each layout is SELCOPYi's CREATE STRUCTURE for Field Definition syntax which, unlike COBOL or PL1 programming languages, supports repeating group segments defined by a triplet field.

The names assigned by SELCOPYi to each SMF record field may be established by browsing the appropriate record source layout member.

Members will be added to the SMFMAP library as further SELCOPYi layouts of SMF record types are defined. These will be implemented as SMP/E PTF SYSMODs but will also be published as they become available via the CBL FTP server.

IQ005091,IQ005086, IQ005073, IQ005072, IQ005071, IQ005066, IQ005052, IQ005045:

Text Editor Fixes and Enhancements:

Correct loop that occurred when the TFLOW command (line command TF) was executed with a flow column greater than the left boundary but less than the indent of the 2nd line of data (the paragraph indent).

Additional verification processing included so that SET HILITE AUTO correctly identifies text in the edit view as COBOL source.

Allow changes made to text in a read-only Text Edit view to be saved to another data set using the REPLACE (Interface ISPF) primary command.

Update cursor positioning following execution of "D" (Delete) or "M" (Move) type prefix area (line) commands so that it is placed at the start of the prefix area on the relevent line, not at the start of the text.

Fixes to Text Edit interpretation and execution of REXX macros that use the ISPF Edit macro commands. These involve updates to SELCOPYi distributed edit macros CUT, JEM, JP, LLX and RENUM.

ALLOC primary command updated to support "DSN(*)" to allocate to the TSO terminal.

Correct PTF in error (RS33007) which prevented a change to the LRECL of a new dataset (SET LRECL n) following execution of SET UNDOING ON/OFF.

Correct ACTION (PF16) operation where text always displayed at command prompt.

IQ005081, IQ005070, IQ005065, IQ005062, IQ005061, IQ005060, IQ005059, IQ005056, IQ005046, IQ005041, IQ005037, IQ005040, IQ005039:

SDE Data Editor Fixes and Enhancements:

Correct CUT which included garbage End-of-File marker in data copied to the clipboard when "C*" line command used to mark text.

SET STRUCTURE OFF for a library DSN and member name has been updated so that if no structure association table entry exists for the specified member name but one exists for the library DSN, then the entry for the library DSN will be removed.

For use in SDE Data Edit macros, support has been introduced for the following:


Primary Command:

FILEIO

Open, close, read and write data to a set data. FILEIO may be used by SDEAMAIN (SELCOPYi batch) and by SELCOPYi VTAM where the TSO/E EXECIO REXX extension is not available.

Syntax:

     >-+ FILEIO +- ddname +- OPENRead ------------+-><
       |        |         |                       |
       + FIO ---+         +- OPENWrite -----------+
                          |                       |
                          +- CLOSE  --------------+
                          |                       |
                          +- READ   rexxvar ------+
                          |                       |
                          +- WRITE  record-text --+
                          |                       |
                          +- WRITEX record-hexstr +
                          |                       |
                          +- SREAD  stem -+-------+
                          |               |       |
                          |               + nrecs +
                          |                       |
                          +- SWRITE stem ---------+



SET/QUERY/EXTRACT options:

BLANKIFZERO | BLANKWHENZERO | BIZ | BWZ

Controls display of blanks instead of zeroes (0) in a field of numeric data type.

EXCLUSions LOGICAL | PHYSICAL

For Segmented Records only, this option controls whether EXCLUDE, ONLY, FIND, ALL, MORE or LESS operations include or exclude individual segments (LOGICAL) or all segments that comprise the record (PHYSICAL).

EXTRACT only options:

FVALUEQP

Same as FVALUE but names are part qualified but exclude the Record-type mapping name.

FVALUEQF

Same as FVALUE but names are fully qualified and include the Record-type mapping name


For use in SDEAMAIN (SELCOPYi batch) execution, support has been introduced for the following primary commands:

TASK

Start a program in a new sub-task as documented for interactive use.

PRINTS

Output a line of text to DDName SDEPRINT with an ASA character in column 1. This complements SDEAMAIN printed output (messages, etc.) which is also written to SDEPRINT by default.


Restriction on processing Extended Compressible data sets has been removed. Compressed data sets may now be used on EDIT (except in-place edit) and BROWSE and as input/output on utilities FCOPY, FSU, COMPFILE, etc.


For BROWSE of a shared KSDS data set, output an error message if record load fails due to updates to the data performed by another process.


For BROWSE of a VSAM data set defined as SHR 2, 3 or 4, allow the operation to continue if the data set has been opened for output by another process then written to but never closed. Previously, the BROWSE operation would report the data set as being empty.


Correct the numeric value displayed for a field defined with data type BINTEGER.


Implement documented data types:

    DATE(DECIMAL)  - X'ccyy,dddF'
    DATE(BINARY)   - X'yyyy,00mm,00dd'
    DATE(CATALOG)  - X'yydd,dFcc'
    DATE(VTOC)     - X'yydddd'
   
    TIME(DECIMAL)  - X'HHMM,SSTH'
    TIME(BINARY)   - X'nnnn,nnnn'
          (1/100th of a second since midnight)

IQ005068, IQ005067, IQ005038, IQ005036, IQ005054, IQ005050, IQ005048, IQ005080:

Fixes and Enhancements to SELCOPYi utilities.

FCOPY and FSU:

Utility panels corrected so that HFS RECFM, LRECL and EOL field value combinations are always respected. Previously, these field values were used only if the input file was ZFS/HFS. Therefore, output to a ZFS/HFS file from a non-HFS source would write the records using the default format.

Correct ZZSD009E Invalid Operand which is returned when FSU is run in batch with NOREPORT option (PRINTREPORT is default). PRINTREPORT is now ignored if NOREPORT is specified.

Use of Concatenated Library Directory (&ddname) input on the FSU panel will now generate the corresponding JCL DD statement for ddname when a batch job is generated.

If FSU option CONTEXT is specified and the FSU report is printed (default for batch execution), then the zT column is no longer suppressed. Furthermore, the zT column entries "L" and "T", which represent leading and trailing context lines respectively, will be replaced with blank entries. This has the benefit of making non-context lines within the plain text report (where colour highlighting is not possible) more easily identifiable. Note that non-context report lines have zT column entries "H", "B" or "A").


XMLGEN and JSONGEN:

SET/QUERY/EXTRACT global option NAMECASE introduced to control whether or not tag names generated from the record-type field names by XMLGEN and JSONGEN are upper cased.

TAGUPPER/NOTAGUPPER parameters are also supported on XMLGEN and JSONGEN primary commands to override the value for option NAMECASE.


COMPFILE:

Correct error whereby an OFFSET value set in the record-type definition within the SDO structure was not being properly applied to the record data.


SELCOPY Debug:

Correct 0C4 Program Check that may occur when the debug session is started from the JCL job steps panel.


Create DB2 Structure:

Avoid potential errors from occurring when no output SDO structure dataset name specified in the utility panel.

IQ005078, IQ005069, IQ005064, IQ005058, IQ005057:

General SELCOPYi system fixes:

Prevent assignment of the SMP/E SELCOPYi install target CBLE library DSN to the User INI variable Edit.UserMacros. This could occur when settings panel exited and System INI variables Edit.DistMacros and Edit.SiteMacros have not been assigned values.

Ensure SELCOPYi execution CBLATRAC trace output is generated when the TRACE primary command is passed to the SELCOPYi program via a parameter string. This may be achieved by by passing an argument string to the SELCOPYI startup REXX procedure.

e.g.

    SELCOPYI    TRACE(CBLATRAC,CBL.SI.TRACE,PRINT)

For utility panels that generate JCL jobs suitable for submission to batch, the EXEC statement has been updated so REGION is no longer included.

Previously, REGION=0M was used which had the undesirable affect of unnecessarily loading potentially very large target files into storage before the utility processing started.

Correct potential 0C4 progrm checks that occurred when obtaining information from Link Pack Area (LPA) control blocks on z/OS systems with extended length LPDEs. This would most commonly occur when SYSLPA command was executed to obtain a list of modules in the LPA.