Skip to content

Include_Resource Command

See Also: Direct_Input, Get_Resource_Name, Register_Resource, Include_Text

Purpose

To embed the contents of a file in a compiled DataFlex program as a resource.

Note

This command is a character-mode legacy command that handles embedding of files as resources. This command does not work on embedded resources like bitmaps, icons, and version information that is compiled into a DataFlex application. See Resources for embedding these types of resources.

Syntax

include_resource
    fileName
    as
    resourceName [
        type
        resourceType
    ]

Argument Explanation

  • fileName: The name of the file (optionally including a path) to embed in the compiled program.
  • resourceName: The name to associate with the embedded file.
  • resourceType: A constant integer, or one of the predefined resource type symbols:
  • DF_RESOURCE_TYPE_BINARY
  • DF_RESOURCE_TYPE_LINE

What It Does

This command includes a file from disk for use as a resource via the sequential input device commands. The resource can be treated as a sequential file in all respects; i.e., the direct_input command is used to open a resource just like any other sequential file.

A resource ID is also defined for the resource based on the resourceName plus a suffix of .RSC: a resource named account_defaults, for example, would have a resource ID defined as account_defaults.rsc. This resource ID is a constant integer value that can be used at runtime to refer to a resource dynamically.

The direct_input and get_resource_type commands support the use of resource names directly in their syntax; any other reference to a resource must use the resource ID (or its integer value).

The type of a resource is defined during compilation and cannot be reset at runtime. Resources included with the include_resource command use a default type of DF_RESOURCE_TYPE_BINARY. This type may be overridden to be any of the predefined resource types, or any user-chosen constant integer value. (You may not use an Integer variable to specify the resource type; only constant Integer values can be assigned during compilation.) You may use the #REPLACE compiler directive to define symbolic replacements for your own resource types.

Zero and all negative integer values are reserved for the predefined resource types; you may use all positive integer values for your own resource types. (0 is reserved for DF_RESOURCE_TYPE_ERROR). The get_resource_type command is used to determine the type of a resource.

In cases where you need to refer to a resource in source code prior to the point where the resource is included, you can use the register_resource command to cause the resource name and resource ID to be defined.

string linestuff 80
include_resource letter.txt as letter type DF_RESOURCE_TYPE_LINE
direct_input "resource: letter"
readln linestuff
while [not seqeof]
    showln linestuff
    readln linestuff
end

This example includes the ASCII file letter.txt in the compiled program. The file is then referenced by its resource name, letter.

Notes

  • Include_Resource appends files at the end of the compiled program. But more importantly, they are outside of the data area or the C-equivalent data segment. This requires resources to be accessed through the I/O API, which for big files is logical.
  • Include_Resource triggers a recompile if the included file has changed.
  • fileName is not used at runtime—only at compile time.
  • Images cannot be accessed with this command.
  • Include_Text uses the data area of the compiled program, allowing the program to directly access it from memory and is similar to a constant string you have defined, so you can immediately use it as a string. However, the sum of all resources included using Include_Text cannot exceed the size of the data area, while files included using Include_Resources can be of relatively infinite size.