Creating a File Parameter

The following describes how you create a file parameter and add it to the DtComponent:

DtScalarVariable fileVar = 
DtModelManager.createScalarVariable("myfile",
        "com.engineous.datatype.File", 
        Variable.ROLE_PARAMETER,
        Variable.MODE_INPUT, null, null);
myComponent.addParameter(fileVar);

There are convenient constants for all MetaModel names shown as literal strings below in class com.engineous.sdk.vars.EsiTypes. For example, EsiTypes.FILE is “com.engineous.datatype.File.”

Once a file parameter is created, it must be configured to point to the proper file. The first step is to get the Value object:

FileValueType fileValue = (FileValueType)fileVar.getValueObj();

The next step is to set the toOption. The valid values are different for MODE_INPUT and MODE_OUTPUT:

fileValue.setToOption(FileValueType.INPUT_OPTION_AUTO);

Next you set the handler type (except for OUTPUT_OPTION_AUTO or OUTPUT_OPTION_FILEMGR). The handler type is specified as a MetaModel name:

fileValue.setHandlerType("com.engineous.plugin.DataHandlerFile"
);

The location of the data pointed to by the handler needs to be set:

DataHandler handler = fileValue.getDataHandler();
handler.setResourceName("C:\\foo\\bar.txt");

The meaning of the string passed to setResourceName is different for each handler type. For DataHandlerFile it is the path the file will have at run time. This path may contain parameter or other substitutions, such as: {root myRoot}/mesh-{var run #}.txt. For more information on available substitutions, see Setting Files and Directories Preferences in the Isight User’s Guide. For DataHandlerInline it is the path to an existing file. The file is immediately copied into the model—subsequent changes to the file on disk will not affect the contents stored in the model unless setResourceName is called again. For DataHandlerURL you pass the URL here. The URL may contain substitutions similar to file names.

You can skip configuring the Handler for an INPUT file parameter if you know that the parameter will be mapped from another component and you never intend to run this component by itself. A handler is never configured for OUTPUT_OPTION_AUTO or OUTPUT_OPTION_FILEMGR.

The last step is to set the Local Name, if required:

fileValue.setLocalFileName("foo.txt");

Parameter and other substitutions can be included in the Local file name, though this technique is used much less often than for the Resource name of a File Handler. It is not necessary to start the local name with {rundir}/—any simple file name (with no slashes) or relative file path (without a leading slash or drive letter) will automatically be resolved relative to the Working directory. Absolute paths are sometimes used for the Local Name, especially for OUTPUT_OPTION_AUTO. In such a case, you will almost certainly need to substitute {workid} or a parameter value into the file name so that different runs of the component do not overwrite each other’s files.

The method setRawFileName(String) does exactly the same thing as setLocalFileName at design time. It may be more intuitive to think of setting the Raw file name, especially if the name contains parameter substitutions.