COPY_LUN

The COPY_LUN procedure copies data between two open files. It allows you to transfer a known amount of data from one file to another without needing to have the data available in an IDL variable. COPY_LUN can copy a fixed amount of data, specified in bytes or lines of text, or it can copy from the current position of the file pointer in the input file to the end of that file.

COPY_LUN copies data between open files. To copy entire files based on their names, see the FILE_COPY procedure. To read and discard a known amount of data from a file, see the SKIP_LUN.

Examples

Copy the next 100000 bytes of data between two files:

COPY_LUN, FromUnit, ToUnit, 100000

Copy the next 8 lines of text between two files:

COPY_LUN, FromUnit, ToUnit, 8, /LINES

Copy the remainder of the data in one file to another, and use the TRANSFER_COUNT keyword to determine how much data was copied:

COPY_LUN, FromUnit, ToUnit, /EOF, TRANSFER_COUNT=n

Copy the remaining lines of text from one file to another, and use the TRANSFER_COUNT keyword to determine how many lines were transferred.

COPY_LUN, FromUnit, ToUnit, /EOF, /LINES, TRANSFER_COUNT=n

Syntax

COPY_LUN, FromUnit, ToUnit [, Num] [, /EOF] [, /LINES] [, /TRANSFER_COUNT]

Arguments

FromUnit

An integer that specifies the file unit for the file from which data is to be taken (the source file). Data is copied from FromUnit, starting at the current position of the file pointer. The file pointer is advanced as data is read. The file specified by FromUnit must be open, and must not have been opened with the RAWIO keyword to OPEN.

ToUnit

An integer that specifies the file unit for the file to which data is to be written (the destination file). Data is written to ToUnit, starting at the current position of the file pointer. The file pointer is advanced as data is written. The file specified by ToUnit must be open for output (OPENW or OPENU), and must not have been opened with the RAWIO keyword to OPEN.

Num

The amount of data to transfer between the two files. This value is specified in bytes, unless the LINES keyword is specified, in which case it is taken to be the number of text lines. If Num is not specified, COPY_LUN acts as if the EOF keyword has been set, and copies all data in FromUnit (the source file) from the current position of the file pointer to the end of the file.

If Num is specified and the source file comes to end of file before the specified amount of data is transferred, COPY_LUN issues an end-of-file error. The EOF keyword alters this behavior.

Keywords

EOF

Set this keyword to ignore the value given by Num (if present) and instead transfer all data between the current position of the file pointer in FromUnit and the end of the file.

Note: If EOF is set, no end-of-file error is issued even if the amount of data transferred does not match the amount specified by Num. The TRANSFER_COUNT keyword can be used with EOF to determine how much data was transferred.

LINES

Set this keyword to indicate that the Num argument specifies the number of lines of text to be transferred. By default, the Num argument specifies the number of bytes of data to transfer.

TRANSFER_COUNT

Set this keyword equal to a named variable that will contain the amount of data transferred. If LINES is specified, this value is the number of lines of text. Otherwise, it is the number of bytes. TRANSFER_COUNT is primarily useful when the Num argument is not specified or the EOF keyword is present. If Num is specified and the EOF keyword is not present, TRANSFER_COUNT will be the same as the value specified for Num.

Version History

5.6	Introduced