Working with Tagged files – Ascii Navigator

Parameterizing Tagged files with the iChrome’s Ascii Navigator has never been easier


For those who are not familiar yet with Nexus (our design process integration and optimization solution), the so-called AsciiNavigator is a JavaScript scripting interface formerly made available within Nexus to allow users to link external application where input and outputs are ASCII files.
From its origins the AsciiNavigator evolved and from Nexus v.3 become a stand-alone and independent application designed to help users automating tasks requiring to operate with AsciiFile.
Additionally, the AsciiNavigator embed advanced features (through easy to use Wizard) to load and manipulate results from third-party CAE solvers such as Abaqus, Ansys, Nastran, Comsol, Amesim and many more. An example on how the AsciiNavigator can be used to extract Nastran results can be found in this post: Batch Processing of Nastran OP2 Files.

This post will show a new feature introduced with Nexus v.3 and made available within the AsciiNavigator, i.e. the writeTemplate(..) function.


  1. the writeTemplate(…) function
  2. a first (simple) example
  3. a second (less simple) example
  4. conclusive remarks

The writeTemplate(…) function:

This function provides an alternative to the parameterization previously offered by the AsciiNavigator and based on file position offsetting. The writeTemplate method operates by reading a user-defined template files containing specific TAGs. The method copies the template file on a new destination file while replacing tags in the template with current values of variables.
Tags in the template file shall have the following format:

‹‹‹ variable : format : length ›››


  • variable is the name of the variable to be written within the tag;
  • format denotes the format to be used to write the value. Standard C formatting will be used (more detailed information on supported formats can be found here:;
  • length is an additional and optional parameter to be used to assure the string written on file matches the user defined length.

Two variants of the function exist:

  • writeTemplate(template,destination): this is typically used when the AsciiNavigator is used embedded within Nexus or another iChrome’s product. In this cases, the set of variables visible within the template function are pre-defined to match the input variables of the framework from where the AsciiNavigator is called from.
  • writeTemplate(template,destination,variables) this second variant allows to add user-specific variables to the ones possibly pre-defiend by the framework. Variables shall be defined via an associative array.

When defining tags in the template file, please consider the followings:

  • tag definition shall start with the character sequence ‹‹‹
  • tag definition shall be written on a single line and shall not contain comments;
  • tag definition shall end, within the same line it started, with the character sequence ›››

>> Back To Top

A first (simple) example

In this example we will see how a template file can be defined and then filled on with the AsciiNavigator. The template file describes a layered shell for a composite material in the Abaqus format. Note the example can be easily generalized. Basically in each line there is a value representing the orientation of the composite ply and we wish to parameterize those.

Original File (before tagging):

0.000310,3,a,  45.0
0.000310,3,a, -45.0                  
0.000310,3,a,  90.0
0.000310,3,a,   0.0
0.000310,3,a,   0.0
0.000310,3,a,  90.0    
0.000310,3,a, -45.0    
0.000310,3,a,  45.0

Tagged File:

0.000310,3,a, <<<X1:%f>>>
0.000310,3,a, <<<X2:%f>>>
0.000310,3,a, <<<X3:%f>>>
0.000310,3,a, <<<X4:%f>>>
0.000310,3,a, <<<X5:%f>>>
0.000310,3,a, <<<X6:%f>>>
0.000310,3,a, <<<X7:%f>>>    
0.000310,3,a, <<<X8:%f>>>

In this specific case therefore the tagging process introduced in the template file 8 variables: X1, X2, X3, X4, X5, X6, X7 X8. Variables (if defined) will be written on file using a compact %f (i.e. flat number) format. The AsciiNavigator script is reported below on the left. Resulting output file on the right.

/* Define an array to map variables by 
 * name. Note that variable names are 
 * case sensitive.
var variables = [];
variables["X1"] = 0.0;
variables["X2"] = 45.;
variables["X3"] = 10;
variables["X4"] = "wrong datum";
variables["X5"] = 70.234;
variables["X6"] = -1000;
variables["X7"] = 10;
variables["X8"] = 0.0;

/* call 'writeTemplate(...) with the 
 * array of parameters on file 'model.inp'
 * and save resulting file as 'model.out'
if( !writeTemplate(
   echo("one or more error!!");

0.000310,3,a, 0.000000
0.000310,3,a, 45.000000
0.000310,3,a, 10.000000
0.000310,3,a, wrong datum
0.000310,3,a, 70.234000
0.000310,3,a, -1000.000000
0.000310,3,a, 10.000000
0.000310,3,a, 0.000000

It is worth noticing that:

  • if a tag referring to an unknown or not defined variable is encountered when writing the output file, the AsciiNavigator will notify an error, leave the tag unchanged and attempt to carry on parsing the remaining part of the file up to its end is reached
  • if format is not compatible with the value of the variable it refers to, the AsciiNavigator will attempt to write the variable using a default formatting, typically a string

>> Back To Top

A second (less simple) example

In this second example, we will build a mailing list and then we will use the AsciiNavigator along with the iChrome Notifier (as part of Nexus) to send personalized email to the receivers in the list.
Let’s start looking at the email tagged template:

  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <body leftmargin="0" marginwidth="0" 
  topmargin="0" marginheight="0" offset="0" 
  <!-- MAIN CONTENTS -->
   <table border="0" cellpadding="0" cellspacing="10" 
    width="800" style="background-color: #FFFFFF;">
     <td colspan="2" align="left" valign="top" width="100%">
      <div style="margin:0;color:#0066cc;font-family:Arial;font-size:18px;">
        Dear <<<USER:%s>>>,
        <br>get Your Results noticed with Grapheme
        <br>Advanced Data Mining and Visualization Tool.

The email template contains two tags, variable TITLE at line 4 with the email title and variable USER at line 22 with the addressee name. Corresponding AsciiNavigator script is reported below:

/* This is a list of users and email address to 
 * which we would like to send an email to thank
 * them for using the AsciiNavigator.
var users = [];
users.push( ["Superman",        ""] );
users.push( ["Ironman",         ""] );
users.push( ["Batman",          ""] );
users.push( ["Spiderman",       ""] );
users.push( ["Captain America", ""] );

/* call 'writeTemplate(...) for each name in 
 * the list
for( var i in users) {
	var variable = [];
	variable["USER"]  = users[i][0];
	variable["TITLE"] = "For " + users[i][0] + "- Big Data Analysis with Grapheme"

	// write template
    if( !writeTemplate("email.html.tmpl", "email.html", variable) )
    // send email (using the iChrome's Notifier)
    var command = "nxNotifier email when=now file=email.html to=";
    command += users[i][1];
    system( command );
    echo("email sent to "+users[i][1]+" via nxNotifier");

When executed, the script will iterate the list of users provided at the beginning (an enhanced version of the script may read the list from an external source) and then iterate each entry of the list preparing a customized TITLE and USER entry for the writeTemplate(…) function.
The writeTemplate(…) function will write on disk a new HTML email (named email.html) that will be send via email to the receiver using the nxNotifier or an equivalent mailing system.
>> Back To Top

Conclusive Remarks

This post present an alternative way to the more traditional file positioning one when using the iChrome’s AsciiNavigator to work and parameterize ASCII files.

  • Positioning mode: this is the default mode. When using the AsciiNavigator in this way, the user moves the file positioning directly on a opened file with commands like offset(…), moveTo(…), findLine(…). Once the file pointer is moved, user can overwriting char sequences in the original file using function like setField(…) or write(…). This working way turns out to be useful when editing files of large dimension and where the portion of file to be modified do not alter the overall length of the file ifself, i.e. when the data to be replaced are as long as the original ones, assuring these are not written overwriting larger portion of data on the original file. In fact, the AsciiNavigator is not able to create and inflate new spaces to fill field with character sequence longer than the original ones
  • Tagging mode: the tagging mode operates reading a so called tagged template file and making a copy of this by replacing the user defined tags with user provided values. This working way allow sequentially reading the file and creating a copy. This process allow the AsciiNavigator to inflate spaces on the destination file, thus allowing to write arbitrary long and variable length files.

When should we use the TEMPLATE TAGGED mode then?
Despite a general rule may be difficult to find, the Template-Tagged approach can be useful when:

  • an immutable template can be defined as starting point – note this is not always possible in industrial application as the file to be manipulated by the AsciiNavigator may be dynamically created by at third application and contents may change across consecutive iterations
  • the parameterization process is straight, i.e. all the TAGS defined in the template will always be processed. In other words, it’s not possible to exploit conditional execution path such as IF ELSE in the parent AsciiNavigator Script to select which tags should be processed in a template and which ignored. In fact, when calling writeTemplate(…) all tags are processed and replaced. Clearly you can exploit the AsciiNavigator script to change the variable values corresponding to a given TAG, but all TAGS should have a defined value

>> Back To Top