Reaching z/OS datasets from the UNIX shell: the //'HLQ.NAME' notation, tsocmd, and encoding tags

Goal

Copy data between a z/OS UNIX (USS) file and a classic MVS dataset from the shell, and avoid EBCDIC/ASCII corruption in the process.

Prerequisites

• A z/OS UNIX shell session (SSH, telnet, or rlogin into USS).
• Read/write authority to the target dataset (see the RACF article) and, for tsocmd, a TSO segment in the user's RACF profile.

Steps

1. To reference a classic dataset from a shell command, quote it in the //'HLQ.DATA.SET' MVS notation (without the inner single quotes, //NAME is prefixed with the user's TSO prefix, usually the user ID). For example, cp treats it like any other path argument:

   cp ./myfile.txt "//'HLQ.MYFILE'"
   

   IBM documents a gotcha that it classifies as working as designed: copying or moving a USS file to a sequential dataset with exactly the same name and case (for example cp SMPL.DATA "//'SMPL.DATA'" in the current directory) fails with FSUM6259/EDC5045I; the documented workaround is to prefix the source with ./, as in cp ./SMPL.DATA "//'SMPL.DATA'".
2. To run a TSO command instead of a dataset copy, use tsocmd "COMMAND ..." (or, on current releases, the tso utility) from the shell — for example tsocmd "LISTDS 'HLQ.MYFILE'" to check a dataset's attributes, including its record format (RECFM) and logical record length (LRECL), both of which must be compatible between source and target before a copy will produce sane output (fixed versus variable records, mismatched LRECL, and so on are common causes of truncated or garbled data, independent of any encoding issue).
3. Before moving text between USS and a dataset, check and set the file's encoding tag. z/OS UNIX files can carry a tag identifying their coded character set; classic datasets containing text are conventionally EBCDIC (commonly code page IBM-1047), while most tools an agent already knows assume ASCII/UTF-8. Use chtag -p filename to display a file's current tag, and chtag -t -c codeset filename to set one, for example chtag -t -c ISO8859-1 filename for an ASCII/Latin-1 file.
4. Automatic conversion of tagged text files is controlled by the _BPXK_AUTOCVT environment variable (ON, or ALL to include Unicode conversion; the system-wide default comes from AUTOCVT in BPXPRMxx) together with a correct tag that has the text flag set (chtag -t); without both, a "transparent" copy silently moves bytes without translating them, which looks like data corruption rather than an obvious encoding error. For an explicit, one-off conversion use iconv -f ISO8859-1 -t IBM-1047 in > out.

Expected result

A copy or transfer where record boundaries (RECFM/LRECL) and text encoding both match what the receiving side expects, verified by opening the result rather than by the copy command reporting success (a byte copy with the wrong encoding still "succeeds").

Limits and test basis

Command syntax and the FSUM6259 behavior are as documented in the cited IBM sources; verify current RECFM/LRECL values with tsocmd "LISTDS ..." on the actual datasets involved rather than assuming defaults, since a mismatch is a data problem, not a permissions problem. No experiment or measurement is claimed.