Overview

Structure Definitions support various #pragma directives to control the properties of structure definitions.  Like C/C++ pragma usage, the directives can be placed in different locations to control properties of elements defined after it.  Exception: the fileextensions, and displayname #pragma directives must only allow to appear once.  

Library Setting #pragma directives must be defined outside of a structure, enumeration, or function declaration.  Some exception exist.

With Library #pragma directives, users can control:

#pragma displayname("<string>")

The display name pragma defines the friendly name of the structure.  The friendly name is displayed on the structure viewer selection tool.

#pragma displayname("zip structures")

#pragma fileextensions("<string>")

The file extensions pragma defines which document extensions are appropriate for the structure definition.  Multiple file extensions can be specified by using a semicolon a delimited.  If the structure definition is loaded/open, Hex Workshop will automatically select the library whenever a compatible document is in focus.

#pragma fileextensions(".zip;.jar")

#pragma hide()

The hide pragma hides all structure definitions and enumerations defined after the #pragma until the next #pragma show() statement is reached.  Hidden structures can be referenced by other structures; however, are not shown in the Add Structure Dialog's list of available structures.  Users often hide structures that are not useful by themselves or always nested within another structure.

#pragma hide()

#pragma show()

The show pragma defeats the #pragma hide() setting and allows structures declared after it to be shown in the Add Structure Dialog.

#pragma show()

#pragma byteorder(<byte order type>)

The byte order directive controls the interpretation of document data (in either Little Endian or Big Endian byte order).  Options include little_endian, big_endian, and environment.  The Environment setting will use the byte order set on the Environment Toolbar.

#pragma byteorder(little_endian)

#pragma byteorder(big_endian)

#pragma byteorder(environment)

#pragma maxarray(n)

By default, Hex Workshop limits the length of arrays to 1024 members. This setting imposes an upper limit to bound how much processing Hex Workshop performs when evaluation structures. If a structure definition contains recursive/exponential data structures (e.g. arrays of arrays) and is applied to a corrupt file, Hex Workshop may appear to hang while processing.

#pragma maxarray(2048); // Increase the max array length to 2048

#pragma maxstring(n)

Like array lengths, Hex Workshop limits the maximum string length to avoid run-away processing of corrupt files. By default, strings are limited to 512 characters, however, users may increase the number of characters to a max of 65,536 by using the maxstring #pragma. An example is shown below:

#pragma maxstring(128); // Decrease the max string length to 128

#pragma ptrsize(<n>)

The structure viewer treats pointers to structures or data types as an absolute location to that data.  For example, adding "UWord* myValue" to a structure definition is interpreted as "the next data (value) within the document represents an absolute value to a UWord".

By default, pointers are assumed to be 32bit.  The ptrsize pragma directive can be used to change the default pointer size to 8 bit, 16bit, 32 bit, or 64 bit.

#pragma ptrsize(1) // Set pointer size to 8 bit

#pragma ptrsize(2) // Set pointer size to 16 bit

#pragma ptrsize(4) // Set pointer size to 32 bit

#pragma ptrsize(8) // Set pointer size to 64 bit

 

NOTE: #pragma ptrsize is allow supported within structure definitions.  See Structure Settings for other definitions allowed within a structure definition.

#pragma enumsize(<n>)

By default an enumerate type is assumed to be a 4 byte (32 bit) data member. To define an enumeration for an 8 bit, 16 bit, 32 bit, or 64 bit enumerated type, use the #pragma directive to indicate the size. The #pragma directive sets the enumeration data size for all enumerations defined after the directive until a new #pragma is encountered.

#pragma enumsize(1) // Enums defined after here are 1 byte (8 bits)

<<enum definitions>>

#pragma enumsize(2) // Enums defined after here are 2 bytes (16 bits)

<<enum definitions>>

#pragma enumsize(4) // Enums defined after here are 4 bytes (32 bits)

<<enum definitions>>

#pragma enumsize(8) // Enums defined after here are 8 bytes (64 bits)

<<enum definitions>>

 

NOTE: The size can be changed between enumeration definitions, but not in the middle of a definition.

#pragma enumsign("<sign>")

Structure definitions can switch the interpretation type of the enumeration elements using the enum_sign #pragma.  Options include signed and unsigned.  Enumerated types are signed by default.  

#pragma enum_sign("signed")

 

<<enum definitions>>

 

#pragma enum_sign("unsigned")

 

<<enum definitions>>

 

NOTE: The sign can be changed between enumeration definitions, but not in the middle of a definition.

#pragma pack(n)

Not yet implemented

More Information on Structure Definitions

Definition Overview, Data Types, Enumerated Types, Arrays, Strings, Bitfields, Expressions, Conditionals, Functions, Verification, Library Settings, Structure Settings, and Reserved Words and Symbols.