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.
Result = BINARY_TEMPLATE ( [Filename] [, CANCEL=variable] [, GROUP=widget_id] [, N_ROWS=rows] [, TEMPLATE=variable] )
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.
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.
Set this keyword to a named variable that will contain the byte value 1 if the user clicked the "Cancel" button, or 0 otherwise.
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.
Set this keyword to the number of rows to be visible in the BINARY_TEMPLATE's table of fields.
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.
When the BINARY_TEMPLATE function is invoked, the following dialog is displayed:
The Template Name is optional, and can be any string.
The byte order in the file is selected using the using the File's byte ordering: pull-down menu. The choices are:
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 Field Name can be any string.
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.
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.