• if a or b is a single value then this value is used for every element.
• if is useful as a quick way of choosing one of two values:

  if(time>"12:00:00","p.m.","a.m.")

• if is useful for applying a floor or a ceiling to a dataset:

  x = if(x<0,0,x);     # same as x = max2(x,0);

  or for undefining values:

  x = if(x=-1,undef, x);

• Always try and use an if statement rather than a for loop. It is much quicker. e.g.:

  longs = if(longs<-180,longs+360,longs);

  rather than

  for i=1 to size(longs)
    if longs[i]<-180 then
      longs[i] = longs[i]+360;
    endif
  endfor

• N.B. x = (a>b); is better than x = if(a>b,true,false);

A normal if programming control also exists. e,g

if exists(page_1.viewport1) then
  v1 = page_1.viewport_1.XuNfirstDiagonalPoint;
else
  v1 = (undef,undef);
endif

N.B. You wouldn't be able to use the if function to do the same thing:

v1 = if(exists(page_1.viewport1),
        page_1.viewport_1.XuNfirstDiagonalPoint,
        (undef,undef) );

as Gsharp will try and evaluate both the true and false arguments to the if function and will have a run-time error on the true argument if page_1.viewport_1 does not exist. With the if control Gsharp only evaluates the true block if the condition is true.

mask

• You must specify either the number of datasets or the names of the datasets in the argument datasetNames, e.g. "6" or "x1 x2 x3 y1 y2 y3"
• You must specify whether the dataType is "real" (default) or "text".
• If you are reading a single dataset then you can use the numRows, numColumns and numPlanes to inform Gsharp of the dimension of the data. N.B. The layout argument has no affect on how single datasets are read.
• If you are reading multiple datasets then the layout argument specifies whether the datasets are arranged in columns - "vertical" or in rows - "horizontal" (default).
• You can also tell the reader only to look for data within a certain window in the file using the argumnets startLine, endLine, startColumn and endColumn. N.B. In this context a column is a character column not a column of data.
• You can also use a conversionFilter as described in import_report

N.B. The ASCII reader completely ignores line feeds. It works through the file looking for numbers wherever they are and then stores the values it finds into datasets as instructed by you.

There is no reason why you can't making multiple calls to import_ascii to read data from the same file.

function ReadFile(string filename);
  float lp, numLines, i;
  #Read first two lines into a string dataset called header
  import_ascii(filename,1,2,,,,"header","text");

  #Read important variables from line 3
  import_ascii(filename,3,3,,,,"numLong numLat numVar");
  lp = 4;

  #Read Longitudes - ten values per line
  numLines = div(numLong+9,10);
  import_ascii(filename,lp,lp+numLines-1,,,,"Longitudes");
  lp = lp+numLines;

  #Read Latitudes - ten values per line
  numLines = div(numLat+9,10);
  import_ascii(filename,lp,lp+numLines-1,,,,"Latitudes");
  lp = lp+numLines;

  #Read Variables
  numLines = div(numLat*numLong+9,10);
  for i=1 to numVar
    import_ascii(filename,lp,lp,,,,"VARNAME","text");
    import_ascii(filename,lp+1,lp+numLines,,,,VARNAME);
    $VARNAME = reshape($VARNAME,numLong, numLat, 1);
    destroy VARNAME;
    lp = lp+numLines+1;
  endfor
endfunction

reset all;
ReadFile("test.dat");

create Viewport page_1.viewport_1;
create Domain page_1.viewport_1.domain_1
   ( XuNgraphClearance = false
   );
page_1.viewport_1.domain_1.xaxis1.XuNtickmarksMajorStepValue = 30;
page_1.viewport_1.domain_1.yaxis1.XuNtickmarksMajorStepValue = 30;
create Graph page_1.viewport_1.domain_1.graph_1
   ( XuNcolorDataGrid = "Pressure",
     XuNgraphType = "2DContour",
     XuNxData = "Longitudes",
     XuNyData = "Latitudes"
   );

Syntax:

include "$UNIDIR/lib/libio.gsl";

import_ascii_folder(string filename, string folder)

Description:

The specified filename is read into folder.

The file must have been created by export_ascii_folder. The folder can be written out on one platform with export_ascii_folder and then read in on another platform using improt_ascii_folder.

• If folder equals "" then the current folder is used.

• This function is implemented in GSL. Either include the library libio.gsl (as shown) in your code or copy the function from your library.

• It is suggested that you use the extension ".afl" for ASCII Folders.

• If you are not concerned about creating platform independent files, then export_ascii and import_ascii are quicker and produce smaller files.

Example:

import_ascii_folder("WORK.afl", "WORK2");

See also:

import_folder, export_ascii_folder

• fileType can be either "c_byte", "c_float", "c_int", "c_short", "f77_int" or "c_real".
• wordsPerRecord should be 512
• The dimension of datasetName can be controlled using numRows, numColumns and numPlanes.

• CSV files can be exported from Microsoft Excel.
• headerRows is the number of rows to be used as headers
• headerCols is the number of columns to be used as headers
• layout is used to specify the layout of the data:
  

  0	Columns
  1	Rows
  2	Grid

• datatype is used to specify the format of the data:
  

  0	Float or String
  1	Float
  2	String

  "Float or String" means Gsharp will create a float dataset if every cell contains a number, otherwise it will create a string dataset.
  "Float" will produce an error if a cell contains a non-number

• undefVal specifies the number that denotes the undef value.
• Datasets are created using the names T1, T2, ... for float datasets and A1, A2, ... for string datasets. If T1 exists, Gsharp will use T2, if T2 exists then T3, etc.

• Only available on Windows.
• sheetName is name of sheet to read.
• layout is one of:
  

  0	Columns (default)
  1	Rows
  2	Grid

• dataStart is the upper-left corner of the data and dataEnd is the bottom-right corner of the data. If these values are omitted the whole sheet is used.
• headerStart and headerEnd specify the location of the text header. If not specified Gsharp will take any text that precedes the data.
• Any cells with the value undefVal will be read as UNDEF. The default value is 999.999

See AVS 5 Documentation for further details.

• If folderName is not set, the folder is read into the current folder.
• If folderName does not exist, it is created.
• If the folder does exists then the datasets from filename are merged in. Any datasets with the same name as one in filename are replaced.
• Folder files are binary files and are not portable between some operating systems.

• The names in the netCDF file will be used as dataset names.
• If readCoordinateInfo is true then a co-ordinate dataset is created for each dataset in the file. The co-ordinate dataset has the same name as the dataset appended with "_coords". The co-ordinate dataset is a string array with the n'th element containing the name of the dataset containing the co-ordinates of the n'th dimension of the dataset. e.g. If grid is a 2 dimensional dataset located on a grid whose x-cordinates are contained in longs and y-cordinates are contains in lats, then grid will be read into a float dataset and grid_coords will contain "longs" // "lats".

import_netcdf("bob.cdf", true);

• Once columns of data have been found, the reader will look for column headers to use as dataset names.
• Columns are only delimited by spaces (" "). If other characters are used they should be converted to spaces using the conversion filter.
• A conversionFilter can be applied before reading. See below for details.
• If titleDataset is specified then any lines which the report reader decides are not part of the columns of data are stored in the specified dataset.

The report reader uses the following logic for reading reports:

1. The conversionFilter is applied to each line as it is read
2. All characters with ASCII value less than 32 are replaced by blanks.
3. The format of the line is calculated - numbers must be separated by at least one blank, strings by two blanks.
   For example "Yellow 2.3 Green Blue 4.0 4.0" has a format of "string float string float float". A valid format must include at least one float column.
   Once the reader finds three consecutive lines with the same number of columns this is used as the format for the file and the reader will include all the following lines which have the specified number of columns.
4. The reader then works backwards from the first line accepted looking for dataset names. So, if five columns of data have been read, it looks for a line with format "string string string string string". N.B. Each string must be separated by at least two spaces. If the reader finds a line with an equal number of strings as columns of data, then the names are used for dataset names. If a title string is not a valid dataset name, Gsharp creates a dataset name. If it can't find a line containing dataset names it creates all the dataset names. Float datasets are called "T1", "T2" and so on. String datasets are called A1, A2 and so on. See the example for a way of retrieving the names of the datasets used.
5. Any lines which do not consist of the correct number of columns are stored in the titlesDataset if specified.

function string MyImportReport(string filename)
  string datasets;
  float n;
  
  datasets = namelist();
  n = size(datasets);
  import_report(filename);
  return dropx(namelist(), 1:n);
endfunction

• countryCodes is an array of countries to be read. If a code is preceded by "-" it is excluded. e.g. South America without Brazil would be "SAM"//"-BRA".
  "" can be used to specify the whole world.
• A list of country codes can be created using:
  echo(getcode()+" - "+getcountry());
• import_worldmap returns complete polygons which can be used for region or barrier data as well as for overlaying as line graphs.
• resolution can be either "full", "reduced_1", "reduced_2", "reduced_3" (default) or "reduced_4"
• longitude is the name of the dataset to store the retrieved longitudes The default name is Long. If the dataset exists, it is overwritten.
• latitude is the name of the dataset to store the retrieved latitudes. The default name is Lat. If the dataset exists, it is overwritten.
• import_worldmap returns the number of co-ordinates read.
• The retrieved co-ordinates can be cropped using minLongitude, maxLongitude and/or minLatitude and maxLatitude. Gsharp will make sure that any cropped data still forms complete polygons.

import_worldmap("GBR","full");
grid = bilinear(rnd(9),rnd(9),rnd(9));
gridx = range(Long,33);
gridy = range(Lat,33);

create Viewport page_1.viewport_1
 ( XuNxRatio = 1,
   XuNyRatio = 1.2
 );
create Domain page_1.viewport_1.domain_1;
create Graph page_1.viewport_1.domain_1.graph_1
 ( XuNcolorDataGrid = "grid",
   XuNgraphType = "2DContour",
   XuNregionBorderCells = "contoured",
   XuNregionXData = "Long",
   XuNregionYData = "Lat",
   XuNxData = "gridx",
   XuNyData = "gridy"
 );

reset;
import_worldmap("");
x1 = -90; x2 = 90; y1 = -45; y2 = 45;  xdiff=5;  ydiff=5;
create Viewport page_1.viewport_1;
create Domain page_1.viewport_1.domain_1
 ( XuNxMinimum = -180,
   XuNxMaximum = 180,
   XuNyMinimum = -90,
   XuNyMaximum = 90
 );
page_1.viewport_1.domain_1.xaxis1.XuNtickmarksMajorStepValue = 30;
page_1.viewport_1.domain_1.yaxis1.XuNtickmarksMajorStepValue = 30;
create Graph page_1.viewport_1.domain_1.graph_1
   ( XuNgraphType = "line",
     XuNxData = "Long",
     XuNyData = "Lat"
   );
create Graph page_1.viewport_1.domain_1.box
   ( XuNgraphType = "line",
     XuNxData = "x1//x2//x2//x1//x1",
     XuNyData = "y1//y1//y2//y2//y1"
   );
repaint;
for i=1 to 100
  x1 = x1+xdiff*(1+rnd(1));  x2 = x2+xdiff*(1+rnd(1));
  if x2>180  xdiff=-5;
  if x1<-180 xdiff=5;
  y1 = y1+ydiff*(1+rnd(1)); y2 = y2+ydiff*(1+rnd(1));
  if y2>90  ydiff=-5;
  if y1<-90 ydiff=5;
  import_worldmap("",,,,x1,x2,y1,y2);
  repaint;
endfor

Syntax:

include filename

Description:

include the specified filename in the current script.

• The User Guide page on function parameters includes a description of how GSL scripts are compiled first then executed.

Code sample:

include "$UNIDIR/lib/libgui.gsl";

x = GuiGetFloats("gsharp_1.mydialog.bulletin.field"+(1:10));

See also:

eval, exec

Prompt the user with a choice

• choices is a string array with each element containing a choice. It can contain a maximum of five chocies.
• default is the string of the default choice.

choice = input_choice("Are you sure?", "Yes" // "No", "No");
choice = input_choice("Specify position", "Top"//"Bottom"//"Cancel");

• requiredType is used to specify what type of dataset is selectable.
  

  1	float
  2	string
  4	date
  8	time

  values can be or'd to allow multiple values. e.g. 11 = 8 + 2 + 1 = time, string or float

  This parameter is optional. If it is not specified all dataset types are displayed.

• requiredDimension is used to specify what dimension of dataset is selectable.
  

  1	0D or 1D
  2	2D
  4	3D

  values can be or'd to allow multiple values. e.g. 2 = 2 + 1 = 0D, 1D or 2D.

  This parameter is optional. If it is not specified all dimensions are displayed.

• The prompt argument is used as the title of the file selection dialog
• The mode argument is used to specify whether or not the selected file can be read from or written to. 

  r	readable
  w	writeable
  a	writeable
  +	readable or writeable

  If mode is not specified then no check is made

• The match argument is true, then it is only possible for files that already exist to be selected. If it is false (or match is not specified) then there is no restriction and users can type in a new filename on the selection line.

• The pattern argument is used to filter the files that are listed. e.g. "*.txt", "*.gs?". By default all files are listed. Users can still type in the name of a file that does not match the pattern.

• The dir argument is used to set the initial directory of the file selection dialog. e.g. "C:\\My Documents\\"

• The title of the dialog is "Enter a number". The prompt argument is displayed above the input field.
• The valid range for the number can be specified with min and/or max.
• If the echo argument is false then the numbers entered cannot be seen on the screen - they are replaced with asterisks.
• If the user presses Cancel - input_float returns undef.
• It default is not set then the default value is 0.

• The main heading of the dialog is specifed by the prompt argument
• The list of strings should be specified in the items argument
• If match is false (or not specified), then the selected string does not need to be one of the strings in items - the user can type a new string in the selection field
• If multi is true then the user can select one or more strings from the list. All selected strings are returned as an array. If no string is selected - then an empty string is returned.
• If the user clicks on cancel, then UNDEF is returned.

• The title of the dialog is "Enter a text". The prompt argument is displayed above the input field
• The valid range for each character can be specified with the minimum and/or the maximum arguments. The ASCII value of the character is used to decide the order. e.g. use "a" to "z" to force all lower case letters, ""A" to "z", for lower case or upper case letters and "0" to "z" to numbers or letters.
• If the echo argument is false then the characters entered cannot be seen on the screen - they are replaced with asterisks.

name = input_string("Enter your name");
password = input_string("Enter password in lower case", "a", "z", false);

integral[n] = (-y[n-2] + 13*y[n-1] + 13*y[n+1] - y[n+2]) / 24

• The first two and last two points have their own special treatment
• The approximation is exact for third degree polynomials
• It is assumed that y values are 1 unit in x apart. If they are not use the expression: accum(diff(integrate(y))*diff(x))

• date is equivalent to invdaysince(daysince(date))

• time is equivalent to invsecsince(secsince(time))