HANDLEIN

You can use the HANDLEIN function when deriving large amounts of data from a parent map for use in a RUN map. The HANDLEIN function works by using the same instance of the parent map's data set in the RUN map, instead of duplicating it as the ECHOIN function does.

The result of the HANDLEIN function is a text object that defines the characteristics of the data to be used. This includes an internal handle, offset, and length of the data. The result of this can be seen in an execution audit log:

<ExecutionSummary MapStatus="Valid" mapreturn="0" ElapsedSec="0.1803"
BurstRestartCount="0">
   <Message>Map completed successfully</Message>
   <CommandLine>install_dir\sdq20.mmc -IH1 4:512:1024 -ae</CommandLine>
   <ObjectsFound>85</ObjectsFound>
   <ObjectsBuilt>23</ObjectsBuilt>
<SourceReport   card="1"   adapter="Handle"   bytes="1024"   adapterreturn="0">
   <Message>Success</Message>
   <Settings>4:512:1024</Settings>
   <TimeStamp>05:06:07 January 27, 2004</TimeStamp>
</SourceReport>

When the HANDLEIN function returns a character text item, the string is prefixed with: IHx, where x is the first parameter.

String format:

-IHx <internal-handle>.<offset>.<length>

Example:

-IH1 4.4096.512

A single-integer-expression is the number item that specifies the card number to override. A single-text-expression specifies the data object to use for the override.

In a RUN map rule, you can override a source card with a handle of a current map's card by specifying the card to override and the object to override it with.

Examples

In the following rule, the data is object c:b:a for input card 2 of the RUN map:

HANDLEIN(2, c:b:a)

The second parameter can be more complex if needed. For example,

HANDLEIN(2, SUBSTITUE(c:b:a, "a", "A"))

Any data in object c:b:a that contains a lowercase "a" would change it to an uppercase "A" for the call to the RUN map. In cases such as this, where the data cannot be expressed contiguously within the original card or cards, a scratch file is used to hold the expression and the calling map's handle is that of the scratch file.

There is no correlation between the handle returned in the output of HANDLEIN and the actual card number of the second parameter.

Related functions

Generally, the ECHOIN function is used to return a command or property to be used in a RUN function argument. However, for large amounts of data, using the HANDLEIN function can be more efficient.

For best results, use the ECHOIN function for small quantities of data, such as less than 100K, and the HANDLEIN function for larger quantities of data of more than 100K.