OCOPY — Copy an MVS data set member or z/OS UNIX file to another member or file

Format

   OCOPY INDD(ddname1) OUTDD(ddname2)
   BINARY | TEXT
   CONVERT(character_conversion_table | YES | NO)
   PATHOPTS (USE|OVERRIDE)
   TO1047 | FROM1047

Description

You can use the OCOPY command to copy data between an MVS™ data set and the z/OS® UNIX file system. For OCOPY, you need to use CONVERT for these two situations:

Conversion between code pages IBM-037 and IBM-1047
Conversion between ASCII and code page IBM-1047

The z/OS shell uses code page 1047, and MVS uses a country extended code page. You can convert data to or from code page 1047 while it is being copied.

If you are copying a file with double-byte data, do not use the CONVERT option.

Before using the OCOPY command, you must allocate the data set or file you are working with. When using the TSO/E ALLOCATE command or a JCL DD statement to allocate a file or data set, you can specify PATHMODE and PATHOPTS parameters along with the PATH parameter. For information about the use of these parameters with the JCL statement, see z/OS MVS JCL Reference. For information about the TSO/E ALLOCATE command, see z/OS TSO/E Command Reference.

You can use OCOPY to copy:

A member of a partitioned data set (PDS or PDSE) to a file
An MVS sequential data set to a file
A file to a member of a PDS or PDSE
A file to a sequential data set
A file to a file
A member of a PDS or PDSE to another member of a PDS or PDSE
A member of a PDS or PDSE to a sequential data set
An MVS sequential data set to another sequential data set
An MVS sequential data set to a member of a PDS or PDSE

Both INDD and OUTDD can represent an MVS data set or a file. If the source (INDD) is an MVS data set and the target (OUTDD) is a z/OS UNIX file, then OCOPY copies an MVS data set to a file; the operation is the same as the OPUT command. If the source (INDD) is a z/OS UNIX file and the target (OUTDD) is an MVS data set, then OCOPY copies a file to an MVS data set; the operation is the same as the OGET command.

Both the target and source can be an MVS data set or member of a partitioned data set, or both can be a file. This function is typically used for code page conversion.

If PATHMODE, which sets the permission bits for a new file, is specified during allocation, it is used when creating a new file. If PATHMODE is not specified during the allocation of a new file, the allocation creates a file with the default permission of 000, which means the user has no access to it.

Parameters

INDD(ddname1)

Specifies the ddname of the source. The ddname is up to 8 characters long.

OUTDD(ddname2)

Specifies the ddname of the target. The ddname is up to 8 characters long.

BINARY | TEXT

Specifies that the data to be copied is a binary file or text file.

BINARY: Specifies that the data to be copied is a binary file. The default is binary when copying a data set of undefined record format to a file.
When you specify BINARY, OCOPY operates without any consideration for <newline> characters or the special characteristics of DBCS data. For example, double-byte characters might be split between MVS data set records, or a “shift-out” state might span records.
TEXT: Specifies that the data to be copied is a text file. The default is text except when copying a data set of undefined record format to a file.
If you are using a DBCS-supported terminal, you should use TEXT. It is assumed that double-byte data in the file system includes the <newline> character in order to delineate line boundaries. Data within these lines that are delineated by <newline> characters must begin and end in the “shift-in” state.

CONVERT(character_conversion_table | YES | NO)

Specifies the character conversion table used to convert between the following:

Code pages IBM-037 and IBM-1047
The ASCII code page and IBM-1047

If this optional operand is omitted, the system copies the data without conversion.

Use this option for single-byte data only.

Specify the CONVERT value as one of the following:

character_conversion_table

Specify one of the following:

data_set_name(member_name). Specifies the name of the partitioned data set (library) and the name of the member that contains the character conversion table.
data_set_name. Specifies the name of the partitioned data set (library) that contains the character conversion table as the default member. The default member name is BPXFX000. (BPXFX000 is an alias; when shipped by IBM®, it points to BPXFX111.) A fully qualified data set name must be enclosed in single quotes.
(member_name). Specifies the name of the conversion table to be used. It is a member of a PDS. Since the data_set_name is omitted, the standard library concatenation is searched for the table. (The default library is SYS1.LINKLIB.)
The following list summarizes what you can specify when you want to convert data to a different code page when copying single-byte data:
- BPXFX100. Null character conversion table. Use this table if the square brackets at your workstation are at the same code points as the square brackets on code page 1047 (it is the default). Also use this table if you are using a DBCS terminal.
- BPXFX111. Specifies a non-APL conversion table to convert between code pages IBM-037 and IBM-1047.
- BPXFX211. Specifies an APL conversion table to convert between code pages IBM-037 and IBM-1047.
- BPXFX311. Specifies an ASCII-EBCDIC conversion table to convert between code pages ISO8859-1 and IBM-1047.

YES

Specifies that the system is to perform conversion and use the default conversion table (BPXFX000) in the system library concatenation. (BPXFX000 is an alias; when shipped by IBM, it points to BPXFX111.)

NO

Specifies that conversion not be done. NO is the same as omitting the CONVERT operand.

PATHOPTS(USE | OVERRIDE)

Specifies whether the OCOPY should use or override the PATHOPTS value specified during allocation. If the PATHOPTS is not specified in the allocation, OCOPY will open the file with the appropriate PATHOPTS.

USE: Specifies that the PATHOPTS value is to be enforced. If a file that was identified as read-only when it was allocated is identified as the output file for OCOPY, OCOPY fails. Similarly, if a write-only file is specified as the input file, OCOPY fails. USE is the default.
OVERRIDE: Specifies that the PATHOPTS value specified during allocation is to be ignored.

TO1047 | FROM1047

TO1047

Specifies that the TO section of the character conversion table is to be used. This is typically used to convert from code page IBM-037 or ASCII to code page IBM-1047.

FROM1047

Specifies that the FROM section of the conversion table is to be used. This is typically used to convert from code page IBM-1047 to code page IBM-037 or ASCII.

If the CONVERT operand is specified and this operand is omitted,

Data copied from an MVS data set to a file uses the TO1047 section of the table.
Data copied from a file to an MVS data set uses the FROM1047 section of the table.

If the CONVERT operand is specified for a copy from a file to a file or an MVS data set to an MVS data set, you must specify either TO1047 or FROM1047.

Usage notes

You can use OCOPY to copy a program object from a PDSE to the file system, and it will be executable there. If you have a load module in a partitioned data set, however, you must first use the IEBCOPY program to copy the load module from a partitioned data set to a PDSE and then subsequently use OCOPY to copy the module into the file system. The IEBCOPY converts the load module to a program object.
Note: You can use the linkage editor to put the load module directly into the file system.
An executable file copied from the file system into an MVS data set is not executable under MVS. Some required directory information is lost during the copy. See z/OS UNIX System Services User's Guide for a discussion of copying executable files.
Data sets with spanned records are not allowed.
When you are copying into an existing file, data is appended to the end of the file if OAPPEND is specified in PATHOPTS. Otherwise, the existing file is overwritten.
Copying from text files in the z/OS UNIX file system to MVS data sets:
- For text files, all <newline> characters are stripped during the copy. Each line in the file ending with a <newline> character is copied into a record of the MVS data set. You cannot copy a text file to an MVS data set in an undefined record format.
  - For an MVS data set in fixed record format: Any line longer than the record size is truncated. If the line is shorter than the record size, the record is padded with blanks.
  - For an MVS data set in variable record format: Any line longer than the largest record size is truncated and the record length is set accordingly. A change in the record length also occurs if the line is short.
Copying from binary files in the z/OS UNIX file system to MVS data sets:
- For binary files, all data is preserved.
  - For an MVS data set in fixed record format: Data is cut into chunks of size equal to the record length. Each chunk is put into one record. The last record is padded with spaces or blanks.
  - For an MVS data set in variable record format: Data is cut into chunks of size equal to the largest record length. Each chunk is put into one record. The length of the last record is equal to the length of the data left.
  - For an MVS data set in undefined record format: Data is cut into chunks of size equal to the block size. Each chunk is put into one record. The length of the last record is equal to the length of the data left.
When you copy MVS data sets to text files in the z/OS UNIX file system, a <newline> character is appended to the end of each record. If trailing blanks exist in the record, the <newline> character is appended after the trailing blanks. MVS fixed block data sets have a fixed record length, which means that trailing blanks could exist up to the end of each record.
When you copy MVS data sets to binary files in the z/OS UNIX file system, the <newline> character is not appended to the record.

Return codes

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

Examples

The following commands copy an MVS sequential data set to a z/OS UNIX file. This is text data, and there is no code page conversion.
- SYSUT1 is the ddname of the source data set, EMPLOYEE.DATA.
- PATHNAME is the ddname of the target, which is the existing file /u/admin/employee/data.
```
ALLOCATE FILE(sysut1) DATASET('employee.data')
ALLOCATE FILE(pathname) PATH('/u/admin/employee/data')
OCOPY INDD(sysut1) OUTDD(pathname) TEXT
```
The following commands copy a binary file into a member of a partitioned data set:
- BINARY is the ddname of the source file, bin/payroll. This file is in the working directory.
- MVSPDS is the ddname of the target data set member, APPL.CODES(PAYROLL)
```
ALLOCATE FILE(binary) PATH('/bin/payroll')
ALLOCATE FILE(mvspds) DATASET('appl.codes(payroll)')
OCOPY INDD(binary) OUTDD(mvspds) BINARY
```
The following commands copy system input from the MVS SYSIN data set to the file system and perform code page conversion:
- SYSIN is the ddname of the source, IBMUSR.EMPLOYEE.DATA.
- PATHNAME is the ddname of the target, /u/admin/employee/data. This file does not currently exist and is created by ALLOCATE.
- This is text data.
- The character conversion table is the default table, member BPXFX000 of the SYS1.BPXLATE data set. (BPXFX000 is an alias; when shipped by IBM, it points to BPXFX111.)
- Because this is a copy from an MVS data set to a file, the section TO1047 of the conversion table is used by default.
```
ALLOCATE FILE(sysin) DATASET('IBMUSR.EMPLOYEE.DATA')

ALLOCATE FILE(pathname) PATH('/u/admin/employee/data')
PATHMODE (sirwxu) PATHOPTS (ocreat, owronly)

OCOPY INDD(sysin) OUTDD(pathname) TEXT CONVERT((BPXFX000))
```
  (BPXFX000 is an alias; when shipped by IBM, it points to BPXFX111.)
The following OCOPY command copies data from one MVS sequential data set to another MVS sequential data set and performs code page conversion. This example shows just the OCOPY command; the necessary ALLOCATE commands are not included.
- SYSUT1 is the ddname of the source data set.
- TRANSDD is the ddname of the target data set.
- This is text data.
- The data is converted using the user-specified character conversion table and the TO1047 section of the table.
```
OCOPY INDD(sysut1) OUTDD(transdd) TEXT CONVERT('sys1.mylib(mytab)') TO1047
```