1 PDS2PDS V3.02 THE PDS to PDS Comparison/Maintenance Utility August 15, 1999 Created by Michael A. Newell, WB4HUC http://wb4huc.home.texas.net/pds2pds wb4huc@texas.net 1 DISCLAIMER: This software is offered free of charge and contains no warranties or guarantees of any kind. The author makes no claims, express or implied, about the suitability of this software for any purpose. The author cannot be held responsible for any damage done through the use of this software. This software should be thoroughly tested in a non-production environment before using it on important or critical files. 1 1 Overview Introduction PDS2PDS is an MVS REXX/SPF Dialog Manager utility that will display two partitioned datasets side by side on the screen and let you perform different operations on them. With PDS2PDS you can, among other things: o copy a member or members from one pds to the other o move a member or members from one pds to the other o edit a memberor members in either pds o delete a member or members from either pds o rename a member or members in either pds o browse a member or members in either pds This document explains in detail how PDS2PDS works, all of its various features, how to install it, and how to use it. This Document ------------------------------------------------------------ Contains Chapter Title Page ------------------------------------------------------------ 1 Overview 1-1 2 Installation 2-1 3 How to Use 3-1 4 Adding New Commands 4-1 ------------------------------------------------------------ ------------------------------------------------------------------------------- $INSTALL.TXT Overview August 15, 1999 1-1 1 2 Installation Introduction This chapter explains how to unpack the PDS2PDS.ZIP file and install the individual files into your TSO/ISPF environment. This Chapter ------------------------------------------------------------ Contains Section Page ------------------------------------------------------------ Unpacking PDS2PDS.ZIP 2-1 Uploading the Files to the Mainframe via FTP 2-2 Restoring the Datasets with the RECEIVE Command 2-2 Compiling the COBOL programs 2-4 Customizing PDS2PDS 2-4 List of Members 2-6 List of Stored Variables 2-7 ------------------------------------------------------------ Unpacking PDS2PDS is delivered in MS-DOS/PC-DOS format ZIP files. PDS2PDS.ZIP Use WinZip or something compatible to unpack these zip files and create the following binary files and text files. ------------------------------------------------------------ ZIP File Contains Description ------------------------------------------------------------ PDS2PDS.ZIP $HISTORY.TXT Change history of PDS2PDS P2PREXX.XMI REXX Execs P2PPANLS.XMI ISPF Panels P2PMSGS.XMI ISPF Message File Member P2PSRCE.XMI COBOL Source Programs P2PALLOC.REX REXX Installation Exec P2PRECV.REX REXX Installation Exec COMPCOB2.TXT Compile JCL for COBOL II COMPCMVS.TXT Compile JCL for COBOL for MVS/VM P2PCMVSL.ZIP P2PCMVSL.XMI COBOL load modules compiled for COBOL for MVS and VM P2PCOB2L.ZIP P2PCOB2L.XMI COBOL load modules compiled for COBOL II ------------------------------------------------------------ ------------------------------------------------------------------------------- $INSTALL.TXT Installation August 15, 1999 2-1 1 2 Installation Uploading the Once you have unpacked the files from PDS2PDS.ZIP you need to Files to the transfer the .XMI files to MVS. This should be done using a Mainframe via binary FTP transfer method. FTP You can give these files any name you want on MVS. You can use either the COBOL II or the COBOL for MVS and VM versions of the load modules. You don't need both. After you transfer the .XMI files to MVS they should each have the following attributes: DSORG=PS, RECFM=FB, LRECL=80, BLKSIZE=3120 The easiest way to ensure that these files have the proper attributes is to preallocate them then transfer the PC files to the preallocated MVS files. Included with the PDS2PDS.ZIP file is a REXX exec, P2PALLOC, that can preallocate these files for you. Follow the comments in the exec to modify it for your use. Restoring the Once the .XMI files are on MVS you need to run the TSO Datasets with RECEIVE command to load each of these files back into a the RECEIVE partitioned dataset. Here are the attributes for each of the Command datasets: ------------------------------------------------------------- File Attributes ------------------------------------------------------------- P2PREXX.XMI RECFM=FB LRECL=80 BLKSIZE=23440 UNIT=3380 10 tracks 5 directory blocks 26 members P2PPANLS.XMI RECFM=FB LRECL=80 BLKSIZE=23440 UNIT=3380 6 tracks 11 directory blocks 65 members P2PMSGS.XMI RECFM=FB LRECL=80 BLKSIZE=23440 UNIT=3380 1 track 1 directory block 1 member P2PSRCE.XMI RECFM=U LRECL=0 BLKSIZE=32760 UNIT=3380 5 tracks 1 directory block 2 members P2PCOB2L.XMI RECFM=U LRECL=0 BLKSIZE=32760 UNIT=3380 17 tracks 1 directory block 2 members P2PCMVSL.XMI RECFM=U LRECL=0 BLKSIZE=32760 UNIT=3380 17 tracks 1 directory block 2 members ------------------------------------------------------------- ------------------------------------------------------------------------------- $INSTALL.TXT Installation August 15, 1999 2-2 1 2 Installation You do not have to preallocate the partitioned datasets that will be output from the RECEIVE command. The RECEIVE command will create them for you. Included in the PDS2PDS.ZIP file is a REXX exec, P2PRECV, that can execute the RECEIVE command for you. Follow the comments in the exec to modify it for your use. If you would rather execute the RECEIVE command yourself, here's how: ------------------------------------------------------------- Step Description ------------------------------------------------------------- 1 Issue the command: TSO RECEIVE INDATASET('P2PREXX.XMI') At the prompt: "INMR906A ENTER RESTORE PARAMETERS OR 'DELETE' OR 'END' +" reply: DA('DATA.SET.NAME') VOLUME(volid) SPACE(20 0) TRACKS where 'data.set.name' is the name of the pds where you want the members to go. The VOLUME parameter is optional but might be needed if the default volumes in your shop are work volumes. ------------------------------------------------------------- Repeat this sequence once for each .XMI file, remembering that you only need one of the COBOL load libraries. Once the partitioned datasets are created you need to copy: o the REXX execs to your TSO REXX library (SYSPROC or SYSEXEC) o the ISPF panels to your ISPF panel library (ISPPLIB) o the ISPF message member to your ISPF message library (ISPMLIB) o the COBOL load modules to your TSO load library (ISPLLIB) ------------------------------------------------------------------------------- $INSTALL.TXT Installation August 15, 1999 2-3 1 2 Installation Compiling the If you didn't download the COBOL load modules from the COBOL Programs web site you can just compile the source code using the supplied JCL members. COMPCOB2 will compile the programs using COBOL II and COMPCMVS will compile the programs using COBOL for MVS and VM. You will have to modify the JCL members with your own job card, system libraries, etc. before you can run them. Customizing Before you execute PDS2PDS for the first time you should take PDS2PDS a look at REXX exec P2PCUSTM. In this exec are some variables whose values you may want to change. These variables are: ------------------------------------------------------------- Variable Description ------------------------------------------------------------- p2puntu These variables are used in TSO ALLOCATE commands p2puntw executed by PDS2PDS. The value of these variables p2punts reflects the names used in the UNIT parm of the ALLOCATE commands. In PDS2PDS there are three categories of allocated files: 1) The left- and right-side dataset names entered on the dataset name panel. If the VOLSER field is entered on this panel then both the UNIT and VOLUME parameters are used in the ALLOCATE command for these files. Set variable P2PUNTU to the proper value in your shop for existing uncataloged files. If the VOLSER field is not entered in the dataset name panel the ALLOCATE statement does not use either the VOLUME or UNIT parameters. 2) Temporary sequential work files are created by PDS2PDS to hold member name and stats data that are processed by the two COBOL programs. These new temporary files are allocated before the COBOL programs are called and then deleted when the COBOL programs are finished executing. Set variable P2PUNTW to the proper value in your shop for temporary work files. These files can be put on work volumes, virtual I/O volumes, etc. ------------------------------------------------------------------------------- $INSTALL.TXT Installation August 15, 1999 2-4 1 2 Installation 3) The SuperCe statements datasets created by the P2PLSUP and P2PGSUP REXX execs are permanent cataloged files. If these files already exist when the SC line or global commands are issued they are deleted and reallocated. Set variable P2PUNTS to the proper value in your shop for permanent cataloged files. If the same esoteric or unit name is used in your shop for all these different types of files then you can set all three variables to the same value. The default for these variables is 'SYSDA'. p2pgstmt Change this variable to the desired dataset name for the SuperCe statements dataset created by REXX exec P2PGSUP. This exec executes the SC Global command. You can assign a fully- or partially- qualified dataset name for this variable. The default value for this variable is 'P2PGSUP.STMT'. p2plstmt Change this variable to the desired dataset name for the SuperCe statements dataset created by REXX exec P2PLSUP. This exec executes the SC Line command. You can assign a fully- or partially- qualified dataset name for this variable. The default value for this variable is 'P2PLSUP.STMT'. ------------------------------------------------------------- You should also make sure that the appropriate COBOL runtime libraries are available to your TSO session. Your systems programming staff can tell you which libraries you need. Just let them know if you're using the COBOL II or COBOL for MVS and VM versions of the programs. ------------------------------------------------------------------------------- $INSTALL.TXT Installation August 15, 1999 2-5 1 2 Installation List of Members Here is a list of members that should have been installed with the PDS2PDS application. REXX Execs (from P2PREXX.XMI) PDS2PDS P2PCUSTM P2PDSNP P2PDSNS P2PGALL P2PGBRW P2PGCMP P2PGCPY P2PGDEL P2PGEDT P2PGINF P2PGMOV P2PGREN P2PGSUP P2PGTTL P2PLALL P2PLBRW P2PLCPY P2PLDEL P2PLEDT P2PLMOV P2PLREN P2PLSUP P2PMBRL P2PSTLF P2PSTRT ISPF Panels (from P2PPANLS.XMI) P2PDSNP P2PGALL P2PGBRW P2PGCPY P2PGDEL P2PGEDT P2PGINF P2PGMOV P2PGREN P2PGTTL P2PLALL P2PLCPY P2PLDEL P2PLMOV P2PLREN P2PMBRL P2PPMSG P2P00000 P2P10000 P2P11000 P2P11010 P2P11020 P2P12000 P2P12010 P2P12020 P2P13000 P2P13010 P2P13020 P2P13030 P2P13040 P2P13050 P2P13060 P2P13070 P2P13080 P2P20000 P2P21000 P2P21010 P2P21020 P2P21030 P2P21040 P2P21050 P2P22000 P2P23000 P2P23010 P2P23020 P2P23020 P2P23040 P2P23050 P2P23060 P2P23070 P2P23080 P2P23090 P2P23100 P2P23110 P2P23120 P2P24000 P2P24010 P2P24020 P2P24030 P2P24040 P2P24050 P2P24060 P2P24070 P2P24080 P2P24090 ISPF Message Library Members (from P2PMSGS.XMI) PTPM00 COBOL Load Modules (from either P2PCOB2L.XMI or P2PCMVSL.XMI) READDIR P2PBTBL ------------------------------------------------------------------------------- $INSTALL.TXT Installation August 15, 1999 2-6 1 2 Installation List of Stored The following is a list of variable names that PDS2PDS Variables stores in the user's ISPF Profile Pool. These variables are stored with the 'VPUT (...) PROFILE' Dialog Service and are retrieved with the 'VGET (...) PROFILE' Dialog Service. If these same variable names are stored in the profile pool by other software they will be overwritten by PDS2PDS. Here are the variable names: CNFRML CNFRMR DISPLINE DSNL DSNR DTL1 DTL2 DTL3 DTL4 DTL5 DTL6 DTL7 HDL HDR MASK MASKOPTL MASKOPTR MBRLEFT MBRRITE NAMEDIFF NAMESAME OLDRLEFT OLDRRITE P2PGSTMT P2PLSTMT P2PUNTS P2PUNTU P2PUNTW P2PVERNO STATDIFF STATSAME UNIQLEFT UNIQRITE VOLIDL VOLIDR The values of the following ISPF System variables are changed temporarily during the execution of the SuperCe (SC) Global and Line commands: SCENWFL SCEODFL SCECMLN SCESSFL ------------------------------------------------------------------------------- $INSTALL.TXT Installation August 15, 1999 2-7 1 3 How to Use Introduction This chapter will explain the various input fields on the two PDS2PDS screens, the Dataset Name and Display Options panel and the Member List panel. This Chapter ------------------------------------------------------------ Contains Section Page ------------------------------------------------------------ Starting PDS2PDS 3-1 The Dataset Name and Display Options panel 3-1 The Member List panel 3-4 Order of Command Processing 3-6 Primary Commands 3-7 ------------------------------------------------------------ Starting To start PDS2PDS just enter TSO PDS2PDS on the ISPF PDS2PDS command line. The Dataset Name and Member Display Options panel should appear. You could also define a shortcut command like 'P2P' in your ISPF command table. This way you could start PDS2PDS by just entering P2P on the command line. For Help with using PDS2PDS, press PF1 when either the Dataset Name or Member List panel is displayed. This will start a small tutorial that you can follow to learn the various commands and functions of the utility. Placing the cursor on a PDS2PDS input field and pressing PF1 will display a help screen for that field. This works for both the Dataset Name and the Member List panels. The Dataset The fields on this panel are: Name and Display Options Panel The Dataset Name, Member Name/Pattern, Include/Exclude member, and volser fields for the two datasets to be displayed. There are two sets of these fields, one for each partitioned dataset. Below these dataset/member fields are the eight member selection/display option fields. In the Left-Side Dataset Name field you enter the name of the pds whose members will be displayed on the left side of the member list panel. ------------------------------------------------------------------------------- $INSTALL.TXT How to Use August 15, 1999 3-1 1 3 How to Use In the Right-Side Dataset Name field you enter the name of the pds whose members will be displayed on the right side of the member list panel. For either dataset name you can enter either a member name or a member name pattern. The pattern can contain the wildcard characters '*' and '%'. The Include/Exclude field can contain the letters 'I' or 'X'. An 'I' will display ONLY the members that match the member name pattern. An 'X' will display all members EXCEPT those that match the member name pattern. In other words, the members that match the pattern are Excluded from the member list display. If you leave either the member name pattern field or the Include/Exclude field blank all members will be selected. In the VOLSER field you can enter the name of the dasd volume where the dataset resides. You only need to use this field if the dataset is not cataloged. Once the member names are read from the datasets the member display option you pick is applied to decide which of the selected members will be displayed. You can only choose one option at a time. Here are the options and their descriptions: Display only if member names match Matching members in both datasets are displayed. Members that appear only in one dataset or the other are not displayed. Display only if member names and stats match Matching members in both datasets are displayed IF their statistics fields are the same. Members that appear only in one dataset or the other are not displayed. ------------------------------------------------------------------------------- $INSTALL.TXT How to Use August 15, 1999 3-2 1 3 How to Use Display only if member names match but stats don't match Matching members in both datasets are displayed ONLY IF their statistics fields DO NOT match. Members that appear only in one dataset or the other are not displayed. Display only if member names are different This option will show only the member names from each dataset that DO NOT have a matching member in the other dataset. Members that exist in both datasets will not be displayed. Show only the members unique to the left-side dataset This option will show those members that only exist in the left-side dataset. Members that exist in both datasets or members that only exist in the right-side dataset will not be displayed. Show only the members unique to the right-side dataset This option will show those members that only exist in the right-side dataset. Members that exist in both datasets or members that only exist in the left-side dataset will not be displayed. Show members on left that are older than members on right This option will show matching members in both datasets. The members on the left will have date and/or time stamps that are earlier than members on the right. Members that exist only in one dataset or the other will not be displayed. ------------------------------------------------------------------------------- $INSTALL.TXT How to Use August 15, 1999 3-3 1 3 How to Use Show members on right that are older than members on left This option will show matching members in both datasets. The members on the right will have date and/or time stamps that are earlier than members on the left. Members that exist only in one dataset or the other will not be displayed. The Member List After you fill in the Dataset Name panel and press the ENTER Panel key the Member List panel is displayed. This section describes the input fields on the member list panel. Member Display Options Input fields for the same member display options used on the Dataset Name panel are presented on the Member List panel. This allows you to change the options without having to return to the Dataset Name panel. The options are listed in the same order as on the Dataset Name panel. Confirm Line Command This field can contain 'Y', 'N', or blank. If it contains 'Y' then when the C, M, R, or D line commands are executed a pop-up window will be displayed that asks you to press the ENTER key to confirm that you want to execute the command. If the field contains 'N' or blank then no confirmation panel is displayed and the command is executed automatically. Global Command Field This field is where you enter commands that operate on the dataset or on all members of the dataset. This field is located on the field heading line to the left of the 'Name' heading. ------------------------------------------------------------------------------- $INSTALL.TXT How to Use August 15, 1999 3-4 1 3 How to Use The Global commands are: o C - Copy all members to the other pds o M - Move all members to the other pds o R - Rename all members in this pds o D - Delete all members from this pds o E - Edit all members in this pds o B - Browse all members in this pds o V - View all members in this pds o Z - Compress this pds o I - Show dataset information o AL - Show all member statistics o SC - Invoke SuperCe to compare both datasets o TL - Show total number of lines in both datasets The phrase 'all members' means all members that are displayed on the member list panel, not necessarily all members of the dataset. If the member name pattern or display options were used to choose only some of the members for display then only these members will be affected by global commands. Line Command Fields Commands entered in these fields operate only on the member name given next to the field. The line command fields are located next to each member name, on both sides of the member list panel. The Line commands are: o C - Copy this member to the other pds o M - Move this member to the other pds o R - Rename this member in this pds o D - Delete this member from this pds o E - Edit this member in this pds o B - Browse this member of this pds o V - View this member of this pds o AL - Show all member statistics o SC - Invoke SuperCe to compare this member in both datasets For more detailed descriptions of each global and line command press PF1 on either the Dataset Name or Member list panel and view the Help Tutorial for the command, or place the cusor on the Global or Line command field to go directly to the help screens for these fields. ------------------------------------------------------------------------------- $INSTALL.TXT How to Use August 15, 1999 3-5 1 3 How to Use Order of PDS2PDS is designed so that only one type of command is Command executed with each press of the ENTER key. This was done to Processing prevent the various types of commands from conflicting with each other. If you were to enter selections into all of the input fields at once, they would be processed in the following order: o Confirm Line Command o Display Options o Primary Commands o Global Commands o Line Commands The Confirm Line Command fields are checked first even though they are not the first fields on the member list panel. This is because editing of this field is done in the panel definition and not in the REXX exec. In most cases the line command fields are completely blanked out when other input fields are processed and must be re-entered when the higher-priority command has finished. In the case of input errors in the higher-priority fields, a message will be displayed telling you of the error and the line command fields may not be blanked out. Once you have corrected the error and processed the command any non-blank line command fields will be blanked. Some examples of command order processing are: If you enter both a global command and one or more line commands, the global command is executed and all the line command fields will be blanked out. After the global command finishes you must re-enter the line commands. If you enter both the left- and right-side global commands the left-side command will be executed with the first press of the ENTER key. You will have to press the ENTER key again to process the right-side global command. If you select a new display option and enter commands in the global command fields, the display option processing will occur on the first press of the ENTER key. Press the ENTER key again to process the left-side global command; when it finishes press the ENTER key one more time to process the right-side global command. ------------------------------------------------------------------------------- $INSTALL.TXT How to Use August 15, 1999 3-6 1 3 How to Use Primary There are five commands that can be entered on the ISPF Commands command line that control the member list display. They are: The Locate command - this command will find the member name entered and position it to the top of the member list panel. The Refresh command - this command will re-read both datasets and rebuild the member list panel. The Flip command - this command will swap the left and right displays to the opposite side of the screen. The LF command - This will move the display of statistics information one field to the left. The RI command - This will move the display of statistics information one field to the right. Press PF1 on either the Dataset Name or Member List panels and view the Help Tutorial for more detailed information about these primary commands. ------------------------------------------------------------------------------- $INSTALL.TXT How to Use August 15, 1999 3-7 1 4 Adding New Commands Introduction One of the new features of PDS2PDS is the ability to easily add new global or line commands or modify the existing ones. This chapter explains how. This Chapter ------------------------------------------------------------ Contains Section Page ------------------------------------------------------------ Adding Global Commands 4-1 Adding Line Commands 4-6 The Member List Table 4-11 ------------------------------------------------------------ Adding Global In the REXX exec P2PMBRL is a procedure called Commands 'Process_Global_Commands:'. In this procedure is a SELECT...OTHERWISE...END structure. Within this SELECT..OTHERWISE..END structure is a series of WHEN statements. Each of these WHEN statements calls a different internal procedure to execute the global command that was entered. Just add your WHEN statement to the list of existing ones to call your new internal procedure. Within the internal procedure you will call an external routine to perform the global command. After returning from the external subroutine the internal procedure will: o pull any data from the stack that might have been placed there by the external subroutine o check the return code issued by the external subroutine o display any errors that might have been issued by the external subroutine Within your new internal procedure you can call the external subroutine any way you want, via a function call or a CALL statement. Whether or not you pass any arguments to the new external subroutine is entirely up to you and depends upon what your new command is supposed to do. Your new command can execute a REXX exec, a CLIST, an external function written in COBOL, Assembler, or any other supported language. The only thing the new program has to do is follow the conventions for passing back error messages to be displayed. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-1 1 4 Adding New Commands The following is a list of variables passed to and used by the existing external subroutines. These variables are already set at the time the external subroutine calls are made and do not have to be changed. Here are the variable definitions: LR_SW This variable contains 'L' if the global command was entered for the left-side dsn or an 'R' if it was entered for the right-side dsn. TBLNAME This variable contains the name of the ISPF table that holds the member list display. GCMD This variable contains the global command, if entered. CMDL This variable contains the left-side line command, if entered. CMDR This variable contains the right-side line command, if entered. DSNL This variable contains the left-side dataset name. DSNR This variable contains the right-side dataset name. P2PVERNO This variable contains the product name and version number which is displayed in the first line of all the screens. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-2 1 4 Adding New Commands MEMLO This is the number of members contained in the left-side member list. If the external routine adds members to or deletes members from the left-side list it should also change this value to reflect these additions or deletions. If the external subroutine changes MEMLO it should QUEUE MEMLO to the stack so the internal routine within P2PMBRL can PULL it from the stack. This variable is displayed on the member list panel on the same line as the Confirm Line Command field. MEMRO This is the number of members contained in the right-side member list. If the external routine adds members to or deletes members from the right-side list it should also change this value to reflect these additions or deletions. If the external subroutine changes MEMRO it should QUEUE MEMRO to the stack so the internal routine within P2PMBRL can PULL it from the stack. This variable is displayed on the member list panel on the same line as the Confirm Line Command field. VOLIDL This variable contains the name of the DASD volume where the left-side dataset resides. This field is used for uncataloged datasets. VOLIDR This variable contains the name of the DASD volume where the right-side dataset resides. This field is used for uncataloged datasets. NBR_OF_MBRS This variable contains the total number of entries in the ISPF member list table. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-3 1 4 Adding New Commands Of course you're not limited to only these variables, and you may not need to pass any of them at all depending upon what your external routine does. Within your external subroutine you may also retrieve the variables p2punt, p2pgstmt and p2plstmt from the user's profile pool if you need them. These are the custom variables that you may have changed in the P2PCUSTM REXX exec. The current global command external subroutines use the following conventions for passing parameters back to the calling routine: If the return code from the function call is zero, then no messages are issued. If the external subroutine QUEUED any data to the stack the internal procedure may PULL it. If the return code from the function call is 4, then the internal procedure will issue these instructions: 'PARSE PULL p2psmsg' 'PARSE PULL p2plmsg' 'pnl_msg = 'MSG(PTPM009Z)' Variables p2psmsg and p2plmsg are the short and long messages to be displayed by message id PTPM009Z. PTPM009Z is defined in the PTPM00 message library member. When the function call ends with a return code of 4 it usually means that some ISPF Service invoked by the external routine has failed. The external routine will then QUEUE the variables zerrsm and zerrlm to the stack then end with a return code of 4. Upon returning from the external subroutine the internal procedure will PULL zerrsm and zerrlm from the stack and assign their values to p2psmsg and p2plmsg, respectively. If the global command external subroutine ended with a return code of 8 then the internal procedure will issue this instruction: 'PARSE PULL pnl_msg' pnl_msg is used in routine Disp_Mbrl_Panel. It is used to hold the message id of any message that should be displayed after the internal procedure has ended. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-4 1 4 Adding New Commands The value of pnl_msg should be in the form 'MSG(PTPMxxxx)'. PTPMxxxx would be the id of a messaged defined in the PTPM00 message library member. If you create your own new messages be sure to define them in the PTPM00 member. When the external subroutine ends with a return code of 8 it usually means that some error condition was encountered that requires the display of one of the PTPM00 messages. The external routine passes back the message id to be displayed and lets P2PMBRL display it. To get a clearer picture of how all of this works just look at any of the internal procedures called in the SELECT... OTHERWISE...END structure of the Process_Global_Commands: procedure of REXX exec P2PMBRL. Then look at the matching external subroutine to see how they pass parameters and error messages back to the calling routine. The external global command subroutine names all begin with 'P2PG'. You are not limited to using return codes 4 and 8 from your external subroutines. These subroutines can end with any return code you want. The important thing they must do is pass back the zerrsm and zerrlm variables for any ISPF Service that issues error messages, or they must pass back a properly formatted PTPMxxxx message if the external routine itself issues a message. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-5 1 4 Adding New Commands Adding Line In the REXX exec P2PMBRL is a procedure called Commands 'Execute_Line_Command:'. In this procedure is a SELECT...OTHERWISE...END structure. Within this SELECT..OTHERWISE..END structure is a series of WHEN statements. Each of these WHEN statements calls a different internal procedure to execute the line command that was entered. Just add your WHEN statement to the list of existing ones to call your new internal procedure. Within the internal procedure you will call an external routine to perform the line command. After returning from the external subroutine the internal procedure will: o pul any data from the stack that might have been placed there by the external subroutine o check the return code issued by the external subroutine o display any errors that might have been issued by the external subroutine Within your new internal procedure you can call the external subroutine any way you want, via a function call or a CALL statement. Whether or not you pass any arguments to the new external subroutine is entirely up to you and depends upon what your new command is supposed to do. Your new command can execute a REXX exec, a CLIST, an external function written in COBOL, Assembler, or any other supported language. The only thing the new program has to do is follow the conventions for passing back error messages to be displayed. The following is a list of variables passed to and used by the existing external subroutines. These variables are already set at the time the external subroutine calls are made and do not have to be changed. Here are the variable definitions: LR_SW This variable contains 'L' if the global command was entered for the left-side dsn or an 'R' if it was entered for the right-side dsn. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-6 1 4 Adding New Commands TBLNAME This variable contains the name of the ISPF table that holds the member list display. GCMD This variable contains the global command, if entered. CMDL This variable contains the left-side line command, if entered. CMDR This variable contains the right-side line command, if entered. DSNL This variable contains the left-side dataset name. DSNR This variable contains the right-side dataset name. P2PVERNO This variable contains the product name and version number which is displayed in the first line of all the screens. MEMLO This is the number of members contained in the left-side member list. If the external routine adds members to or deletes members from the left-side list it should also change this value to reflect these additions or deletions. If the external subroutine changes MEMLO is should QUEUE MEMLO to the stack so the internal routine within P2PMBRL can PULL it from the stack. This variable is displayed on the member list panel on the same line as the Confirm Line Command field. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-7 1 4 Adding New Commands MEMRO This is the number of members contained in the right-side member list. If the external routine adds members to or deletes members from the right-side list it should also change this value to reflect these additions or deletions. If the external subroutine changes MEMRO is should QUEUE MEMRO to the stack so the internal routine within P2PMBRL can PULL it from the stack. This variable is displayed on the member list panel on the same line as the Confirm Line Command field. VOLIDL This variable contains the name of the DASD volume where the left-side dataset resides. This field is used for uncataloged datasets. VOLIDR This variable contains the name of the DASD volume where the right-side dataset resides. This field is used for uncataloged datasets. NBR_OF_MBRS This variable contains the total number of entries in the ISPF member list table. Of course you're not limited to only these variables, and you may not need to pass any of them at all depending upon what your external routine does. Within your external subroutine you may also retrieve the variables p2punt, p2pgstmt and p2plstmt from the user's profile pool if you need them. These are the custom variables that you may have changed in the P2PCUSTM REXX exec. The current line command external subroutines use the following conventions for passing parameters back to the calling routine: ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-8 1 4 Adding New Commands If the line command external subroutine ends with a return code of 0 then no error messages are issued and no variables are pulled from the stack. If the return code from the function call is 10, then no error messages are issued but there is data in the stack and the internal routine needs to PULL this data from the stack. If the return code from the function call is 4, then the internal procedure will issue these instructions: 'PARSE PULL p2psmsg' 'PARSE PULL p2plmsg' 'pnl_msg = 'MSG(PTPM009Z)' Variables p2psmsg and p2plmsg are the short and long messages to be displayed by message id PTPM009Z. PTPM009Z is defined in the PTPM00 message library member. When the function call ends with a return code of 4 it usually means that some ISPF Service invoked by the external routine has failed. The external routine will then QUEUE the variables zerrsm and zerrlm to the stack then end with a return code of 4. Upon returning from the external subroutine the internal procedure will PULL zerrsm and zerrlm from the stack and assign their values to p2psmsg and p2plmsg respectively. If the line command external subroutine ended with a return code of 8 then the internal procedure will issue this instruction: 'PARSE PULL pnl_msg' pnl_msg is used in routine Disp_Mbrl_Panel. It is used to hold the message id of any message that should be displayed after the internal procedure has ended. The value of pnl_msg should be in the form 'MSG(PTPMxxxx)'. PTPMxxxx would be the id of a messaged defined in the PTPM00 message library member. If you create your own new messages be sure to define them in the PTPM00 member. When the external subroutine ends with a return code of 8 it usually means that some error condition was encountered that requires the display of one of the PTPM00 messages. The external routine passes back the message id to be displayed and lets P2PMBRL display it. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-9 1 4 Adding New Commands When the line command external subroutine ends with a return code of 4 or 8 then the internal procedure will call the Line_Command_Error procedure. The Line_Command_Error procedure sets an error switch, positions the cursor to the correct line of the panel, and clears out the line command process flag. To get a clearer picture of how all of this works just look at any of the internal procedures called in the SELECT... OTHERWISE...END structure of the 'Execute_Line_Command:' procedure of REXX exec P2PMBRL. Then look at the matching external subroutines to see how they pass parameters and error messages back to the calling routine. The external global command subroutine names all begin with 'P2PL'. You are not limited to using return codes 4 and 8 from your external subroutines. These subroutines can end with any return code you want. The important thing they must do is pass back the zerrsm and zerrlm variables for any ISPF Service that issues error messages, or they must pass back a properly formatted PTPMxxxx message if the external routine itself issues a message. They must also call the Line_Command_Error subroutine if any error message is to be displayed. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-10 1 4 Adding New Commands The Member List The member list table is an ISPF table that PDS2PDS creates Table to hold the member list that is displayed on the screen. This table contains all of the fields that make up the member list. When you add members to or remove members from either pds you need to update the member list table to reflect the changes. You manipulate the table through the normal ISPF table services. When you want to change one of the table rows just use the appropriate table service to position to the row and retrieve it. After you've retrieved the desired row, just set the variable names to the new values then delete the old row and add the new row. You can look at any of the P2PGxxx or P2PLxxx REXX execs to see examples of how to manipulate the table. Panel P2PMBRL is used to dispay the member list table. Since you can have up to 99 active PDS2PDS sessions at once the member list table names will be P2PTB001 through P2PTB099. Here are the variables contained in the table: RESL and RESR These fields are display only fields on the member list panel. They are located between the member name and the line command input field. RESL is for the left-side member list and RESR is for the right-side member list. Use this field to show what was done to the member. If the member was edited, put an 'E' in the field. If copied, put a 'C' in the field, etc. MBRL and MBRR These fields are the member names for the left- and right- side member lists, respectively. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-11 1 4 Adding New Commands The STATxL and STATxR fields These fields contain the statistics information for each member. STATxL fields are for the left-side members and STATxR fields are for the right-side members. On the member list display there is only room to show three statistics fields at a time. Each of the STATxL or STATxR variables contains three of these displayed fields. When you issue the LF or RI primary commands PDS2PDS is simply changing which of the STATx variables that it displays. STAT1L and STAT1R contain the vvmm, created, and changed stats fields. STAT2L and STAT2R contain the created, changed, and time stats fields. STAT3L and STAT3R contain the changed, time, and size stats fields. STAT4L and STAT4R contain the time, size, and init stats fields. STAT5L and STAT5R contain the size, init, and mod stats fields. STAT6L and STAT6R contain the init, mod, and user stats fields. STAT7L and STAT7R contain the mod, user, and alias stats fields. To see how the table is initially constructed, look at the P2PBTBL COBOL source program. To see an example of how the stats fields are updated after they're changed, look at REXX execs P2PGEDT and P2PLEDT. To see how the LF and RI primary commands work, look at REXX execs P2PSTLF and P2PSTRT. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-12 1 4 Adding New Commands If you want to see the innards of the table itself, use the Dialog Test functions to set a breakpoint within PDS2PDS so that execution will stop and let you view the table. Enter Dialog Test (ISPF 7). Choose selection 8 (Breakpoints). Enter TBDISPL under Service, enter BEFORE under When, enter PDS2PDS under Function, and enter YES under Active. Press PF3 to return to the main Dialog Test menu. Choose selection 1 (Functions). Under Invoke Command:, on the CMD line, enter PDS2PDS and press the ENTER key. Fill in the Dataset Names and Display Options panel and press ENTER again. Now you should see the Breakpoint Primary Option Panel. At the bottom of this panel is the TBDISPL service and its parameters. On this panel choose selection 4 (Tables). This will take you to the panel where you can view the table. If you only have one active PDS2PDS session the table name should be P2PTB1. Enter this in the Table Name field, and now you can use any of the functions on this panel to view table information and contents. When you're done with the tables panel press PF3 and return to the breakpoints panel. On the breakpoints panel enter 'G' in the command line field to continue execution of PDS2PDS. Eventually, after you have exited PDS2PDS via PF3 or PF4 you will be returned to the Invoke Dialog Function panel. From here you can just keep pressing PF3 until you are back at the main ISPF menu. ------------------------------------------------------------------------------- $INSTALL.TXT Adding New Commands August 15, 1999 4-13