User's Guide

COPY

DITTO command ---- Copy from input device to output device

Function:

Copies files from the current position of the input device to the output device. The DITTO copy command has the capability to perform a tape-to-tape copy, tape-to-disk copy, disk-to-tape copy, or a disk-to-disk copy. If the output device is tape, an end of volume (EOV)--a double tapemark--is written and then backspaced one tapemark to ensure an EOV exists at the end of tape. If the output device is a disk file, a new file is created.

Parameters:

Subcommand -FILE:
Copies specified number of files from input device to output device. An error is generated if the output file does not have the same record and block size as the input file.

If the DITTO output device is allocated to a disk file, it is assumed that multiple disk files have been allocated, i.e., each file copied creates a disk file appended with "_x" and then the extension (e.g. NY_x.IMG), where x is an ascending file number.

NFILES(--)
Number of files. Number of files to be copied. Default is to copy all files from current position of the input device to the output device.

TRANOPT(NONE)
Translation option. Specifies the type of translation to be done when copying to the output device. Valid values are:

  = NONE:    No translation (default)
  = ASTOEB:  Convert ASCII to EBCIDIC
  = EBTOAS:  Convert EBCIDIC to ASCII
  = LOW2UP:  Convert lower-case characters to upper-case
  = UP2LOW:  Convert upper-case characters to lower-case
  = HIOFF:   Set high bit of each byte to 0
  = HION:    Set high bit of each byte to 1

The translation is performed immediately after the read.

The HIOFF and HION options are useful when transfering ASCII data to and from the PRIMOS operating system. PRIMOS stores ASCII data with the most significant bit set to 1, whereas non PRIMOS systems store ASCII data with the most significant bit set to 0.

NBYTES(0)
Number of bytes to swap. Specifies whether the data is to be byte swapped when copied to the output device. The value of swap should be set to the number of bytes for each entity of the file.

For example, with a data file containing 16-bit integer data, SWAP would be assigned a value of 2. Byte data never needs to be swapped.

Subcommand -RECORD:
Copies specified number of records of a single file from input device to output device. An error is generated if the output file does not have the same record and block size as the input file.

NRECS(--)
Number of records. The number of physical records to be copied from the current position of the input device to the output device. The default is to copy until an end of file is reached on the input device.

TRANOPT(NONE)
Translation option. Specifies the type of translation to be done when copying to the output device. Valid values are:

  = NONE:    No translation (default)
  = ASTOEB:  Convert ASCII to EBCIDIC
  = EBTOAS:  Convert EBCIDIC to ASCII
  = LOW2UP:  Convert lower-case characters to upper-case
  = UP2LOW:  Convert upper-case characters to lower-case
  = HIOFF:   Set high bit of each byte to 0
  = HION:    Set high bit of each byte to 1

The translation is performed immediately after the read.

The HIOFF and HION options are useful when transfering ASCII data to and from the PRIMOS operating system. PRIMOS stores ASCII data with the most significant bit set to 1, whereas non PRIMOS systems store ASCII data with the most significant bit set to 0.

NBYTES(0)
Number of bytes to swap. Specifies whether the data is to be byte swapped when copied to the output device. The value of swap should be set to the number of bytes for each entity of the file.

For example, with a data file containing 16-bit integer data, SWAP would be assigned a value of 2. Byte data never needs to be swapped.

Subcommand -REBLOCK:
Copies and reblocks one file from input device to output device. The record and block size currently assigned to each file are used.

NRECS(--)
Number of records. The number of physical records to be copied from the current position of the input device to the output device. The default is to copy until an end of file is reached on the input device.

TRANOPT(NONE)
Translation option. Specifies the type of translation to be done when copying to the output device. Valid values are:

  = NONE:    No translation (default)
  = ASTOEB:  Convert ASCII to EBCIDIC
  = EBTOAS:  Convert EBCIDIC to ASCII
  = LOW2UP:  Convert lower-case characters to upper-case
  = UP2LOW:  Convert upper-case characters to lower-case
  = HIOFF:   Set high bit of each byte to 0
  = HION:    Set high bit of each byte to 1

The translation is performed immediately after the read.

The HIOFF and HION options are useful when transfering ASCII data to and from the PRIMOS operating system. PRIMOS stores ASCII data with the most significant bit set to 1, whereas non PRIMOS systems store ASCII data with the most significant bit set to 0.

NBYTES(0)
Number of bytes to swap. Specifies whether the data is to be byte swapped when copied to the output device. The value of swap should be set to the number of bytes for each entity of the file.

For example, with a data file containing 16-bit integer data, SWAP would be assigned a value of 2. Byte data never needs to be swapped.

FILLVAL(00)
Fill value. Specifies the value of which short records are to be padded. A record is too short when it does not contain as many bytes as the record length for fixed-length record format.

The FILLVAL value may be specified as an ASCII character or as a hexadecimal digit. The fill value is required to be a byte value. A byte value in ASCII format is a single character, and a byte value in hexadecimal format is a maximum of two digits.

FILLTYPE(HEX)
Fill type. Specifies type of fill value. Valid values are:


  =CHAR: ASCII character
  =HEX:  Hexadecimal digit
Subcommand -MODREC:
Copies and allows the user to modify selected records. This subcommand queries the user; therefore it is required to execute this subcommand in TAE interactive mode. An error is generated if the output file does not have the same record and block size as the input file.

NRECS(--)
Number of records. The number of physical records to be copied from the current position of the input device to the output device. The default is to copy until an end of file is reached on the input device.

TRANOPT(NONE)
Translation option. Specifies the type of translation to be done when copying to the output device. Valid values are:

  = NONE:    No translation (default)
  = ASTOEB:  Convert ASCII to EBCIDIC
  = EBTOAS:  Convert EBCIDIC to ASCII
  = LOW2UP:  Convert lower-case characters to upper-case
  = UP2LOW:  Convert upper-case characters to lower-case
  = HIOFF:   Set high bit of each byte to 0
  = HION:    Set high bit of each byte to 1

The translation is performed immediately after the read.

The HIOFF and HION options are useful when transfering ASCII data to and from the PRIMOS operating system. PRIMOS stores ASCII data with the most significant bit set to 1, whereas non PRIMOS systems store ASCII data with the most significant bit set to 0.

NBYTES(0)
Number of bytes to swap. Specifies whether the data is to be byte swapped when copied to the output device. The value of swap should be set to the number of bytes for each entity of the file.

For example, with a data file containing 16-bit integer data, SWAP would be assigned a value of 2. Byte data never needs to be swapped.

Subcommand -PITS:
Copies files. If an I/O or parity error occurs, control is turned over to the operator. The operator then has the opportunity to zero fill or correct the bad data.

NFILES(--)
Number of files. Number of files to be copied. Default is to copy all files from current position of the input device to the output device.

Examples:

  1. DITTO> copy-file nfiles=2 tranopt=none

    The user has requested to copy two files from the current position of the input DITTO device to the output device. No translation is done during the copy. If the output device is a tape, an end of volume is written to the output tape and then backspaced after the copy is complete.

    Input device prior to copy:

                            file ptr.
                                |
                                v
               ---------------------------------------------------
               |        |E|          |E|        |E|           |E|E|
               | file 1 |O|  file 2  |O| file 3 |O|  file 4   |O|O|
               |        |F|          |F|        |F|           |F|F|
               ----------------------------------------------------
    

    --then after the copy, the two DITTO devices have the following characteristics. Note that the first file copied begins from the current position of the input device to the first end of file.

    Input device after copy:

                                              file ptr.
                                                  |
                                                  v
               ---------------------------------------------------
               |        |E|          |E|        |E|           |E|E|
               | file 1 |O|  file 2  |O| file 3 |O|  file 4   |O|O|
               |        |F|          |F|        |F|           |F|F|
               ----------------------------------------------------
    

    Output device after copy:

                                file ptr.
                                    |
                                    v
               ------------------------
               |      |E|         |E|E|
               |file 1|O| file 2  |O|O|
               |      |F|         |F|F|
               ------------------------
    

  2. DITTO> copy-record nrecs=5 nbytes=2

    The user has requested to copy five records from the current position of the input device to the output device. After a record is read from the input device, it is byte swapped and then written to the output device. For example:

    Input device prior to copy:

                  file ptr.
                      |
                      v
               ----------------------------------------------------
               |      |      |      |      |      |      |      |E|
               | rec 1| rec 2| rec 3| rec 4| rec 5| rec 6| rec 7|O|
               |      |      |      |      |      |      |      |F|
               ----------------------------------------------------
    

    Input device after copy:

                                                     file ptr.
                                                         |
                                                         v
               ----------------------------------------------------
               |      |      |      |      |      |      |      |E|
               | rec 1| rec 2| rec 3| rec 4| rec 5| rec 6| rec 7|O|
               |      |      |      |      |      |      |      |F|
               -----------------------------------------------------
    

    Output device after copy:

                                                file ptr.
                                                    |
                                                    v
               ----------------------------------------
               |      |      |      |      |      |E|E|
               | rec 1| rec 2| rec 3| rec 4| rec 5|O|O|
               |      |      |      |      |      |F|F|
               ----------------------------------------
    

  3. DITTO> copy-reblock fillval=" " filltype=char tranopt=ebtoas

    The user has requested to copy one file from the current position of the input device to the output device. A record is read from the input device using the block size and record size assigned to the file and converted from EBCIDIC to ASCII. The record is then written to the output file with the block size and record size assigned to the output device. If the output record is too short, the record is padded with spaces.

Description/Algorithm:

The input parameters are retrieved from the TAE parameter block. It is determined what subcommand is being executed. As specified by the subcommand, the subroutine is called to perform the copy. The COPY function copies the specified number of files or records from the current position of the DITTO input device to the DITTO output device. If the output device is tape, an EOV is written and then backspaced one tape mark to ensure an EOV exists at the end of tape. If the output device is a disk file, a new file is created. If any translation is required, it is done immediately after a record is read from the input device. The following transformations may be performed:

  ASTOEB      convert ASCII to EBCIDIC 
  EBTOAS      convert EBCIDIC to ASCII 
  LOW2UP      convert lower-case characters to upper-case 
  UP2LOW      convert upper-case characters to lower-case 
  SWAP        byte swap the data
  HIOFF       set high bit of each byte to 0
  HION        set high bit of each byte to 1

Nonfatal Error Messages:

    None.

Fatal Error Messages:

    None.

User Note:

  1. The HIOFF and HION options are useful when transfering ASCII data to and from the PRIMOS operating system. PRIMOS stores ASCII data with the most significant bit set to 1, whereas non PRIMOS systems store ASCII data with the most significant bit set to 0.