BINARY_TEMPLATE

The BINARY_TEMPLATE function presents a graphical user interface which allows the user to interactively generate a template structure for use with READ_BINARY.

The graphical user interface allows the user to define one or more fields in the binary file. The file may be big, little, or native byte ordering.

Individual fields can be edited by the user to define the dimensionality and type of data to be read. Where necessary, fields can be defined in terms of other previously defined fields using IDL expressions. Fields can also be designated as "Verify". When a file is read using a template with "Verify" fields, those fields will be checked against a user defined value supplied via the template.

Syntax

Result = BINARY_TEMPLATE ( [Filename] [, CANCEL=variable] [, GROUP=widget_id] [, N_ROWS=rows] [, TEMPLATE=variable] )

Return Value

This function returns an anonymous structure that contains the template. If the user cancels out of the graphical user interface and no initial template was supplied, it returns zero.

Arguments

Filename

A scalar string containing the name of a binary file which may be used to test the template. As the user interacts with the BINARY_TEMPLATE graphical user interface, the user's input will be tested for correctness against the binary data in the file. If filename is not specified, a dialog allows the user to choose the file.

Keywords

CANCEL

Set this keyword to a named variable that will contain the byte value 1 if the user clicked the "Cancel" button, or 0 otherwise.

GROUP

The widget ID of an existing widget that serves as "group leader" for the BINARY_TEMPLATE interface. When a group leader is killed, for any reason, all widgets in the group are also destroyed.

N_ROWS

Set this keyword to the number of rows to be visible in the BINARY_TEMPLATE's table of fields.

TEMPLATE

Set this keyword to structure variable containing an initial template (usually from a previous call to BINARY_TEMPLATE). This template structure will be used to fill in the initial fields in the new BINARY_TEMPLATE. If TEMPLATE is specified and the user cancels out of the dialog, the specified template will be returned as the Result.

The BINARY_TEMPLATE Interface

When the BINARY_TEMPLATE function is invoked, the following dialog is displayed:

The byte order in the file is selected using the using the File's byte ordering: pull-down menu. The choices are:

Native - The type of storage method that is native to the machine you are currently running. Little Endian for Intel microprocessor-based machines and Big Endian for Motorola microprocessor-based machines. No byte swapping will be performed.

Little Endian - A method of storing numbers so that the least significant byte appears first in the number. For example, given the hexadecimal number A02B, the little endian method specifies the number to be stored as 2BA0. Specify this if the original file was created on a machine that uses an Intel microprocessor.

Big Endian - A method of storing numbers so that the most significant byte appears first in the number. For example, given the hexadecimal number A02B, the big endian method specifies the number to be stored as A02B. Specify this if the original file was created on a machine that uses a Motorola microprocessor.

Fields are read in the order in which they are listed in the main dialog for BINARY_TEMPLATE, with offsets being added to the current file position pointer before each field is read. If a field has already been defined, clicking in the Return column will toggle the value of the field between Yes and No. Fields that are not marked for return can be used for calculations by other fields in the template. At least one field must be marked Yes for return in order for the BINARY_TEMPLATE function to return a template. Click New Field... to enter the description of a new template field. The New Field dialog appears:

The Type of each Template-specified field is selected from a droplist that offers the following IDL types: byte, integer, long, float, double, complex, dcomplex, uint, ulong, long64 and ulong64. Strings are read as an array of bytes for later conversion to type STRING.

Offsets can be specified using integer values, field names, or any valid IDL expression.

An absolute integer offset specifies a fixed location (in bytes) from the beginning of the file (or the initial file position for an externally opened file).

A relative integer offset specifies a position relative to the current file position pointer after the previous field (if any) is read. Relative offsets are shown in the BINARY_TEMPLATE user interface with a preceding > or < character, to indicate a positive (>) or negative (<) byte offset.

Expressions can include the names of fields that will be read before the current field - that is, the field number of the referenced field must be lower than the field number of the field being defined.

The Verify field can contain an integer, field name, or any valid IDL expression. Only scalar fields can be verified. READ_BINARY reports an error if a verification fails.

The Number of Dimensions of a field can be set via a droplist of values 0 (scalar) to 8 (which is the maximum number of dimensions that an IDL variable can have.) The size of each dimension can be an integer, field name, or any valid IDL expression. Any of the first three dimensions of array data can also be specified to be reversed in order.

Click OK to create the new field definition, and repeat to define all necessary fields.

The BINARY_TEMPLATE function returns a structure variable containing the template. The template variable can be saved and used as the value of the TEMPLATE keyword to the READ_BINARY function:

template = BINARY_TEMPLATE(file.dat) 
Result = READ_BINARY('file.dat', TEMPLATE=template)

where file.dat is a binary data file to be read. The template variable can also be reused as the value of the TEMPLATE keyword to BINARY_TEMPLATE.