User's Guide

DITTO

Utility program to manipulate magnetic tapes and disk files

Function:

DITTO is a utility program which is used to manipulate magnetic tapes and disk files. The following list of commands are defined by DITTO:

  Name     Description                                             
  ----     -----------                                            
  ALLOC    Allocate DITTO device
  BSF      Back space files on DITTO device 
  BSR      Back space records on DITTO device 
  COPY     Copy from input device to output device
  DEALLOC  Deallocate DITTO device(s)
  DITTOX   Exit DITTO program
  DUMP     Print file contents of a DITTO device
  FSF      Forward space files on DITTO device
  FSR      Forward space records on DITTO device
  GBLS     Modify DITTO global variables
  MAPPER   Examine file structure of DITTO device
  REWIND   Rewind DITTO device
  SCAN     Scan DITTO device for a specified string
  STATUS   Display status of DITTO devices
  VERIFY   Verify file contents of DITTO devices
  WEOF     Write End-of-File marks (tape only)

DITTO error conditions are divided into three classes.

  1.  Some error messages are strictly "fatal" error 
      messages, i.e., they are determined to be fatal 
      by program design.  A fatal error condition is 
      one in which processing of the DITTO command is 
      aborted.

  2.  Some error messages are strictly set by the 
      program to be "nonfatal" error messages.  A 
      nonfatal error condition is one in which 
      processing of the DITTO command continues.

  3.  Other error messages are designed to allow 
      the user to have some control for determining 
      the handling of error conditions.  This is 
      accomplished with the global variable ERRMODE
      (parameter) in the command GBLS;  ERRMODE 
      has responses of QUERY or ABORT that allow the 
      user to determine the fate of processing with 
      error conditions.  Before any DITTO commands 
      are executed, the user would set ERRMODE to 
      strictly specify ABORT in error processing 
      conditions or to designate QUERY, thus allowing 
      the user to determine with each error condition 
      if processing should continue.  The user may 
      modify the error mode flag by executing the 
      DITTO command GBLS.

Parameters:

Examples:

  1. LAS> ditto

    The user initializes the DITTO program prior to executing the individual DITTO commands.

Description/Algorithm:

This function initializes all DITTO global variables which are used by the DITTO commands. In addition, it sets the TAE libraries so that the user has access only to the DITTO commands and TAE utility procs. The original libraries of the TAE session are reassigned when the DITTOX command is executed. DITTO must be run prior to any of the DITTO commands.

Nonfatal Error Messages:

  1. [ditto-bsf] Error back spacing files on DITTO input/output device

    This error occurs if the user tries to backspace beyond the beginning of DITTO device. The DITTO device is left positioned at file 1 of the DITTO device.

  2. [ditto-bsr] Error back spacing records on DITTO input/output device

    This error occurs if the user tries to backspace beyond the beginning of the current file. The DITTO device is left positioned at the beginning of the current file.

  3. [ditto-dclose] Error closing DITTO input/output disk file

    This error indicates the program was not able to properly close a disk file.

  4. [ditto-dfix] Input disk file does not have fixed length records.

    This error occurs if the user specifies to allocate the input DITTO device to a fixed length disk file but the existing disk file consists of variable length records. The input DITTO device is still allocated to the disk file with the variable length disk file format.

  5. [ditto-dvar] Input disk file does not have variable length records

    This error occurs if the user specifies to allocate the input DITTO device to a variable length disk file but the existing disk file consists of fixed length records. The input DITTO device is still allocated to the disk file with the fixed length disk file format.

  6. [ditto-eof] EOF detected prior to processing all records

    This error indicates that an unexpected end of file was detected prior to processing all specified records.

  7. [ditto-fsf] Error forward spacing files on DITTO kinput/output device

    This error occurs if the user tries to forward space beyond the end of DITTO device. The DITTO device is left positioned at the end of the last file of the DITTO device.

  8. [ditto-fsr] Error forward spacing record on DITTO input/ output device

    This error occurs if the user tries to forward space beyond the end of the current file. The DITTO device is left positioned at the end of the beginning of the next file.

  9. [ditto-hexdig] Two hex digits is maximum pad value

    This error indicates that the hex character string contains more than two hex digits. The left most two digits are used to compute the byte value.

  10. [ditto-hexinv] An invalid hex digit encountered

    This error indicates that the hex character string contains an invalid hex digit. Hex digits may contain the digits 0 through 9 and letters "a" through "f" or "A" through "F." Zero is assigned to the invalid hex digit.

  11. [ditto-invmod] Invalid record number -- Cannot modify specified record

    This error indicates that the specified record number cannot be modified. The user is reprompted to input a different record number. There are two causes for this error:

          a. Record has already been copied to the output device
          b. Record is not within the range of records to be copied
    

  12. [ditto-modlen] Requested to modify beyond end of record

    This error indicates that the number of bytes to be modified exceeds the record length of the current record. Only the number of bytes within the record are modified.

  13. [ditto-nalloc] The DITTO input/output device was not allocated

    This error condition informs the user that the specified DITTO device was not allocated.

  14. [ditto-tpclos] Error closing DITTO input/output tape

    An error was detected trying to close the tape device.

  15. [ditto-tprew] Error rewinding DITTO input/output device

    This error occurs if an error was detected in rewinding the DITTO device.

Fatal Error Messages:

  1. [ditto-abort] Process aborted by the user

    This is an error condition in which the DITTO command is aborted by the user when the global variable ERRMODE is set to QUERY.

  2. [ditto-alloc] The DITTO input/output device is not allocated

    This is an error condition in which the DITTO device is not allocated. The ALLOC command must be executed to allocate the device.

  3. [ditto-blksiz] Block sizes are NOT compatible

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that the program expected the input and output block sizes to be equal.

  4. [ditto-calloc] Error allocating dynamic buffer space

    This error indicates there is not sufficient memory on the system to do the specified processing.

  5. [ditto-dalloc] DITTO input/output device is not allocated to a disk file

    The user tried to reopen a DITTO device that is not allocated to a disk file.

  6. [ditto-dopen] Error opening DITTO input/output disk file

    This error indicates that the program was unable to open the specified disk file.

  7. [ditto-double] DITTO input/output device has already been allocated

    This error occurs when the user tries to allocate a DITTO input/output device that has already been allocated. The status of the DITTO device is not changed. The user must first execute the DEALLOC command to deallocate the DITTO device.

  8. [ditto-dread] Error reading record from DITTO input/output disk file

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error indicates that an error was detected when reading a record from the specified disk file.

  9. [ditto-dstat] Error retrieving attributes of input/output disk file

    This error occurs when the user specifies to allocate the DITTO device to a disk file but is unable to retrieve the file attributes. The most probable cause is that the input disk file does not exist. This error indicates the input DITTO device is not allocated.

  10. [ditto-dwrite] Error writing record to DITTO input/output disk file

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error indicates that an error was detected when writing a record to the specified disk file.

  11. [ditto-ineof] VERIFY error -- Unexpected EOF in input device

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that an end of file (EOF) was detected on the input DITTO device and an actual record was read on the output DITTO device.

  12. [ditto-modrec] DITTO command "copy-modrec" is required to run in interactive mode

    This is an error condition informing the user that the "copy-modrec" DITTO command is required to be executed in the TAE interactive mode. It cannot be executed in batch mode because it dynamically queries the user to edit the specified records within a file.

  13. [ditto-outeof] VERIFY error--Unexpected EOF in output device

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that an EOF was detected on the output DITTO device and an actual record was read on the input DITTO device.

  14. [ditto-padchr] One character is maximum pad length

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that the input parameter PAD contains more than one character. If processing is continued, the left most character is used as the pad value.

  15. [ditto-recsiz] Record sizes are NOT compatible

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that the program expected the input and output record sizes to be equal.

  16. [ditto-rectyp] Record types are NOT compatible

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that the program expected the input and output record types to be equal.

  17. [ditto-talloc] DITTO input/output device is not allocated to a tape

    The user tried to reopen a DITTO device that is not allocated to a tape device.

  18. [ditto-tpopen] Error mounting DITTO input/output tape

    An error was detected while mounting the input/output tape. The DITTO device is not allocated.

  19. [ditto-tpread] Error reading DITTO input/output tape

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that an error was detected while reading from the tape device.

  20. [ditto-tpreop] Error reopening DITTO input/output tape

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error indicates that the program was unable to reopen the specified tape device.

  21. [ditto-tpwrit] Error writing DITTO input/output tape

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that an error was detected while writing to the tape device.

  22. [ditto-uneq] VERIFY error at record X, Number bytes in input record = X, Number bytes in output record = X, Input/Output record sizes are NOT EQUAL

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that the two records being verified do not contain the same number of bytes. The error message includes the record number and the number of bytes in the input and output records. If processing continues, it tries to verify the two records.

  23. [ditto-verify] VERIFY error at record X byte offset X, Input hex value X not equal to output hex value X, Files are NOT the same

    This is an error condition in which the user has the option to continue processing by setting the error mode flag to QUERY. This error condition indicates that the two files being verified are not the same. The error message includes the record number and byte offset of where the difference occurred. It also outputs the byte values in hexadecimal format. If processing continues, the DITTO command VERIFY begins with the next byte of the current record.

User Notes:

  1. Each DITTO command is an individual TAE proc making it easy to modify or add new commands to DITTO. Even though the commands are individual TAE procs, DITTO is held together like a program with the use of TAE. Prior to running DITTO, the user does not have access to any of the commands; and after running DITTO, the user will have access to only the DITTO commands.

  2. The DITTO program and related commands must be run in a specific order: DITTO, ALLOC, other DITTO commands (by selection), DEALLOC, and DITTOX.

        o  DITTO initializes TAE global variables.  It also sets 
           the TAE libraries so that the user can only access the 
           DITTO commands, LAS world utilities, and TAE utility procs.  
           The libraries are reset to original values when the 
           DITTOX command is executed.  Note that it does not 
           allocate the input and output devices.
    
        o  ALLOC allocates the input or output DITTO device.  If the
           input device is tape, then the tape is mounted.  ALLOC 
           must be run separately to allocate input and output DITTO 
           devices, i.e., it must be run twice if both input and 
           output devices are to be allocated.
    
        o  DITTO commands (by selection) are executed to process the 
           input and/or output files on DITTO devices.
    
        o  DEALLOC deallocates the input and/or output devices.  If 
           the device is tape, then the tape is dismounted.  Note 
           that the user may continue processing by reallocating the
           input/output devices, i.e., refer to the second step again.
    
        o  DITTOX exits the DITTO program.  It deletes all global 
           variables declared by the program.  If the user did not 
           deallocate the devices, it will do so.  The original TAE 
           libraries are restored.
    

  3. A DITTO command begins processing from the current position of the input/output devices. Once the DITTO command has completed, the input/output devices are not rewound. Exceptions to this rule are stated in the user guide of the individual DITTO commands.

    A DITTO command, which writes to the output device, assumes it is writing at the end of that device. For example, if the output device is allocated to a tape, an end-of-volume mark is written to the tape after the DITTO command has completed.

  4. The DITTO utility program can be executed in batch mode. To do so, the user is required to build a TAE proc. This proc is required to invoke the individual procs of the DITTO module. For example, the following PDF file copies disk file "ny.dat" to disk file "newfile.dat." After the copy has completed, both disk files are rewound and verified.

        procedure example
        body
    
        DITTO                         ! initialize DITTO program
        ALLOC-DISK input  ny.dat      ! allocate input disk file
        ALLOC-DISK output newfile.dat ! allocate output disk file
        COPY-RECORD                   ! copy input file to output file
        REWIND both                   ! rewind DITTO devices
        VERIFY-RECORD                 ! verify input and output files
        DEALLOC both                  ! deallocate DITTO devices
        DITTOX                        ! exit DITTO program
        end-proc
    
        To execute this TAE proc in batch mode, the following command
        is made:
    
    
    LAS> example |runtype=batch|