Preamble Records

Preamble records must appear first in the file and typically describe the properties of the file, rather than the data itself. This metadata includes when the file was saved and by whom, and which version of IDL wrote it. By observation there appears to be an established order for these records to appear in a file, but it is not known whether this ordering is required or merely the default. The order appears to be:

Format: TIMESTAMP (10) (timestamp and user information)

Type	Name	Description
RHDR	HDR	Block header record
LONG $\times$ 256	--	Unknown ( = LONARR(256))
STRING	DATE	Date session was saved, as a string.
STRING	USER	User name of saved session.
STRING	HOST	Host name of saved session.

NOTES: The TIMESTAMP record always appears to come first. Depending on the host operating system, the ``user'' and ``host'' fields may be empty or contain unreliable data. The format of the DATE field appears to be ``WWW MMM DD hh:mm:ss YYYY'' where the WWW is an abbreviation of the name of the day of the week, MMM is an abbreviation of the month name, DD is the day of the month, YYYY is the calendar year, and ``hh:mm:ss'' is the 24-hour time.

Format: VERSION (14) (version information)

Type	Name	Description
RHDR	HDR	Block header record
LONG	FORMAT	Save file format version number
STRING	ARCH	Architecture of saved session (= !VERSION.ARCH)
STRING	OS	OS of saved session (= !VERSION.OS)
STRING	RELEASE	IDL version of saved session ( = !VERSION.RELEASE)

NOTES: The VERSION record type can be used to determine which version of IDL, and which OS was used to write a particular save file. It does not appear in files generated by IDL 4. The FORMAT entry is a file format version number, which appears to be incremented when the file format is changed. The following table describes the IDL software version where a given FORMAT value first appeared.

FORMAT value	IDL Version
5	5.3(?)
6	5.4(?)
7	5.6
8	6.0
9	6.1

Format: PROMOTE64 (17) (signals start of RHDR64 record headers)

Type	Name	Description
RHDR	HDR	Block header record

NOTES: Any records which appear after this record will have RHDR64 record headers in place of RHDR records. This record is not mandatory, and only appears in files generated by IDL version 5.4 or later.

Format: IDENTIFICATION (13) (provides author information)

Type	Name	Description
STRING	AUTHOR	Author of save file
STRING	TITLE	Title of the save file
STRING	IDCODE	Other author information

NOTES: This record is optional, and appears to provide more definitive information about who saved the IDL file. [ This may be more useful for SAVE files which contain compiled procedures and functions. ] There appears to be no direct way for users to specify this information from the built-in IDL SAVE command, but there does seem to be some connection to the EMBEDDED keyword to SAVE, and the creation of embedded-license save files.

Format: HEAP_HEADER (15) (heap data table of contents)

Type	Name	Description
LONG	NVALUES	Number of heap values in SAVE file
LONG $\times$ NVALUES	INDICES	Indices of heap values

NOTES: This record appears only if the file contains heap data, which is data pointed to by IDL pointers. Pointers are available only in IDL version 5.0 or later. The HEAP_HEADER record is merely a table of contents record which describes how many heap values there are, and lists there numerical index values. The use of the heap index values is described later in this document.

Format: NOTICE (19) (disclaimer notice)

Type	Name	Description
STRING	TEXT	ASCII text of disclaimer notice