BPXCOPY: Copying a sequential or partitioned data set or PDSE member into files

Use BPXCOPY to copy sequential or partitioned data sets or PDSE members into files.

Format

JCL:
EXEC PGM=BPXCOPY,PARM='ELEMENT HEADID LINK TYPE PATHMODE SYMLINK
SYMPATH APF | NOAPF PROGCTL | NOPROGCTL SHAREAS | NOSHAREAS UID GID
SHARELIB | NOSHARELIB

Description

BPXCOPY copies a file, a sequential data set, or partitioned data set or PDSE member into a file. You can invoke BPXCOPY in several ways:

From JCL using EXEC PGM=BPXCOPY. BPXCOPY does not need the Terminal Monitor Program (TMP) to be started when it is invoked from JCL.
From LINK, XCTL, ATTACH, a TSO/E CALL command with the asis option, or by a CALL after a LOAD.

BPXCOPY provides similar function to the OPUT command, but differs from OPUT in these ways:

There is no code page conversion available.
The specified file name cannot be longer than 8 characters.
The path name of the directory that is specified cannot be longer than 255 characters.
You can define hard links to the file.
You can define symbolic links to the file.
You can set the permission access bits of the file.
You can set the extended attributes of the file.
You can set the owning UID and GID of the file.
Do not specify PATHOPTS when using the TSO/E ALLOCATE command or a JCL DD statement. It will be ignored.

A DD statement allocates a data set or file and sets up a ddname. For BPXCOPY:

The input ddname can specify an MVSMVS™ data set (either a sequential data set or a member of a partitioned data set or PDSE) or the input ddname can be the full path name of the file. When you invoke BPXCOPY from JCL, you must use SYSUT1 as the input ddname. If BPXCOPY is invoked from LINK, XCTL, or ATTACH, a TSO/E CALL command with the asis option, or by a call after a LOAD, you can specify an alternative ddname.
The output ddname is associated with the path name of the directory in which the file resides. The absolute path name for the file is this path name combined with the name specified with the ELEMENT parameter. When you invoke BPXCOPY from JCL, you must use SYSUT2 as the output ddname. If BPXCOPY is invoked from LINK, XCTL, or ATTACH, a TSO/E CALL command with the asis option, or by a CALL after a LOAD, you can specify an alternative ddname.
The message output ddname is associated with an MVS data set. The default ddname is SYSTSPRT, which typically directs messages to SYSOUT. When you invoke BPXCOPY from JCL, you must use SYSTSPRT as the message output ddname. SYSTSPRT's default LRECL is 137, with a BLKSIZE of 3155. If BPXCOPY is invoked from LINK, XCTL, or ATTACH, a TSO/E CALL command with the asis option, or by a CALL after a LOAD, you can specify an alternative ddname.
BPXCOPY invokes IKJTSOEV, which will always have an allocation for ddnames SYSTSIN and SYSTSPRT. SYSTSPRT must be allocated correctly as described in the preceding bullet and ensured that it is closed after entry to BPXCOPY. See z/OS TSO/E Programming Services for more information about the IKJTSOEV service.

Parameters

You can specify the following keyword parameters with BPXCOPY. The parameters can be separated by any delimiter (space, comma, tab, or comment (/*)).

ELEMENT(element_name)

element_name is a simple 1-to-8-character file name of the output file. The element_name specified is converted to uppercase characters.

The directory path name for the output file is specified with the PATH keyword on a JCL DD statement.

The path name of the output file consists the directory path name that is appended with the element_name.

This parameter is required.

HEADID('character_string')

An 8-byte character string, enclosed in single quotation marks, that will appear on the header of each page of output created.

This optional parameter is provided for SMP/E usage, not for a typical user.

LINK('linkname','linkname',…)

The names of hard links to the file. Each linkname is concatenated with the output directory path name. On the JCL DD statement for the directory, the maximum length for a path name (before concatenation) is 255 characters. Path names with a length of up to 1023 characters can be specified only if BPXCOPY is invoked from LINK, XCTL, or ATTACH, a TSO/E CALL command, or by a CALL after a LOAD.

If you specify this parameter, you create one or more hard links to the file when the data is copied into a file. The linkname must be enclosed in single quotation marks. You can specify up to 64 linknames, and each must be enclosed in single quotes. Specifying LINK is optional.

SYMLINK('linkname','linkname',…)

The names of symbolic links to the file. Each linkname is concatenated with the output directory path name. On the JCL DD statement for the directory, the maximum length for a path name (before concatenation) is 255 characters. Path names with a length of up to 1023 characters (after concatenation) can be specified if BPXCOPY is involved from LINK, XCTL, or ATTACH, a TSO/E CALL command, or by a CALL after a LOAD.

If you specify this parameter, you create one or more symbolic links to the file. The linkname must be enclosed in single quotation marks. You can specify up to 64 linknames, and each must be enclosed in single quotation marks. Specifying SYMLINK is optional. If you specify SYMLINK, you must also specify SYMPATH.

SYMPATH('path name','pathname',…)

The path names of the file for which the symbolic link is created. Each path name may be an absolute path name (beginning with a slash) or a relative path name (not beginning with a slash). When an absolute path name is used, the symbolic link will be resolved starting at the root directory. When a relative path name is used, the symbolic link will be resolved starting at the parent directory of the symbolic link.

For JCL, the maximum length for a path name is limited by the 100 character limit on the entire PARM string (including other parameters) on the EXEC statement. Path names with a length of up to 1023 characters can be specified if BPXCOPY is invoked from LINK, XCTL, or ATTACH, a TSO/E CALL command, or by a CALL after a LOAD.

Specifying SYMPATH is optional, but if you specify SYMPATH, you must also specify SYMLINK. Each SYMLINK linkname must be matched with a corresponding SYMPATH path name. The first linkname define a symbolic link to the first path name, the second linkname defines a symbolic link to the second path name, and so on. If there are fewer path names than linknames, the last path name is used for the remaining linknames.

PATHMODE (mode_bits)

Changes the access permissions, or modes, of the specified file or directory. Modes determine who can read, write, or search a directory. The bits are used to set execution and permission access of the output file. On BPXCOPY, you can specify PATHMODE as an absolute mode; it must consist of four octal numbers that are separated by commas or blanks.

Absolute modes are four octal numbers specifying the complete list of attributes for the files. Specify attributes by ORing together the bits for each octal number.

4,0,0,0   Set-user-ID bit
2,0,0,0   Set-group-ID bit
1,0,0,0   Sticky bit
0,4,0,0   Individual read
0,2,0,0   Individual write
0,1,0,0   Individual execute (or list directory)
0,0,4,0   Group read
0,0,2,0   Group write
0,0,1,0   Group execute
0,0,0,4   Other read
0,0,0,2   Other write
0,0,0,1   Other execute

Specifying PATHMODE is optional.

For more information about permission bits, see the chmod command.

TYPE (TEXT|BINARY)

The format for the file. The default is BINARY for U-format data sets and TEXT for all others. (U-format means undefined-length records.) Specifying TYPE is optional.

APF|NOAPF

Specifies whether the APF extended attribute is set or unset. When this attribute is set (APF) on an executable program file (load module), it behaves as if loaded from an APF-authorized library. For example, if this program is exec()ed at the job step level and the program is linked with the AC = 1 attribute, the program is executed as APF-authorized.

To be able to set APF, you must have at least READ access to the BPX.FILEATTR.APF resource in the FACILITY class.

Specifying APF or NOAPF is optional. If not specified, the attribute is defined as NOAPF.

PROGCTL|NOPROGCTL

Specifies whether the PROGCTL extended attribute is set or unset. When this is set (PROGCTL) on an executable program file (load module), it causes the program to behave as if an RDEFINE had been done for the load module to the PROGRAM class. When this program is brought into storage, it does not cause the enviroment to be marked dirty.

To be able to set PROGCTL, you must have at least READ access to the BPX.FILEATTR.PROGCTL resource in the FACILITY class.

Specifying PROGCTL or NOPROGCTL is optional. If not specified, the attribute is defined as NOPROGCTL.

SHAREAS | NOSHAREAS

Specifies whether the SHAREAS extended attribute is set or unset. When this attribute is set (SHAREAS) on an executable program file (load module), the _BPX_SHAREAS environment variable is honored when the file is spawn()ed. When this attribute is not set (NOSHAREAS), the _BPX_SHAREAS environment variable is ignored when the file is spawn()ed.

Specifying SHAREAS or NOSHAREAS is optional. If not specified, the attribute will be defined as SHAREAS.

SHARELIB | NOSHARELIB

Specifies whether the st_ShareLib extended attribute is set or unset in the target file.

Note: In order to use BPXCOPY with this keyword parameter, you must have at least READ access to the BPX.FILEATTR.SHARELIB resource in the FACILITY class.

UID(owner)

Specifies the owner of the file. Owner can be a user name or a numeric user ID (UID). However, if a numeric owner exists as a user name in the user data base, the UID number associated with that user name is used.

Specifying the UID is optional. If it is not specified, the UID of the user running BPXCOPY is used.

These requirements must be met when specifying the UID:

To be able to set the UID of the file, the user must have UID 0 or have at least READ access to the BPX.SUPERUSER resource in the FACILITY class.
The UID must be known to the system.
If a mixed case user name is specified, it must be enclosed in single quotation marks.

GID(group)

Specifies the group owner of the file. group can be a group name or a numeric group ID (GID). However, if a numeric group exists as a group name in the group data base, the GID number associated with that group name is used.

Specifying the GID is optional. If it is not specified, the GID of the directory path name is used.

These requirements must be met when specifying the GID:

To be able to set the GID of the file, the user must have UID 0 or have at least READ access to the BPX.SUPERUSER resource in the FACILITY class.
If a mixed case user name is specified, it must be enclosed in single quotation marks.

Return codes

0: Processing successful
12: Processing unsuccessful. An error message has been issued.

Examples

JCL and BPXCOPY are used to copy a PDSE member into a directory. These facts are known:
- The name of the PDSE member is REGEREX.
- The directory name is /u/turbo/llib.
- Output messages are to be directed to SYSOUT.
- Type of data: binary.
```
//TEST JOB MSGLEVEL=(1,1)
//STEP EXEC PGM=BPXCOPY,
//  PARM='ELEMENT(REGEREX) LINK("../erex") TYPE(BINARY)'
//SYSUT1   DD DSN=TURBO.LOADLIB(REGEREX),DISP=SHR
//SYSUT2   DD PATH='/u/turbo/llib'
//SYSTSPRT DD SYSOUT=*
```
The LINK name is concatenated with the directory name from SYSUT2, yielding /u/turbo/llib/../erex. The file system treats this as /u/turbo/erex, making this an alias for /u/turbo/llib/REGEREX.
JCL and BPXCOPY are used to copy a PDS member into a directory. These facts are known:
- The name of the PDS member is TABLE1.
- The directory name is /u/carbon/data.
- Output messages are to be directed to SYSOUT.
- Type of data: text.
```
//TEST JOB MSGLEVEL=(1,1)
//STEP EXEC PGM=BPXCOPY,
//  PARM='ELEMENT(TABLE1) TYPE(TEXT) PATHMODE(0,7,6,4)'
//SYSUT1   DD DSN=CARBON.DATA(TABLE1),DISP=SHR
//SYSUT2   DD PATH='/u/carbon/data'
//SYSTSPRT DD SYSOUT=*
```
The file /u/carbon/data/TABLE1 is created, with read, write, and execute authority for the user; read and write authority for the group; and read authority for other users.

A member of an MVS partitioned data set is copied to a file from a program using the LINK macro. These facts are known:

The ddname of the source: INDD. INDD can be any sequential data set and is defined by an ALLOCATE command that is issued outside the program.
The ddname of the directory to copy into: OUTDD. OUTDD can be any directory name and is defined by an ALLOCATE command that is issued outside the program.
Three link names (DATA, link1, and link2) for the target file.
Output messages are directed to SYSOUT.
Type of data: text.

*
COPYEX   CSECT
         STM   14,12,12(13)            Entry linkage
         LR    12,15
         USING COPYEX,12
         LA    10,SAVEAREA
         ST    10,8(13)
         ST    13,SAVEAREA+4
         LR    13,10
*
         LINK  EP=BPXCOPY,PARAM=(OPT_LIST,DD_LIST),VL
*
         L     13,SAVEAREA+4           Exit linkage
         L     14,12(13)
         LM    0,12,20(13)
         BR    14
*
SAVEAREA DS    18F
*
OPT_LIST DC    H'80'                   Length of option string
         DC    CL80'ELEMENT(DATA) HEAD(''0001'') TYPE(TEXT)           X
               LINK('link1'', ''link2'')'
*
DD_LIST  DC    H'72'                   Length of DDNAME list
         DC    XL56'0'
         DC    CL8'INDD'               Logical SYSUT1  input
         DC    CL8'OUTDD'              Logical SYSUT2  output directory
*
         END   COPYEX

JCL and BPXCOPY are used to copy a file to another file.
```
//TEST JOB MSGLEVEL=(1,1)
//STEP EXEC PGM=BPXCOPY, 
//     PARM='ELEMENT(PROGINFO) TYPE(TEXT) PATHMODE(0,7,4,4)'
//SYSUT1        DD  PATH='/u/dept/data/proginfo'
//SYSUT2        DD  PATH='/u/program'
//SYSTSPRT   DD SYSOUT=*
```
There is no inheritance of file attributes, path mode, links, or symbolic links. This information is determined from the input parameter to BPXCOPY, not from the source file.