Problem solve Get help with specific problems with your technologies, process and projects.

How to use CPSM's PNEWCOPY command

PNEWCOPY is a good demonstration of how to use CPSM for automated operations. This tip illustrates the PNEWCOPY structure and how to use PNEWCOPY for automated operations.

Over the last few months I've been extolling the splendor and majesty of CPSM's Rexx interface. This month I'll go over a really useful example shipped by IBM in library SEYUCLIB. I chose PNEWCOPY because it shows how to work with result sets and the way CPSM values get into Rexx variables.

Understanding PNEWCOPY structure
The over-all structure of PNEWCOPY is displayed in the state of the art flow chart below. The logic is straightforward for the most part, although it uses the Rexx SIGNAL verb which is obscure to me and not necessarily a good structured programming practice. Suffice to say, if anything goes wrong, PNEWCOPY issues a signal to branch to the appropriate subroutine. It also uses signal at the end of script to print a few finishing lines before exiting.

Setting PNEWCOPY context
You may specify two parameters for PNEWCOPY. The first is the program name. The second is the scope about which I'll speak more later.

More on CICS commands:
Submitting a batch job from CICS

CICS command security

Securing a CICS screen
The program begins, as all good CPSM Rexx programs must, with an INITAPI call. This call initializes the environment and loads the proper CPSM routines. The INITAPI is followed swiftly by a CONNECT request. The connect sets the context and scope the subsequent commands apply to.

PNEWCOPY comes with the context hard coded to "SCSPLEX" which is less than useful, but easily changed in a customized version of the script. The scope can be the entire CICSPlex or an individual region as needed. Interestingly, the program name can be masked with an asterisk at the end, thus enabling you to new copy many programs in one shot.

PERFORM OBJECT to execute phase-in command
After setting context and scope the PERFORM OBJECT command actually does the deed. Note that despite the name of the script, it actually executes a "phase-in" command. Phasing in a program is preferable because a new copy will fail if the target module is in use at the time of the command. In contrast, phase in tells CICS to find and load the new version of the program to be used by all subsequent tasks.

The PERFORM OBJECT's criteria parameter specifies the program or programs to be phased in. PNEWCOPY knocks the criteria around until it looks just like a parameter coded in a CPSM program, in this case, "( PROGRAM=pgmname AND LENGTH ¬= 0)." Note that CPSM variable substitution rules apply as outlined last month and the almighty period at the end is very important. Failure to understand the rules or include the period will result in errors.

Writing the results
The perform object command returns a variable containing the number of rows in the result set. PNEWCOPY uses this variable to control the fetch loop as it retrieves the rows one by one. Before it can retrieve the rows, however, it must use the "LOCATE TOP" command to set the cursor to the first row.

The loop is fairly simple. At the top is the FETCH that brings each result set row along with its columns into a single Rexx variable. Also included is the length of the fetched information.

PNEWCOPY follows this with the TPARSE command. In general, TPARSE separates the columns of information as fetched into a Rexx variable into another set. The new variable names consist of the prefix named in the PREFIX parameter followed by the column name. Note the available columns and data depend on the object type and the tables associated with it. Please consult the CPSM Resource Tables Reference for details.

Since PNEWCOPY operates on programs it fetches rows from the PROGRAM resource table. On the TPARSE command it specifies a prefix of PGM, thus CPSM loads the program name into variable PGM_PROGRAM, the program's length into PGM_LENGTH and so on. After collecting all this dandy information PNEWCOPY writes it out.

The end, results and gotchas
After displaying all the records in the result set PNEWCOPY signals ENDPGM. The ENDPGM routine terminates the CPSM environment and returns.

Here is an example of PNEWCOPY output run from a TSO batch job:

* PHASEIN NEWCOPY Will Be Processed In SCOPE:   CICSPLEX     *
101 Program(s) New Copied
* NEWCOPY Results                                            *
Program  Language     Status  Program Length      CICS System

Following the information about context and scope is the number of programs phased in. For each program in the result set PNEWCOPY displays information intended to serve as a check for if things really worked or not.

Normally this works very well but there are a couple of gotcha's:

  • PNEWCOPY as written will issue a zero return code even if it runs into problems with the CPSM interface. Instead it will write the CPSM return and reason codes to the output stream and exit.
  • The reported program information doesn't necessarily indicate if the program was new copied. You may have to post-process the report to compare lengths to determine success.
  • PNEWCOPY issues return code zero if the program isn't found. A similar situation may arise if you use program auto-install and the target program isn't defined because it hasn't been used. Again, this may or may not be an error condition which would require some kind of post-processing or IEBIBALL check.

PNEWCOPY is a good demonstration of how to use CPSM for automated operations. Even if as an example it is somewhat clunky, it contains the structure for a customized solution for automating program management. For us PNEWCOPY has also served as a springboard for more batch automation. I hope these last few columns about CPSM have been useful. It should be my last for a while -- I promise. Back to top

ABOUT THE AUTHOR: Robert Crawford has been a CICS systems programmer off and on for 24 years. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.

Dig Deeper on IBM system z and mainframe systems

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.