Usage notes for BCL statements

The following are additional usage notes for BCL statements.

PDS members are referenced as a sequential file.

The following references must be made in two separate BCL steps when a partitioned data set is referenced with a specific PDS member to be accessed as a sequential file (see note 1 in the example) and when that member is uploaded (see note 2 in the example) from the remote build client (distributed system):

Reference to the upload target (PDS without the member specification)

Reference to the specific member (S1ALLOC and S2COMP in the following example)

//S1ALLOC EXEC PGM=IEFBR14 
//TEMP1 DD DSN=&HLQ..CBL,RCCEXT=CBL,  <--- note 2 
// DISP=SHR 
//* if a new dataset, comment out DISP=SHR above and uncomment statements below 
//* DISP=(NEW,CATLG,DELETE),SPACE=(CYL,(1,5,10)),UNIT=VIO, 
//* DCB=(RECFM=FB,DSORG=PO,LRECL=80,BLKSIZE=23440) 
//* other PDS allocations as required //S2COMP EXEC PGM=IGYCRCTL 
//* --> other BCL statements for compile 
//SYSIN DD DISP=OLD,DSN=&HLQ..CBL(&MBR)                           <--- note 1

BCL statements containing substitution strings cannot contain comments.
A null statement (// without parameter) must have spaces in columns 73 - 80.
Data set concatenation must not occur at the end of BCL statements.
If a data set concatenation is specified as the last statement within a BCL statement, the data sets are not recognized (except for the first one in the concatenation). This applies only if it is the last statement within the BCL.

If it the data set concatenation not the last statement, the concatenation is handled properly.

Example:
In this example the SYSLIN concatenation is not processed correctly.
```
//S3LINK EXEC …
…
//SYSLIN DD DSN=LINK.CNTL.CARDS,DISP=SHR
//         DD DSN=YOUR.SOURCE,DISP=SHR 
```
Example:
In this example, the SYSLIN concatenation is processed properly.
```
//LKEDCS    EXEC … 
… 
//SYSLIN    DD  DISP=SHR,DSN=USERLIB1.PLKLIB 
//          DD  DISP=SHR,DSN=SYS2.SYSEXEC(INDB2CIC) 
//          DD  DISP=SHR,DSN=SYS2.SYSEXEC(INCICSCM) 
//          DD  DISP=SHR,DSN=SYS2.SYSEXEC(INCICSDB) 
//          DD  DISP=SHR,DSN=USERLIB1.TEST.LOADNAME(&MEM) 
… 
//SYSUT1    DD  UNIT=SYSDA,SPACE=(1024,(50,50))
```
The first data set in a concatenation must have the largest block size
When concatenating data sets with different block sizes (BLKSIZE), the one with the largest block size must be the first data set in the concatenation. One work around for this is to allocate a dummy data set with a large (equal to or larger than the largest block sizes of data sets in the concatenation) data set and to place it as the first data set in the concatenation.
The maximum number of data sets for one concatenation is 64.

For a continued parm string that is enclosed in apostrophes, do not add an apostrophe at the end of a continuing statement or at the beginning of the continued statement .

Example

The following PARM statement will not be processed correctly.

//S2COMP      EXEC PGM=IGYCRCTL, 
//             PARM=('AWO,NOC(E),LIB,MAP,BUF(128K),', 
//             'DATA(31),OFF,OPT,VBREF,XREF,QUOTE', 
//             '')

The following PARM statement does process correctly:

//S2COMP      EXEC PGM=IGYCRCTL, 
//             PARM=('AWO,NOC(E),LIB,MAP,BUF(128K), 
//             DATA(31),OFF,OPT,VBREF,XREF,QUOTE')

Issuing DB2® binds

When issuing DB2 binds, using a DBRM library causes an allocation failure. This is because of the way DB2 tries to read or allocate the library and because the BCL is running under its own address space (as a child task running under the CC z/OS® Extension remote build server [started task]).

To avoid this problem, use DB2 library statements within the actual Bind commands

Example:

//STEP1     EXEC PGM=IKJEFT01
//SYSPRINT  DD SYSOUT=*
//SYSTSPRT  DD RCCEXT=RCCSTD,
//          DSNAME=USERID.&USR..BINDLST.PACKAGE,
//          DISP=(NEW,CATLG),DCB=(RECFM=VB,LRECL=240,BLKSIZE=3210), 
//          SPACE=(32000,(30,30)) 
//SYSUDUMP  DD SYSOUT=* 
//SYSTSIN   DD *
DSN SYSTEM(&SUBSYS)
 BIND PACKAGE (&SUBSYS..&PACKNM)     -
     LIB('USERID.TEST.USR.DBRM')    -	   <--- Lib statements
     LIB('USERID.TEST.USR.DBRMLIB')    -	<--- Lib statements
     OWNER(&PACKNM)     -
     MEMBER(&MBR)     -
     QUALIFIER(&PACKNM)     -
     SQLERROR(NOPACKAGE)     -
     VALIDATE(BIND)     -
     FLAG(I)     -
     ISOLATION(CS)     -
     RELEASE(COMMIT)     -
     EXPLAIN(YES)     -
     CURRENTDATA(NO)     -
     DYNAMICRULES(BIND)     -
     ACTION(REPLACE)     -
     ENABLE(*)

The temporary PASS dataset can only be referenced one time.
In the following example, &&LOADSET is referenced by both STEP2 and STEP3. But only STEP2 can execute successfully, and STEP3 will fail because &&LOADSET will be freed after STEP2 execution completes.
Example:
```
//STEP1 PGM=XXX
//DD1 DD DSN=XXX.XXXX,DISP=XXX
//DD2 DD DSN=&&LOADSET,DISP=(NEW,PASS),
//       DCB=(...),...
...
//STEP2 PGM=XXX
//DD3 DD DSN=&&LOADSET,DISP=SHR
//DD4 DD ...
...
//STEP3 PGM=XXX
//DD5 DD DSN=&&LOADSET,DISP=SHR
...
//
```
Dataset attributes should be specified consistently for the temporary PASS dataset.
To define a temporary PASS dataset as a sequential data set, specify DSN=&&X with SPACE=(xx,(xx,xx));
To define a temporary PASS dataset as a partitioned data set, specify DSN=&&X(MEMBER) with SPACE=(xx,(xx,xx,xx));
Example:
Specify the sequential data set as follows:
```
//STEP1 PGM=xxx
//DD1 DD DSN=&&X,SPACE=(CYL,(5,1))
...
//
```
Specify the partitioned data set as follows:
```
//STEP1 PGM=xxx
//DD1 DD DSN=&&X(MEMBER),SPACE=(CYL,(5,1,10))
...
//
```
A temporary PASS dataset with an undefined record format will still have the limitation where the DD name for PASS DD can not be reused in subsequent steps.
In the following example, DD1 in STEP2 will have a dataset allocation error due to the DD name in use, because DD1 in STEP1 is specified with RECFM=U.
Example:
```
//STEP1 PGM=XXX
//DD1 DD DSN=&&LOADSET(MEM1),DISP=(NEW,PASS),
//       DCB=(RECFM=U,LRECL=0,BLKSIZE=32760),
//       SPACE=(CYL,(1,5,10))
//DD2 DD ...
//STEP2 PGM=XXX
//DD3 DD DSN=&&LOADSET,DISP=SHR
//DD1 DD DSN=XXX.XXX,DISP=SHR
//
```