Attachments

Attachment Directories

When an app is run in Insight, attachments allow you to store files directly in the scenario or application. In mminsight test mode, we simulate this using directories. Set the parameter insight_test_attach_dir to be the path of a directory; the files in a subdirectory called scenattach will be the attachments of the current scenario, while the content of a subdirectory appattach will be the application attachments. If either subdirectory doesn't exist, it will be created automatically the first time you try to access that attachment type. Alternatively, the developer can specify specific directories for app and scenario attachments using the procedures insightsettestappattachdir and insightsettestscenattachdir.

The initial content of either directory will be treated as the initial scenario and appplication attachments, and any attachment changes made by calling mminsight attachment procedures will be reflected immediately in the target directory. For example:

setparam('insight_test_attach_dir','/home/user/mytests/mytestattach')
...
! Access an attachment (read from file /home/user/mytests/mytestattach/scenattach/inputdata.dat)
insightgetscenattach('inputdata.dat')
if insightattachstatus<>INSIGHT_ATTACH_OK then
 writeln("Error accessing attachment")
end-if
...
! Create an attachment (written to file /home/user/mytests/mytestattach/scenattach/hello.txt)
insightputscenattach('hello.txt')
if insightattachstatus<>INSIGHT_ATTACH_OK then
 writeln("Error creating attachment")
end-if

Attachment meta-data (e.g. description, last-modified date, etc) can be written to an optional .properties file in the same directory. This file contains an insightattachment record called attach written using initializations to, for example:

declarations
  attach: insightattachment
end-declarations
attach.filename := "myattachment.dat"
attach.description := "this is the description of my attachment"
attach.tags := ['first','test']
attach.lastModifiedUser := 'Winston Churchill'
initializations to '/home/user/mytests/mytestattach/scenattach/myattachment.dat.properties'
  attach
end-initializations

If the .properties file for an attachment is missing, it will be created automatically the first time mminsight looks in that attachment directory. If the filename field specifies a different name from the actual filename, the name from the .properties file will be reported as the attachment filename by all mminsight attachment functions.

Attachment Tags

There are two ways to set the list of attachment tags that will be available. The first is to pass a list of insightattachmenttag records to insightsetattachtags, e.g.:

declarations
  test,first: insightattachment
end-declarations
first.name := 'first'
first.usage = 'single-file'
test.name := 'test'
test.usage := 'multi-file'
insightsetattachtags([first,test])

Alternatively, the tag definitions can be read directly from the application's companion file. To do this, set the parameter insight_test_cfile_path to be the path to the model companion file. mminsight in test mode will automatically try to read the tags from insight_test_cfile_path so long as this is set before the first mminsight procedure call that requires tags.

Attachment Validation

By default, Insight will perform some basic validation on new attachments and attachment meta-data: attachments must be no more than a given size, their filenames and descriptions have a maximum length, certain characters are not allowed in attachment filenames, and there is a limit to how many files can be attached to a single scenario. If you wish to set different rules during your test - for example, to check how your code handles Insight failing to add an attachment - then this can be done by calling insightsetattachrules, e.g.:

declarations
  rules: insightattachmentrules
end-declarations
rules.maxsize := 1*1024*1024
rules.maxattachcount := 3
rules.maxfilenamelen := 32
rules.invalidfilenamechars := [text('/'),text('\\'),text(' ')]
rules.maxdescriptionlen := 128
insightsetattachrules(rules)