Skip to content
CA Endevor® SCM - 18.0
Documentation powered by DocOps

Processor Utilities

Last update March 12, 2019

Including Processor Utilities in Processor Logic

The following utilities are delivered with CA Endevor® SCM. You can include these utilities anywhere in your processor logic, to perform the functions described. A Yes or No indicates whether the utility supports USS files.

  • BC1PDSIN
    (No) Initializes any number of allocated data sets that begin with ddname C1INIT. This utility is generally used to allocate list data sets.
  • BC1PTMP0
    (Yes) Executes TSO commands, once a TSO environment has been created. This program accepts as input a parameter defining the data set containing the TSO commands to be called. BC1PTMP0 acts as a terminal monitor program and command processor, calling one program (EXEC) to place the commands in a TSO stack, then issuing GETLINE requests to extract the commands from the TSO stack.
  • BC1PXFPI
    (No) Installs “transportable” footprints in object modules generated under z/OS, VSE, or z/VM.

    Note: For more information about "transportable" footprints, see Administrating.
  • BC1PMVCL
    (No) Provides the ability to update the component list to reflect the location of the output components as the result of the move processor. (The Delta library, where the component list is stored, cannot be a USS file.)
  • BSTCOPY
    (No) Copies members from one partitioned data set to another. BSTCOPY allows for the use of MONITOR=COMPONENTS and backout.
  • C1BM3000
    (Yes) Executes CA Endevor® SCM from within a processor.
  • C1PRMGEN
    (No) Creates 80-column (card-image) statements from a parameter passed to the utility. These statements, once expanded, are passed as input control statements to subsequent job steps. C1PRMGEN expands any CA Endevor® SCM symbolic parameters contained in the statements, allowing you to vary the input control specifications based on the values of CA Endevor® SCM symbolic parameters.
  • CONAPI
    (Yes) Invokes a program which issues API calls through a processor.
  • CONDELE
    (Yes) Removes a member from a user library or USS directory, after verifying the footprint for the member.
  • CONLIST
    (No) Manages output listings generated by the processors: store (and footprint) new members in listing libraries, print listings stored as sequential files or as members in listing libraries, or copy a member from one listing library to another (optionally after appending one or more listings at the end of the member).
  • CONPARMX
    (Yes) Reduces processor complexity and the number of CA Endevor® SCM Processor Groups. The primary use of CONPARMX is to support varying program (for example: compiler or linkage editor) options without having to create and update large numbers of processors or processor groups by allowing different levels of Options members (Default, Processor Group, Element) to be included at execution time.
  • CONRELE
    (Yes) Includes entities related to an element in a component list when generating component list reports and when using the LIST action.
  • CONSCAN
    (No) Creates ACM relationships between a CA Endevor® SCM ELEMENT and scanned values from the content of the ELEMENT. It then applies parsing rules to the ELEMENT content, and passes these as standard CONRELE syntax to the CONRELE step as exemplified in the CONSCAN prototype.
  • CONWRITE
    (Yes) Combines all levels of an element, optionally expands INCLUDE statements and writes the merged source to a user-specified data set or USS directory. Can be used as input to a specified program.
    Writes a component list to an external data set for further processing.
  • ENBX1000
    (Yes) For more information, see Expand Includes Utility.
  • ENUSSUTL
    (Yes) Collects package backout information for USS processor output files.
  • LEXTRCTR
    To parse and capture all the pieces of a CSP application when the user is managing at the application rather than the component level.
  • BC1PCCSP
    Attaches the compiler for each piece of the application identified by LEXTRCTR.
Note: The following non-processor utilities do not support USS files:
  • BC1PNLIB-ELIB Copy Utility
  • ENBS1000-Text Search-and-Replace
  • ENBX1000-Include/Copy Member Expansion Utility
  • C1BML000-Initial Inventory Load Utility
Important! ELIB utilities, BC1PNLIB, NCPY, and NLST cannot be used within a processor.

BC1PDSIN Utility

BC1PDSIN can be used to initialize sequential data sets. For example, in a processor with COMPILE, LINK, and CONLIST steps (where CONLIST uses temporary listing data sets created by the COMPILE and LINK steps), an allocation error would occur in the CONLIST step if the COMPILE or LINK did not run thereby not creating the needed temporary data sets. If you use BC1PDSIN, however, it allocates temporary data sets, so CONLIST has the files it needs to execute.

BC1PDSIN initializes all data sets that are allocated by the C1INIT or C1LIST DD statements. If you specify more than one C1INIT or C1LIST data sets, assign the ddnames sequentially. For example, C1LIST01, C1LIST02 and so forth, or C1INIT01, C1INIT02, and so forth.

To initialize a PDS within BC1PDSIN, specify:

  • The member name in the data set name
  • DSORG=PO
  • The number of directory blocks to allocate in the SPACE parameter.

To allocate but not initialize an entire temporary PDS, use a DDNAME that does not begin with //C1INIT. For example, //C2INIT, //TEMPPDS, or //C1INTPO. This allocates the library in the same manner as IEFBR14.

Sample JCL

A sample JCL for the BC1PDSIN utility is shown:

//STEPNAME   EXEC PGM=BC1PDSIN
//C1INITxx   DD DSN=&&COBLST,DISP=(,PASS,DELETE),
//              UNIT=SYSDA,SPACE=(TRK,(1,2),RLSE),
//              DCB=(RECFM=FBA,LRECL=121,BLKSIZE=3630,DSORG=PO)
 
//C1LISTxx   DD DSN=&&LNKLST,DISP=(,PASS,DELETE),
//              UNIT=SYSDA,SPACE=(TRK,(1,2),RLSE),
//              DCB=(RECFM=FBA,LRECL=121,BLKSIZE=3630,DSORG=PO)

BC1PTMP0 Utility

BC1PTMP0 allows TSO commands to be executed once a TSO environment has been created. The program accepts as input a parameter that defines the data set containing the TSO commands to be called. This program is usually used for processors that are executed under the CA Endevor® SCM ISPF dialog.

Note: BC1PTMP0 issues TSO command processor STACK services using the BARRIER option. Only releases of TSO that support the BARRIER option can use this utility.
Note: If using a REXX EXEC instead of a TSO CLIST, a PUSH END statement must be coded at the end of the EXEC.

BC1PTMP0 first checks whether a TSO environment is present and performs the following actions:

  • If no TSO environment is present, BC1PTMP0 ends with a return code of 5.

    Note: For more information about return codes, see Return Codes.
  • If a TSO environment is present, BC1PTMP0 acts as a terminal monitor program and command processor. BC1PTMP0 calls the program EXEC, which then places the commands (specified in the data set coded on the PARM= parameter) in the TSO stack. BC1PTMP0 issues GETLINE requests to extract those commands from the TSO stack.

TSO does not allow the program IKJEFT01, a TSO program, to be executed once TSO processing has started. (That is, TSO does not allow TSO to run under it.) Executing BC1PTMP0 in a processor rather than executing IKJEFT01 allows TSO commands to be executed within a CA Endevor® SCM processor.

The CA Endevor® SCM for DB2 product requires the use of BC1PTMP0.

You can code a BC1PTMP0 step and a IKJEFT01 step in a processor, so that BC1PTMP0 executes, if the processor is running under TSO, and IKJEFT01 executes, if the processor is running in batch mode. Use the following steps to implement this technique.

//TSOMODE      EXEC PGM=BC1PTMP0                                             

//XX                                                                      

//BATMODE      EXEC PGM=IKJEFT01,COND=(5,NE,TSOMODE)                         

//XX                                                                       

Important! ISPF services cannot be invoked in a TMP. CA Endevor® SCM is using ISPF services to invoke the processor and an attached TMP (BC1PTMP0) can not start another ISPF service in the same TSO address space. ISPF services (ISPEXEC, ISPSTART, etc.) cannot be invoked via BC1PTMP0.

Sample JCL and Parameters

The following JCL is specified in the processor:

//STEPNAME EXEC  PGM=BC1PTMP0,
//    PARM='uprfx.uqual.CLISTLIB(clist)'
//STEPLIB DD DSN=iprfx.iqual.CSIQLOAD,DISP=SHR

The parameters in the previous syntax are described as follows:

  • PARM=
    The name of the data set containing the commands to be executed by BC1PTMP0.
  • uprfx.uqual.CLISTLIB
    The name of the CLIST library containing the commands that you want to execute.
  • clist
    The name of the CLIST that you want to execute.
  • iprfx.iqual.CSIQLOAD
    The CA Endevor® SCM installation load library containing the program BC1PTMP0. (For DB2 processors, you may need to add your DB2 load library.)

Return Codes

BC1PTMP0 utility can return any of the following return codes:

  • 0
    All commands were successfully processed.
  • 5
    TSO (that is, program IKJEFT01) currently is not active. This step within the processor was executed, however.
  • 6
    No parameter was specified in the PARM= statement within the JCL, or a data set name greater than 56 characters was specified.
  • 7
    A command specified in the CLIST was not found. BC1PTMP0 attempts to load all programs prior to issuing an ATTACH. If the load fails, this return code is passed back to.
  • 8
    The PARM= specification on the EXEC card was coded incorrectly, for example:
    • No parameter was passed
    • Parameter is too large (greater than 54)
    • Parameter does not end with a pair of parentheses surrounding a member name
    • Member name portion of the parameter is invalid
  • 9
    A GETMAIN failed for the command buffer required by attached programs. BC1PTMP0 attempted to acquire a command buffer in subpool 78 and the GETMAIN failed.

Any program or command invoked by BC1PTMP0 can issue any return code for their own reasons. This includes return codes 5,6,7,8,9 and any other return code. BC1PTMP0 simply returns the return code passed by those programs. For example, a command invoked by BC1PTMP0 may return a RC=8 when it gets an allocation error. A different command invoked by BC1PTMP0 may return a RC=8 when a program is not found.

REXX Exec or CLIST Executing a DB2 Bind

To enable BC1PTMP0 to invoke a REXX exec or CLIST to execute a DB2 Bind, a DD statement with the name EN$SELCT must be coded in the BC1PTMP0 definitions.

Assume that a processor running in foreground is executing BC1PTMP0 which invokes a CLIST or a REXX exec to execute a DB2 Bind. A STEPLIB in the BC1PTMP0 step defines the library containing the DB2 DSNxxxxx programs. In this case, the STEPLIB is ignored and an 806 occurs. The error occurs if the following processor step and CLIST are coded:

Example processor step:

//TMP0 EXEC PGM=BC1PTMP0

// PARM='PROD.CLIST(TSTCLIST)'

//STEPLIB DD DSN=PUBLIC.PXXXX.STEPLIB,DISP=SHR

//SYSTERM DD SYSOUT=*

//SYSTSPRT DD SYSOUT=*

//SYSPRINT DD SYSOUT=*

//SYSOUT DD SYSOUT=*

Example CLIST TSTCLIST:

DSN SYSTEM(D91A)

BIND PLAN(P2229PRG) -

MEMBER (P2229PRG) -

OWNER (KEIGR01) -

ACTION (REPLACE) RETAIN -

VALIDATE (BIND)

The problem occurs due to the way the program DSN is invoked internally by BC1PTMP0. To correct this, the REXX exec or CLIST must be invoked by a different method. To use this method, code a DD statement with the name EN$SELCT in the BC1PTMP0 definitions. Also, the library containing the REXX exec must be a member of the SYSPROC dd definition. In the following corrected processor step, the clist library 'PROD.CLIST' was defined to the SYSPROC DD concatenation.

Example of a corrected processor step:

//TMP0 EXEC PGM=BC1PTMP0

// PARM='PROD.CLIST(TSTCLIST)'

//STEPLIB DD DSN=PUBLIC.PXXXX.STEPLIB,DISP=SHR

//SYSTERM DD SYSOUT=*

//SYSTSPRT DD SYSOUT=*

//SYSPRINT DD SYSOUT=*

//SYSOUT DD SYSOUT=*

//EN$SELCT DD DUMMY

If this method is used, then the STEPLIB is passed through to the invocation of the DB2 DSN programs.

BC1PXFPI Utility

The BC1PXFPI utility installs “transportable” footprints in object modules generated under z/OS, VSE, or z/VM. Transportable footprints provide footprint audit trails for software that executes in non-z/OS environments (VSE and z/VM).

Note: For more information about transportable footprints, see Footprint Synchronization. (This facility is for non-z/OS environments only).

BC1PMVCL Utility

The BC1PMVCL utility provides the ability to update the component list to reflect the location of the output components as the result of the move processor.

A move processor typically copies the outputs of the generate processor from their libraries to the next stage's output libraries. Once the outputs have been copied, the move processor typically also copies the existing component list to the new inventory area. The utility to move component lists is a pseudo processor program called BC1PMVCL.

When using BC1PMVCL, the existing component data does not get updated so all the input and output components in the component list reflect the data sets used at generate time. If, in a move processor, MONITOR=COMPONENTS is coded on the output files, and BC1PMVCL is part of the processor (as the last step), CA Endevor® SCM :

  • Removes existing output components from component list
  • Adds new output components to component list
  • Does not change input components

Technically, the BC1PMVCL does not have to be the last step; however, it must execute after all monitored components. If components have been monitored in a move processor (prior to the execution of BC1PMVCL), then all of the gathered output components is used to replace all existing output components in the existing component list. These gathered output components are subsequently removed from the storage lists in which they were collected to avoid subsequent update at the end of the processor execution.

This causes output component lists to be generated by a move if a move processor has collected new output components prior to the execution of BC1PMVCL. The output components replace all output in the existing components list.

BC1PMVCL provides the ability to update the component list to reflect the location of the output components as the result of the move processor.

The move processor utility BC1PMVCL now can dynamically replace old Endevor output components with the new output components at the end of the move processor execution. By using BC1PMVCL in your move processor, Quick Edit commands LL and LO function after a move.

BSTCOPY Utility

The BSTCOPY utility offers a limited subset of the functionality provided by IEBCOPY.

You must use BSTCOPY instead of IEBCOPY if you use the CA Endevor® SCM Automated Configuration Manager (ACM), or if package backout has been enabled for the output library. This is because CA Endevor® SCM cannot determine which members are changed by IEBCOPY.

BSTXCOPY is a CA Endevor® SCM utility that performs the same functions as the CA Endevor® SCM processor utility BSTCOPY. However, you can use BSTXCOPY to perform these functions outside of a CA Endevor® SCM processor. 

BSTCOPY Copy Functions

BSTCOPY can be used to copy between PDS load libraries and PDSE load libraries, from PDSE to PDSE, and from PDSE back to PDS. It cannot copy between a PDSE load library and any other CA Endevor® SCM access method (CA Librarian, CA Panvalet, ELIB).

BSTCOPY can copy aliases, but the alias must be explicitly requested. To copy an alias, the original loadlib member must be copied first. For more information about aliases, see BSTCOPY and Aliases.

Copying from a PDSE load library to a PDS may result in errors, depending on whether the PDSE contains any program object members which cannot be converted back to load modules. This includes program objects which are greater than 16 megabytes in size, or which included mixed-case, extended names, or contain more than 32K of external symbols.

Note: For more information about the conversion restrictions, see the program management manuals for DFSMS/MVS 1.1 or higher.

BSTCOPY is not intended to replace IEBCOPY. Rather, it is provided to support simple member copy operations from one library to another.

When a PDS load module is copied to a PDSE, CA Endevor® SCMinframe load module footprint information is retained only if the CA Endevor® SCM processor utility BSTCOPY is used. Other utilities, such as IEBCOPY, do not have the capability to copy the *LOADMOD footprint. For more information, see TEC316937, How to Convert AllFusion Endevor Change Manager Load Libraries between PDS and PDSe Formats, on ca.com/support.

BSTCOPY Syntax - Literal Interpretation

►►──COPy──Indd──=─┬──ddname1────────┬──,──Outdd──=──ddname2──────────────────────────►
                  └─ ((ddname1,R)) ─┘

►►──Select──Member──=─┬─member1────────────────────────┬──.─────────────────────────►◄
                      ├─member1member2───────────────┤

                      ├─((member1,newname1,R))─────────┤

                      │    ┌─,────────────────────┐    │

                      └─(──▼─(member1,newname1,R)─┴──)─┘

BSTCOPY Syntax - Alternate Interpretation

►►──COPy──INDd──=─┬──ddname1────────┬──,──OUTdd──=──ddname2──────────────────────────►
                  └─ ((ddname1,R)) ─┘

►►──SELect──MEMber──=─┬─member1────────────────────────┬──.─────────────────────────►◄
                      ├─member1member2───────────────┤

                      │    ┌─,────────────────────┐    │

                      └─(──▼─(member1,newname1,R)─┴──)─┘

Important! Spaces before or after the comma between COPY INDD and OUTDD results in a syntax error.
BSTCOPY and Aliases

Load modules and program objects with an alias can be handled by BSTCOPY even though BSTCOPY does not support COPYGRP syntax. The following methods are suggested.

  • To bring loadonly software under CA Endevor® SCM control, use the following method, which requires two steps in the Generate processor:
    • A step to COPYGRP with IEBCOPY into a temporary PDSE, and then
    • A BSTCOPY step to copy all the results into the final target PDSE library. This latter step ensures that the CA Endevor® SCM Automated Configuration option output components are monitored, while preserving the aliases.

    The following Generate Processor example uses this method:

    //************************************************************

    //* FIRST COPY LOADMODULE TO TEMPORARY PDSE

    //************************************************************

    //CPY1    EXEC PGM=IEBCOPY,MAXRC=04

    //SYSPRINT  DD SYSOUT=*

    //SYSUT3    DD UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //SYSUT4    DD UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //INDD      DD DSN=&C1USRDS,DISP=SHR

    //OUTDD     DD DSN=&&TEMPDSN,DISP=(,PASS),UNIT=SYSDA,

    //            SPACE=(CYL,(5,5,44)),DSNTYPE=LIBRARY,

    //            DCB=(LRECL=0,BLKSIZE=32760,RECFM=U,DSORG=PO)

    //SYSIN     DD *

       COPYGRP OUTDD=OUTDD,INDD=INDD

       SELECT MEMBER=&C1ELEMENT

    //**********************************************************************

    //* NOW COPY All INTO TARGET OUTPUT LOADLIB MONITOR=COMPONENTS         *

    //**********************************************************************

    //CPY2    EXEC PGM=BSTCOPY,MAXRC=04

    //SYSPRINT  DD SYSOUT=*

    //SYSUT3    DD UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //SYSUT4    DD UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //INDD      DD DSN=&&TEMPDSN,DISP=(OLD,PASS)

    //OUTDD     DD DSN=&LOADLIB1,DISP=SHR,MONITOR=COMPONENTS,

    //           FOOTPRNT=CREATE

    //SYSIN     DD *

       COPY    OUTDD=OUTDD,INDD=((INDD,R))


  • To copy aliases of load modules or program objects inside a Move processor, use the following method. The temporary library and the source library for IEBCOPY must be the same library type (PDS or PDSE). Otherwise IEBCOPY might not copy the *LOADMOD Footprint.
    The following Move Processor example uses this method:

    //IF2  IF (&C1ACTION=TRANSFER) OR (&C1ACTION=MOVE) THEN

    //********FIRST IEBCOPY COPYGRP TO PRESERVE ALIAS***********************

    //TRCOPY1 EXEC PGM=IEBCOPY,MAXRC=04

    //SYSPRINT  DD SYSOUT=*

    //FCOPYOFF DD DUMMY

    //SYSUT3    DD UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //SYSUT4    DD UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //INDD      DD DSN=&LOADLIB1,DISP=SHR

    //OUTDD     DD DSN=&&TMPDSN,DISP=(,PASS),UNIT=SYSDA,

    //            SPACE=(CYL,(5,5,44)),DSNTYPE=LIBRARY,

    //            DCB=(LRECL=0,BLKSIZE=32760,RECFM=U,DSORG=PO)

    //SYSIN     DD *

       COPYGRP OUTDD=OUTDD,INDD=INDD

       SELECT MEMBER=&C1ELEMENT

    //********NOW COPY ALL IN TEMPORARY TO TARGET PDSE**********************

    //TRCPY2 EXEC PGM=BSTCOPY,MAXRC=04

    //SYSPRINT  DD  SYSOUT=*

    //SYSUT3    DD  UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //SYSUT4    DD  UNIT=&WRKUNIT,SPACE=(TRK,(1,1))

    //OUTDD     DD  DSN=&LOADLIB2,DISP=SHR,MONITOR=COMPONENTS

    //INDD      DD  DSN=&&TMPDSN,DISP=SHR,FOOTPRNT=VERIFY

    //SYSIN     DD  *

       COPY    OUTDD=OUTDD,INDD=((INDD,R))

    //********NOW MOVE THE COMPONENT LIST..must be the LAST step       ***

    //BC1PMVCL EXEC PGM=BC1PMVCL,COND=(0,NE)

    //END2  ENDIF

BSTCOPY Unsupported Functions

BSTCOPY does not:

  • Copy members of a partitioned data set to a sequential data set.
  • Compress partitioned data sets.
  • Copy load modules that have the linkage editor OVERLAY attribute.
  • Reblock load modules when the BLKSIZE of the input library is greater than that of the output library.
  • Support multiple DD definitions on the INDD statement.
  • Support splitting a SELECT statement on multiple lines. A SELECT statement must be specified on one physical input record.
  • Support FREE-CLOSE on any input or output DD names.

//BSTCOPY  PGM=BSTCOPY,MAXRC=0
//SYSPRINT DD  SYSOUT=*
//IN1      DD  DISP=SHR,DSN=DSNAME1
//IN2      DD  DISP=SHR,DSN=DSNAME2
//OUT1     DD  DISP=OLD,DSN=DSNAME3
//SYSIN    DD  *
    COPY INDD=((IN1,R)),OUTDD=OUT1
    SELECT MEMBER=MEMBER1
    COPY INDD=IN2,OUTDD=OUT1
    SELECT MEMBER=((MEMBER2,,R),(MEMBER3,,R))
    SELECT MEMBER=((MEMBER4,NEWNAME4,R))
 /*

BSTCOPY and OVERLAY Modules

BSTCOPY does not support the copy of a load module that is linked as OVERLAY. When BSTCOPY cannot be used, backout processing is effectively disabled for packages.

One solution is to relink the load modules. If the load modules are vendor-supplied, however, and relinking may jeopardize ongoing vendor support, another solution is to write a two-step processor. Follow these steps to create the new processor:

  1. Create a dummy module and execute a BSTCOPY step that copies it and renames it to the name of the OVERLAY module. This bypasses the system's security and renames the target module, creating a backout.
  2. Code an IEBCOPY step that copies the real module in, overlaying the dummy module. Because IEBCOPY cannot be screened, backouts are not affected.

The following processor executes these two steps:

//STEP1    EXEC PGM=BSTCOPY
//SYSPRINT DD SYSOUT=*
//IN       DD DSN=source.data.set,DISP=SHR
//OUT      DD DSN=target.data.set,DISP=SHR
//SYSIN    DD *
 C I=IN,O=OUT
 S M=((dumymbr,&C1ELEMENT.,R)) <===DUMMY MEMBER COPIED TO CREATE BACKOUT
//STEP2    EXEC PGM=IEBCOPY
//SYSPRINT DD SYSOUT=*
//SYSUT3   DD UNIT=SYSDA,SPACE=(TRK, (5,5))
//SYSUT4   DD UNIT=SYSDA,SPACE=(TRK, (5,5))
//IN       DD DSN=source.data.set,DISP=SHR
//OUT      DD DSN=target.data.set,DISP=OLD
//SYSIN    DD *
 C I=IN,O=OUT
 S M=((&C1ELEMENT.,,R)) <===COPY REAL MEMBER

For PDSMAN users

  1. Using the PDSMAN $IEBCOPY statement, BSTCOPY can be replaced with the PDSMAN utility FASTCOPY. Specify NAME=BSTCOPY on the $IEBCOPY statement to enable this support. Package shipment jobs and processors coded to run BSTCOPY in this situation execute FASTCOPY instead.
  2. To disable substitution of FASTCOPY for BSTCOPY in this environment, code a DD statement in the processor JCL for the ddname 'FCOPYOFF,' allocated to DD DUMMY.
  3. For CA Endevor® SCM Automated Configuration Option users, when executing FASTCOPY, input components are not collected. Output components are collected and package backout members and data are collected.
  4. OVERLAY and SCTRLOAD modules are supported when using FASTCOPY.
  5. Set the $IEBCOPY operand STORFAIL= to the value TERMINATE when using FASTCOPY substitution for BSTCOPY.

SYSPRINT DCB Information

When directing SYSPRINT output to a data set, the DCB information specified should be as follows:

  • RECFM=VBA
  • LRECL=121
  • BLKSIZE=125

C1BM3000 Utility

The C1BM3000 utility lets you execute CA Endevor® SCM actions from within a processor.

You must pass the SCLIN (SCL input) and MSGOUT1 (output messages) parameters to the C1BM3000 utility. Optionally, if you want:

  • A package ID associated with this execution, you must pass the PACKAGE parameter.
  • CA Endevor® SCM to write the Action Summary report to a separate file, you must pass the MSGOUT2 parameter.
Important! When a package action executes a processor that invokes C1BM3000, the actions run by the C1BM3000 step are considered non-package actions. If the actions update an inventory area that has approver relations, the C1BM3000 utility issues a C1U0900E error (package processing required). Also, backout information is not created for actions run in a C1BM3000 step.

Example (Sample JCL)

Sample JCL for the C1BM3000 utility is shown next. This JCL specifies a SCL input file, and the messages and Action Summary report are written to SYSOUT. A package ID is not specified, as indicated by the two commas between MSGOUT1 and MSGOUT2. The two commas are required.

//C1BM3000  EXEC PGM=C1BM3000,PARM='SCLIN,MSGOUT1,,MSGOUT2'
//STEPLIB   DD  DSN=iprfx.iqual.CSIQAUTH,
//          DISP=SHR
//MSGOUT1   DD  SYSOUT=*
//MSGOUT2   DD  SYSOUT=*
//SYSABEND  DD  SYSOUT=*
//SCLIN     DD  DSN=uprfx.uqual.SCL,DISP=SHR
//          DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160,DSORG=PS)
//

Note: You need not specify the CONLIB DD statement, because the library has been specified by the batch job or by the logon procedure in foreground.

Considerations When Using the C1BM3000 Utility

Do not use the following:

  • BSTIPT01 for SCLIN, the name is reserved by CA Endevor® SCM for input SCL.
  • C1MSGS1 for MSGOUT1, the name is reserved by CA Endevor® SCM for batch execution report messages.
  • C1MSGS2 for MSGOUT2, the name is reserved by CA Endevor® SCM for the Action Summary report.
Important! A C1BM3000 step in a processor step cannot perform actions against an element that is currently being acted upon. Only actions that do not require exclusive use of the element, for example LIST, PRINT or TRANSFER with BYPASS ELEMENT DELETE, can be executed against the same element. Failure to observe this rule leads to an endless wait where the primary C1BM3000 task waits for the secondary task to terminate while the secondary C1BM3000 task waits for the primary task to release the element.

C1WORK01-06 DD Statements

When you use the C1BM3000 utility to TRANSFER an element, the datasets are dynamically allocated to process data. The dynamically allocated datasets may not be sufficient, if a large element is transferred, and the System abort B37 error may occur. In this case, you can use the C1WORK01-C1WORK06 DD statements to override the standard dynamic allocation of datasets, and run the TRANSFER action again. These DD statements override the following records during the TRANSFER action:

  • C1WORK01-Merged configuration records
  • C1WORK02-Configuration delta records
  • C1WORK03-Configuration base records
  • C1WORK04-Merged element records
  • C1WORK05-Element delta records
  • C1WORK06-Element base records

You can code any or all of the previous DD statements. If you code one C1WORK DD statement, then it overrides the equivalent dynamic allocation of datasets. For example, if a very large element is transferred the regular dynamic allocation of datasets may not be sufficient for storing element base, element delta, and merged element records. In this case, you can code the C1WORK04, C1WORK05 and C1WORK06 statements to override the dynamic allocation of datasets.

A sample JCL illustrating how to code these DD statements is shown as follows:

//STEP1     EXEC PGM=C1BM3000,PARM='SCLIN,MSGOUT1,,MSGOUT2'
//MSGOUT1   DD  SYSOUT=A
//MSGOUT2   DD  SYSOUT=A
//SCLIN     DD  *
//ARC       DD  DISP=OLD,DSN=ARCHIVE.DATASET
//C1WORK04  DD  UNIT=SYSDA,SPACE=(CYL,(50,50)),
//              DCB=(RECFM=VB,LRECL=5000,BLKSIZE=6233)
//C1WORK05  DD  UNIT=SYSDA,SPACE=(CYL,(50,50)),
//              DCB=(RECFM=VB,LRECL=5000,BLKSIZE=6233)
//C1WORK06  DD  UNIT=SYSDA,SPACE=(CYL,(50,50)),
//              DCB=(RECFM=VB,LRECL=5000,BLKSIZE=6233)
//BSTIPT01  DD  *

C1PRMGEN Utility

The C1PRMGEN utility creates 80-column (card-image) statements from a parameter passed to it. These statements are passed as input control statements to subsequent job steps.

To create card-image data, you can include CA Endevor® SCM symbols in the parameter passed to C1PRMGEN. If you do this, the utility expands the symbols as it creates the output statements, allowing you to vary the input control statements passed to subsequent job steps based on the values of CA Endevor® SCM symbolic parameters. This is illustrated next, where C1PRMGEN creates two control statements for use by the IBM IEBCOPY utility.

Example (Sample JCL)

To use C1PRMGEN, pass the data to be expanded in the PARM= parameter of the EXEC statement. To create more than one card-image statement, separate the statements using a vertical bar (|) in the PARM= value, as illustrated in the following sample JCL:

//STEPNAME EXEC PGM=C1PRMGEN,
//              PARM=' C I=I,O=O| S M=((&&C1ELEMENT.,,R))'
//PARMOUT    DD  DSN=&&CPYPARM,DISP=(,PASS,DELETE)
//               DCB=(RECFM=FB,LRECL=80,BLKSIZE=80)

The parameters in the previous sample JCL are described as follows:

  • PARM=
    The statement to be expanded, enclosed in single quotes or parentheses. This statement can be 1-100 characters in length. Once expanded, it is output in card-image format starting in column 1. To output more than one card-image statement, use the separator character (|) in the PARM statement, as shown above.
    If the statement contains more than 72 characters (up to 100 characters are allowed), you can add a second line to the parameter by coding the statement as follows:
    • Enter the first 71 characters of the line.
    • In position 72, type any non-blank character (except a single quote), and continue entering your data on the next line.
    • Type a (single) quote only at the end of the entire statement. Note the example below:

    Col                                                 Col1                                                 72PARM='abcd..................................................zx//  z.................................................a'   

    • To include a quotation mark within the card-image data, specify two contiguous quotes: ' '.
    • You can include an unbalanced parentheses, with the restriction that you must use single quotes as the surrounding delimiters in this case. You cannot include unbalanced parentheses when the enclosing characters are parentheses, however.
  • PARMOUT
    The data set to which the expanded statement is written.
    In the previous example, the output written to PARMOUT, assuming that the current element is NDVR, is as follows:

    Col
    1
    C I=I,O=O
    S M=((NDVR,R))

CONAPI Utility

The CONAPI utility lets you execute a program that issues API calls through a processor.

A program that issues API calls CANNOT be executed from a processor directly. You must use this utility passing it the name of your program through the PARM= parameter on the EXEC statement. If your program requires parameter data, you may append it to the parameter string using a comma to separate the program name from your parameter data.

Note: For more information about the API interface, see API and User Exits Reference.

Example (Sample JCL)

A sample JCL is shown:

//STEPNAME  EXEC PGM=CONAPI,PARM='APIPROG1,1,22,333'

CONAPI invokes program APIPROG1. On entry to APIPROG1, register 1 contains an address which points to an address for the parameter data. The first two bytes of parameter data contains the length after which follows the data.

In the above example storage (in hex) would appear as follows:

     0008F16BF2F26BF3F3F3

CONDELE Utility

The CONDELE utility removes a member (load module, listing, etc.) from an output library. The output library can be any of the following:

  • Source output library
  • Processor listing library
  • Processor load library
  • User output library
  • USS directory

This utility is generally used in delete processors.

Example (Sample JCL)

Sample JCL for this utility is shown next:

//STEPNAME  EXEC PGM=CONDELE,PARM='mbr-name'
//C1LIB       DD  DSN=CA.STAGE1.LOADLIB,DISP=SHR

The parameters in the preceding syntax are described as follows:

  • PARM=
    Indicates an alternate member name (mbr-name) for the element. You have the option of overriding the default member name. To specify all output components (including object modules, load modules, and listings) instead of an individual member name, specify 'PARM=*COMPONENTS'. CONDELE accesses the component list at the current location and deletes all output components from that list.

    Important! CONDELE does not verify the component list was generated at the current location. You need to verify this independently before using the PARM=*COMPONENTS parameter.
  • C1LIB
    Specifies the library or USS directory containing the member targeted for deletion. The member name is the name of the element being processed (generally moved, deleted, or archived).

CONLIST Utility

The CONLIST utility is a multi-purpose utility used to manage output listings. Specify one of the following options on the PARM= statement on the EXEC card. You can also specify the MBR option with any of these options, except for the PRINT option.

  • STORE
    Consolidates and compresses one or more temporary list data sets into a member in the output library defined by the DD statement C1LLIBO. CONLIST converts the data sets to the record format of the output library, and uses the member name as the element name. The output library can be a PDS with record size and record format appropriate for listings (RECFM=VBA is recommended), or a ELIB data set which is stored as if RECFM=VBA. You can optionally generate a banner page and store it at the front of the member.

    Note: RECFM=VBA forces the listing to be stored in compressed format. To store the listing in uncompressed (human readable) format, allocate the library with RECFM=FBA instead.

    If more than one file is input, CONLIST concatenates the files before storing them.
    The listing files must be sequential; they cannot be PDS members. If you use a PDS, you receive an error message stating the member cannot be found in the directory.

  • PRINT
    Default. Prints a temporary list data set, optionally generating a banner page before the listing. If more than one file is input, CONLIST concatenates the files before printing them.
  • PRTMBR
    Decompresses then prints a member from a listing library.
  • COPY
    Copies a member from an input listing library to an output listing library (generally from Stage 1 to Stage 2), after optionally appending one or more temporary list data sets at the end of the member. You can optionally store a banner at the front of the member in the output library.
  • DELETE
    Deletes a member from the output library.
  • MBR (mbr-name)
    Overrides the default member name (that is, the element name) used by CONLIST. This option can be used with the STORE, PRTMBR, COPY, and DELETE options.

Banner Pages

You can request a banner when using the STORE, PRINT, and COPY options. Banner pages are defined with a C1BANNER DD statement. This statement must specify LRECL=121.

The banner is useful for scanning listings and browsing stored members. The banner includes the following items:

  • The element name across the top.
  • A summary of the processor being run (user ID, date, return code, stage, and so on).
  • An itemization of each processor step, up to but not including the CONLIST step, with the return code from each.

Error conditions are reflected in the banner; for example, an error may have occurred within a processor step, or steps were not executed because of condition-code testing.

STORE Option

The STORE option consolidates and compresses one or more temporary list data sets into a member in the output library defined by the DD statement C1LLIBO.

//STEPNAME  EXEC PGM=CONLIST,PARM='STORE'
//C1BANNER    DD DISP=(,PASS,DELETE),
//               UNIT=SYSDA,SPACE=(TRK,(1,1)),
//               DCB=(RECFM=FBA,LRECL=121,BLKSIZE=6171,DSORG=PS)
//C1LLIBO     DD DSN=&C1STAGE.LISTINGS,DISP=SHR
//LIST01      DD DSN=&&COBLST,DISP=(OLD,DELETE)
//LIST02      DD DSN=&&LNKLST,DISP=(OLD,DELETE)

The parameters in the previous sample JCL are described next:

  • C1BANNER
    Requests a banner (as illustrated above) be included at the front of the stored member. Omit this statement if you do not want the banner included.
  • C1LLIBO
    Identifies the output listing library to which the new member is written. The output member name is the name of the element being processed. If a member by this name currently exists, it is replaced.
Note: FOOTPRNT=CREATE is not needed on this DD statement, becuase CONLIST footprints automatically.
  • LISTnn
    Identifies a listing data set to be stored in C1LLIBO. If you specify more than one LISTnn library, assign the ddnames sequentially (LIST01, LIST02, and so forth). LISTnn data sets are concatenated before they are stored, in order by the nn suffix.
    Note: You must specify at least one LISTnn DD statement.
Note: You can override the default member (element) name for the STORE option, using the MBR (mbr-name) option.

PRINT Option

The PRINT option prints a temporary list data set, optionally generating a banner page before the listing.

//STEPNAME  EXEC PGM=CONLIST,PARM='PRINT'
//C1BANNER    DD DSN=&&BANNER,DISP=(,PASS,DELETE),
//               UNIT=SYSDA,SPACE=(TRK,(1,1)),
//               DCB=(RECFM=FBA,LRECL=121,BLKSIZE=6171,DSORG=PS)
//C1PRINT     DD SYSOUT=*,
//               DCB=(RECFM=FBA,LRECL=133,BLKSIZE=0,DSORG=PS)
//LIST01      DD DSN=&&COBLST,DISP=(OLD,DELETE)
//LIST02      DD DSN=&&LNKLST,DISP=(OLD,DELETE)

The parameters in the previous sample JCL are described:

  • C1BANNER
    Requests a banner page (as illustrated above). Omit this statement if you do not want the banner to print.
  • C1PRINT
    The output print file.
  • LISTnn
    Identifies a listing data set to be printed. If you specify more than one LISTnn data set, assign the ddnames sequentially (LIST01, LIST02, and so forth). LISTnn data sets are concatenated before they are printed, in order by the nn suffix.
    Note: You must specify at least one LISTnn DD statement.

PRTMBR (Print Member) Option

The PRTMBR option decompresses then prints a member from a listing library.

//STEPNAME  EXEC PGM=CONLIST,PARM='PRTMBR'

//C1LLIBI     DD DSN=STAGE1.LISTINGS,DISP=SHR
//C1PRINT     DD SYSOUT=*,
//               DCB=(RECFM=FBA,LRECL=133,BLKSIZE=0,DSORG=PS)

The parameters in the previous syntax are described:

  • C1LLIBI
    Identifies the input listing library from which a member is being printed. The name of the member to be printed is the name of the element being processed.
  • C1PRINT
    The output print file.
Note: You can override the default member (element) name for the PRTMBR option, using the MBR (mbr-name) option. For example, to specify member mbrname in data set prtmbr.mbr, you would code:

//STEPNAME EXEC PGM=CONLIST,PARM='PRTMBR.MBR(mbr-name)'

The COPY Option

The COPY option copies a member from an input listing library to an output listing library (generally from Stage 1 to Stage 2), after optionally appending one or more temporary list data sets at the end of the member.

//STEPNAME  EXEC PGM=CONLIST,PARM='COPY'

//C1BANNER    DD DSN=&&BANNER,DISP=(,PASS,DELETE),
//               UNIT=SYSDA,SPACE=(TRK,(1,1)),
//               DCB=(RECFM=FBA,LRECL=121,BLKSIZE=6171,DSORG=PS)
//C1LLIBI     DD DSN=STAGE1.LISTINGS,DISP=SHR
//C1LLIBO     DD DSN=STAGE2.LISTINGS,DISP=SHR
//LIST01      DD DSN=&&COBLST,DISP=(OLD,DELETE)
//LIST02      DD DSN=&&LNKLST,DISP=(OLD,DELETE)

The parameters in the previous sample JCL are described:

  • C1BANNER
    Requests a banner page. Omit this statement if you do not want the banner included in the output member.
  • C1LLIBI
    Identifies the input listing library from which a member is being copied. The member being copied has the name of the element being processed.
  • C1LLIBO
    Identifies the output listing library to which the copied member is being written (after appending any LISTnn files at the end of the member). The member name is the element name.
  • LISTnn
    Identifies a listing data set to be concatenated at the end of the C1LLIBI member before it is written to C1LLIBO. If you specify more than one LISTnn data set, assign the ddnames sequentially (LIST01, LIST02, and so forth). LISTnn data sets are concatenated (in order by the nn suffix) before they are appended to the member. 
    Note: Specifying a LISTnn DD statement is optional for the COPY option.
Note: You can override the default member (element) name for the COPY option, using the MBR (mbr-name) option.

DELETE Option

The DELETE option deletes a member from the output library.

//STEPNAME  EXEC PGM=CONLIST,PARM='DELETE'

//C1LLIBI     DD DSN=STAGE1.LISTINGS,DISP=SHR

The parameters in the previous sample JCL are described:

  • C1LLIBI
    Identifies the input listing library from which a member is to be deleted. The name of the member to be deleted is the name of the element being processed.
Note: You can override the default member (element) name for the DELETE option, using the MBR (mbr-name) option. For example, to specify member mbrname in data set delete.mbr, you would code:

//STEPNAME EXEC PGM=CONLIST,PARM='DELETE.MBR(mbrname)'

Guidelines When Creating Listings

There are several ways you can approach the creation and handling of listings within CA Endevor® SCM processors. The following is the recommended approach.

  1. Writing the listings to a data set other than SYSOUT during the processor step
  2. Running the CA Endevor® SCM CONLIST utility at the end of the job to combine all the listings into a single member of a listing library.

To do this:

  1. Initialize each listing data set before you write to it, to ensure that there is a listing to open in the final (CONLIST) step. You need one such data set for each utility that outputs listings. The utility that initializes data sets is BC1PDSIN.
  2. In the JCL for the processor utilities, write to the appropriate listing data set--not to SYSOUT.
  3. Use the CA Endevor® SCM CONLIST utility to condense and combine the listings from all the job steps, and store them in a designated listing library or print them.

This approach is illustrated by the following compile and link-edit processor.

Note: In the following examples, Userinfo represents information you must supply.

//INITLST  EXEC PGM=BC1PDSIN,COND=EVEN
//C1INIT01   DD DSN=&&COBLST,DISP=(,PASS,DELETE),UNIT=SYSDA,
//              SPACE=(TRK,(1,2),RLSE)
//C1INIT02   DD DSN=&&LNKLST,DISP=(,PASS,DELETE),UNIT=SYSDA,
//              SPACE=(TRK,(1,2),RLSE)
//WRITE    EXEC PGM=CONWRITE,PARM='EXPINCL(N)'
//ELMOUT     DD DSN=&&SYSIN,DISP=(,PASS,DELETE),userinfo
//*
//*

//COMPILE  EXEC PGM=IGYCRCTL,COND=(0,NE),PARM=mmm,MAXRC=04
//SYSLIB     DD DSN=userinfo
//SYSIN      DD DSN=userinfo
//SYSLIN     DD DSN=&&SYSLIN,DISP=(,PASS,DELETE),userinfo
//SYSUT1     DD UNIT=SYSDA,userinfo
//*

//SYSUT6     DD UNIT=SYSDA,userinfo
//SYSPRINT   DD DSN=&&COBLST,DISP=(OLD,PASS,DELETE),
//              UNIT=SYSDA,SPACE=(TRK,(5,10),RLSE),
//              DCB=(RECFM=FBA,LRECL=133,BLKSIZE=0,DSORG=PS)
//*

//LINK    EXEC PGM=IEWL,PARM='userinfo,COND=userinfo,MAXRC=0
//SYSLIN    DD DSN=&&SYSLIN,DISP=(OLD,PASS)
//SYSLMOD   DD DSN=userinfo
//SYSUT1    DD UNIT=SYSDA,userinfo
//SYSPRINT  DD DSN=&&LNKLST,DISP=(OLD,PASS,DELETE),
//             UNIT=SYSDA,SPACE=(TRK,(5,3),RLSE),
//             DCB=(RECFM=FBA,LRECL=133,BLKSIZE=0)
//*

//CONLIST  EXEC PGM=CONLIST,PARM=STORE,COND=EVEN,MAXRC=0
//C1LLIBO    DD DSN=STAGE1.LISTINGS,DISP=SHR
//C1BANNER   DD DSN=&&BANNER,userinfo
//LIST01     DD DSN=&&COBLST,DISP=(OLD,DELETE)
//LIST02     DD DSN=&&LNKLST,DISP=(OLD,DELETE)
//

  • BC1PDSIN initializes a listing library for use in the COMPILE and LINK steps.
  • CA Endevor® SCM CONWRITE utility creates a source file by merging all levels of the element.
  • COBOL compile writes listings to the file initialized in the INITCOB step.
  • Link-edit writes listings to the file initialized in the INITLNK step.
  • CA Endevor® SCM CONLIST utility creates a CA Endevor® SCM banner page and combines the compile and link-edit listings and stores them as a single member in the Stage 1 listings library.

One Alternative

As an alternative, you can write the listings to SYSOUT. If you are running the processor in batch, SYSOUT=* data sets are attached to the message class (MSGCLASS) assigned in the jobcard for the corresponding batch job.

Note: If you are running in foreground, SYSOUT=* data sets are attached to the default SYSOUT class assigned for your user ID. TSO allocates the SYSOUT file when it is first opened, and does not free it until you log off from TSO or issue an explicit TSO FREE command for the file.

This approach is illustrated by the compile and link-edit processor shown next:

//*
//WRITE    EXEC PGM=CONWRITE,PARM='EXPINCL(N)'

//ELMOUT     DD DSN=&&SYSIN,DISP=(,PASS,DELETE),userinfo
//*
//COMPILE EXEC PGM=IGYCRCTL,COND=(0,NE),PARM=mmm
//SYSLIB     DD DSN=userinfo
//SYSIN      DD DSN=userinfo
//SYSLIN     DD DSN=&&SYSLIN,DISP=(,PASS,DELETE),userinfo
//SYSUT1     DD UNIT=SYSDA,userinfo
//*

//SYSUT6     DD UNIT=SYSDA,userinfo
//SYSPRINT   DD SYSOUT=*
//*
//*

//LINK     EXEC PGM=IEWL,PARM='userinfo,COND=userinfo,
//SYSLIN     DD DSN=&&SYSLIN,DISP=(OLD,PASS)
//SYSLMOD    DD DSN=userinfo
//SYSUT1     DD UNIT=SYSDA,userinfo
//SYSPRINT   DD SYSOUT=*
//*

  • CA Endevor® SCM CONWRITE utility creates a source file by merging all levels of the element.
  • COBOL compile writes listings to SYSOUT.
  • Link-edit writes listings to SYSOUT.

Another Alternative

This approach is similar to the recommended approach but uses the PRINT option of the CONLIST utility, so the listings are printed instead of stored. The JCL for this approach is the same as that for the recommended approach with the exception of the CONLIST step, which is shown below.

//*

//*
//CONLIST EXEC PGM=CONLIST,PARM=PRINT,COND=EVEN,MAXRC=0
//C1PRINT   DD SYSOUT=*,
//             DCB=(RECFM=FBA,LRECL=133,BLKSIZE=0,DSORG=PS)
//C1BANNER  DD DSN=&&BANNER,userinfo
//LIST01    DD DSN=&&COBLST,DISP=(OLD,DELETE)
//LIST02    DD DSN=&&LNKLST,DISP=(OLD,DELETE)
 *

CONPARMX Utility

The CONPARMX utility lets administrators reduce processor complexity and the number of processor groups. CONPARMX dynamically builds execution parameters for processor programs such as compilers or the linkage editor. The build process uses the symbols defined in the processor and one or more of the following groups of options, which may or may not be concatenated:

  • Default options
  • Processor group options
  • Element options

Using this utility avoids the need to create and update large numbers of processors or processor groups with different input parameters.

How to Create a CONPARMX Processor JCL Step

CONPARMX enables you to use fewer processors and processor groups. To use the utility, do the following:

  • Write your CONPARMX processor JCL.
  • Create the options members referenced by CONPARMX's PARM= parameters. Follow the syntax rules when you create the options members.

    Note: We recommend that you store the options members in CA Endevor® SCM and monitor the members as part of an element's input component list.

CONPARMX - Dynamically Build a Parameter String

The CONPARMX utility can reduce the complexity of your processors by dynamically building execution parameters for a specified program. CONPARMX builds a parameter string and optionally invokes a program depending on how you code the utility.

The processor step JCL for the CONPARMX utility is shown next.

//CONP     EXEC PGM=CONPARMX,MAXRC=n, 

//         PARM=(parm1,'(parm2)',parm3,parm4,parm5,

//         '(parm6)','parm7','parm8')

//STEPLIB  DD DSN=xxxxxx.loadlib.if.required,DISP=SHR 

//PARMSDEF DD DISP=SHR,DSN=&PFX..PARMS, 

//            MONITOR=COMPONENTS,ALLOC=PMAP       

//PARMS    DD DSN=&&PPARMS,DISP=(,PASS),   

//            SPACE=(CYL,(1,1)),

//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160)

//PARMSMSG DD SYSOUT=*                  

//* Additional DD statements as required by the parm1 program

The JCL statements and variables used by the CONPARMX utility are as follows:

  • CONP EXEC PGM=CONPARMX,MAXRC=n, 
    PARM=(parm1,'(parm2)',parm3,parm4,parm5,'(parm6)','parm7','parm8')

    Specifies the JCL EXEC statement that executes the CONPARMX utility program. This step requires the following parameters.
    • MAXRC=n
      Specifies the maximum return code value for the parm1 value. If the parm1 program is not called by CONPARMX, the MAXRC should be set to 0.

PARM=

Specifies the parameters the utility used. The total length of the output options string using all options values for CONPARMX parm2 through parm6 can be no more than 512 characters (the CONPARMX limit). This limit is the limit supported by the parm1 program. If CONPARMX is not going to invoke the parm1 program (parm8 = Y), the 512 characters limit is suppressed.

  • parm1
    Specifies a program name for which the options parameter string is to be built. This program name is used to find the options values within the options members. It can be any value up to eight characters. If CONPARMX is going to invoke the program (parm8 = N), this value must also be the name of the program to be run.
    When IGYCRCTL is passed as the program name, the parameters have the prefix CBL. This is to allow those parameters to be passed through SYSIN DD. If this is not wanted, use another program name.
  • parm2
    (Optional) Specifies the processor symbolic that identifies the options to be included first in the output options string. This value must be within parentheses in the CONPARMX parameter list. Parm2 is usually specified with a processor symbolic and can contain 0 to n options. Its value is placed first and is always included in the output options string. The parentheses are not included in the output.

  • parm3
    Specifies the default options member name. The options values found in this member to match the parm1 value (the program name) are added in the output parameter string after the parm2 options values. This member is read from the PARMSDEF DD statement.
    Parm7 determines whether the options members are concatenated. 

  • parm4
    Specifies the processor group options member name. A processor group options member can be created for each processor group. In the member, only the options that are to be overridden for a particular processor group should be included, unless parm7 is set to N. This member is read from the PARMSDEF DD statement.
    Parm7 determines whether the options members are concatenated. 

  • parm5
    Specifies the element options member name. An element options member can be created for any element in the CA Endevor SCM inventory. In this member, only the options that are to be overridden specifically for this element should be included, unless parm7 is set to N. This member is read from the PARMSDEF DD statement.
    Parm7 determines whether the options members are concatenated. 

  • parm6

    (Optional) Specifies the processor symbolic that identifies the options to be included last in the output parameter string. This value must be specified within parentheses in the CONPARMX parameter list. Parm6 can contain 0 to n options and its value is placed last and always is included in the output options string. The parentheses are not included in the output.

  • parm7
    (Optional) Specifies whether to concatenate the options values in the output parameter string. Valid values follow:
    Y - (Default) Specifies that the contents of parm2 through parm6 are to be concatenated.
    N - Specifies that the content of parm5, parm4, or parm3 are to be included between parm2 and parm6. The first options member found to have a record that matches the parm1 program name is used. The options members are searched until the match is found beginning with parm5, then parm4, and then parm3.

  • parm8
    (Optional) Specifies whether to build a parameter string to a file. Valid values follow.
    Y - Writes the parameter string to the PARMS DD statement and the parm1 program is not invoked. This data set can be used as input to a program step that follows. This option suppresses the 512 characters limit for the output options string.
    N - (Default) Passes the parameter string to the parm1 program and invokes the program. The parameter string is not written to the PARMS DD statement.

STEPLIB DD DSN=xxxxxx.loadlib.if.required,DISP=SHR

Specifies the library that should be searched for the parm1 program executed by CONPARMX. Required only if parm8=N indicating that the parm1 program is to be invoked.

PARMSDEF DD DISP=SHR,DSN=&PFX..PARMS,

MONITOR=COMPONENTS,ALLOC=PMAP

Specifies a concatenation of one or more FB-80 PDS or PDSE data sets. The parm3, parm4, and parm5 values point to options members in this data set. Options members do not have to exist or can exist in one or more of the concatenated data sets. The first found options member is used. During processing, if an options member does not exist, it is skipped and processing continues.

  • MONITOR=COMPONENTS
    (Optional) Instructs the CA Endevor® SCM Automated Configuration option to monitor the &PRX..PARMS data set for input or output components and to build a component list with the information captured.
  • ALLOC=PMAP
    (Optional) The ALLOC=PMAP processor DD statement parameter can be specified to indicate that this data set concatenation varies with the CA Endevor® SCM location from which the processor is being executed.

PARMS DD DSN=&&PPARMS,DISP=(,PASS),

SPACE=(CYL,(1,1)),

DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160)

Specifies the data set name to which the parameter string built by the utility is written. The PARMS DD statement is only required if the parm8 value in the CONPARMX parameter string is set to Y.

Note: For program ASMA90, this data set is read from the ASMAOPT DD statement. For COBOL and PL/I compiler programs, place this data set first within the SYSIN DD statement.

PARMSMSG DD SYSOUT=*

Specifies that the output options string value is written to this data set for diagnostic purposes. The PARMSMSG DD statement is not required. The data set DCB attributes are FB-80-32720.

If parm8=N, the output options string is written to the data set 72 bytes per line until the string is exhausted. A maximum of 512 bytes of data (the maximum size of the output options string) or eight lines (7 x 72 = 504 bytes plus 8 bytes on the eighth line) are written to the data set.

If parm8=Y, the output options string is written to the data set exactly as it appears in the PARMS DD output. The 512 bytes limit is suppressed in this case.

How CONPARMX Creates a Parameter String

CONPARMX builds the parameter string and determines whether to execute the program based on how you code the CONPARMX JCL as follows:

  • The following parameters can be specified for CONPARMX. These parameters are passed to CONPARMX on the EXEC statement using the PARM keyword as follows:

//STEP001 EXEC PGM=CONPARMX,PARM=(parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8)

  • CONPARMX produces an output options string from the options values in parm2 through parm6, subject to the following parameters:
    • Parm1 specifies the processor program for which the parameters are built.
    • Parm7 is optional and specifies if the parameters are concatenated. The default forces concatenation.
    • Parm8 is optional and specifies whether the parm1 processor program is invoked or if the parameters are stored for a future processor step. The default invokes the program.
  • The PARMSDEF DD statement on the CONPARMX JCL reads the options members whose names are coded in parm3, parm4, and parm5. PARMSDEF finds the matching record in each options member by matching the record to the name of the program specified in parm1. The options members contains records that start with a program name followed by a parameter string. For example, the following record matches parm1 IGYCRCTL and specifies the parameters COBOL, LANGLVL(2), and NOSOURCE:

    IGYCRCTL   ‘COBOL3,LANGLVL(2),NOSOURCE’

  • For parm3, parm4, and parm5, only the options in the matching records are used as input to building the output parameter string. Whether the options for parm3, parm4, or parm5 are included in the output parameter string depends on the parm7 concatenation specification.

Example: CONPARMX Builds a Parameter String and Invokes a Program

Sample processor step JCL for the CONPARMX utility is shown next. This JCL invokes program ASMA90 and passes a parameter string to the program.

The parameter string is built as follows:

  • The string begins with the content of &PARMA.
  • Then $$$$DFLT is read and the program name ASMA90 is searched for within the member. If there is a match for ASMA90, the options values are added to the output options string.
  • Then &C1PRGRP and &C1ELEMENare processed the same way.
  • The options values for &PARMZ are added last in the output options string.

//CONP     EXEC PGM=CONPARMX,MAXRC=4, 

//         PARM=(ASMA90,'(&PARMA)',$$$$DFLT,&C1PRGRP,&C1ELEMENT,

//         '(&PARMZ)','Y','N')

//STEPLIB  DD DSN=ASMA90.loadlib.if.required,DISP=SHR 

//PARMSDEF DD DISP=SHR,DSN=&PFX..PARMS, 

//            MONITOR=COMPONENTS

//PARMS    DD DSN=&&PPARMS,DISP=(,PASS),  

// SPACE=(CYL,(1,1)),

// DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160)

//PARMSMSG DD SYSOUT=*                 

//* Additional DD statements as required by the parm1 program

Example: CONPARMX Builds a Parameter String and Writes It to PARM DD

This example JCL builds a parameter string and writes it to PARM DD for the program IGYCRCTL.

In the JCL, see the comments to the right that identify parm1, parm2, parm6, parm7, and parm8:

//COBPROC PROC PARMTAIL=XYZ

//STEP001  EXEC PGM=CONPARMX,                    

// PARM=(IGYCRCTL,     (invocation pgm name)

// (‘ABC’),           (parm2 - constant parm data)

// $$$$DFLT,  &C1PRGRP.P, &C1ELEMENT.P, 

// '(&PARMTAIL)',      (parm6 - last parm)

// 'Y','Y')            (parm7/8 directions)

//PARMSDEF DD DSN=input.parameter.pds,DISP=SHR

//PARMS    DD DSN=&&parmout,DISP=(NEW,PASS),…

The options members specified in the JCL are as follows:

  • Parm3, $$$$DFLT, is the member that contains the default options. 
    This example assumes that parm3, $$$$DLFT, contains the following records:

    ASMA90    ‘LIST…      ‘

    IGYCRCTL ‘COBOL3,LANGLVL(2),NOSOURCE’

    IEWL ‘AMODE(31)’

    IEWL ‘RMODE(ANY)’

  • Parm4, &C1PRGRP.P, is the member that contains the processor group override parameters.
  • Parm5, &C1ELEMENT.P, is the member that contains the element override parameters.

This example JCL results in a PARMS output DD that contains the following parameter string for IGYCRCTL:

ABC

COBOL3,LANGLVL(2),NOSOURCE

Parameters defined by the Processor member

Parameters defined by the Element member

XYZ

This parameter string includes the following:

  • ABC- The constant parameter data specified by parm2.
  • COBOL3,LANGLVL(2),NOSOURCE - The record in parm3 options member $$$$DLFT found to match IGYCRCTL.
  • Parameters defined by the Processor member - The actual parameters defined by parm4, &C1PRGRP.P, would depend on the record found to match IGYCRCTL.
  • Parameters defined by the Element member - The actual parameters defined by parm5, &C1ELEMENT.P, would depend on the record found to match IGYCRCTL.
  • XYZ- The constant parameter data specified by parm6.

If parm8 in this example was N, instead of Y, the parameter string would not have been written to the PARMS output DD. Instead, IGYCRCTL would have been invoked directly with the following parameter string:

//CONPARMX EXEC PGM=IGYCRCTL,

// PARM=‘ABC,COBOL3,LANGLVL(2),NOSOURCE,

// procgrp-parms, elm-parms, XYZ’

Return Codes for CONPARMX

The following return codes can be issued during CONPARMX processing:

  • 0
    Processing successful.
  • 16
    WTO message issued with specific error condition.

All other return codes are issued by the parm1 program when called.

Options Member Syntax Rules

The options members contain the options values that can be passed by the PARM parameter to the CONPARMX utility. The syntax for the options members follows:

Column 1

V

program = 'options values[,]' [+ -] 

          ["options values[,]"] [+ -]

              .

              .

              .

          ['options values[,]'] 

  • program
    Specifies a program name and must begin in column 1.
  • options values 
    Specifies the options values that can be passed by the PARM parameter to the CONPARMX utility. The following rules apply to options values:
    • Bracketed […] elements in the syntax diagram are optional.
    • The options values can be enclosed within single or double quotes, can span multiple lines, and optionally end with a comma (,).
    • A plus sign (+) or dash (-) at the end of a line indicates continuation of the options values on the next line. Only enter one of the continuation characters.
    • An options values continuation line can begin in any column.
    • A blank in column 1 is treated as a comment line, unless the previous line contains a continuation character.
    • An asterisk (*) in column 1 always indicates a comment line and is ignored.
    • Single or double quotes can be used to enclose the options member’s options values. If an options value requires single quotes, enclose the value in double quotes. For example:

      ********************************* Top of Data **************************

      ----+----1----+----2----+----3----+----4----+----5----+----6----+----7--

      CCNDRVR = 'ARCH(5),EXPMAC,RENT,'+

              "SEARCH(//'SYS1.SIEAHDR.H'),"+  

              'RENT,' 

      ******************************** Bottom of Data ************************

    • The total length of the output options string using all options values coded for CONPARMX parm2 through parm6 must be less than 512 characters (CONPARMX limit) or the limit that is supported by the parm1 program, whichever is less.

Options Member Examples

Example: Sample Default Options Member

This example assumes this sample defaults options member:

********************************* Top of Data **************************

----+----1----+----2----+----3----+----4----+----5----+----6----+----7--

ASMA90 = 'RENT,TERM,XREF(SHORT),USING(MAP,WARN(13)),LIST(133),'

IGYCRCTL = 'OBJECT,APOST,AWO,DATA(24),FASTSRT,LIB,FLAG(W),'+

           'RESIDENT,LIST,RENT,TRUNC(BIN),'+

           'NODBCS,SOURCE,MAP,NOSEQ,XREF,NONUMBER,LIST,'

IEWL = 'LIST,MAP,RENT,REUS,NOLET,XREF,SIZE=(256K,64K),'

******************************** Bottom of Data ************************

This defaults options member would display this options string for ASMA90:

RENT,TERM,XREF(SHORT),USING(MAP,WARN(13)),LIST(133) 

It would display this options string for IGYCRCTL:

OBJECT,APOST,AWO,DATA(24),FASTSRT,LIB,FLAG(W),RESIDENT,LIST,RENT,TRUNC(BIN), NODBCS,SOURCE,MAP,NOSEQ,XREF,NONUMBER,LIST

Example: Sample Processor Group and Element Options Members

This example assumes that the parm7 value is set to Y. When parm7 is set to Y (default), for the processor group options member, the utility only includes options that are overridden from the default options member. For the element options member, the utility only includes options that are overridden from the processor group, default options members, or both.

Note: When parm7 is set to N, the utility includes all necessary options values. The options values that are first found to match the program name are used and placed in the output options string.

This example assumes this is the default options member:

********************************* Top of Data **************************

----+----1----+----2----+----3----+----4----+----5----+----6----+----7--

ASMA90 = 'RENT,TERM,XREF(SHORT),USING(MAP,WARN(13)),LIST(133),'

IGYCRCTL = 'OBJECT,APOST,AWO,DATA(24),FASTSRT,LIB,FLAG(W),'+

           'RESIDENT,LIST,RENT,TRUNC(BIN),'+

           'NODBCS,SOURCE,MAP,NOSEQ,XREF,NONUMBER,LIST,'

IEWL = 'LIST,MAP,RENT,REUS,NOLET,XREF,SIZE=(256K,64K),'

******************************** Bottom of Data ************************

This example assumes this member is the processor group options member:

********************************* Top of Data **************************

----+----1----+----2----+----3----+----4----+----5----+----6----+----7--

ASMA90 = 'NORENT,'

******************************** Bottom of Data ************************

Using this default options member with this processor group options member would result in the following output options string for ASMA90:

RENT,TERM,XREF(SHORT),USING(MAP,WARN(13)),LIST(133),NORENT

ASMA90 and most compiler programs use the last option specified if conflicting options are used. Consequently, in this example, the NORENT option overrides the RENT option specified earlier in the options list.

CONRELE Utility

The CONRELE utility allows you to include entities related to an element in a component list. The entities can be data sets, CASE entities, JCL, parameter list members, documentation members, etc. The entities do not have to be CA Endevor® SCM elements.

The CONRELE utility parses and processes input data. CONRELE accepts user syntax from the NDVRIPT DD statement. After the parsing process is complete the data is formatted as special component record types and processed with the rest of the component list. The related data portion is appended to the end of the component list. You are not required to store the input in.

Note: You must use the CONRELE utility with an active component list (the component list for the element being processed).

You must include the CONRELE utility as a processor step and you must provide the input. You can include the optional NOECHO parameter to suppress CONRELE messages from appearing in C1MSGS1 output. The following sample processor JCL executes CONRELE and suppresses the CONRELE messages:

//STEPxx   EXEC  PGM=CONRELE,PARM='NOECHO'

//NDVRIPT  DD   DSN=&user.data.set,DISP=SHR

CONRELE Utility Commands

The CONRELE utility accepts the following commands from the NDVRIPT file:

  • RELATE ELEMENT-Relates an element to another element.
  • RELATE MEMBER-Relates a data set member to an element.
  • RELATE OBJECT-Relates an object such as a pathname or a filename for an object on another platform to an element.
  • RELATE COMMENT-Adds comments to a component list.
  • SET ERROR RETURN CODE-Returns an error code when the CONRELE utility finds errors in the input syntax (default 8).

The syntax for these commands follows.

RELATE ELEMENT Command Syntax

The RELATE ELEMENT command syntax is shown next.

►►───RELate ELEment──elementname────────────────────────────────────────────►

►──¤─┬─────────────────────────────────────────┬──¤──────────────────────────►

     ├─LOCation───────────────────────────────┤

     ├─ENVironment──┬────┬──'environment-name'─┤

     │              ├─EQ─┤                     │

     │              └─=──┘                     │

     ├─SYStem──┬────┬────'system-name'─────────┤

     │         ├─EQ─┤                          │

     │         └─=──┘                          │

     ├─SUBsystem──┬────┬───'subsystem-name'────┤

     │            ├─EQ─┤                       │

     │            └─=──┘                       │

     ├─TYPe──┬────┬──'type-name'───────────────┤

     │       ├─EQ─┤                            │

     │       └─=──┘                            │

     └─STAge──┬────┬──'stage-id'───────────────┘

              ├─EQ─┤

              └─=──┘

►──┬─INPut──┬───┬─────────┬──.───────────────────────────────────────────────►◄
   └─OUTput─┘   └VALidate─┘

  • element-name
    The name of the element, maximum length of 10.
  • LOCATION
    (Optional) Location of the element-name. If you do not include the location in your syntax the location defaults to the target location of the current CA Endevor® SCM element.
    INPUT
    Input component
    OUTPUT
    Output component
  • VALIDATE
    Verifies the elements' presence at the specified location in. This is optional.
    If the element doesn't exist, the RELATEd element is rejected.
    If you specify the VALIDATE option and the validation fails, the return code is set according to the SET ERROR RETURN CODE syntax.
    • When the VALIDATE option is specified, the location names (environment, system, etc.) cannot be wildcarded. If they are omitted, the location names associated with the target element are used.
    • When the VALIDATE option is NOT specified, CONRELE stores the location information "as specified". Omitted location information is taken from the target element's location.
Note: Package component validation only validates RELATED ELEMENTS, (not members, objects or comments) which were related using the CONRELE VALIDATE option.

RELATE MEMBER Command Syntax

The RELATE MEMBER command syntax is shown next:

►►───RELate MEMber──membername──DATaset──┬────┬──data set-name──────────►

├─EQ─┤ └─=──┘

►──┬─INPut──┬───┬─────────┬──┬───────────────────┬──.────────────────────►◄
   └─OUTput─┘   └VALidate─┘  └INClude FOOtprints─┘

  • member-name
    The name of the member in a data set, the maximum member-name length is 10. A blank member is valid.
  • data set-name
    The name of the data set that contains the member-name.
    INPUT
    Input component
    OUTPUT
    Output component
  • VALIDATE
    CA Endevor® SCM determines whether the specified data set exists. This is optional.
    If you specify the VALIDATE option, CA Endevor® SCM determines whether or not the data set exists.
    If the validation fails the default SET ERROR RETURN CODE is displayed. If you do not specify the VALIDATE option no validation occurs.
  • INCLUDE FOOTPRINTS
    (Optional) If the member is footprinted, the footprint is stored in the component list.

RELATE OBJECT Command Syntax

The RELATE OBJECT command syntax is shown:

►►───RELate OBJect──object-data──.────────────────────────────────────────►◄

  • object-data
    The name of object-data. The object-data name is a maximum length of 70 bytes. The object-data is not verified. Related objects are stored in a first-in-first-out (FIFO) sequence.

RELATE COMMENT Command Syntax

The RELATE COMMENT command syntax is shown next:

►►───RELate COMment──comment-data──.────────────────────────────────────────►◄

  • Comment-data
    The comments should be enclosed in quotations marks and are stored in a first-in-first-out (FIFO) sequence. You can include an unlimited number of comments. The comments are not verified but you can search on the text.

SET ERROR RETURN CODE Command Syntax

The SET ERROR RETURN CODE command syntax is shown:

►►───SET ERRor RETurn CODe──┬────┬──error-return-code──.─────────────────────►◄

                            ├─EQ─┤

                            └─=──┘

  • error-return-code
    Specifies the error return code when the Validate option fails.
    Default: 8.

Example of CONRELE Syntax

An example of the CONRELE syntax is shown:

SET ERROR RETURN CODE 0000.

 RELATE ELEMENT BGSQL600
   LOCATION
    ENVIRONMENT = TEST
    SYSTEM   = FINANCE
    SUBSYSTEM  = AP
    TYPE    = BGLOAD2
    STAGE    = 1
   INPUT.

 RELATE ELEMENT BGSQL723
   LOCATION
    ENVIRONMENT = TEST
    SYSTEM   = FINANCE
    SUBSYSTEM  = AP
    TYPE    = BGLOAD3
    STAGE    = 1
   INPUT.

 RELATE ELEMENT BGSQL601
   LOCATION
    ENVIRONMENT = TEST
    SYSTEM   = FINANCE
    SUBSYSTEM  = AP
    TYPE    = BGLOAD2
    STAGE    = 1
   OUTPUT.

 RELATE ELEMENT BGSQL64
   LOCATION
    ENVIRONMENT = TEST
    SYSTEM   = FINANCE
    SUBSYSTEM  = AP
    TYPE    = DB2COB3
    STAGE    = 1
   OUTPUT.

 RELATE ELEMENT BGSQL65
   LOCATION
    ENVIRONMENT = TEST
    SYSTEM   = FINANCE
    SUBSYSTEM  = AP
    TYPE    = DB2COB
    STAGE    = 1
  OUTPUT
 VALIDATE.
 RELATE MEMBER BC1PSQL1
    dataset = 'JSMITH.SRCLIB'
    INPUT.

 RELATE MEMBER BGSQL60
    dataset = 'DA1BG10.DBRMLIB'
    INPUT
    VALIDATE
    INCLUDE FOOTPRINTS.
 
RELATE MEMBER BC1PSQL3
    dataset = 'JSMITH.SRCLIB'
    OUTPUT.

RELATE MEMBER BGSQL70
    dataset = 'DA1BG10.DBRMLIB'
    INPUT
    VALIDATE
    INCLUDE FOOTPRINTS.
 
RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC'.
 RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC2'.
 RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC3'.
 RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC4'.
 RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC5'.
 RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC6'.
 RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC7'.
 RELATE OBJECT 'D;\ENDEVOR\TEMP.DOC8'.
 RELATE OBJECT
'<--------------------------------------------------------------─.'
.
 RELATE COMMENT 'THIS IS A FREE FORM TEST'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST2'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST3'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST4'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST5'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST6'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST7'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST8'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST9'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST10'.
 RELATE COMMENT 'THIS IS A FREE FORM TEST11'.

CONSCAN Utility

The CONSCAN utility lets you identify additional Automated Configuration Management (ACM) relationships between CA Endevor® SCM Elements and objects contained within the element, such as data set or program names contained within a JCL jobstream or dynamic program call statements within a COBOL program.

User-defined selection criteria and scan rules are applied against the element source and CONRELE control statements are produced by the CONSCAN utility. These statements can be passed to the CONRELE utility, which updates the ACM component data for an element.

Note: For more information about the CONRELE utility, see The CONRELE Utility.

Once these relationships are established, the element display component options or the ACMQ facility can be used to view this information in addition to standard ACM input and output component data.

Although CONSCAN can be executed as a stand-alone utility, it is intended to be executed as a step in a CA Endevor® SCM processor, followed by a CONRELE step. If used as a stand-alone utility, none of the CA Endevor® SCM processor symbolic parameters (&C1ELEM, etc.) are available and the processor IF, THEN, ELSE logic cannot be utilized.

CONSCAN Parameter Data Set

A user-defined data set must be created to hold the input control parameters necessary to execute this utility. This data set must be a card image file defined as a fixed blocked file with a record length of 80. It is recommended this file be a partitioned data set (PDS).

This parameter data set contains selection criteria and scan rules. It is recommended you create one PARMSCAN member in this library for each element TYPE that utilizes the CONSCAN utility.

PARMSCAN Parameter Statements

When coding PARMSCAN statements, keep these conditions in mind:

  • All lines with an asterisk in column 1 are considered comments and are ignored.
  • Positions 2-72 are used for control statement syntax in free format.
  • Lines that end with a comma are continued.
  • Literals that contain special characters must be enclosed within single quotes.
  • Quotes within literals must be doubled.
  • Only one statement is allowed per line.

CONSCAN validates all the PARMSCAN input for proper syntax. If a syntax error is detected, a return code of 8 is returned and error messages are written to the report file.

CONSCAN does not scan any source until all the statements in the PARMSCAN input pass the syntax checking rules.

The contents of the PARMSCAN input consists of three logical parts:

  • Excluding source data
  • Selecting source data
  • Scan rule processing

Excluding Source Data

Exclusion groups define conditions that cause source data to be ignored. An unlimited number of exclusion groups are allowed per PARMSCAN member, but none are required. A COMMENT statement is used to identify the beginning of an exclusion group. A FIND statement, which defines element source exclusion criteria follows. If a match is found, the input source data is ignored. This may be the entire record or selected data within a record. An END must follow the FIND statement to identify the end of the data to be excluded and to terminate the exclusion group.

Exclusion Group Syntax

 COMMENT

 FIND1 STRING='string',POS=ANY/'nn'

 END1 CARD/STRING='string',POS=ANY/'nn'

  • COMMENT
    Indicates the beginning of an exclusion group.
  • FIND1
    Indicates the beginning of the FIND statement.
  • STRING=
    Indicates to scan this record for a string. The search is case sensitive; the search only finds a string value with a matching case.
  • 'string',
    Specified string. One to eight characters can be specified.
  • POS
    Identifies the position to search for the delimiter string.
  • ANY
    The specified string may occur anywhere in the source.
  • nn
    The specified string must occur after this position in the source.
  • END1
    END1 Indicates the end of an exclusion group.
  • CARD
    Ignore from the FIND POS to the end of the source record.
  • STRING
    Delimiter for the data to be ignored.
  • 'string',
    Indicates to include any characters following this string. 1-8 characters can be specified.
  • POS
    Identifies the position to search for the delimiter string.
  • ANY
    The specified string may occur anywhere in the source.
  • nn
    The specified string must occur after this position in the source.

Examples: Exclusion Groups

Example 1: In this assembler example, CONSCAN searches for source records containing an asterisk '*' in position 1. If found, the remainder of this record is ignored.

COMMENT

FIND1 STRING='*',POS=1

END1  CARD

Example 2: In this JCL example, CONSCAN searches for source records containing '//*' starting in position 1. If found, the remainder of the record is ignored.

COMMENT

FIND1 STRING='//*',POS=1

END1 CARD

Example 3: In this example, CONSCAN searches for source records containing a '/*' followed by a '*/' in any position of the record. If found, these characters and any characters in between are ignored.

COMMENT

FIND1 STRING='/*',POS=ANY

END1 STRING='*/',POS=ANY

Selecting Source Data

Selection groups specify the conditions that are used to select source data. An unlimited number of selection groups are allowed per PARMSCAN member. A minimum of one group is required.

These are the required statements, and they must be in order:

  1. SCANTYPE-Identifies the beginning of a selection group.
  2. FIND-Defines the element source selection criteria. One FIND statement (FIND1) is required and an optional second FIND statement (FIND2) can be specified per group. If FIND1 and FIND2 are present, both conditions must be true (treated as an AND condition) for the source data to be selected.
  3. START- Follows the last FIND statement and identifies the location of the data to extract and is placed on the generated CONRELE control statement. Only one START statement is allowed.
  4. END-Must follow the START statement to terminate the extracted string and to terminate the selection group. One END statement is required (END1) and an optional second END statement (END2) can be specified per group. If END1 and END2 are present, either condition can be true (treated as an OR condition) for the termination to take place.

If a match is found against the FIND criteria, the data specified by the START criteria is extracted. There can be more than one match per input record. CONRELE control statements are generated for each match found. These control parameters are written to the data set specified on the ACMRELE DD statement and to the report file, SCANPRT.

Selection Group Syntax

 SCANTYPE type
 FINDn keyword,
    STRING='string'POS=nn/ANY
 START TYPE=type,PARM=parm
 ENDn TYPE=type,PARM=parm

  • SCANTYPE
    Indicates the beginning of a selection group.
    • type
      Identifies the type of relationship and is used to generate the CONRELE RELATE control statements. Valid values are:
      • MEMBER
      • ELEMENT
      • OBJECT
      • COMMENT

CONSCAN attempts to determine the type of relationship existing in the data. You may have specified a type of OBJECT, but the control statements are generated with a type of COMMENT. If you specify the type MEMBER and the FIND string is 'DSN=' several checks are performed. If no member exists in the extracted string, CONSCAN determines the length of the data set name and the CONRELE control statements are generated with a type of OBJECT.

  • FIND
    Indicates the beginning of a FIND statement.
    • n
      The valid values for n are 1 or 2. FIND2 cannot exist unless FIND1 exists.

    keyword
    Optional keywords used to identify additional information related to the string. Only one keyword is allowed:
    AFTER
    Used in conjunction with the POS parameter. Directs CONSCAN to begin the search for the string after POS=nn.
    WORD
    The string must be a word surrounded by spaces, parentheses () or greater than/less than symbols >< or preceded or followed by one of the following symbols:.,;+-/*.
    REJECT
    Specified on a FIND2 statement. Allows the user to code a FIND1 and not FIND2 condition. If FIND1 and FIND2 match and REJECT is present on the FIND2 statement, the source data is ignored. For REJECT to work properly, two selection groups are required and the FIND1 statement must be identical.

    Note: For an example of the REJECT parameter, see Example 3.
  • STRING=
    Indicates to start scanning this record for a string. The search is case sensitive; the search only finds a string value with a matching case.
    'string',
    Specified string. One to eight characters can be specified.
  • POS
    Identifies the position to search for the delimiter string.
    ANY
    The specified string may occur anywhere in the source.
    nn
    The specified string must occur after this position in the source.
  • START
    Defines where to start the collection of data when the FIND criteria is true. If two FIND statements are specified and both match, the start criteria are relative to the FIND2 statement.
    • TYPE=
      Identifies the direction of the start collection. Valid values are:
      • FORW
      • BACK
      • STRG
      • DFLT
    • PARM=
      Works in conjunction with the TYPE keyword.
      • parm
        PARM defines the position to start the collection of data characters as follows:
      • After the last character found by the FIND statements when TYPE is FORW.
      • Before the first character found by the FIND statements when TYPE is BACK.
      Note: The collection of data starts at the first non-blank character.
    • END
      Indicates the START collection string delimiter. When this condition is met, the string collection is terminated.
      The valid values are 1 and 2. END2 cannot be specified unless END1 is specified. Code all END statements after the START statement. If END1 and END2 are present, they are treated as an OR condition.
    • TYPE=
      Identifies the type of delimiter.
      type
      Works in conjunction with the PARM keyword. Valid values are:
    • CHAR
    • LENG
    • SPAC
    • STRG
    PARM=
    Works in conjunction with the TYPE keyword.
    parm
    Specifies:
  • If TYPE is CHAR, which character(s) ends the collection string
  • If TYPE is LENG, the length of the collection string.
  • If TYPE is SPAC, PARM is ignored.
  • If TYPE is STRG, specifies the number of additional strings to collect after the initial string before termination of the collection. Each string must be separated by a space. For example, if a START string is detected and PARM=3 is specified, the initial string plus three additional strings are collected. CONRELE control statements are generated for each of the four strings.

Generated CONRELE Control Statements

CONRELE control card statements are generated as output from CONSCAN. This file can be fed into the CONRELE utility and added as additional component information. As described above, four types of components can be created; MEMBER, ELEMENT, OBJECT, and COMMENT. A sample CONRELE control statement output is shown next:

RELATE COMMENT
  'WS-ABEND-PGM'
.
 RELATE ELEMENT DTESUB
  LOCATION
  ENVIRONMENT = ' '
  SYSTEM = ' '
  SUBSYSTEM = ' '
  TYPE = ' '
  STAGE = ' '
  INPUT
.
 RELATE MEMBER SCANCBL
   data set='iprfx.iqual.CSIQOPTN'
   INPUT
.
 RELATE OBJECT
   'iprfx.iqual.LOADLIB'

Selection Group Examples

Example 1

In this JCL example, CONSCAN searches for source records containing data set or member names. The data set name begins in the first position after the FIND string (DSN=) and is terminated by a space or a comma.

Source Statements CONSCAN Statements CONRELE Statements

//DD DSN=SYS1.PROCS(ABC)

//DD DSN=SYS1.PROC2II

SCANTYPE MEMBER

FIND1 STRING='DSN=',

POS=ANY

START TYPE=DFLT

END1 TYPE=SPAC

END2 TYPE=CHAR,

PARM=','

RELATE MEMBER ABC

DSN='SYS1.PROCS'

INPUT.

RELATE OBJECT

DSN='SYS1.PROC2II'

Example 2

In this COBOL example, CONSCAN searches for source records containing dynamically called programs. The program name is the next word following the search string of CALL and terminated by a space or a comma.

Source Statements CONSCAN Statements CONRELE Statements

CALL DTESUB.


SCANTYPE ELEMENT

FIND1 STRING='CALL',

POS=ANY

START TYPE=DFLT

END1 TYPE=SPAC

END2 TYPE=CHAR,

PARM='.'

RELATE ELEMENT DTESUB

LOCATION

ENVIRONMENT = ' '

SYSTEM = ' '

TYPE = ' '

STAGE = ' '

INPUT.

Example 3

In this JCL example, CONSCAN searches for source records containing PROC names. This requires two selection groups. The first selection group ensures program names are not selected. The second selection group selects the processors. In both cases, the search is terminated by a space.

Note: The FIND1 statement is identical in both selection groups.
Source Statements CONSCAN Statements CONRELE Statements

//PROC EXEC NDVR

//EXEC PGM=ABC







*



SCANTYPE ELEMENT

FIND1 STRING='EXEC',

POS=ANY

FIND2 REJECT,

STRING='PGM',

POS=ANY

START TYPE=DFLT

END1 TYPE=SPAC


SCANTYPE ELEMENT

FIND1 STRING='EXEC',

POS=ANY

START TYPE=DFLT

END1 TYPE=SPAC


ELATE ELEMENT NDVR

LOCATION

ENVIRONMENT = ' '

SYSTEM = ' '

SUBSYSTEM = ' '

TYPE = ' '

STAGE = ' '

INPUT.

Example 4

In this assembler example, CONSCAN searches for source records containing links to other programs. Two FIND statements are required to identify these programs. Both conditions must be true to be selected. The search is terminated when a blank space or a comma is detected.

Source Statements CONSCAN Statements CONRELE Statements

LINK EP=CSECT1


SCANTYPE ELEMENT

FIND1 STRING='LINK',

POS=ANY

FIND2 STRING='EP=',

POS=ANY

START TYPE=DFLT

END1 TYPE=SPAC

END2 TYPE=CHAR,

PARM=','

RELATE ELEMENT CSECT1

LOCATION

ENVIRONMENT = ' '

SYSTEM = ' '

SUBSYSTEM = ' '

TYPE = ' '

STAGE = ' '

INPUT.

Example 5

In this COBOL example, CONSCAN searches for source records containing calls to program XYZ. This program requires three parameters. The goal is to capture the data associated with each parameter and generate a RELATE control statement for each. The extract is terminated after the third parameter or when the closing ')' is detected.

Source Statements CONSCAN Statements CONRELE Statements

CALL XYZ,(PARM1 PARM2)


SCANTYPE COMMENT

FIND1 STRING='XYZ,(',

POS=ANY

START TYPE=DFLT

END1 TYPE=STRG,

PARM=1

END2 TYPE=CHAR,

PARM=')'


RELATE COMMENT 'PARM1 PARM2'.

Example 6

In this COBOL example, CONSCAN searches for source records containing object names which are followed by a special comment denoting the type of object. The object name begins in the 20 positions before the FIND string (object), is 16 characters in length and is terminated by a space.

Source Statements CONSCAN Statements CONRELE Statements

SERVICE-FIND-APP OBJECT


SCANTYPE OBJECT

FIND1 AFTER,

POS=7,

STRING=' OBJ'

FIND2 AFTER,

POS=7,

STRING='OBJECT'

START TYPE=BACK,

PARM=20

END1 TYPE=LENG,PARM=16


RELATE 'OBJECT'.


Additional examples can be found in the iprfx.iqual.CSIQOPTN installation library. Assembler examples are provided in member SCANASM, COBOL examples are in SCANCBL, and JCL examples in SCANJCL.

Scan Rule Processing

The element source is read one line at a time. Each selection group defined, from top to bottom, is applied against this source line. If a match is found against a group, the FIND criteria of this group is applied to the remainder of this record to check for any additional matches. If a record contains data that matches the FIND criteria of a group, this record is not processed against any of the subsequent selection groups. By default, CONRELE control statements are only generated by one selection group.

If you want your input records to be applied against all the selection groups, regardless of the outcome of previous selection groups, code APPLY ALL as the first line of your PARMSCAN control statements. This causes the input record to be applied against each selection group within the PARMSCAN library. Therefore, CONRELE control statements may be generated for one input record by more than one selection group.

Sample CONSCAN Utility Processor

//*-------------------------------------------------------------------*

//*

//*

//* NAME: CONSCAN

//*

//* FUNCTION: SCAN THE ELEMENT BASED ON THE PARMSCAN PARAMETERS TO

//* CREATE ADDITIONAL RELATIONSHIPS. THE SCAN RULES VARY

//* DEPENDING ON THE ENDEVOR TYPE.

//*

//* ADD THE RELATIONSHIP TO THE ELEMENT COMPONENT LIST

//* USING THE CONRELE UTILITY.

//*

//* THE SRCIN DD IS ONE OF THE FOLLOWING:

//* 1) FOR FORWARD DELTAS, THIS IS CONWRITE OUTPUT OF THE ELEMENT

//* 2) FOR REVERSE DELTAS, THIS IS BASE OUTPUT LIBRARY

//*-------------------------------------------------------------------*

//*

//*********************************************************************

//** SCAN CONTENTS OF ELEMENT USING THE CONSCAN UTILITY

//*********************************************************************

//CONSCAN EXEC PGM=CONSCAN,REGION=4*96K

//*********************************************************************

//* INPUT FILES

//*********************************************************************

//SRCIN DD DISP=(OLD,DELETE),DSN=&&ELMOUT

//PARMSCAN DD DISP=SHR,DSN=iprfx.iqual.CSIQOPTN(&C1ELTYPE)

//*********************************************************************

//* OUTPUT FILES

//*********************************************************************

//ACMRELE   DD   DISP=(NEW,PASS),DSN=&&RELEIN,SPACE=(TRK,(10,5))

//SCANPRT   DD   DISP=(OLD,PASS),DSN=&&SCOUT2                   

//SYSPRINT  DD   DISP=(OLD,PASS),DSN=&&SCOUT1                   

//*

//********************************************************************

//* ADD RELATIONSHIPS TO ELEMENT COMPONENT LIST

//********************************************************************

//CONRELE    EXEC   PGM=CONRELE                    

//NDVRIPT    DD     DISP=(OLD,DELETE),DSN=&&RELEIN 

//*

Note: The SYSPRINT DD is required when running the CONSCAN JCL in a CA Endevor® SCM processor or in a batch job.

CONWRITE Utility

You can use the CONWRITE utility to write component list data or the current level of any element to an external location such as a data set or a database.

  • The standard form of CONWRITE writes the current element to a user specified data set.
  • The extended form of CONWRITE:
    • Writes component list data to an external file.
    • Processes WRITE ELEMENT control statements to write user specified elements to an external data set or USS directory.
    • Passes individual element data to a user exit program.

Both forms of CONWRITE can expand INCLUDE statements embedded in the element.

Writing Component List Data to an External Location

The CONWRITE utility provides you with the ability to take component list data and store it in an external data set or use the component list data as input to other processes. The component list can be an active component list or an existing component list. (An active component list is actively being built in memory by a processor, and may be incomplete depending on when and where you request it. If this is a delete processor, the list is taken from disk.)

You can code a CONWRITE step anywhere in any processor. For example, you can code a CONWRITE step within a move processor. The default location of the component list is the target location of the MOVE action, but you can override this default.

Note: You should be aware when retrieving an active component list that the entire component list is not available until all steps are complete.

Component List Data

CONWRITE allows you to extract and use the following component list data:

  • Input components
  • Output components
  • Symbolics
  • Related input and related output data
  • Related objects
  • Related comments
Note: Use the CONRELE utility to create related input components, related output components, related objects, and related comments before using the CONWRITE utility.

Output Format

The output format of the extracted component list data does not contain binary data. Assembler DSECTS and COBOL copy statements are provided in the output source file of the install process. In addition, COBOL layouts for the data are provided in &uprfx.SOURCE(COBCOMP), and an example of a COBOL program displaying records field by field is provided in &uprfx.SOURCE(COBCOMPX). See the following elements for the layout of external component list records:

  • $COMPDS ASMMAC
    Assembler layouts for component list data
  • COMPRECS EXAMPLE
    COBOL copy statements for component list data
  • CONCOMP EXAMPLE
    COBOL program which displays fields within component list data.

Writing Elements to an External Location

When CONWRITE writes to an external data set or USS directory, it validates the external data set record length against the maximum record length defined in the element type record. If the external data set record length is less than the element type record length, CONWRITE truncates the element data records. If the external data set record length is greater than the element type record length, CONWRITE pads the element records with spaces. In both cases CONWRITE issues a warning message and sets the step return code to four. If either circumstance is not desired then code the MAXRC or COND statement on the processor JCL to terminate the processor.

The Standard Form of CONWRITE

The standard form of CONWRITE writes to the first DD statement after the EXEC statement that does not begin with C1INCL and is not the CONWLIB or CONWIN statement. If this DD statement points to a partitioned data set without a member name coded, the element name will be used as an output member name. The CONWRITE output can be passed to a subsequent processor step such as a compiler or assembler. STEPLIB is a reserved DD name for the CONWRITE utility.

Note: The standard form of CONWRITE does not support the extraction of a component list.

The following JCL is an example of the standard form of the CONWRITE utility:

//WRITE  EXEC PGM=CONWRITE,PARM='EXPINCL(N)'
//ELMOUT   DD DSN=&&SYSIN,DISP=(NEW,PASS,DELETE)

Extended Form of CONWRITE

You can use the extended form of CONWRITE to extract elements or component list records for any CA Endevor® SCM element. CONWRITE reads WRITE ELEMENT control statements from the CONWIN DD statement to determine which elements to be extracted. You can write the output element or component list records to an external data set or you can pass it to a user specified exit program.

The following JCL is an example of the extended form of CONWRITE:

//WRITE  EXEC PGM=CONWRITE,MAXRC=4
//CONWLIB  DD DSN=user.loadlib,DISP=SHR
//CONWIN   DD *

You create copies of more than one element or component list record using the CONWIN DD statement. You can also use this statement to pass the individual element or component list records to a user exit program.

Sample JCL for using the CONWIN DD statement to extract a component list with the extended form of CONWRITE is shown next:

//WRITE   EXEC   PGM=CONWRITE
//COMPOUT   DD   DSN=&user.data.set,DISP=(NEW,PASS),UNIT=SYSDA,
//               SPACE=(TRK,(3,5),RLSE),
//               DCB=(RECFM=VB,LRECL=256,BLKSIZE=0,DSORG=PS)
//CONWIN    DD    *
  WRITE ELEMENT &c1element
     FROM ENV &c1envmnt SYSTEM &c1system SUBSYSTEM &c1subsys
          TYPE &c1eltype STAGE &c1stgid
  TO DDN COMPOUT
  OPTION COMPONENT.
 /*

Command Syntax for the CONWRITE Utility

The syntax of the CONWRITE utility is shown as follows:

►►──WRIte ELEment──element-name──────────────────────────────────────────────────────────────────►

►──FROm──ENVironment──env-name──SYStem──sys-name──SUBsystem──subsys-name──TYPe──type-name────────►

►──┬─STAge──stage-id────────┬──TO──¤──┬─────────────────────┬──¤──┬─PGM─────┬──program-name──────►

   └─STAge NUMber──stage-no─┘         ├─┬─FILe───┬──dd-name─┤     └─PROgram─┘

                                      │ └─DDName─┘          │

                                      └─MEMber──member-name─┘

►──┬───────────────────────────────────────────────────────────┬──.─────────────────────────────►◄

   └─OPTions──¤──┬─────────────────────────────────────────┬─¤─┘

                 ├─EXPand──┬──────────┬────────────────────┤

                 │         └─INCludes─┘                    │

                 └─┬─SEArch─────────────────────────────┬──┘

                   ├─COMponent──────────────────────────┤

                    └─┬─PGM─────┬──PARm─┬────┬─parameter─┘        

                      └─PROgram─┘       ├─EQ─┤

                                        └─=─┘

  • user.loadlib
    The load library where a user exit program resides.
  • program-name
    The name of a user exit program invoked for each element record. If the CONWLIB DD statement is specified the program is loaded from the library specified in the DD statement.
    On entry to the user program, R1 points to this parameter list:
    • +0-Address of a 256 byte work area. The area is initialized to zeroes for the first invocation of the exit.
    • +4-Address of a half word containing the record length.
    • +8-Address of the data record.
    • +12-Address of a 100 byte message area. The message area is set to blanks before each user program call.
    • +16-Address of the parameter specified on the 'program parm =' statement. The parameter is a halfword length field followed by the parameter string. If a 'program parm =' statement was not specified, the halfword length is set to zero.
  • parameter
    A 1- to 70-character parameter passed to the user program.
Note: When you include a CONWIN DD statement in a CONWRITE step, CONWRITE ignores PARM information in the EXEC statement for that step.

There is no limit to the number of WRITE ELEMENT statements that can be included in the CONWIN DD statement.

If a syntax error is detected in the CONWIN DD input stream, CONWRITE issues an error message. All remaining WRITE ELEMENT statements are syntax-checked, but they are not executed.

For example, if link-edit control cards are separate from programs, and you want to use these control cards in a processor, you can fetch the control cards using the extended form of CONWRITE. The following example shows how the control cards can be processed:

Note: This example uses OPTION SEARCH to fetch the current version of LINKCARD's source.

//*********************************************************************

//**  EXAMPLE OF CONWRITE EXECUTION JCL WITH CONWIN DD STMT INPUT **
//*********************************************************************
//CONWRITE EXEC PGM=CONWRITE
//*
//* ELMSRC IS A TEMPORARY DATA SET USED TO CONTAIN ELM SOURCE CODE
//*
//ELMSRC  DD DSN=&&ELMSRC,DISP=(,PASS),
//           UNIT=VIO,SPACE=(TRK,5,1),
//           DCB=(RECFM=FB,LRECL=80,BLKSIZE=0,DSORG=PS)
//*
//* LNKSRC IS A TEMPORARY DATA SET USED TO CONTAIN ELM LINK-EDIT STMTS
//*
//LNKSRC  DD DSN=&&LNKSRC,DISP=(,PASS),
//           UNIT=VIO,SPACE=(TRK,1,1),
//           DCB=(RECFM=FB,LRECL=80,BLKSIZE=0,DSORG=PS)
//CONWIN  DD *
 WRITE ELEMENT &C1ELEMENT.
     FROM ENV &C1ENVMNT. SYSTEM &C1SYSTEM. SUBSYSTEM &C1SUBSYS.
          TYPE &C1ELTYPE.  STAGE &C1STGID.
     TO  DDN ELMSRC
     OPTION EXPAND INCLUDES.
 WRITE ELEMENT &C1ELEMENT.
     FROM ENV &C1ENVMNT. SYSTEM &C1SYSTEM. SUBSYSTEM &C1SUBSYS.
          TYPE LINKCARD  STAGE &C1STGID.
     TO  DDN LNKSRC
   OPTION SEARCH.
//*
//*********************************************************************
//**  PERFORM COMPILE                       **
//*********************************************************************
//COMPILE EXEC...
//SYSIN  DD DSN=&&ELMSRC,DISP=(OLD,DELETE)
//*
//*********************************************************************
//**  PERFORM LINK-EDIT                      **
//*********************************************************************
//LINKEDIT EXEC PGM=IEWL
//SYSLIN  DD DSN=&&LNKSRC,DISP=(OLD,DELETE)

Using CONWRITE to Expand INCLUDEs

If the element source references one or more INCLUDE members, you can expand or not expand those members within CONWRITE using either of the following clauses.

PARM=EXPINCL( ) Clause

Specify PARM=EXPINCL(Y) to expand INCLUDE members; specify PARM=EXPINCL(N) if you do not want to expand the INCLUDE members. The default is PARM=EXPINCL(N).

//STEPNAME EXEC PGM=CONWRITE,PARM=EXPINCL(Y)

//DDNAME     DD DSN=&&WRITEOUT,DISP=PASS,UNIT=SYSDA,
//              SPACE=(TRK,(3,5),RLSE),
//              DCB=(RECFM=FB,LRECL=80,BLKSIZE=0,DSORG=PS) 

EXPAND INCLUDES Option within a WRITE ELEMENT Statement

//CONWIN  DD *

 WRITE ELEMENT &C1ELEMENT.
       FROM ENV &C1ENVMNT. SYSTEM &C1SYSTEM. SUBSYSTEM &C1SUBSYS.
            TYPE &C1ELTYPE.  STAGE &C1STGID.
       TO  DDN ELMSRC
   OPTION EXPAND INCLUDES.

Note: CONWIN DD statements and PARM clauses are mutually exclusive. If you code a CONWIN DD statement, CONWRITE ignores any PARM clauses in the EXEC statement for the step.

By default, CONWRITE searches the environment map for INCLUDE members in the default INCLUDE libraries for specified types. This means that when expanding INCLUDEs for a Stage 1 element, CONWRITE looks first in the Stage 1 INCLUDE library for the member, then in INCLUDE libraries in successive stages on the map. When processing a Stage 2 element, CONWRITE looks for the INCLUDE member first in the Stage 2 library, then in successive stages on the map.

Alternatively, you can use C1INCL DD statements to specify up to 99 INCLUDE libraries within the CONWRITE step of a processor. When you do this, CA Endevor® SCM accesses these statements in ascending order based on their DD names. The example below shows how to write C1INCL DD statements.

//STEPNAME EXEC PGM=CONWRITE,PARM=EXPINCL(Y)

//C1INCL01 DD DSN=include.library1,DISP=SHR
//C1INCL02 DD DSN=include.library2,DISP=SHR
//DDNAME   DD DSN=&&WRITEOUT,DISP=(NEW,PASS),
//            UNIT=SYSDA,SPACE=(TRK,(3,5),RLSE),

Note: These search rules are mutually exclusive. If you use C1INCL DD statements, CONWRITE does not search in the default INCLUDE libraries for the specified types. Also, all C1INCL DD statements must precede the CONWRITE output data set statement.

Writing Exit Programs to Use CONWRITE Input

The WRITE ELEMENT control statement allows CONWRITE to pass the output element, record by record, to a user-specified exit program. The program could, for example, process the data before the exit writes the record to an external data set. Specify the user program on the TO PROGRAM statement of the WRITE ELEMENT action. You can use the OPTION PROGRAM PARM EQ statement to pass a parameter string to the user program.

CONWRITE passes the user exit a five-word parameter list for each data record. Register 1 points to the parameter list. The parameter list and all parameters are in 24-bit addressable storage. The parameter list points to these fields:

  • A 256-byte program work area. The work area is double word aligned and is initialized to binary zeroes for the first exit call. The work area is not reinitialized between exit calls or between WRITE ELEMENT statements within a step.
  • A halfword field that contains the length of the record.
  • The element data record.
  • A 100-byte area in which the user program can place a message. The area is initialized to blanks prior to each invocation of the exit. The message is printed if the exit sets a return code of four or eight and the message area contains non-blank data.
  • The program parameter specified in the OPTION PROGRAM PARM EQ statement. The parameter is a halfword length field followed by the parameter specified. If the PROGRAM PARM EQ statement was not specified, CONWRITE sets the halfword length field to zero.

After CONWRITE processes all of the element data records, it calls the exit a final time with the record length field and the record address parameter set to zero. CONWRITE expects one of the following return codes from the user program. The return code is passed back in Register 15.

  • 0
    Normal completion. CONWRITE continues processing the element.
  • 4
    Terminate the current WRITE ELEMENT operation. CONWRITE continues with the next WRITE ELEMENT statement.
  • 8
    Terminate CONWRITE processing. CONWRITE immediately terminates with a return code of 12. If an invalid return code is received, CONWRITE immediately terminates the current step with a return code of 12.

The exit program should be link-edited with the REUS attribute.

ENUSSUTL Utility

The ENUSSUTL processor utility collects package backout information for USS processor output files. This backout information consists of backout records and backout files.

Package outputs for USS files can be transmitted to other sites using the Package Ship utility. However, the output cannot be shipped unless package backout information for USS files is available. To collect this information, the processor that is associated to the element type must include the ENUSSUTL utility to collect and associate the backout files to an element. When this utility is executed under Package processing, the utility enables these files for Package Backout and Package Ship. For more information about ENUSSUTL, see How to Enable USS Supported Files for Package Ship.

LEXTRCTR and BC1PCCSP Utilities

The CSP 4.1 generate program produces link cards that must be passed dynamically to the linkage editor during processor execution. CA Endevor® SCM for CSP uses the LEXTRCTR utility to pass these link cards.

The purpose of LEXTRCTR is to parse and capture all the pieces of a CSP application when the user is managing at the application versus the component level. BC1PCCSP then attaches the compiler for each piece of the application identified by LEXTRCTR.

Note: For an example of the use of LEXTRCTR and BC1PCCSP, see Sample Processors.
Was this helpful?

Please log in to post comments.