OGET — Copy z/OS UNIX files into an MVS data set

Format

OGET  'pathname'
      mvs_data_set_name | mvs_data_set_name(member_name)
      BINARY | TEXT
      CONVERT(character_conversion_table | YES | NO)

Description

You can use the OGET command to copy a z/OS® UNIX file:

To a member of an MVS™ partitioned data set (PDS or PDSE)
To an MVS sequential data set

and convert the data from code page 1047 to code page IBM-037 or ASCII while it is being copied. Do not use the CONVERT option when copying files that contain double-byte data. This option is used for single-byte data only, not for double-byte data.

Parameters

pathname

Specifies the path name of the file that is being copied to a data set. This operand is required. The path name is:

A relative or absolute path name. A relative path name is relative to the working directory of the TSO/E session (usually the HOME directory). Therefore, you should usually specify an absolute path name.
Up to 1023 characters long.
Enclosed in single quotation marks.
In uppercase or lowercase characters, which are not changed by the system.

mvs_data_set_name | mvs_data_set_name(member_name)

Specifies the name of an MVS sequential data set or an MVS partitioned data set member to receive the file that is being copied. One of these two operands is required. The data set name is:

A fully qualified name that is enclosed in single quotation marks, or an unqualified name
Up to 44 characters long
Converted to uppercase letters by the system

BINARY | TEXT

Specifies whether the file being copied contains binary data or text.

BINARY: Specifies that the file being copied contains binary data.
When you specify BINARY, OGET 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 file being copied contains text. This is the default.
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 that the data being copied is to be converted from IBM-1047 to IBM-037 or ASCII. This operand is optional. If 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 (PDS) and the name of the member that contains the character conversion table.
data_set_name. Specifies the name of the partitioned data set (PDS) that contains the character conversion table. The table is the FROM1047 part in member BPXFX000. (This is an alias; when shipped by IBM®, it points to BPXFX111.)
(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 standard 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.

Do not use the CONVERT parameter on files containing double-byte data. double-byte data in the file system is in code page 939. If you need to convert to a code page other than 939, you use the iconv command.

Usage notes

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; the record length is set to the length of the line. A change in the record length also occurs if the line is short.
For text mode transfer, if the line is longer than the record size, the line is truncated (for DBCS, perhaps in the middle of a double-byte character or in “shift-in” state). If the line is shorter than the record size, the record is padded with blanks.
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.
For binary mode transfers, double-byte characters might be split between MVS data set records, or a “shift-out” state might span records.
If the MVS data set does not exist, OGET allocates a new data set, a sequential data set of variable record format. However, OGET does not allocate a new partitioned data set. The record length of the new data set is either 255 or the size of the longest line in the z/OS UNIX file system file, whichever is larger. Dynamic allocation services determine the block size and space, based on installation-defined defaults. If the defaults are not sufficient, you should allocate a new MVS data set and then specify it on OGET.
A simple method of allocating a sufficient size is to specify a primary extent size and a secondary extent size equal to the number of bytes in the file being copied.
An executable file copied into an MVS data set is not executable under MVS, because some required directory information is lost during the copy to the partitioned data set.
Data sets with spanned records are not allowed.
If you are using a DBCS-supported terminal, the target MVS data set should be defined or defaulted to variable record format. The record length of the data set must be greater than or equal to the longest line in the z/OS UNIX file system file. (OGET can determine how long the longest line is if you ask it to allocate the target data set.)
OGET cannot be used to copy a load module out of a partitioned data set and into a file system. You have to use a binder to "flatten" the load module. For more information about copying load modules, see z/OS UNIX System Services User's Guide

Return codes

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

Examples

The following command copies a text file to an MVS sequential data set, converting from code page 1047 to code page IBM-037 using the default table BPXFX000. (BPXFX000 is an alias; when shipped by IBM, it points to BPXFX111.)
- The path name of the file is /u/admin/employee/data.
- The unqualified name of the sequential data set is EMPLOYEE.DATA.
```
OGET '/u/admin/employee/data' EMPLOYEE.DATA TEXT CONVERT(YES)
```
The following command copies a text file to an MVS sequential data set, converting from code page 1047 to code page IBM-037 using conversion table BPXFX111 in the user's library data set.
- The path name of the file is /u/admin/employee/data.
- The fully qualified name of the sequential data set is IBMUSR.EMPLOYEE.DATA.
```
OGET '/u/admin/employee/data' 'IBMUSR.EMPLOYEE.DATA'
         CONVERT('MY.LOADLIB(BPXFX111)')
```